Merge pull request #1848 from antonio-nino-diaz-arm/an/docs

Minor changes to documentation and comments

bl31/bl31_main.c

@@ -90,7 +90,7 @@ void bl31_setup(u_register_t arg0, u_register_t arg1, u_register_t arg2,
  * function calls runtime_svc_init() which initializes all registered runtime
  * services. The run time services would setup enough context for the core to
  * switch to the next exception level. When this function returns, the core will
- * switch to the programmed exception level via. an ERET.
+ * switch to the programmed exception level via an ERET.
  ******************************************************************************/
 void bl31_main(void)
 {

bl31/ehf.c

@@ -314,9 +314,9 @@ static void *ehf_entering_normal_world(const void *arg)
 
 /*
  * Program Priority Mask to the original Non-secure priority such that
- * Non-secure interrupts may preempt Secure execution, viz. during Yielding SMC
- * calls. The 'preempt_ret_code' parameter indicates the Yielding SMC's return
- * value in case the call was preempted.
+ * Non-secure interrupts may preempt Secure execution (for example, during
+ * Yielding SMC calls). The 'preempt_ret_code' parameter indicates the Yielding
+ * SMC's return value in case the call was preempted.
  *
  * This API is expected to be invoked before delegating a yielding SMC to Secure
  * EL1. I.e. within the window of secure execution after Non-secure context is
@@ -360,7 +360,7 @@ void ehf_allow_ns_preemption(uint64_t preempt_ret_code)
 
 /*
  * Return whether Secure execution has explicitly allowed Non-secure interrupts
- * to preempt itself, viz. during Yielding SMC calls.
+ * to preempt itself (for example, during Yielding SMC calls).
  */
 unsigned int ehf_is_ns_preemption_allowed(void)
 {

docs/arm-sip-service.rst

@@ -4,7 +4,7 @@ Arm SiP Service
 This document enumerates and describes the Arm SiP (Silicon Provider) services.
 
 SiP services are non-standard, platform-specific services offered by the silicon
-implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
+implementer or platform provider. They are accessed via ``SMC`` ("SMC calls")
 instruction executed from Exception Levels below EL3. SMC calls for SiP
 services:
 

docs/exception-handling.rst

@@ -233,7 +233,7 @@ Note:
    The ``ARRAY_SIZE()`` macro therefore should be used to determine the size of
    array.
 
-Finally, this array of descriptors is exposed to |EHF| via. the
+Finally, this array of descriptors is exposed to |EHF| via the
 ``EHF_REGISTER_PRIORITIES()`` macro.
 
 Refer to the `Interrupt handling example`_ for usage. See also: `Interrupt
@@ -379,8 +379,8 @@ Activating and Deactivating priorities
 
 A priority level is said to be *active* when an exception of that priority is
 being handled: for interrupts, this is implied when the interrupt is
-acknowledged; for non-interrupt exceptions, viz. SErrors or `SDEI explicit
-dispatches`__, this has to be done via. calling ``ehf_activate_priority()``. See
+acknowledged; for non-interrupt exceptions, such as SErrors or `SDEI explicit
+dispatches`__, this has to be done via calling ``ehf_activate_priority()``. See
 `Run-time flow`_.
 
 .. __: sdei.rst#explicit-dispatch-of-events
@@ -388,7 +388,7 @@ dispatches`__, this has to be done via. calling ``ehf_activate_priority()``. See
 Conversely, when the dispatcher has reached a logical resolution for the cause
 of the exception, the corresponding priority level ought to be deactivated. As
 above, for interrupts, this is implied when the interrupt is EOId in the GIC;
-for other exceptions, this has to be done via. calling
+for other exceptions, this has to be done via calling
 ``ehf_deactivate_priority()``.
 
 Thanks to `different provisions`__ for exception delegation, there are
@@ -405,7 +405,7 @@ potentially more than one work flow for deactivation:
 
 -  The dispatcher has to delegate the execution to lower ELs, and the cause of
    the exception can be considered resolved only when the lower EL returns
-   signals complete (via. an ``SMC``) at a future point in time. The following
+   signals complete (via an ``SMC``) at a future point in time. The following
    sequence ensues:
 
    #. The dispatcher calls ``setjmp()`` to setup a jump point, and arranges to
@@ -414,7 +414,7 @@ potentially more than one work flow for deactivation:
    #. Through the ensuing ``ERET`` from runtime firmware, execution is delegated
       to a lower EL.
 
-   #. The lower EL completes its execution, and signals completion via. an
+   #. The lower EL completes its execution, and signals completion via an
       ``SMC``.
 
    #. The ``SMC`` is handled by the same dispatcher that handled the exception
@@ -597,7 +597,7 @@ world ones. The platform further assigns relative priorities amongst Secure
 dispatchers through |EHF|.
 
 As mentioned in `Partitioning priority levels`_, interrupts targeting distinct
-dispatchers fall in distinct priority levels. Because they're routed via. the
+dispatchers fall in distinct priority levels. Because they're routed via the
 GIC, interrupt delivery to the PE is subject to GIC prioritisation rules. In
 particular, when an interrupt is being handled by the PE (i.e., the interrupt is
 in *Active* state), only interrupts of higher priority are signalled to the PE,

docs/firmware-design.rst

@@ -1282,9 +1282,9 @@ interrupt configuration during the driver initialisation.
 Secure interrupt configuration are specified in an array of secure interrupt
 properties. In this scheme, in both GICv2 and GICv3 driver data structures, the
 ``interrupt_props`` member points to an array of interrupt properties. Each
-element of the array specifies the interrupt number and its configuration, viz.
-priority, group, configuration. Each element of the array shall be populated by
-the macro ``INTR_PROP_DESC()``. The macro takes the following arguments:
+element of the array specifies the interrupt number and its attributes
+(priority, group, configuration). Each element of the array shall be populated
+by the macro ``INTR_PROP_DESC()``. The macro takes the following arguments:
 
 - 10-bit interrupt number,
 
@@ -1439,7 +1439,7 @@ C run time. Therefore it must follow AAPCS, and must not use stack.
 
 CPU drivers that apply errata workaround can optionally implement an assembly
 function that report the status of errata workarounds pertaining to that CPU.
-For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops``
+For a driver that registers the CPU, for example, ``cpux`` via ``declare_cpu_ops``
 macro, the errata reporting function, if it exists, must be named
 ``cpux_errata_report``. This function will always be called with MMU enabled; it
 must follow AAPCS and may use stack.

docs/platform-interrupt-controller-API.rst

@@ -22,7 +22,7 @@ Function: unsigned int plat_ic_get_running_priority(void); [optional]
 
 This API should return the priority of the interrupt the PE is currently
 servicing. This must be be called only after an interrupt has already been
-acknowledged via. ``plat_ic_acknowledge_interrupt``.
+acknowledged via ``plat_ic_acknowledge_interrupt``.
 
 In the case of Arm standard platforms using GIC, the *Running Priority Register*
 is read to determine the priority of the interrupt.

docs/porting-guide.rst

@@ -1936,7 +1936,7 @@ handler (if present) is called for the CPU power domain.
 
 The ``power-state`` parameter of a PSCI ``CPU_SUSPEND`` call can be used to
 describe composite power states specific to a platform. The PSCI implementation
-defines a generic representation of the power-state parameter viz which is an
+defines a generic representation of the power-state parameter, which is an
 array of local power states where each index corresponds to a power domain
 level. Each entry contains the local power state the power domain at that power
 level could enter. It depends on the ``validate_power_state()`` handler to

docs/ras.rst

@@ -15,10 +15,10 @@ Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and
 later CPUs, and also an optional extension to the base Armv8.0 architecture.
 
 In conjunction with the |EHF|, support for RAS extension enables firmware-first
-paradigm for handling platform errors, in which exceptions resulting from
-errors—viz. Synchronous External Abort (SEA), Asynchronous External Abort
-(signalled as SErrors), Fault Handling and Error Recovery interrupts are routed
-to and handled in EL3. The |EHF| document mentions various `error handling
+paradigm for handling platform errors: exceptions resulting from errors are
+routed to and handled in EL3. Said errors are Synchronous External Abort (SEA),
+Asynchronous External Abort (signalled as SErrors), Fault Handling and Error
+Recovery interrupts.  The |EHF| document mentions various `error handling
 use-cases`__.
 
 .. __: exception-handling.rst#delegation-use-cases
@@ -66,7 +66,7 @@ through one one of the notification mechanisms—SEAs, SErrors, or interrupts. R
 nodes contain one or more error records, which are registers through which the
 nodes advertise various properties of the signalled error. Arm recommends that
 error records are implemented in the Standard Error Record format. The RAS
-architecture allows for error records to be accessible via. system or
+architecture allows for error records to be accessible via system or
 memory-mapped registers.
 
 The platform should enumerate the error records providing for each of them:
@@ -121,7 +121,7 @@ The error handler must have the following prototype:
                int probe_data, const struct err_handler_data *const data);
 
 The ``data`` constant parameter describes the various properties of the error,
-viz. the reason for the error, exception syndrome, and also ``flags``,
+including the reason for the error, exception syndrome, and also ``flags``,
 ``cookie``, and ``handle`` parameters from the `top-level exception handler`__.
 
 .. __: interrupt-framework-design.rst#el3-interrupts

docs/sdei.rst

@@ -142,7 +142,7 @@ Event flags describe the properties of the event. They are bit maps that can be
 .. __: `Defining events`_
 
 -  ``SDEI_MAPF_DYNAMIC``: Marks the event as dynamic. Dynamic events can be
-   bound to (or released from) any Non-secure interrupt at runtime via. the
+   bound to (or released from) any Non-secure interrupt at runtime via the
    ``SDEI_INTERRUPT_BIND`` and ``SDEI_INTERRUPT_RELEASE`` calls.
 
 -  ``SDEI_MAPF_BOUND``: Marks the event as statically bound to an interrupt.
@@ -226,7 +226,7 @@ Explicit dispatch of events
 Typically, an SDEI event dispatch is caused by the PE receiving interrupts that
 are bound to an SDEI event. However, there are cases where the Secure world
 requires dispatch of an SDEI event as a direct or indirect result of a past
-activity, viz. receiving a Secure interrupt or an exception.
+activity, such as receiving a Secure interrupt or an exception.
 
 The SDEI dispatcher implementation provides ``sdei_dispatch_event()`` API for
 this purpose. The API has the following signature:

docs/user-guide.rst

@@ -548,13 +548,13 @@ Common build options
 
 -  ``KEY_ALG``: This build flag enables the user to select the algorithm to be
    used for generating the PKCS keys and subsequent signing of the certificate.
-   It accepts 3 values viz. ``rsa``, ``rsa_1_5``, ``ecdsa``. The ``rsa_1_5`` is
-   the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR compliant and is
-   retained only for compatibility. The default value of this flag is ``rsa``
-   which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
+   It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option
+   ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR
+   compliant and is retained only for compatibility. The default value of this
+   flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
 
 -  ``HASH_ALG``: This build flag enables the user to select the secure hash
-   algorithm. It accepts 3 values viz. ``sha256``, ``sha384``, ``sha512``.
+   algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
    The default value of this flag is ``sha256``.
 
 -  ``LDFLAGS``: Extra user options appended to the linkers' command line in
@@ -619,14 +619,14 @@ Common build options
    does not need to be implemented in this case.
 
 -  ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
-   possible for the PSCI power-state parameter viz original and extended
-   State-ID formats. This flag if set to 1, configures the generic PSCI layer
-   to use the extended format. The default value of this flag is 0, which
-   means by default the original power-state format is used by the PSCI
-   implementation. This flag should be specified by the platform makefile
-   and it governs the return value of PSCI_FEATURES API for CPU_SUSPEND
-   smc function id. When this option is enabled on Arm platforms, the
-   option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well.
+   possible for the PSCI power-state parameter: original and extended State-ID
+   formats. This flag if set to 1, configures the generic PSCI layer to use the
+   extended format. The default value of this flag is 0, which means by default
+   the original power-state format is used by the PSCI implementation. This flag
+   should be specified by the platform makefile and it governs the return value
+   of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is
+   enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be
+   set to 1 as well.
 
 -  ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features
    are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2

drivers/arm/css/scpi/css_scpi.c

@@ -169,7 +169,7 @@ void scpi_set_css_power_state(unsigned int mpidr,
  * In response to the query, SCP returns power states of all CPUs in all
  * clusters of the system. The returned response is then filtered based on the
  * supplied MPIDR. Power states of requested cluster and CPUs within are updated
- * via. supplied non-NULL pointer arguments.
+ * via supplied non-NULL pointer arguments.
  *
  * Returns 0 on success, or -1 on errors.
  */
@@ -223,7 +223,7 @@ int scpi_get_css_power_state(unsigned int mpidr, unsigned int *cpu_state_p,
 	if (CLUSTER_ID(power_state) != cluster)
 		goto exit;
 
-	/* Update power state via. pointers */
+	/* Update power state via pointers */
 	if (cluster_state_p)
 		*cluster_state_p = CLUSTER_POWER_STATE(power_state);
 	if (cpu_state_p)

drivers/arm/gic/v2/gicv2_main.c

@@ -279,8 +279,8 @@ unsigned int gicv2_get_running_priority(void)
 /*******************************************************************************
  * This function sets the GICv2 target mask pattern for the current PE. The PE
  * target mask is used to translate linear PE index (returned by platform core
- * position) to a bit mask used when targeting interrupts to a PE, viz. when
- * raising SGIs and routing SPIs.
+ * position) to a bit mask used when targeting interrupts to a PE (for example
+ * when raising SGIs and routing SPIs).
  ******************************************************************************/
 void gicv2_set_pe_target_mask(unsigned int proc_num)
 {

include/lib/el3_runtime/pubsub.h

@@ -49,7 +49,7 @@
 /*
  * Have the function func called back when the specified event happens. This
  * macro places the function address into the pubsub section, which is picked up
- * and invoked by the invoke_pubsubs() function via. the PUBLISH_EVENT* macros.
+ * and invoked by the invoke_pubsubs() function via the PUBLISH_EVENT* macros.
  *
  * The extern declaration is there to satisfy MISRA C-2012 rule 8.4.
  */

include/lib/extensions/ras.h

@@ -106,7 +106,7 @@ struct err_handler_data {
 	 */
 	uint32_t syndrome;
 
-	/* For errors signalled via. interrupt, the raw interrupt ID; otherwise, 0. */
+	/* For errors signalled via interrupt, the raw interrupt ID; otherwise, 0. */
 	unsigned int interrupt;
 };
 
@@ -129,7 +129,7 @@ struct err_record_info {
 	union {
 		struct {
 			/*
-			 * For a group accessed via. memory-mapped register,
+			 * For a group accessed via memory-mapped register,
 			 * base address of the page hosting error records, and
 			 * the size of the record group.
 			 */
@@ -141,7 +141,7 @@ struct err_record_info {
 
 		struct {
 			/*
-			 * For error records accessed via. system register, index of
+			 * For error records accessed via system register, index of
 			 * the error record.
 			 */
 			unsigned int idx_start;

lib/el3_runtime/aarch64/context.S

@@ -456,7 +456,7 @@ func restore_gp_registers
 endfunc restore_gp_registers
 
 /* -----------------------------------------------------
- * Restore general purpose registers (including x30), and exit EL3 via. ERET to
+ * Restore general purpose registers (including x30), and exit EL3 via ERET to
  * a lower exception level.
  * -----------------------------------------------------
  */

make_helpers/defaults.mk

@@ -140,8 +140,7 @@ PL011_GENERIC_UART		:= 0
 # The platform Makefile is free to override this value.
 PROGRAMMABLE_RESET_ADDRESS	:= 0
 
-# Flag used to choose the power state format viz Extended State-ID or the
-# Original format.
+# Flag used to choose the power state format: Extended State-ID or Original
 PSCI_EXTENDED_STATE_ID		:= 0
 
 # Enable RAS support

plat/common/aarch64/platform_mp_stack.S

@@ -14,13 +14,13 @@
 	.weak	plat_set_my_stack
 
 	/* ---------------------------------------------------------------------
-	 * When the compatility layer is disabled, the new platform APIs
-	 * viz plat_get_my_stack() and plat_set_my_stack() are
-	 * supported by the platform and the previous APIs platform_get_stack()
-	 * and platform_set_stack() are defined in terms of new APIs making use
-	 * of the fact that they are only ever invoked for the current CPU.
-	 * This is to enable components of Trusted Firmware like SPDs using the
-	 * old platform APIs to continue to work.
+	 * When the compatility layer is disabled, the platform APIs
+	 * plat_get_my_stack() and plat_set_my_stack() are supported by the
+	 * platform and the previous APIs platform_get_stack() and
+	 * platform_set_stack() are defined in terms of new APIs making use of
+	 * the fact that they are only ever invoked for the current CPU.  This
+	 * is to enable components of Trusted Firmware like SPDs using the old
+	 * platform APIs to continue to work.
 	 * --------------------------------------------------------------------
 	 */