Skip to content

GitLab

Commit b110f61a authored by danh-arm's avatar danh-arm
Browse files

Merge pull request #203 from danh-arm/dh/misc-docs-1.0 

Miscellaneous documentation fixes
parents ae5bb9db 44804252
Show whitespace changes
Inline Side-by-side
bl1/aarch64/bl1_exceptions.S
View file @ b110f61a
......@@ -44,7 +44,7 @@
.align 7
bl1_exceptions:
/* -----------------------------------------------------
* Current EL with SP0 : 0x0 - 0x180
* Current EL with SP0 : 0x0 - 0x200
* -----------------------------------------------------
*/
SynchronousExceptionSP0:
......@@ -75,7 +75,7 @@ SErrorSP0:
check_vector_size SErrorSP0
/* -----------------------------------------------------
* Current EL with SPx: 0x200 - 0x380
* Current EL with SPx: 0x200 - 0x400
* -----------------------------------------------------
*/
.align 7
......@@ -107,7 +107,7 @@ SErrorSPx:
check_vector_size SErrorSPx
/* -----------------------------------------------------
* Lower EL using AArch64 : 0x400 - 0x580
* Lower EL using AArch64 : 0x400 - 0x600
* -----------------------------------------------------
*/
.align 7
......@@ -184,7 +184,7 @@ SErrorA64:
check_vector_size SErrorA64
/* -----------------------------------------------------
* Lower EL using AArch32 : 0x0 - 0x180
* Lower EL using AArch32 : 0x600 - 0x800
* -----------------------------------------------------
*/
.align 7
......
bl31/aarch64/bl31_entrypoint.S
View file @ b110f61a
......@@ -198,7 +198,3 @@ func bl31_entrypoint
bl bl31_main
b el3_exit
_panic:
wfi
b _panic
bl31/aarch64/context.S
View file @ b110f61a
......@@ -207,7 +207,7 @@ func el1_sysregs_context_restore
ret
/* -----------------------------------------------------
* The followsing function follows the aapcs_64 strictly
* The following function follows the aapcs_64 strictly
* to use x9-x17 (temporary caller-saved registers
* according to AArch64 PCS) to save floating point
* register context. It assumes that 'x0' is pointing to
......
bl31/aarch64/runtime_exceptions.S
View file @ b110f61a
......@@ -39,7 +39,7 @@
.globl el3_exit
/* -----------------------------------------------------
* Handle SMC exceptions seperately from other sync.
* Handle SMC exceptions separately from other sync.
* exceptions.
* -----------------------------------------------------
*/
......@@ -167,7 +167,7 @@ interrupt_error_\label:
.align 7
runtime_exceptions:
/* -----------------------------------------------------
* Current EL with _sp_el0 : 0x0 - 0x180
* Current EL with _sp_el0 : 0x0 - 0x200
* -----------------------------------------------------
*/
sync_exception_sp_el0:
......@@ -199,7 +199,7 @@ serror_sp_el0:
check_vector_size serror_sp_el0
/* -----------------------------------------------------
* Current EL with SPx: 0x200 - 0x380
* Current EL with SPx: 0x200 - 0x400
* -----------------------------------------------------
*/
.align 7
......@@ -230,7 +230,7 @@ serror_sp_elx:
check_vector_size serror_sp_elx
/* -----------------------------------------------------
* Lower EL using AArch64 : 0x400 - 0x580
* Lower EL using AArch64 : 0x400 - 0x600
* -----------------------------------------------------
*/
.align 7
......@@ -267,7 +267,7 @@ serror_aarch64:
check_vector_size serror_aarch64
/* -----------------------------------------------------
* Lower EL using AArch32 : 0x600 - 0x780
* Lower EL using AArch32 : 0x600 - 0x800
* -----------------------------------------------------
*/
.align 7
......
docs/cpu-errata-workarounds.md
View file @ b110f61a
ARM CPU Errata Workarounds
==========================
ARM Trusted Firmware exports a series of build flags which controls the
ARM Trusted Firmware exports a series of build flags which control the
errata workarounds that are applied to each CPU by the reset handler. The
errata details can be found in the CPU specifc errata documents published
by ARM. The errata workarounds are implemented for a particular revision
......@@ -19,7 +19,7 @@ In the current implementation, a platform which has more than 1 variant
with different revisions of a processor has no runtime mechanism available
for it to specify which errata workarounds should be enabled or not.
The value of the build flags are 0 by default, that is disabled. Any other
The value of the build flags are 0 by default, that is, disabled. Any other
value will enable it.
For Cortex A57, following errata build flags are defined :
......
docs/firmware-design.md
View file @ b110f61a
......@@ -1195,24 +1195,24 @@ sections must not overstep. The platform code must provide those.
The following list describes the memory layout on the FVP:
* A 4KB page of shared memory is used to store the entrypoint mailboxes
* A 4KB page of shared memory is used to store the entrypoint mailboxes
and the parameters passed between bootloaders. The shared memory can be
allocated either at the top of Trusted SRAM or at the base of Trusted
DRAM at build time. When allocated in Trusted SRAM, the amount of Trusted
SRAM available to load the bootloader images will be reduced by the size
of the shared memory.
* BL1 is originally sitting in the Trusted ROM at address `0x0`. Its
* BL1 is originally sitting in the Trusted ROM at address `0x0`. Its
read-write data are relocated at the top of the Trusted SRAM at runtime.
If the shared memory is allocated in Trusted SRAM, the BL1 read-write data
is relocated just below the shared memory.
* BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
* BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
sections will overwrite BL1 R/W data.
* BL2 is loaded below BL3-1.
* BL2 is loaded below BL3-1.
* The TSP is loaded as the BL3-2 image at the base of either the Trusted
* The TSP is loaded as the BL3-2 image at the base of either the Trusted
SRAM or Trusted DRAM. When loaded into Trusted SRAM, its NOBITS sections
are allowed to overlay BL2. When loaded into Trusted DRAM, an offset
corresponding to the size of the shared memory is applied to avoid
......@@ -1223,7 +1223,7 @@ possible when it is loaded into Trusted SRAM. Depending on the location of the
shared memory page and the TSP, it will result in different memory maps,
illustrated by the following diagrams.
** Shared data & TSP in Trusted SRAM (default option): **
**Shared data & TSP in Trusted SRAM (default option):**
Trusted SRAM
0x04040000 +----------+
......@@ -1244,7 +1244,7 @@ illustrated by the following diagrams.
0x00000000 +----------+
** Shared data & TSP in Trusted DRAM: **
**Shared data & TSP in Trusted DRAM:**
Trusted DRAM
0x08000000 +----------+
......@@ -1271,7 +1271,7 @@ illustrated by the following diagrams.
| BL1 (ro) |
0x00000000 +----------+
** Shared data in Trusted DRAM, TSP in Trusted SRAM: **
**Shared data in Trusted DRAM, TSP in Trusted SRAM:**
Trusted DRAM
0x08000000 +----------+
......
docs/interrupt-framework-design.md
View file @ b110f61a
......@@ -151,9 +151,9 @@ terminology used in the following sub-sections is explained below.
is not visible to the secure software which violates the motivation behind
the ARM Security Extensions.
4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in secure
state. This is a valid routing model as secure software in EL3 can
handover the interrupt to Secure-EL1 for handling.
4. __CSS=1, TEL3=1__. Interrupt is routed to EL3 when execution is in
non-secure state. This is a valid routing model as secure software in EL3
can handover the interrupt to Secure-EL1 for handling.
##### 1.2.3.2 Non-secure interrupts
......@@ -240,7 +240,7 @@ is expected to be aware of the secure devices present in the system and their
associated interrupt numbers. It should configure the interrupt controller to
enable the secure interrupts, ensure that their priority is always higher than
the non-secure interrupts and target them to the primary CPU. It should also
export the interface described in the the [Porting Guide][PRTG] to enable
export the interface described in the [Porting Guide] to enable
handling of interrupts.
In the remainder of this document, for the sake of simplicity it is assumed that
......@@ -685,7 +685,7 @@ should handle this secure monitor call so that execution resumes in the
exception level and the security state from where the Secure-EL1 interrupt was
originally taken.
##### 2.3.2.1 Test secure payload dispatcher behavior
##### 2.3.2.3 Test secure payload dispatcher behavior
The example TSPD service registers a handler for Secure-EL1 interrupts taken
from the non-secure state. Its handler `tspd_secure_el1_interrupt_handler()`
takes the following actions upon being invoked.
......
docs/porting-guide.md
View file @ b110f61a
......@@ -1069,7 +1069,7 @@ level as 1, resulting in PSCI power control up to the cluster level.
### Function : platform_setup_pm() [mandatory]
Argument : plat_pm_ops **
Argument : const plat_pm_ops **
Return : int
This function may execute with the MMU and data caches enabled if the platform
......@@ -1081,10 +1081,9 @@ handler routines for platform-specific power management actions by populating
the passed pointer with a pointer to BL3-1's private `plat_pm_ops` structure.
A description of each member of this structure is given below. Please refer to
the ARM FVP specific implementation of these handlers in [plat/fvp/plat_pm.c]
the ARM FVP specific implementation of these handlers in [plat/fvp/fvp_pm.c]
as an example. A platform port may choose not implement some of the power
management operations. For example, the ARM FVP port does not implement the
`affinst_standby()` function.
management operations.
#### plat_pm_ops.affinst_standby()
......@@ -1300,24 +1299,24 @@ uses the group value to determine the type of interrupt.
3.5 Crash Reporting mechanism (in BL3-1)
----------------------------------------------
BL3-1 implements a crash reporting mechanism which prints the various registers
of the CPU to enable quick crash analysis and debugging. It requires that a console
is designated as the crash console by the platform which will used to print the
register dump.
of the CPU to enable quick crash analysis and debugging. It requires that a
console is designated as the crash console by the platform which will be used to
print the register dump.
The following functions must be implemented by the platform if it wants crash reporting
mechanism in BL3-1. The functions are implemented in assembly so that they can be
invoked without a C Runtime stack.
The following functions must be implemented by the platform if it wants crash
reporting mechanism in BL3-1. The functions are implemented in assembly so that
they can be invoked without a C Runtime stack.
### Function : plat_crash_console_init
Argument : void
Return : int
This API is used by the crash reporting mechanism to intialize the crash console.
It should only use the general purpose registers x0 to x2 to do the initiaization
and returns 1 on success.
This API is used by the crash reporting mechanism to initialize the crash
console. It should only use the general purpose registers x0 to x2 to do the
initialization and returns 1 on success.
The FVP port designates the PL011_UART0 as the crash console and calls the
The FVP port designates the `PL011_UART0` as the crash console and calls the
console_core_init() to initialize the console.
### Function : plat_crash_console_putc
......@@ -1330,7 +1329,7 @@ designated crash console. It should only use general purpose registers x1 and
x2 to do its work. The parameter and the return value are in general purpose
register x0.
The FVP port designates the PL011_UART0 as the crash console and calls the
The FVP port designates the `PL011_UART0` as the crash console and calls the
console_core_putc() to print the character on the console.
4. C Library
......
docs/user-guide.md
View file @ b110f61a
......@@ -17,10 +17,10 @@ Contents :
1. Introduction
----------------
This document describes how to build ARM Trusted Firmware and run it with a
tested set of other software components using defined configurations on ARM
Fixed Virtual Platform (FVP) models. It is possible to use other software
components, configurations and platforms but that is outside the scope of this
document.
tested set of other software components using defined configurations on the Juno
ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is
possible to use other software components, configurations and platforms but that
is outside the scope of this document.
This document should be used in conjunction with the [Firmware Design].
......@@ -48,7 +48,7 @@ The following tools are required to use the ARM Trusted Firmware:
* `ia32-libs` package.
* `build-essential`, `uuid-dev` and `iasl` packages for building UEFI and the
Firmware Image Package(FIP) tool.
Firmware Image Package (FIP) tool.
* `bc` and `ncurses-dev` packages for building Linux.
......@@ -79,7 +79,7 @@ To build the Trusted Firmware images, follow these steps:
cd arm-trusted-firmware
3. Set the compiler path, specify a Non-trusted Firmware image (BL3-3) and
a valid platform and build:
a valid platform, and then build:
CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \
BL33=<path-to>/<bl33_image> \
......@@ -109,8 +109,9 @@ To build the Trusted Firmware images, follow these steps:
* `build/<platform>/<build-type>/bl31.bin`
where `<platform>` is the name of the chosen platform and `<build-type>` is
either `debug` or `release`. A Firmare Image Package(FIP) will be created as
part of the build. It contains all boot loader images except for `bl1.bin`.
either `debug` or `release`. A Firmare Image Package (FIP) will be created
as part of the build. It contains all boot loader images except for
`bl1.bin`.
* `build/<platform>/<build-type>/fip.bin`
......@@ -119,7 +120,7 @@ To build the Trusted Firmware images, follow these steps:
4. (Optional) Some platforms may require a BL3-0 image to boot. This image can
be included in the FIP when building the Trusted Firmware by specifying the
BL30 build option:
`BL30` build option:
BL30=<path-to>/<bl30_image>
......@@ -150,16 +151,16 @@ performed.
* `BL30`: Path to BL3-0 image in the host file system. This image is optional.
If a BL3-0 image is present then this option must be passed for the `fip`
target
target.
* `BL33`: Path to BL33 image in the host file system. This is mandatory for
`fip` target
`fip` target.
* `CROSS_COMPILE`: Prefix to tool chain binaries. Please refer to examples in
this document for usage
* `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in
this document for usage.
* `DEBUG`: Chooses between a debug and release build. It can take either 0
(release) or 1 (debug) as values. 0 is the default
(release) or 1 (debug) as values. 0 is the default.
* `LOG_LEVEL`: Chooses the log level, which controls the amount of console log
output compiled into the build. This should be one of the following:
......@@ -176,30 +177,31 @@ performed.
* `NS_TIMER_SWITCH`: Enable save and restore for non-secure timer register
contents upon world switch. It can take either 0 (don't save and restore) or
1 (do save and restore). 0 is the default. An SPD could set this to 1 if it
wants the timer registers to be saved and restored
1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
wants the timer registers to be saved and restored.
* `PLAT`: Choose a platform to build ARM Trusted Firmware for. The chosen
platform name must be the name of one of the directories under the `plat/`
directory other than `common`
directory other than `common`.
* `SPD`: Choose a Secure Payload Dispatcher component to be built into the
Trusted Firmware. The value should be the path to the directory containing
SPD source; the directory is expected to contain `spd.mk` makefile
the SPD source, relative to `services/spd/`; the directory is expected to
contain a makefile called `<spd-value>.mk`.
* `V`: Verbose build. If assigned anything other than 0, the build commands
are printed. Default is 0
are printed. Default is 0.
* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM GIC
driver for implementing the platform GIC API. This API is used
by the interrupt management framework. Default is 2 i.e. version 2.0.
by the interrupt management framework. Default is 2 (that is, version 2.0).
* `IMF_READ_INTERRUPT_ID`: Boolean flag used by the interrupt management
framework to enable passing of the interrupt id to its handler. The id is
read using a platform GIC API. `INTR_ID_UNAVAILABLE` is passed instead if
this option set to 0. Default is 0.
* `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector in place
* `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector instead
of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
entrypoint) or 1 (CPU reset to BL3-1 entrypoint).
The default value is 0.
......@@ -211,12 +213,12 @@ performed.
* `ASM_ASSERTION`: This flag determines whether the assertion checks within
assembly source files are enabled or not. This option defaults to the
value of `DEBUG` - i.e. by default this is only enabled for a debug
value of `DEBUG` - that is, by default this is only enabled for a debug
build of the firmware.
* `TSP_INIT_ASYNC`: Choose BL3-2 initialization method as asynchronous or
synchronous, e.g. "(see "Initializing a BL3-2 Image" section in [Firmware
Design])". It can take the value 0 (BL3-2 is initialized using
synchronous, (see "Initializing a BL3-2 Image" section in [Firmware
Design]). It can take the value 0 (BL3-2 is initialized using
synchronous method) or 1 (BL3-2 is initialized using asynchronous method).
Default is 0.
......@@ -224,15 +226,15 @@ performed.
* `FVP_SHARED_DATA_LOCATION`: location of the shared memory page. Available
options:
- 'tsram' (default) : top of Trusted SRAM
- 'tdram' : base of Trusted DRAM
- `tsram` (default) : top of Trusted SRAM
- `tdram` : base of Trusted DRAM
* `FVP_TSP_RAM_LOCATION`: location of the TSP binary. Options:
- 'tsram' (default) : base of Trusted SRAM
- 'tdram' : Trusted DRAM (above shared data)
- `tsram` (default) : base of Trusted SRAM
- `tdram` : Trusted DRAM (above shared data)
For a better understanding of FVP options, the FVP memory map is detailed in
[Firmware Design].
For a better understanding of FVP options, the FVP memory map is explained in
the [Firmware Design].
### Creating a Firmware Image Package
......@@ -307,7 +309,8 @@ When debugging logic problems it might also be useful to disable all compiler
optimizations by using `-O0`.
NOTE: Using `-O0` could cause output images to be larger and base addresses
might need to be recalculated (see the later memory layout section).
might need to be recalculated (see the "Memory layout of BL images" section in
the [Firmware Design]).
Extra debug options can be passed to the build system by setting `CFLAGS`:
......@@ -333,7 +336,7 @@ BL3-1 binary. Then to build the TSP image and include it into the FIP use:
An additional boot loader binary file is created in the `build` directory:
* `build/<platform>/<build-type>/bl32.bin`
* `build/<platform>/<build-type>/bl32.bin`
The FIP will now contain the additional BL3-2 image. Here is an example
output from an FVP build in release mode including BL3-2 and using
......@@ -357,12 +360,12 @@ FVP_AARCH64_EFI.fd as BL3-3 image:
When making changes to the source for submission to the project, the source
must be in compliance with the Linux style guide, and to assist with this check
the project Makefile contains two targets, which both utilise the checkpatch.pl
script that ships with the Linux source tree.
the project Makefile contains two targets, which both utilise the
`checkpatch.pl` script that ships with the Linux source tree.
To check the entire source tree, you must first download a copy of checkpatch.pl
(or the full Linux source), set the CHECKPATCH environment variable to point to
the script and build the target checkcodebase:
To check the entire source tree, you must first download a copy of
`checkpatch.pl` (or the full Linux source), set the `CHECKPATCH` environment
variable to point to the script and build the target checkcodebase:
make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
......@@ -372,8 +375,8 @@ the remote master, use:
make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
If you wish to check your patch against something other than the remote master,
set the BASE_COMMIT variable to your desired branch. By default, BASE_COMMIT
is set to 'origin/master'.
set the `BASE_COMMIT` variable to your desired branch. By default, `BASE_COMMIT`
is set to `origin/master`.
5. Obtaining the normal world software
......@@ -385,7 +388,7 @@ Potentially any kind of non-trusted firmware may be used with the ARM Trusted
Firmware but the software has only been tested with the EFI Development Kit 2
(EDK2) open source implementation of the UEFI specification.
To build the software to be compatible with Foundation and Base FVPs and the
To build the software to be compatible with the Foundation and Base FVPs, or the
Juno platform, follow these steps:
1. Clone the [EDK2 source code][EDK2] from GitHub:
......@@ -599,7 +602,6 @@ To prepare a VirtioBlock file-system, do the following:
--block-device="<path-to>/<file-system-image>"
5. Ensure that the FVP doesn't output any error messages. If the following
error message is displayed:
......
include/plat/common/platform.h
View file @ b110f61a
......@@ -72,7 +72,7 @@ uint32_t plat_interrupt_type_to_line(uint32_t type,
unsigned int platform_get_core_pos(unsigned long mpidr);
unsigned long platform_get_stack(unsigned long mpidr);
void plat_report_exception(unsigned long);
void plat_crash_console_init(unsigned long base_addr);
int plat_crash_console_init(void);
int plat_crash_console_putc(int c);
/*******************************************************************************
......
plat/fvp/aarch64/fvp_helpers.S
View file @ b110f61a
......@@ -215,7 +215,7 @@ func plat_crash_console_init
b console_core_init
/* ---------------------------------------------
* int plat_crash_console_putc(void)
* int plat_crash_console_putc(int c)
* Function to print a character on the crash
* console without a C Runtime.
* Clobber list : x1, x2
......
plat/fvp/include/plat_macros.S
View file @ b110f61a
......@@ -45,7 +45,7 @@ spacer:
/* ---------------------------------------------
* The below macro prints out relevant GIC
* registers whenever an unhandled exception is
* taken in BL31.
* taken in BL3-1.
* Clobbers: x0 - x10, x16, sp
* ---------------------------------------------
*/
......@@ -59,7 +59,7 @@ spacer:
ldr w8, [x16, #GICC_HPPIR]
ldr w9, [x16, #GICC_AHPPIR]
ldr w10, [x16, #GICC_CTLR]
/* Store to the crash buf and print to cosole */
/* Store to the crash buf and print to console */
bl str_in_crash_buf_print
/* Print the GICD_ISPENDR regs */
......@@ -88,7 +88,7 @@ cci_iface_regs:
/* ------------------------------------------------
* The below macro prints out relevant interconnect
* registers whenever an unhandled exception is
* taken in BL31.
* taken in BL3-1.
* Clobbers: x0 - x9, sp
* ------------------------------------------------
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment