Skip to content

GitLab

Commit ab4a90cd authored by Sandrine Bailleux's avatar Sandrine Bailleux
Browse files

Porting Guide: Remove useless escape characters 



Replace all occurences of escaped underscore characters by plain ones.
This makes the text version of the porting guide easier to read and
grep into.

Change-Id: I7bf3b292b686be4c6d847a467b6708ac16544c90
Signed-off-by: default avatarSandrine Bailleux <sandrine.bailleux@arm.com>
parent 32bcba00
Show whitespace changes
Inline Side-by-side
docs/porting-guide.rst
View file @ ab4a90cd
...@@ -28,7 +28,7 @@ effort. Each platform port can override them with its own implementation if the ...@@ -28,7 +28,7 @@ effort. Each platform port can override them with its own implementation if the
default implementation is inadequate. default implementation is inadequate.
Platform ports that want to be aligned with standard Arm platforms (for example 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 corresponding source files in ``plat/arm/common/``. These provide standard
implementations for some of the required platform porting functions. However, implementations for some of the required platform porting functions. However,
using these functions requires the platform port to implement additional using these functions requires the platform port to implement additional
...@@ -99,56 +99,56 @@ and caches disabled. Examples are given below. ...@@ -99,56 +99,56 @@ and caches disabled. Examples are given below.
The following variables, functions and constants must be defined by the platform The following variables, functions and constants must be defined by the platform
for the firmware to work correctly. 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 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 include path with the following constants defined. This will require updating
the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. 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 which provides typical values for some of the constants below. These values are
likely to be suitable for all platform ports. 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 Defines the linker format used by the platform, for example
``elf64-littleaarch64``. ``elf64-littleaarch64``.
- **#define : PLATFORM\_LINKER\_ARCH** - **#define : PLATFORM_LINKER_ARCH**
Defines the processor architecture for the linker by the platform, for Defines the processor architecture for the linker by the platform, for
example ``aarch64``. example ``aarch64``.
- **#define : PLATFORM\_STACK\_SIZE** - **#define : PLATFORM_STACK_SIZE**
Defines the normal stack memory available to each CPU. This constant is used Defines the normal stack memory available to each CPU. This constant is used
by `plat/common/aarch64/platform\_mp\_stack.S`_ and by `plat/common/aarch64/platform_mp_stack.S`_ and
`plat/common/aarch64/platform\_up\_stack.S`_. `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 Defines the size in bits of the largest cache line across all the cache
levels in the platform. 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()`` Defines the character string printed by BL1 upon entry into the ``bl1_main()``
function. function.
- **#define : PLATFORM\_CORE\_COUNT** - **#define : PLATFORM_CORE_COUNT**
Defines the total number of CPUs implemented by the platform across all Defines the total number of CPUs implemented by the platform across all
clusters in the system. 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 Defines the total number of nodes in the power domain topology
tree at all the power domain levels used by the platform. tree at all the power domain levels used by the platform.
This macro is used by the PSCI implementation to allocate This macro is used by the PSCI implementation to allocate
data structures to represent power domain topology. 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 Defines the maximum power domain level that the power management operations
should apply to. More often, but not always, the power domain level should apply to. More often, but not always, the power domain level
...@@ -158,24 +158,24 @@ likely to be suitable for all platform ports. ...@@ -158,24 +158,24 @@ likely to be suitable for all platform ports.
example, the Base AEM FVP implements two clusters with a configurable example, the Base AEM FVP implements two clusters with a configurable
number of CPUs and it reports the maximum power domain level as 1. 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 Defines the local power state corresponding to the deepest power down
possible at every power domain level in the platform. The local power 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 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 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 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 Defines the local power state corresponding to the deepest retention state
possible at every power domain level in the platform. This macro should be 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 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 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 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. ...@@ -184,69 +184,69 @@ likely to be suitable for all platform ports.
account for more local power states, then it must redefine this macro. account for more local power states, then it must redefine this macro.
Currently, this macro is used by the Generic PSCI implementation to size 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 Defines the base address in secure ROM where BL1 originally lives. Must be
aligned on a page-size boundary. 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. Defines the maximum address in secure ROM that BL1's actual content (i.e.
excluding any data section allocated at runtime) can occupy. 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 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. 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 Defines the maximum address in secure RAM that BL1's read-write data can
occupy at runtime. occupy at runtime.
- **#define : BL2\_BASE** - **#define : BL2_BASE**
Defines the base address in secure RAM where BL1 loads the BL2 binary image. 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 Must be aligned on a page-size boundary. This constant is not applicable
when BL2_IN_XIP_MEM is set to '1'. 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. 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'. 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 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 lives. Must be aligned on a page-size boundary. This constant is only needed
when BL2_IN_XIP_MEM is set to '1'. 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 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 (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'. 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 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 at runtime. Must be aligned on a page-size boundary. This constant is only
needed when BL2_IN_XIP_MEM is set to '1'. 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 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 occupy at runtime. This constant is only needed when BL2_IN_XIP_MEM is set
to '1'. to '1'.
- **#define : BL31\_BASE** - **#define : BL31_BASE**
Defines the base address in secure RAM where BL2 loads the BL31 binary Defines the base address in secure RAM where BL2 loads the BL31 binary
image. Must be aligned on a page-size boundary. 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. 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, ...@@ -258,57 +258,57 @@ information about the image to be loaded (file handler, load address,
authentication information, etc.). The following image identifiers are authentication information, etc.). The following image identifiers are
mandatory: mandatory:
- **#define : BL2\_IMAGE\_ID** - **#define : BL2_IMAGE_ID**
BL2 image identifier, used by BL1 to load BL2. 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. 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. BL33 image identifier, used by BL2 to load BL33.
If Trusted Board Boot is enabled, the following certificate identifiers must If Trusted Board Boot is enabled, the following certificate identifiers must
also be defined: 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 BL2 content certificate identifier, used by BL1 to load the BL2 content
certificate. certificate.
- **#define : TRUSTED\_KEY\_CERT\_ID** - **#define : TRUSTED_KEY_CERT_ID**
Trusted key certificate identifier, used by BL2 to load the trusted key Trusted key certificate identifier, used by BL2 to load the trusted key
certificate. 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 BL31 key certificate identifier, used by BL2 to load the BL31 key
certificate. 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 BL31 content certificate identifier, used by BL2 to load the BL31 content
certificate. 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 BL33 key certificate identifier, used by BL2 to load the BL33 key
certificate. 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 BL33 content certificate identifier, used by BL2 to load the BL33 content
certificate. 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. FWU content certificate.
- **#define : PLAT\_CRYPTOCELL\_BASE** - **#define : PLAT_CRYPTOCELL_BASE**
This defines the base address of Arm® TrustZone® CryptoCell and must be This defines the base address of Arm® TrustZone® CryptoCell and must be
defined if CryptoCell crypto driver is used for Trusted Board Boot. For defined if CryptoCell crypto driver is used for Trusted Board Boot. For
...@@ -318,125 +318,125 @@ also be defined: ...@@ -318,125 +318,125 @@ also be defined:
If the AP Firmware Updater Configuration image, BL2U is used, the following If the AP Firmware Updater Configuration image, BL2U is used, the following
must also be defined: must also be defined:
- **#define : BL2U\_BASE** - **#define : BL2U_BASE**
Defines the base address in secure memory where BL1 copies the BL2U binary Defines the base address in secure memory where BL1 copies the BL2U binary
image. Must be aligned on a page-size boundary. 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. 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 BL2U image identifier, used by BL1 to fetch an image descriptor
corresponding to BL2U. 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: 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 SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
corresponding to SCP\_BL2U. corresponding to SCP_BL2U.
NOTE: TF-A does not provide source code for this image. 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: 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. Must be aligned on a page-size boundary.
NOTE: TF-A does not provide source code for this image. 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 NS_BL1U image identifier, used by BL1 to fetch an image descriptor
corresponding to NS\_BL1U. 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: 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. Must be aligned on a page-size boundary.
NOTE: TF-A does not provide source code for this image. 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 NS_BL2U image identifier, used by BL1 to fetch an image descriptor
corresponding to NS\_BL2U. corresponding to NS_BL2U.
For the the Firmware update capability of TRUSTED BOARD BOOT, the following For the the Firmware update capability of TRUSTED BOARD BOOT, the following
macros may also be defined: 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 Total number of images that can be loaded simultaneously. If the platform
doesn't specify any value, it defaults to 10. 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: 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. 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). 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). content certificate (mandatory when Trusted Board Boot is enabled).
If a BL32 image is supported by the platform, the following constants must If a BL32 image is supported by the platform, the following constants must
also be defined: also be defined:
- **#define : BL32\_IMAGE\_ID** - **#define : BL32_IMAGE_ID**
BL32 image identifier, used by BL2 to load BL32. 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 BL32 key certificate identifier, used by BL2 to load the BL32 key
certificate (mandatory when Trusted Board Boot is enabled). 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 BL32 content certificate identifier, used by BL2 to load the BL32 content
certificate (mandatory when Trusted Board Boot is enabled). 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 Defines the base address in secure memory where BL2 loads the BL32 binary
image. Must be aligned on a page-size boundary. 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. Defines the maximum address that the BL32 image can occupy.
If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
platform, the following constants must also be defined: 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 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``. 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 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 platform. ``TSP_SEC_MEM_BASE`` and ``TSP_SEC_MEM_SIZE`` must fully
accommodate the memory required by the BL32 image, defined by ``BL32_BASE`` accommodate the memory required by the BL32 image, defined by ``BL32_BASE``
and ``BL32_LIMIT``. 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 Defines the ID of the secure physical generic timer interrupt used by the
TSP's interrupt handling code. TSP's interrupt handling code.
...@@ -444,14 +444,14 @@ platform, the following constants must also be defined: ...@@ -444,14 +444,14 @@ platform, the following constants must also be defined:
If the platform port uses the translation table library code, the following If the platform port uses the translation table library code, the following
constants must also be defined: 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 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 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 functionality will be available, if defined and set to 1 it will also
include the dynamic functionality. include the dynamic functionality.
- **#define : MAX\_XLAT\_TABLES** - **#define : MAX_XLAT_TABLES**
Defines the maximum number of translation tables that are allocated by the Defines the maximum number of translation tables that are allocated by the
translation table library code. To minimize the amount of runtime memory translation table library code. To minimize the amount of runtime memory
...@@ -460,7 +460,7 @@ constants must also be defined: ...@@ -460,7 +460,7 @@ constants must also be defined:
image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions
as well. as well.
- **#define : MAX\_MMAP\_REGIONS** - **#define : MAX_MMAP_REGIONS**
Defines the maximum number of regions that are allocated by the translation Defines the maximum number of regions that are allocated by the translation
table library code. A region consists of physical base address, virtual base table library code. A region consists of physical base address, virtual base
...@@ -473,12 +473,12 @@ constants must also be defined: ...@@ -473,12 +473,12 @@ constants must also be defined:
enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate
the dynamic regions as well. 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, 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)``. 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, 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)``. for a 32 bit physical address space, this value should be ``(1ULL << 32)``.
...@@ -486,22 +486,22 @@ constants must also be defined: ...@@ -486,22 +486,22 @@ constants must also be defined:
If the platform port uses the IO storage framework, the following constants If the platform port uses the IO storage framework, the following constants
must also be defined: must also be defined:
- **#define : MAX\_IO\_DEVICES** - **#define : MAX_IO_DEVICES**
Defines the maximum number of registered IO devices. Attempting to register Defines the maximum number of registered IO devices. Attempting to register
more devices than this value using ``io_register_device()`` will fail with more devices than this value using ``io_register_device()`` will fail with
-ENOMEM. -ENOMEM.
- **#define : MAX\_IO\_HANDLES** - **#define : MAX_IO_HANDLES**
Defines the maximum number of open IO handles. Attempting to open more IO Defines the maximum number of open IO handles. Attempting to open more IO
entities than this value using ``io_open()`` will fail with -ENOMEM. 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 Defines the maximum number of registered IO block devices. Attempting to
register more devices this value using ``io_dev_open()`` will fail 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 With this macro, multiple block devices could be supported at the same
time. time.
...@@ -511,7 +511,7 @@ the platform decides not to use the coherent memory section by undefining the ...@@ -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 ``USE_COHERENT_MEM`` build flag. In this case, the framework allocates the
required memory within the the per-cpu data to minimize wastage. 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 Defines the memory (in bytes) to be reserved within the per-cpu data
structure for use by the platform layer. structure for use by the platform layer.
...@@ -519,39 +519,39 @@ required memory within the the per-cpu data to minimize wastage. ...@@ -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 The following constants are optional. They should be defined when the platform
memory layout implies some image overlaying like in Arm standard platforms. 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 Defines the maximum address in secure RAM that the BL31's progbits sections
can occupy. can occupy.
- **#define : TSP\_PROGBITS\_LIMIT** - **#define : TSP_PROGBITS_LIMIT**
Defines the maximum address that the TSP's progbits sections can occupy. 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 If the platform port uses the PL061 GPIO driver, the following constant may
optionally be defined: optionally be defined:
- **PLAT\_PL061\_MAX\_GPIOS** - **PLAT_PL061_MAX_GPIOS**
Maximum number of GPIOs required by the platform. This allows control how Maximum number of GPIOs required by the platform. This allows control how
much memory is allocated for PL061 GPIO controllers. The default value is 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 If the platform port uses the partition driver, the following constant may
optionally be defined: optionally be defined:
- **PLAT\_PARTITION\_MAX\_ENTRIES** - **PLAT_PARTITION_MAX_ENTRIES**
Maximum number of partition entries required by the platform. This allows Maximum number of partition entries required by the platform. This allows
control how much memory is allocated for partition entries. The default control how much memory is allocated for partition entries. The default
value is 128. value is 128.
`For example, define the build flag in platform.mk`_: `For example, define the build flag in platform.mk`_:
PLAT\_PARTITION\_MAX\_ENTRIES := 12 PLAT_PARTITION_MAX_ENTRIES := 12
$(eval $(call add\_define,PLAT\_PARTITION\_MAX\_ENTRIES)) $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES))
The following constant is optional. It should be defined to override the default The following constant is optional. It should be defined to override the default
behaviour of the ``assert()`` function (for example, to save memory). 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``, 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 ``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 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). ...@@ -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 If the platform port uses the Activity Monitor Unit, the following constants
may be defined: 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 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 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 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 counters are enabled. If the platform defines this mask, the following
constant needs to also be defined. 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 This value is used to allocate an array to save and restore the counters
specified by ``PLAT_AMU_GROUP1_COUNTERS_MASK`` on CPU suspend. specified by ``PLAT_AMU_GROUP1_COUNTERS_MASK`` on CPU suspend.
This value should be equal to the highest bit position set in the 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. 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 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 the following macro defined. In the Arm development platforms, this file is
found in ``plat/arm/board/<plat_name>/include/plat_macros.S``. 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 This macro allows the crash reporting routine to print relevant platform
registers in case of an unhandled exception in BL31. This aids in debugging 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: ...@@ -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 The following functions need to be implemented by the platform port to enable
reset vector code to perform the above tasks. 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 ...@@ -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 type of reset nor to query the warm reset entrypoint. Therefore, implementing
this function is not required on such platforms. 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 ...@@ -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 primary CPU will execute the cold boot code. Therefore, implementing this
function is not required on such platforms. 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 ...@@ -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 distinguish between primary and secondary CPUs and implementing this function is
not required. not required.
Function : platform\_mem\_init() [mandatory] Function : platform_mem_init() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -695,8 +695,8 @@ 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 This function is called before any access to data is made by the firmware, in
order to carry out any essential memory initialization. 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: ...@@ -745,8 +745,8 @@ to the ROTPK in the flags parameter:
verifying it against the platform value. This flag verifying it against the platform value. This flag
must not be used in a deployed production environment. 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 ...@@ -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 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 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 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 The function returns 0 on success. Any other value means the counter value could
not be retrieved from the platform. 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() ...@@ -773,14 +773,14 @@ Function: plat\_set\_nv\_ctr()
This function is mandatory when Trusted Board Boot is enabled. It sets a new 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 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 updated counter value to be written to the NV counter.
The function returns 0 on success. Any other value means the counter value could The function returns 0 on success. Any other value means the counter value could
not be updated. not be updated.
Function: plat\_set\_nv\_ctr2() Function: plat_set_nv_ctr2()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -806,8 +806,8 @@ Common mandatory function modifications ...@@ -806,8 +806,8 @@ Common mandatory function modifications
The following functions are mandatory functions which need to be implemented The following functions are mandatory functions which need to be implemented
by the platform port. by the platform port.
Function : plat\_my\_core\_pos() Function : plat_my_core_pos()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -825,8 +825,8 @@ x9 - x29. ...@@ -825,8 +825,8 @@ x9 - x29.
This function plays a crucial role in the power domain topology framework in 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`_. 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 ...@@ -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 common platform-specific tasks. A platform may choose to override these
definitions. 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 ...@@ -863,11 +863,11 @@ of the stack allocated to each CPU is specified by the platform defined
constant ``PLATFORM_STACK_SIZE``. constant ``PLATFORM_STACK_SIZE``.
Common implementations of this function for the UP and MP BL images are Common implementations of this function for the UP and MP BL images are
provided in `plat/common/aarch64/platform\_up\_stack.S`_ and provided in `plat/common/aarch64/platform_up_stack.S`_ and
`plat/common/aarch64/platform\_mp\_stack.S`_ `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 ...@@ -881,11 +881,11 @@ of the stack allocated to each CPU is specified by the platform defined
constant ``PLATFORM_STACK_SIZE``. constant ``PLATFORM_STACK_SIZE``.
Common implementations of this function for the UP and MP BL images are Common implementations of this function for the UP and MP BL images are
provided in `plat/common/aarch64/platform\_up\_stack.S`_ and provided in `plat/common/aarch64/platform_up_stack.S`_ and
`plat/common/aarch64/platform\_mp\_stack.S`_ `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. ...@@ -905,15 +905,15 @@ about the way the platform displays its status information.
For AArch64, this function receives the exception type as its argument. For AArch64, this function receives the exception type as its argument.
Possible values for exceptions types are listed in the 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. related to any architectural exception code; they are just a TF-A convention.
For AArch32, this function receives the exception mode as its argument. For AArch32, this function receives the exception mode as its argument.
Possible values for exception modes are listed in the Possible values for exception modes are listed in the
`include/lib/aarch32/arch.h`_ header file. `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 ...@@ -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 the default implementation, refer to the `Firmware Design`_ for general
guidelines. 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 ...@@ -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 scratch registers. It should preserve the value in x18 register as it is used
by the caller to store the return address. 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: ...@@ -968,8 +968,8 @@ Possible errors reported by the generic code are:
The default implementation simply spins. The default implementation simply spins.
Function : plat\_panic\_handler() Function : plat_panic_handler()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -984,8 +984,8 @@ environment is initialized. ...@@ -984,8 +984,8 @@ environment is initialized.
Note: The address from where it was called is stored in x30 (Link Register). Note: The address from where it was called is stored in x30 (Link Register).
The default implementation simply spins. 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 ...@@ -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 populated to load. This function is invoked in BL2 to load the
BL3xx images. 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 ...@@ -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 function is invoked in BL2 to pass this information to the next BL
image. image.
Function : plat\_get\_stack\_protector\_canary() Function : plat_get_stack_protector_canary()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -1018,7 +1018,7 @@ Function : plat\_get\_stack\_protector\_canary() ...@@ -1018,7 +1018,7 @@ Function : plat\_get\_stack\_protector\_canary()
Return : u_register_t Return : u_register_t
This function returns a random value that is used to initialize the canary used 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 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 value as part of the attack most of the time. Therefore, it should return a
true random number. true random number.
...@@ -1027,8 +1027,8 @@ Note: For the protection to be effective, the global data need to be placed at ...@@ -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 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. 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 ...@@ -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 next image. This function is invoked in BL2 to flush this information
to the next BL image. 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 ...@@ -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 the log output. The implementation should be robust to future changes that
increase the number of log levels. 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: ...@@ -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 The following functions need to be implemented by the platform port to enable
BL1 to perform the above tasks. 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: ...@@ -1138,8 +1138,8 @@ On Arm standard platforms, this function:
the CCI slave interface corresponding to the cluster that includes the the CCI slave interface corresponding to the cluster that includes the
primary CPU. 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. ...@@ -1154,8 +1154,8 @@ In Arm standard platforms, this function enables the MMU.
This function helps fulfill requirement 2 above. 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 ...@@ -1167,15 +1167,15 @@ for performing any remaining platform-specific setup that can occur after the
MMU and data cache have been enabled. MMU and data cache have been enabled.
if support for multiple boot sources is required, it initializes the boot 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 In Arm standard platforms, this function initializes the storage abstraction
layer used to load the next bootloader image. layer used to load the next bootloader image.
This function helps fulfill requirement 4 above. 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. ...@@ -1198,8 +1198,8 @@ its own use.
This function helps fulfill requirements 4 and 5 above. 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 ...@@ -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`` 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. 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` ...@@ -1224,8 +1224,8 @@ This function allows platforms to override ``ep_info`` for the given ``image_id`
The default implementation just returns. 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 ...@@ -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 platforms override this function to detect if firmware update is required, and
if so, return the first image in the firmware update process. 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 ...@@ -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 the firmware update images defined in the Trusted Board Boot Requirements
specification. 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 ...@@ -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 corresponding to ``image_id``. This function is invoked in BL1, both in cold
boot and FWU code path, before loading the image. 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 ...@@ -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 of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint
information to BL2. 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. ...@@ -1304,8 +1304,8 @@ example to initiate the normal boot flow.
The default implementation spins forever. 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. ...@@ -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 The following functions must be implemented by the platform port to enable BL2
to perform the above tasks. 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: ...@@ -1367,11 +1367,11 @@ On Arm standard platforms, this function also:
family of functions in BL2. family of functions in BL2.
- Initializes the storage abstraction layer used to load further bootloader - 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, 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. 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. ...@@ -1386,8 +1386,8 @@ that varies across platforms.
On Arm standard platforms, this function enables the MMU. 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 ...@@ -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 configuration of the TrustZone controller to allow non-secure masters access
to most of DRAM. Part of DRAM is reserved for secure world use. 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 ...@@ -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 for given ``image_id``. This function is currently invoked in BL2 before
loading each image. 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 ...@@ -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 for given ``image_id``. This function is currently invoked in BL2 after
loading each image. 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] ...@@ -1439,12 +1439,12 @@ Function : bl2\_plat\_preload\_setup [optional]
This optional function performs any BL2 platform initialization This optional function performs any BL2 platform initialization
required before image loading, that is not done later in 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 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 ...@@ -1468,14 +1468,14 @@ execute at EL3 instead of executing at EL1. Refer to the `Firmware
Design`_ for more information. Design`_ for more information.
All mandatory functions of BL2 must be implemented, except the functions All mandatory functions of BL2 must be implemented, except the functions
bl2\_early\_platform\_setup and bl2\_el3\_plat\_arch\_setup, because bl2_early_platform_setup and bl2_el3_plat_arch_setup, because
their work is done now by bl2\_el3\_early\_platform\_setup and their work is done now by bl2_el3_early_platform_setup and
bl2\_el3\_plat\_arch\_setup. These functions should generally implement bl2_el3_plat_arch_setup. These functions should generally implement
the bl1\_plat\_xxx() and bl2\_plat\_xxx() functionality combined. 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: ...@@ -1492,13 +1492,13 @@ On Arm standard platforms, this function does the following:
family of functions in BL2. family of functions in BL2.
- Initializes the storage abstraction layer used to load further bootloader - 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, 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. since the later ``bl2_platform_setup`` must be done after SCP_BL2 is loaded.
- Initializes the private variables that define the memory layout used. - 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. ...@@ -1513,8 +1513,8 @@ that varies across platforms.
On Arm standard platforms, this function enables the MMU. 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 ...@@ -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 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: ``BL2U_BASE``. BL2U executes in Secure-EL1 and is responsible for:
#. (Optional) Transferring the optional SCP\_BL2U binary image from AP secure #. (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. 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 ``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 should be copied from. Subsequent handling of the SCP_BL2U image is
implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function. implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function.
If ``SCP_BL2U_BASE`` is not defined then this step is not performed. 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 ...@@ -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 The following functions must be implemented by the platform port to enable
BL2U to perform the tasks mentioned above. 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 ...@@ -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. 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, 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. 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 ...@@ -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 that varies across platforms, for example enabling the MMU (since the memory
map differs across platforms). 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 ...@@ -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 configuration of the TrustZone controller to allow non-secure masters access
to most of DRAM. Part of DRAM is reserved for secure world use. 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 ...@@ -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. Application Processor (AP) for BL2U execution to continue.
This function returns 0 on success, a negative error code otherwise. 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) Boot Loader Stage 3-1 (BL31)
---------------------------- ----------------------------
...@@ -1650,8 +1650,8 @@ section 2.2 before the tasks described above. ...@@ -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 The following functions must be implemented by the platform port to enable BL31
to perform the above tasks. 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: ...@@ -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 CCI slave interface corresponding to the cluster that includes the primary
CPU. CPU.
Function : bl31\_plat\_arch\_setup() [mandatory] Function : bl31_plat_arch_setup() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -1700,7 +1700,7 @@ that varies across platforms. ...@@ -1700,7 +1700,7 @@ that varies across platforms.
On Arm standard platforms, this function enables the MMU. 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: ...@@ -1742,8 +1742,8 @@ On Arm standard platforms, this function does the following:
In particular, initialise the locks that prevent concurrent accesses to the In particular, initialise the locks that prevent concurrent accesses to the
power controller device. 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 ...@@ -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 implementation of this function will invoke ``console_switch_state()`` to switch
console output to consoles marked for use in the ``runtime`` state. 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 ...@@ -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 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. 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 ...@@ -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 of the system counter, which is retrieved from the first entry in the frequency
modes table. 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 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 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. ...@@ -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. 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 ...@@ -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 statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
default implementation will use PMF to capture timestamps. 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 ...@@ -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 statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
default implementation will use PMF to capture timestamps. 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 ...@@ -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 CPU in the power domain to suspend and may be needed to calculate the residency
for that power domain. 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 ...@@ -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 coordinated target local power state for a power domain will be the minimum
of the requested local power state values. 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 ...@@ -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 described in `Power Domain Topology Design`_. The BL31 PSCI initialization code
requires this array to be described by the platform, either statically or requires this array to be described by the platform, either statically or
dynamically, to initialize the power domain topology tree. In case the array dynamically, to initialize the power domain topology tree. In case the array
is populated dynamically, then plat\_core\_pos\_by\_mpidr() and is populated dynamically, then plat_core_pos_by_mpidr() and
plat\_my\_core\_pos() should also be implemented suitably so that the topology 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 tree description matches the CPU indices returned by these APIs. These APIs
together form the platform interface for the PSCI topology framework. 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. ...@@ -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 A description of each member of this structure is given below. Please refer to
the Arm FVP specific implementation of these handlers in 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 platform wants to support, the associated operation or operations in this
structure must be provided and implemented (Refer section 4 of structure must be provided and implemented (Refer section 4 of
`Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI `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 function in a platform port, the operation should be removed from this
structure instead of providing an empty implementation. 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 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 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 ...@@ -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 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. 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 Perform the platform specific actions to power on a CPU, specified
by the ``MPIDR`` (first argument). The generic code expects the platform to 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 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`` 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 ...@@ -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 for the higher power domain levels depending on the result of state
coordination. The generic code expects the handler to succeed. 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 This optional function may be used as a performance optimization to replace
or complement pwr_domain_suspend() on some platforms. Its calling semantics 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 ...@@ -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 = 1, data caches remain enabled throughout, and so there is no advantage to
moving platform specific actions to this function. 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 Perform the platform specific actions to prepare to suspend the calling
CPU and its higher parent power domain levels as indicated by the 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 ...@@ -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 data, for example in DRAM. The Distributor can then be powered down using an
implementation-defined sequence. 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 This is an optional function and, if implemented, is expected to perform
platform specific actions including the ``wfi`` invocation which allows the platform specific actions including the ``wfi`` invocation which allows the
...@@ -2167,8 +2167,8 @@ not return back to the caller. ...@@ -2167,8 +2167,8 @@ not return back to the caller.
If this function is not implemented by the platform, PSCI generic If this function is not implemented by the platform, PSCI generic
implementation invokes ``psci_power_down_wfi()`` for power down. 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 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. 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 ...@@ -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 above the CPU might require initialization due to having previously been in
low power states. The generic code expects the handler to succeed. 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 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 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 ...@@ -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 suspend, their context must be restored in this function in the reverse order
to how they were saved during suspend sequence. 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`` This function is called by PSCI implementation in response to a ``SYSTEM_OFF``
call. It performs the platform-specific system poweroff sequence after call. It performs the platform-specific system poweroff sequence after
notifying the Secure Payload Dispatcher. 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`` This function is called by PSCI implementation in response to a ``SYSTEM_RESET``
call. It performs the platform-specific system reset sequence after call. It performs the platform-specific system reset sequence after
notifying the Secure Payload Dispatcher. 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`` 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, 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 populate it in ``req_state`` (second argument) array as power domain level
specific local states. If the ``power_state`` is invalid, the platform must 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. 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``, 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`` ``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, 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. 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`` 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 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 ...@@ -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 ``pwr_domain_suspend()`` will be invoked with the coordinated target state to
enter system suspend. 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 This is an optional function and, if implemented, is invoked by the PSCI
implementation to convert the ``local_state`` (first argument) at a specified 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 ...@@ -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 ``PLAT_MAX_PWR_LVL_STATES`` is greater than 2, and needs to account for these
local power states. 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`` This is an optional function and, if implemented, verifies the ``power_state``
(second argument) parameter of the PSCI API corresponding to a target power (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 ...@@ -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 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 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 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 function is not implemented, then the generic implementation relies on
``validate_power_state`` function to translate the ``power_state``. ``validate_power_state`` function to translate the ``power_state``.
This function can also be used in case the platform wants to support local 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`_. 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 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 the power state of a node (identified by the first parameter, the ``MPIDR``) in
...@@ -2288,8 +2288,8 @@ appropriate. ...@@ -2288,8 +2288,8 @@ appropriate.
Implementations are not expected to handle ``power_levels`` greater than Implementations are not expected to handle ``power_levels`` greater than
``PLAT_MAX_PWR_LVL``. ``PLAT_MAX_PWR_LVL``.
plat\_psci\_ops.system\_reset2() plat_psci_ops.system_reset2()
................................ .............................
This is an optional function. If implemented this function is This is an optional function. If implemented this function is
called during the ``SYSTEM_RESET2`` call to perform a reset called during the ``SYSTEM_RESET2`` call to perform a reset
...@@ -2301,8 +2301,8 @@ resets, all failures must return ``PSCI_E_INVALID_PARAMETERS`` ...@@ -2301,8 +2301,8 @@ resets, all failures must return ``PSCI_E_INVALID_PARAMETERS``
and vendor reset can return other PSCI error codes as defined and vendor reset can return other PSCI error codes as defined
in `PSCI`_. On success this function will not return. 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 This is an optional function. If implemented it enables or disables the
``MEM_PROTECT`` functionality based on the value of ``val``. ``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 ...@@ -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 disables it. Upon encountering failures it must return a negative value
and on success it must return 0. 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 This is an optional function. If implemented it returns the current
state of ``MEM_PROTECT`` via the ``val`` parameter. Upon encountering state of ``MEM_PROTECT`` via the ``val`` parameter. Upon encountering
failures it must return a negative value and on success it must failures it must return a negative value and on success it must
return 0. 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 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`` region defined by a base address ``base`` and with a size of ``length``
...@@ -2348,8 +2348,8 @@ See also: `Interrupt Controller Abstraction APIs`__. ...@@ -2348,8 +2348,8 @@ See also: `Interrupt Controller Abstraction APIs`__.
.. __: platform-interrupt-controller-API.rst .. __: 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: ...@@ -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 - The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2
context. 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. ...@@ -2417,8 +2417,8 @@ depends upon the id value as follows.
#. id = ``GIC_SPURIOUS_INTERRUPT`` (1023) is reported as an invalid interrupt type. #. id = ``GIC_SPURIOUS_INTERRUPT`` (1023) is reported as an invalid interrupt type.
#. All other interrupt id's are reported as EL3 interrupt. #. 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. ...@@ -2456,11 +2456,11 @@ interrupt controller as follows.
When the API invoked from S-EL1 for GICv3 systems, the id read from system 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 ``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. ``INTR_ID_UNAVAILABLE`` is returned.
Function : plat\_ic\_acknowledge\_interrupt() [mandatory] Function : plat_ic_acknowledge_interrupt() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -2491,8 +2491,8 @@ unmodified. ...@@ -2491,8 +2491,8 @@ unmodified.
The TSP uses this API to start processing of the secure physical timer The TSP uses this API to start processing of the secure physical timer
interrupt. interrupt.
Function : plat\_ic\_end\_of\_interrupt() [mandatory] Function : plat_ic_end_of_interrupt() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:: ::
...@@ -2513,8 +2513,8 @@ controller. ...@@ -2513,8 +2513,8 @@ controller.
The TSP uses this API to finish processing of the secure physical timer The TSP uses this API to finish processing of the secure physical timer
interrupt. 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`` ...@@ -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) that are designed to be used by these functions. See Arm platforms (like juno)
for an example of this. 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 ...@@ -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 console. It must only use the general purpose registers x0 through x7 to do the
initialization and returns 1 on success. 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 ...@@ -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 x2 to do its work. The parameter and the return value are in general purpose
register x0. 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 ...@@ -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 need to be defined in the platform makefile which will get included by the
build system. build system.
- **NEED\_BL33** - **NEED_BL33**
By default, this flag is defined ``yes`` by the build system and ``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 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 option of excluding the BL33 image in the ``fip`` image by defining this flag
...@@ -2770,7 +2770,7 @@ operations such as loading a bootloader image. ...@@ -2770,7 +2770,7 @@ operations such as loading a bootloader image.
The current implementation only allows for known images to be loaded by the 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 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 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 a device and a driver-specific ``spec`` which will be understood by the driver
to allow access to the image data. to allow access to the image data.
...@@ -2791,19 +2791,19 @@ amount of open resources per driver. ...@@ -2791,19 +2791,19 @@ amount of open resources per driver.
*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _include/plat/common/platform.h: ../include/plat/common/platform.h .. _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 .. _User Guide: user-guide.rst
.. _include/plat/common/common\_def.h: ../include/plat/common/common_def.h .. _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 .. _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_mp_stack.S: ../plat/common/aarch64/platform_mp_stack.S
.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_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 .. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160
.. _Power Domain Topology Design: psci-pd-tree.rst .. _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 .. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h
.. _Firmware Design: firmware-design.rst .. _Firmware Design: firmware-design.rst
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _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 .. _Platform compatibility policy: ./platform-compatibility-policy.rst
.. _IMF Design Guide: interrupt-framework-design.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 .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment