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

Miscellaneous documentation fixes

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 @@ 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

@@ -198,7 +198,3 @@ func bl31_entrypoint
 	bl	bl31_main
 
 	b	el3_exit
-
-_panic:
-	wfi
-	b	_panic

bl31/aarch64/context.S

@@ -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

@@ -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

 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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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
 	 * ------------------------------------------------
 	 */