diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/auth-framework.rst | 6 | ||||
| -rw-r--r-- | docs/change-log.rst | 28 | ||||
| -rw-r--r-- | docs/coding-guidelines.rst | 9 | ||||
| -rw-r--r-- | docs/cpu-specific-build-macros.rst | 2 | ||||
| -rw-r--r-- | docs/firmware-design.rst | 50 | ||||
| -rw-r--r-- | docs/firmware-update.rst | 44 | ||||
| -rw-r--r-- | docs/interrupt-framework-design.rst | 6 | ||||
| -rw-r--r-- | docs/platform-compatibility-policy.rst | 2 | ||||
| -rw-r--r-- | docs/porting-guide.rst | 658 | ||||
| -rw-r--r-- | docs/psci-lib-integration-guide.rst | 102 | ||||
| -rw-r--r-- | docs/rt-svc-writers-guide.rst | 8 | ||||
| -rw-r--r-- | docs/trusted-board-boot.rst | 22 | ||||
| -rw-r--r-- | docs/user-guide.rst | 74 | ||||
| -rw-r--r-- | docs/xlat-tables-lib-v2-design.rst | 34 |
14 files changed, 522 insertions, 523 deletions
diff --git a/docs/auth-framework.rst b/docs/auth-framework.rst index e0b569f31..7e401b773 100644 --- a/docs/auth-framework.rst +++ b/docs/auth-framework.rst @@ -209,7 +209,7 @@ It is responsible for: #. Tracking which images have been verified. In case an image is a part of multiple CoTs then it should be verified only once e.g. the Trusted World Key Certificate in the TBBR-Client spec. contains information to verify - SCP\_BL2, BL31, BL32 each of which have a separate CoT. (This + SCP_BL2, BL31, BL32 each of which have a separate CoT. (This responsibility has not been described in this document but should be trivial to implement). @@ -627,7 +627,7 @@ The TBBR CoT The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of an array of image descriptors and it is registered in the framework using the macro -``REGISTER_COT(cot_desc)``, where 'cot\_desc' must be the name of the array +``REGISTER_COT(cot_desc)``, where 'cot_desc' must be the name of the array (passing a pointer or any other type of indirection will cause the registration process to fail). @@ -720,7 +720,7 @@ Example: the BL31 Chain of Trust Four image descriptors form the BL31 Chain of Trust: -.. code:: asm +.. code:: c [TRUSTED_KEY_CERT_ID] = { .img_id = TRUSTED_KEY_CERT_ID, diff --git a/docs/change-log.rst b/docs/change-log.rst index 73e6d726f..b0ef4221b 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -973,7 +973,7 @@ New features - Updated PSCI support: - - Added support for PSCI NODE\_HW\_STATE API for Arm platforms. + - Added support for PSCI NODE_HW_STATE API for Arm platforms. - New optional platform hook, ``pwr_domain_pwr_down_wfi()``, in ``plat_psci_ops`` to enable platforms to perform platform-specific actions @@ -1000,14 +1000,14 @@ New features This can be useful to map a non-cacheable memory region, such as a DMA buffer. - - Introduced the MT\_EXECUTE/MT\_EXECUTE\_NEVER memory mapping attributes to + - Introduced the MT_EXECUTE/MT_EXECUTE_NEVER memory mapping attributes to specify the access permissions for instruction execution of a memory region. - Enabled support to isolate code and read-only data on separate memory pages, allowing independent access control to be applied to each. -- Enabled SCR\_EL3.SIF (Secure Instruction Fetch) bit in BL1 and BL31 common +- Enabled SCR_EL3.SIF (Secure Instruction Fetch) bit in BL1 and BL31 common architectural setup code, preventing fetching instructions from non-secure memory when in secure state. @@ -1025,7 +1025,7 @@ New features the working directory. - Aligned command line options for specifying images to use same naming - convention as specified by TBBR and already used in cert\_create tool. + convention as specified by TBBR and already used in cert_create tool. - Refactored the TZC-400 driver to also support memory controllers that integrate TZC functionality, for example Arm CoreLink DMC-500. Also added @@ -1036,7 +1036,7 @@ New features - Enhanced support for Arm platforms: - - Updated image loading support to make SCP images (SCP\_BL2 and SCP\_BL2U) + - Updated image loading support to make SCP images (SCP_BL2 and SCP_BL2U) optional. - Enhanced topology description support to allow multi-cluster topology @@ -1104,7 +1104,7 @@ New features **Note** the default build of TF-A will not be able to boot Linux kernel with GICv2 FDT blob. - - Enabled wake-up from CPU\_SUSPEND to stand-by by temporarily re-routing + - Enabled wake-up from CPU_SUSPEND to stand-by by temporarily re-routing interrupts and then restoring after resume. Issues resolved since last release @@ -1219,7 +1219,7 @@ New features - Better alignment with version 1.0 of the PSCI specification. -- Added support for the SYSTEM\_SUSPEND PSCI API on Arm platforms. When invoked +- Added support for the SYSTEM_SUSPEND PSCI API on Arm platforms. When invoked on the last running core on a supported platform, this puts the system into a low power mode with memory retention. @@ -1615,7 +1615,7 @@ Known issues <SimName>System Generator:FVP_Base_A57x4_A53x4</SimName> to - System Generator:FVP\_Base\_Cortex-A57x4\_A53x4 + System Generator:FVP_Base_Cortex-A57x4_A53x4 A similar change can be made to the other Cortex-A57-A53 Base FVP variants. @@ -1643,7 +1643,7 @@ New features - Moved architectural timer setup to platform-specific code. -- Added standby state support to PSCI cpu\_suspend implementation. +- Added standby state support to PSCI cpu_suspend implementation. - SRAM usage improvements: @@ -1669,7 +1669,7 @@ New features default configuration is provided for the Base FVPs. This means the model parameter ``-C bp.secure_memory=1`` is now supported. -- Started saving the PSCI cpu\_suspend 'power\_state' parameter prior to +- Started saving the PSCI cpu_suspend 'power_state' parameter prior to suspending a CPU. This allows platforms that implement multiple power-down states at the same affinity level to identify a specific state. @@ -1767,13 +1767,13 @@ New features instructions for how to contribute and updated copyright text in all files to acknowledge contributors. -- The PSCI CPU\_SUSPEND API has been stabilised to the extent where it can be +- The PSCI CPU_SUSPEND API has been stabilised to the extent where it can be used for entry into power down states with the following restrictions: - Entry into standby states is not supported. - The API is only supported on the AEMv8 and Cortex-A57-A53 Base FVPs. -- The PSCI AFFINITY\_INFO api has undergone limited testing on the Base FVPs to +- The PSCI AFFINITY_INFO api has undergone limited testing on the Base FVPs to allow experimental use. - Required C library and runtime header files are now included locally in @@ -1803,7 +1803,7 @@ New features particular code modules to DRAM itself. - Reworked BL2 to BL3-1 handover interface. A new composite structure - (bl31\_args) holds the superset of information that needs to be passed from + (bl31_args) holds the superset of information that needs to be passed from BL2 to BL3-1, including information on how handover execution control to BL3-2 (if present) and BL3-3 (non-trusted firmware). @@ -1817,7 +1817,7 @@ New features - Added a framework for implementing EL3 runtime services. Reworked the PSCI implementation to be one such runtime service. -- Reworked the exception handling logic, making use of both SP\_EL0 and SP\_EL3 +- Reworked the exception handling logic, making use of both SP_EL0 and SP_EL3 stack pointers for determining the type of exception, managing general purpose and system register context on exception entry/exit, and handling SMCs. SMCs are directed to the correct EL3 runtime service. diff --git a/docs/coding-guidelines.rst b/docs/coding-guidelines.rst index d5ac97882..e8f365b36 100644 --- a/docs/coding-guidelines.rst +++ b/docs/coding-guidelines.rst @@ -85,7 +85,7 @@ file names; this type of name reuse should be otherwise avoided. #include "./a_header.h" Include statement variants -^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^ Two variants of the ``#include`` directive are acceptable in the TF codebase. Correct use of the two styles improves readability by suggesting the location @@ -125,7 +125,7 @@ Types and typedefs ------------------ Use of built-in *C* and *libc* data types -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The TF codebase should be kept as portable as possible, especially since both 64-bit and 32-bit platforms are supported. To help with this, the following data @@ -214,9 +214,8 @@ type usage guidelines should be followed: u_register_t arg7; } aapcs64_params_t; - - If some code wants to operate on ``arg0`` and knows that it represents a - 32-bit unsigned integer on all systems, cast it to ``unsigned int``. +If some code wants to operate on ``arg0`` and knows that it represents a 32-bit +unsigned integer on all systems, cast it to ``unsigned int``. These guidelines should be updated if additional types are needed. diff --git a/docs/cpu-specific-build-macros.rst b/docs/cpu-specific-build-macros.rst index 6a3635c6f..315457a19 100644 --- a/docs/cpu-specific-build-macros.rst +++ b/docs/cpu-specific-build-macros.rst @@ -93,7 +93,7 @@ For Cortex-A53, the following errata build flags are defined : - ``ERRATA_A53_855873``: This applies errata 855873 workaround to Cortex-A53 CPUs. Though the erratum is present in every revision of the CPU, this workaround is only applied to CPUs from r0p3 onwards, which feature - a chicken bit in CPUACTLR\_EL1 to enable a hardware workaround. + a chicken bit in CPUACTLR_EL1 to enable a hardware workaround. Earlier revisions of the CPU have other errata which require the same workaround in software, so they should be covered anyway. diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index 06fdbacdd..617cbb886 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -404,16 +404,16 @@ needed in the ``bl2_plat_handle_post_image_load()`` function. These configuration files can be passed to next Boot Loader stages as arguments by updating the corresponding entrypoint information in this function. -SCP\_BL2 (System Control Processor Firmware) image load -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +SCP_BL2 (System Control Processor Firmware) image load +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some systems have a separate System Control Processor (SCP) for power, clock, -reset and system control. BL2 loads the optional SCP\_BL2 image from platform +reset and system control. BL2 loads the optional SCP_BL2 image from platform storage into a platform-specific region of secure memory. The subsequent -handling of SCP\_BL2 is platform specific. For example, on the Juno Arm +handling of SCP_BL2 is platform specific. For example, on the Juno Arm development platform port the image is transferred into SCP's internal memory using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM -memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP) +memory. The SCP executes SCP_BL2 and signals to the Application Processor (AP) for BL2 execution to continue. EL3 Runtime Software image load @@ -688,7 +688,7 @@ Data structures used in the BL31 cold boot interface These structures are designed to support compatibility and independent evolution of the structures and the firmware images. For example, a version of BL31 that can interpret the BL3x image information from different versions of -BL2, a platform that uses an extended entry\_point\_info structure to convey +BL2, a platform that uses an extended entry_point_info structure to convey additional register information to BL31, or a ELF image loader that can convey more details about the firmware images. @@ -803,10 +803,10 @@ Required CPU state for warm boot initialization When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3 Runtime Software must ensure execution of a warm boot initialization entrypoint. -If TF-A BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build flag is false, +If TF-A BL1 is used and the PROGRAMMABLE_RESET_ADDRESS build flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches to the warm boot entrypoint by arranging for the BL1 platform function, -plat\_get\_my\_entrypoint(), to return a non-zero value. +plat_get_my_entrypoint(), to return a non-zero value. In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian data access and all interrupt sources masked: @@ -996,7 +996,7 @@ mandatory APIs in PSCI v1.1, PSCI v1.0 and in PSCI v0.2 draft specification `Power State Coordination Interface PDD`_ are implemented. The table lists the PSCI v1.1 APIs and their support in generic code. -An API implementation might have a dependency on platform code e.g. CPU\_SUSPEND +An API implementation might have a dependency on platform code e.g. CPU_SUSPEND requires the platform to export a part of the implementation. Hence the level of support of the mandatory APIs depends upon the support exported by the platform port as well. The Juno and FVP (all variants) platforms export all the @@ -1657,13 +1657,13 @@ The following list describes the memory layout on the Arm development platforms: - BL2 is loaded below BL1 RW -- EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP\_MIN), +- EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP_MIN), is loaded at the top of the Trusted SRAM, such that its NOBITS sections will overwrite BL1 R/W data and BL2. This implies that BL1 global variables remain valid only until execution reaches the EL3 Runtime Software entry point during a cold boot. -- On Juno, SCP\_BL2 is loaded temporarily into the EL3 Runtime Software memory +- On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory region and transfered to the SCP before being overwritten by EL3 Runtime Software. @@ -2089,11 +2089,11 @@ the update made by CPU0 as well. To use bakery locks when ``USE_COHERENT_MEM`` is disabled, the lock data structure has been redesigned. The changes utilise the characteristic of Lamport's Bakery -algorithm mentioned earlier. The bakery\_lock structure only allocates the memory +algorithm mentioned earlier. The bakery_lock structure only allocates the memory for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks needed for a CPU into a section ``bakery_lock``. The linker allocates the memory -for other cores by using the total size allocated for the bakery\_lock section -and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to +for other cores by using the total size allocated for the bakery_lock section +and multiplying it with (PLATFORM_CORE_COUNT - 1). This enables software to perform software cache maintenance on the lock data structure without running into coherency issues associated with mismatched attributes. @@ -2155,7 +2155,7 @@ with n bakery locks are: ------------------ Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an -operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1 +operation on Lock_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1 ``bakery_lock`` section need to be fetched and appropriate cache operations need to be performed for each access. @@ -2343,18 +2343,18 @@ A publisher that wants to publish event ``foo`` would: A subscriber that wants to subscribe to event ``foo`` published above would implement: -:: +.. code:: c - void *foo_handler(const void *arg) - { - void *result; + void *foo_handler(const void *arg) + { + void *result; - /* Do handling ... */ + /* Do handling ... */ - return result; - } + return result; + } - SUBSCRIBE_TO_EVENT(foo, foo_handler); + SUBSCRIBE_TO_EVENT(foo, foo_handler); Reclaiming the BL31 initialization code @@ -2619,8 +2619,8 @@ categories. Based upon the above, the code layout looks like this: lib Yes Yes Yes services No No Yes -The build system provides a non configurable build option IMAGE\_BLx for each -boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be +The build system provides a non configurable build option IMAGE_BLx for each +boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE_BL1 will be defined by the build system. This enables TF-A to compile certain code only for specific boot loader stages diff --git a/docs/firmware-update.rst b/docs/firmware-update.rst index 3ee57bcbb..1f07f7681 100644 --- a/docs/firmware-update.rst +++ b/docs/firmware-update.rst @@ -135,8 +135,8 @@ The following is a brief description of the supported states: BL1 SMC Interface ----------------- -BL1\_SMC\_CALL\_COUNT -~~~~~~~~~~~~~~~~~~~~~ +BL1_SMC_CALL_COUNT +~~~~~~~~~~~~~~~~~~ :: @@ -148,8 +148,8 @@ BL1\_SMC\_CALL\_COUNT This SMC returns the number of SMCs supported by BL1. -BL1\_SMC\_UID -~~~~~~~~~~~~~ +BL1_SMC_UID +~~~~~~~~~~~ :: @@ -162,8 +162,8 @@ BL1\_SMC\_UID This SMC returns the 128-bit `Universally Unique Identifier`_ for the BL1 SMC service. -BL1\_SMC\_VERSION -~~~~~~~~~~~~~~~~~ +BL1_SMC_VERSION +~~~~~~~~~~~~~~~ :: @@ -176,8 +176,8 @@ BL1\_SMC\_VERSION This SMC returns the current version of the BL1 SMC service. -BL1\_SMC\_RUN\_IMAGE -~~~~~~~~~~~~~~~~~~~~ +BL1_SMC_RUN_IMAGE +~~~~~~~~~~~~~~~~~ :: @@ -196,8 +196,8 @@ This SMC passes execution control to an EL3 image described by the provided ``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes this SMC for BL1 to pass execution control to BL31. -FWU\_SMC\_IMAGE\_COPY -~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_IMAGE_COPY +~~~~~~~~~~~~~~~~~~ :: @@ -245,8 +245,8 @@ contiguous memory. Once the SMC is handled, BL1 returns from exception to the normal world caller. -FWU\_SMC\_IMAGE\_AUTH -~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_IMAGE_AUTH +~~~~~~~~~~~~~~~~~~ :: @@ -285,8 +285,8 @@ BL1 returns from exception to the caller. If authentication succeeds then BL1 sets the image state to AUTHENTICATED. If authentication fails then BL1 returns the -EAUTH error and sets the image state back to RESET. -FWU\_SMC\_IMAGE\_EXECUTE -~~~~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_IMAGE_EXECUTE +~~~~~~~~~~~~~~~~~~~~~ :: @@ -313,8 +313,8 @@ secure world image. BL1 saves the normal world caller's context, sets the secure image state to EXECUTED, and returns from exception to the secure image. -FWU\_SMC\_IMAGE\_RESUME -~~~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_IMAGE_RESUME +~~~~~~~~~~~~~~~~~~~~ :: @@ -340,8 +340,8 @@ the resuming world. If the call is successful then the caller provided ``image_param`` is returned to the resumed world, otherwise an error code is returned to the caller. -FWU\_SMC\_SEC\_IMAGE\_DONE -~~~~~~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_SEC_IMAGE_DONE +~~~~~~~~~~~~~~~~~~~~~~ :: @@ -361,8 +361,8 @@ BL1 sets the previously executing secure image state to the RESET state, restores the normal world context and returns from exception into the normal world. -FWU\_SMC\_UPDATE\_DONE -~~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_UPDATE_DONE +~~~~~~~~~~~~~~~~~~~ :: @@ -377,8 +377,8 @@ This SMC completes the firmware update process. BL1 calls the platform specific function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as a ``void *``. The SMC does not return. -FWU\_SMC\_IMAGE\_RESET -~~~~~~~~~~~~~~~~~~~~~~ +FWU_SMC_IMAGE_RESET +~~~~~~~~~~~~~~~~~~~ :: diff --git a/docs/interrupt-framework-design.rst b/docs/interrupt-framework-design.rst index 4247f1f08..52d1ed41b 100644 --- a/docs/interrupt-framework-design.rst +++ b/docs/interrupt-framework-design.rst @@ -451,7 +451,7 @@ requirements mentioned earlier. The handover agreement between the TSP and the TSPD requires that the TSPD masks all interrupts (``PSTATE.DAIF`` bits) when it calls ``tsp_sel1_intr_entry()``. The TSP has to preserve the callee saved general - purpose, SP\_EL1/Secure-EL0, LR, VFP and system registers. It can use + purpose, SP_EL1/Secure-EL0, LR, VFP and system registers. It can use ``x0-x18`` to enable its C runtime. #. The TSPD implements a handler function for Secure-EL1 interrupts. This @@ -595,7 +595,7 @@ The TSP also replaces the default exception vector table referenced through the ``early_exceptions`` variable, with a vector table capable of handling FIQ and IRQ exceptions taken at the same (Secure-EL1) exception level. This table is referenced through the ``tsp_exceptions`` variable and programmed into the -VBAR\_EL1. It caters for the asynchronous handling model. +VBAR_EL1. It caters for the asynchronous handling model. The TSP also programs the Secure Physical Timer in the Arm Generic Timer block to raise a periodic interrupt (every half a second) for the purpose of testing @@ -904,7 +904,7 @@ In the synchronous model, it should begin handling a Secure-EL1 interrupt after receiving control from the SPD service at an entrypoint agreed upon during build time or during the registration phase. Before handling the interrupt, the SP should save any Secure-EL1 system register context which is needed for resuming -normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR\_EL1\`. After handling the +normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR_EL1\`. After handling the interrupt, the SP could return control back to the exception level and security state where the interrupt was originally taken from. The SP should use an SMC32 or SMC64 to ask the SPD service to do this. diff --git a/docs/platform-compatibility-policy.rst b/docs/platform-compatibility-policy.rst index d7e13ad89..6bab447ee 100644 --- a/docs/platform-compatibility-policy.rst +++ b/docs/platform-compatibility-policy.rst @@ -1,5 +1,5 @@ TF-A Platform Compatibility Policy -====================================================== +================================== .. section-numbering:: diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index d3f3b298d..7c2a4d419 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -28,7 +28,7 @@ effort. Each platform port can override them with its own implementation if the default implementation is inadequate. Platform ports that want to be aligned with standard Arm platforms (for example -FVP and Juno) may also use `include/plat/arm/common/plat\_arm.h`_ and the +FVP and Juno) may also use `include/plat/arm/common/plat_arm.h`_ and the corresponding source files in ``plat/arm/common/``. These provide standard implementations for some of the required platform porting functions. However, using these functions requires the platform port to implement additional @@ -99,56 +99,56 @@ and caches disabled. Examples are given below. The following variables, functions and constants must be defined by the platform for the firmware to work correctly. -File : platform\_def.h [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +File : platform_def.h [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each platform must ensure that a header file of this name is in the system include path with the following constants defined. This will require updating the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. -Platform ports may optionally use the file `include/plat/common/common\_def.h`_, +Platform ports may optionally use the file `include/plat/common/common_def.h`_, which provides typical values for some of the constants below. These values are likely to be suitable for all platform ports. -- **#define : PLATFORM\_LINKER\_FORMAT** +- **#define : PLATFORM_LINKER_FORMAT** Defines the linker format used by the platform, for example ``elf64-littleaarch64``. -- **#define : PLATFORM\_LINKER\_ARCH** +- **#define : PLATFORM_LINKER_ARCH** Defines the processor architecture for the linker by the platform, for example ``aarch64``. -- **#define : PLATFORM\_STACK\_SIZE** +- **#define : PLATFORM_STACK_SIZE** Defines the normal stack memory available to each CPU. This constant is used - by `plat/common/aarch64/platform\_mp\_stack.S`_ and - `plat/common/aarch64/platform\_up\_stack.S`_. + by `plat/common/aarch64/platform_mp_stack.S`_ and + `plat/common/aarch64/platform_up_stack.S`_. -- **define : CACHE\_WRITEBACK\_GRANULE** +- **define : CACHE_WRITEBACK_GRANULE** Defines the size in bits of the largest cache line across all the cache levels in the platform. -- **#define : FIRMWARE\_WELCOME\_STR** +- **#define : FIRMWARE_WELCOME_STR** Defines the character string printed by BL1 upon entry into the ``bl1_main()`` function. -- **#define : PLATFORM\_CORE\_COUNT** +- **#define : PLATFORM_CORE_COUNT** Defines the total number of CPUs implemented by the platform across all clusters in the system. -- **#define : PLAT\_NUM\_PWR\_DOMAINS** +- **#define : PLAT_NUM_PWR_DOMAINS** Defines the total number of nodes in the power domain topology tree at all the power domain levels used by the platform. This macro is used by the PSCI implementation to allocate data structures to represent power domain topology. -- **#define : PLAT\_MAX\_PWR\_LVL** +- **#define : PLAT_MAX_PWR_LVL** Defines the maximum power domain level that the power management operations should apply to. More often, but not always, the power domain level @@ -158,24 +158,24 @@ likely to be suitable for all platform ports. example, the Base AEM FVP implements two clusters with a configurable number of CPUs and it reports the maximum power domain level as 1. -- **#define : PLAT\_MAX\_OFF\_STATE** +- **#define : PLAT_MAX_OFF_STATE** Defines the local power state corresponding to the deepest power down possible at every power domain level in the platform. The local power states for each level may be sparsely allocated between 0 and this value with 0 being reserved for the RUN state. The PSCI implementation uses this value to initialize the local power states of the power domain nodes and - to specify the requested power state for a PSCI\_CPU\_OFF call. + to specify the requested power state for a PSCI_CPU_OFF call. -- **#define : PLAT\_MAX\_RET\_STATE** +- **#define : PLAT_MAX_RET_STATE** Defines the local power state corresponding to the deepest retention state possible at every power domain level in the platform. This macro should be - a value less than PLAT\_MAX\_OFF\_STATE and greater than 0. It is used by the + a value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by the PSCI implementation to distinguish between retention and power down local - power states within PSCI\_CPU\_SUSPEND call. + power states within PSCI_CPU_SUSPEND call. -- **#define : PLAT\_MAX\_PWR\_LVL\_STATES** +- **#define : PLAT_MAX_PWR_LVL_STATES** Defines the maximum number of local power states per power domain level that the platform supports. The default value of this macro is 2 since @@ -184,69 +184,69 @@ likely to be suitable for all platform ports. account for more local power states, then it must redefine this macro. Currently, this macro is used by the Generic PSCI implementation to size - the array used for PSCI\_STAT\_COUNT/RESIDENCY accounting. + the array used for PSCI_STAT_COUNT/RESIDENCY accounting. -- **#define : BL1\_RO\_BASE** +- **#define : BL1_RO_BASE** Defines the base address in secure ROM where BL1 originally lives. Must be aligned on a page-size boundary. -- **#define : BL1\_RO\_LIMIT** +- **#define : BL1_RO_LIMIT** Defines the maximum address in secure ROM that BL1's actual content (i.e. excluding any data section allocated at runtime) can occupy. -- **#define : BL1\_RW\_BASE** +- **#define : BL1_RW_BASE** Defines the base address in secure RAM where BL1's read-write data will live at runtime. Must be aligned on a page-size boundary. -- **#define : BL1\_RW\_LIMIT** +- **#define : BL1_RW_LIMIT** Defines the maximum address in secure RAM that BL1's read-write data can occupy at runtime. -- **#define : BL2\_BASE** +- **#define : BL2_BASE** Defines the base address in secure RAM where BL1 loads the BL2 binary image. Must be aligned on a page-size boundary. This constant is not applicable when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL2\_LIMIT** +- **#define : BL2_LIMIT** Defines the maximum address in secure RAM that the BL2 image can occupy. This constant is not applicable when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL2\_RO\_BASE** +- **#define : BL2_RO_BASE** Defines the base address in secure XIP memory where BL2 RO section originally lives. Must be aligned on a page-size boundary. This constant is only needed when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL2\_RO\_LIMIT** +- **#define : BL2_RO_LIMIT** Defines the maximum address in secure XIP memory that BL2's actual content (i.e. excluding any data section allocated at runtime) can occupy. This constant is only needed when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL2\_RW\_BASE** +- **#define : BL2_RW_BASE** Defines the base address in secure RAM where BL2's read-write data will live at runtime. Must be aligned on a page-size boundary. This constant is only needed when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL2\_RW\_LIMIT** +- **#define : BL2_RW_LIMIT** Defines the maximum address in secure RAM that BL2's read-write data can occupy at runtime. This constant is only needed when BL2_IN_XIP_MEM is set to '1'. -- **#define : BL31\_BASE** +- **#define : BL31_BASE** Defines the base address in secure RAM where BL2 loads the BL31 binary image. Must be aligned on a page-size boundary. -- **#define : BL31\_LIMIT** +- **#define : BL31_LIMIT** Defines the maximum address in secure RAM that the BL31 image can occupy. @@ -258,57 +258,57 @@ information about the image to be loaded (file handler, load address, authentication information, etc.). The following image identifiers are mandatory: -- **#define : BL2\_IMAGE\_ID** +- **#define : BL2_IMAGE_ID** BL2 image identifier, used by BL1 to load BL2. -- **#define : BL31\_IMAGE\_ID** +- **#define : BL31_IMAGE_ID** BL31 image identifier, used by BL2 to load BL31. -- **#define : BL33\_IMAGE\_ID** +- **#define : BL33_IMAGE_ID** BL33 image identifier, used by BL2 to load BL33. If Trusted Board Boot is enabled, the following certificate identifiers must also be defined: -- **#define : TRUSTED\_BOOT\_FW\_CERT\_ID** +- **#define : TRUSTED_BOOT_FW_CERT_ID** BL2 content certificate identifier, used by BL1 to load the BL2 content certificate. -- **#define : TRUSTED\_KEY\_CERT\_ID** +- **#define : TRUSTED_KEY_CERT_ID** Trusted key certificate identifier, used by BL2 to load the trusted key certificate. -- **#define : SOC\_FW\_KEY\_CERT\_ID** +- **#define : SOC_FW_KEY_CERT_ID** BL31 key certificate identifier, used by BL2 to load the BL31 key certificate. -- **#define : SOC\_FW\_CONTENT\_CERT\_ID** +- **#define : SOC_FW_CONTENT_CERT_ID** BL31 content certificate identifier, used by BL2 to load the BL31 content certificate. -- **#define : NON\_TRUSTED\_FW\_KEY\_CERT\_ID** +- **#define : NON_TRUSTED_FW_KEY_CERT_ID** BL33 key certificate identifier, used by BL2 to load the BL33 key certificate. -- **#define : NON\_TRUSTED\_FW\_CONTENT\_CERT\_ID** +- **#define : NON_TRUSTED_FW_CONTENT_CERT_ID** BL33 content certificate identifier, used by BL2 to load the BL33 content certificate. -- **#define : FWU\_CERT\_ID** +- **#define : FWU_CERT_ID** - Firmware Update (FWU) certificate identifier, used by NS\_BL1U to load the + Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the FWU content certificate. -- **#define : PLAT\_CRYPTOCELL\_BASE** +- **#define : PLAT_CRYPTOCELL_BASE** This defines the base address of Arm® TrustZone® CryptoCell and must be defined if CryptoCell crypto driver is used for Trusted Board Boot. For @@ -318,125 +318,125 @@ also be defined: If the AP Firmware Updater Configuration image, BL2U is used, the following must also be defined: -- **#define : BL2U\_BASE** +- **#define : BL2U_BASE** Defines the base address in secure memory where BL1 copies the BL2U binary image. Must be aligned on a page-size boundary. -- **#define : BL2U\_LIMIT** +- **#define : BL2U_LIMIT** Defines the maximum address in secure memory that the BL2U image can occupy. -- **#define : BL2U\_IMAGE\_ID** +- **#define : BL2U_IMAGE_ID** BL2U image identifier, used by BL1 to fetch an image descriptor corresponding to BL2U. -If the SCP Firmware Update Configuration Image, SCP\_BL2U is used, the following +If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following must also be defined: -- **#define : SCP\_BL2U\_IMAGE\_ID** +- **#define : SCP_BL2U_IMAGE_ID** - SCP\_BL2U image identifier, used by BL1 to fetch an image descriptor - corresponding to SCP\_BL2U. + SCP_BL2U image identifier, used by BL1 to fetch an image descriptor + corresponding to SCP_BL2U. NOTE: TF-A does not provide source code for this image. -If the Non-Secure Firmware Updater ROM, NS\_BL1U is used, the following must +If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must also be defined: -- **#define : NS\_BL1U\_BASE** +- **#define : NS_BL1U_BASE** - Defines the base address in non-secure ROM where NS\_BL1U executes. + Defines the base address in non-secure ROM where NS_BL1U executes. Must be aligned on a page-size boundary. NOTE: TF-A does not provide source code for this image. -- **#define : NS\_BL1U\_IMAGE\_ID** +- **#define : NS_BL1U_IMAGE_ID** - NS\_BL1U image identifier, used by BL1 to fetch an image descriptor - corresponding to NS\_BL1U. + NS_BL1U image identifier, used by BL1 to fetch an image descriptor + corresponding to NS_BL1U. -If the Non-Secure Firmware Updater, NS\_BL2U is used, the following must also +If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also be defined: -- **#define : NS\_BL2U\_BASE** +- **#define : NS_BL2U_BASE** - Defines the base address in non-secure memory where NS\_BL2U executes. + Defines the base address in non-secure memory where NS_BL2U executes. Must be aligned on a page-size boundary. NOTE: TF-A does not provide source code for this image. -- **#define : NS\_BL2U\_IMAGE\_ID** +- **#define : NS_BL2U_IMAGE_ID** - NS\_BL2U image identifier, used by BL1 to fetch an image descriptor - corresponding to NS\_BL2U. + NS_BL2U image identifier, used by BL1 to fetch an image descriptor + corresponding to NS_BL2U. For the the Firmware update capability of TRUSTED BOARD BOOT, the following macros may also be defined: -- **#define : PLAT\_FWU\_MAX\_SIMULTANEOUS\_IMAGES** +- **#define : PLAT_FWU_MAX_SIMULTANEOUS_IMAGES** Total number of images that can be loaded simultaneously. If the platform doesn't specify any value, it defaults to 10. -If a SCP\_BL2 image is supported by the platform, the following constants must +If a SCP_BL2 image is supported by the platform, the following constants must also be defined: -- **#define : SCP\_BL2\_IMAGE\_ID** +- **#define : SCP_BL2_IMAGE_ID** - SCP\_BL2 image identifier, used by BL2 to load SCP\_BL2 into secure memory + SCP_BL2 image identifier, used by BL2 to load SCP_BL2 into secure memory from platform storage before being transferred to the SCP. -- **#define : SCP\_FW\_KEY\_CERT\_ID** +- **#define : SCP_FW_KEY_CERT_ID** - SCP\_BL2 key certificate identifier, used by BL2 to load the SCP\_BL2 key + SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 key certificate (mandatory when Trusted Board Boot is enabled). -- **#define : SCP\_FW\_CONTENT\_CERT\_ID** +- **#define : SCP_FW_CONTENT_CERT_ID** - SCP\_BL2 content certificate identifier, used by BL2 to load the SCP\_BL2 + SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2 content certificate (mandatory when Trusted Board Boot is enabled). If a BL32 image is supported by the platform, the following constants must also be defined: -- **#define : BL32\_IMAGE\_ID** +- **#define : BL32_IMAGE_ID** BL32 image identifier, used by BL2 to load BL32. -- **#define : TRUSTED\_OS\_FW\_KEY\_CERT\_ID** +- **#define : TRUSTED_OS_FW_KEY_CERT_ID** BL32 key certificate identifier, used by BL2 to load the BL32 key certificate (mandatory when Trusted Board Boot is enabled). -- **#define : TRUSTED\_OS\_FW\_CONTENT\_CERT\_ID** +- **#define : TRUSTED_OS_FW_CONTENT_CERT_ID** BL32 content certificate identifier, used by BL2 to load the BL32 content certificate (mandatory when Trusted Board Boot is enabled). -- **#define : BL32\_BASE** +- **#define : BL32_BASE** Defines the base address in secure memory where BL2 loads the BL32 binary image. Must be aligned on a page-size boundary. -- **#define : BL32\_LIMIT** +- **#define : BL32_LIMIT** Defines the maximum address that the BL32 image can occupy. If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the platform, the following constants must also be defined: -- **#define : TSP\_SEC\_MEM\_BASE** +- **#define : TSP_SEC_MEM_BASE** Defines the base address of the secure memory used by the TSP image on the platform. This must be at the same address or below ``BL32_BASE``. -- **#define : TSP\_SEC\_MEM\_SIZE** +- **#define : TSP_SEC_MEM_SIZE** Defines the size of the secure memory used by the BL32 image on the platform. ``TSP_SEC_MEM_BASE`` and ``TSP_SEC_MEM_SIZE`` must fully accommodate the memory required by the BL32 image, defined by ``BL32_BASE`` and ``BL32_LIMIT``. -- **#define : TSP\_IRQ\_SEC\_PHY\_TIMER** +- **#define : TSP_IRQ_SEC_PHY_TIMER** Defines the ID of the secure physical generic timer interrupt used by the TSP's interrupt handling code. @@ -444,14 +444,14 @@ platform, the following constants must also be defined: If the platform port uses the translation table library code, the following constants must also be defined: -- **#define : PLAT\_XLAT\_TABLES\_DYNAMIC** +- **#define : PLAT_XLAT_TABLES_DYNAMIC** Optional flag that can be set per-image to enable the dynamic allocation of regions even when the MMU is enabled. If not defined, only static functionality will be available, if defined and set to 1 it will also include the dynamic functionality. -- **#define : MAX\_XLAT\_TABLES** +- **#define : MAX_XLAT_TABLES** Defines the maximum number of translation tables that are allocated by the translation table library code. To minimize the amount of runtime memory @@ -460,7 +460,7 @@ constants must also be defined: image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions as well. -- **#define : MAX\_MMAP\_REGIONS** +- **#define : MAX_MMAP_REGIONS** Defines the maximum number of regions that are allocated by the translation table library code. A region consists of physical base address, virtual base @@ -473,12 +473,12 @@ constants must also be defined: enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate the dynamic regions as well. -- **#define : PLAT\_VIRT\_ADDR\_SPACE\_SIZE** +- **#define : PLAT_VIRT_ADDR_SPACE_SIZE** Defines the total size of the virtual address space in bytes. For example, for a 32 bit virtual address space, this value should be ``(1ULL << 32)``. -- **#define : PLAT\_PHY\_ADDR\_SPACE\_SIZE** +- **#define : PLAT_PHY_ADDR_SPACE_SIZE** Defines the total size of the physical address space in bytes. For example, for a 32 bit physical address space, this value should be ``(1ULL << 32)``. @@ -486,22 +486,22 @@ constants must also be defined: If the platform port uses the IO storage framework, the following constants must also be defined: -- **#define : MAX\_IO\_DEVICES** +- **#define : MAX_IO_DEVICES** Defines the maximum number of registered IO devices. Attempting to register more devices than this value using ``io_register_device()`` will fail with -ENOMEM. -- **#define : MAX\_IO\_HANDLES** +- **#define : MAX_IO_HANDLES** Defines the maximum number of open IO handles. Attempting to open more IO entities than this value using ``io_open()`` will fail with -ENOMEM. -- **#define : MAX\_IO\_BLOCK\_DEVICES** +- **#define : MAX_IO_BLOCK_DEVICES** Defines the maximum number of registered IO block devices. Attempting to register more devices this value using ``io_dev_open()`` will fail - with -ENOMEM. MAX\_IO\_BLOCK\_DEVICES should be less than MAX\_IO\_DEVICES. + with -ENOMEM. MAX_IO_BLOCK_DEVICES should be less than MAX_IO_DEVICES. With this macro, multiple block devices could be supported at the same time. @@ -511,7 +511,7 @@ 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. -- **#define : PLAT\_PCPU\_DATA\_SIZE** +- **#define : PLAT_PCPU_DATA_SIZE** Defines the memory (in bytes) to be reserved within the per-cpu data structure for use by the platform layer. @@ -519,39 +519,39 @@ required memory within the the per-cpu data to minimize wastage. The following constants are optional. They should be defined when the platform memory layout implies some image overlaying like in Arm standard platforms. -- **#define : BL31\_PROGBITS\_LIMIT** +- **#define : BL31_PROGBITS_LIMIT** Defines the maximum address in secure RAM that the BL31's progbits sections can occupy. -- **#define : TSP\_PROGBITS\_LIMIT** +- **#define : TSP_PROGBITS_LIMIT** Defines the maximum address that the TSP's progbits sections can occupy. If the platform port uses the PL061 GPIO driver, the following constant may optionally be defined: -- **PLAT\_PL061\_MAX\_GPIOS** +- **PLAT_PL061_MAX_GPIOS** Maximum number of GPIOs required by the platform. This allows control how much memory is allocated for PL061 GPIO controllers. The default value is - #. $(eval $(call add\_define,PLAT\_PL061\_MAX\_GPIOS)) + #. $(eval $(call add_define,PLAT_PL061_MAX_GPIOS)) If the platform port uses the partition driver, the following constant may optionally be defined: -- **PLAT\_PARTITION\_MAX\_ENTRIES** +- **PLAT_PARTITION_MAX_ENTRIES** Maximum number of partition entries required by the platform. This allows control how much memory is allocated for partition entries. The default value is 128. `For example, define the build flag in platform.mk`_: - PLAT\_PARTITION\_MAX\_ENTRIES := 12 - $(eval $(call add\_define,PLAT\_PARTITION\_MAX\_ENTRIES)) + PLAT_PARTITION_MAX_ENTRIES := 12 + $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES)) The following constant is optional. It should be defined to override the default behaviour of the ``assert()`` function (for example, to save memory). -- **PLAT\_LOG\_LEVEL\_ASSERT** +- **PLAT_LOG_LEVEL_ASSERT** If ``PLAT_LOG_LEVEL_ASSERT`` is higher or equal than ``LOG_LEVEL_VERBOSE``, ``assert()`` prints the name of the file, the line number and the asserted expression. Else if it is higher than ``LOG_LEVEL_INFO``, it prints the file @@ -562,27 +562,27 @@ behaviour of the ``assert()`` function (for example, to save memory). If the platform port uses the Activity Monitor Unit, the following constants may be defined: -- **PLAT\_AMU\_GROUP1\_COUNTERS\_MASK** +- **PLAT_AMU_GROUP1_COUNTERS_MASK** This mask reflects the set of group counters that should be enabled. The maximum number of group 1 counters supported by AMUv1 is 16 so the mask can be at most 0xffff. If the platform does not define this mask, no group 1 counters are enabled. If the platform defines this mask, the following constant needs to also be defined. -- **PLAT\_AMU\_GROUP1\_NR\_COUNTERS** +- **PLAT_AMU_GROUP1_NR_COUNTERS** This value is used to allocate an array to save and restore the counters specified by ``PLAT_AMU_GROUP1_COUNTERS_MASK`` on CPU suspend. This value should be equal to the highest bit position set in the mask, plus 1. The maximum number of group 1 counters in AMUv1 is 16. -File : plat\_macros.S [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +File : plat_macros.S [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each platform must ensure a file of this name is in the system include path with the following macro defined. In the Arm development platforms, this file is found in ``plat/arm/board/<plat_name>/include/plat_macros.S``. -- **Macro : plat\_crash\_print\_regs** +- **Macro : plat_crash_print_regs** This macro allows the crash reporting routine to print relevant platform registers in case of an unhandled exception in BL31. This aids in debugging @@ -614,8 +614,8 @@ For each CPU, the reset vector code is responsible for the following tasks: The following functions need to be implemented by the platform port to enable reset vector code to perform the above tasks. -Function : plat\_get\_my\_entrypoint() [mandatory when PROGRAMMABLE\_RESET\_ADDRESS == 0] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_my_entrypoint() [mandatory when PROGRAMMABLE_RESET_ADDRESS == 0] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -642,8 +642,8 @@ both on a cold and warm reset. In this case, there is no need to identify the type of reset nor to query the warm reset entrypoint. Therefore, implementing this function is not required on such platforms. -Function : plat\_secondary\_cold\_boot\_setup() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_secondary_cold_boot_setup() [mandatory when COLD_BOOT_SINGLE_CPU == 0] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -666,8 +666,8 @@ Note that for platforms that can't release secondary CPUs out of reset, only the primary CPU will execute the cold boot code. Therefore, implementing this function is not required on such platforms. -Function : plat\_is\_my\_cpu\_primary() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_is_my_cpu_primary() [mandatory when COLD_BOOT_SINGLE_CPU == 0] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -684,8 +684,8 @@ primary CPU will execute the cold boot code. Therefore, there is no need to distinguish between primary and secondary CPUs and implementing this function is not required. -Function : platform\_mem\_init() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : platform_mem_init() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -695,8 +695,8 @@ Function : platform\_mem\_init() [mandatory] This function is called before any access to data is made by the firmware, in order to carry out any essential memory initialization. -Function: plat\_get\_rotpk\_info() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function: plat_get_rotpk_info() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -745,8 +745,8 @@ to the ROTPK in the flags parameter: verifying it against the platform value. This flag must not be used in a deployed production environment. -Function: plat\_get\_nv\_ctr() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function: plat_get_nv_ctr() +~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -758,13 +758,13 @@ non-volatile counter value stored in the platform in the second argument. The cookie in the first argument may be used to select the counter in case the platform provides more than one (for example, on platforms that use the default TBBR CoT, the cookie will correspond to the OID values defined in -TRUSTED\_FW\_NVCOUNTER\_OID or NON\_TRUSTED\_FW\_NVCOUNTER\_OID). +TRUSTED_FW_NVCOUNTER_OID or NON_TRUSTED_FW_NVCOUNTER_OID). The function returns 0 on success. Any other value means the counter value could not be retrieved from the platform. -Function: plat\_set\_nv\_ctr() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function: plat_set_nv_ctr() +~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -773,14 +773,14 @@ Function: plat\_set\_nv\_ctr() This function is mandatory when Trusted Board Boot is enabled. It sets a new counter value in the platform. The cookie in the first argument may be used to -select the counter (as explained in plat\_get\_nv\_ctr()). The second argument is +select the counter (as explained in plat_get_nv_ctr()). The second argument is the updated counter value to be written to the NV counter. The function returns 0 on success. Any other value means the counter value could not be updated. -Function: plat\_set\_nv\_ctr2() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function: plat_set_nv_ctr2() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -806,8 +806,8 @@ Common mandatory function modifications The following functions are mandatory functions which need to be implemented by the platform port. -Function : plat\_my\_core\_pos() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_my_core_pos() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -825,8 +825,8 @@ x9 - x29. This function plays a crucial role in the power domain topology framework in PSCI and details of this can be found in `Power Domain Topology Design`_. -Function : plat\_core\_pos\_by\_mpidr() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_core_pos_by_mpidr() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -848,8 +848,8 @@ The following are helper functions implemented by the firmware that perform common platform-specific tasks. A platform may choose to override these definitions. -Function : plat\_set\_my\_stack() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_set_my_stack() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -863,11 +863,11 @@ of the stack allocated to each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``. Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform\_up\_stack.S`_ and -`plat/common/aarch64/platform\_mp\_stack.S`_ +provided in `plat/common/aarch64/platform_up_stack.S`_ and +`plat/common/aarch64/platform_mp_stack.S`_ -Function : plat\_get\_my\_stack() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_my_stack() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -881,11 +881,11 @@ of the stack allocated to each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``. Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform\_up\_stack.S`_ and -`plat/common/aarch64/platform\_mp\_stack.S`_ +provided in `plat/common/aarch64/platform_up_stack.S`_ and +`plat/common/aarch64/platform_mp_stack.S`_ -Function : plat\_report\_exception() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_report_exception() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -905,15 +905,15 @@ about the way the platform displays its status information. For AArch64, this function receives the exception type as its argument. Possible values for exceptions types are listed in the -`include/common/bl\_common.h`_ header file. Note that these constants are not +`include/common/bl_common.h`_ header file. Note that these constants are not related to any architectural exception code; they are just a TF-A convention. For AArch32, this function receives the exception mode as its argument. Possible values for exception modes are listed in the `include/lib/aarch32/arch.h`_ header file. -Function : plat\_reset\_handler() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_reset_handler() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -929,8 +929,8 @@ The default implementation doesn't do anything. If a platform needs to override the default implementation, refer to the `Firmware Design`_ for general guidelines. -Function : plat\_disable\_acp() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_disable_acp() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -944,8 +944,8 @@ it has restrictions for stack usage and it can use the registers x0 - x17 as scratch registers. It should preserve the value in x18 register as it is used by the caller to store the return address. -Function : plat\_error\_handler() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_error_handler() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -968,8 +968,8 @@ Possible errors reported by the generic code are: The default implementation simply spins. -Function : plat\_panic\_handler() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_panic_handler() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -984,8 +984,8 @@ environment is initialized. Note: The address from where it was called is stored in x30 (Link Register). The default implementation simply spins. -Function : plat\_get\_bl\_image\_load\_info() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_bl_image_load_info() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -996,8 +996,8 @@ This function returns pointer to the list of images that the platform has populated to load. This function is invoked in BL2 to load the BL3xx images. -Function : plat\_get\_next\_bl\_params() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_next_bl_params() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1009,8 +1009,8 @@ kept aside to pass TF-A related information that next BL image needs. This function is invoked in BL2 to pass this information to the next BL image. -Function : plat\_get\_stack\_protector\_canary() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_stack_protector_canary() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1018,7 +1018,7 @@ Function : plat\_get\_stack\_protector\_canary() Return : u_register_t This function returns a random value that is used to initialize the canary used -when the stack protector is enabled with ENABLE\_STACK\_PROTECTOR. A predictable +when the stack protector is enabled with ENABLE_STACK_PROTECTOR. A predictable value will weaken the protection as the attacker could easily write the right value as part of the attack most of the time. Therefore, it should return a true random number. @@ -1027,8 +1027,8 @@ Note: For the protection to be effective, the global data need to be placed at a lower address than the stack bases. Failure to do so would allow an attacker to overwrite the canary as part of the stack buffer overflow attack. -Function : plat\_flush\_next\_bl\_params() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_flush_next_bl_params() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1039,8 +1039,8 @@ This function flushes to main memory all the image params that are passed to next image. This function is invoked in BL2 to flush this information to the next BL image. -Function : plat\_log\_get\_prefix() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_log_get_prefix() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1054,8 +1054,8 @@ can override the common implementation to define a different prefix string for the log output. The implementation should be robust to future changes that increase the number of log levels. -Function : plat\_get\_mbedtls\_heap() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_mbedtls_heap() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1116,8 +1116,8 @@ warm boot. For each CPU, BL1 is responsible for the following tasks: The following functions need to be implemented by the platform port to enable BL1 to perform the above tasks. -Function : bl1\_early\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_early_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1138,8 +1138,8 @@ On Arm standard platforms, this function: the CCI slave interface corresponding to the cluster that includes the primary CPU. -Function : bl1\_plat\_arch\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_arch_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1154,8 +1154,8 @@ In Arm standard platforms, this function enables the MMU. This function helps fulfill requirement 2 above. -Function : bl1\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1167,15 +1167,15 @@ for performing any remaining platform-specific setup that can occur after the MMU and data cache have been enabled. if support for multiple boot sources is required, it initializes the boot -sequence used by plat\_try\_next\_boot\_source(). +sequence used by plat_try_next_boot_source(). In Arm standard platforms, this function initializes the storage abstraction layer used to load the next bootloader image. This function helps fulfill requirement 4 above. -Function : bl1\_plat\_sec\_mem\_layout() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_sec_mem_layout() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1198,8 +1198,8 @@ its own use. This function helps fulfill requirements 4 and 5 above. -Function : bl1\_plat\_prepare\_exit() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_prepare_exit() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1212,8 +1212,8 @@ platform specific clean up or bookkeeping operations before transferring control to the next image. It receives the address of the ``entry_point_info_t`` structure passed from BL2. This function runs with MMU disabled. -Function : bl1\_plat\_set\_ep\_info() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_set_ep_info() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1224,8 +1224,8 @@ This function allows platforms to override ``ep_info`` for the given ``image_id` The default implementation just returns. -Function : bl1\_plat\_get\_next\_image\_id() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_get_next_image_id() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1243,8 +1243,8 @@ The default implementation always returns ``BL2_IMAGE_ID``. The Arm development platforms override this function to detect if firmware update is required, and if so, return the first image in the firmware update process. -Function : bl1\_plat\_get\_image\_desc() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_get_image_desc() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1259,8 +1259,8 @@ standard platforms return an image descriptor corresponding to BL2 or one of the firmware update images defined in the Trusted Board Boot Requirements specification. -Function : bl1\_plat\_handle\_pre\_image\_load() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_handle_pre_image_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1271,8 +1271,8 @@ This function can be used by the platforms to update/use image information corresponding to ``image_id``. This function is invoked in BL1, both in cold boot and FWU code path, before loading the image. -Function : bl1\_plat\_handle\_post\_image\_load() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_handle_post_image_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1289,8 +1289,8 @@ structure at the beginning of this free memory and populates it. The address of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint information to BL2. -Function : bl1\_plat\_fwu\_done() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_fwu_done() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1304,8 +1304,8 @@ example to initiate the normal boot flow. The default implementation spins forever. -Function : bl1\_plat\_mem\_check() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl1_plat_mem_check() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1342,8 +1342,8 @@ images to be passed to the next BL image. The following functions must be implemented by the platform port to enable BL2 to perform the above tasks. -Function : bl2\_early\_platform\_setup2() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_early_platform_setup2() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1367,11 +1367,11 @@ On Arm standard platforms, this function also: family of functions in BL2. - Initializes the storage abstraction layer used to load further bootloader - images. It is necessary to do this early on platforms with a SCP\_BL2 image, - since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded. + images. It is necessary to do this early on platforms with a SCP_BL2 image, + since the later ``bl2_platform_setup`` must be done after SCP_BL2 is loaded. -Function : bl2\_plat\_arch\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_plat_arch_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1386,8 +1386,8 @@ that varies across platforms. On Arm standard platforms, this function enables the MMU. -Function : bl2\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1405,8 +1405,8 @@ In Arm standard platforms, this function performs security setup, including configuration of the TrustZone controller to allow non-secure masters access to most of DRAM. Part of DRAM is reserved for secure world use. -Function : bl2\_plat\_handle\_pre\_image\_load() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_plat_handle_pre_image_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1417,8 +1417,8 @@ This function can be used by the platforms to update/use image information for given ``image_id``. This function is currently invoked in BL2 before loading each image. -Function : bl2\_plat\_handle\_post\_image\_load() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_plat_handle_post_image_load() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1429,8 +1429,8 @@ This function can be used by the platforms to update/use image information for given ``image_id``. This function is currently invoked in BL2 after loading each image. -Function : bl2\_plat\_preload\_setup [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_plat_preload_setup [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1439,12 +1439,12 @@ Function : bl2\_plat\_preload\_setup [optional] This optional function performs any BL2 platform initialization required before image loading, that is not done later in -bl2\_platform\_setup(). Specifically, if support for multiple +bl2_platform_setup(). Specifically, if support for multiple boot sources is required, it initializes the boot sequence used by -plat\_try\_next\_boot\_source(). +plat_try_next_boot_source(). -Function : plat\_try\_next\_boot\_source() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_try_next_boot_source() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1468,14 +1468,14 @@ execute at EL3 instead of executing at EL1. Refer to the `Firmware Design`_ for more information. All mandatory functions of BL2 must be implemented, except the functions -bl2\_early\_platform\_setup and bl2\_el3\_plat\_arch\_setup, because -their work is done now by bl2\_el3\_early\_platform\_setup and -bl2\_el3\_plat\_arch\_setup. These functions should generally implement -the bl1\_plat\_xxx() and bl2\_plat\_xxx() functionality combined. +bl2_early_platform_setup and bl2_el3_plat_arch_setup, because +their work is done now by bl2_el3_early_platform_setup and +bl2_el3_plat_arch_setup. These functions should generally implement +the bl1_plat_xxx() and bl2_plat_xxx() functionality combined. -Function : bl2\_el3\_early\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_el3_early_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1492,13 +1492,13 @@ On Arm standard platforms, this function does the following: family of functions in BL2. - Initializes the storage abstraction layer used to load further bootloader - images. It is necessary to do this early on platforms with a SCP\_BL2 image, - since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded. + images. It is necessary to do this early on platforms with a SCP_BL2 image, + since the later ``bl2_platform_setup`` must be done after SCP_BL2 is loaded. - Initializes the private variables that define the memory layout used. -Function : bl2\_el3\_plat\_arch\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_el3_plat_arch_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1513,8 +1513,8 @@ that varies across platforms. On Arm standard platforms, this function enables the MMU. -Function : bl2\_el3\_plat\_prepare\_exit() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2_el3_plat_prepare_exit() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1533,10 +1533,10 @@ The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU process and is executed only by the primary CPU. BL1 passes control to BL2U at ``BL2U_BASE``. BL2U executes in Secure-EL1 and is responsible for: -#. (Optional) Transferring the optional SCP\_BL2U binary image from AP secure - memory to SCP RAM. BL2U uses the SCP\_BL2U ``image_info`` passed by BL1. - ``SCP_BL2U_BASE`` defines the address in AP secure memory where SCP\_BL2U - should be copied from. Subsequent handling of the SCP\_BL2U image is +#. (Optional) Transferring the optional SCP_BL2U binary image from AP secure + memory to SCP RAM. BL2U uses the SCP_BL2U ``image_info`` passed by BL1. + ``SCP_BL2U_BASE`` defines the address in AP secure memory where SCP_BL2U + should be copied from. Subsequent handling of the SCP_BL2U image is implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function. If ``SCP_BL2U_BASE`` is not defined then this step is not performed. @@ -1547,8 +1547,8 @@ process and is executed only by the primary CPU. BL1 passes control to BL2U at The following functions must be implemented by the platform port to enable BL2U to perform the tasks mentioned above. -Function : bl2u\_early\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2u_early_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1563,11 +1563,11 @@ The platform may copy the contents of the ``mem_info`` and ``plat_info`` into private storage as the original memory may be subsequently overwritten by BL2U. On Arm CSS platforms ``plat_info`` is interpreted as an ``image_info_t`` structure, -to extract SCP\_BL2U image information, which is then copied into a private +to extract SCP_BL2U image information, which is then copied into a private variable. -Function : bl2u\_plat\_arch\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2u_plat_arch_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1581,8 +1581,8 @@ The purpose of this function is to perform any architectural initialization that varies across platforms, for example enabling the MMU (since the memory map differs across platforms). -Function : bl2u\_platform\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2u_platform_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1600,8 +1600,8 @@ In Arm standard platforms, this function performs security setup, including configuration of the TrustZone controller to allow non-secure masters access to most of DRAM. Part of DRAM is reserved for secure world use. -Function : bl2u\_plat\_handle\_scp\_bl2u() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl2u_plat_handle_scp_bl2u() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1614,7 +1614,7 @@ a platform-specific protocol and waits until SCP executes it and signals to the Application Processor (AP) for BL2U execution to continue. This function returns 0 on success, a negative error code otherwise. -This function is included if SCP\_BL2U\_BASE is defined. +This function is included if SCP_BL2U_BASE is defined. Boot Loader Stage 3-1 (BL31) ---------------------------- @@ -1650,8 +1650,8 @@ section 2.2 before the tasks described above. The following functions must be implemented by the platform port to enable BL31 to perform the above tasks. -Function : bl31\_early\_platform\_setup2() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl31_early_platform_setup2() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1684,8 +1684,8 @@ information for BL32 and BL33. It also performs the following: CCI slave interface corresponding to the cluster that includes the primary CPU. -Function : bl31\_plat\_arch\_setup() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl31_plat_arch_setup() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1700,7 +1700,7 @@ that varies across platforms. On Arm standard platforms, this function enables the MMU. -Function : bl31\_platform\_setup() [mandatory] +Function : bl31_platform_setup() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1742,8 +1742,8 @@ On Arm standard platforms, this function does the following: In particular, initialise the locks that prevent concurrent accesses to the power controller device. -Function : bl31\_plat\_runtime\_setup() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl31_plat_runtime_setup() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1755,8 +1755,8 @@ setup just prior to BL31 exit during cold boot. The default weak implementation of this function will invoke ``console_switch_state()`` to switch console output to consoles marked for use in the ``runtime`` state. -Function : bl31\_plat\_get\_next\_image\_ep\_info() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : bl31_plat_get_next_image_ep_info() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1792,8 +1792,8 @@ defined by the translation library, and can be found in the file On DynamIQ systems, this function must not use stack while enabling MMU, which is how the function in xlat table library version 2 is implemented. -Function : plat\_get\_syscnt\_freq2() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_syscnt_freq2() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1806,8 +1806,8 @@ frequency for the CPU's generic timer. This value will be programmed into the of the system counter, which is retrieved from the first entry in the frequency modes table. -#define : PLAT\_PERCPU\_BAKERY\_LOCK\_SIZE [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When ``USE_COHERENT_MEM = 0``, this constant defines the total memory (in bytes) aligned to the cache line boundary that should be allocated per-cpu to @@ -1929,8 +1929,8 @@ passed in a PSCI ``CPU_SUSPEND`` call to this representation. The following functions form part of platform port of PSCI functionality. -Function : plat\_psci\_stat\_accounting\_start() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_psci_stat_accounting_start() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1947,8 +1947,8 @@ residency statistics. For higher levels (array indices > 0), the residency statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the default implementation will use PMF to capture timestamps. -Function : plat\_psci\_stat\_accounting\_stop() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_psci_stat_accounting_stop() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1965,8 +1965,8 @@ residency statistics. For higher levels (array indices > 0), the residency statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the default implementation will use PMF to capture timestamps. -Function : plat\_psci\_stat\_get\_residency() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_psci_stat_get_residency() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -1985,8 +1985,8 @@ power state and the ``last_cpu_idx`` (third parameter) is the index of the last CPU in the power domain to suspend and may be needed to calculate the residency for that power domain. -Function : plat\_get\_target\_pwr\_state() [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_target_pwr_state() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2010,8 +2010,8 @@ then X represents a shallower power state than Y. As a result, the coordinated target local power state for a power domain will be the minimum of the requested local power state values. -Function : plat\_get\_power\_domain\_tree\_desc() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_get_power_domain_tree_desc() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2023,13 +2023,13 @@ topology tree description. The format and method to construct this array are described in `Power Domain Topology Design`_. The BL31 PSCI initialization code requires this array to be described by the platform, either statically or dynamically, to initialize the power domain topology tree. In case the array -is populated dynamically, then plat\_core\_pos\_by\_mpidr() and -plat\_my\_core\_pos() should also be implemented suitably so that the topology +is populated dynamically, then plat_core_pos_by_mpidr() and +plat_my_core_pos() should also be implemented suitably so that the topology tree description matches the CPU indices returned by these APIs. These APIs together form the platform interface for the PSCI topology framework. -Function : plat\_setup\_psci\_ops() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_setup_psci_ops() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2048,15 +2048,15 @@ pointer with a pointer to BL31's private ``plat_psci_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/arm/board/fvp/fvp\_pm.c`_ as an example. For each PSCI function that the +`plat/arm/board/fvp/fvp_pm.c`_ as an example. For each PSCI function that the platform wants to support, the associated operation or operations in this structure must be provided and implemented (Refer section 4 of `Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI function in a platform port, the operation should be removed from this structure instead of providing an empty implementation. -plat\_psci\_ops.cpu\_standby() -.............................. +plat_psci_ops.cpu_standby() +........................... Perform the platform-specific actions to enter the standby state for a cpu indicated by the passed argument. This provides a fast path for CPU standby @@ -2068,15 +2068,15 @@ handler should put the CPU into a low power retention state (usually by issuing a wfi instruction) and ensure that it can be woken up from that state by a normal interrupt. The generic code expects the handler to succeed. -plat\_psci\_ops.pwr\_domain\_on() -................................. +plat_psci_ops.pwr_domain_on() +............................. Perform the platform specific actions to power on a CPU, specified by the ``MPIDR`` (first argument). The generic code expects the platform to -return PSCI\_E\_SUCCESS on success or PSCI\_E\_INTERN\_FAIL for any failure. +return PSCI_E_SUCCESS on success or PSCI_E_INTERN_FAIL for any failure. -plat\_psci\_ops.pwr\_domain\_off() -.................................. +plat_psci_ops.pwr_domain_off() +.............................. Perform the platform specific actions to prepare to power off the calling CPU and its higher parent power domain levels as indicated by the ``target_state`` @@ -2092,8 +2092,8 @@ power down state where as it could be either power down, retention or run state for the higher power domain levels depending on the result of state coordination. The generic code expects the handler to succeed. -plat\_psci\_ops.pwr\_domain\_suspend\_pwrdown\_early() [optional] -................................................................. +plat_psci_ops.pwr_domain_suspend_pwrdown_early() [optional] +........................................................... This optional function may be used as a performance optimization to replace or complement pwr_domain_suspend() on some platforms. Its calling semantics @@ -2109,8 +2109,8 @@ efficient to move those actions to this function. When HW_ASSISTED_COHERENCY = 1, data caches remain enabled throughout, and so there is no advantage to moving platform specific actions to this function. -plat\_psci\_ops.pwr\_domain\_suspend() -...................................... +plat_psci_ops.pwr_domain_suspend() +.................................. Perform the platform specific actions to prepare to suspend the calling CPU and its higher parent power domain levels as indicated by the @@ -2150,8 +2150,8 @@ allocated in a special area if it cannot fit in the platform's global static data, for example in DRAM. The Distributor can then be powered down using an implementation-defined sequence. -plat\_psci\_ops.pwr\_domain\_pwr\_down\_wfi() -............................................. +plat_psci_ops.pwr_domain_pwr_down_wfi() +....................................... This is an optional function and, if implemented, is expected to perform platform specific actions including the ``wfi`` invocation which allows the @@ -2167,8 +2167,8 @@ not return back to the caller. If this function is not implemented by the platform, PSCI generic implementation invokes ``psci_power_down_wfi()`` for power down. -plat\_psci\_ops.pwr\_domain\_on\_finish() -......................................... +plat_psci_ops.pwr_domain_on_finish() +.................................... This function is called by the PSCI implementation after the calling CPU is powered on and released from reset in response to an earlier PSCI ``CPU_ON`` call. @@ -2181,8 +2181,8 @@ immediately before the CPU was turned on. It indicates which power domains above the CPU might require initialization due to having previously been in low power states. The generic code expects the handler to succeed. -plat\_psci\_ops.pwr\_domain\_suspend\_finish() -.............................................. +plat_psci_ops.pwr_domain_suspend_finish() +......................................... This function is called by the PSCI implementation after the calling CPU is powered on and released from reset in response to an asynchronous wakeup @@ -2199,41 +2199,41 @@ If the Distributor, Redistributors or ITS have been powered off as part of a suspend, their context must be restored in this function in the reverse order to how they were saved during suspend sequence. -plat\_psci\_ops.system\_off() -............................. +plat_psci_ops.system_off() +.......................... This function is called by PSCI implementation in response to a ``SYSTEM_OFF`` call. It performs the platform-specific system poweroff sequence after notifying the Secure Payload Dispatcher. -plat\_psci\_ops.system\_reset() -............................... +plat_psci_ops.system_reset() +............................ This function is called by PSCI implementation in response to a ``SYSTEM_RESET`` call. It performs the platform-specific system reset sequence after notifying the Secure Payload Dispatcher. -plat\_psci\_ops.validate\_power\_state() -........................................ +plat_psci_ops.validate_power_state() +.................................... This function is called by the PSCI implementation during the ``CPU_SUSPEND`` call to validate the ``power_state`` parameter of the PSCI API and if valid, populate it in ``req_state`` (second argument) array as power domain level specific local states. If the ``power_state`` is invalid, the platform must -return PSCI\_E\_INVALID\_PARAMS as error, which is propagated back to the +return PSCI_E_INVALID_PARAMS as error, which is propagated back to the normal world PSCI client. -plat\_psci\_ops.validate\_ns\_entrypoint() -.......................................... +plat_psci_ops.validate_ns_entrypoint() +...................................... This function is called by the PSCI implementation during the ``CPU_SUSPEND``, ``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the non-secure ``entry_point`` parameter passed by the normal world. If the ``entry_point`` is invalid, -the platform must return PSCI\_E\_INVALID\_ADDRESS as error, which is +the platform must return PSCI_E_INVALID_ADDRESS as error, which is propagated back to the normal world PSCI client. -plat\_psci\_ops.get\_sys\_suspend\_power\_state() -................................................. +plat_psci_ops.get_sys_suspend_power_state() +........................................... This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND`` call to get the ``req_state`` parameter from platform which encodes the power @@ -2242,8 +2242,8 @@ domain level specific local states to suspend to system affinity level. The ``pwr_domain_suspend()`` will be invoked with the coordinated target state to enter system suspend. -plat\_psci\_ops.get\_pwr\_lvl\_state\_idx() -........................................... +plat_psci_ops.get_pwr_lvl_state_idx() +..................................... This is an optional function and, if implemented, is invoked by the PSCI implementation to convert the ``local_state`` (first argument) at a specified @@ -2253,8 +2253,8 @@ supports more than two local power states at each power domain level, that is ``PLAT_MAX_PWR_LVL_STATES`` is greater than 2, and needs to account for these local power states. -plat\_psci\_ops.translate\_power\_state\_by\_mpidr() -.................................................... +plat_psci_ops.translate_power_state_by_mpidr() +.............................................. This is an optional function and, if implemented, verifies the ``power_state`` (second argument) parameter of the PSCI API corresponding to a target power @@ -2265,16 +2265,16 @@ populated in the ``output_state`` (third argument) array. The functionality is similar to the ``validate_power_state`` function described above and is envisaged to be used in case the validity of ``power_state`` depend on the targeted power domain. If the ``power_state`` is invalid for the targeted power -domain, the platform must return PSCI\_E\_INVALID\_PARAMS as error. If this +domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this function is not implemented, then the generic implementation relies on ``validate_power_state`` function to translate the ``power_state``. This function can also be used in case the platform wants to support local -power state encoding for ``power_state`` parameter of PSCI\_STAT\_COUNT/RESIDENCY +power state encoding for ``power_state`` parameter of PSCI_STAT_COUNT/RESIDENCY APIs as described in Section 5.18 of `PSCI`_. -plat\_psci\_ops.get\_node\_hw\_state() -...................................... +plat_psci_ops.get_node_hw_state() +................................. This is an optional function. If implemented this function is intended to return the power state of a node (identified by the first parameter, the ``MPIDR``) in @@ -2288,8 +2288,8 @@ appropriate. Implementations are not expected to handle ``power_levels`` greater than ``PLAT_MAX_PWR_LVL``. -plat\_psci\_ops.system\_reset2() -................................ +plat_psci_ops.system_reset2() +............................. This is an optional function. If implemented this function is called during the ``SYSTEM_RESET2`` call to perform a reset @@ -2301,8 +2301,8 @@ resets, all failures must return ``PSCI_E_INVALID_PARAMETERS`` and vendor reset can return other PSCI error codes as defined in `PSCI`_. On success this function will not return. -plat\_psci\_ops.write\_mem\_protect() -.................................... +plat_psci_ops.write_mem_protect() +................................. This is an optional function. If implemented it enables or disables the ``MEM_PROTECT`` functionality based on the value of ``val``. @@ -2310,16 +2310,16 @@ A non-zero value enables ``MEM_PROTECT`` and a value of zero disables it. Upon encountering failures it must return a negative value and on success it must return 0. -plat\_psci\_ops.read\_mem\_protect() -..................................... +plat_psci_ops.read_mem_protect() +................................ This is an optional function. If implemented it returns the current state of ``MEM_PROTECT`` via the ``val`` parameter. Upon encountering failures it must return a negative value and on success it must return 0. -plat\_psci\_ops.mem\_protect\_chk() -................................... +plat_psci_ops.mem_protect_chk() +............................... This is an optional function. If implemented it checks if a memory region defined by a base address ``base`` and with a size of ``length`` @@ -2348,8 +2348,8 @@ See also: `Interrupt Controller Abstraction APIs`__. .. __: platform-interrupt-controller-API.rst -Function : plat\_interrupt\_type\_to\_line() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_interrupt_type_to_line() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2384,8 +2384,8 @@ interrupt is signalled and are as follows: - The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2 context. -Function : plat\_ic\_get\_pending\_interrupt\_type() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_ic_get_pending_interrupt_type() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2417,8 +2417,8 @@ depends upon the id value as follows. #. id = ``GIC_SPURIOUS_INTERRUPT`` (1023) is reported as an invalid interrupt type. #. All other interrupt id's are reported as EL3 interrupt. -Function : plat\_ic\_get\_pending\_interrupt\_id() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_ic_get_pending_interrupt_id() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2456,11 +2456,11 @@ interrupt controller as follows. When the API invoked from S-EL1 for GICv3 systems, the id read from system register ``ICC_HPPIR1_EL1``, *Highest Priority Pending group 1 Interrupt -Register*, is returned if is not equal to GIC\_SPURIOUS\_INTERRUPT (1023) else +Register*, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) else ``INTR_ID_UNAVAILABLE`` is returned. -Function : plat\_ic\_acknowledge\_interrupt() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_ic_acknowledge_interrupt() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2491,8 +2491,8 @@ unmodified. The TSP uses this API to start processing of the secure physical timer interrupt. -Function : plat\_ic\_end\_of\_interrupt() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_ic_end_of_interrupt() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2513,8 +2513,8 @@ controller. The TSP uses this API to finish processing of the secure physical timer interrupt. -Function : plat\_ic\_get\_interrupt\_type() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_ic_get_interrupt_type() [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2564,8 +2564,8 @@ console drivers provide functions named ``console_xxx_core_init/putc/flush`` that are designed to be used by these functions. See Arm platforms (like juno) for an example of this. -Function : plat\_crash\_console\_init [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_crash_console_init [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2576,8 +2576,8 @@ This API is used by the crash reporting mechanism to initialize the crash console. It must only use the general purpose registers x0 through x7 to do the initialization and returns 1 on success. -Function : plat\_crash\_console\_putc [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_crash_console_putc [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2589,8 +2589,8 @@ designated crash console. It must only use general purpose registers x1 and x2 to do its work. The parameter and the return value are in general purpose register x0. -Function : plat\_crash\_console\_flush [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_crash_console_flush [mandatory] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -2710,7 +2710,7 @@ inclusion or exclusion of certain BL stages from the FIP image. These flags need to be defined in the platform makefile which will get included by the build system. -- **NEED\_BL33** +- **NEED_BL33** By default, this flag is defined ``yes`` by the build system and ``BL33`` build option should be supplied as a build option. The platform has the option of excluding the BL33 image in the ``fip`` image by defining this flag @@ -2733,8 +2733,8 @@ been written specifically for TF-A. Fome implementation files have been obtained from `FreeBSD`_, others have been written specifically for TF-A as well. The files can be found in ``include/lib/libc`` and ``lib/libc``. -SCC can be found in `http://www.simple-cc.org/`_. A copy of the `FreeBSD`_ -sources can be obtained from `http://github.com/freebsd/freebsd`_. +SCC can be found in http://www.simple-cc.org/. A copy of the `FreeBSD`_ sources +can be obtained from http://github.com/freebsd/freebsd. Storage abstraction layer ------------------------- @@ -2770,7 +2770,7 @@ operations such as loading a bootloader image. The current implementation only allows for known images to be loaded by the firmware. These images are specified by using their identifiers, as defined in -[include/plat/common/platform\_def.h] (or a separate header file included from +[include/plat/common/platform_def.h] (or a separate header file included from there). The platform layer (``plat_get_image_source()``) then returns a reference to a device and a driver-specific ``spec`` which will be understood by the driver to allow access to the image data. @@ -2791,19 +2791,19 @@ amount of open resources per driver. *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* .. _include/plat/common/platform.h: ../include/plat/common/platform.h -.. _include/plat/arm/common/plat\_arm.h: ../include/plat/arm/common/plat_arm.h%5D +.. _include/plat/arm/common/plat_arm.h: ../include/plat/arm/common/plat_arm.h%5D .. _User Guide: user-guide.rst -.. _include/plat/common/common\_def.h: ../include/plat/common/common_def.h -.. _include/plat/arm/common/arm\_def.h: ../include/plat/arm/common/arm_def.h -.. _plat/common/aarch64/platform\_mp\_stack.S: ../plat/common/aarch64/platform_mp_stack.S -.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_stack.S +.. _include/plat/common/common_def.h: ../include/plat/common/common_def.h +.. _include/plat/arm/common/arm_def.h: ../include/plat/arm/common/arm_def.h +.. _plat/common/aarch64/platform_mp_stack.S: ../plat/common/aarch64/platform_mp_stack.S +.. _plat/common/aarch64/platform_up_stack.S: ../plat/common/aarch64/platform_up_stack.S .. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160 .. _Power Domain Topology Design: psci-pd-tree.rst -.. _include/common/bl\_common.h: ../include/common/bl_common.h +.. _include/common/bl_common.h: ../include/common/bl_common.h .. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h .. _Firmware Design: firmware-design.rst .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c +.. _plat/arm/board/fvp/fvp_pm.c: ../plat/arm/board/fvp/fvp_pm.c .. _Platform compatibility policy: ./platform-compatibility-policy.rst .. _IMF Design Guide: interrupt-framework-design.rst .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html diff --git a/docs/psci-lib-integration-guide.rst b/docs/psci-lib-integration-guide.rst index 1be224088..555d347c3 100644 --- a/docs/psci-lib-integration-guide.rst +++ b/docs/psci-lib-integration-guide.rst @@ -140,7 +140,7 @@ to this library are declared in ``psci.h`` and are as listed below: void psci_register_spd_pm_hook(const spd_pm_ops_t *pm); void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info); -The CPU context data 'cpu\_context\_t' is programmed to the registers differently +The CPU context data 'cpu_context_t' is programmed to the registers differently when PSCI is integrated with an AArch32 EL3 Runtime Software compared to when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For example, in the case of AArch64, there is no need to retrieve ``cpu_context_t`` @@ -159,7 +159,7 @@ values if required. PSCI library needs the flexibility to access both secure and non-secure copies of banked registers. Hence it needs to be invoked in Monitor mode -for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR\_EL3 +for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR_EL3 (in AArch64) must be set to 0. Additional requirements for the PSCI library interfaces are: @@ -175,8 +175,8 @@ interfaces are: Further requirements for each interface can be found in the interface description. -Interface : psci\_setup() -~~~~~~~~~~~~~~~~~~~~~~~~~ +Interface : psci_setup() +~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -212,8 +212,8 @@ must have completed. Major actions performed by this interface are: `CPU Context management API`_) for all the CPUs in the platform -Interface : psci\_prepare\_next\_non\_secure\_ctx() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Interface : psci_prepare_next_non_secure_ctx() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -225,11 +225,11 @@ must be called by the EL3 Runtime Software to initialize the non-secure world context. The non-secure world entrypoint information ``next_image_info`` (first argument) will be used to determine the non-secure context. After this function returns, the EL3 Runtime Software must retrieve the ``cpu_context_t`` (using -cm\_get\_context()) for the current CPU and program the registers prior to exit +cm_get_context()) for the current CPU and program the registers prior to exit to the non-secure world. -Interface : psci\_register\_spd\_pm\_hook() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Interface : psci_register_spd_pm_hook() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -244,8 +244,8 @@ appropriately during power management. Calling this function is optional and need to be called by the primary CPU during the cold boot sequence after ``psci_setup()`` has completed. -Interface : psci\_smc\_handler() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Interface : psci_smc_handler() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -270,8 +270,8 @@ PSCI API corresponding to ``smc_fid``. This function may not return back to the caller if PSCI API causes power down of the CPU. In this case, when the CPU wakes up, it will start execution from the warm reset address. -Interface : psci\_warmboot\_entrypoint() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Interface : psci_warmboot_entrypoint() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: @@ -302,7 +302,7 @@ EL3 Runtime Software dependencies --------------------------------- The PSCI Library includes supporting frameworks like context management, -cpu operations (cpu\_ops) and per-cpu data framework. Other helper library +cpu operations (cpu_ops) and per-cpu data framework. Other helper library functions like bakery locks and spin locks are also included in the library. The dependencies which must be fulfilled by the EL3 Runtime Software for integration with PSCI library are described below. @@ -323,7 +323,7 @@ these functions but the EL3 Runtime Software may use its own implementation. These must be implemented as described in ISO C Standard. -**Function : flush\_dcache\_range()** +**Function : flush_dcache_range()** :: @@ -333,7 +333,7 @@ These must be implemented as described in ISO C Standard. This function cleans and invalidates (flushes) the data cache for memory at address ``addr`` (first argument) address and of size ``size`` (second argument). -**Function : inv\_dcache\_range()** +**Function : inv_dcache_range()** :: @@ -343,7 +343,7 @@ at address ``addr`` (first argument) address and of size ``size`` (second argume This function invalidates (flushes) the data cache for memory at address ``addr`` (first argument) address and of size ``size`` (second argument). -**Function : do\_panic()** +**Function : do_panic()** :: @@ -363,7 +363,7 @@ demonstrates how these APIs can be implemented but the EL3 Runtime Software can choose a more optimal implementation (like dedicating the secure TPIDRPRW system register (in AArch32) for storing these pointers). -**Function : cm\_set\_context\_by\_index()** +**Function : cm_set_context_by_index()** :: @@ -384,7 +384,7 @@ The actual method of storing the ``context`` pointers is implementation specific For example, SP-MIN stores the pointers in the array ``sp_min_cpu_ctx_ptr`` declared in ``sp_min_main.c``. -**Function : cm\_get\_context()** +**Function : cm_get_context()** :: @@ -398,7 +398,7 @@ context pointers are stored prior to invoking this API. The ``security_state`` will always be non-secure when called by PSCI library and this argument is retained for compatibility with BL31. -**Function : cm\_get\_context\_by\_index()** +**Function : cm_get_context_by_index()** :: @@ -423,25 +423,25 @@ Runtime Software for integration with the PSCI library. The mandatory platform APIs are: -- plat\_my\_core\_pos -- plat\_core\_pos\_by\_mpidr -- plat\_get\_syscnt\_freq2 -- plat\_get\_power\_domain\_tree\_desc -- plat\_setup\_psci\_ops -- plat\_reset\_handler -- plat\_panic\_handler -- plat\_get\_my\_stack +- plat_my_core_pos +- plat_core_pos_by_mpidr +- plat_get_syscnt_freq2 +- plat_get_power_domain_tree_desc +- plat_setup_psci_ops +- plat_reset_handler +- plat_panic_handler +- plat_get_my_stack The mandatory platform macros are: -- PLATFORM\_CORE\_COUNT -- PLAT\_MAX\_PWR\_LVL -- PLAT\_NUM\_PWR\_DOMAINS -- CACHE\_WRITEBACK\_GRANULE -- PLAT\_MAX\_OFF\_STATE -- PLAT\_MAX\_RET\_STATE -- PLAT\_MAX\_PWR\_LVL\_STATES (optional) -- PLAT\_PCPU\_DATA\_SIZE (optional) +- PLATFORM_CORE_COUNT +- PLAT_MAX_PWR_LVL +- PLAT_NUM_PWR_DOMAINS +- CACHE_WRITEBACK_GRANULE +- PLAT_MAX_OFF_STATE +- PLAT_MAX_RET_STATE +- PLAT_MAX_PWR_LVL_STATES (optional) +- PLAT_PCPU_DATA_SIZE (optional) The details of these APIs/macros can be found in `Porting Guide`_. @@ -486,50 +486,50 @@ enabled/re-targeted back to the current CPU. A brief description of each callback is given below: -- svc\_on, svc\_off, svc\_on\_finish +- svc_on, svc_off, svc_on_finish - The ``svc_on``, ``svc_off`` callbacks are called during PSCI\_CPU\_ON, - PSCI\_CPU\_OFF APIs respectively. The ``svc_on_finish`` is called when the - target CPU of PSCI\_CPU\_ON API powers up and executes the + The ``svc_on``, ``svc_off`` callbacks are called during PSCI_CPU_ON, + PSCI_CPU_OFF APIs respectively. The ``svc_on_finish`` is called when the + target CPU of PSCI_CPU_ON API powers up and executes the ``psci_warmboot_entrypoint()`` PSCI library interface. -- svc\_suspend, svc\_suspend\_finish +- svc_suspend, svc_suspend_finish The ``svc_suspend`` callback is called during power down bu either - PSCI\_SUSPEND or PSCI\_SYSTEM\_SUSPEND APIs. The ``svc_suspend_finish`` is + PSCI_SUSPEND or PSCI_SYSTEM_SUSPEND APIs. The ``svc_suspend_finish`` is called when the CPU wakes up from suspend and executes the ``psci_warmboot_entrypoint()`` PSCI library interface. The ``max_off_pwrlvl`` (first parameter) denotes the highest power domain level being powered down to or woken up from suspend. -- svc\_system\_off, svc\_system\_reset +- svc_system_off, svc_system_reset - These callbacks are called during PSCI\_SYSTEM\_OFF and PSCI\_SYSTEM\_RESET + These callbacks are called during PSCI_SYSTEM_OFF and PSCI_SYSTEM_RESET PSCI APIs respectively. -- svc\_migrate\_info +- svc_migrate_info - This callback is called in response to PSCI\_MIGRATE\_INFO\_TYPE or - PSCI\_MIGRATE\_INFO\_UP\_CPU APIs. The return value of this callback must - correspond to the return value of PSCI\_MIGRATE\_INFO\_TYPE API as described + This callback is called in response to PSCI_MIGRATE_INFO_TYPE or + PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must + correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described in `PSCI spec`_. If the secure payload is a Uniprocessor (UP) implementation, then it must update the mpidr of the CPU it is resident in via ``resident_cpu`` (first argument). The updates to ``resident_cpu`` is ignored if the secure payload is a multiprocessor (MP) implementation. -- svc\_migrate +- svc_migrate This callback is only relevant if the secure payload in EL3 Runtime Software is a Uniprocessor (UP) implementation and supports migration from the current CPU ``from_cpu`` (first argument) to another CPU ``to_cpu`` - (second argument). This callback is called in response to PSCI\_MIGRATE + (second argument). This callback is called in response to PSCI_MIGRATE API. This callback is never called if the secure payload is a Multiprocessor (MP) implementation. CPU operations ~~~~~~~~~~~~~~ -The CPU operations (cpu\_ops) framework implement power down sequence specific +The CPU operations (cpu_ops) framework implement power down sequence specific to the CPU and the details of which can be found in the ``CPU specific operations framework`` section of `Firmware Design`_. The TF-A tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime diff --git a/docs/rt-svc-writers-guide.rst b/docs/rt-svc-writers-guide.rst index cec2ae708..4d4066c26 100644 --- a/docs/rt-svc-writers-guide.rst +++ b/docs/rt-svc-writers-guide.rst @@ -91,7 +91,7 @@ TF-A has a `services`_ directory in the source tree under which each owning entity can place the implementation of its runtime service. The `PSCI`_ implementation is located here in the `lib/psci`_ directory. -Runtime service sources will need to include the `runtime\_svc.h`_ header file. +Runtime service sources will need to include the `runtime_svc.h`_ header file. Registering a runtime service ----------------------------- @@ -140,7 +140,7 @@ to ensure that the following conditions are met: #. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD`` #. ``_setup`` and ``_smch`` routines have been specified -`std\_svc\_setup.c`_ provides an example of registering a runtime service: +`std_svc_setup.c`_ provides an example of registering a runtime service: .. code:: c @@ -310,6 +310,6 @@ provide this information.... .. _Firmware Design: ./firmware-design.rst .. _services: ../services .. _lib/psci: ../lib/psci -.. _runtime\_svc.h: ../include/common/runtime_svc.h +.. _runtime_svc.h: ../include/common/runtime_svc.h .. _smccc.h: ../include/lib/smccc.h -.. _std\_svc\_setup.c: ../services/std_svc/std_svc_setup.c +.. _std_svc_setup.c: ../services/std_svc/std_svc_setup.c diff --git a/docs/trusted-board-boot.rst b/docs/trusted-board-boot.rst index 0ef4797d2..1ca6fef75 100644 --- a/docs/trusted-board-boot.rst +++ b/docs/trusted-board-boot.rst @@ -59,7 +59,7 @@ The keys used to establish the CoT are: - **Trusted world key** The private part is used to sign the key certificates corresponding to the - secure world images (SCP\_BL2, BL31 and BL32). The public part is stored in + secure world images (SCP_BL2, BL31 and BL32). The public part is stored in one of the extension fields in the trusted world certificate. - **Non-trusted world key** @@ -70,7 +70,7 @@ The keys used to establish the CoT are: - **BL3-X keys** - For each of SCP\_BL2, BL31, BL32 and BL33, the private part is used to + For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to sign the content certificate for the BL3-X image. The public part is stored in one of the extension fields in the corresponding key certificate. @@ -78,7 +78,7 @@ The following images are included in the CoT: - BL1 - BL2 -- SCP\_BL2 (optional) +- SCP_BL2 (optional) - BL31 - BL33 - BL32 (optional) @@ -96,14 +96,14 @@ The following certificates are used to authenticate the images. public part of the trusted world key and the public part of the non-trusted world key. -- **SCP\_BL2 key certificate** +- **SCP_BL2 key certificate** It is self-signed with the trusted world key. It contains the public part of - the SCP\_BL2 key. + the SCP_BL2 key. -- **SCP\_BL2 content certificate** +- **SCP_BL2 content certificate** - It is self-signed with the SCP\_BL2 key. It contains a hash of the SCP\_BL2 + It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2 image. - **BL31 key certificate** @@ -133,8 +133,8 @@ The following certificates are used to authenticate the images. It is self-signed with the BL33 key. It contains a hash of the BL33 image. -The SCP\_BL2 and BL32 certificates are optional, but they must be present if the -corresponding SCP\_BL2 or BL32 images are present. +The SCP_BL2 and BL32 certificates are optional, but they must be present if the +corresponding SCP_BL2 or BL32 images are present. Trusted Board Boot Sequence --------------------------- @@ -160,8 +160,8 @@ if any of the steps fail. registers. If the comparison succeeds, BL2 reads and saves the trusted and non-trusted world public keys from the verified certificate. -The next two steps are executed for each of the SCP\_BL2, BL31 & BL32 images. -The steps for the optional SCP\_BL2 and BL32 images are skipped if these images +The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images. +The steps for the optional SCP_BL2 and BL32 images are skipped if these images are not present. - BL2 loads and verifies the BL3x key certificate. The certificate signature diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 22f5d4092..4ff1c7270 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -197,7 +197,7 @@ Building TF-A - (AArch32 only) Currently only ``PLAT=fvp`` is supported. - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it - corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp\_min, is + corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is provided by TF-A to demonstrate how PSCI Library can be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may include other runtime services, for example Trusted OS services. A guide @@ -324,7 +324,7 @@ Common build options where applicable). Defaults to a string that contains the time and date of the compilation. -- ``BUILD_STRING``: Input string for VERSION\_STRING, which allows the TF-A +- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A build to be uniquely identified. Defaults to the current git commit id. - ``CFLAGS``: Extra user options appended on the compiler's command line in @@ -479,12 +479,12 @@ Common build options - ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create`` tool to create certificates as per the Chain of Trust described in `Trusted Board Boot`_. The build system then calls ``fiptool`` to - include the certificates in the FIP and FWU\_FIP. Default value is '0'. + include the certificates in the FIP and FWU_FIP. Default value is '0'. Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support for the Trusted Board Boot feature in the BL1 and BL2 images, to generate the corresponding certificates, and to include those certificates in the - FIP and FWU\_FIP. + FIP and FWU_FIP. Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2 images will not include support for Trusted Board Boot. The FIP will still @@ -492,7 +492,7 @@ Common build options Chain of Trust on the host machine through other mechanisms. Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2 - images will include support for Trusted Board Boot, but the FIP and FWU\_FIP + images will include support for Trusted Board Boot, but the FIP and FWU_FIP will not include the corresponding certificates, causing a boot failure. - ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have @@ -566,7 +566,7 @@ Common build options specifies the file that contains the Non-Trusted World private key in PEM format. If ``SAVE_KEYS=1``, this file name will be used to save the key. -- ``NS_BL2U``: Path to NS\_BL2U image in the host file system. This image is +- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is optional. It is only needed if the platform makefile specifies that it is required in order to build the ``fwu_fip`` target. @@ -575,7 +575,7 @@ Common build options 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. -- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc +- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc for the BL image. It can be either 0 (include) or 1 (remove). The default value is 0. @@ -611,7 +611,7 @@ Common build options 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 + 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. @@ -629,10 +629,10 @@ Common build options entrypoint) or 1 (CPU reset to BL31 entrypoint). The default value is 0. -- ``RESET_TO_SP_MIN``: SP\_MIN is the minimal AArch32 Secure Payload provided - in TF-A. This flag configures SP\_MIN entrypoint as the CPU reset vector +- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided + in TF-A. This flag configures SP_MIN 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 SP\_MIN entrypoint). The default value is 0. + entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0. - ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this @@ -642,15 +642,15 @@ Common build options certificate generation tool to save the keys used to establish the Chain of Trust. Allowed options are '0' or '1'. Default is '0' (do not save). -- ``SCP_BL2``: Path to SCP\_BL2 image in the host file system. This image is optional. - If a SCP\_BL2 image is present then this option must be passed for the ``fip`` +- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional. + If a SCP_BL2 image is present then this option must be passed for the ``fip`` target. - ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the SCP\_BL2 private key in PEM format. If ``SAVE_KEYS=1``, + file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``, this file name will be used to save the key. -- ``SCP_BL2U``: Path to SCP\_BL2U image in the host file system. This image is +- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is optional. It is only needed if the platform makefile specifies that it is required in order to build the ``fwu_fip`` target. @@ -689,7 +689,7 @@ Common build options Boot feature. When set to '1', BL1 and BL2 images include support to load and verify the certificates and images in a FIP, and BL1 includes support for the Firmware Update. The default value is '0'. Generation and inclusion - of certificates in the FIP and FWU\_FIP depends upon the value of the + of certificates in the FIP and FWU_FIP depends upon the value of the ``GENERATE_COT`` option. Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys @@ -832,8 +832,8 @@ Arm CSS platform specific build options TF-A no longer supports earlier SCP versions. If this option is set to 1 then TF-A will detect if an earlier version is in use. Default is 1. -- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and - SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded +- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP_BL2 and + SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded during boot. Default is 1. - ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers @@ -1087,7 +1087,7 @@ Trusted Board Boot primarily consists of the following two features: - Image Authentication, described in `Trusted Board Boot`_, and - Firmware Update, described in `Firmware Update`_ -The following steps should be followed to build FIP and (optionally) FWU\_FIP +The following steps should be followed to build FIP and (optionally) FWU_FIP images with support for these features: #. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser @@ -1150,13 +1150,13 @@ images with support for these features: described in the TBBR-client document. These certificates can also be found in the output build directory. -#. The optional FWU\_FIP contains any additional images to be loaded from +#. The optional FWU_FIP contains any additional images to be loaded from Non-Volatile storage during the `Firmware Update`_ process. To build the - FWU\_FIP, any FWU images required by the platform must be specified on the + FWU_FIP, any FWU images required by the platform must be specified on the command line. On Arm development platforms like Juno, these are: - - NS\_BL2U. The AP non-secure Firmware Updater image. - - SCP\_BL2U. The SCP Firmware Update Configuration image. + - NS_BL2U. The AP non-secure Firmware Updater image. + - SCP_BL2U. The SCP Firmware Update Configuration image. Example of Juno command line for generating both ``fwu`` and ``fwu_fip`` targets using RSA development: @@ -1173,15 +1173,15 @@ images with support for these features: NS_BL2U=<path-to>/<ns_bl2u_image> \ all fip fwu_fip - Note: The BL2U image will be built by default and added to the FWU\_FIP. + Note: The BL2U image will be built by default and added to the FWU_FIP. The user may override this by adding ``BL2U=<path-to>/<bl2u_image>`` to the command line above. - Note: Building and installing the non-secure and SCP FWU images (NS\_BL1U, - NS\_BL2U and SCP\_BL2U) is outside the scope of this document. + Note: Building and installing the non-secure and SCP FWU images (NS_BL1U, + NS_BL2U and SCP_BL2U) is outside the scope of this document. - The result of this build will be bl1.bin, fip.bin and fwu\_fip.bin binaries. - Both the FIP and FWU\_FIP will include the certificates corresponding to the + The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. + Both the FIP and FWU_FIP will include the certificates corresponding to the Chain of Trust described in the TBBR-client document. These certificates can also be found in the output build directory. @@ -1198,7 +1198,7 @@ command: make PLAT=<platform> [DEBUG=1] [V=1] certtool For platforms that require their own IDs in certificate files, the generic -'cert\_create' tool can be built with the following command: +'cert_create' tool can be built with the following command: :: @@ -1240,9 +1240,9 @@ section for more info on selecting the right FDT to use. make realclean -#. Obtain SCP\_BL2 (Juno) and BL33 (all platforms) +#. Obtain SCP_BL2 (Juno) and BL33 (all platforms) - Use the fiptool to extract the SCP\_BL2 and BL33 images from the FIP + Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP package included in the Linaro release: :: @@ -1255,7 +1255,7 @@ section for more info on selecting the right FDT to use. <path/to/linaro/release>/fip.bin The unpack operation will result in a set of binary images extracted to the - current working directory. The SCP\_BL2 image corresponds to + current working directory. The SCP_BL2 image corresponds to ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``. Note: The fiptool will complain if the images to be unpacked already @@ -1406,7 +1406,7 @@ developing EL3 baremetal code by: - putting the system into a known architectural state; - taking care of platform secure world initialization; -- loading the SCP\_BL2 image if required by the platform. +- loading the SCP_BL2 image if required by the platform. When booting an EL3 payload on Arm standard platforms, the configuration of the TrustZone controller is simplified such that only region 0 is enabled and is @@ -1923,8 +1923,8 @@ Notes: ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of ``BL32_BASE``. -Running on the AEMv8 Base FVP (AArch32) with reset to SP\_MIN entrypoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux with 8 CPUs using the AArch32 build of TF-A. @@ -1991,8 +1991,8 @@ boot Linux with 8 CPUs using the AArch64 build of TF-A. --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 -Running on the Cortex-A32 Base FVP (AArch32) with reset to SP\_MIN entrypoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to boot Linux with 4 CPUs using the AArch32 build of TF-A. diff --git a/docs/xlat-tables-lib-v2-design.rst b/docs/xlat-tables-lib-v2-design.rst index f07dfab68..dbed7f8e2 100644 --- a/docs/xlat-tables-lib-v2-design.rst +++ b/docs/xlat-tables-lib-v2-design.rst @@ -37,8 +37,8 @@ About version 1 and version 2 ----------------------------- This document focuses on version 2 of the library, whose sources are available -in the `lib/xlat\_tables\_v2`_ directory. Version 1 of the library can still be -found in `lib/xlat\_tables`_ directory but it is less flexible and doesn't +in the `lib/xlat_tables_v2`_ directory. Version 1 of the library can still be +found in `lib/xlat_tables`_ directory but it is less flexible and doesn't support dynamic mapping. Although potential bug fixes will be applied to both versions, future features enhancements will focus on version 2 and might not be back-ported to version 1. Therefore, it is recommended to use version 2, @@ -69,7 +69,7 @@ map. It is one of the key interfaces to the library. It is identified by: - its attributes; - its mapping granularity (optional). -See the ``struct mmap_region`` type in `xlat\_tables\_v2.h`_. +See the ``struct mmap_region`` type in `xlat_tables_v2.h`_. The user usually provides a list of such mmap regions to map and lets the library transpose that in a set of translation tables. As a result, the library @@ -80,7 +80,7 @@ normal memory) as well as the memory access permissions (read-only or read-write, executable or not, secure or non-secure, and so on). In the case of the EL1&0 translation regime, the attributes also specify whether the region is a User region (EL0) or Privileged region (EL1). See the ``MT_xxx`` definitions -in `xlat\_tables\_v2.h`_. Note that for the EL1&0 translation regime the Execute +in `xlat_tables_v2.h`_. Note that for the EL1&0 translation regime the Execute Never attribute is set simultaneously for both EL1 and EL0. The granularity controls the translation table level to go down to when mapping @@ -208,7 +208,7 @@ Library APIs ------------ The external APIs exposed by this library are declared and documented in the -`xlat\_tables\_v2.h`_ header file. This should be the reference point for +`xlat_tables_v2.h`_ header file. This should be the reference point for getting information about the usage of the different APIs this library provides. This section just provides some extra details and clarifications. @@ -291,7 +291,7 @@ The library is divided into 4 modules: provides functions such as ``mmap_add_region_ctx`` that let the caller specify the translation tables context affected by them. - See `xlat\_tables\_core.c`_. + See `xlat_tables_core.c`_. - **Active context module** @@ -300,14 +300,14 @@ The library is divided into 4 modules: This module provides functions such as ``mmap_add_region``, that directly affect the BL image using them. - See `xlat\_tables\_context.c`_. + See `xlat_tables_context.c`_. - **Utilities module** Provides additional functionality like debug print of the current state of the translation tables and helpers to query memory attributes and to modify them. - See `xlat\_tables\_utils.c`_. + See `xlat_tables_utils.c`_. - **Architectural module** @@ -316,7 +316,7 @@ The library is divided into 4 modules: MMU, or calculate the Physical Address Space size. They do not need a translation context to work on. - See `aarch32/xlat\_tables\_arch.c`_ and `aarch64/xlat\_tables\_arch.c`_. + See `aarch32/xlat_tables_arch.c`_ and `aarch64/xlat_tables_arch.c`_. From mmap regions to translation tables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -416,13 +416,13 @@ mapping cannot be cached in the TLBs. *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* -.. _lib/xlat\_tables\_v2: ../lib/xlat_tables_v2 -.. _lib/xlat\_tables: ../lib/xlat_tables -.. _xlat\_tables\_v2.h: ../include/lib/xlat_tables/xlat_tables_v2.h -.. _xlat\_tables\_context.c: ../lib/xlat_tables_v2/xlat_tables_context.c -.. _xlat\_tables\_core.c: ../lib/xlat_tables_v2/xlat_tables_core.c -.. _xlat\_tables\_utils.c: ../lib/xlat_tables_v2/xlat_tables_utils.c -.. _aarch32/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c -.. _aarch64/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c +.. _lib/xlat_tables_v2: ../lib/xlat_tables_v2 +.. _lib/xlat_tables: ../lib/xlat_tables +.. _xlat_tables_v2.h: ../include/lib/xlat_tables/xlat_tables_v2.h +.. _xlat_tables_context.c: ../lib/xlat_tables_v2/xlat_tables_context.c +.. _xlat_tables_core.c: ../lib/xlat_tables_v2/xlat_tables_core.c +.. _xlat_tables_utils.c: ../lib/xlat_tables_v2/xlat_tables_utils.c +.. _aarch32/xlat_tables_arch.c: ../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c +.. _aarch64/xlat_tables_arch.c: ../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c .. _Porting Guide: porting-guide.rst .. |Alignment Example| image:: ./diagrams/xlat_align.png?raw=true |