diff options
Diffstat (limited to 'docs/plat/arm')
| -rw-r--r-- | docs/plat/arm/arm-build-options.rst | 159 | ||||
| -rw-r--r-- | docs/plat/arm/arm_fpga/index.rst | 97 | ||||
| -rw-r--r-- | docs/plat/arm/corstone1000/index.rst | 61 | ||||
| -rw-r--r-- | docs/plat/arm/fvp-ve/index.rst | 84 | ||||
| -rw-r--r-- | docs/plat/arm/fvp/index.rst | 639 | ||||
| -rw-r--r-- | docs/plat/arm/fvp_r/index.rst | 46 | ||||
| -rw-r--r-- | docs/plat/arm/index.rst | 24 | ||||
| -rw-r--r-- | docs/plat/arm/juno/index.rst | 252 | ||||
| -rw-r--r-- | docs/plat/arm/morello/index.rst | 43 | ||||
| -rw-r--r-- | docs/plat/arm/tc/index.rst | 62 |
10 files changed, 1467 insertions, 0 deletions
diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst new file mode 100644 index 0000000..3301067 --- /dev/null +++ b/docs/plat/arm/arm-build-options.rst @@ -0,0 +1,159 @@ +Arm Development Platform Build Options +====================================== + +Arm Platform Build Options +-------------------------- + +- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured + DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load + BL31 in TZC secured DRAM. If TSP is present, then setting this option also + sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build + flag. + +- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>`` + frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The + frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which + should match the frame used by the Non-Secure image (normally the Linux + kernel). Default is true (access to the frame is allowed). + +- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog. + By default, Arm platforms use a watchdog to trigger a system reset in case + an error is encountered during the boot process (for example, when an image + could not be loaded or authenticated). The watchdog is enabled in the early + platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The + Trusted Watchdog may be disabled at build time for testing or development + purposes. + +- ``ARM_LINUX_KERNEL_AS_BL33``: The Linux kernel expects registers x0-x3 to + have specific values at boot. This boolean option allows the Trusted Firmware + to have a Linux kernel image as BL33 by preparing the registers to these + values before jumping to BL33. This option defaults to 0 (disabled). For + AArch64 ``RESET_TO_BL31`` and for AArch32 ``RESET_TO_SP_MIN`` must be 1 when + using it. If this option is set to 1, ``ARM_PRELOADED_DTB_BASE`` must be set + to the location of a device tree blob (DTB) already loaded in memory. The + Linux Image address must be specified using the ``PRELOADED_BL33_BASE`` + option. + +- ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to + cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag + is set, the functions which deal with MPIDR assume that the ``MT`` bit in + MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of + this flag is 0. Note that this option is not used on FVP platforms. + +- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding + for the construction of composite state-ID in the power-state parameter. + The existing PSCI clients currently do not support this encoding of + State-ID yet. Hence this flag is used to configure whether to use the + recommended State-ID encoding or not. The default value of this flag is 0, + in which case the platform is configured to expect NULL in the State-ID + field of power-state parameter. + +- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the + location of the ROTPK returned by the function ``plat_get_rotpk_info()`` + for Arm platforms. Depending on the selected option, the proper private key + must be specified using the ``ROT_KEY`` option when building the Trusted + Firmware. This private key will be used by the certificate generation tool + to sign the BL2 and Trusted Key certificates. Available options for + ``ARM_ROTPK_LOCATION`` are: + + - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage + registers. + - ``devel_rsa`` : return a development public key hash embedded in the BL1 + and BL2 binaries. This hash has been obtained from the RSA public key + ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use + this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` + when creating the certificates. + - ``devel_ecdsa`` : return a development public key hash embedded in the BL1 + and BL2 binaries. This hash has been obtained from the ECDSA public key + ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To + use this option, ``arm_rotprivk_ecdsa.pem`` must be specified as + ``ROT_KEY`` when creating the certificates. + - ``devel_full_dev_rsa_key`` : returns a development public key embedded in + the BL1 and BL2 binaries. This key has been obtained from the RSA public + key ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. + +- ``ARM_ROTPK_HASH``: used when ``ARM_ROTPK_LOCATION=devel_*``, excluding + ``devel_full_dev_rsa_key``. Specifies the location of the ROTPK hash. Not + expected to be a build option. This defaults to + ``plat/arm/board/common/rotpk/*_sha256.bin`` depending on the specified + algorithm. Providing ``ROT_KEY`` enforces generation of the hash from the + ``ROT_KEY`` and overwrites the default hash file. + +- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options: + + - ``tsram`` : Trusted SRAM (default option when TBB is not enabled) + - ``tdram`` : Trusted DRAM (if available) + - ``dram`` : Secure region in DRAM (default option when TBB is enabled, + configured by the TrustZone controller) + +- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile TF-A with version 1 + of the translation tables library instead of version 2. It is set to 0 by + default, which selects version 2. + +- ``ARM_GPT_SUPPORT``: Enable GPT parser to get the entry address and length of + the various partitions present in the GPT image. This support is available + only for the BL2 component, and it is disabled by default. + The following diagram shows the view of the FIP partition inside the GPT + image: + + |FIP in a GPT image| + +For a better understanding of these options, the Arm development platform memory +map is explained in the :ref:`Firmware Design`. + +.. _build_options_arm_css_platform: + +Arm CSS Platform-Specific Build Options +--------------------------------------- + +- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version + incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards + compatible change to the MTL protocol, used for AP/SCP communication. + TF-A no longer supports earlier SCP versions. If this option is set to 1 + then TF-A will detect if an earlier version is in use. Default is 1. + +- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP_BL2 and + SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded + during boot. Default is 1. + +- ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers + instead of SCPI/BOM driver for communicating with the SCP during power + management operations and for SCP RAM Firmware transfer. If this option + is set to 1, then SCMI/SDS drivers will be used. Default is 0. + + - ``CSS_SGI_CHIP_COUNT``: Configures the number of chips on a SGI/RD platform + which supports multi-chip operation. If ``CSS_SGI_CHIP_COUNT`` is set to any + valid value greater than 1, the platform code performs required configuration + to support multi-chip operation. + +- ``CSS_SGI_PLATFORM_VARIANT``: Selects the variant of a SGI/RD platform. A + particular SGI/RD platform may have multiple variants which may differ in + core count, cluster count or other peripherals. This build option is used + to select the appropriate platform variant for the build. The range of + valid values is platform specific. + +- ``CSS_SYSTEM_GRACEFUL_RESET``: Build option to enable graceful powerdown of + CPU core on reset. This build option can be used on CSS platforms that + require all the CPUs to execute the CPU specific power down sequence to + complete a warm reboot sequence in which only the CPUs are power cycled. + +Arm FVP Build Options +--------------------- + +- ``FVP_TRUSTED_SRAM_SIZE``: Size (in kilobytes) of the Trusted SRAM region to + utilize when building for the FVP platform. This option defaults to 256. + +Arm Juno Build Options +---------------------- + +- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3 + runtime software in AArch32 mode, which is required to run AArch32 on Juno. + By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in + AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable + images. + +-------------- + +.. |FIP in a GPT image| image:: ../../resources/diagrams/FIP_in_a_GPT_image.png + +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/arm_fpga/index.rst b/docs/plat/arm/arm_fpga/index.rst new file mode 100644 index 0000000..5427c1d --- /dev/null +++ b/docs/plat/arm/arm_fpga/index.rst @@ -0,0 +1,97 @@ +Arm FPGA Platform +================= + +This platform supports FPGA images used internally in Arm Ltd., for +testing and bringup of new cores. With that focus, peripheral support is +minimal: there is no mass storage or display output, for instance. Also +this port ignores any power management features of the platform. +Some interconnect setup is done internally by the platform, so the TF-A code +just needs to setup UART and GIC. + +The FPGA platform requires to pass on a DTB for the non-secure payload +(mostly Linux), so we let TF-A use information from the DTB for dynamic +configuration: the UART and GIC base addresses are read from there. + +As a result this port is a fairly generic BL31-only port, which can serve +as a template for a minimal new (and possibly DT-based) platform port. + +The aim of this port is to support as many FPGA images as possible with +a single build. Image specific data must be described in the DTB or should +be auto-detected at runtime. + +As the number and topology layout of the CPU cores differs significantly +across the various images, this is detected at runtime by BL31. +The /cpus node in the DT will be added and filled accordingly, as long as +it does not exist already. + +Platform-specific build options +------------------------------- + +- ``SUPPORT_UNKNOWN_MPID`` : Boolean option to allow unknown MPIDR registers. + Normally TF-A panics if it encounters a MPID value not matched to its + internal list, but for new or experimental cores this creates a lot of + churn. With this option, the code will fall back to some basic CPU support + code (only architectural system registers, and no errata). + Default value of this flag is 1. + +- ``PRELOADED_BL33_BASE`` : Physical address of the BL33 non-secure payload. + It must have been loaded into DRAM already, typically this is done by + the script that also loads BL31 and the DTB. + It defaults to 0x80080000, which is the traditional load address for an + arm64 Linux kernel. + +- ``FPGA_PRELOADED_DTB_BASE`` : Physical address of the flattened device + tree blob (DTB). This DT will be used by TF-A for dynamic configuration, + so it must describe at least the UART and a GICv3 interrupt controller. + The DT gets amended by the code, to potentially add a command line and + fill the CPU topology nodes. It will also be passed on to BL33, by + putting its address into the x0 register before jumping to the entry + point (following the Linux kernel boot protocol). + It defaults to 0x80070000, which is 64KB before the BL33 load address. + +- ``FPGA_PRELOADED_CMD_LINE`` : Physical address of the command line to + put into the devicetree blob. Due to the lack of a proper bootloader, + a command line can be put somewhere into memory, so that BL31 will + detect it and copy it into the DTB passed on to BL33. + To avoid random garbage, there needs to be a "CMD:" signature before the + actual command line. + Defaults to 0x1000, which is normally in the "ROM" space of the typical + FPGA image (which can be written by the FPGA payload uploader, but is + read-only to the CPU). The FPGA payload tool should be given a text file + containing the desired command line, prefixed by the "CMD:" signature. + +Building the TF-A image +----------------------- + + .. code:: shell + + make PLAT=arm_fgpa DEBUG=1 + + This will use the default load addresses as described above. When those + addresses need to differ for a certain setup, they can be passed on the + make command line: + + .. code:: shell + + make PLAT=arm_fgpa DEBUG=1 PRELOADED_BL33_BASE=0x80200000 FPGA_PRELOADED_DTB_BASE=0x80180000 bl31 + +Running the TF-A image +---------------------- + +After building TF-A, the actual TF-A code will be located in ``bl31.bin`` in +the build directory. +Additionally there is a ``bl31.axf`` ELF file, which contains BL31, as well +as some simple ROM trampoline code (required by the Arm FPGA boot flow) and +a generic DTB to support most of the FPGA images. This can be simply handed +over to the FPGA payload uploader, which will take care of loading the +components at their respective load addresses. In addition to this file +you need at least a BL33 payload (typically a Linux kernel image), optionally +a Linux initrd image file and possibly a command line: + + .. code:: shell + + fpga-run ... -m bl31.axf -l auto -m Image -l 0x80080000 -m initrd.gz -l 0x84000000 -m cmdline.txt -l 0x1000 + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/corstone1000/index.rst b/docs/plat/arm/corstone1000/index.rst new file mode 100644 index 0000000..dc626e1 --- /dev/null +++ b/docs/plat/arm/corstone1000/index.rst @@ -0,0 +1,61 @@ +Corstone1000 Platform +========================== + +Some of the features of the Corstone1000 platform referenced in TF-A include: + +- Cortex-A35 application processor (64-bit mode) +- Secure Enclave +- GIC-400 +- Trusted Board Boot + +Boot Sequence +------------- + +The board boot relies on CoT (chain of trust). The trusted-firmware-a +BL2 is extracted from the FIP and verified by the Secure Enclave +processor. BL2 verification relies on the signature area at the +beginning of the BL2 image. This area is needed by the SecureEnclave +bootloader. + +Then, the application processor is released from reset and starts by +executing BL2. + +BL2 performs the actions described in the trusted-firmware-a TBB design +document. + +Build Procedure (TF-A only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Obtain AArch64 ELF bare-metal target `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + make LD=aarch64-none-elf-ld \ + CC=aarch64-none-elf-gcc \ + V=1 \ + BUILD_BASE=<path to the build folder> \ + PLAT=corstone1000 \ + SPD=spmd \ + SPMD_SPM_AT_SEL2=0 \ + DEBUG=1 \ + MBEDTLS_DIR=mbedtls \ + OPENSSL_DIR=<path to openssl usr folder> \ + RUNTIME_SYSROOT=<path to the sysroot> \ + ARCH=aarch64 \ + TARGET_PLATFORM=<fpga or fvp> \ + ENABLE_PIE=1 \ + RESET_TO_BL2=1 \ + CREATE_KEYS=1 \ + GENERATE_COT=1 \ + TRUSTED_BOARD_BOOT=1 \ + COT=tbbr \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ + BL32=<path to optee binary> \ + BL33=<path to u-boot binary> \ + bl2 + +*Copyright (c) 2021-2023, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/fvp-ve/index.rst b/docs/plat/arm/fvp-ve/index.rst new file mode 100644 index 0000000..8ac0741 --- /dev/null +++ b/docs/plat/arm/fvp-ve/index.rst @@ -0,0 +1,84 @@ +Arm Versatile Express +===================== + +Versatile Express (VE) family development platform provides an ultra fast +environment for prototyping Armv7 System-on-Chip designs. VE Fixed Virtual +Platforms (FVP) are simulations of Versatile Express boards. The platform in +Trusted Firmware-A has been verified with Arm Cortex-A5 and Cortex-A7 VE FVP's. +This platform is tested on and only expected to work with single core models. + +Boot Sequence +------------- + +BL1 --> BL2 --> BL32(sp_min) --> BL33(u-boot) --> Linux kernel + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ +- `U-boot <https://git.linaro.org/landing-teams/working/arm/u-boot.git>`__ + +- `Trusted Firmware-A <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Obtain arm toolchain. The software stack has been verified with linaro 6.2 + `arm-linux-gnueabihf <https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/>`__. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Fetch and build u-boot. + Make the .config file using the command: + + .. code:: shell + + make ARCH=arm vexpress_aemv8a_aarch32_config + + Make the u-boot binary for Cortex-A5 using the command: + + .. code:: shell + + make ARCH=arm SUPPORT_ARCH_TIMER=no + + Make the u-boot binary for Cortex-A7 using the command: + + .. code:: shell + + make ARCH=arm + + +- Build TF-A: + + The make command for Cortex-A5 is: + + .. code:: shell + + make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A5=yes \ + AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A5x1.dts \ + ARM_XLAT_TABLES_LIB_V1=1 BL33=<path_to_u-boot.bin> all fip + + The make command for Cortex-A7 is: + + .. code:: shell + + make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A7=yes \ + AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A7x1.dts \ + BL33=<path_to_u-boot.bin> all fip + +Run Procedure +~~~~~~~~~~~~~ + +The following model parameters should be used to boot Linux using the build of +Trusted Firmware-A made using the above make commands: + + .. code:: shell + + ./<path_to_model> <path_to_bl1.elf> \ + -C motherboard.flashloader1.fname=<path_to_fip.bin> \ + --data cluster.cpu0=<path_to_zImage>@0x80080000 \ + --data cluster.cpu0=<path_to_ramdisk>@0x84000000 + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/fvp/index.rst b/docs/plat/arm/fvp/index.rst new file mode 100644 index 0000000..700020f --- /dev/null +++ b/docs/plat/arm/fvp/index.rst @@ -0,0 +1,639 @@ +Arm Fixed Virtual Platforms (FVP) +================================= + +Fixed Virtual Platform (FVP) Support +------------------------------------ + +This section lists the supported Arm |FVP| platforms. Please refer to the FVP +documentation for a detailed description of the model parameter options. + +The latest version of the AArch64 build of TF-A has been tested on the following +Arm FVPs without shifted affinities, and that do not support threaded CPU cores +(64-bit host machine only). + +.. note:: + The FVP models used are Version 11.22 Build 14, unless otherwise stated. + +- ``Foundation_Platform`` +- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` (Version 11.17/21) +- ``FVP_Base_AEMv8A-GIC600AE`` (Version 11.17/21) +- ``FVP_Base_AEMvA`` +- ``FVP_Base_AEMvA-AEMvA`` +- ``FVP_Base_Cortex-A32x4`` (Version 11.12/38) +- ``FVP_Base_Cortex-A35x4`` +- ``FVP_Base_Cortex-A53x4`` +- ``FVP_Base_Cortex-A55`` +- ``FVP_Base_Cortex-A55x4+Cortex-A75x4`` +- ``FVP_Base_Cortex-A55x4+Cortex-A76x2`` +- ``FVP_Base_Cortex-A57x1-A53x1`` +- ``FVP_Base_Cortex-A57x2-A53x4`` +- ``FVP_Base_Cortex-A57x4`` +- ``FVP_Base_Cortex-A57x4-A53x4`` +- ``FVP_Base_Cortex-A65`` +- ``FVP_Base_Cortex-A65AE`` +- ``FVP_Base_Cortex-A710x4`` (Version 11.17/21) +- ``FVP_Base_Cortex-A72x4`` +- ``FVP_Base_Cortex-A72x4-A53x4`` +- ``FVP_Base_Cortex-A73x4`` +- ``FVP_Base_Cortex-A73x4-A53x4`` +- ``FVP_Base_Cortex-A75`` +- ``FVP_Base_Cortex-A76`` +- ``FVP_Base_Cortex-A76AE`` +- ``FVP_Base_Cortex-A77`` +- ``FVP_Base_Cortex-A78`` +- ``FVP_Base_Cortex-A78AE`` +- ``FVP_Base_Cortex-A78C`` +- ``FVP_Base_Cortex-X2x4`` (Version 11.17/21) +- ``FVP_Base_Neoverse-E1`` +- ``FVP_Base_Neoverse-N1`` +- ``FVP_Base_Neoverse-V1`` +- ``FVP_Base_RevC-2xAEMvA`` +- ``FVP_BaseR_AEMv8R`` +- ``FVP_Morello`` (Version 0.11/33) +- ``FVP_RD_V1`` +- ``FVP_TC1`` +- ``FVP_TC2`` (Version 11.20/24) + +The latest version of the AArch32 build of TF-A has been tested on the +following Arm FVPs without shifted affinities, and that do not support threaded +CPU cores (64-bit host machine only). + +- ``FVP_Base_AEMvA`` +- ``FVP_Base_AEMvA-AEMvA`` +- ``FVP_Base_Cortex-A32x4`` + +.. note:: + The ``FVP_Base_RevC-2xAEMvA`` FVP only supports shifted affinities, which + is not compatible with legacy GIC configurations. Therefore this FVP does not + support these legacy GIC configurations. + +The *Foundation* and *Base* FVPs can be downloaded free of charge. See the `Arm +FVP website`_. The Cortex-A models listed above are also available to download +from `Arm's website`_. + +.. note:: + The build numbers quoted above are those reported by launching the FVP + with the ``--version`` parameter. + +.. note:: + Linaro provides a ramdisk image in prebuilt FVP configurations and full + file systems that can be downloaded separately. To run an FVP with a virtio + file system image an additional FVP configuration option + ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be + used. + +.. note:: + The software will not work on Version 1.0 of the Foundation FVP. + The commands below would report an ``unhandled argument`` error in this case. + +.. note:: + FVPs can be launched with ``--cadi-server`` option such that a + CADI-compliant debugger (for example, Arm DS-5) can connect to and control + its execution. + +.. warning:: + Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 + the internal synchronisation timings changed compared to older versions of + the models. The models can be launched with ``-Q 100`` option if they are + required to match the run time characteristics of the older versions. + +All the above platforms have been tested with `Linaro Release 20.01`_. + +.. _build_options_arm_fvp_platform: + +Arm FVP Platform Specific Build Options +--------------------------------------- + +- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to + build the topology tree within TF-A. By default TF-A is configured for dual + cluster topology and this option can be used to override the default value. + +- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The + default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as + explained in the options below: + + - ``FVP_CCI`` : The CCI driver is selected. This is the default + if 0 < ``FVP_CLUSTER_COUNT`` <= 2. + - ``FVP_CCN`` : The CCN driver is selected. This is the default + if ``FVP_CLUSTER_COUNT`` > 2. + +- ``FVP_MAX_CPUS_PER_CLUSTER``: Sets the maximum number of CPUs implemented in + a single cluster. This option defaults to 4. + +- ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU + in the system. This option defaults to 1. Note that the build option + ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms. + +- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options: + + - ``FVP_GICV2`` : The GICv2 only driver is selected + - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) + +- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled + to DTB and packaged in FIP as the HW_CONFIG. See :ref:`Firmware Design` for + details on HW_CONFIG. By default, this is initialized to a sensible DTS + file in ``fdts/`` folder depending on other build options. But some cases, + like shifted affinity format for MPIDR, cannot be detected at build time + and this option is needed to specify the appropriate DTS file. + +- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in + FIP. See :ref:`Firmware Design` for details on HW_CONFIG. This option is + similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the + HW_CONFIG blob instead of the DTS file. This option is useful to override + the default HW_CONFIG selected by the build system. + +- ``FVP_GICR_REGION_PROTECTION``: Mark the redistributor pages of + inactive/fused CPU cores as read-only. The default value of this option + is ``0``, which means the redistributor pages of all CPU cores are marked + as read and write. + +Booting Firmware Update images +------------------------------ + +When Firmware Update (FWU) is enabled there are at least 2 new images +that have to be loaded, the Non-Secure FWU ROM (NS-BL1U), and the +FWU FIP. + +The additional fip images must be loaded with: + +:: + + --data cluster0.cpu0="<path_to>/ns_bl1u.bin"@0x0beb8000 [ns_bl1u_base_address] + --data cluster0.cpu0="<path_to>/fwu_fip.bin"@0x08400000 [ns_bl2u_base_address] + +The address ns_bl1u_base_address is the value of NS_BL1U_BASE. +In the same way, the address ns_bl2u_base_address is the value of +NS_BL2U_BASE. + +Booting an EL3 payload +---------------------- + +The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for +the secondary CPUs holding pen to work properly. Unfortunately, its reset value +is undefined on the FVP platform and the FVP platform code doesn't clear it. +Therefore, one must modify the way the model is normally invoked in order to +clear the mailbox at start-up. + +One way to do that is to create an 8-byte file containing all zero bytes using +the following command: + +.. code:: shell + + dd if=/dev/zero of=mailbox.dat bs=1 count=8 + +and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``) +using the following model parameters: + +:: + + --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs] + --data=mailbox.dat@0x04000000 [Foundation FVP] + +To provide the model with the EL3 payload image, the following methods may be +used: + +#. If the EL3 payload is able to execute in place, it may be programmed into + flash memory. On Base Cortex and AEM FVPs, the following model parameter + loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already + used for the FIP): + + :: + + -C bp.flashloader1.fname="<path-to>/<el3-payload>" + + On Foundation FVP, there is no flash loader component and the EL3 payload + may be programmed anywhere in flash using method 3 below. + +#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5 + command may be used to load the EL3 payload ELF image over JTAG: + + :: + + load <path-to>/el3-payload.elf + +#. The EL3 payload may be pre-loaded in volatile memory using the following + model parameters: + + :: + + --data cluster0.cpu0="<path-to>/el3-payload>"@address [Base FVPs] + --data="<path-to>/<el3-payload>"@address [Foundation FVP] + + The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address + used when building TF-A. + +Booting a preloaded kernel image (Base FVP) +------------------------------------------- + +The following example uses a simplified boot flow by directly jumping from the +TF-A to the Linux kernel, which will use a ramdisk as filesystem. This can be +useful if both the kernel and the device tree blob (DTB) are already present in +memory (like in FVP). + +For example, if the kernel is loaded at ``0x80080000`` and the DTB is loaded at +address ``0x82000000``, the firmware can be built like this: + +.. code:: shell + + CROSS_COMPILE=aarch64-none-elf- \ + make PLAT=fvp DEBUG=1 \ + RESET_TO_BL31=1 \ + ARM_LINUX_KERNEL_AS_BL33=1 \ + PRELOADED_BL33_BASE=0x80080000 \ + ARM_PRELOADED_DTB_BASE=0x82000000 \ + all fip + +Now, it is needed to modify the DTB so that the kernel knows the address of the +ramdisk. The following script generates a patched DTB from the provided one, +assuming that the ramdisk is loaded at address ``0x84000000``. Note that this +script assumes that the user is using a ramdisk image prepared for U-Boot, like +the ones provided by Linaro. If using a ramdisk without this header,the ``0x40`` +offset in ``INITRD_START`` has to be removed. + +.. code:: bash + + #!/bin/bash + + # Path to the input DTB + KERNEL_DTB=<path-to>/<fdt> + # Path to the output DTB + PATCHED_KERNEL_DTB=<path-to>/<patched-fdt> + # Base address of the ramdisk + INITRD_BASE=0x84000000 + # Path to the ramdisk + INITRD=<path-to>/<ramdisk.img> + + # Skip uboot header (64 bytes) + INITRD_START=$(printf "0x%x" $((${INITRD_BASE} + 0x40)) ) + INITRD_SIZE=$(stat -Lc %s ${INITRD}) + INITRD_END=$(printf "0x%x" $((${INITRD_BASE} + ${INITRD_SIZE})) ) + + CHOSEN_NODE=$(echo \ + "/ { \ + chosen { \ + linux,initrd-start = <${INITRD_START}>; \ + linux,initrd-end = <${INITRD_END}>; \ + }; \ + };") + + echo $(dtc -O dts -I dtb ${KERNEL_DTB}) ${CHOSEN_NODE} | \ + dtc -O dtb -o ${PATCHED_KERNEL_DTB} - + +And the FVP binary can be run with the following command: + +.. code:: shell + + <path-to>/FVP_Base_AEMv8A-AEMv8A \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C cluster0.NUM_CORES=4 \ + -C cluster1.NUM_CORES=4 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.RVBAR=0x04001000 \ + -C cluster0.cpu1.RVBAR=0x04001000 \ + -C cluster0.cpu2.RVBAR=0x04001000 \ + -C cluster0.cpu3.RVBAR=0x04001000 \ + -C cluster1.cpu0.RVBAR=0x04001000 \ + -C cluster1.cpu1.RVBAR=0x04001000 \ + -C cluster1.cpu2.RVBAR=0x04001000 \ + -C cluster1.cpu3.RVBAR=0x04001000 \ + --data cluster0.cpu0="<path-to>/bl31.bin"@0x04001000 \ + --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000 + +Obtaining the Flattened Device Trees +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on the FVP configuration and Linux configuration used, different +FDT files are required. FDT source files for the Foundation and Base FVPs can +be found in the TF-A source directory under ``fdts/``. The Foundation FVP has +a subset of the Base FVP components. For example, the Foundation FVP lacks +CLCD and MMC support, and has only one CPU cluster. + +.. note:: + It is not recommended to use the FDTs built along the kernel because not + all FDTs are available from there. + +The dynamic configuration capability is enabled in the firmware for FVPs. +This means that the firmware can authenticate and load the FDT if present in +FIP. A default FDT is packaged into FIP during the build based on +the build configuration. This can be overridden by using the ``FVP_HW_CONFIG`` +or ``FVP_HW_CONFIG_DTS`` build options (refer to +:ref:`build_options_arm_fvp_platform` for details on the options). + +- ``fvp-base-gicv2-psci.dts`` + + For use with models such as the Cortex-A57-A53 or Cortex-A32 Base FVPs + without shifted affinities and with Base memory map configuration. + +- ``fvp-base-gicv3-psci.dts`` + + For use with models such as the Cortex-A57-A53 or Cortex-A32 Base FVPs + without shifted affinities and with Base memory map configuration and + Linux GICv3 support. + +- ``fvp-base-gicv3-psci-1t.dts`` + + For use with models such as the AEMv8-RevC Base FVP with shifted affinities, + single threaded CPUs, Base memory map configuration and Linux GICv3 support. + +- ``fvp-base-gicv3-psci-dynamiq.dts`` + + For use with models as the Cortex-A55-A75 Base FVPs with shifted affinities, + single cluster, single threaded CPUs, Base memory map configuration and Linux + GICv3 support. + +- ``fvp-foundation-gicv2-psci.dts`` + + For use with Foundation FVP with Base memory map configuration. + +- ``fvp-foundation-gicv3-psci.dts`` + + (Default) For use with Foundation FVP with Base memory map configuration + and Linux GICv3 support. + + +Running on the Foundation FVP with reset to BL1 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``Foundation_Platform`` parameters should be used to boot Linux with +4 CPUs using the AArch64 build of TF-A. + +.. code:: shell + + <path-to>/Foundation_Platform \ + --cores=4 \ + --arm-v8.0 \ + --secure-memory \ + --visualization \ + --gicv3 \ + --data="<path-to>/<bl1-binary>"@0x0 \ + --data="<path-to>/<FIP-binary>"@0x08000000 \ + --data="<path-to>/<kernel-binary>"@0x80080000 \ + --data="<path-to>/<ramdisk-binary>"@0x84000000 + +Notes: + +- BL1 is loaded at the start of the Trusted ROM. +- The Firmware Image Package is loaded at the start of NOR FLASH0. +- The firmware loads the FDT packaged in FIP to the DRAM. The FDT load address + is specified via the ``load-address`` property in the ``hw-config`` node of + `FW_CONFIG for FVP`_. +- The default use-case for the Foundation FVP is to use the ``--gicv3`` option + and enable the GICv3 device in the model. Note that without this option, + the Foundation FVP defaults to legacy (Versatile Express) memory map which + is not supported by TF-A. +- In order for TF-A to run correctly on the Foundation FVP, the architecture + versions must match. The Foundation FVP defaults to the highest v8.x + version it supports but the default build for TF-A is for v8.0. To avoid + issues either start the Foundation FVP to use v8.0 architecture using the + ``--arm-v8.0`` option, or build TF-A with an appropriate value for + ``ARM_ARCH_MINOR``. + +Running on the AEMv8 Base FVP with reset to BL1 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux +with 8 CPUs using the AArch64 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_RevC-2xAEMv8A \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cluster0.NUM_CORES=4 \ + -C cluster1.NUM_CORES=4 \ + -C cache_state_modelled=1 \ + -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ + -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires + a specific DTS for all the CPUs to be loaded. + +Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux +with 8 CPUs using the AArch32 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_AEMv8A-AEMv8A \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cluster0.NUM_CORES=4 \ + -C cluster1.NUM_CORES=4 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.CONFIG64=0 \ + -C cluster0.cpu1.CONFIG64=0 \ + -C cluster0.cpu2.CONFIG64=0 \ + -C cluster0.cpu3.CONFIG64=0 \ + -C cluster1.cpu0.CONFIG64=0 \ + -C cluster1.cpu1.CONFIG64=0 \ + -C cluster1.cpu2.CONFIG64=0 \ + -C cluster1.cpu3.CONFIG64=0 \ + -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ + -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to +boot Linux with 8 CPUs using the AArch64 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cache_state_modelled=1 \ + -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ + -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to +boot Linux with 4 CPUs using the AArch32 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_Cortex-A32x4 \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cache_state_modelled=1 \ + -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ + -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + + +Running on the AEMv8 Base FVP with reset to BL31 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux +with 8 CPUs using the AArch64 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_RevC-2xAEMv8A \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cluster0.NUM_CORES=4 \ + -C cluster1.NUM_CORES=4 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.RVBAR=0x04010000 \ + -C cluster0.cpu1.RVBAR=0x04010000 \ + -C cluster0.cpu2.RVBAR=0x04010000 \ + -C cluster0.cpu3.RVBAR=0x04010000 \ + -C cluster1.cpu0.RVBAR=0x04010000 \ + -C cluster1.cpu1.RVBAR=0x04010000 \ + -C cluster1.cpu2.RVBAR=0x04010000 \ + -C cluster1.cpu3.RVBAR=0x04010000 \ + --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \ + --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \ + --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ + --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +Notes: + +- Position Independent Executable (PIE) support is enabled in this + config allowing BL31 to be loaded at any valid address for execution. + +- Since a FIP is not loaded when using BL31 as reset entrypoint, the + ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>`` + parameter is needed to load the individual bootloader images in memory. + BL32 image is only needed if BL31 has been built to expect a Secure-EL1 + Payload. For the same reason, the FDT needs to be compiled from the DT source + and loaded via the ``--data cluster0.cpu0="<path-to>/<fdt>"@0x82000000`` + parameter. + +- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a + specific DTS for all the CPUs to be loaded. + +- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where + X and Y are the cluster and CPU numbers respectively, is used to set the + reset vector for each core. + +- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require + changing the value of + ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of + ``BL32_BASE``. + + +Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux +with 8 CPUs using the AArch32 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_AEMv8A-AEMv8A \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cluster0.NUM_CORES=4 \ + -C cluster1.NUM_CORES=4 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.CONFIG64=0 \ + -C cluster0.cpu1.CONFIG64=0 \ + -C cluster0.cpu2.CONFIG64=0 \ + -C cluster0.cpu3.CONFIG64=0 \ + -C cluster1.cpu0.CONFIG64=0 \ + -C cluster1.cpu1.CONFIG64=0 \ + -C cluster1.cpu2.CONFIG64=0 \ + -C cluster1.cpu3.CONFIG64=0 \ + -C cluster0.cpu0.RVBAR=0x04002000 \ + -C cluster0.cpu1.RVBAR=0x04002000 \ + -C cluster0.cpu2.RVBAR=0x04002000 \ + -C cluster0.cpu3.RVBAR=0x04002000 \ + -C cluster1.cpu0.RVBAR=0x04002000 \ + -C cluster1.cpu1.RVBAR=0x04002000 \ + -C cluster1.cpu2.RVBAR=0x04002000 \ + -C cluster1.cpu3.RVBAR=0x04002000 \ + --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \ + --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ + --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +.. note:: + Position Independent Executable (PIE) support is enabled in this + config allowing SP_MIN to be loaded at any valid address for execution. + +Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to +boot Linux with 8 CPUs using the AArch64 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.RVBARADDR=0x04010000 \ + -C cluster0.cpu1.RVBARADDR=0x04010000 \ + -C cluster0.cpu2.RVBARADDR=0x04010000 \ + -C cluster0.cpu3.RVBARADDR=0x04010000 \ + -C cluster1.cpu0.RVBARADDR=0x04010000 \ + -C cluster1.cpu1.RVBARADDR=0x04010000 \ + -C cluster1.cpu2.RVBARADDR=0x04010000 \ + -C cluster1.cpu3.RVBARADDR=0x04010000 \ + --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \ + --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \ + --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ + --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to +boot Linux with 4 CPUs using the AArch32 build of TF-A. + +.. code:: shell + + <path-to>/FVP_Base_Cortex-A32x4 \ + -C pctl.startup=0.0.0.0 \ + -C bp.secure_memory=1 \ + -C bp.tzc_400.diagnostics=1 \ + -C cache_state_modelled=1 \ + -C cluster0.cpu0.RVBARADDR=0x04002000 \ + -C cluster0.cpu1.RVBARADDR=0x04002000 \ + -C cluster0.cpu2.RVBARADDR=0x04002000 \ + -C cluster0.cpu3.RVBARADDR=0x04002000 \ + --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \ + --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ + --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ + --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ + --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 + +-------------- + +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* + +.. _FW_CONFIG for FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_fw_config.dts +.. _Arm's website: `FVP models`_ +.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms +.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01 +.. _Arm FVP website: https://developer.arm.com/products/system-design/fixed-virtual-platforms diff --git a/docs/plat/arm/fvp_r/index.rst b/docs/plat/arm/fvp_r/index.rst new file mode 100644 index 0000000..8af16ba --- /dev/null +++ b/docs/plat/arm/fvp_r/index.rst @@ -0,0 +1,46 @@ +ARM V8-R64 Fixed Virtual Platform (FVP) +======================================= + +Some of the features of Armv8-R AArch64 FVP platform referenced in Trusted +Boot R-class include: + +- Secure World Support Only +- EL2 as Maximum EL support (No EL3) +- MPU Support only at EL2 +- MPU or MMU Support at EL0/EL1 +- AArch64 Support Only +- Trusted Board Boot + +Further information on v8-R64 FVP is available at `info <https://developer.arm.com/documentation/ddi0600/latest/>`_ + +Boot Sequence +------------- + +BL1 –> BL33 + +The execution begins from BL1 which loads the BL33 image, a boot-wrapped (bootloader + Operating System) +Operating System, from FIP to DRAM. + +Build Procedure +~~~~~~~~~~~~~~~ + +- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + make PLAT=fvp_r BL33=<path_to_os.bin> all fip + + Enable TBBR by adding the following options to the make command: + + .. code:: shell + + MBEDTLS_DIR=<path_to_mbedtls_directory> \ + TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/index.rst b/docs/plat/arm/index.rst new file mode 100644 index 0000000..2f68522 --- /dev/null +++ b/docs/plat/arm/index.rst @@ -0,0 +1,24 @@ +Arm Development Platforms +========================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + juno/index + fvp/index + fvp_r/index + fvp-ve/index + tc/index + arm_fpga/index + arm-build-options + morello/index + corstone1000/index + +This chapter holds documentation related to Arm's development platforms, +including both software models (FVPs) and hardware development boards +such as Juno. + +-------------- + +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/juno/index.rst b/docs/plat/arm/juno/index.rst new file mode 100644 index 0000000..5320a3b --- /dev/null +++ b/docs/plat/arm/juno/index.rst @@ -0,0 +1,252 @@ +Arm Juno Development Platform +============================= + +Platform-specific build options +------------------------------- + +- ``JUNO_TZMP1`` : Boolean option to configure Juno to be used for TrustZone + Media Protection (TZ-MP1). Default value of this flag is 0. + +Running software on Juno +------------------------ + +This version of TF-A has been tested on variants r0, r1 and r2 of Juno. + +To run TF-A on Juno, you need to first prepare an SD card with Juno software +stack that includes TF-A. This version of TF-A is tested with pre-built +`Linaro release software stack`_ version 20.01. You can alternatively +build the software stack yourself by following the +`Juno platform software user guide`_. Once you prepare the software stack +on an SD card, you can replace the ``bl1.bin`` and ``fip.bin`` +binaries in the ``SOFTWARE/`` directory with custom built TF-A binaries. + +Preparing TF-A images +--------------------- + +This section provides Juno and FVP specific instructions to build Trusted +Firmware, obtain the additional required firmware, and pack it all together in +a single FIP binary. It assumes that a Linaro release software stack has been +installed. + +.. note:: + Pre-built binaries for AArch32 are available from Linaro Release 16.12 + onwards. Before that release, pre-built binaries are only available for + AArch64. + +.. warning:: + Follow the full instructions for one platform before switching to a + different one. Mixing instructions for different platforms may result in + corrupted binaries. + +.. warning:: + The uboot image downloaded by the Linaro workspace script does not always + match the uboot image packaged as BL33 in the corresponding fip file. It is + recommended to use the version that is packaged in the fip file using the + instructions below. + +.. note:: + For the FVP, the kernel FDT is packaged in FIP during build and loaded + by the firmware at runtime. + +#. Clean the working directory + + .. code:: shell + + make realclean + +#. Obtain SCP binaries (Juno) + + This version of TF-A is tested with SCP version 2.12.0 on Juno. You can + download pre-built SCP binaries (``scp_bl1.bin`` and ``scp_bl2.bin``) + from `TF-A downloads page`_. Alternatively, you can `build + the binaries from source`_. + +#. Obtain BL33 (all platforms) + + Use the fiptool to extract the BL33 image from the FIP + package included in the Linaro release: + + .. code:: shell + + # Build the fiptool + make [DEBUG=1] [V=1] fiptool + + # Unpack firmware images from Linaro FIP + ./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin + + The unpack operation will result in a set of binary images extracted to the + current working directory. BL33 corresponds to ``nt-fw.bin``. + + .. note:: + The fiptool will complain if the images to be unpacked already + exist in the current directory. If that is the case, either delete those + files or use the ``--force`` option to overwrite. + + .. note:: + For AArch32, the instructions below assume that nt-fw.bin is a + normal world boot loader that supports AArch32. + +#. Build TF-A images and create a new FIP for FVP + + .. code:: shell + + # AArch64 + make PLAT=fvp BL33=nt-fw.bin all fip + + # AArch32 + make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip + +#. Build TF-A images and create a new FIP for Juno + + For AArch64: + + Building for AArch64 on Juno simply requires the addition of ``SCP_BL2`` + as a build parameter. + + .. code:: shell + + make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp_bl2.bin all fip + + For AArch32: + + Hardware restrictions on Juno prevent cold reset into AArch32 execution mode, + therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled + separately for AArch32. + + - Before building BL32, the environment variable ``CROSS_COMPILE`` must point + to the AArch32 Linaro cross compiler. + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- + + - Build BL32 in AArch32. + + .. code:: shell + + make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \ + RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32 + + - Save ``bl32.bin`` to a temporary location and clean the build products. + + :: + + cp <path-to-build>/bl32.bin <path-to-temporary> + make realclean + + - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE`` + must point to the AArch64 Linaro cross compiler. + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + + - The following parameters should be used to build BL1 and BL2 in AArch64 + and point to the BL32 file. + + .. code:: shell + + make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \ + BL33=nt-fw.bin SCP_BL2=scp_bl2.bin \ + BL32=<path-to-temporary>/bl32.bin all fip + +The resulting BL1 and FIP images may be found in: + +:: + + # Juno + ./build/juno/release/bl1.bin + ./build/juno/release/fip.bin + + # FVP + ./build/fvp/release/bl1.bin + ./build/fvp/release/fip.bin + +After building TF-A, the files ``bl1.bin``, ``fip.bin`` and ``scp_bl1.bin`` +need to be copied to the ``SOFTWARE/`` directory on the Juno SD card. + +Booting Firmware Update images +------------------------------ + +The new images must be programmed in flash memory by adding +an entry in the ``SITE1/HBI0262x/images.txt`` configuration file +on the Juno SD card (where ``x`` depends on the revision of the Juno board). +Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory +programming" for more information. User should ensure these do not +overlap with any other entries in the file. + +:: + + NOR10UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE + NOR10ADDRESS: 0x00400000 ;Image Flash Address [ns_bl2u_base_address] + NOR10FILE: \SOFTWARE\fwu_fip.bin ;Image File Name + NOR10LOAD: 00000000 ;Image Load Address + NOR10ENTRY: 00000000 ;Image Entry Point + + NOR11UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE + NOR11ADDRESS: 0x03EB8000 ;Image Flash Address [ns_bl1u_base_address] + NOR11FILE: \SOFTWARE\ns_bl1u.bin ;Image File Name + NOR11LOAD: 00000000 ;Image Load Address + +The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000. +In the same way, the address ns_bl2u_base_address is the value of +NS_BL2U_BASE - 0x8000000. + +.. _plat_juno_booting_el3_payload: + +Booting an EL3 payload +---------------------- + +If the EL3 payload is able to execute in place, it may be programmed in flash +memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file +on the Juno SD card (where ``x`` depends on the revision of the Juno board). +Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory +programming" for more information. + +Alternatively, the same DS-5 command mentioned in the FVP section above can +be used to load the EL3 payload's ELF file over JTAG on Juno. + +For more information on EL3 payloads in general, see +:ref:`alt_boot_flows_el3_payload`. + +Booting a preloaded kernel image +-------------------------------- + +The Trusted Firmware must be compiled in a similar way as for FVP explained +above. The process to load binaries to memory is the one explained in +`plat_juno_booting_el3_payload`_. + +Testing System Suspend +---------------------- + +The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend +to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend +on Juno, at the linux shell prompt, issue the following command: + +.. code:: shell + + echo +10 > /sys/class/rtc/rtc0/wakealarm + echo -n mem > /sys/power/state + +The Juno board should suspend to RAM and then wakeup after 10 seconds due to +wakeup interrupt from RTC. + +Additional Resources +-------------------- + +Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno +software information. Please also refer to the `Juno Getting Started Guide`_ to +get more detailed information about the Juno Arm development platform and how to +configure it. + +-------------- + +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* + +.. _Linaro release software stack: http://releases.linaro.org/members/arm/platforms/ +.. _Juno platform software user guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/juno/user-guide.rst +.. _TF-A downloads page: https://downloads.trustedfirmware.org/tf-a/css_scp_2.12.0/juno/ +.. _build the binaries from source: https://github.com/ARM-software/SCP-firmware/blob/master/user_guide.md#scp-firmware-user-guide +.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/ +.. _Juno Getting Started Guide: https://developer.arm.com/documentation/den0928/f/?lang=en +.. _PSCI: https://developer.arm.com/documentation/den0022/latest/ diff --git a/docs/plat/arm/morello/index.rst b/docs/plat/arm/morello/index.rst new file mode 100644 index 0000000..91549c0 --- /dev/null +++ b/docs/plat/arm/morello/index.rst @@ -0,0 +1,43 @@ +Morello Platform +================ + +Morello is an ARMv8-A platform that implements the capability architecture extension. +The platform port present at `site <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`_ +provides ARMv8-A architecture enablement. + +Capability architecture specific changes will be added `here <https://git.morello-project.org/morello>`_ + +Further information on Morello Platform is available at `info <https://developer.arm.com/architectures/cpu-architecture/a-profile/morello>`_ + +Boot Sequence +------------- + +The SCP initializes the RVBAR registers to point to the AP_BL1. Once RVBAR is +initialized, the primary core is powered on. The primary core boots the AP_BL1. +It performs minimum initialization necessary to load and authenticate the AP +firmware image (the FIP image) from the AP QSPI NOR Flash Memory into the +Trusted SRAM. + +AP_BL1 authenticates and loads the AP_BL2 image. AP_BL2 performs additional +initializations, and then authenticates and loads the AP_BL31 and AP_BL33. +AP_BL2 then transfers execution control to AP_BL31, which is the EL3 runtime +firmware. Execution is finally handed off to AP_BL33, which is the non-secure +world (UEFI). + +SCP -> AP_BL1 -> AP_BL2 -> AP_BL31 -> AP_BL33 + +Build Procedure (TF-A only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + + make PLAT=morello all + +*Copyright (c) 2020-2023, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/tc/index.rst b/docs/plat/arm/tc/index.rst new file mode 100644 index 0000000..9469e9a --- /dev/null +++ b/docs/plat/arm/tc/index.rst @@ -0,0 +1,62 @@ +TC Total Compute Platform +========================== + +Some of the features of TC platform referenced in TF-A include: + +- A `System Control Processor <https://github.com/ARM-software/SCP-firmware>`_ + to abstract power and system management tasks away from application + processors. The RAM firmware for SCP is included in the TF-A FIP and is + loaded by AP BL2 from FIP in flash to SRAM for copying by SCP (SCP has access + to AP SRAM). +- GICv4 +- Trusted Board Boot +- SCMI +- MHUv2 + +Currently, the main difference between TC0 (TARGET_PLATFORM=0), TC1 +(TARGET_PLATFORM=1), TC2 (TARGET_PLATFORM=2) platforms w.r.t to TF-A +is the CPUs supported as below: + +- TC0 has support for Cortex A510, Cortex A710 and Cortex X2. (Note TC0 is now deprecated) +- TC1 has support for Cortex A510, Cortex A715 and Cortex X3. (Note TC1 is now deprecated) +- TC2 has support for Cortex A520, Cortex A720 and Cortex x4. + +Boot Sequence +------------- + +The execution begins from SCP_BL1. SCP_BL1 powers up the AP which starts +executing AP_BL1 and then executes AP_BL2 which loads the SCP_BL2 from +FIP to SRAM. The SCP has access to AP SRAM. The address and size of SCP_BL2 +is communicated to SCP using SDS. SCP copies SCP_BL2 from SRAM to its own +RAM and starts executing it. The AP then continues executing the rest of TF-A +stages including BL31 runtime stage and hands off executing to +Non-secure world (u-boot). + +Build Procedure (TF-A only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Obtain `Arm toolchain`_ and set the CROSS_COMPILE environment variable to + point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + make PLAT=tc BL33=<path_to_uboot.bin> \ + SCP_BL2=<path_to_scp_ramfw.bin> TARGET_PLATFORM={0,1,2} all fip + + Enable TBBR by adding the following options to the make command: + + .. code:: shell + + MBEDTLS_DIR=<path_to_mbedtls_directory> \ + TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem + +-------------- + +*Copyright (c) 2020-2023, Arm Limited. All rights reserved.* + +.. _Arm Toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads |