Miscellaneous doc fixes for v1.2

Change-Id: I6f49bd779f2a4d577c6443dd160290656cdbc59b

Makefile

@@ -56,7 +56,7 @@ SPD				:= none
 BASE_COMMIT			:= origin/master
 # NS timer register save and restore
 NS_TIMER_SWITCH			:= 0
-# By default, Bl1 acts as the reset handler, not BL31
+# By default, BL1 acts as the reset handler, not BL31
 RESET_TO_BL31			:= 0
 # Include FP registers in cpu context
 CTX_INCLUDE_FPREGS		:= 0
@@ -295,7 +295,7 @@ include plat/compat/plat_compat.mk
 endif
 
 # Include the CPU specific operations makefile. By default all CPU errata
-# workarounds and CPU specifc optimisations are disabled. This can be
+# workarounds and CPU specific optimisations are disabled. This can be
 # overridden by the platform.
 include lib/cpus/cpu-ops.mk
 
@@ -309,7 +309,7 @@ ifeq (${DISABLE_PEDANTIC},0)
         CFLAGS		+= 	-pedantic
 endif
 
-# Using the ARM Trusted Firmware BL2 implies that a BL33 image also need to be
+# Using the ARM Trusted Firmware BL2 implies that a BL33 image also needs to be
 # supplied for the FIP and Certificate generation tools. This flag can be
 # overridden by the platform.
 ifdef BL2_SOURCES

bl31/aarch64/crash_reporting.S

@@ -359,7 +359,7 @@ func report_unhandled_exception
 report_unhandled_interrupt:
 	b	crash_panic
 endfunc report_unhandled_exception
-#endif	/* CRASH_REPORING */
+#endif	/* CRASH_REPORTING */
 
 
 func crash_panic

bl31/bl31.mk

@@ -61,7 +61,7 @@ endif
 
 BL31_LINKERFILE		:=	bl31/bl31.ld.S
 
-# Flag used to inidicate if Crash reporting via console should be included
+# Flag used to indicate if Crash reporting via console should be included
 # in BL31. This defaults to being present in DEBUG builds only
 ifndef CRASH_REPORTING
 CRASH_REPORTING		:=	$(DEBUG)

bl31/runtime_svc.c

@@ -110,7 +110,7 @@ void runtime_svc_init(void)
 		}
 
 		/*
-		 * The runtime service may have seperate rt_svc_desc_t
+		 * The runtime service may have separate rt_svc_desc_t
 		 * for its fast smc and standard smc. Since the service itself
 		 * need to be initialized only once, only one of them will have
 		 * an initialisation routine defined. Call the initialisation

common/aarch64/context.S

@@ -303,7 +303,7 @@ func fpregs_context_restore
 
 	/*
 	 * No explict ISB required here as ERET to
-	 * swtich to secure EL1 or non-secure world
+	 * switch to secure EL1 or non-secure world
 	 * covers it
 	 */
 

docs/firmware-design.md

@@ -99,8 +99,8 @@ The functionality implemented by this stage is as follows.
 
 Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
 boot and a cold boot. This is done using platform-specific mechanisms (see the
-`platform_get_entrypoint()` function in the [Porting Guide]). In the case of a
-warm boot, a CPU is expected to continue execution from a seperate
+`plat_get_my_entrypoint()` function in the [Porting Guide]). In the case of a
+warm boot, a CPU is expected to continue execution from a separate
 entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
 platform-specific state (see the `plat_secondary_cold_boot_setup()` function in
 the [Porting Guide]) while the primary CPU executes the remaining cold boot path
@@ -217,7 +217,7 @@ In the normal boot flow, BL1 execution continues as follows:
     there is not enough free trusted SRAM the following error message is
     printed:
 
-        "Failed to load boot loader stage 2 (BL2) firmware."
+        "Failed to load BL2 firmware."
 
     If the load is successful, BL1 updates the limits of the remaining free
     trusted SRAM. It also populates information about the amount of trusted
@@ -228,7 +228,7 @@ In the normal boot flow, BL1 execution continues as follows:
 2.  BL1 prints the following string from the primary CPU to indicate successful
     execution of the BL1 stage:
 
-        "Booting trusted firmware boot loader stage 1"
+        "Booting Trusted Firmware"
 
 3.  BL1 passes control to the BL2 image at Secure EL1, starting from its load
     address.
@@ -712,7 +712,7 @@ required support.
 | PSCI v1.0 API         |Supported| Comments                                  |
 |:----------------------|:--------|:------------------------------------------|
 |`PSCI_VERSION`         | Yes     | The version returned is 1.0               |
-|`CPU_SUSPEND`          | Yes*    | The original `power_state` format is used |
+|`CPU_SUSPEND`          | Yes*    |                                           |
 |`CPU_OFF`              | Yes*    |                                           |
 |`CPU_ON`               | Yes*    |                                           |
 |`AFFINITY_INFO`        | Yes     |                                           |
@@ -796,7 +796,7 @@ To do this the SPD has to register a BL32 initialization function during
 initialization of the SPD service. The BL32 initialization function has this
 prototype:
 
-    int32_t init();
+    int32_t init(void);
 
 and is registered using the `bl31_register_bl32_init()` function.
 
@@ -806,7 +806,7 @@ before returning through EL3 and running the non-trusted firmware (BL33):
 1.  In the BL32 setup function, use `bl31_set_next_image_type()` to
     request that the exit from `bl31_main()` is to the BL32 entrypoint in
     Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
-    calling bl31_prepare_next_image_entry() and el3_exit().
+    calling `bl31_prepare_next_image_entry()` and `el3_exit()`.
 
     When the BL32 has completed initialization at Secure-EL1, it returns to
     BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
@@ -816,7 +816,7 @@ before returning through EL3 and running the non-trusted firmware (BL33):
     the normal world firmware BL33. On return from the handler the framework
     will exit to EL2 and run BL33.
 
-2.  The BL32 setup function registers a initialization function using
+2.  The BL32 setup function registers an initialization function using
     `bl31_register_bl32_init()` which provides a SPD-defined mechanism to
     invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
     entrypoint.
@@ -1501,7 +1501,7 @@ structure is allocated in the coherent memory region in the Trusted Firmware
 because it can be accessed by multple CPUs, either with caches enabled or
 disabled.
 
-typedef struct non_cpu_pwr_domain_node {
+    typedef struct non_cpu_pwr_domain_node {
         /*
          * Index of the first CPU power domain node level 0 which has this node
          * as its parent.
@@ -1527,7 +1527,7 @@ typedef struct non_cpu_pwr_domain_node {
 
         /* For indexing the psci_lock array*/
         unsigned char lock_index;
-} non_cpu_pd_node_t;
+    } non_cpu_pd_node_t;
 
 In order to move this data structure to normal memory, the use of each of its
 fields must be analyzed. Fields like `cpu_start_idx`, `ncpus`, `parent_node`
@@ -1659,7 +1659,7 @@ There is however a performance impact for bakery locks, due to:
 *   Multiple cache line reads for each lock operation, since the bakery locks
     for each CPU are distributed across different cache lines.
 
-The implementation has been optimized to mimimize this additional overhead.
+The implementation has been optimized to minimize this additional overhead.
 Measurements indicate that when bakery locks are allocated in Normal memory, the
 minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas
 in Device memory the same is 2 micro seconds. The measurements were done on the

docs/interrupt-framework-design.md

@@ -359,7 +359,7 @@ for the security state specified in the `flags` parameter.
 
 Once the handler routine completes, execution will return to either the secure
 or non-secure state. The handler routine should return a pointer to
-`cpu_context` structure of the current CPU for the the target security state. It
+`cpu_context` structure of the current CPU for the target security state. It
 should treat all error conditions as critical errors and take appropriate action
 within its implementation e.g. use assertion failures.
 

docs/porting-guide.md

@@ -430,8 +430,8 @@ must also be defined:
 If the platform needs to allocate data within the per-cpu data framework in
 BL31, it should define the following macro. Currently this is only required if
 the platform decides not to use the coherent memory section by undefining the
-USE_COHERENT_MEM build flag. In this case, the framework allocates the required
-memory within the the per-cpu data to minimize wastage.
+`USE_COHERENT_MEM` build flag. In this case, the framework allocates the
+required memory within the the per-cpu data to minimize wastage.
 
 *   **#define : PLAT_PCPU_DATA_SIZE**
 
@@ -477,7 +477,7 @@ found in `plat/arm/board/<plat_name>/include/plat_macros.S`.
 
 BL1 by default implements the reset vector where execution starts from a cold
 or warm boot. BL31 can be optionally set as a reset vector using the
-RESET_TO_BL31 make variable.
+`RESET_TO_BL31` make variable.
 
 For each CPU, the reset vector code is responsible for the following tasks:
 
@@ -1437,7 +1437,7 @@ concept of a _power domain_. A _power domain_ is a CPU or a logical group of
 CPUs which share some state on which power management operations can be
 performed as specified by [PSCI]. Each CPU in the system is assigned a cpu
 index which is a unique number between `0` and `PLATFORM_CORE_COUNT - 1`.
-The _power domains_ are arranged in a hierarchial tree structure and
+The _power domains_ are arranged in a hierarchical tree structure and
 each _power domain_ can be identified in a system by the cpu index of any CPU
 that is part of that domain and a _power domain level_. A processing element
 (for example, a CPU) is at level 0. If the _power domain_ node above a CPU is
@@ -1725,7 +1725,7 @@ depends upon the id value as follows.
     Return   : uint32_t
 
 This API returns the id of the highest priority pending interrupt at the
-platform IC. INTR_ID_UNAVAILABLE is returned when there is no interrupt
+platform IC. `INTR_ID_UNAVAILABLE` is returned when there is no interrupt
 pending.
 
 In the case of ARM standard platforms using GICv2, the _Highest Priority

docs/rt-svc-writers-guide.md

@@ -127,7 +127,7 @@ initialization and call handler functions.
         typedef uint64_t (*rt_svc_handle)(uint32_t smc_fid,
                                           uint64_t x1, uint64_t x2,
                                           uint64_t x3, uint64_t x4,
-                                          void *reserved,
+                                          void *cookie,
                                           void *handle,
                                           uint64_t flags);
 
@@ -296,7 +296,7 @@ provide this information....
 
 - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
+_Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved._
 
 
 [Firmware Design]:  ./firmware-design.md
@@ -304,7 +304,7 @@ _Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
 [`services`]:               ../services
 [`services/std_svc/psci`]:  ../services/std_svc/psci
 [`std_svc_setup.c`]:        ../services/std_svc/std_svc_setup.c
-[`runtime_svc.h`]:          ../include/runtime_svc.h
+[`runtime_svc.h`]:          ../include/bl31/runtime_svc.h
 [`smcc_helpers.h`]:          ../include/common/smcc_helpers.h
 [PSCI]:                     http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
 [SMCCC]:                    http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"

docs/user-guide.md

@@ -132,7 +132,7 @@ Trusted Firmware source tree and 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
+    either `debug` or `release`. A Firmware Image Package (FIP) will be created
     as part of the build. It contains all boot loader images except for
     `bl1.bin`.
 
@@ -167,8 +167,8 @@ Trusted Firmware source tree and follow these steps:
     the specified binary in the final FIP image. Please note that BL32 will be
     included in the build, only if the `SPD` build option is specified.
 
-    For example, specifying BL2=<path-to>/<bl2_image> in the build option, will
-    skip compilation of BL2 source in trusted firmware, but include the BL2
+    For example, specifying `BL2=<path-to>/<bl2_image>` in the build option,
+    will skip compilation of BL2 source in trusted firmware, but include the BL2
     binary specified in the final FIP image.
 
 ### Summary of build options
@@ -399,8 +399,8 @@ performed.
 *   `SPIN_ON_BL1_EXIT`: This option introduces an infinite loop in BL1. It can
     take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
     execution in BL1 just before handing over to BL31. At this point, all
-    firmware images have been loaded in memory and the MMU as well as the caches
-    are turned off. Refer to the "Debugging options" section for more details.
+    firmware images have been loaded in memory, and the MMU and caches are
+    turned off. Refer to the "Debugging options" section for more details.
 
 *   `EL3_PAYLOAD_BASE`: This option enables booting an EL3 payload instead of
     the normal boot flow. It must specify the entry point address of the EL3
@@ -516,7 +516,7 @@ View the contents of an existing Firmware package:
     - EL3 Runtime Firmware BL31: offset=0x8270, size=0xC218
     ---------------------------
 
-Existing package entries can be individially updated:
+Existing package entries can be individually updated:
 
     # Change the BL2 from Debug to Release version
     ./tools/fip_create/fip_create fip.bin --dump \
@@ -599,7 +599,7 @@ An additional boot loader binary file is created in the `build` directory:
 
 The FIP will now contain the additional BL32 image. Here is an example
 output from an FVP build in release mode including BL32 and using
-FVP_AARCH64_EFI.fd as BL33 image:
+`FVP_AARCH64_EFI.fd` as BL33 image:
 
     Firmware Image Package ToC:
     ---------------------------

include/bl31/services/psci.h

@@ -38,7 +38,7 @@
 #endif
 
 /*******************************************************************************
- * Number of power domains whose state this psci imp. can track
+ * Number of power domains whose state this PSCI implementation can track
  ******************************************************************************/
 #ifdef PLAT_NUM_PWR_DOMAINS
 #define PSCI_NUM_PWR_DOMAINS	PLAT_NUM_PWR_DOMAINS
@@ -60,7 +60,7 @@
 #define PSCI_MAX_PWR_LVL	3
 
 /*******************************************************************************
- * Defines for runtime services func ids
+ * Defines for runtime services function ids
  ******************************************************************************/
 #define PSCI_VERSION			0x84000000
 #define PSCI_CPU_SUSPEND_AARCH32	0x84000001
@@ -255,7 +255,7 @@ typedef struct psci_cpu_data {
 
 /*******************************************************************************
  * Structure populated by platform specific code to export routines which
- * perform common low level pm functions
+ * perform common low level power management functions
  ******************************************************************************/
 typedef struct plat_psci_ops {
 	void (*cpu_standby)(plat_local_state_t cpu_state);
@@ -276,7 +276,7 @@ typedef struct plat_psci_ops {
 
 /*******************************************************************************
  * Optional structure populated by the Secure Payload Dispatcher to be given a
- * chance to perform any bookkeeping before PSCI executes a power mgmt.
+ * chance to perform any bookkeeping before PSCI executes a power management
  * operation. It also allows PSCI to determine certain properties of the SP e.g.
  * migrate capability etc.
  ******************************************************************************/

plat/arm/board/fvp/aarch64/fvp_helpers.S

@@ -139,7 +139,7 @@ endfunc plat_secondary_cold_boot_setup
 	 * For a warm boot, read the mailbox and return the address it contains.
 	 *
 	 * TODO: PSYSR is a common register and should be
-	 * 	accessed using locks. Since its not possible
+	 * 	accessed using locks. Since it is not possible
 	 * 	to use locks immediately after a cold reset
 	 * 	we are relying on the fact that after a cold
 	 * 	reset all cpus will read the same WK field

services/spd/tspd/tspd_main.c

@@ -231,7 +231,7 @@ int32_t tspd_setup(void)
 		return 1;
 
 	/*
-	 * We could inspect the SP image and determine it's execution
+	 * We could inspect the SP image and determine its execution
 	 * state i.e whether AArch32 or AArch64. Assuming it's AArch64
 	 * for the time being.
 	 */
@@ -461,7 +461,7 @@ uint64_t tspd_smc_handler(uint32_t smc_fid,
 #endif
 
 	/*
-	 * These function IDs is used only by the SP to indicate it has
+	 * These function IDs are used only by the SP to indicate it has
 	 * finished:
 	 * 1. turning itself on in response to an earlier psci
 	 *    cpu_on request
@@ -472,7 +472,7 @@ uint64_t tspd_smc_handler(uint32_t smc_fid,
 	case TSP_RESUME_DONE:
 
 	/*
-	 * These function IDs is used only by the SP to indicate it has
+	 * These function IDs are used only by the SP to indicate it has
 	 * finished:
 	 * 1. suspending itself after an earlier psci cpu_suspend
 	 *    request.

services/std_svc/psci/psci_private.h

@@ -206,10 +206,10 @@ int psci_cpu_on_start(unsigned long target_cpu,
 void psci_cpu_on_finish(unsigned int cpu_idx,
 			psci_power_state_t *state_info);
 
-/* Private exported functions from psci_cpu_off.c */
+/* Private exported functions from psci_off.c */
 int psci_do_cpu_off(unsigned int end_pwrlvl);
 
-/* Private exported functions from psci_pwrlvl_suspend.c */
+/* Private exported functions from psci_suspend.c */
 void psci_cpu_suspend_start(entry_point_info_t *ep,
 			unsigned int end_pwrlvl,
 			psci_power_state_t *state_info,