Miscellaneous documentation fixes
This patch gathers miscellaneous minor fixes to the documentation, and comments
in the source code.
Change-Id: I631e3dda5abafa2d90f464edaee069a1e58b751b
Co-Authored-By: Soby Mathew <soby.mathew@arm.com>
Co-Authored-By: Dan Handley <dan.handley@arm.com>
diff --git a/bl1/aarch64/bl1_exceptions.S b/bl1/aarch64/bl1_exceptions.S
index 13b34b7..1ca3a6c 100644
--- a/bl1/aarch64/bl1_exceptions.S
+++ b/bl1/aarch64/bl1_exceptions.S
@@ -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 @@
check_vector_size SErrorSP0
/* -----------------------------------------------------
- * Current EL with SPx: 0x200 - 0x380
+ * Current EL with SPx: 0x200 - 0x400
* -----------------------------------------------------
*/
.align 7
@@ -107,7 +107,7 @@
check_vector_size SErrorSPx
/* -----------------------------------------------------
- * Lower EL using AArch64 : 0x400 - 0x580
+ * Lower EL using AArch64 : 0x400 - 0x600
* -----------------------------------------------------
*/
.align 7
@@ -184,7 +184,7 @@
check_vector_size SErrorA64
/* -----------------------------------------------------
- * Lower EL using AArch32 : 0x0 - 0x180
+ * Lower EL using AArch32 : 0x600 - 0x800
* -----------------------------------------------------
*/
.align 7
diff --git a/bl31/aarch64/bl31_entrypoint.S b/bl31/aarch64/bl31_entrypoint.S
index c74858f..04063e1 100644
--- a/bl31/aarch64/bl31_entrypoint.S
+++ b/bl31/aarch64/bl31_entrypoint.S
@@ -198,7 +198,3 @@
bl bl31_main
b el3_exit
-
-_panic:
- wfi
- b _panic
diff --git a/bl31/aarch64/context.S b/bl31/aarch64/context.S
index 1117026..b127480 100644
--- a/bl31/aarch64/context.S
+++ b/bl31/aarch64/context.S
@@ -207,7 +207,7 @@
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
diff --git a/bl31/aarch64/runtime_exceptions.S b/bl31/aarch64/runtime_exceptions.S
index f5be9e0..3265862 100644
--- a/bl31/aarch64/runtime_exceptions.S
+++ b/bl31/aarch64/runtime_exceptions.S
@@ -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 @@
.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 @@
check_vector_size serror_sp_el0
/* -----------------------------------------------------
- * Current EL with SPx: 0x200 - 0x380
+ * Current EL with SPx: 0x200 - 0x400
* -----------------------------------------------------
*/
.align 7
@@ -230,7 +230,7 @@
check_vector_size serror_sp_elx
/* -----------------------------------------------------
- * Lower EL using AArch64 : 0x400 - 0x580
+ * Lower EL using AArch64 : 0x400 - 0x600
* -----------------------------------------------------
*/
.align 7
@@ -267,7 +267,7 @@
check_vector_size serror_aarch64
/* -----------------------------------------------------
- * Lower EL using AArch32 : 0x600 - 0x780
+ * Lower EL using AArch32 : 0x600 - 0x800
* -----------------------------------------------------
*/
.align 7
diff --git a/docs/cpu-errata-workarounds.md b/docs/cpu-errata-workarounds.md
index 73e8e18..8285d89 100644
--- a/docs/cpu-errata-workarounds.md
+++ b/docs/cpu-errata-workarounds.md
@@ -1,7 +1,7 @@
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 @@
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 :
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 41a0432..6161b52 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -1195,35 +1195,35 @@
The following list describes the memory layout on the FVP:
- * 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.
+* 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
- 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.
+* 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
- sections will overwrite BL1 R/W data.
+* 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
- 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
- overlap.
+* 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
+ overlap.
This memory layout is designed to give the BL3-2 image as much memory as
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 @@
0x00000000 +----------+
-** Shared data & TSP in Trusted DRAM: **
+**Shared data & TSP in Trusted DRAM:**
Trusted DRAM
0x08000000 +----------+
@@ -1271,7 +1271,7 @@
| BL1 (ro) |
0x00000000 +----------+
-** Shared data in Trusted DRAM, TSP in Trusted SRAM: **
+**Shared data in Trusted DRAM, TSP in Trusted SRAM:**
Trusted DRAM
0x08000000 +----------+
diff --git a/docs/interrupt-framework-design.md b/docs/interrupt-framework-design.md
index f96f764..d620f3b 100644
--- a/docs/interrupt-framework-design.md
+++ b/docs/interrupt-framework-design.md
@@ -55,7 +55,7 @@
intervention from non-secure software.
2. It should be possible to route interrupts meant to be handled by
- non-secure software (Non-secure interrupts) to the last executed exception
+ non-secure software (Non-secure interrupts) to the last executed exception
level in the normal world when the execution is in secure world at
exception levels lower than EL3. This could be done with or without the
knowledge of software executing in Secure-EL1/Secure-EL0. The choice of
@@ -151,9 +151,9 @@
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 @@
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 @@
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.
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 0a07bff..ae5e720 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -1069,7 +1069,7 @@
### 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 @@
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 @@
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 @@
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
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 94db701..d60b623 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -17,10 +17,10 @@
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 @@
* `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 @@
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 @@
* `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 @@
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 @@
* `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 @@
* `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 @@
* `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 @@
* `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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
--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:
diff --git a/include/plat/common/platform.h b/include/plat/common/platform.h
index 8e038aa..69bb749 100644
--- a/include/plat/common/platform.h
+++ b/include/plat/common/platform.h
@@ -72,7 +72,7 @@
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);
/*******************************************************************************
diff --git a/plat/fvp/aarch64/fvp_helpers.S b/plat/fvp/aarch64/fvp_helpers.S
index 94f15c0..e4749e0 100644
--- a/plat/fvp/aarch64/fvp_helpers.S
+++ b/plat/fvp/aarch64/fvp_helpers.S
@@ -215,7 +215,7 @@
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
diff --git a/plat/fvp/include/plat_macros.S b/plat/fvp/include/plat_macros.S
index 892dbfb..0419906 100644
--- a/plat/fvp/include/plat_macros.S
+++ b/plat/fvp/include/plat_macros.S
@@ -45,7 +45,7 @@
/* ---------------------------------------------
* 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 @@
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 @@
/* ------------------------------------------------
* The below macro prints out relevant interconnect
* registers whenever an unhandled exception is
- * taken in BL31.
+ * taken in BL3-1.
* Clobbers: x0 - x9, sp
* ------------------------------------------------
*/