From 73308618fee8afc4518c592956b31864e57e48e7 Mon Sep 17 00:00:00 2001 From: Antonio Nino Diaz Date: Thu, 28 Feb 2019 13:35:21 +0000 Subject: [PATCH] Minor changes to documentation and comments Fix some typos and clarify some sentences. Change-Id: Id276d1ced9a991b4eddc5c47ad9a825e6b29ef74 Signed-off-by: Antonio Nino Diaz --- bl31/bl31_main.c | 2 +- bl31/ehf.c | 8 +++---- docs/arm-sip-service.rst | 2 +- docs/exception-handling.rst | 14 ++++++------ docs/firmware-design.rst | 8 +++---- docs/platform-interrupt-controller-API.rst | 2 +- docs/porting-guide.rst | 2 +- docs/ras.rst | 12 +++++----- docs/sdei.rst | 4 ++-- docs/user-guide.rst | 26 +++++++++++----------- drivers/arm/css/scpi/css_scpi.c | 4 ++-- drivers/arm/gic/v2/gicv2_main.c | 4 ++-- include/lib/el3_runtime/pubsub.h | 2 +- include/lib/extensions/ras.h | 6 ++--- lib/el3_runtime/aarch64/context.S | 2 +- make_helpers/defaults.mk | 3 +-- plat/common/aarch64/platform_mp_stack.S | 14 ++++++------ 17 files changed, 57 insertions(+), 58 deletions(-) diff --git a/bl31/bl31_main.c b/bl31/bl31_main.c index aca16d677..856ea9f62 100644 --- a/bl31/bl31_main.c +++ b/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) { diff --git a/bl31/ehf.c b/bl31/ehf.c index 1bcebee53..745f165d4 100644 --- a/bl31/ehf.c +++ b/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) { diff --git a/docs/arm-sip-service.rst b/docs/arm-sip-service.rst index 9f0e26615..6cdac8357 100644 --- a/docs/arm-sip-service.rst +++ b/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: diff --git a/docs/exception-handling.rst b/docs/exception-handling.rst index dbcd4bca8..b7cd69d4c 100644 --- a/docs/exception-handling.rst +++ b/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, diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index ead7297d9..266de2795 100644 --- a/docs/firmware-design.rst +++ b/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. diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 230a99055..ad68709a3 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/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. diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index c3df389f8..3ea86b04f 100644 --- a/docs/porting-guide.rst +++ b/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 diff --git a/docs/ras.rst b/docs/ras.rst index cea74e9af..ac4d019f1 100644 --- a/docs/ras.rst +++ b/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 diff --git a/docs/sdei.rst b/docs/sdei.rst index 531145f87..c52481706 100644 --- a/docs/sdei.rst +++ b/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: diff --git a/docs/user-guide.rst b/docs/user-guide.rst index b42012757..b602956aa 100644 --- a/docs/user-guide.rst +++ b/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 diff --git a/drivers/arm/css/scpi/css_scpi.c b/drivers/arm/css/scpi/css_scpi.c index 4b73265ad..c56b7c41b 100644 --- a/drivers/arm/css/scpi/css_scpi.c +++ b/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) diff --git a/drivers/arm/gic/v2/gicv2_main.c b/drivers/arm/gic/v2/gicv2_main.c index c5d4fe1c3..c5bced00d 100644 --- a/drivers/arm/gic/v2/gicv2_main.c +++ b/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) { diff --git a/include/lib/el3_runtime/pubsub.h b/include/lib/el3_runtime/pubsub.h index eb9128656..9c303f548 100644 --- a/include/lib/el3_runtime/pubsub.h +++ b/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. */ diff --git a/include/lib/extensions/ras.h b/include/lib/extensions/ras.h index 9f6b2905f..98daab601 100644 --- a/include/lib/extensions/ras.h +++ b/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; diff --git a/lib/el3_runtime/aarch64/context.S b/lib/el3_runtime/aarch64/context.S index 4489e908b..4371cb2b2 100644 --- a/lib/el3_runtime/aarch64/context.S +++ b/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. * ----------------------------------------------------- */ diff --git a/make_helpers/defaults.mk b/make_helpers/defaults.mk index 819abcd18..be84f7791 100644 --- a/make_helpers/defaults.mk +++ b/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 diff --git a/plat/common/aarch64/platform_mp_stack.S b/plat/common/aarch64/platform_mp_stack.S index 972a118a4..f9780e80c 100644 --- a/plat/common/aarch64/platform_mp_stack.S +++ b/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. * -------------------------------------------------------------------- */