diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 17:43:51 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 17:43:51 +0000 |
| commit | be58c81aff4cd4c0ccf43dbd7998da4a6a08c03b (patch) | |
| tree | 779c248fb61c83f65d1f0dc867f2053d76b4e03a /docs/plat | |
| parent | Initial commit. (diff) | |
| download | arm-trusted-firmware-be58c81aff4cd4c0ccf43dbd7998da4a6a08c03b.tar.xz arm-trusted-firmware-be58c81aff4cd4c0ccf43dbd7998da4a6a08c03b.zip | |
Adding upstream version 2.10.0+dfsg.upstream/2.10.0+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/plat')
67 files changed, 7845 insertions, 0 deletions
diff --git a/docs/plat/allwinner.rst b/docs/plat/allwinner.rst new file mode 100644 index 0000000..8e967dc --- /dev/null +++ b/docs/plat/allwinner.rst @@ -0,0 +1,144 @@ +Allwinner ARMv8 SoCs +==================== + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Allwinner +SoCs with ARMv8 cores. Only BL31 is used to provide proper EL3 setup and +PSCI runtime services. + +Building TF-A +------------- + +There is one build target per supported SoC: + ++------+-------------------+ +| SoC | TF-A build target | ++======+===================+ +| A64 | sun50i_a64 | ++------+-------------------+ +| H5 | sun50i_a64 | ++------+-------------------+ +| H6 | sun50i_h6 | ++------+-------------------+ +| H616 | sun50i_h616 | ++------+-------------------+ +| H313 | sun50i_h616 | ++------+-------------------+ +| T507 | sun50i_h616 | ++------+-------------------+ +| R329 | sun50i_r329 | ++------+-------------------+ + +To build with the default settings for a particular SoC: + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=<build target> DEBUG=1 + +So for instance to build for a board with the Allwinner A64 SoC:: + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1 + +Platform-specific build options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default build options should generate a working firmware image. There are +some build options that allow to fine-tune the firmware, or to disable support +for optional features. + +- ``SUNXI_PSCI_USE_NATIVE`` : Support direct control of the CPU cores powerdown + and powerup sequence by BL31. This requires either support for a code snippet + to be loaded into the ARISC SCP (A64, H5), or the power sequence control + registers to be programmed directly (H6, H616). This supports only basic + control, like core on/off and system off/reset. + This option defaults to 1. If an active SCP supporting the SCPI protocol + is detected at runtime, this control scheme will be ignored, and SCPI + will be used instead, unless support has been explicitly disabled. + +- ``SUNXI_PSCI_USE_SCPI`` : Support control of the CPU cores powerdown and + powerup sequence by talking to the SCP processor via the SCPI protocol. + This allows more advanced power saving techniques, like suspend to RAM. + This option defaults to 1 on SoCs that feature an SCP. If no SCP firmware + using the SCPI protocol is detected, the native sequence will be used + instead. If both native and SCPI methods are included, SCPI will be favoured + if SCP support is detected. + +- ``SUNXI_SETUP_REGULATORS`` : On SoCs that typically ship with a PMIC + power management controller, BL31 tries to set up all needed power rails, + programming them to their respective voltages. That allows bootloader + software like U-Boot to ignore power control via the PMIC. + This setting defaults to 1. In some situations that enables too many + regulators, or some regulators need to be enabled in a very specific + sequence. To avoid problems with those boards, ``SUNXI_SETUP_REGULATORS`` + can bet set to ``0`` on the build command line, to skip the PMIC setup + entirely. Any bootloader or OS would need to setup the PMIC on its own then. + +Installation +------------ + +U-Boot's SPL acts as a loader, loading both BL31 and BL33 (typically U-Boot). +Loading is done from SD card, eMMC or SPI flash, also via an USB debug +interface (FEL). + +After building bl31.bin, the binary must be fed to the U-Boot build system +to include it in the FIT image that the SPL loader will process. +bl31.bin can be either copied (or sym-linked) into U-Boot's root directory, +or the environment variable BL31 must contain the binary's path. +See the respective `U-Boot documentation`_ for more details. + +.. _U-Boot documentation: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/sunxi/README.sunxi64 + +Memory layout +------------- + +A64, H5 and H6 SoCs +~~~~~~~~~~~~~~~~~~~ + +BL31 lives in SRAM A2, which is documented to be accessible from secure +world only. Since this SRAM region is very limited (48 KB), we take +several measures to reduce memory consumption. One of them is to confine +BL31 to only 28 bits of virtual address space, which reduces the number +of required page tables (each occupying 4KB of memory). +The mapping we use on those SoCs is as follows: + +:: + + 0 64K 16M 1GB 1G+160M physical address + +-+------+-+---+------+--...---+-------+----+------+---------- + |B| |S|///| |//...///| |////| | + |R| SRAM |C|///| dev |//...///| (sec) |////| BL33 | DRAM ... + |O| |P|///| MMIO |//...///| DRAM |////| | + |M| | |///| |//...///| (32M) |////| | + +-+------+-+---+------+--...---+-------+----+------+---------- + | | | | | | / / / / + | | | | | | / / / / + | | | | | | / / / / + | | | | | | / // / + | | | | | | / / / + +-+------+-+---+------+--+-------+------+ + |B| |S|///| |//| | | + |R| SRAM |C|///| dev |//| sec | BL33 | + |O| |P|///| MMIO |//| DRAM | | + |M| | |///| |//| | | + +-+------+-+---+------+--+-------+------+ + 0 64K 16M 160M 192M 256M virtual address + + +H616 SoC +~~~~~~~~ + +The H616 lacks the secure SRAM region present on the other SoCs, also +lacks the "ARISC" management processor (SCP) we use. BL31 thus needs to +run from DRAM, which prevents our compressed virtual memory map described +above. Since running in DRAM also lifts the restriction of the limited +SRAM size, we use the normal 1:1 mapping with 32 bits worth of virtual +address space. So the virtual addresses used in BL31 match the physical +addresses as presented above. + +Trusted OS dispatcher +--------------------- + +One can boot Trusted OS(OP-TEE OS, bl32 image) along side bl31 image on Allwinner A64. + +In order to include the 'opteed' dispatcher in the image, pass 'SPD=opteed' on the command line +while compiling the bl31 image and make sure the loader (SPL) loads the Trusted OS binary to +the beginning of DRAM (0x40000000). 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 diff --git a/docs/plat/ast2700.rst b/docs/plat/ast2700.rst new file mode 100644 index 0000000..6deade3 --- /dev/null +++ b/docs/plat/ast2700.rst @@ -0,0 +1,17 @@ +Aspeed AST2700 +============== + +Aspeed AST2700 is a 64-bit ARM SoC with 4-cores Cortex-A35 integrated. +Each core operates at 1.6GHz. + +Boot Flow +--------- + + BootRom --> TF-A BL31 --> BL32 --> BL33 --> Linux Kernel + +How to build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=ast2700 SPD=opteed diff --git a/docs/plat/brcm-stingray.rst b/docs/plat/brcm-stingray.rst new file mode 100644 index 0000000..95029cc --- /dev/null +++ b/docs/plat/brcm-stingray.rst @@ -0,0 +1,43 @@ +Broadcom Stingray +================= + +Description +----------- +Broadcom's Stingray(BCM958742t) is a multi-core processor with 8 Cortex-A72 cores. +Trusted Firmware-A (TF-A) is used to implement secure world firmware, supporting +BL2 and BL31 for Broadcom Stingray SoCs. + +On Poweron, Boot ROM will load bl2 image and Bl2 will initialize the hardware, +then loads bl31 and bl33 into DDR and boots to bl33. + +Boot Sequence +------------- + +Bootrom --> TF-A BL2 --> TF-A BL31 --> BL33(u-boot) + +Code Locations +~~~~~~~~~~~~~~ +- Trusted Firmware-A: + `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/>`__ + +How to build +------------ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Prepare AARCH64 toolchain. + +- Build u-boot first, and get the binary image: u-boot.bin, + +- Build TF-A + + Build fip: + + .. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=stingray BOARD_CFG=bcm958742t all fip BL33=u-boot.bin + +Deploy TF-A Images +~~~~~~~~~~~~~~~~~~ +The u-boot will be upstreamed soon, this doc will be updated once they are ready, and the link will be posted. diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst new file mode 100644 index 0000000..6c488b8 --- /dev/null +++ b/docs/plat/hikey.rst @@ -0,0 +1,155 @@ +HiKey +===== + +HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey. + +More information are listed in `link`_. + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- OP-TEE + `link <https://github.com/OP-TEE/optee_os>`__ + +- edk2: + `link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__ + +- OpenPlatformPkg: + `link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__ + +- l-loader: + `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__ + +- atf-fastboot: + `link <https://github.com/96boards-hikey/atf-fastboot/tree/master>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Fetch all the above repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + + .. code:: shell + + git clone https://github.com/ARM-software/arm-trusted-firmware -b integration + git clone https://github.com/OP-TEE/optee_os + git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5 + git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4 + git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2 + git clone https://github.com/96boards-hikey/atf-fastboot + +- Create the symbol link to OpenPlatformPkg in edk2. + + .. code:: shell + + $cd ${BUILD_PATH}/edk2 + $ln -sf ../OpenPlatformPkg + +- Prepare AARCH64 && AARCH32 toolchain. Prepare python. + +- If your hikey hardware is built by CircuitCo, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey/HiKey.dsc* first. *(optional)* + console on hikey.** + + .. code:: shell + + DEFINE SERIAL_BASE=0xF8015000 + + If your hikey hardware is built by LeMaker, nothing to do. + +- Build it as debug mode. Create your own build script file or you could refer to **build\_uefi.sh** in l-loader git repository. + + .. code:: shell + + cd {BUILD_PATH}/arm-trusted-firmware + sh ../l-loader/build_uefi.sh hikey + +- Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian. + + .. code:: shell + + cd ${BUILD_PATH}/l-loader + ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin + ln -sf ${EDK2_OUTPUT_DIR}/FV/bl2.bin + ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin + make hikey PTABLE_LST=aosp-8g + +Setup Console +------------- + +- Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. **If you don't need Boot Manager GUI, just ignore this section.** + + .. code:: shell + + $sudo apt-get install ser2net + +- Configure ser2net. + + .. code:: shell + + $sudo vi /etc/ser2net.conf + + Append one line for serial-over-USB in below. + *#ser2net.conf* + + .. code:: shell + + 2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner + +- Start ser2net + + .. code:: shell + + $sudo killall ser2net + $sudo ser2net -u + +- Open the console. + + .. code:: shell + + $telnet localhost 2004 + + And you could open the console remotely, too. + +Flash images in recovery mode +----------------------------- + +- Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey. + +- Remove the modemmanager package. This package may cause the idt tool failure. + + .. code:: shell + + $sudo apt-get purge modemmanager + +- Run the command to download recovery.bin into HiKey. + + .. code:: shell + + $sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 recovery.bin + +- Update images. All aosp or debian images could be fetched from `link <http://releases.linaro.org/96boards/>`__. + + .. code:: shell + + $sudo fastboot flash ptable prm_ptable.img + $sudo fastboot flash loader l-loader.bin + $sudo fastboot flash fastboot fip.bin + $sudo fastboot flash boot boot.img + $sudo fastboot flash cache cache.img + $sudo fastboot flash system system.img + $sudo fastboot flash userdata userdata.img + +Boot UEFI in normal mode +------------------------ + +- Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey. + +- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__ + +.. _link: https://www.96boards.org/documentation/consumer/hikey/ diff --git a/docs/plat/hikey960.rst b/docs/plat/hikey960.rst new file mode 100644 index 0000000..982c2c8 --- /dev/null +++ b/docs/plat/hikey960.rst @@ -0,0 +1,180 @@ +HiKey960 +======== + +HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960. + +More information are listed in `link`_. + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- OP-TEE: + `link <https://github.com/OP-TEE/optee_os>`__ + +- edk2: + `link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__ + +- OpenPlatformPkg: + `link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__ + +- l-loader: + `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Fetch all the above 5 repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + + .. code:: shell + + git clone https://github.com/ARM-software/arm-trusted-firmware -b integration + git clone https://github.com/OP-TEE/optee_os + git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5 + git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4 + git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2 + +- Create the symbol link to OpenPlatformPkg in edk2. + + .. code:: shell + + $cd ${BUILD_PATH}/edk2 + $ln -sf ../OpenPlatformPkg + +- Prepare AARCH64 toolchain. + +- If your hikey960 hardware is v1, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey960/HiKey960.dsc* first. *(optional)* + + .. code:: shell + + DEFINE SERIAL_BASE=0xFDF05000 + + If your hikey960 hardware is v2 or newer, nothing to do. + +- Build it as debug mode. Create script file for build. + + .. code:: shell + + cd {BUILD_PATH}/arm-trusted-firmware + sh ../l-loader/build_uefi.sh hikey960 + +- Generate l-loader.bin and partition table. + *Make sure that you're using the sgdisk in the l-loader directory.* + + .. code:: shell + + cd ${BUILD_PATH}/l-loader + ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin + ln -sf ${EDK2_OUTPUT_DIR}/FV/bl2.bin + ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin + ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd + make hikey960 + +Setup Console +------------- + +- Install ser2net. Use telnet as the console since UEFI will output window + that fails to display in minicom. + + .. code:: shell + + $sudo apt-get install ser2net + +- Configure ser2net. + + .. code:: shell + + $sudo vi /etc/ser2net.conf + + Append one line for serial-over-USB in *#ser2net.conf* + + :: + + 2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner + +- Start ser2net + + .. code:: shell + + $sudo killall ser2net + $sudo ser2net -u + +- Open the console. + + .. code:: shell + + $telnet localhost 2004 + + And you could open the console remotely, too. + +Boot UEFI in recovery mode +-------------------------- + +- Fetch that are used in recovery mode. The code location is in below. + `link <https://github.com/96boards-hikey/tools-images-hikey960>`__ + +- Prepare recovery binary. + + .. code:: shell + + $cd tools-images-hikey960 + $ln -sf ${BUILD_PATH}/l-loader/l-loader.bin + $ln -sf ${BUILD_PATH}/l-loader/fip.bin + $ln -sf ${BUILD_PATH}/l-loader/recovery.bin + +- Prepare config file. + + .. code:: shell + + $vi config + # The content of config file + ./sec_usb_xloader.img 0x00020000 + ./sec_uce_boot.img 0x6A908000 + ./recovery.bin 0x1AC00000 + +- Remove the modemmanager package. This package may causes hikey\_idt tool failure. + + .. code:: shell + + $sudo apt-get purge modemmanager + +- Run the command to download recovery.bin into HiKey960. + + .. code:: shell + + $sudo ./hikey_idt -c config -p /dev/ttyUSB1 + +- UEFI running in recovery mode. + When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running. + The timeout of prompt '.' is 10 seconds. + +- Update images. + + .. code:: shell + + $sudo fastboot flash ptable prm_ptable.img + $sudo fastboot flash xloader sec_xloader.img + $sudo fastboot flash fastboot l-loader.bin + $sudo fastboot flash fip fip.bin + $sudo fastboot flash boot boot.img + $sudo fastboot flash cache cache.img + $sudo fastboot flash system system.img + $sudo fastboot flash userdata userdata.img + +- Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in + recovery mode. + +Boot UEFI in normal mode +------------------------ + +- Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960. + +- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__ + +.. _link: https://www.96boards.org/documentation/consumer/hikey/hikey960 diff --git a/docs/plat/imx8.rst b/docs/plat/imx8.rst new file mode 100644 index 0000000..49ba374 --- /dev/null +++ b/docs/plat/imx8.rst @@ -0,0 +1,58 @@ +NXP i.MX 8 Series +================= + +The i.MX 8 series of applications processors is a feature- and +performance-scalable multi-core platform that includes single-, +dual-, and quad-core families based on the Arm® Cortex® +architecture—including combined Cortex-A72 + Cortex-A53, +Cortex-A35, and Cortex-M4 based solutions for advanced graphics, +imaging, machine vision, audio, voice, video, and safety-critical +applications. + +The i.MX8QM is with 2 Cortex-A72 ARM core, 4 Cortex-A53 ARM core +and 1 Cortex-M4 system controller. + +The i.MX8QX is with 4 Cortex-A35 ARM core and 1 Cortex-M4 system +controller. + +The System Controller (SC) represents the evolution of centralized +control for system-level resources on i.MX8. The heart of the system +controller is a Cortex-M4 that executes system controller firmware. + +Boot Sequence +------------- + +Bootrom --> BL31 --> BL33(u-boot) --> Linux kernel + +How to build +------------ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Prepare AARCH64 toolchain. + +- Build System Controller Firmware and u-boot firstly, and get binary images: scfw_tcm.bin and u-boot.bin + +- Build TF-A + + Build bl31: + + .. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31 + + Target_SoC should be "imx8qm" for i.MX8QM SoC. + Target_SoC should be "imx8qx" for i.MX8QX SoC. + +Deploy TF-A Images +~~~~~~~~~~~~~~~~~~ + +TF-A binary(bl31.bin), scfw_tcm.bin and u-boot.bin are combined together +to generate a binary file called flash.bin, the imx-mkimage tool is used +to generate flash.bin, and flash.bin needs to be flashed into SD card +with certain offset for BOOT ROM. The system controller firmware, +u-boot and imx-mkimage will be upstreamed soon, this doc will be updated +once they are ready, and the link will be posted. + +.. _i.MX8: https://www.nxp.com/products/processors-and-microcontrollers/applications-processors/i.mx-applications-processors/i.mx-8-processors/i.mx-8-family-arm-cortex-a53-cortex-a72-virtualization-vision-3d-graphics-4k-video:i.MX8 diff --git a/docs/plat/imx8m.rst b/docs/plat/imx8m.rst new file mode 100644 index 0000000..f8071f7 --- /dev/null +++ b/docs/plat/imx8m.rst @@ -0,0 +1,113 @@ +NXP i.MX 8M Series +================== + +The i.MX 8M family of applications processors based on Arm Corte-A53 and Cortex-M4 +cores provide high-performance computing, power efficiency, enhanced system +reliability and embedded security needed to drive the growth of fast-growing +edge node computing, streaming multimedia, and machine learning applications. + +imx8mq is dropped in TF-A CI build due to the small OCRAM size, but still actively +maintained in NXP official release. + +Boot Sequence +------------- + +Bootrom --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel + +How to build +------------ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Prepare AARCH64 toolchain. + +- Build spl and u-boot firstly, and get binary images: u-boot-spl.bin, + u-boot-nodtb.bin and dtb for the target board. + +- Build TF-A + + Build bl31: + + .. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31 + + Target_SoC should be "imx8mq" for i.MX8MQ SoC. + Target_SoC should be "imx8mm" for i.MX8MM SoC. + Target_SoC should be "imx8mn" for i.MX8MN SoC. + Target_SoC should be "imx8mp" for i.MX8MP SoC. + +Deploy TF-A Images +~~~~~~~~~~~~~~~~~~ + +TF-A binary(bl31.bin), u-boot-spl.bin u-boot-nodtb.bin and dtb are combined +together to generate a binary file called flash.bin, the imx-mkimage tool is +used to generate flash.bin, and flash.bin needs to be flashed into SD card +with certain offset for BOOT ROM. the u-boot and imx-mkimage will be upstreamed +soon, this doc will be updated once they are ready, and the link will be posted. + +TBBR Boot Sequence +------------------ + +When setting NEED_BL2=1 on imx8mm. We support an alternative way of +boot sequence to support TBBR. + +Bootrom --> SPL --> BL2 --> BL31 --> BL33(u-boot with UEFI) --> grub + +This helps us to fulfill the SystemReady EBBR standard. +BL2 will be in the FIT image and SPL will verify it. +All of the BL3x will be put in the FIP image. BL2 will verify them. +In U-boot we turn on the UEFI secure boot features so it can verify +grub. And we use grub to verify linux kernel. + +Measured Boot +------------- + +When setting MEASURED_BOOT=1 on imx8mm we can let TF-A generate event logs +with a DTB overlay. The overlay will be put at PLAT_IMX8M_DTO_BASE with +maximum size PLAT_IMX8M_DTO_MAX_SIZE. Then in U-boot we can apply the DTB +overlay and let U-boot to parse the event log and update the PCRs. + +High Assurance Boot (HABv4) +--------------------------- + +All actively maintained platforms have a support for High Assurance +Boot (HABv4), which is implemented via ROM Vector Table (RVT) API to +extend the Root-of-Trust beyond the SPL. Those calls are done via SMC +and are executed in EL3, with results returned back to original caller. + +Note on DRAM Memory Mapping +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There is a special case of mapping the DRAM: entire DRAM available on the +platform is mapped into the EL3 with MT_RW attributes. + +Mapping the entire DRAM allows the usage of 2MB block mapping in Level-2 +Translation Table entries, which use less Page Table Entries (PTEs). If +Level-3 PTE mapping is used instead then additional PTEs would be required, +which leads to the increase of translation table size. + +Due to the fact that the size of SRAM is limited on some platforms in the +family it should rather be avoided creating additional Level-3 mapping and +introduce more PTEs, hence the implementation uses Level-2 mapping which +maps entire DRAM space. + +The reason for the MT_RW attribute mapping scheme is the fact that the SMC +API to get the status and events is called from NS world passing destination +pointers which are located in DRAM. Mapping DRAM without MT_RW permissions +causes those locations not to be filled, which in turn causing EL1&0 software +not to receive replies. + +Therefore, DRAM mapping is done with MT_RW attributes, as it is required for +data exchange between EL3 and EL1&0 software. + +Reference Documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +Details on HABv4 usage and implementation could be found in following documents: + +- AN4581: "i.MX Secure Boot on HABv4 Supported Devices", Rev. 4 - June 2020 +- AN12263: "HABv4 RVT Guidelines and Recommendations", Rev. 1 - 06/2020 +- "HABv4 API Reference Manual". This document in the part of NXP Code Signing Tool (CST) distribution. + diff --git a/docs/plat/imx9.rst b/docs/plat/imx9.rst new file mode 100644 index 0000000..4adaae3 --- /dev/null +++ b/docs/plat/imx9.rst @@ -0,0 +1,60 @@ +NXP i.MX 9 Series +================== + +Building on the market-proven i.MX 6 and i.MX 8 series, i.MX 9 series applications +processors bring together higher performance applications cores, an independent +MCU-like real-time domain, Energy Flex architecture, state-of-the-art security +with EdgeLock® secure enclave and dedicated multi-sensory data processing engines +(graphics, image, display, audio and voice). The i.MX 9 series, part of the EdgeVerse™ +edge computing platform, integrates hardware neural processing units across many +members of the series for acceleration of machine learning applications at the edge +`i.MX9 Applications Processors`_. + +Boot Sequence +------------- + +BootROM --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel + +How to build +------------ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Prepare AARCH64 toolchain. + +- Get the ELE FW image from NXP linux SDK package + +- Build SPL and u-boot firstly, and get binary images: u-boot-spl.bin, + u-boot.bin and dtb + +- Build TF-A + + Build bl31: + + .. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31 + + Target_SoC should be "imx93" for i.MX93 SoC. + +Deploy TF-A Images +~~~~~~~~~~~~~~~~~~ + +TF-A binary(bl31.bin), u-boot-spl.bin u-boot.bin, ELE FW image are combined +together to generate a binary file called flash.bin, the imx-mkimage tool is +used to generate flash.bin, and flash.bin needs to be flashed into SD card +with certain offset for BOOT ROM. + +Reference Documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +Details on how to prepare, generate & deploy the boot image be found in following documents: + +- i.MX Linux User's Guide + `link <https://www.nxp.com/design/software/embedded-software/i-mx-software/embedded-linux-for-i-mx-applications-processors:IMXLINUX>`__ +- i.MX Linux Reference Manual + `link <https://www.nxp.com/design/software/embedded-software/i-mx-software/embedded-linux-for-i-mx-applications-processors:IMXLINUX>`__ + +.. _i.MX9 Applications Processors: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-9-processors:IMX9-PROCESSORS + diff --git a/docs/plat/index.rst b/docs/plat/index.rst new file mode 100644 index 0000000..b1ccaa5 --- /dev/null +++ b/docs/plat/index.rst @@ -0,0 +1,89 @@ +Platform Ports +============== + +.. toctree:: + :maxdepth: 1 + :caption: Contents + :hidden: + + allwinner + arm/index + ast2700 + meson-axg + meson-gxbb + meson-gxl + meson-g12a + hikey + hikey960 + intel-agilex + intel-stratix10 + marvell/index + mt8183 + mt8186 + mt8188 + mt8192 + mt8195 + nvidia-tegra + warp7 + imx8 + imx8m + imx9 + npcm845x + nxp/index + poplar + qemu + qemu-sbsa + qti + qti-msm8916 + rpi3 + rpi4 + rcar-gen3 + rz-g2 + rockchip + socionext-uniphier + synquacer + st/index + ti-k3 + xilinx-versal-net + xilinx-versal + xilinx-zynqmp + brcm-stingray + +This section provides a list of supported upstream *platform ports* and the +documentation associated with them. + +.. note:: + In addition to the platforms ports listed within the table of contents, there + are several additional platforms that are supported upstream but which do not + currently have associated documentation: + + - Arm Neoverse N1 System Development Platform (N1SDP) + - Arm Neoverse Reference Design N1 Edge (RD-N1-Edge) FVP + - Arm Neoverse Reference Design E1 Edge (RD-E1-Edge) FVP + - Arm SGI-575 + - MediaTek MT8173 SoCs + +Deprecated platforms +-------------------- + ++----------------+----------------+--------------------+--------------------+ +| Platform | Vendor | Deprecated version | Deleted version | ++================+================+====================+====================+ +| sgm775 | Arm | 2.5 | 2.7 | ++----------------+----------------+--------------------+--------------------+ +| mt6795 | MTK | 2.5 | 2.7 | ++----------------+----------------+--------------------+--------------------+ +| sgi575 | Arm | 2.8 | TBD | ++----------------+----------------+--------------------+--------------------+ +| rdn1edge | Arm | 2.8 | TBD | ++----------------+----------------+--------------------+--------------------+ +| tc0 | Arm | 2.8 | 2.10 | ++----------------+----------------+--------------------+--------------------+ +| tc1 | Arm | 2.10 | TBD | ++----------------+----------------+--------------------+--------------------+ +| rde1edge | Arm | 2.9 | 3.0 | ++----------------+----------------+--------------------+--------------------+ + +-------------- + +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* diff --git a/docs/plat/intel-agilex.rst b/docs/plat/intel-agilex.rst new file mode 100644 index 0000000..ff27b6b --- /dev/null +++ b/docs/plat/intel-agilex.rst @@ -0,0 +1,86 @@ +Intel Agilex SoCFPGA +======================== + +Agilex SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor. + +Upon boot, Boot ROM loads bl2 into OCRAM. Bl2 subsequently initializes +the hardware, then loads bl31 and bl33 (UEFI) into DDR and boots to bl33. + +:: + + Boot ROM --> Trusted Firmware-A --> UEFI + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- UEFI (to be updated with new upstreamed UEFI): + `link <https://github.com/altera-opensource/uefi-socfpga>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Fetch all the above 2 repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + +- Prepare the AARCH64 toolchain. + +- Build UEFI using Agilex platform as configuration + This will be updated to use an updated UEFI using the latest EDK2 source + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- device=agx + +- Build atf providing the previously generated UEFI as the BL33 image + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- bl2 fip PLAT=agilex + BL33=PEI.ROM + +Install Procedure +~~~~~~~~~~~~~~~~~ + +- dd fip.bin to a A2 partition on the MMC drive to be booted in Agilex + board. + +- Generate a SOF containing bl2 + +.. code:: bash + + aarch64-linux-gnu-objcopy -I binary -O ihex --change-addresses 0xffe00000 bl2.bin bl2.hex + quartus_cpf --bootloader bl2.hex <quartus_generated_sof> <output_sof_with_bl2> + +- Configure SOF to board + +.. code:: bash + + nios2-configure-sof <output_sof_with_bl2> + +Boot trace +---------- + +:: + + INFO: DDR: DRAM calibration success. + INFO: ECC is disabled. + NOTICE: BL2: v2.1(debug) + NOTICE: BL2: Built + INFO: BL2: Doing platform setup + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0xffe1c000 + INFO: SPSR = 0x3cd + NOTICE: BL31: v2.1(debug) + NOTICE: BL31: Built + INFO: ARM GICv2 driver initialized + INFO: BL31: Initializing runtime services + WARNING: BL31: cortex_a53 + INFO: BL31: Preparing for EL3 exit to normal world + INFO: Entry point address = 0x50000 + INFO: SPSR = 0x3c9 diff --git a/docs/plat/intel-stratix10.rst b/docs/plat/intel-stratix10.rst new file mode 100644 index 0000000..7f8d18e --- /dev/null +++ b/docs/plat/intel-stratix10.rst @@ -0,0 +1,94 @@ +Intel Stratix 10 SoCFPGA +======================== + +Stratix 10 SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor. + +Upon boot, Boot ROM loads bl2 into OCRAM. Bl2 subsequently initializes +the hardware, then loads bl31 and bl33 (UEFI) into DDR and boots to bl33. + +:: + + Boot ROM --> Trusted Firmware-A --> UEFI + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- UEFI (to be updated with new upstreamed UEFI): + `link <https://github.com/altera-opensource/uefi-socfpga>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Fetch all the above 2 repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + +- Prepare the AARCH64 toolchain. + +- Build UEFI using Stratix 10 platform as configuration + This will be updated to use an updated UEFI using the latest EDK2 source + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- device=s10 + +- Build atf providing the previously generated UEFI as the BL33 image + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- bl2 fip PLAT=stratix10 + BL33=PEI.ROM + +Install Procedure +~~~~~~~~~~~~~~~~~ + +- dd fip.bin to a A2 partition on the MMC drive to be booted in Stratix 10 + board. + +- Generate a SOF containing bl2 + +.. code:: bash + + aarch64-linux-gnu-objcopy -I binary -O ihex --change-addresses 0xffe00000 bl2.bin bl2.hex + quartus_cpf --bootloader bl2.hex <quartus_generated_sof> <output_sof_with_bl2> + +- Configure SOF to board + +.. code:: bash + + nios2-configure-sof <output_sof_with_bl2> + +Boot trace +---------- + +:: + + INFO: DDR: DRAM calibration success. + INFO: ECC is disabled. + INFO: Init HPS NOC's DDR Scheduler. + NOTICE: BL2: v2.0(debug):v2.0-809-g7f8474a-dirty + NOTICE: BL2: Built : 17:38:19, Feb 18 2019 + INFO: BL2: Doing platform setup + INFO: BL2: Loading image id 3 + INFO: Loading image id=3 at address 0xffe1c000 + INFO: Image id=3 loaded: 0xffe1c000 - 0xffe24034 + INFO: BL2: Loading image id 5 + INFO: Loading image id=5 at address 0x50000 + INFO: Image id=5 loaded: 0x50000 - 0x550000 + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0xffe1c000 + INFO: SPSR = 0x3cd + NOTICE: BL31: v2.0(debug):v2.0-810-g788c436-dirty + NOTICE: BL31: Built : 15:17:16, Feb 20 2019 + INFO: ARM GICv2 driver initialized + INFO: BL31: Initializing runtime services + WARNING: BL31: cortex_a53: CPU workaround for 855873 was missing! + INFO: BL31: Preparing for EL3 exit to normal world + INFO: Entry point address = 0x50000 + INFO: SPSR = 0x3c9 + UEFI firmware (version 1.0 built at 11:26:18 on Nov 7 2018) diff --git a/docs/plat/marvell/armada/build.rst b/docs/plat/marvell/armada/build.rst new file mode 100644 index 0000000..8cb3fdf --- /dev/null +++ b/docs/plat/marvell/armada/build.rst @@ -0,0 +1,476 @@ +TF-A Build Instructions for Marvell Platforms +============================================= + +This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms. + +Build Instructions +------------------ +(1) Set the cross compiler + + .. code:: shell + + > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu- + +(2) Set path for FIP images: + +Set U-Boot image path (relatively to TF-A root or absolute path) + + .. code:: shell + + > export BL33=path/to/u-boot.bin + +For example: if U-Boot project (and its images) is located at ``~/project/u-boot``, +BL33 should be ``~/project/u-boot/u-boot.bin`` + + .. note:: + + *u-boot.bin* should be used and not *u-boot-spl.bin* + +Set MSS/SCP image path (mandatory only for A7K/A8K/CN913x when MSS_SUPPORT=1) + + .. code:: shell + + > export SCP_BL2=path/to/mrvl_scp_bl2*.img + +(3) Armada-37x0 build requires WTP tools installation. + +See below in the section "Tools and external components installation". +Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3 + + .. code:: shell + + > sudo apt-get install gcc-arm-linux-gnueabi + +(4) Clean previous build residuals (if any) + + .. code:: shell + + > make distclean + +(5) Build TF-A + +There are several build options: + +- PLAT + + Supported Marvell platforms are: + + - a3700 - A3720 DB, EspressoBin and Turris MOX + - a70x0 + - a70x0_amc - AMC board + - a70x0_mochabin - Globalscale MOCHAbin + - a80x0 + - a80x0_mcbin - MacchiatoBin + - a80x0_puzzle - IEI Puzzle-M801 + - t9130 - CN913x + - t9130_cex7_eval - CN913x CEx7 Evaluation Board + +- DEBUG + + Default is without debug information (=0). in order to enable it use ``DEBUG=1``. + Can be enabled also when building UART recovery images, there is no issue with it. + + Production TF-A images should be built without this debug option! + +- LOG_LEVEL + + Defines the level of logging which will be purged to the default output port. + + - 0 - LOG_LEVEL_NONE + - 10 - LOG_LEVEL_ERROR + - 20 - LOG_LEVEL_NOTICE (default for DEBUG=0) + - 30 - LOG_LEVEL_WARNING + - 40 - LOG_LEVEL_INFO (default for DEBUG=1) + - 50 - LOG_LEVEL_VERBOSE + +- USE_COHERENT_MEM + + This flag determines whether to include the coherent memory region in the + BL memory map or not. Enabled by default. + +- LLC_ENABLE + + Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``). + +- LLC_SRAM + + Flag enabling the LLC (L3) cache SRAM support. The LLC SRAM is activated and used + by Trusted OS (OP-TEE OS, BL32). The TF-A only prepares CCU address translation windows + for SRAM address range at BL31 execution stage with window target set to DRAM-0. + When Trusted OS activates LLC SRAM, the CCU window target is changed to SRAM. + There is no reason to enable this feature if OP-TEE OS built with CFG_WITH_PAGER=n. + Only set LLC_SRAM=1 if OP-TEE OS is built with CFG_WITH_PAGER=y. + +- MARVELL_SECURE_BOOT + + Build trusted(=1)/non trusted(=0) image, default is non trusted. + This parameter is used only for ``mrvl_flash`` and ``mrvl_uart`` targets. + +- MV_DDR_PATH + + This parameter is required for ``mrvl_flash`` and ``mrvl_uart`` targets. + For A7K/A8K/CN913x it is used for BLE build and for Armada37x0 it used + for ddr_tool build. + + Specify path to the full checkout of Marvell mv-ddr-marvell git + repository. Checkout must contain also .git subdirectory because + mv-ddr build process calls git commands. + + Do not remove any parts of git checkout becuase build process and other + applications need them for correct building and version determination. + + +CN913x specific build options: + +- CP_NUM + + Total amount of CPs (South Bridge) connected to AP. When the parameter is omitted, + the build uses the default number of CPs, which is a number of embedded CPs inside the + package: 1 or 2 depending on the SoC used. The parameter is valid for OcteonTX2 CN913x SoC + family (PLAT=t9130), which can have external CPs connected to the MCI ports. Valid + values with CP_NUM are in a range of 1 to 3. + + +A7K/A8K/CN913x specific build options: + +- BLE_PATH + + Points to BLE (Binary ROM extension) sources folder. + The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble`` + which uses TF-A in-tree BLE implementation. + +- MSS_SUPPORT + + When ``MSS_SUPPORT=1``, then TF-A includes support for Management SubSystem (MSS). + When enabled it is required to specify path to the MSS firmware image via ``SCP_BL2`` + option. + + This option is by default enabled. + +- SCP_BL2 + + Specify path to the MSS fimware image binary which will run on Cortex-M3 coprocessor. + It is available in Marvell binaries-marvell git repository. Required when ``MSS_SUPPORT=1``. + +Globalscale MOCHAbin specific build options: + +- DDR_TOPOLOGY + + The DDR topology map index/name, default is 0. + + Supported Options: + - 0 - DDR4 1CS 2GB + - 1 - DDR4 1CS 4GB + - 2 - DDR4 2CS 8GB + +Armada37x0 specific build options: + +- HANDLE_EA_EL3_FIRST_NS + + When ``HANDLE_EA_EL3_FIRST_NS=1``, External Aborts and SError Interrupts, resulting from errors + in NS world, will be always trapped in TF-A. TF-A in this case enables dirty hack / workaround for + a bug found in U-Boot and Linux kernel PCIe controller driver pci-aardvark.c, traps and then masks + SError interrupt caused by AXI SLVERR on external access (syndrome 0xbf000002). + + Otherwise when ``HANDLE_EA_EL3_FIRST_NS=0``, these exceptions will be trapped in the current + exception level (or in EL1 if the current exception level is EL0). So exceptions caused by + U-Boot will be trapped in U-Boot, exceptions caused by Linux kernel (or user applications) + will be trapped in Linux kernel. + + Mentioned bug in pci-aardvark.c driver is fixed in U-Boot version v2021.07 and Linux kernel + version v5.13 (workarounded since Linux kernel version 5.9) and also backported in Linux + kernel stable releases since versions v5.12.13, v5.10.46, v5.4.128, v4.19.198, v4.14.240. + + If target system has already patched version of U-Boot and Linux kernel then it is strongly + recommended to not enable this workaround as it disallows propagating of all External Aborts + to running Linux kernel and makes correctable errors as fatal aborts. + + This option is now disabled by default. In past this option has different name "HANDLE_EA_EL3_FIRST" and + was enabled by default in TF-A versions v2.2, v2.3, v2.4 and v2.5. + +- CM3_SYSTEM_RESET + + When ``CM3_SYSTEM_RESET=1``, the Cortex-M3 secure coprocessor will be used for system reset. + + TF-A will send command 0x0009 with a magic value via the rWTM mailbox interface to the + Cortex-M3 secure coprocessor. + The firmware running in the coprocessor must either implement this functionality or + ignore the 0x0009 command (which is true for the firmware from A3700-utils-marvell + repository). If this option is enabled but the firmware does not support this command, + an error message will be printed prior trying to reboot via the usual way. + + This option is needed on Turris MOX as a workaround to a HW bug which causes reset to + sometime hang the board. + +- A3720_DB_PM_WAKEUP_SRC + + For Armada 3720 Development Board only, when ``A3720_DB_PM_WAKEUP_SRC=1``, + TF-A will setup PM wake up src configuration. This option is disabled by default. + + +Armada37x0 specific build options for ``mrvl_flash`` and ``mrvl_uart`` targets: + +- DDR_TOPOLOGY + + The DDR topology map index/name, default is 0. + + Supported Options: + - 0 - DDR3 1CS 512MB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) + - 1 - DDR4 1CS 512MB (DB-88F3720-DDR4-Modular) + - 2 - DDR3 2CS 1GB (EspressoBin V3-V5) + - 3 - DDR4 2CS 4GB (DB-88F3720-DDR4-Modular) + - 4 - DDR3 1CS 1GB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) + - 5 - DDR4 1CS 1GB (EspressoBin V7, EspressoBin-Ultra) + - 6 - DDR4 2CS 2GB (EspressoBin V7) + - 7 - DDR3 2CS 2GB (EspressoBin V3-V5) + - CUST - CUSTOMER BOARD (Customer board settings) + +- CLOCKSPRESET + + The clock tree configuration preset including CPU and DDR frequency, + default is CPU_800_DDR_800. + + - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz + - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz + - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz + - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz + + Look at Armada37x0 chip package marking on board to identify correct CPU frequency. + The last line on package marking (next line after the 88F37x0 line) should contain: + + - C080 or I080 - chip with 800 MHz CPU - use ``CLOCKSPRESET=CPU_800_DDR_800`` + - C100 or I100 - chip with 1000 MHz CPU - use ``CLOCKSPRESET=CPU_1000_DDR_800`` + - C120 - chip with 1200 MHz CPU - use ``CLOCKSPRESET=CPU_1200_DDR_750`` + +- BOOTDEV + + The flash boot device, default is ``SPINOR``. + + Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``: + + - SPINOR - SPI NOR flash boot + - SPINAND - SPI NAND flash boot + - EMMCNORM - eMMC Download Mode + + Download boot loader or program code from eMMC flash into CM3 or CA53 + Requires full initialization and command sequence + + - SATA - SATA device boot + + Image needs to be stored at disk LBA 0 or at disk partition with + MBR type 0x4d (ASCII 'M' as in Marvell) or at disk partition with + GPT partition type GUID ``6828311A-BA55-42A4-BCDE-A89BB5EDECAE``. + +- PARTNUM + + The boot partition number, default is 0. + + To boot from eMMC, the value should be aligned with the parameter in + U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is + 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot + build instructions. + +- WTMI_IMG + + The path of the binary can point to an image which + does nothing, an image which supports EFUSE or a customized CM3 firmware + binary. The default image is ``fuse.bin`` that built from sources in WTP + folder, which is the next option. If the default image is OK, then this + option should be skipped. + + Please note that this is not a full WTMI image, just a main loop without + hardware initialization code. Final WTMI image is built from this WTMI_IMG + binary and sys-init code from the WTP directory which sets DDR and CPU + clocks according to DDR_TOPOLOGY and CLOCKSPRESET options. + + CZ.NIC as part of Turris project released free and open source WTMI + application firmware ``wtmi_app.bin`` for all Armada 3720 devices. + This firmware includes additional features like access to Hardware + Random Number Generator of Armada 3720 SoC which original Marvell's + ``fuse.bin`` image does not have. + + CZ.NIC's Armada 3720 Secure Firmware is available at website: + + https://gitlab.nic.cz/turris/mox-boot-builder/ + +- WTP + + Specify path to the full checkout of Marvell A3700-utils-marvell git + repository. Checkout must contain also .git subdirectory because WTP + build process calls git commands. + + WTP build process uses also Marvell mv-ddr-marvell git repository + specified in MV_DDR_PATH option. + + Do not remove any parts of git checkout becuase build process and other + applications need them for correct building and version determination. + +- CRYPTOPP_PATH + + Use this parameter to point to Crypto++ source code + directory. If this option is specified then Crypto++ source code in + CRYPTOPP_PATH directory will be automatically compiled. Crypto++ library + is required for building WTP image tool. Either CRYPTOPP_PATH or + CRYPTOPP_LIBDIR with CRYPTOPP_INCDIR needs to be specified for Armada37x0. + +- CRYPTOPP_LIBDIR + + Use this parameter to point to the directory with + compiled Crypto++ library. By default it points to the CRYPTOPP_PATH. + + On Debian systems it is possible to install system-wide Crypto++ library + via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_LIBDIR + to ``/usr/lib/``. + +- CRYPTOPP_INCDIR + + Use this parameter to point to the directory with + header files of Crypto++ library. By default it points to the CRYPTOPP_PATH. + + On Debian systems it is possible to install system-wide Crypto++ library + via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_INCDIR + to ``/usr/include/crypto++/``. + + +For example, in order to build the image in debug mode with log level up to 'notice' level run + +.. code:: shell + + > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> mrvl_flash + +And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level, +the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS, +the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command +line is as following + +.. code:: shell + + > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \ + MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 \ + MV_DDR_PATH=/path/to/mv-ddr-marvell/ WTP=/path/to/A3700-utils-marvell/ \ + CRYPTOPP_PATH=/path/to/cryptopp/ BL33=/path/to/u-boot.bin \ + all fip mrvl_bootimage mrvl_flash mrvl_uart + +To build just TF-A without WTMI image (useful for A3720 Turris MOX board), run following command: + +.. code:: shell + + > make USE_COHERENT_MEM=0 PLAT=a3700 CM3_SYSTEM_RESET=1 BL33=/path/to/u-boot.bin \ + CROSS_COMPILE=aarch64-linux-gnu- mrvl_bootimage + +Here is full example how to build production release of Marvell firmware image (concatenated +binary of Marvell's A3720 sys-init, CZ.NIC's Armada 3720 Secure Firmware, TF-A and U-Boot) for +EspressoBin board (PLAT=a3700) with 1GHz CPU (CLOCKSPRESET=CPU_1000_DDR_800) and +1GB DDR4 RAM (DDR_TOPOLOGY=5): + +.. code:: shell + + > git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + > git clone https://source.denx.de/u-boot/u-boot.git + > git clone https://github.com/weidai11/cryptopp.git + > git clone https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git + > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git + > git clone https://gitlab.nic.cz/turris/mox-boot-builder.git + > make -C u-boot CROSS_COMPILE=aarch64-linux-gnu- mvebu_espressobin-88f3720_defconfig u-boot.bin + > make -C mox-boot-builder CROSS_CM3=arm-linux-gnueabi- wtmi_app.bin + > make -C trusted-firmware-a CROSS_COMPILE=aarch64-linux-gnu- CROSS_CM3=arm-linux-gnueabi- \ + USE_COHERENT_MEM=0 PLAT=a3700 CLOCKSPRESET=CPU_1000_DDR_800 DDR_TOPOLOGY=5 \ + MV_DDR_PATH=$PWD/mv-ddr-marvell/ WTP=$PWD/A3700-utils-marvell/ \ + CRYPTOPP_PATH=$PWD/cryptopp/ BL33=$PWD/u-boot/u-boot.bin \ + WTMI_IMG=$PWD/mox-boot-builder/wtmi_app.bin FIP_ALIGN=0x100 mrvl_flash + +Produced Marvell firmware flash image: ``trusted-firmware-a/build/a3700/release/flash-image.bin`` + +Special Build Flags +-------------------- + +- PLAT_RECOVERY_IMAGE_ENABLE + When set this option to enable secondary recovery function when build atf. + In order to build UART recovery image this operation should be disabled for + A7K/A8K/CN913x because of hardware limitation (boot from secondary image + can interrupt UART recovery process). This MACRO definition is set in + ``plat/marvell/armada/a8k/common/include/platform_def.h`` file. + +- DDR32 + In order to work in 32bit DDR, instead of the default 64bit ECC DDR, + this flag should be set to 1. + +For more information about build options, please refer to the +:ref:`Build Options` document. + + +Build output +------------ +Marvell's TF-A compilation generates 8 files: + + - ble.bin - BLe image (not available for Armada37x0) + - bl1.bin - BL1 image + - bl2.bin - BL2 image + - bl31.bin - BL31 image + - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images) + - boot-image.bin - TF-A image (contains BL1 and FIP images) + - flash-image.bin - Flashable Marvell firmware image. For Armada37x0 it + contains TIM, WTMI and boot-image.bin images. For other platforms it contains + BLe and boot-image.bin images. Should be placed on the boot flash/device. + - uart-images.tgz.bin - GZIPed TAR archive which contains Armada37x0 images + for booting via UART. Could be loaded via Marvell's WtpDownload tool from + A3700-utils-marvell repository. + +Additional make target ``mrvl_bootimage`` produce ``boot-image.bin`` file. Target +``mrvl_flash`` produce final ``flash-image.bin`` file and target ``mrvl_uart`` +produce ``uart-images.tgz.bin`` file. + + +Tools and external components installation +------------------------------------------ + +Armada37x0 Builds require installation of additional components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(1) ARM cross compiler capable of building images for the service CPU (CM3). + This component is usually included in the Linux host packages. + On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed + using the following command + + .. code:: shell + + > sudo apt-get install gcc-arm-linux-gnueabi + + Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be + overwritten using the environment variable ``CROSS_CM3``. + Example for BASH shell + + .. code:: shell + + > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi + +(2) DDR initialization library sources (mv_ddr) available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git + +(3) Armada3700 tools available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git + +(4) Crypto++ library available at the following repository: + + https://github.com/weidai11/cryptopp.git + +(5) Optional CZ.NIC's Armada 3720 Secure Firmware: + + https://gitlab.nic.cz/turris/mox-boot-builder.git + +Armada70x0, Armada80x0 and CN913x Builds require installation of additional components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(1) DDR initialization library sources (mv_ddr) available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git + +(2) MSS Management SubSystem Firmware available at the following repository + (use the "binaries-marvell-armada-SDK10.0.1.0" branch): + + https://github.com/MarvellEmbeddedProcessors/binaries-marvell.git diff --git a/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst new file mode 100644 index 0000000..e88a458 --- /dev/null +++ b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst @@ -0,0 +1,49 @@ +Address decoding flow and address translation units of Marvell Armada 8K SoC family +=================================================================================== + +:: + + +--------------------------------------------------------------------------------------------------+ + | +-------------+ +--------------+ | + | | Memory +----- DRAM CS | | + |+------------+ +-----------+ +-----------+ | Controller | +--------------+ | + || AP DMA | | | | | +-------------+ | + || SD/eMMC | | CA72 CPUs | | AP MSS | +-------------+ | + || MCI-0/1 | | | | | | Memory | | + |+------+-----+ +--+--------+ +--------+--+ +------------+ | Controller | +-------------+ | + | | | | | +----- Translaton | |AP | | + | | | | | | +-------------+ |Configuration| | + | | | +-----+ +-------------------------Space | | + | | | +-------------+ | CCU | +-------------+ | + | | | | MMU +---------+ Windows | +-----------+ +-------------+ | + | | +-| translation | | Lookup +---- +--------- AP SPI | | + | | +-------------+ | | | | +-------------+ | + | | +-------------+ | | | IO | +-------------+ | + | +------------| SMMU +---------+ | | Windows +--------- AP MCI0/1 | | + | | translation | +------------+ | Lookup | +-------------+ | + | +---------+---+ | | +-------------+ | + | - | | +--------- AP STM | | + | +----------------- | | +-------------+ | + | AP | | +-+---------+ | + +---------------------------------------------------------------|----------------------------------+ + +-------------|-------------------------------------------------|----------------------------------+ + | CP | +-------------+ +------+-----+ +-------------------+ | + | | | | | +------- SB CFG Space | | + | | | DIOB | | | +-------------------+ | + | | | Windows ----------------- IOB | +-------------------+ | + | | | Control | | Windows +------| SB PCIe-0 - PCIe2 | | + | | | | | Lookup | +-------------------+ | + | | +------+------+ | | +-------------------+ | + | | | | +------+ SB NAND | | + | | | +------+-----+ +-------------------+ | + | | | | | + | | | | | + | +------------------+ +------------+ +------+-----+ +-------------------+ | + | | Network Engine | | | | +------- SB SPI-0/SPI-1 | | + | | Security Engine | | PCIe, MSS | | RUNIT | +-------------------+ | + | | SATA, USB | | DMA | | Windows | +-------------------+ | + | | SD/eMMC | | | | Lookup +------- SB Device Bus | | + | | TDM, I2C | | | | | +-------------------+ | + | +------------------+ +------------+ +------------+ | + | | + +--------------------------------------------------------------------------------------------------+ diff --git a/docs/plat/marvell/armada/misc/mvebu-amb.rst b/docs/plat/marvell/armada/misc/mvebu-amb.rst new file mode 100644 index 0000000..d734003 --- /dev/null +++ b/docs/plat/marvell/armada/misc/mvebu-amb.rst @@ -0,0 +1,58 @@ +AMB - AXI MBUS address decoding +=============================== + +AXI to M-bridge decoding unit driver for Marvell Armada 8K and 8K+ SoCs. + +The Runit offers a second level of address windows lookup. It is used to map +transaction towards the CD BootROM, SPI0, SPI1 and Device bus (NOR). + +The Runit contains eight configurable windows. Each window defines a contiguous, +address space and the properties associated with that address space. + +:: + + Unit Bank ATTR + Device-Bus DEV_BOOT_CS 0x2F + DEV_CS0 0x3E + DEV_CS1 0x3D + DEV_CS2 0x3B + DEV_CS3 0x37 + SPI-0 SPI_A_CS0 0x1E + SPI_A_CS1 0x5E + SPI_A_CS2 0x9E + SPI_A_CS3 0xDE + SPI_A_CS4 0x1F + SPI_A_CS5 0x5F + SPI_A_CS6 0x9F + SPI_A_CS7 0xDF + SPI SPI_B_CS0 0x1A + SPI_B_CS1 0x5A + SPI_B_CS2 0x9A + SPI_B_CS3 0xDA + BOOT_ROM BOOT_ROM 0x1D + UART UART 0x01 + +Mandatory functions +------------------- + +- marvell_get_amb_memory_map + Returns the AMB windows configuration and the number of windows + +Mandatory structures +-------------------- + +- amb_memory_map + Array that include the configuration of the windows. Every window/entry is a + struct which has 2 parameters: + + - Base address of the window + - Attribute of the window + +Examples +-------- + +.. code:: c + + struct addr_map_win amb_memory_map[] = { + {0xf900, AMB_DEV_CS0_ID}, + }; diff --git a/docs/plat/marvell/armada/misc/mvebu-ccu.rst b/docs/plat/marvell/armada/misc/mvebu-ccu.rst new file mode 100644 index 0000000..12118e9 --- /dev/null +++ b/docs/plat/marvell/armada/misc/mvebu-ccu.rst @@ -0,0 +1,33 @@ +Marvell CCU address decoding bindings +===================================== + +CCU configuration driver (1st stage address translation) for Marvell Armada 8K and 8K+ SoCs. + +The CCU node includes a description of the address decoding configuration. + +Mandatory functions +------------------- + +- marvell_get_ccu_memory_map + Return the CCU windows configuration and the number of windows of the + specific AP. + +Mandatory structures +-------------------- + +- ccu_memory_map + Array that includes the configuration of the windows. Every window/entry is + a struct which has 3 parameters: + + - Base address of the window + - Size of the window + - Target-ID of the window + +Example +------- + +.. code:: c + + struct addr_map_win ccu_memory_map[] = { + {0x00000000f2000000, 0x00000000e000000, IO_0_TID}, /* IO window */ + }; diff --git a/docs/plat/marvell/armada/misc/mvebu-io-win.rst b/docs/plat/marvell/armada/misc/mvebu-io-win.rst new file mode 100644 index 0000000..7498291 --- /dev/null +++ b/docs/plat/marvell/armada/misc/mvebu-io-win.rst @@ -0,0 +1,46 @@ +Marvell IO WIN address decoding bindings +======================================== + +IO Window configuration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs. + +The IO WIN includes a description of the address decoding configuration. + +Transactions that are decoded by CCU windows as IO peripheral, have an additional +layer of decoding. This additional address decoding layer defines one of the +following targets: + +- **0x0** = BootRom +- **0x1** = STM (Serial Trace Macro-cell, a programmer's port into trace stream) +- **0x2** = SPI direct access +- **0x3** = PCIe registers +- **0x4** = MCI Port +- **0x5** = PCIe port + +Mandatory functions +------------------- + +- marvell_get_io_win_memory_map + Returns the IO windows configuration and the number of windows of the + specific AP. + +Mandatory structures +-------------------- + +- io_win_memory_map + Array that include the configuration of the windows. Every window/entry is + a struct which has 3 parameters: + + - Base address of the window + - Size of the window + - Target-ID of the window + +Example +------- + +.. code:: c + + struct addr_map_win io_win_memory_map[] = { + {0x00000000fe000000, 0x000000001f00000, PCIE_PORT_TID}, /* PCIe window 31Mb for PCIe port*/ + {0x00000000ffe00000, 0x000000000100000, PCIE_REGS_TID}, /* PCI-REG window 64Kb for PCIe-reg*/ + {0x00000000f6000000, 0x000000000100000, MCIPHY_TID}, /* MCI window 1Mb for PHY-reg*/ + }; diff --git a/docs/plat/marvell/armada/misc/mvebu-iob.rst b/docs/plat/marvell/armada/misc/mvebu-iob.rst new file mode 100644 index 0000000..aa41822 --- /dev/null +++ b/docs/plat/marvell/armada/misc/mvebu-iob.rst @@ -0,0 +1,52 @@ +Marvell IOB address decoding bindings +===================================== + +IO bridge configuration driver (3rd stage address translation) for Marvell Armada 8K and 8K+ SoCs. + +The IOB includes a description of the address decoding configuration. + +IOB supports up to n (in CP110 n=24) windows for external memory transaction. +When a transaction passes through the IOB, its address is compared to each of +the enabled windows. If there is a hit and it passes the security checks, it is +advanced to the target port. + +Mandatory functions +------------------- + +- marvell_get_iob_memory_map + Returns the IOB windows configuration and the number of windows + +Mandatory structures +-------------------- + +- iob_memory_map + Array that includes the configuration of the windows. Every window/entry is + a struct which has 3 parameters: + + - Base address of the window + - Size of the window + - Target-ID of the window + +Target ID options +----------------- + +- **0x0** = Internal configuration space +- **0x1** = MCI0 +- **0x2** = PEX1_X1 +- **0x3** = PEX2_X1 +- **0x4** = PEX0_X4 +- **0x5** = NAND flash +- **0x6** = RUNIT (NOR/SPI/BootRoom) +- **0x7** = MCI1 + +Example +------- + +.. code:: c + + struct addr_map_win iob_memory_map[] = { + {0x00000000f7000000, 0x0000000001000000, PEX1_TID}, /* PEX1_X1 window */ + {0x00000000f8000000, 0x0000000001000000, PEX2_TID}, /* PEX2_X1 window */ + {0x00000000f6000000, 0x0000000001000000, PEX0_TID}, /* PEX0_X4 window */ + {0x00000000f9000000, 0x0000000001000000, NAND_TID} /* NAND window */ + }; diff --git a/docs/plat/marvell/armada/porting.rst b/docs/plat/marvell/armada/porting.rst new file mode 100644 index 0000000..ba8736d --- /dev/null +++ b/docs/plat/marvell/armada/porting.rst @@ -0,0 +1,158 @@ +TF-A Porting Guide for Marvell Platforms +======================================== + +This section describes how to port TF-A to a customer board, assuming that the +SoC being used is already supported in TF-A. + + +Source Code Structure +--------------------- + +- The customer platform specific code shall reside under ``plat/marvell/armada/<soc family>/<soc>_cust`` + (e.g. 'plat/marvell/armada/a8k/a7040_cust'). +- The platform name for build purposes is called ``<soc>_cust`` (e.g. ``a7040_cust``). +- The build system will reuse all files from within the soc directory, and take only the porting + files from the customer platform directory. + +Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory. + + +Armada-70x0/Armada-80x0 Porting +------------------------------- + +SoC Physical Address Map (marvell_plat_config.c) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This file describes the SoC physical memory mapping to be used for the CCU, +IOWIN, AXI-MBUS and IOB address decode units (Refer to the functional spec for +more details). + +In most cases, using the default address decode windows should work OK. + +In cases where a special physical address map is needed (e.g. Special size for +PCIe MEM windows, large memory mapped SPI flash...), then porting of the SoC +memory map is required. + +.. note:: + For a detailed information on how CCU, IOWIN, AXI-MBUS & IOB work, please + refer to the SoC functional spec, and under + ``docs/plat/marvell/armada/misc/mvebu-[ccu/iob/amb/io-win].rst`` files. + +boot loader recovery (marvell_plat_config.c) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Background: + + Boot rom can skip the current image and choose to boot from next position if a + specific value (``0xDEADB002``) is returned by the ble main function. This + feature is used for boot loader recovery by booting from a valid flash-image + saved in next position on flash (e.g. address 2M in SPI flash). + + Supported options to implement the skip request are: + - GPIO + - I2C + - User defined + +- Porting: + + Under marvell_plat_config.c, implement struct skip_image that includes + specific board parameters. + + .. warning:: + To disable this feature make sure the struct skip_image is not implemented. + +- Example: + +In A7040-DB specific implementation +(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is +implemented using GPIO: mpp 33 (SW5). + +Before resetting the board make sure there is a valid image on the next flash +address: + + -tftp [valid address] flash-image.bin + -sf update [valid address] 0x2000000 [size] + +Press reset and keep pressing the button connected to the chosen GPIO pin. A +skip image request message is printed on the screen and boot rom boots from the +saved image at the next position. + +DDR Porting (dram_port.c) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This file defines the dram topology and parameters of the target board. + +The DDR code is part of the BLE component, which is an extension of ARM Trusted +Firmware (TF-A). + +The DDR driver called mv_ddr is released separately apart from TF-A sources. + +The BLE and consequently, the DDR init code is executed at the early stage of +the boot process. + +Each supported platform of the TF-A has its own DDR porting file called +dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory. + +Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed +porting description. + +The build target directory is "build/<platform>/release/ble". + +Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Background: + Some of the comphy's parameters value depend on the HW connection between + the SoC and the PHY. Every board type has specific HW characteristics like + wire length. Due to those differences some comphy parameters vary between + board types. Therefore each board type can have its own list of values for + all relevant comphy parameters. The PHY porting layer specifies which + parameters need to be suited and the board designer should provide relevant + values. + + The PHY porting layer simplifies updating static values per board type, + which are now grouped in one place. + + .. note:: + The parameters for the same type of comphy may vary even for the same + board type, it is because the lanes from comphy-x to some PHY may have + different HW characteristic than lanes from comphy-y to the same + (multiplexed) or other PHY. + +- Porting: + The porting layer for PHY was introduced in TF-A. There is one file + ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the + defaults. Those default parameters are used only if there is no appropriate + phy-porting-layer.h file under: ``plat/marvell/armada/<soc + family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h + exists, the phy-default-porting-layer.h is not going to be included. + + .. warning:: + Not all comphy types are already reworked to support the PHY porting + layer, currently the porting layer is supported for XFI/SFI and SATA + comphy types. + + The easiest way to prepare the PHY porting layer for custom board is to copy + existing example to a new platform: + + - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h" + - adjust relevant parameters or + - if different comphy index is used for specific feature, move it to proper table entry and then adjust. + + .. note:: + The final table size with comphy parameters can be different, depending + on the CP module count for given SoC type. + +- Example: + Example porting layer for armada-8040-db is under: + ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` + + .. note:: + If there is no PHY porting layer for new platform (missing + phy-porting-layer.h), the default values are used + (drivers/marvell/comphy/phy-default-porting-layer.h) and the user is + warned: + + .. warning:: + "Using default comphy parameters - it may be required to suit them for + your board". diff --git a/docs/plat/marvell/armada/uart-booting.rst b/docs/plat/marvell/armada/uart-booting.rst new file mode 100644 index 0000000..04ce464 --- /dev/null +++ b/docs/plat/marvell/armada/uart-booting.rst @@ -0,0 +1,103 @@ +TF-A UART Booting Instructions for Marvell Platforms +==================================================== + +This section describes how to temporary boot the Trusted Firmware-A (TF-A) project over UART +without flashing it to non-volatile storage for Marvell's platforms. + +See :ref:`TF-A Build Instructions for Marvell Platforms` how to build ``mrvl_uart`` and +``mrvl_flash`` targets used in this section. + +Armada37x0 UART image downloading +--------------------------------- + +There are two options how to download UART image into any Armada37x0 board. + +Marvell Wtpdownloader +~~~~~~~~~~~~~~~~~~~~~ + +Marvell Wtpdownloader works only with UART images stored in separate files and supports only upload +speed with 115200 bauds. Target ``mrvl_uart`` produces GZIPed TAR archive ``uart-images.tgz.bin`` +with either three files ``TIM_ATF.bin``, ``wtmi_h.bin`` and ``boot-image_h.bin`` for non-secure +boot or with four files ``TIM_ATF_TRUSTED.bin``, ``TIMN_ATF_TRUSTED.bin``, ``wtmi_h.bin`` and +``boot-image_h.bin`` when secure boot is enabled. + +Compilation: + +.. code:: shell + + > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git + > make -C A3700-utils-marvell/wtptp/src/Wtpdownloader_Linux -f makefile.mk + +It produces executable binary ``A3700-utils-marvell/wtptp/src/Wtpdownloader_Linux/WtpDownload_linux`` + +To download images from ``uart-images.tgz.bin`` archive unpack it and for non-secure boot variant run: + +.. code:: shell + + > stty -F /dev/ttyUSB<port#> clocal + > WtpDownload_linux -P UART -C <port#> -E -B TIM_ATF.bin -I wtmi_h.bin -I boot-image_h.bin + +After that immediately start terminal on ``/dev/ttyUSB<port#>`` to see boot output. + +CZ.NIC mox-imager +~~~~~~~~~~~~~~~~~ + +CZ.NIC mox-imager supports all Armada37x0 boards (not only Turris MOX as name suggests). It works +with either with separate files from ``uart-images.tgz.bin`` archive (like Marvell Wtpdownloader) +produced by ``mrvl_uart`` target or also with ``flash-image.bin`` file produced by ``mrvl_flash`` +target, which is the exactly same file as used for flashing. So when using CZ.NIC mox-imager there +is no need to build separate files for UART flashing like in case with Marvell Wtpdownloader. + +CZ.NIC mox-imager moreover supports higher upload speeds up to the 6000000 bauds (which seems to +be limit of Armada37x0 SoC) which is much higher and faster than Marvell Wtpdownloader. + +Compilation: + +.. code:: shell + + > git clone https://gitlab.nic.cz/turris/mox-imager.git + > make -C mox-imager + +It produces executable binary ``mox-imager/mox-imager`` + +To download single file image built by ``mrvl_flash`` target at the highest speed, run: + +.. code:: shell + + > mox-imager -D /dev/ttyUSB<port#> -E -b 6000000 -t flash-image.bin + +To download images from ``uart-images.tgz.bin`` archive built by ``mrvl_uart`` target for +non-secure boot variant (like Wtpdownloader) but at the highest speed, first unpack +``uart-images.tgz.bin`` archive and then run: + +.. code:: shell + + > mox-imager -D /dev/ttyUSB<port#> -E -b 6000000 -t TIM_ATF.bin wtmi_h.bin boot-image_h.bin + +CZ.NIC mox-imager after successful download will start its own mini terminal (option ``-t``) to +not loose any boot output. It also prints boot output which is sent either by image files or by +bootrom during transferring of image files. This mini terminal can be quit by CTRL-\\ + C keypress. + + +A7K/A8K/CN913x UART image downloading +------------------------------------- + +A7K/A8K/CN913x uses same image ``flash-image.bin`` for both flashing and booting over UART. +For downloading image over UART it is possible to use mvebu64boot tool. + +Compilation: + +.. code:: shell + + > git clone https://github.com/pali/mvebu64boot.git + > make -C mvebu64boot + +It produces executable binary ``mvebu64boot/mvebu64boot`` + +To download ``flash-image.bin`` image run: + +.. code:: shell + + > mvebu64boot -t -b flash-image.bin /dev/ttyUSB0 + +After successful download it will start own mini terminal (option ``-t``) like CZ.NIC mox-imager. diff --git a/docs/plat/marvell/index.rst b/docs/plat/marvell/index.rst new file mode 100644 index 0000000..2d5cdeb --- /dev/null +++ b/docs/plat/marvell/index.rst @@ -0,0 +1,15 @@ +Marvell +======= + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + armada/build + armada/uart-booting + armada/porting + armada/misc/mvebu-a8k-addr-map + armada/misc/mvebu-amb + armada/misc/mvebu-ccu + armada/misc/mvebu-io-win + armada/misc/mvebu-iob diff --git a/docs/plat/meson-axg.rst b/docs/plat/meson-axg.rst new file mode 100644 index 0000000..6f6732e --- /dev/null +++ b/docs/plat/meson-axg.rst @@ -0,0 +1,27 @@ +Amlogic Meson A113D (AXG) +=========================== + +The Amlogic Meson A113D is a SoC with a quad core Arm Cortex-A53 running at +~1.2GHz. It also contains a Cortex-M3 used as SCP. + +This port is a minimal implementation of BL31 capable of booting mainline U-Boot +and Linux: + +- SCPI support. +- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0 + can't be turned off, so there is a workaround to hide this from the caller. +- GICv2 driver set up. +- Basic SIP services (read efuse data, enable/disable JTAG). + +In order to build it: + +.. code:: shell + + CROSS_COMPILE=aarch64-none-elf- make DEBUG=1 PLAT=axg [SPD=opteed] + [AML_USE_ATOS=1 when using ATOS as BL32] + +This port has been tested on a A113D board. After building it, follow the +instructions in the `U-Boot repository`_, replacing the mentioned **bl31.img** +by the one built from this port. + +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/s400.rst diff --git a/docs/plat/meson-g12a.rst b/docs/plat/meson-g12a.rst new file mode 100644 index 0000000..9588ec4 --- /dev/null +++ b/docs/plat/meson-g12a.rst @@ -0,0 +1,27 @@ +Amlogic Meson S905X2 (G12A) +=========================== + +The Amlogic Meson S905X2 is a SoC with a quad core Arm Cortex-A53 running at +~1.8GHz. It also contains a Cortex-M3 used as SCP. + +This port is a minimal implementation of BL31 capable of booting mainline U-Boot +and Linux: + +- SCPI support. +- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0 + can't be turned off, so there is a workaround to hide this from the caller. +- GICv2 driver set up. +- Basic SIP services (read efuse data, enable/disable JTAG). + +In order to build it: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=g12a + +This port has been tested on a SEI510 board. After building it, follow the +instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the +mentioned **bl31.img** by the one built from this port. + +.. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README.g12a +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/sei510.rst diff --git a/docs/plat/meson-gxbb.rst b/docs/plat/meson-gxbb.rst new file mode 100644 index 0000000..dbd83e0 --- /dev/null +++ b/docs/plat/meson-gxbb.rst @@ -0,0 +1,26 @@ +Amlogic Meson S905 (GXBB) +========================= + +The Amlogic Meson S905 is a SoC with a quad core Arm Cortex-A53 running at +1.5Ghz. It also contains a Cortex-M3 used as SCP. + +This port is a minimal implementation of BL31 capable of booting mainline U-Boot +and Linux: + +- SCPI support. +- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0 + can't be turned off, so there is a workaround to hide this from the caller. +- GICv2 driver set up. +- Basic SIP services (read efuse data, enable/disable JTAG). + +In order to build it: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxbb bl31 + +This port has been tested in a ODROID-C2. After building it, follow the +instructions in the `U-Boot repository`_, replacing the mentioned **bl31.bin** +by the one built from this port. + +.. _U-Boot repository: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/amlogic/p200/README.odroid-c2 diff --git a/docs/plat/meson-gxl.rst b/docs/plat/meson-gxl.rst new file mode 100644 index 0000000..0751f1d --- /dev/null +++ b/docs/plat/meson-gxl.rst @@ -0,0 +1,27 @@ +Amlogic Meson S905x (GXL) +========================= + +The Amlogic Meson S905x is a SoC with a quad core Arm Cortex-A53 running at +1.5Ghz. It also contains a Cortex-M3 used as SCP. + +This port is a minimal implementation of BL31 capable of booting mainline U-Boot +and Linux: + +- SCPI support. +- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0 + can't be turned off, so there is a workaround to hide this from the caller. +- GICv2 driver set up. +- Basic SIP services (read efuse data, enable/disable JTAG). + +In order to build it: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxl + +This port has been tested on a Lepotato. After building it, follow the +instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the +mentioned **bl31.img** by the one built from this port. + +.. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/p212.rst diff --git a/docs/plat/mt8183.rst b/docs/plat/mt8183.rst new file mode 100644 index 0000000..c639be1 --- /dev/null +++ b/docs/plat/mt8183.rst @@ -0,0 +1,20 @@ +MediaTek 8183 +============= + +MediaTek 8183 (MT8183) is a 64-bit ARM SoC introduced by MediaTek in early 2018. +The chip incorporates eight cores - four Cortex-A53 little cores and Cortex-A73. +Both clusters can operate at up to 2 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8183 DEBUG=1 diff --git a/docs/plat/mt8186.rst b/docs/plat/mt8186.rst new file mode 100644 index 0000000..16b833a --- /dev/null +++ b/docs/plat/mt8186.rst @@ -0,0 +1,21 @@ +MediaTek 8186 +============= + +MediaTek 8186 (MT8186) is a 64-bit ARM SoC introduced by MediaTek in 2021. +The chip incorporates eight cores - six Cortex-A55 little cores and two Cortex-A76. +Cortex-A76 can operate at up to 2.05 GHz. +Cortex-A55 can operate at up to 2.0 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8186 DEBUG=1 COREBOOT=1 diff --git a/docs/plat/mt8188.rst b/docs/plat/mt8188.rst new file mode 100644 index 0000000..93abaa5 --- /dev/null +++ b/docs/plat/mt8188.rst @@ -0,0 +1,21 @@ +MediaTek 8188 +============= + +MediaTek 8188 (MT8188) is a 64-bit ARM SoC introduced by MediaTek in 2022. +The chip incorporates eight cores - six Cortex-A55 little cores and two Cortex-A78. +Cortex-A78 can operate at up to 2.6 GHz. +Cortex-A55 can operate at up to 2.0 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + + How to Build + ------------ + + .. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- LD=aarch64-linux-gnu-gcc PLAT=mt8188 DEBUG=1 COREBOOT=1 diff --git a/docs/plat/mt8192.rst b/docs/plat/mt8192.rst new file mode 100644 index 0000000..369afcf --- /dev/null +++ b/docs/plat/mt8192.rst @@ -0,0 +1,21 @@ +MediaTek 8192 +============= + +MediaTek 8192 (MT8192) is a 64-bit ARM SoC introduced by MediaTek in 2020. +The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76. +Cortex-A76 can operate at up to 2.2 GHz. +Cortex-A55 can operate at up to 2 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8192 DEBUG=1 COREBOOT=1 diff --git a/docs/plat/mt8195.rst b/docs/plat/mt8195.rst new file mode 100644 index 0000000..b2aeea2 --- /dev/null +++ b/docs/plat/mt8195.rst @@ -0,0 +1,21 @@ +MediaTek 8195 +============= + +MediaTek 8195 (MT8195) is a 64-bit ARM SoC introduced by MediaTek in 2021. +The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76. +Cortex-A76 can operate at up to 2.2 GHz. +Cortex-A55 can operate at up to 2.0 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8195 DEBUG=1 COREBOOT=1 diff --git a/docs/plat/npcm845x.rst b/docs/plat/npcm845x.rst new file mode 100644 index 0000000..91dbfd9 --- /dev/null +++ b/docs/plat/npcm845x.rst @@ -0,0 +1,21 @@ +Nuvoton NPCM845X +================ + +Nuvoton NPCM845X is the Nuvoton Arbel NPCM8XX Board Management controller (BMC) SoC. + +The Nuvoton Arbel NPCM845X SoC is a fourth-generation BMC. +The NPCM845X computing subsystem comprises a quadcore Arm Cortex-A35 CPU. + +This SoC includes secured components, i.e., bootblock stored in ROM, +u-boot, OPTEE-OS, trusted-firmware-a and Linux. +Every stage is measured and validated by the bootblock. +This SoC was tested on the Arbel NPCM845X evaluation board. + + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-none-elf- PLAT=npcm845x all SPD=opteed + diff --git a/docs/plat/nvidia-tegra.rst b/docs/plat/nvidia-tegra.rst new file mode 100644 index 0000000..391c7c8 --- /dev/null +++ b/docs/plat/nvidia-tegra.rst @@ -0,0 +1,148 @@ +NVIDIA Tegra +============ + +- .. rubric:: T194 + :name: t194 + +T194 has eight NVIDIA Carmel CPU cores in a coherent multi-processor +configuration. The Carmel cores support the ARM Architecture version 8.2, +executing both 64-bit AArch64 code, and 32-bit AArch32 code. The Carmel +processors are organized as four dual-core clusters, where each cluster has +a dedicated 2 MiB Level-2 unified cache. A high speed coherency fabric connects +these processor complexes and allows heterogeneous multi-processing with all +eight cores if required. + +- .. rubric:: T186 + :name: t186 + +The NVIDIA® Parker (T186) series system-on-chip (SoC) delivers a heterogeneous +multi-processing (HMP) solution designed to optimize performance and +efficiency. + +T186 has Dual NVIDIA Denver2 ARM® CPU cores, plus Quad ARM Cortex®-A57 cores, +in a coherent multiprocessor configuration. The Denver 2 and Cortex-A57 cores +support ARMv8, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code +including legacy ARMv7 applications. The Denver 2 processors each have 128 KB +Instruction and 64 KB Data Level 1 caches; and have a 2MB shared Level 2 +unified cache. The Cortex-A57 processors each have 48 KB Instruction and 32 KB +Data Level 1 caches; and also have a 2 MB shared Level 2 unified cache. A +high speed coherency fabric connects these two processor complexes and allows +heterogeneous multi-processing with all six cores if required. + +Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is +fully Armv8-A architecture compatible. Each of the two Denver cores +implements a 7-way superscalar microarchitecture (up to 7 concurrent +micro-ops can be executed per clock), and includes a 128KB 4-way L1 +instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2 +cache, which services both cores. + +Denver implements an innovative process called Dynamic Code Optimization, +which optimizes frequently used software routines at runtime into dense, +highly tuned microcode-equivalent routines. These are stored in a +dedicated, 128MB main-memory-based optimization cache. After being read +into the instruction cache, the optimized micro-ops are executed, +re-fetched and executed from the instruction cache as long as needed and +capacity allows. + +Effectively, this reduces the need to re-optimize the software routines. +Instead of using hardware to extract the instruction-level parallelism +(ILP) inherent in the code, Denver extracts the ILP once via software +techniques, and then executes those routines repeatedly, thus amortizing +the cost of ILP extraction over the many execution instances. + +Denver also features new low latency power-state transitions, in addition +to extensive power-gating and dynamic voltage and clock scaling based on +workloads. + +- .. rubric:: T210 + :name: t210 + +T210 has Quad Arm® Cortex®-A57 cores in a switched configuration with a +companion set of quad Arm Cortex-A53 cores. The Cortex-A57 and A53 cores +support Armv8-A, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code +including legacy Armv7-A applications. The Cortex-A57 processors each have +48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared +Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction +and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache. + +Directory structure +------------------- + +- plat/nvidia/tegra/common - Common code for all Tegra SoCs +- plat/nvidia/tegra/soc/txxx - Chip specific code + +Trusted OS dispatcher +--------------------- + +Tegra supports multiple Trusted OS'. + +- Trusted Little Kernel (TLK): In order to include the 'tlkd' dispatcher in + the image, pass 'SPD=tlkd' on the command line while preparing a bl31 image. +- Trusty: In order to include the 'trusty' dispatcher in the image, pass + 'SPD=trusty' on the command line while preparing a bl31 image. + +This allows other Trusted OS vendors to use the upstream code and include +their dispatchers in the image without changing any makefiles. + +These are the supported Trusted OS' by Tegra platforms. + +- Tegra210: TLK and Trusty +- Tegra186: Trusty +- Tegra194: Trusty + +Scatter files +------------- + +Tegra platforms currently support scatter files and ld.S scripts. The scatter +files help support ARMLINK linker to generate BL31 binaries. For now, there +exists a common scatter file, plat/nvidia/tegra/scat/bl31.scat, for all Tegra +SoCs. The `LINKER` build variable needs to point to the ARMLINK binary for +the scatter file to be used. Tegra platforms have verified BL31 image generation +with ARMCLANG (compilation) and ARMLINK (linking) for the Tegra186 platforms. + +Preparing the BL31 image to run on Tegra SoCs +--------------------------------------------- + +.. code:: shell + + CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \ + TARGET_SOC=<target-soc e.g. t194|t186|t210> SPD=<dispatcher e.g. trusty|tlkd> + bl31 + +Platforms wanting to use different TZDRAM\_BASE, can add ``TZDRAM_BASE=<value>`` +to the build command line. + +The Tegra platform code expects a pointer to the following platform specific +structure via 'x1' register from the BL2 layer which is used by the +bl31\_early\_platform\_setup() handler to extract the TZDRAM carveout base and +size for loading the Trusted OS and the UART port ID to be used. The Tegra +memory controller driver programs this base/size in order to restrict NS +accesses. + +typedef struct plat\_params\_from\_bl2 { +/\* TZ memory size */ +uint64\_t tzdram\_size; +/* TZ memory base */ +uint64\_t tzdram\_base; +/* UART port ID \*/ +int uart\_id; +/* L2 ECC parity protection disable flag \*/ +int l2\_ecc\_parity\_prot\_dis; +/* SHMEM base address for storing the boot logs \*/ +uint64\_t boot\_profiler\_shmem\_base; +} plat\_params\_from\_bl2\_t; + +Power Management +---------------- + +The PSCI implementation expects each platform to expose the 'power state' +parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field +is implementation defined on Tegra SoCs and is preferably defined by +tegra\_def.h. + +Tegra configs +------------- + +- 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity + Protection bit, for Arm Cortex-A57 CPUs, during CPU boot. This flag will + be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit. diff --git a/docs/plat/nxp/index.rst b/docs/plat/nxp/index.rst new file mode 100644 index 0000000..8546887 --- /dev/null +++ b/docs/plat/nxp/index.rst @@ -0,0 +1,17 @@ +NXP Reference Development Platforms +=================================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + nxp-layerscape + nxp-ls-fuse-prov + nxp-ls-tbbr + +This chapter holds documentation related to NXP reference development platforms. +It includes details on image flashing, fuse provisioning and trusted board boot-up. + +-------------- + +*Copyright (c) 2021, NXP Limited. All rights reserved.* diff --git a/docs/plat/nxp/nxp-layerscape.rst b/docs/plat/nxp/nxp-layerscape.rst new file mode 100644 index 0000000..cd5874b --- /dev/null +++ b/docs/plat/nxp/nxp-layerscape.rst @@ -0,0 +1,473 @@ +NXP SoCs - Overview +===================== +.. section-numbering:: + :suffix: . + +The QorIQ family of ARM based SoCs that are supported on TF-A are: + +1. LX2160A + +- SoC Overview: + +The LX2160A multicore processor, the highest-performance member of the +Layerscape family, combines FinFET process technology's low power and +sixteen Arm® Cortex®-A72 cores with datapath acceleration optimized for +L2/3 packet processing, together with security offload, robust traffic +management and quality of service. + +Details about LX2160A can be found at `lx2160a`_. + +- LX2160ARDB Board: + +The LX2160A reference design board provides a comprehensive platform +that enables design and evaluation of the LX2160A or LX2162A processors. It +comes preloaded with a board support package (BSP) based on a standard Linux +kernel. + +Board details can be fetched from the link: `lx2160ardb`_. + +2. LS1028A + +- SoC Overview: + +The Layerscape LS1028A applications processor for industrial and +automotive includes a time-sensitive networking (TSN) -enabled Ethernet +switch and Ethernet controllers to support converged IT and OT networks. +Two powerful 64-bit Arm®v8 cores support real-time processing for +industrial control and virtual machines for edge computing in the IoT. +The integrated GPU and LCD controller enable Human-Machine Interface +(HMI) systems with next-generation interfaces. + +Details about LS1028A can be found at `ls1028a`_. + +- LS1028ARDB Board: + +The LS1028A reference design board (RDB) is a computing, evaluation, +and development platform that supports industrial IoT applications, human +machine interface solutions, and industrial networking. + +Details about LS1028A RDB board can be found at `ls1028ardb`_. + +3. LS1043A + +- SoC Overview: + +The Layerscape LS1043A processor is NXP's first quad-core, 64-bit Arm®-based +processor for embedded networking. The LS1023A (two core version) and the +LS1043A (four core version) deliver greater than 10 Gbps of performance +in a flexible I/O package supporting fanless designs. This SoC is a +purpose-built solution for small-form-factor networking and industrial +applications with BOM optimizations for economic low layer PCB, lower cost +power supply and single clock design. The new 0.9V versions of the LS1043A +and LS1023A deliver addition power savings for applications such as Wireless +LAN and to Power over Ethernet systems. + +Details about LS1043A can be found at `ls1043a`_. + +- LS1043ARDB Board: + +The LS1043A reference design board (RDB) is a computing, evaluation, and +development platform that supports the Layerscape LS1043A architecture +processor. The LS1043A-RDB can help shorten your time to market by providing +the following features: + +Memory subsystem: + * 2GByte DDR4 SDRAM (32bit bus) + * 128 Mbyte NOR flash single-chip memory + * 512 Mbyte NAND flash + * 16 Mbyte high-speed SPI flash + * SD connector to interface with the SD memory card + +Ethernet: + * XFI 10G port + * QSGMII with 4x 1G ports + * Two RGMII ports + +PCIe: + * PCIe2 (Lanes C) to mini-PCIe slot + * PCIe3 (Lanes D) to PCIe slot + +USB 3.0: two super speed USB 3.0 type A ports + +UART: supports two UARTs up to 115200 bps for console + +Details about LS1043A RDB board can be found at `ls1043ardb`_. + +4. LS1046A + +- SoC Overview: + +The LS1046A is a cost-effective, power-efficient, and highly integrated +system-on-chip (SoC) design that extends the reach of the NXP value-performance +line of QorIQ communications processors. Featuring power-efficient 64-bit +Arm Cortex-A72 cores with ECC-protected L1 and L2 cache memories for high +reliability, running up to 1.8 GHz. + +Details about LS1046A can be found at `ls1046a`_. + +- LS1046ARDB Board: + +The LS1046A reference design board (RDB) is a high-performance computing, +evaluation, and development platform that supports the Layerscape LS1046A +architecture processor. The LS1046ARDB board supports the Layerscape LS1046A +processor and is optimized to support the DDR4 memory and a full complement +of high-speed SerDes ports. + +Details about LS1046A RDB board can be found at `ls1046ardb`_. + +- LS1046AFRWY Board: + +The LS1046A Freeway board (FRWY) is a high-performance computing, evaluation, +and development platform that supports the LS1046A architecture processor +capable of support more than 32,000 CoreMark performance. The FRWY-LS1046A +board supports the LS1046A processor, onboard DDR4 memory, multiple Gigabit +Ethernet, USB3.0 and M2_Type_E interfaces for Wi-Fi, FRWY-LS1046A-AC includes +the Wi-Fi card. + +Details about LS1046A FRWY board can be found at `ls1046afrwy`_. + +5. LS1088A + +- SoC Overview: + +The LS1088A family of multicore communications processors combines up to and eight +Arm Cortex-A53 cores with the advanced, high-performance data path and network +peripheral interfaces required for wireless access points, networking infrastructure, +intelligent edge access, including virtual customer premise equipment (vCPE) and +high-performance industrial applications. + +Details about LS1088A can be found at `ls1088a`_. + +- LS1088ARDB Board: + +The LS1088A reference design board provides a comprehensive platform that +enables design and evaluation of the product (LS1088A processor). This RDB +comes pre-loaded with a board support package (BSP) based on a standard +Linux kernel. + +Details about LS1088A RDB board can be found at `ls1088ardb`_. + +Table of supported boot-modes by each platform & platform that needs FIP-DDR: +----------------------------------------------------------------------------- + ++---------------------+---------------------------------------------------------------------+-----------------+ +| | BOOT_MODE | | +| PLAT +-------+--------+-------+-------+-------+-------------+--------------+ fip_ddr_needed | +| | sd | qspi | nor | nand | emmc | flexspi_nor | flexspi_nand | | ++=====================+=======+========+=======+=======+=======+=============+==============+=================+ +| lx2160ardb | yes | | | | yes | yes | | yes | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ +| ls1028ardb | yes | | | | yes | yes | | no | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ +| ls1043ardb | yes | | yes | yes | | | | no | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ +| ls1046ardb | yes | yes | | | yes | | | no | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ +| ls1046afrwy | yes | yes | | | | | | no | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ +| ls1088ardb | yes | yes | | | | | | no | ++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+ + + +Boot Sequence +------------- +:: + ++ Secure World | Normal World ++ EL0 | ++ | ++ EL1 BL32(Tee OS) | kernel ++ ^ | | ^ ++ | | | | ++ EL2 | | | BL33(u-boot) ++ | | | ^ ++ | v | / ++ EL3 BootROM --> BL2 --> BL31 ---------------/ ++ + +Boot Sequence with FIP-DDR +-------------------------- +:: + ++ Secure World | Normal World ++ EL0 | ++ | ++ EL1 fip-ddr BL32(Tee OS) | kernel ++ ^ | ^ | | ^ ++ | | | | | | ++ EL2 | | | | | BL33(u-boot) ++ | | | | | ^ ++ | v | v | / ++ EL3 BootROM --> BL2 -----> BL31 ---------------/ ++ + +DDR Memory Layout +-------------------------- + +NXP Platforms divide DRAM into banks: + +- DRAM0 Bank: Maximum size of this bank is fixed to 2GB, DRAM0 size is defined in platform_def.h if it is less than 2GB. + +- DRAM1 ~ DRAMn Bank: Greater than 2GB belongs to DRAM1 and following banks, and size of DRAMn Bank varies for one platform to others. + +The following diagram is default DRAM0 memory layout in which secure memory is at top of DRAM0. + +:: + + high +---------------------------------------------+ + | | + | Secure EL1 Payload Shared Memory (2 MB) | + | | + +---------------------------------------------+ + | | + | Secure Memory (64 MB) | + | | + +---------------------------------------------+ + | | + | Non Secure Memory | + | | + low +---------------------------------------------+ + +How to build +============= + +Code Locations +-------------- + +- OP-TEE: + `link <https://source.codeaurora.org/external/qoriq/qoriq-components/optee_os>`__ + +- U-Boot: + `link <https://source.codeaurora.org/external/qoriq/qoriq-components/u-boot>`__ + +- RCW: + `link <https://source.codeaurora.org/external/qoriq/qoriq-components/rcw>`__ + +- ddr-phy-binary: Required by platforms that need fip-ddr. + `link <https:://github.com/NXP/ddr-phy-binary>`__ + +- cst: Required for TBBR. + `link <https:://source.codeaurora.org/external/qoriq/qoriq-components/cst>`__ + +Build Procedure +--------------- + +- Fetch all the above repositories into local host. + +- Prepare AARCH64 toolchain and set the environment variable "CROSS_COMPILE". + + .. code:: shell + + export CROSS_COMPILE=.../bin/aarch64-linux-gnu- + +- Build RCW. Refer README from the respective cloned folder for more details. + +- Build u-boot and OPTee firstly, and get binary images: u-boot.bin and tee.bin. + For u-boot you can use the <platform>_tfa_defconfig for build. + +- Copy/clone the repo "ddr-phy-binary" to the tfa directory for platform needing ddr-fip. + +- Below are the steps to build TF-A images for the supported platforms. + +Compilation steps without BL32 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BUILD BL2: + +-To compile + .. code:: shell + + make PLAT=$PLAT \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + pbl + +BUILD FIP: + + .. code:: shell + + make PLAT=$PLAT \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL33=$UBOOT_SECURE_BIN \ + pbl \ + fip + +Compilation steps with BL32 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BUILD BL2: + +-To compile + .. code:: shell + + make PLAT=$PLAT \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + pbl + +BUILD FIP: + + .. code:: shell + + make PLAT=$PLAT \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + BL33=$UBOOT_SECURE_BIN \ + pbl \ + fip + + +BUILD fip-ddr (Mandatory for certain platforms, refer table above): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +-To compile additional fip-ddr for selected platforms(Refer above table if the platform needs fip-ddr). + .. code:: shell + + make PLAT=<platform_name> fip-ddr + + +Deploy ATF Images +================= + +Note: The size in the standard uboot commands for copy to nor, qspi, nand or sd +should be modified based on the binary size of the image to be copied. + +- Deploy ATF images on flexspi-Nor or QSPI flash Alt Bank from U-Boot prompt. + + -- Commands to flash images for bl2_xxx.pbl and fip.bin + + Notes: ls1028ardb has no flexspi-Nor Alt Bank, so use "sf probe 0:0" for current bank. + + .. code:: shell + + tftp 82000000 $path/bl2_xxx.pbl; + + i2c mw 66 50 20;sf probe 0:1; sf erase 0 +$filesize; sf write 0x82000000 0x0 $filesize; + + tftp 82000000 $path/fip.bin; + i2c mw 66 50 20;sf probe 0:1; sf erase 0x100000 +$filesize; sf write 0x82000000 0x100000 $filesize; + + -- Next step is valid for platform where FIP-DDR is needed. + + .. code:: shell + + tftp 82000000 $path/ddr_fip.bin; + i2c mw 66 50 20;sf probe 0:1; sf erase 0x800000 +$filesize; sf write 0x82000000 0x800000 $filesize; + + -- Then reset to alternate bank to boot up ATF. + + Command for lx2160a, ls1088a and ls1028a platforms: + + .. code:: shell + + qixisreset altbank; + + Command for ls1046a platforms: + + .. code:: shell + + cpld reset altbank; + +- Deploy ATF images on SD/eMMC from U-Boot prompt. + -- file_size_in_block_sizeof_512 = (Size_of_bytes_tftp / 512) + + .. code:: shell + + mmc dev <idx>; (idx = 1 for eMMC; idx = 0 for SD) + + tftp 82000000 $path/bl2_<sd>_or_<emmc>.pbl; + mmc write 82000000 8 <file_size_in_block_sizeof_512>; + + tftp 82000000 $path/fip.bin; + mmc write 82000000 0x800 <file_size_in_block_sizeof_512>; + + -- Next step is valid for platform that needs FIP-DDR. + + .. code:: shell + + tftp 82000000 $path/ddr_fip.bin; + mmc write 82000000 0x4000 <file_size_in_block_sizeof_512>; + + -- Then reset to sd/emmc to boot up ATF from sd/emmc as boot-source. + + Command for lx2160A, ls1088a and ls1028a platforms: + + .. code:: shell + + qixisreset <sd or emmc>; + + Command for ls1043a and ls1046a platform: + + .. code:: shell + + cpld reset <sd or emmc>; + +- Deploy ATF images on IFC nor flash from U-Boot prompt. + + .. code:: shell + + tftp 82000000 $path/bl2_nor.pbl; + protect off 64000000 +$filesize; erase 64000000 +$filesize; cp.b 82000000 64000000 $filesize; + + tftp 82000000 $path/fip.bin; + protect off 64100000 +$filesize; erase 64100000 +$filesize; cp.b 82000000 64100000 $filesize; + + -- Then reset to alternate bank to boot up ATF. + + Command for ls1043a platform: + + .. code:: shell + + cpld reset altbank; + +- Deploy ATF images on IFC nand flash from U-Boot prompt. + + .. code:: shell + + tftp 82000000 $path/bl2_nand.pbl; + nand erase 0x0 $filesize; nand write 82000000 0x0 $filesize; + + tftp 82000000 $path/fip.bin; + nand erase 0x100000 $filesize;nand write 82000000 0x100000 $filesize; + + -- Then reset to nand flash to boot up ATF. + + Command for ls1043a platform: + + .. code:: shell + + cpld reset nand; + + + +Trusted Board Boot: +=================== + +For TBBR, the binary name changes: + ++-------------+--------------------------+---------+-------------------+ +| Boot Type | BL2 | FIP | FIP-DDR | ++=============+==========================+=========+===================+ +| Normal Boot | bl2_<boot_mode>.pbl | fip.bin | ddr_fip.bin | ++-------------+--------------------------+---------+-------------------+ +| TBBR Boot | bl2_<boot_mode>_sec.pbl | fip.bin | ddr_fip_sec.bin | ++-------------+--------------------------+---------+-------------------+ + +Refer `nxp-ls-tbbr.rst`_ for detailed user steps. + + +.. _lx2160a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-lx2160a-lx2120a-lx2080a-processors:LX2160A +.. _lx2160ardb: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-communication-process/layerscape-lx2160a-multicore-communications-processor:LX2160A +.. _ls1028a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1028a-applications-processor:LS1028A +.. _ls1028ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1028a-reference-design-board:LS1028ARDB +.. _ls1043a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1043a-and-1023a-processors:LS1043A +.. _ls1043ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1043a-reference-design-board:LS1043A-RDB +.. _ls1046a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1046a-and-1026a-processors:LS1046A +.. _ls1046ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1046a-reference-design-board:LS1046A-RDB +.. _ls1046afrwy: https://www.nxp.com/design/qoriq-developer-resources/ls1046a-freeway-board:FRWY-LS1046A +.. _ls1088a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1088a-and-1048a-processor:LS1088A +.. _ls1088ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1088a-reference-design-board:LS1088A-RDB +.. _nxp-ls-tbbr.rst: ./nxp-ls-tbbr.rst diff --git a/docs/plat/nxp/nxp-ls-fuse-prov.rst b/docs/plat/nxp/nxp-ls-fuse-prov.rst new file mode 100644 index 0000000..64e1c6f --- /dev/null +++ b/docs/plat/nxp/nxp-ls-fuse-prov.rst @@ -0,0 +1,271 @@ + +Steps to blow fuses on NXP LS SoC: +================================== + + +- Enable POVDD + -- Refer board GSG(Getting Started Guide) for the steps to enable POVDD. + -- Once the POVDD is enabled, make sure to set variable POVDD_ENABLE := yes, in the platform.mk. + ++---+-----------------+-----------+------------+-----------------+-----------------------------+ +| | Platform | Jumper | Switch | LED to Verify | Through GPIO Pin (=number) | ++===+=================+===========+============+=================+=============================+ +| 1.| lx2160ardb | J9 | | | no | ++---+-----------------+-----------+------------+-----------------+-----------------------------+ +| 2.| lx2160aqds | J35 | | | no | ++---+-----------------+-----------+------------+-----------------+-----------------------------+ +| 3.| lx2162aqds | J35 | SW9[4] = 1 | D15 | no | ++---+-----------------+-----------+------------+-----------------+-----------------------------+ + +- SFP registers to be written to: + ++---+----------------------------------+----------------------+----------------------+ +| | Platform | OTPMKR0..OTPMKR7 | SRKHR0..SRKHR7 | ++===+==================================+======================+======================+ +| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 0x1e80234..0x1e80250 | 0x1e80254..0x1e80270 | ++---+----------------------------------+----------------------+----------------------+ + +- At U-Boot prompt, verify that SNVS register - HPSR, whether OTPMK was written, already: + ++---+----------------------------------+-------------------------------------------+---------------+ +| | Platform | OTPMK_ZERO_BIT(=value) | SNVS_HPSR_REG | ++===+==================================+===========================================+===============+ +| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 27 (= 1 means not blown, =0 means blown) | 0x01E90014 | ++---+----------------------------------+-------------------------------------------+---------------+ + +From u-boot prompt: + + -- Check for the OTPMK. + .. code:: shell + + md $SNVS_HPSR_REG + + Command Output: + 01e90014: 88000900 + + In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap). + +0 +4 +8 +C + [0x01E90014] 88000900 + + Note: OTPMK_ZERO_BIT is 1, indicating that the OTPMK is not blown. + + -- Check for the SRK Hash. + .. code:: shell + + md $SRKHR0 0x10 + + Command Output: + 01e80254: 00000000 00000000 00000000 00000000 ................ + 01e80264: 00000000 00000000 00000000 00000000 ................ + + Note: Zero means that SRK hash is not blown. + +- If not blown, then from the U-Boot prompt, using following commands: + -- Provision the OTPMK. + + .. code:: shell + + mw.l $OTPMKR0 <OTMPKR_0_32Bit_val> + mw.l $OTPMKR1 <OTMPKR_1_32Bit_val> + mw.l $OTPMKR2 <OTMPKR_2_32Bit_val> + mw.l $OTPMKR3 <OTMPKR_3_32Bit_val> + mw.l $OTPMKR4 <OTMPKR_4_32Bit_val> + mw.l $OTPMKR5 <OTMPKR_5_32Bit_val> + mw.l $OTPMKR6 <OTMPKR_6_32Bit_val> + mw.l $OTPMKR7 <OTMPKR_7_32Bit_val> + + -- Provision the SRK Hash. + + .. code:: shell + + mw.l $SRKHR0 <SRKHR_0_32Bit_val> + mw.l $SRKHR1 <SRKHR_1_32Bit_val> + mw.l $SRKHR2 <SRKHR_2_32Bit_val> + mw.l $SRKHR3 <SRKHR_3_32Bit_val> + mw.l $SRKHR4 <SRKHR_4_32Bit_val> + mw.l $SRKHR5 <SRKHR_5_32Bit_val> + mw.l $SRKHR6 <SRKHR_6_32Bit_val> + mw.l $SRKHR7 <SRKHR_7_32Bit_val> + + Note: SRK Hash should be carefully written keeping in mind the SFP Block Endianness. + +- At U-Boot prompt, verify that SNVS registers for OTPMK are correctly written: + + -- Check for the OTPMK. + .. code:: shell + + md $SNVS_HPSR_REG + + Command Output: + 01e90014: 80000900 + + OTPMK_ZERO_BIT is zero, indicating that the OTPMK is blown. + + Note: In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap). + + .. code:: shell + + md $OTPMKR0 0x10 + + Command Output: + 01e80234: ffffffff ffffffff ffffffff ffffffff ................ + 01e80244: ffffffff ffffffff ffffffff ffffffff ................ + + Note: OTPMK will never be visible in plain. + + -- Check for the SRK Hash. For example, if following SRK hash is written: + + SFP SRKHR0 = fdc2fed4 + SFP SRKHR1 = 317f569e + SFP SRKHR2 = 1828425c + SFP SRKHR3 = e87b5cfd + SFP SRKHR4 = 34beab8f + SFP SRKHR5 = df792a70 + SFP SRKHR6 = 2dff85e1 + SFP SRKHR7 = 32a29687, + + then following would be the value on dumping SRK hash. + + .. code:: shell + + md $SRKHR0 0x10 + + Command Output: + 01e80254: d4fec2fd 9e567f31 5c422818 fd5c7be8 ....1.V..(B\.{\. + 01e80264: 8fabbe34 702a79df e185ff2d 8796a232 4....y*p-...2... + + Note: SRK Hash is visible in plain based on the SFP Block Endianness. + +- Caution: Donot proceed to the next step, until you are sure that OTPMK and SRKH are correctly blown from above steps. + -- After the next step, there is no turning back. + -- Fuses will be burnt, which cannot be undo. + +- Write SFP_INGR[INST] with the PROGFB(0x2) instruction to blow the fuses. + -- User need to save the SRK key pair and OTPMK Key forever, to continue using this board. + ++---+----------------------------------+-------------------------------------------+-----------+ +| | Platform | SFP_INGR_REG | SFP_WRITE_DATE_FRM_MIRROR_REG_TO_FUSE | ++===+==================================+=======================================================+ +| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 0x01E80020 | 0x2 | ++---+----------------------------------+--------------+----------------------------------------+ + + .. code:: shell + + md $SFP_INGR_REG $SFP_WRITE_DATE_FRM_MIRROR_REG_TO_FUSE + +- On reset, if the SFP register were read from u-boot, it will show the following: + -- Check for the OTPMK. + + .. code:: shell + + md $SNVS_HPSR_REG + + Command Output: + 01e90014: 80000900 + + In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap). + +0 +4 +8 +C + [0x01E90014] 80000900 + + Note: OTPMK_ZERO_BIT is zero, indicating that the OTPMK is blown. + + .. code:: shell + + md $OTPMKR0 0x10 + + Command Output: + 01e80234: ffffffff ffffffff ffffffff ffffffff ................ + 01e80244: ffffffff ffffffff ffffffff ffffffff ................ + + Note: OTPMK will never be visible in plain. + + -- SRK Hash + + .. code:: shell + + md $SRKHR0 0x10 + + Command Output: + 01e80254: d4fec2fd 9e567f31 5c422818 fd5c7be8 ....1.V..(B\.{\. + 01e80264: 8fabbe34 702a79df e185ff2d 8796a232 4....y*p-...2... + + Note: SRK Hash is visible in plain based on the SFP Block Endianness. + +Second method to do the fuse provsioning: +========================================= + +This method is used for quick way to provision fuses. +Typically used by those who needs to provision number of boards. + +- Enable POVDD: + -- Refer the table above to enable POVDD. + + Note: If GPIO Pin supports enabling POVDD, it can be done through the below input_fuse_file. + + -- Once the POVDD is enabled, make sure to set variable POVDD_ENABLE := yes, in the platform.mk. + +- User need to populate the "input_fuse_file", corresponding to the platform for: + + -- OTPMK + -- SRKH + + Table of fuse provisioning input file for every supported platform: + ++---+----------------------------------+-----------------------------------------------------------------+ +| | Platform | FUSE_PROV_FILE | ++===+==================================+=================================================================+ +| 1.| lx2160ardb/lx2160aqds/lx2162aqds | ${CST_DIR}/input_files/gen_fusescr/ls2088_1088/input_fuse_file | ++---+----------------------------------+--------------+--------------------------------------------------+ + +- Create the TF-A binary with FUSE_PROG=1. + + .. code:: shell + + make PLAT=$PLAT FUSE_PROG=1\ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + BL33=$UBOOT_SECURE_BIN \ + pbl \ + fip \ + fip_fuse \ + FUSE_PROV_FILE=../../apps/security/cst/input_files/gen_fusescr/ls2088_1088/input_fuse_file + +- Deployment: + -- Refer the nxp-layerscape.rst for deploying TF-A images. + -- Deploying fip_fuse.bin: + + For Flexspi-Nor: + + .. code:: shell + + tftp 82000000 $path/fuse_fip.bin; + i2c mw 66 50 20;sf probe 0:0; sf erase 0x880000 +$filesize; sf write 0x82000000 0x880000 $filesize; + + For SD or eMMC [file_size_in_block_sizeof_512 = (Size_of_bytes_tftp / 512)]: + + .. code:: shell + + tftp 82000000 $path/fuse_fip.bin; + mmc write 82000000 0x4408 <file_size_in_block_sizeof_512>; + +- Valiation: + ++---+----------------------------------+---------------------------------------------------+ +| | Platform | Error_Register | Error_Register_Address | ++===+==================================+===================================================+ +| 1.| lx2160ardb/lx2160aqds/lx2162aqds | DCFG scratch 4 register | 0x01EE020C | ++---+----------------------------------+---------------------------------------------------+ + + At the U-Boot prompt, check DCFG scratch 4 register for any error. + + .. code:: shell + + md $Error_Register_Address 1 + + Command Ouput: + 01ee020c: 00000000 + + Note: + - 0x00000000 shows no error, then fuse provisioning is successful. + - For non-zero value, refer the code header file ".../drivers/nxp/sfp/sfp_error_codes.h" diff --git a/docs/plat/nxp/nxp-ls-tbbr.rst b/docs/plat/nxp/nxp-ls-tbbr.rst new file mode 100644 index 0000000..43e15f7 --- /dev/null +++ b/docs/plat/nxp/nxp-ls-tbbr.rst @@ -0,0 +1,210 @@ + +-------------- +NXP Platforms: +-------------- +TRUSTED_BOARD_BOOT option can be enabled by specifying TRUSTED_BOARD_BOOT=1 on command line during make. + + + +Bare-Minimum Preparation to run TBBR on NXP Platforms: +======================================================= +- OTPMK(One Time Programable Key) needs to be burnt in fuses. + -- It is the 256 bit key that stores a secret value used by the NXP SEC 4.0 IP in Trusted or Secure mode. + + Note: It is primarily for the purpose of decrypting additional secrets stored in system non-volatile memory. + + -- NXP CST tool gives an option to generate it. + + Use the below command from directory 'cst', with correct options. + + .. code:: shell + + ./gen_otpmk_drbg + +- SRKH (Super Root Key Hash) needs to be burnt in fuses. + -- It is the 256 bit hash of the list of the public keys of the SRK key pair. + -- NXP CST tool gives an option to generate the RSA key pair and its hash. + + Use the below command from directory 'cst', with correct options. + + .. code:: shell + + ./gen_keys + +Refer fuse frovisioning readme 'nxp-ls-fuse-prov.rst' for steps to blow these keys. + + + +Two options are provided for TRUSTED_BOARD_BOOT: +================================================ + +------------------------------------------------------------------------- +Option 1: CoT using X 509 certificates +------------------------------------------------------------------------- + +- This CoT is as provided by ARM. + +- To use this option user needs to specify mbedtld dir path in MBEDTLS_DIR. + +- To generate CSF header, path of CST repository needs to be specified as CST_DIR + +- CSF header is embedded to each of the BL2 image. + +- GENERATE_COT=1 adds the tool 'cert_create' to the build environment to generate: + -- X509 Certificates as (.crt) files. + -- X509 Pem key file as (.pem) files. + +- SAVE_KEYS=1 saves the keys and certificates, if GENERATE_COT=1. + -- For this to work, file name for cert and keys are provided as part of compilation or build command. + + --- default file names will be used, incase not provided as part compilation or build command. + --- default folder 'BUILD_PLAT' will be used to store them. + +- ROTPK for x.509 certificates is generated and embedded in bl2.bin and + verified as part of CoT by Boot ROM during secure boot. + +- Compilation steps: + +All Images + .. code:: shell + + make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=$MBEDTLS_PATH CST_DIR=$CST_DIR_PATH \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + BL33=$UBOOT_SECURE_BIN \ + pbl \ + fip + +Additional FIP_DDR Image (For NXP platforms like lx2160a) + .. code:: shell + + make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=$MBEDTLS_PATH fip_ddr + + Note: make target 'fip_ddr' should never be combine with other make target 'fip', 'pbl' & 'bl2'. + +------------------------------------------------------------------------- +Option 2: CoT using NXP CSF headers. +------------------------------------------------------------------------- + +- This option is automatically selected when TRUSTED_BOARD_BOOT is set but MBEDTLS_DIR path is not specified. + +- CSF header is embedded to each of the BL31, BL32 and BL33 image. + +- To generate CSF header, path of CST repository needs to be specified as CST_DIR + +- Default input files for CSF header generation is added in this repo. + +- Default input file requires user to generate RSA key pair named + -- srk.pri, and + -- srk.pub, and add them in ATF repo. + -- These keys can be generated using gen_keys tool of CST. + +- To change the input file , user can use the options BL33_INPUT_FILE, BL32_INPUT_FILE, BL31_INPUT_FILE + +- There are 2 paths in secure boot flow : + -- Development Mode (sb_en in RCW = 1, SFP->OSPR, ITS = 0) + + --- In this flow , even on ROTPK comparison failure, flow would continue. + --- However SNVS is transitioned to non-secure state + + -- Production mode (SFP->OSPR, ITS = 1) + + --- Any failure is fatal failure + +- Compilation steps: + +All Images + .. code:: shell + + make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + BL33=$UBOOT_SECURE_BIN \ + pbl \ + fip + +Additional FIP_DDR Image (For NXP platforms like lx2160a) + .. code:: shell + + make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH fip_ddr + +- Compilation Steps with build option for generic image processing filters to prepend CSF header: + -- Generic image processing filters to prepend CSF header + + BL32_INPUT_FILE = < file name> + BL33_INPUT_FILE = <file name> + + .. code:: shell + + make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH \ + BOOT_MODE=<platform_supported_boot_mode> \ + RCW=$RCW_BIN \ + BL32=$TEE_BIN SPD=opteed\ + BL33=$UBOOT_SECURE_BIN \ + BL33_INPUT_FILE = <ip file> \ + BL32_INPUT_FILE = <ip_file> \ + BL31_INPUT_FILE = <ip file> \ + pbl \ + fip + + +Deploy ATF Images +================= +Same steps as mentioned in the readme "nxp-layerscape.rst". + + + +Verification to check if Secure state is achieved: +================================================== + ++---+----------------+-----------------+------------------------+----------------------------------+-------------------------------+ +| | Platform | SNVS_HPSR_REG | SYS_SECURE_BIT(=value) | SYSTEM_SECURE_CONFIG_BIT(=value) | SSM_STATE | ++===+================+=================+========================+==================================+===============================+ +| 1.| lx2160ardb or | 0x01E90014 | 15 | 14-12 | 11-8 | +| | lx2160aqds or | | ( = 1, BootROM Booted) | ( = 010 means Intent to Secure, | (=1111 means secure boot) | +| | lx2162aqds | | | ( = 000 Unsecure) | (=1011 means Non-secure Boot) | ++---+----------------+-----------------+------------------------+----------------------------------+-------------------------------+ + +- Production mode (SFP->OSPR, ITS = 1) + -- Linux prompt will successfully come. if the TBBR is successful. + + --- Else, Linux boot will be successful. + + -- For secure-boot status, read SNVS Register $SNVS_HPSR_REG from u-boot prompt: + + .. code:: shell + + md $SNVS_HPSR_REG + + Command Output: + 1e90014: 8000AF00 + + In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap). + +0 +4 +8 +C + [0x01E90014] 8000AF00 + + +- Development Mode (sb_en in RCW = 1, SFP->OSPR, ITS = 0) + -- Refer the SoC specific table to read the register to interpret whether the secure boot is achieved or not. + -- Using JTAG (in development environment only, using CW tap): + + --- For secure-boot status, read SNVS Register $SNVS_HPSR_REG + + .. code:: shell + + ccs::display_regs 86 0x01E90014 4 0 1 + + Command Output: + Using the SAP chain position number 86, following is the output. + + +0 +4 +8 +C + [0x01E90014] 8000AF00 + + Note: Chain position number will vary from one SoC to other SoC. + +- Interpretation of the value: + + -- 0xA indicates BootROM booted, with intent to secure. + -- 0xF = secure boot, as SSM_STATE. diff --git a/docs/plat/poplar.rst b/docs/plat/poplar.rst new file mode 100644 index 0000000..215f551 --- /dev/null +++ b/docs/plat/poplar.rst @@ -0,0 +1,176 @@ +Poplar +====== + +Poplar is the first development board compliant with the 96Boards Enterprise +Edition TV Platform specification. + +The board features the Hi3798C V200 with an integrated quad-core 64-bit +Arm Cortex A53 processor and high performance Mali T720 GPU, making it capable +of running any commercial set-top solution based on Linux or Android. + +It supports a premium user experience with up to H.265 HEVC decoding of 4K +video at 60 frames per second. + +:: + + SOC Hisilicon Hi3798CV200 + CPU Quad-core Arm Cortex-A53 64 bit + DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB + USB Two USB 2.0 ports One USB 3.0 ports + CONSOLE USB-micro port for console support + ETHERNET 1 GBe Ethernet + PCIE One PCIe 2.0 interfaces + JTAG 8-Pin JTAG + EXPANSION INTERFACE Linaro 96Boards Low Speed Expansion slot + DIMENSION Standard 160×120 mm 96Boards Enterprice Edition form factor + WIFI 802.11AC 2*2 with Bluetooth + CONNECTORS One connector for Smart Card One connector for TSI + +At the start of the boot sequence, the bootROM executes the so called l-loader +binary whose main role is to change the processor state to 64bit mode. This +must happen prior to invoking Trusted Firmware-A: + +:: + + l-loader --> Trusted Firmware-A --> u-boot + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- l-loader: + `link <https://github.com/Linaro/poplar-l-loader.git>`__ + +- u-boot: + `link <http://git.denx.de/u-boot.git>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Fetch all the above 3 repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + +- Prepare the AARCH64 toolchain. + +- Build u-boot using poplar_defconfig + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- poplar_defconfig + make CROSS_COMPILE=aarch64-linux-gnu- + +- Build atf providing the previously generated u-boot.bin as the BL33 image + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- all fip SPD=none PLAT=poplar + BL33=u-boot.bin + +- Build l-loader (generated the final fastboot.bin) + 1. copy the atf generated files fip.bin and bl1.bin to l-loader/atf/ + 2. export ARM_TRUSTED_FIRMWARE=${ATF_SOURCE_PATH) + 3. make + +Install Procedure +----------------- + +- Copy l-loader/fastboot.bin to a FAT partition on a USB pen drive. + +- Plug the USB pen drive to any of the USB2 ports + +- Power the board while keeping S3 pressed (usb_boot) + +The system will boot into a u-boot shell which you can then use to write the +working firmware to eMMC. + +Boot trace +---------- + +:: + + Bootrom start + Boot Media: eMMC + Decrypt auxiliary code ...OK + + lsadc voltage min: 000000FE, max: 000000FF, aver: 000000FE, index: 00000000 + + Entry boot auxiliary code + + Auxiliary code - v1.00 + DDR code - V1.1.2 20160205 + Build: Mar 24 2016 - 17:09:44 + Reg Version: v134 + Reg Time: 2016/03/18 09:44:55 + Reg Name: hi3798cv2dmb_hi3798cv200_ddr3_2gbyte_8bitx4_4layers.reg + + Boot auxiliary code success + Bootrom success + + LOADER: Switched to aarch64 mode + LOADER: Entering ARM TRUSTED FIRMWARE + LOADER: CPU0 executes at 0x000ce000 + + INFO: BL1: 0xe1000 - 0xe7000 [size = 24576] + NOTICE: Booting Trusted Firmware + NOTICE: BL1: v1.3(debug):v1.3-372-g1ba9c60 + NOTICE: BL1: Built : 17:51:33, Apr 30 2017 + INFO: BL1: RAM 0xe1000 - 0xe7000 + INFO: BL1: Loading BL2 + INFO: Loading image id=1 at address 0xe9000 + INFO: Image id=1 loaded at address 0xe9000, size = 0x5008 + NOTICE: BL1: Booting BL2 + INFO: Entry point address = 0xe9000 + INFO: SPSR = 0x3c5 + NOTICE: BL2: v1.3(debug):v1.3-372-g1ba9c60 + NOTICE: BL2: Built : 17:51:33, Apr 30 2017 + INFO: BL2: Loading BL31 + INFO: Loading image id=3 at address 0x129000 + INFO: Image id=3 loaded at address 0x129000, size = 0x8038 + INFO: BL2: Loading BL33 + INFO: Loading image id=5 at address 0x37000000 + INFO: Image id=5 loaded at address 0x37000000, size = 0x58f17 + NOTICE: BL1: Booting BL31 + INFO: Entry point address = 0x129000 + INFO: SPSR = 0x3cd + INFO: Boot bl33 from 0x37000000 for 364311 Bytes + NOTICE: BL31: v1.3(debug):v1.3-372-g1ba9c60 + NOTICE: BL31: Built : 17:51:33, Apr 30 2017 + INFO: BL31: Initializing runtime services + INFO: BL31: Preparing for EL3 exit to normal world + INFO: Entry point address = 0x37000000 + INFO: SPSR = 0x3c9 + + + U-Boot 2017.05-rc2-00130-gd2255b0 (Apr 30 2017 - 17:51:28 +0200)poplar + + Model: HiSilicon Poplar Development Board + BOARD: Hisilicon HI3798cv200 Poplar + DRAM: 1 GiB + MMC: Hisilicon DWMMC: 0 + In: serial@f8b00000 + Out: serial@f8b00000 + Err: serial@f8b00000 + Net: Net Initialization Skipped + No ethernet found. + + Hit any key to stop autoboot: 0 + starting USB... + USB0: USB EHCI 1.00 + scanning bus 0 for devices... 1 USB Device(s) found + USB1: USB EHCI 1.00 + scanning bus 1 for devices... 4 USB Device(s) found + scanning usb for storage devices... 1 Storage Device(s) found + scanning usb for ethernet devices... 1 Ethernet Device(s) found + + USB device 0: + Device 0: Vendor: SanDisk Rev: 1.00 Prod: Cruzer Blade + Type: Removable Hard Disk + Capacity: 7632.0 MB = 7.4 GB (15630336 x 512) + ... is now current device + Scanning usb 0:1... + => diff --git a/docs/plat/qemu-sbsa.rst b/docs/plat/qemu-sbsa.rst new file mode 100644 index 0000000..bc82ae5 --- /dev/null +++ b/docs/plat/qemu-sbsa.rst @@ -0,0 +1,56 @@ +QEMU SBSA Target +================ + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU SBSA +Armv8-A. While running Qemu from command line, we need to supply two Flash +images. First Secure BootRom is supplied by -pflash argument. This Flash image +is made by EDK2 build system by composing BL1 and FIP. Second parameter for Qemu +is responsible for Non-secure rom which also given with -pflash argument and +contains of UEFI and EFI variables (also made by EDK2 build system). Semihosting +is not used + +When QEMU starts all CPUs are released simultaneously, BL1 selects a +primary CPU to handle the boot and the secondaries are placed in a polling +loop to be released by normal world via PSCI. + +BL2 edits the FDT, generated by QEMU at run-time to add a node describing PSCI +and also enable methods for the CPUs. + +Current limitations: + +- Only cold boot is supported + +To build TF-A: + +:: + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa + cd tfa + export CROSS_COMPILE=aarch64-none-elf- + make PLAT=qemu_sbsa all fip + +To build TF-A with BL32 and SPM enabled(StandaloneMM as a Secure Payload): + +:: + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa + cd tfa + export CROSS_COMPILE=aarch64-none-elf- + make PLAT=qemu_sbsa BL32=../STANDALONE_MM.fd SPM_MM=1 EL3_EXCEPTION_HANDLING=1 all fip + +Images will be placed at build/qemu_sbsa/release (bl1.bin and fip.bin). +Need to copy them into top directory for EDK2 compilation. + +:: + + cp build/qemu_sbsa/release/bl1.bin ../ + cp build/qemu_sbsa/release/fip.bin ../ + +Those images cannot be used by itself (no semihosing support). Flash images are built by +EDK2 build system, refer to edk2-platform repo for full build instructions. + +:: + + git clone https://github.com/tianocore/edk2-platforms.git + Platform/Qemu/SbsaQemu/Readme.md + diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst new file mode 100644 index 0000000..f2a39e9 --- /dev/null +++ b/docs/plat/qemu.rst @@ -0,0 +1,191 @@ +QEMU virt Armv8-A +================= + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU virt +Armv8-A. BL1 is used as the BootROM, supplied with the -bios argument. +When QEMU starts all CPUs are released simultaneously, BL1 selects a +primary CPU to handle the boot and the secondaries are placed in a polling +loop to be released by normal world via PSCI. + +BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to +add a node describing PSCI and also enable methods for the CPUs. + +If ``ARM_LINUX_KERNEL_AS_BL33`` is set to 1 then this FDT will be passed to BL33 +via register x0, as expected by a Linux kernel. This allows a Linux kernel image +to be booted directly as BL33 rather than using a bootloader. + +An ARM64 defconfig v5.5 Linux kernel is known to boot, FDT doesn't need to be +provided as it's generated by QEMU. + +Current limitations: + +- Only cold boot is supported + +Getting non-TF images +--------------------- + +``QEMU_EFI.fd`` can be downloaded from +http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC5/QEMU_EFI.fd + +or, can be built as follows: + +.. code:: shell + + git clone https://github.com/tianocore/edk2.git + cd edk2 + git submodule update --init + make -C BaseTools + source edksetup.sh + export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- + build -a AARCH64 -t GCC5 -p ArmVirtPkg/ArmVirtQemuKernel.dsc + +```` + +Then, you will get ``Build/ArmVirtQemuKernel-AARCH64/DEBUG_GCC5/FV/QEMU_EFI.fd`` + +Please note you do not need to use GCC 5 in spite of the environment variable +``GCC5_AARCH64_PREFIX``. + +The rootfs can be built by using Buildroot as follows: + +.. code:: shell + + git clone git://git.buildroot.net/buildroot.git + cd buildroot + make qemu_aarch64_virt_defconfig + utils/config -e BR2_TARGET_ROOTFS_CPIO + utils/config -e BR2_TARGET_ROOTFS_CPIO_GZIP + make olddefconfig + make + +Then, you will get ``output/images/rootfs.cpio.gz``. + +Booting via semi-hosting option +------------------------------- + +Boot binaries, except BL1, are primarily loaded via semi-hosting so all +binaries has to reside in the same directory as QEMU is started from. This +is conveniently achieved with symlinks the local names as: + +- ``bl2.bin`` -> BL2 +- ``bl31.bin`` -> BL31 +- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``) +- ``Image`` -> linux/arch/arm64/boot/Image + +To build: + +.. code:: shell + + make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu + +To start (QEMU v5.0.0): + +.. code:: shell + + qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ + -kernel Image \ + -append "console=ttyAMA0,38400 keep_bootcon" \ + -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ + -d unimp -semihosting-config enable,target=native + +Booting via flash based firmware +-------------------------------- + +An alternate approach to deploy a full system stack on QEMU is to load the +firmware via a secure flash device. This involves concatenating ``bl1.bin`` and +``fip.bin`` to create a boot ROM that is flashed onto secure FLASH0 with the +``-bios`` option. + +For example, to test the following firmware stack: + + +- BL32 - ``bl32.bin`` -> ``tee-header_v2.bin`` +- BL32 Extra1 - ``bl32_extra1.bin`` -> ``tee-pager_v2.bin`` +- BL32 Extra2 - ``bl32_extra2.bin`` -> ``tee-pageable_v2.bin`` +- BL33 - ``bl33.bin`` -> ``QEMU_EFI.fd`` (EDK II) +- ``Image`` -> linux/arch/arm64/boot/Image + + +1. Compile TF-A + + .. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip + + Or, alternatively, to build with TBBR enabled, as well as, BL31 and BL32 encrypted with + test key: + + .. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip \ + MBEDTLS_DIR=<path-to-mbedtls-repo> TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 DECRYPTION_SUPPORT=aes_gcm FW_ENC_STATUS=0 \ + ENCRYPT_BL31=1 ENCRYPT_BL32=1 + +2. Concatenate ``bl1.bin`` and ``fip.bin`` to create the boot ROM + + .. code:: shell + + dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc + dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc + +3. Launch QEMU + + .. code:: shell + + qemu-system-aarch64 -nographic -machine virt,secure=on + -cpu cortex-a57 -kernel Image \ + -append 'console=ttyAMA0,38400 keep_bootcon' \ + -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin \ + -d unimp + +The ``-bios`` option abstracts the loading of raw bare metal binaries into flash +or ROM memory. QEMU loads the binary into the region corresponding to +the hardware's entrypoint, from which the binary is executed upon a platform +"reset". In addition to this, it places the information about the kernel +provided with option ``-kernel``, and the RamDisk provided with ``-initrd``, +into the firmware configuration ``fw_cfg``. In this setup, EDK II is responsible +for extracting and launching these from ``fw_cfg``. + +.. note:: + QEMU may be launched with or without ACPI (``-acpi``/``-no-acpi``). In + either case, ensure that the kernel build options are aligned with the + parameters passed to QEMU. + +Running QEMU in OpenCI +----------------------- + +Linaro's continuous integration platform OpenCI supports running emulated tests +on QEMU. The tests are kicked off on Jenkins and deployed through the Linaro +Automation and Validation Architecture `LAVA`_. + +There are a set of Linux boot tests provided in OpenCI. They rely on prebuilt +`binaries`_ for UEFI, the kernel, root file system, as well as, any other TF-A +dependencies, and are run as part of the OpenCI TF-A `daily job`_. To run them +manually, a `builder`_ job may be triggered with the test configuration +``qemu-boot-tests``. + + +You may see the following warning repeated several times in the boot logs: + +.. code:: shell + + pflash_write: Write to buffer emulation is flawed + +Please ignore this as it is an unresolved `issue in QEMU`_, it is an internal +QEMU warning that logs flawed use of "write to buffer". + +.. note:: + For more information on how to trigger jobs in OpenCI, please refer to + Linaro's CI documentation, which explains how to trigger a `manual job`_. + +.. _binaries: https://downloads.trustedfirmware.org/tf-a/linux_boot/ +.. _daily job: https://ci.trustedfirmware.org/view/TF-A/job/tf-a-main/ +.. _builder: https://ci.trustedfirmware.org/view/TF-A/job/tf-a-builder/ +.. _LAVA: https://tf.validation.linaro.org/ +.. _manual job: https://tf-ci-users-guide.readthedocs.io/en/latest/#manual-job-trigger +.. _issue in QEMU: https://git.qemu.org/?p=qemu.git;a=blob;f=hw/block/pflash_cfi01.c;h=0cbc2fb4cbf62c9a033b8dd89012374ff74ed610;hb=refs/heads/master#l500 diff --git a/docs/plat/qti-msm8916.rst b/docs/plat/qti-msm8916.rst new file mode 100644 index 0000000..3bc121a --- /dev/null +++ b/docs/plat/qti-msm8916.rst @@ -0,0 +1,211 @@ +Qualcomm MSM8916 +================ +The MSM8916 platform port in TF-A supports multiple similar Qualcomm SoCs: + ++-----------------------+----------------+-------------------+-----------------+ +| System-on-Chip (SoC) | TF-A Platform | Application CPU | Supports | ++=======================+================+===================+=================+ +| `Snapdragon 410`_ |``PLAT=msm8916``| 4x ARM Cortex-A53 | AArch64/AArch32 | +| (MSM8x16, APQ8016(E)) | | | | +| (`DragonBoard 410c`_) | | | | ++-----------------------+----------------+-------------------+-----------------+ +| `Snapdragon 615`_ |``PLAT=msm8939``| 4x ARM Cortex-A53 | AArch64/AArch32 | +| (MSM8x39, APQ8039) | | 4x ARM Cortex-A53 | | ++-----------------------+----------------+-------------------+-----------------+ +| `Snapdragon 210`_ |``PLAT=msm8909``| 4x ARM Cortex-A7 | AArch32 only | +| (MSM8x09, APQ8009) | | | | ++-----------------------+----------------+-------------------+-----------------+ +| `Snapdragon X5 Modem`_|``PLAT=mdm9607``| 1x ARM Cortex-A7 | AArch32 only | +| (MDM9x07) | | | | ++-----------------------+----------------+-------------------+-----------------+ + +It provides a minimal, community-maintained EL3 firmware and PSCI implementation, +based on information from the public `Snapdragon 410E Technical Reference Manual`_ +combined with a lot of trial and error to actually make it work. + +.. note:: + Unlike the :doc:`QTI SC7180/SC7280 <qti>` ports, this port does **not** + make use of a proprietary binary components (QTISECLIB). It is fully + open-source but therefore limited to publicly documented hardware + components. + +Functionality +------------- +The TF-A port is much more minimal compared to the original firmware and +therefore expects the non-secure world (e.g. Linux) to manage more hardware, +such as the SMMUs and all remote processors (RPM, WCNSS, Venus, Modem). +Everything except modem is currently functional with a slightly modified version +of mainline Linux. + +.. warning:: + This port is **not secure**. There is no special secure memory and the + used DRAM is available from both the non-secure and secure worlds. + Unfortunately, the hardware used for memory protection is not described + in the APQ8016E documentation. + +The port is primarily intended as a minimal PSCI implementation (without a +separate secure world) where this limitation is not a big problem. Booting +secondary CPU cores (PSCI ``CPU_ON``) is supported. Basic CPU core power +management (``CPU_SUSPEND``) is functional but still work-in-progress and +will be added later once ready. + +Boot Flow +--------- +BL31 (AArch64) or BL32/SP_MIN (AArch32) replaces the original ``tz`` firmware +in the boot flow:: + + Boot ROM (PBL) -> SBL -> BL31 (EL3) -> U-Boot (EL2) -> Linux (EL2) + +After initialization the normal world starts at a fixed entry address in EL2/HYP +mode, configured using ``PRELOADED_BL33_BASE``. At runtime, it is expected that +the normal world bootloader was already loaded into RAM by a previous firmware +component (usually SBL) and that it is capable of running in EL2/HYP mode. + +`U-Boot for DragonBoard 410c`_ is recommended if possible. The original Little +Kernel-based bootloader from Qualcomm does not support EL2/HYP, but can be +booted using an additional shim loader such as `tfalkstub`_. + +Build +----- +It is possible to build for either AArch64 or AArch32. Some platforms use 32-bit +CPUs that only support AArch32 (see table above). For all others AArch64 is the +preferred build option. + +AArch64 (BL31) +^^^^^^^^^^^^^^ +Setup the cross compiler for AArch64 and build BL31 for one of the platforms in +the table above:: + + $ make CROSS_COMPILE=aarch64-none-elf- PLAT=... + +The BL31 ELF image is generated in ``build/$PLAT/release/bl31/bl31.elf``. + +AArch32 (BL32/SP_MIN) +^^^^^^^^^^^^^^^^^^^^^ +Setup the cross compiler for AArch32 and build BL32 with SP_MIN for one of the +platforms in the table above:: + + $ make CROSS_COMPILE=arm-none-eabi- PLAT=... ARCH=aarch32 AARCH32_SP=sp_min + +The BL32 ELF image is generated in ``build/$PLAT/release/bl32/bl32.elf``. + +Build Options +------------- +Some options can be changed at build time by adding them to the make command line: + + * ``QTI_UART_NUM``: Number of UART controller to use for debug output and crash + reports. This must be the same UART as used by earlier boot firmware since + the UART controller does not get fully initialized at the moment. Defaults to + the usual debug UART used for the platform (see ``platform.mk``). + * ``QTI_RUNTIME_UART``: By default (``0``) the UART is only used for the boot + process and critical crashes. If set to ``1`` it is also used for runtime + messages. Note that this option can only be used if the UART is reserved in + the normal world and the necessary clocks remain enabled. + +The memory region used for the different firmware components is not fixed and +can be changed on the make command line. The default values match the addresses +used by the original firmware (see ``platform.mk``): + + * ``PRELOADED_BL33_BASE``: The entry address for the normal world. Usually + refers to the first bootloader (e.g. U-Boot). + * ``BL31_BASE``: Base address for the BL31 firmware component. Must point to + a 64K-aligned memory region with at least 128 KiB space that is permanently + reserved in the normal world. + * ``BL32_BASE``: Base address for the BL32 firmware component. + + * **AArch32:** BL32 is used in place of BL31, so the option is equivalent to + ``BL31_BASE``. + * **AArch64:** Secure-EL1 Payload. Defaults to using 128 KiB of space + directly after BL31. For testing only, the port is primarily intended as + a minimal PSCI implementation without a separate secure world. + +Installation +------------ +The ELF image must be "signed" before flashing it, even if the board has secure +boot disabled. In this case the signature does not provide any security, +but it provides the firmware with required metadata. + +The `DragonBoard 410c`_ does not have secure boot enabled by default. In this +case you can simply sign the ELF image using a randomly generated key. You can +use e.g. `qtestsign`_:: + + $ ./qtestsign.py tz build/msm8916/release/bl31/bl31.elf + +Then install the resulting ``build/msm8916/release/bl31/bl31-test-signed.mbn`` +to the ``tz`` partition on the device. BL31 should be running after a reboot. + +.. note:: + On AArch32 the ELF image is called ``bl32.elf``. + The installation procedure is identical. + +.. warning:: + Do not flash incorrectly signed firmware on devices that have secure + boot enabled! Make sure that you have a way to recover the board in case + of problems (e.g. using EDL). + +Boot Trace +---------- + +AArch64 (BL31) +^^^^^^^^^^^^^^ +BL31 prints some lines on the debug console, which will usually look like this +(with ``DEBUG=1``, otherwise only the ``NOTICE`` lines are shown):: + + ... + S - DDR Frequency, 400 MHz + NOTICE: BL31: v2.6(debug):v2.6 + NOTICE: BL31: Built : 20:00:00, Dec 01 2021 + INFO: BL31: Platform setup start + INFO: ARM GICv2 driver initialized + INFO: BL31: Platform setup done + INFO: BL31: Initializing runtime services + INFO: BL31: cortex_a53: CPU workaround for 819472 was applied + INFO: BL31: cortex_a53: CPU workaround for 824069 was applied + INFO: BL31: cortex_a53: CPU workaround for 826319 was applied + INFO: BL31: cortex_a53: CPU workaround for 827319 was applied + INFO: BL31: cortex_a53: CPU workaround for 835769 was applied + INFO: BL31: cortex_a53: CPU workaround for disable_non_temporal_hint was applied + INFO: BL31: cortex_a53: CPU workaround for 843419 was applied + INFO: BL31: cortex_a53: CPU workaround for 1530924 was applied + INFO: BL31: Preparing for EL3 exit to normal world + INFO: Entry point address = 0x8f600000 + INFO: SPSR = 0x3c9 + + U-Boot 2021.10 (Dec 01 2021 - 20:00:00 +0000) + Qualcomm-DragonBoard 410C + ... + +AArch32 (BL32/SP_MIN) +^^^^^^^^^^^^^^^^^^^^^ +BL32/SP_MIN prints some lines on the debug console, which will usually look like +this (with ``DEBUG=1``, otherwise only the ``NOTICE`` lines are shown):: + + ... + S - DDR Frequency, 400 MHz + NOTICE: SP_MIN: v2.8(debug):v2.8 + NOTICE: SP_MIN: Built : 23:03:31, Mar 31 2023 + INFO: SP_MIN: Platform setup start + INFO: ARM GICv2 driver initialized + INFO: SP_MIN: Platform setup done + INFO: SP_MIN: Initializing runtime services + INFO: BL32: cortex_a53: CPU workaround for 819472 was applied + INFO: BL32: cortex_a53: CPU workaround for 824069 was applied + INFO: BL32: cortex_a53: CPU workaround for 826319 was applied + INFO: BL32: cortex_a53: CPU workaround for 827319 was applied + INFO: BL32: cortex_a53: CPU workaround for disable_non_temporal_hint was applied + INFO: SP_MIN: Preparing exit to normal world + INFO: Entry point address = 0x86400000 + INFO: SPSR = 0x1da + Android Bootloader - UART_DM Initialized!!! + [0] welcome to lk + ... + +.. _Snapdragon 210: https://www.qualcomm.com/products/snapdragon-processors-210 +.. _Snapdragon 410: https://www.qualcomm.com/products/snapdragon-processors-410 +.. _Snapdragon 615: https://www.qualcomm.com/products/snapdragon-processors-615 +.. _Snapdragon X5 Modem: https://www.qualcomm.com/products/snapdragon-modems-4g-lte-x5 +.. _DragonBoard 410c: https://www.96boards.org/product/dragonboard410c/ +.. _Snapdragon 410E Technical Reference Manual: https://developer.qualcomm.com/download/sd410/snapdragon-410e-technical-reference-manual.pdf +.. _U-Boot for DragonBoard 410c: https://u-boot.readthedocs.io/en/latest/board/qualcomm/dragonboard410c.html +.. _qtestsign: https://github.com/msm8916-mainline/qtestsign +.. _tfalkstub: https://github.com/msm8916-mainline/tfalkstub diff --git a/docs/plat/qti.rst b/docs/plat/qti.rst new file mode 100644 index 0000000..1d483e7 --- /dev/null +++ b/docs/plat/qti.rst @@ -0,0 +1,43 @@ +Qualcomm Technologies, Inc. +=========================== + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QTI SC7180, +SC7280. + +Boot Trace +------------- + +Bootrom --> BL1/BL2 --> BL31 --> BL33 --> Linux kernel + +BL1/2 and BL33 can currently be supplied from Coreboot + Depthcharge + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +QTI SoC expects TF-A's BL31 to get integrated with other boot software +Coreboot, so only bl31.elf need to get build from the TF-A repository. + +The build command looks like + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sc7180 COREBOOT=1 + +update value of CROSS_COMPILE argument with your cross-compilation toolchain. + +Additional QTISECLIB_PATH=<path to qtiseclib> can be added in build command. +if QTISECLIB_PATH is not added in build command stub implementation of qtiseclib +is picked. qtiseclib with stub implementation doesn't boot device. This was +added to satisfy compilation. + +QTISELIB for SC7180 is available at +`link <https://github.com/coreboot/qc_blobs/blob/master/sc7180/qtiseclib/libqtisec.a?raw=true>`__ +QTISELIB for SC7280 is available at +`link <https://github.com/coreboot/qc_blobs/blob/master/sc7280/qtiseclib/libqtisec.a?raw=true>`__ diff --git a/docs/plat/rcar-gen3.rst b/docs/plat/rcar-gen3.rst new file mode 100644 index 0000000..7107bea --- /dev/null +++ b/docs/plat/rcar-gen3.rst @@ -0,0 +1,268 @@ +Renesas R-Car +============= + +"R-Car" is the nickname for Renesas' system-on-chip (SoC) family for +car information systems designed for the next-generation of automotive +computing for the age of autonomous vehicles. + +The scalable R-Car hardware platform and flexible software platform +cover the full product range, from the premium class to the entry +level. Plug-ins are available for multiple open-source software tools. + + +Renesas R-Car Gen3 evaluation boards: +------------------------------------- + ++------------+-----------------+-----------------------------+ +| | Standard | Low Cost Boards (LCB) | ++============+=================+=============================+ +| R-Car H3 | - Salvator-X | - R-Car Starter Kit Premier | +| | - Salvator-XS | | ++------------+-----------------+-----------------------------+ +| R-Car M3-W | - Salvator-X | | +| | - Salvator-XS | - R-Car Starter Kit Pro | ++------------+-----------------+-----------------------------+ +| R-Car M3-N | - Salvator-X | | +| | - Salvator-XS | | ++------------+-----------------+-----------------------------+ +| R-Car V3M | - Eagle | - Starter Kit | ++------------+-----------------+-----------------------------+ +| R-Car V3H | - Condor | - Starter Kit | ++------------+-----------------+-----------------------------+ +| R-Car D3 | - Draak | | ++------------+-----------------+-----------------------------+ + +`boards info <https://elinux.org/R-Car>`__ + +The current TF-A port has been tested on the R-Car H3 Salvator-X +Soc_id r8a7795 revision ES1.1 (uses a Secure Payload Dispatcher) + + +:: + + ARM CA57 (ARMv8) 1.5 GHz quad core, with NEON/VFPv4, L1$ I/D + 48K/32K, L2$ 2MB + ARM CA53 (ARMv8) 1.2 GHz quad core, with NEON/VFPv4, L1$ I/D 32K/32K, + L2$ 512K + Memory controller for LPDDR4-3200 4GB in 2 channels, each 64-bit wide + Two- and three-dimensional graphics engines, + Video processing units, + 3 channels Display Output, + 6 channels Video Input, + SD card host interface, + USB3.0 and USB2.0 interfaces, + CAN interfaces + Ethernet AVB + PCI Express Interfaces + Memories + INTERNAL 384KB SYSTEM RAM + DDR 4 GB LPDDR4 + HYPERFLASH 64 MB HYPER FLASH (512 MBITS, 160 MHZ, 320 MBYTES/S) + QSPI FLASH 16MB QSPI (128 MBITS,80 MHZ,80 MBYTES/S)1 HEADER QSPI + MODULE + EMMC 32 GB EMMC (HS400 240 MBYTES/S) + MICROSD-CARD SLOT (SDR104 100 MBYTES/S) + + +Overview +-------- +On the rcar-gen3 the BOOTROM starts the cpu at EL3; for this port BL2 +will therefore be entered at this exception level (the Renesas' ATF +reference tree [1] resets into EL1 before entering BL2 - see its +bl2.ld.S) + +BL2 initializes DDR (and on some platforms i2c to interface to the +PMIC) before determining the boot reason (cold or warm). + +During suspend all CPUs are switched off and the DDR is put in backup +mode (some kind of self-refresh mode). This means that BL2 is always +entered in a cold boot scenario. + +Once BL2 boots, it determines the boot reason, writes it to shared +memory (BOOT_KIND_BASE) together with the BL31 parameters +(PARAMS_BASE) and jumps to BL31. + +To all effects, BL31 is as if it is being entered in reset mode since +it still needs to initialize the rest of the cores; this is the reason +behind using direct shared memory access to BOOT_KIND_BASE _and_ +PARAMS_BASE instead of using registers to get to those locations (see +el3_common_macros.S and bl31_entrypoint.S for the RESET_TO_BL31 use +case). + +Depending on the boot reason BL31 initializes the rest of the cores: +in case of suspend, it uses a MBOX memory region to recover the +program counters. + +[1] https://github.com/renesas-rcar/arm-trusted-firmware + + +How to build +------------ + +The TF-A build options depend on the target board so you will have to +refer to those specific instructions. What follows is customized to +the H3 SiP Salvator-X development system used in this port. + +Build Tested: +~~~~~~~~~~~~~ +RCAR_OPT="LSI=H3 RCAR_DRAM_SPLIT=1 RCAR_LOSSY_ENABLE=1" +MBEDTLS_DIR=$mbedtls_src + +$ MBEDTLS_DIR=$mbedtls_src_tree make clean bl2 bl31 rcar_layout_tool \ +PLAT=rcar ${RCAR_OPT} SPD=opteed + +System Tested: +~~~~~~~~~~~~~~ +* mbed_tls: + git@github.com:ARMmbed/mbedtls.git [devel] + + commit 552754a6ee82bab25d1bdf28c8261a4518e65e4d + Merge: 68dbc94 f34a4c1 + Author: Simon Butcher <simon.butcher@arm.com> + Date: Thu Aug 30 00:57:28 2018 +0100 + +* optee_os: + https://github.com/BayLibre/optee_os + + Until it gets merged into OP-TEE, the port requires Renesas' + Trusted Environment with a modification to support power + management. + commit 80105192cba9e704ebe8df7ab84095edc2922f84 + + Author: Jorge Ramirez-Ortiz <jramirez@baylibre.com> + Date: Thu Aug 30 16:49:49 2018 +0200 + plat-rcar: cpu-suspend: handle the power level + Signed-off-by: Jorge Ramirez-Ortiz <jramirez@baylibre.com> + +* u-boot: + The port has beent tested using mainline uboot. + + commit 4cdeda511f8037015b568396e6dcc3d8fb41e8c0 + Author: Fabio Estevam <festevam@gmail.com> + Date: Tue Sep 4 10:23:12 2018 -0300 + +* linux: + The port has beent tested using mainline kernel. + + commit 7876320f88802b22d4e2daf7eb027dd14175a0f8 + Author: Linus Torvalds <torvalds@linux-foundation.org> + Date: Sun Sep 16 11:52:37 2018 -0700 + Linux 4.19-rc4 + +TF-A Build Procedure +~~~~~~~~~~~~~~~~~~~~ + +- Fetch all the above 4 repositories. + +- Prepare the AARCH64 toolchain. + +- Build u-boot using r8a7795_salvator-x_defconfig. + Result: u-boot-elf.srec + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- + r8a7795_salvator-x_defconfig + + make CROSS_COMPILE=aarch64-linux-gnu- + +- Build atf + Result: bootparam_sa0.srec, cert_header_sa6.srec, bl2.srec, bl31.srec + +.. code:: bash + + RCAR_OPT="LSI=H3 RCAR_DRAM_SPLIT=1 RCAR_LOSSY_ENABLE=1" + + MBEDTLS_DIR=$mbedtls_src_tree make clean bl2 bl31 rcar \ + PLAT=rcar ${RCAR_OPT} SPD=opteed + +- Build optee-os + Result: tee.srec + +.. code:: bash + + make -j8 PLATFORM="rcar" CFG_ARM64_core=y + +Install Procedure +~~~~~~~~~~~~~~~~~ + +- Boot the board in Mini-monitor mode and enable access to the + Hyperflash. + + +- Use the XSL2 Mini-monitor utility to accept all the SREC ascii + transfers over serial. + + +Boot trace +---------- + +Notice that BL31 traces are not accessible via the console and that in +order to verbose the BL2 output you will have to compile TF-A with +LOG_LEVEL=50 and DEBUG=1 + +:: + + Initial Program Loader(CA57) Rev.1.0.22 + NOTICE: BL2: PRR is R-Car H3 Ver.1.1 + NOTICE: BL2: Board is Salvator-X Rev.1.0 + NOTICE: BL2: Boot device is HyperFlash(80MHz) + NOTICE: BL2: LCM state is CM + NOTICE: AVS setting succeeded. DVFS_SetVID=0x53 + NOTICE: BL2: DDR1600(rev.0.33)NOTICE: [COLD_BOOT]NOTICE: ..0 + NOTICE: BL2: DRAM Split is 4ch + NOTICE: BL2: QoS is default setting(rev.0.37) + NOTICE: BL2: Lossy Decomp areas + NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570 + NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0 + NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0 + NOTICE: BL2: v2.0(release):v2.0-rc0-32-gbcda69a + NOTICE: BL2: Built : 16:41:23, Oct 2 2018 + NOTICE: BL2: Normal boot + INFO: BL2: Doing platform setup + INFO: BL2: Loading image id 3 + NOTICE: BL2: dst=0xe6322000 src=0x8180000 len=512(0x200) + NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=6144(0x1800) + WARNING: r-car ignoring the BL31 size from certificate,using + RCAR_TRUSTED_SRAM_SIZE instead + INFO: Loading image id=3 at address 0x44000000 + NOTICE: rcar_file_len: len: 0x0003e000 + NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=253952(0x3e000) + INFO: Image id=3 loaded: 0x44000000 - 0x4403e000 + INFO: BL2: Loading image id 4 + INFO: Loading image id=4 at address 0x44100000 + NOTICE: rcar_file_len: len: 0x00100000 + NOTICE: BL2: dst=0x44100000 src=0x8200000 len=1048576(0x100000) + INFO: Image id=4 loaded: 0x44100000 - 0x44200000 + INFO: BL2: Loading image id 5 + INFO: Loading image id=5 at address 0x50000000 + NOTICE: rcar_file_len: len: 0x00100000 + NOTICE: BL2: dst=0x50000000 src=0x8640000 len=1048576(0x100000) + INFO: Image id=5 loaded: 0x50000000 - 0x50100000 + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0x44000000 + INFO: SPSR = 0x3cd + VERBOSE: Argument #0 = 0xe6325578 + VERBOSE: Argument #1 = 0x0 + VERBOSE: Argument #2 = 0x0 + VERBOSE: Argument #3 = 0x0 + VERBOSE: Argument #4 = 0x0 + VERBOSE: Argument #5 = 0x0 + VERBOSE: Argument #6 = 0x0 + VERBOSE: Argument #7 = 0x0 + + + U-Boot 2018.09-rc3-00028-g3711616 (Sep 27 2018 - 18:50:24 +0200) + + CPU: Renesas Electronics R8A7795 rev 1.1 + Model: Renesas Salvator-X board based on r8a7795 ES2.0+ + DRAM: 3.5 GiB + Flash: 64 MiB + MMC: sd@ee100000: 0, sd@ee140000: 1, sd@ee160000: 2 + Loading Environment from MMC... OK + In: serial@e6e88000 + Out: serial@e6e88000 + Err: serial@e6e88000 + Net: eth0: ethernet@e6800000 + Hit any key to stop autoboot: 0 + => diff --git a/docs/plat/rockchip.rst b/docs/plat/rockchip.rst new file mode 100644 index 0000000..b7c43fb --- /dev/null +++ b/docs/plat/rockchip.rst @@ -0,0 +1,55 @@ +Rockchip SoCs +============= + +Trusted Firmware-A supports a number of Rockchip ARM SoCs from both +AARCH32 and AARCH64 fields. + +This includes right now: +- px30: Quad-Core Cortex-A53 +- rk3288: Quad-Core Cortex-A17 (past A12) +- rk3328: Quad-Core Cortex-A53 +- rk3368: Octa-Core Cortex-A53 +- rk3399: Hexa-Core Cortex-A53/A72 + + +Boot Sequence +------------- + +For AARCH32: + Bootrom --> BL1/BL2 --> BL32 --> BL33 --> Linux kernel + +For AARCH64: + Bootrom --> BL1/BL2 --> BL31 --> BL33 --> Linux kernel + +BL1/2 and BL33 can currently be supplied from either: +- Coreboot + Depthcharge +- U-Boot - either separately as TPL+SPL or only SPL + + +How to build +------------ + +Rockchip SoCs expect TF-A's BL31 (AARCH64) or BL32 (AARCH32) to get +integrated with other boot software like U-Boot or Coreboot, so only +these images need to get build from the TF-A repository. + +For AARCH64 architectures the build command looks like + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3399 bl32 + +while AARCH32 needs a slightly different command + + make ARCH=aarch32 CROSS_COMPILE=arm-linux-gnueabihf- PLAT=rk3288 AARCH32_SP=sp_min bl32 + +Both need replacing the PLAT argument with the platform from above you +want to build for and the CROSS_COMPILE argument with you cross- +compilation toolchain. + + +How to deploy +------------- + +Both upstream U-Boot and Coreboot projects contain instructions on where +to put the built images during their respective build process. +So after successfully building TF-A just follow their build instructions +to continue. diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst new file mode 100644 index 0000000..5d97a88 --- /dev/null +++ b/docs/plat/rpi3.rst @@ -0,0 +1,461 @@ +Raspberry Pi 3 +============== + +The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four +Arm Cortex-A53 cores. + +The following instructions explain how to use this port of the TF-A with the +default distribution of `Raspbian`_ because that's the distribution officially +supported by the Raspberry Pi Foundation. At the moment of writing this, the +officially supported kernel is a AArch32 kernel. This doesn't mean that this +port of TF-A can't boot a AArch64 kernel. The `Linux tree fork`_ maintained by +the Foundation can be compiled for AArch64 by following the steps in +`AArch64 kernel build instructions`_. + +**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM, +which is available from both the Non-secure and Secure worlds. This port +shouldn't be considered more than a prototype to play with and implement +elements like PSCI to support the Linux kernel. + +Design +------ + +The SoC used by the Raspberry Pi 3 is the Broadcom BCM2837. It is a SoC with a +VideoCore IV that acts as primary processor (and loads everything from the SD +card) and is located between all Arm cores and the DRAM. Check the `Raspberry Pi +3 documentation`_ for more information. + +This explains why it is possible to change the execution state (AArch64/AArch32) +depending on a few files on the SD card. We only care about the cases in which +the cores boot in AArch64 mode. + +The rules are simple: + +- If a file called ``kernel8.img`` is located on the ``boot`` partition of the + SD card, it will load it and execute in EL2 in AArch64. Basically, it executes + a `default AArch64 stub`_ at address **0x0** that jumps to the kernel. + +- If there is also a file called ``armstub8.bin``, it will load it at address + **0x0** (instead of the default stub) and execute it in EL3 in AArch64. All + the cores are powered on at the same time and start at address **0x0**. + +This means that we can use the default AArch32 kernel provided in the official +`Raspbian`_ distribution by renaming it to ``kernel8.img``, while TF-A and +anything else we need is in ``armstub8.bin``. This way we can forget about the +default bootstrap code. When using a AArch64 kernel, it is only needed to make +sure that the name on the SD card is ``kernel8.img``. + +Ideally, we want to load the kernel and have all cores available, which means +that we need to make the secondary cores work in the way the kernel expects, as +explained in `Secondary cores`_. In practice, a small bootstrap is needed +between TF-A and the kernel. + +To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode +in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The +architecture specifies that AArch32 Hypervisor mode isn't present when AArch64 +is used for EL2. When using a AArch64 kernel, it should simply start in EL2. + +Placement of images +~~~~~~~~~~~~~~~~~~~ + +The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding +between them so that the addresses they are loaded to match the ones specified +when compiling TF-A. This is done automatically by the build system. + +The device tree block is loaded by the VideoCore loader from an appropriate +file, but we can specify the address it is loaded to in ``config.txt``. + +The file ``kernel8.img`` contains a kernel image that is loaded to the address +specified in ``config.txt``. The `Linux kernel tree`_ has information about how +a AArch32 Linux kernel image is loaded in ``Documentation/arm/Booting``: + +:: + + The zImage may also be placed in system RAM and called there. The + kernel should be placed in the first 128MiB of RAM. It is recommended + that it is loaded above 32MiB in order to avoid the need to relocate + prior to decompression, which will make the boot process slightly + faster. + +There are no similar restrictions for AArch64 kernels, as specified in the file +``Documentation/arm64/booting.txt``. + +This means that we need to avoid the first 128 MiB of RAM when placing the +TF-A images (and specially the first 32 MiB, as they are directly used to +place the uncompressed AArch32 kernel image. This way, both AArch32 and +AArch64 kernels can be placed at the same address. + +In the end, the images look like the following diagram when placed in memory. +All addresses are Physical Addresses from the point of view of the Arm cores. +Again, note that this is all just part of the same DRAM that goes from +**0x00000000** to **0x3F000000**, it just has different names to simulate a real +secure platform! + +:: + + 0x00000000 +-----------------+ + | ROM | BL1 + 0x00020000 +-----------------+ + | FIP | + 0x00200000 +-----------------+ + | | + | ... | + | | + 0x01000000 +-----------------+ + | DTB | (Loaded by the VideoCore) + +-----------------+ + | | + | ... | + | | + 0x02000000 +-----------------+ + | Kernel | (Loaded by the VideoCore) + +-----------------+ + | | + | ... | + | | + 0x10000000 +-----------------+ + | Secure SRAM | BL2, BL31 + 0x10100000 +-----------------+ + | Secure DRAM | BL32 (Secure payload) + 0x11000000 +-----------------+ + | Non-secure DRAM | BL33 + +-----------------+ + | | + | ... | + | | + 0x3F000000 +-----------------+ + | I/O | + 0x40000000 +-----------------+ + +The area between **0x10000000** and **0x11000000** has to be manually protected +so that the kernel doesn't use it. The current port tries to modify the live DTB +to add a memreserve region that reserves the previously mentioned area. + +If this is not possible, the user may manually add ``memmap=16M$256M`` to the +command line passed to the kernel in ``cmdline.txt``. See the `Setup SD card`_ +instructions to see how to do it. This system is strongly discouraged. + +The last 16 MiB of DRAM can only be accessed by the VideoCore, that has +different mappings than the Arm cores in which the I/O addresses don't overlap +the DRAM. The memory reserved to be used by the VideoCore is always placed at +the end of the DRAM, so this space isn't wasted. + +Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for +TF-A, there are 880 MiB available for Linux. + +Boot sequence +~~~~~~~~~~~~~ + +The boot sequence of TF-A is the usual one except when booting an AArch32 +kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so that it +can jump to the kernel in the same mode and let it take over that privilege +level. If BL33 was running in EL2 in AArch64 (as in the default bootflow of +TF-A) it could only jump to the kernel in AArch32 in Supervisor mode. + +The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel +in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The +bootstrap should take care of this. + +This port support a direct boot of the Linux kernel from the firmware (as a BL33 +image). Alternatively, U-Boot or other bootloaders may be used. + +Secondary cores +~~~~~~~~~~~~~~~ + +This port of the Trusted Firmware-A supports ``PSCI_CPU_ON``, +``PSCI_SYSTEM_RESET`` and ``PSCI_SYSTEM_OFF``. The last one doesn't really turn +the system off, it simply reboots it and asks the VideoCore firmware to keep it +in a low power mode permanently. + +The kernel used by `Raspbian`_ doesn't have support for PSCI, so it is needed to +use mailboxes to trap the secondary cores until they are ready to jump to the +kernel. This mailbox is located at a different address in the AArch32 default +kernel than in the AArch64 kernel. + +Kernels with PSCI support can use the PSCI calls instead for a cleaner boot. + +Also, this port of TF-A has another Trusted Mailbox in Shared BL RAM. During +cold boot, all secondary cores wait in a loop until they are given given an +address to jump to in this Mailbox (``bl31_warm_entrypoint``). + +Once BL31 has finished and the primary core has jumped to the BL33 payload, it +has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop. +The payload then makes them wait in another waitloop listening from messages +from the kernel. When the primary CPU jumps into the kernel, it will send an +address to the mailbox so that the secondary CPUs jump to it and are recognised +by the kernel. + +Build Instructions +------------------ + +To boot a AArch64 kernel, only the AArch64 toolchain is required. + +To boot a AArch32 kernel, both AArch64 and AArch32 toolchains are required. The +AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit +kernel. + +The build system concatenates BL1 and the FIP so that the addresses match the +ones in the memory map. The resulting file is ``armstub8.bin``, located in the +build folder (e.g. ``build/rpi3/debug/armstub8.bin``). To know how to use this +file, follow the instructions in `Setup SD card`_. + +The following build options are supported: + +- ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image. + By default this option is 0, which means that TF-A will jump to BL33 in EL2 + in AArch64 mode. If set to 1, it will jump to BL33 in Hypervisor in AArch32 + mode. + +- ``PRELOADED_BL33_BASE``: Used to specify the address of a BL33 binary that has + been preloaded by any other system than using the firmware. ``BL33`` isn't + needed in the build command line if this option is used. Specially useful + because the file ``kernel8.img`` can be loaded anywhere by modifying the file + ``config.txt``. It doesn't have to contain a kernel, it could have any + arbitrary payload. + +- ``RPI3_DIRECT_LINUX_BOOT``: Disabled by default. Set to 1 to enable the direct + boot of the Linux kernel from the firmware. Option ``RPI3_PRELOADED_DTB_BASE`` + is mandatory when the direct Linux kernel boot is used. Options + ``PRELOADED_BL33_BASE`` will most likely be needed as well because it is + unlikely that the kernel image will fit in the space reserved for BL33 images. + This option can be combined with ``RPI3_BL33_IN_AARCH32`` in order to boot a + 32-bit kernel. The only thing this option does is to set the arguments in + registers x0-x3 or r0-r2 as expected by the kernel. + +- ``RPI3_PRELOADED_DTB_BASE``: Auxiliary build option needed when using + ``RPI3_DIRECT_LINUX_BOOT=1``. This option allows to specify the location of a + DTB in memory. + +- ``RPI3_RUNTIME_UART``: Indicates whether the UART should be used at runtime + or disabled. ``-1`` (default) disables the runtime UART. Any other value + enables the default UART (currently UART1) for runtime messages. + +- ``RPI3_USE_UEFI_MAP``: Set to 1 to build ATF with the altername memory + mapping required for an UEFI firmware payload. These changes are needed + to be able to run Windows on ARM64. This option, which is disabled by + default, results in the following memory mappings: + +:: + + 0x00000000 +-----------------+ + | ROM | BL1 + 0x00010000 +-----------------+ + | DTB | (Loaded by the VideoCore) + 0x00020000 +-----------------+ + | FIP | + 0x00030000 +-----------------+ + | | + | UEFI PAYLOAD | + | | + 0x00200000 +-----------------+ + | Secure SRAM | BL2, BL31 + 0x00300000 +-----------------+ + | Secure DRAM | BL32 (Secure payload) + 0x00400000 +-----------------+ + | | + | | + | Non-secure DRAM | BL33 + | | + | | + 0x01000000 +-----------------+ + | | + | ... | + | | + 0x3F000000 +-----------------+ + | I/O | + +- ``BL32``: This port can load and run OP-TEE. The OP-TEE image is optional. + Please use the code from `here <https://github.com/OP-TEE/optee_os>`__. + Build the Trusted Firmware with option ``BL32=tee-header_v2.bin + BL32_EXTRA1=tee-pager_v2.bin BL32_EXTRA2=tee-pageable_v2.bin`` + to put the binaries into the FIP. + + .. warning:: + If OP-TEE is used it may be needed to add the following options to the + Linux command line so that the USB driver doesn't use FIQs: + ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``. + This will unfortunately reduce the performance of the USB driver. It is + needed when using Raspbian, for example. + +- ``TRUSTED_BOARD_BOOT``: This port supports TBB. Set this option to 1 to enable + it. In order to use TBB, you might want to set ``GENERATE_COT=1`` to let the + contents of the FIP automatically signed by the build process. The ROT key + will be generated and output to ``rot_key.pem`` in the build directory. It is + able to set ROT_KEY to your own key in PEM format. Also in order to build, + you need to clone mbed TLS from `here <https://github.com/ARMmbed/mbedtls>`__. + ``MBEDTLS_DIR`` must point at the mbed TLS source directory. + +- ``ENABLE_STACK_PROTECTOR``: Disabled by default. It uses the hardware RNG of + the board. + +The following is not currently supported: + +- AArch32 for TF-A itself. + +- ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any + address by changing the file ``armstub8.bin``, so there's no point in using + TF-A in this case. + +Building the firmware for kernels that don't support PSCI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the case for the 32-bit image of Raspbian, for example. 64-bit kernels +always support PSCI, but they may not know that the system understands PSCI due +to an incorrect DTB file. + +First, clone and compile the 32-bit version of the `Raspberry Pi 3 TF-A +bootstrap`_. Choose the one needed for the architecture of your kernel. + +Then compile TF-A. For a 32-bit kernel, use the following command line: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \ + RPI3_BL33_IN_AARCH32=1 \ + BL33=../rpi3-arm-tf-bootstrap/aarch32/el2-bootstrap.bin + +For a 64-bit kernel, use this other command line: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \ + BL33=../rpi3-arm-tf-bootstrap/aarch64/el2-bootstrap.bin + +However, enabling PSCI support in a 64-bit kernel is really easy. In the +repository `Raspberry Pi 3 TF-A bootstrap`_ there is a patch that can be applied +to the Linux kernel tree maintained by the Raspberry Pi foundation. It modifes +the DTS to tell the kernel to use PSCI. Once this patch is applied, follow the +instructions in `AArch64 kernel build instructions`_ to get a working 64-bit +kernel image and supporting files. + +Building the firmware for kernels that support PSCI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a 64-bit kernel: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \ + PRELOADED_BL33_BASE=0x02000000 \ + RPI3_PRELOADED_DTB_BASE=0x01000000 \ + RPI3_DIRECT_LINUX_BOOT=1 + +For a 32-bit kernel: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \ + PRELOADED_BL33_BASE=0x02000000 \ + RPI3_PRELOADED_DTB_BASE=0x01000000 \ + RPI3_DIRECT_LINUX_BOOT=1 \ + RPI3_BL33_IN_AARCH32=1 + +AArch64 kernel build instructions +--------------------------------- + +The following instructions show how to install and run a AArch64 kernel by +using a SD card with the default `Raspbian`_ install as base. Skip them if you +want to use the default 32-bit kernel. + +Note that this system won't be fully 64-bit because all the tools in the +filesystem are 32-bit binaries, but it's a quick way to get it working, and it +allows the user to run 64-bit binaries in addition to 32-bit binaries. + +1. Clone the `Linux tree fork`_ maintained by the Raspberry Pi Foundation. To + speed things up, do a shallow clone of the desired branch. + +.. code:: shell + + git clone --depth=1 -b rpi-4.18.y https://github.com/raspberrypi/linux + cd linux + +2. Configure and compile the kernel. Adapt the number after ``-j`` so that it is + 1.5 times the number of CPUs in your computer. This may take some time to + finish. + +.. code:: shell + + make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcmrpi3_defconfig + make -j 6 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- + +3. Copy the kernel image and the device tree to the SD card. Replace the path + by the corresponding path in your computers to the ``boot`` partition of the + SD card. + +.. code:: shell + + cp arch/arm64/boot/Image /path/to/boot/kernel8.img + cp arch/arm64/boot/dts/broadcom/bcm2710-rpi-3-b.dtb /path/to/boot/ + cp arch/arm64/boot/dts/broadcom/bcm2710-rpi-3-b-plus.dtb /path/to/boot/ + +4. Install the kernel modules. Replace the path by the corresponding path to the + filesystem partition of the SD card on your computer. + +.. code:: shell + + make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \ + INSTALL_MOD_PATH=/path/to/filesystem modules_install + +5. Follow the instructions in `Setup SD card`_ except for the step of renaming + the existing ``kernel7.img`` (we have already copied a AArch64 kernel). + +Setup SD card +------------- + +The instructions assume that you have an SD card with a fresh install of +`Raspbian`_ (or that, at least, the ``boot`` partition is untouched, or nearly +untouched). They have been tested with the image available in 2018-03-13. + +1. Insert the SD card and open the ``boot`` partition. + +2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore + bootloader into booting the Arm cores in AArch64 mode, like TF-A needs, + even though the kernel is not compiled for AArch64. + +3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore + bootloader will look for a file called ``armstub8.bin`` and load it at + address **0x0** instead of a predefined one. + +4. To enable the serial port "Mini UART" in Linux, open ``cmdline.txt`` and add + ``console=serial0,115200 console=tty1``. + +5. Open ``config.txt`` and add the following lines at the end (``enable_uart=1`` + is only needed to enable debugging through the Mini UART): + +:: + + enable_uart=1 + kernel_address=0x02000000 + device_tree_address=0x01000000 + +If you connect a serial cable to the Mini UART and your computer, and connect +to it (for example, with ``screen /dev/ttyUSB0 115200``) you should see some +text. In the case of an AArch32 kernel, you should see something like this: + +:: + + NOTICE: Booting Trusted Firmware + NOTICE: BL1: v1.4(release):v1.4-329-g61e94684-dirty + NOTICE: BL1: Built : 00:09:25, Nov 6 2017 + NOTICE: BL1: Booting BL2 + NOTICE: BL2: v1.4(release):v1.4-329-g61e94684-dirty + NOTICE: BL2: Built : 00:09:25, Nov 6 2017 + NOTICE: BL1: Booting BL31 + NOTICE: BL31: v1.4(release):v1.4-329-g61e94684-dirty + NOTICE: BL31: Built : 00:09:25, Nov 6 2017 + [ 0.266484] bcm2835-aux-uart 3f215040.serial: could not get clk: -517 + + Raspbian GNU/Linux 9 raspberrypi ttyS0 + raspberrypi login: + +Just enter your credentials, everything should work as expected. Note that the +HDMI output won't show any text during boot. + +.. _default Arm stub: https://github.com/raspberrypi/tools/blob/master/armstubs/armstub7.S +.. _default AArch64 stub: https://github.com/raspberrypi/tools/blob/master/armstubs/armstub8.S +.. _Linux kernel tree: https://github.com/torvalds/linux +.. _Linux tree fork: https://github.com/raspberrypi/linux +.. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/ +.. _Raspberry Pi 3 TF-A bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap +.. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/ +.. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/ diff --git a/docs/plat/rpi4.rst b/docs/plat/rpi4.rst new file mode 100644 index 0000000..6e83fd7 --- /dev/null +++ b/docs/plat/rpi4.rst @@ -0,0 +1,84 @@ +Raspberry Pi 4 +============== + +The `Raspberry Pi 4`_ is an inexpensive single-board computer that contains four +Arm Cortex-A72 cores. Also in contrast to previous Raspberry Pi versions this +model has a GICv2 interrupt controller. + +This port is a minimal port to support loading non-secure EL2 payloads such +as a 64-bit Linux kernel. Other payloads such as U-Boot or EDK-II should work +as well, but have not been tested at this point. + +**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM, +which is available from both the Non-secure and Secure worlds. The SoC does +not seem to feature a secure memory controller of any kind, so portions of +DRAM can't be protected properly from the Non-secure world. + +Build Instructions +------------------ + +There are no real configuration options at this point, so there is only +one universal binary (bl31.bin), which can be built with: + +.. code:: shell + + CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi4 DEBUG=1 + +Copy the generated build/rpi4/debug/bl31.bin to the SD card, adding an entry +starting with ``armstub=``, then followed by the respective file name to +``config.txt``. You should have AArch64 code in the file loaded as the +"kernel", as BL31 will drop into AArch64/EL2 to the respective load address. +arm64 Linux kernels are known to work this way. + +Other options that should be set in ``config.txt`` to properly boot 64-bit +kernels are: + +:: + + enable_uart=1 + arm_64bit=1 + enable_gic=1 + +The BL31 code will patch the provided device tree blob in memory to advertise +PSCI support, also will add a reserved-memory node to the DT to tell the +non-secure payload to not touch the resident TF-A code. + +If you connect a serial cable between the Mini UART and your computer, and +connect to it (for example, with ``screen /dev/ttyUSB0 115200``) you should +see some text from BL31, followed by the output of the EL2 payload. +The command line provided is read from the ``cmdline.txt`` file on the SD card. + +TF-A port design +---------------- + +In contrast to the existing Raspberry Pi 3 port this one here is a BL31-only +port, also it deviates quite a lot from the RPi3 port in many other ways. +There is not so much difference between the two models, so eventually those +two could be (more) unified in the future. + +As with the previous models, the GPU and its firmware are the first entity to +run after the SoC gets its power. The on-chip Boot ROM loads the next stage +(bootcode.bin) from flash (EEPROM), which is again GPU code. +This part knows how to access the MMC controller and how to parse a FAT +filesystem, so it will load further components and configuration files +from the first FAT partition on the SD card. + +To accommodate this existing way of configuring and setting up the board, +we use as much of this workflow as possible. +If bootcode.bin finds a file called ``armstub8.bin`` on the SD card or it gets +pointed to such code by finding a ``armstub=`` key in ``config.txt``, it will +load this file to the beginning of DRAM (address 0) and execute it in +AArch64 EL3. +But before doing that, it will also load a "kernel" and the device tree into +memory. The load addresses have a default, but can also be changed by +setting them in ``config.txt``. If the GPU firmware finds a magic value in the +armstub image file, it will put those two load addresses in memory locations +near the beginning of memory, where TF-A code picks them up. + +To keep things simple, we will just use the kernel load address as the BL33 +entry point, also put the DTB address in the x0 register, as requested by +the arm64 Linux kernel boot protocol. This does not necessarily mean that +the EL2 payload needs to be a Linux kernel, a bootloader or any other kernel +would work as well, as long as it can cope with having the DT address in +register x0. If the payload has other means of finding the device tree, it +could ignore this address as well. diff --git a/docs/plat/rz-g2.rst b/docs/plat/rz-g2.rst new file mode 100644 index 0000000..e7ae620 --- /dev/null +++ b/docs/plat/rz-g2.rst @@ -0,0 +1,228 @@ +Renesas RZ/G +============ + +The "RZ/G" Family of high-end 64-bit Arm®-based microprocessors (MPUs) +enables the solutions required for the smart society of the future. +Through a variety of Arm Cortex®-A53 and A57-based devices, engineers can +easily implement high-resolution human machine interfaces (HMI), embedded +vision, embedded artificial intelligence (e-AI) and real-time control and +industrial ethernet connectivity. + +The scalable RZ/G hardware platform and flexible software platform +cover the full product range, from the premium class to the entry +level. Plug-ins are available for multiple open-source software tools. + + +Renesas RZ/G2 reference platforms: +---------------------------------- + ++--------------+----------------------------------------------------------------------------------+ +| Board | Details | ++==============+===============+==================================================================+ +| hihope-rzg2h | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2H SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| hihope-rzg2m | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2M SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| hihope-rzg2n | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2N SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| ek874 | "96 boards" compatible board from Silicon Linux equipped with Renesas RZ/G2E SoC | +| +----------------------------------------------------------------------------------+ +| | https://www.si-linux.co.jp/index.php?CAT%2FCAT874 | ++--------------+----------------------------------------------------------------------------------+ + +`boards info <https://www.renesas.com/us/en/products/rzg-linux-platform/rzg-marcketplace/board-solutions.html#rzg2>`__ + +The current TF-A port has been tested on the HiHope RZ/G2M +SoC_id r8a774a1 revision ES1.3. + + +:: + + ARM CA57 (ARMv8) 1.5 GHz dual core, with NEON/VFPv4, L1$ I/D 48K/32K, L2$ 1MB + ARM CA53 (ARMv8) 1.2 GHz quad core, with NEON/VFPv4, L1$ I/D 32K/32K, L2$ 512K + Memory controller for LPDDR4-3200 4GB in 2 channels(32-bit bus mode) + Two- and three-dimensional graphics engines, + Video processing units, + Display Output, + Video Input, + SD card host interface, + USB3.0 and USB2.0 interfaces, + CAN interfaces, + Ethernet AVB, + Wi-Fi + BT, + PCI Express Interfaces, + Memories + INTERNAL 384KB SYSTEM RAM + DDR 4 GB LPDDR4 + QSPI FLASH 64MB + EMMC 32 GB EMMC (HS400 240 MBYTES/S) + MICROSD-CARD SLOT (SDR104 100 MBYTES/S) + +Overview +-------- +On RZ/G2 SoCs the BOOTROM starts the cpu at EL3; for this port BL2 +will therefore be entered at this exception level (the Renesas' ATF +reference tree [1] resets into EL1 before entering BL2 - see its +bl2.ld.S) + +BL2 initializes DDR before determining the boot reason (cold or warm). + +Once BL2 boots, it determines the boot reason, writes it to shared +memory (BOOT_KIND_BASE) together with the BL31 parameters +(PARAMS_BASE) and jumps to BL31. + +To all effects, BL31 is as if it is being entered in reset mode since +it still needs to initialize the rest of the cores; this is the reason +behind using direct shared memory access to BOOT_KIND_BASE _and_ +PARAMS_BASE instead of using registers to get to those locations (see +el3_common_macros.S and bl31_entrypoint.S for the RESET_TO_BL31 use +case). + +[1] https://github.com/renesas-rz/meta-rzg2/tree/BSP-1.0.5/recipes-bsp/arm-trusted-firmware/files + + +How to build +------------ + +The TF-A build options depend on the target board so you will have to +refer to those specific instructions. What follows is customized to +the HiHope RZ/G2M development kit used in this port. + +Build Tested: +~~~~~~~~~~~~~ + +.. code:: bash + + make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\ + RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls + +System Tested: +~~~~~~~~~~~~~~ +* mbed_tls: + git@github.com:ARMmbed/mbedtls.git [devel] + +| commit 72ca39737f974db44723760623d1b29980c00a88 +| Merge: ef94c4fcf dd9ec1c57 +| Author: Janos Follath <janos.follath@arm.com> +| Date: Wed Oct 7 09:21:01 2020 +0100 + +* u-boot: + The port has beent tested using mainline uboot with HiHope RZ/G2M board + specific patches. + +| commit 46ce9e777c1314ccb78906992b94001194eaa87b +| Author: Heiko Schocher <hs@denx.de> +| Date: Tue Nov 3 15:22:36 2020 +0100 + +* linux: + The port has beent tested using mainline kernel. + +| commit f8394f232b1eab649ce2df5c5f15b0e528c92091 +| Author: Linus Torvalds <torvalds@linux-foundation.org> +| Date: Sun Nov 8 16:10:16 2020 -0800 +| Linux 5.10-rc3 + +TF-A Build Procedure +~~~~~~~~~~~~~~~~~~~~ + +- Fetch all the above 3 repositories. + +- Prepare the AARCH64 toolchain. + +- Build u-boot using hihope_rzg2_defconfig. + + Result: u-boot-elf.srec + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- + hihope_rzg2_defconfig + + make CROSS_COMPILE=aarch64-linux-gnu- + +- Build TF-A + + Result: bootparam_sa0.srec, cert_header_sa6.srec, bl2.srec, bl31.srec + +.. code:: bash + + make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\ + RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls + + +Install Procedure +~~~~~~~~~~~~~~~~~ + +- Boot the board in Mini-monitor mode and enable access to the + QSPI flash. + + +- Use the flash_writer utility[2] to flash all the SREC files. + +[2] https://github.com/renesas-rz/rzg2_flash_writer + + +Boot trace +---------- +:: + + INFO: ARM GICv2 driver initialized + NOTICE: BL2: RZ/G2 Initial Program Loader(CA57) Rev.2.0.6 + NOTICE: BL2: PRR is RZ/G2M Ver.1.3 + NOTICE: BL2: Board is HiHope RZ/G2M Rev.4.0 + NOTICE: BL2: Boot device is QSPI Flash(40MHz) + NOTICE: BL2: LCM state is unknown + NOTICE: BL2: DDR3200(rev.0.40) + NOTICE: BL2: [COLD_BOOT] + NOTICE: BL2: DRAM Split is 2ch + NOTICE: BL2: QoS is default setting(rev.0.19) + NOTICE: BL2: DRAM refresh interval 1.95 usec + NOTICE: BL2: Periodic Write DQ Training + NOTICE: BL2: CH0: 400000000 - 47fffffff, 2 GiB + NOTICE: BL2: CH2: 600000000 - 67fffffff, 2 GiB + NOTICE: BL2: Lossy Decomp areas + NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570 + NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0 + NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0 + NOTICE: BL2: FDT at 0xe631db30 + NOTICE: BL2: v2.3(release):v2.4-rc0-2-g1433701e5 + NOTICE: BL2: Built : 13:45:26, Nov 7 2020 + NOTICE: BL2: Normal boot + INFO: BL2: Doing platform setup + INFO: BL2: Loading image id 3 + NOTICE: BL2: dst=0xe631d200 src=0x8180000 len=512(0x200) + NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=6144(0x1800) + WARNING: r-car ignoring the BL31 size from certificate,using RCAR_TRUSTED_SRAM_SIZE instead + INFO: Loading image id=3 at address 0x44000000 + NOTICE: rcar_file_len: len: 0x0003e000 + NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=253952(0x3e000) + INFO: Image id=3 loaded: 0x44000000 - 0x4403e000 + INFO: BL2: Loading image id 5 + INFO: Loading image id=5 at address 0x50000000 + NOTICE: rcar_file_len: len: 0x00100000 + NOTICE: BL2: dst=0x50000000 src=0x8300000 len=1048576(0x100000) + INFO: Image id=5 loaded: 0x50000000 - 0x50100000 + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0x44000000 + INFO: SPSR = 0x3cd + + + U-Boot 2021.01-rc1-00244-gac37e14fbd (Nov 04 2020 - 20:03:34 +0000) + + CPU: Renesas Electronics R8A774A1 rev 1.3 + Model: HopeRun HiHope RZ/G2M with sub board + DRAM: 3.9 GiB + MMC: mmc@ee100000: 0, mmc@ee160000: 1 + Loading Environment from MMC... OK + In: serial@e6e88000 + Out: serial@e6e88000 + Err: serial@e6e88000 + Net: eth0: ethernet@e6800000 + Hit any key to stop autoboot: 0 + => diff --git a/docs/plat/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst new file mode 100644 index 0000000..9288193 --- /dev/null +++ b/docs/plat/socionext-uniphier.rst @@ -0,0 +1,116 @@ +Socionext UniPhier +================== + +Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure +world firmware, supporting BL2 and BL31. + +UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_ +image from a non-volatile storage to the on-chip SRAM, and jumps over to it. +TF-A provides a special mode, BL2-AT-EL3, which enables BL2 to execute at EL3. +It is useful for platforms with non-TF-A boot ROM, like UniPhier. Here, a +problem is BL2 does not fit in the 64KB limit if +:ref:`Trusted Board Boot (TBB) <Trusted Board Boot>` is enabled. +To solve this issue, Socionext provides a first stage loader called +`UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the DRAM, +expands BL2 there, and hands the control over to it. Therefore, all images +of TF-A run in DRAM. + +The UniPhier platform works with/without TBB. See below for the build process +of each case. The image authentication for the UniPhier platform fully +complies with the Trusted Board Boot Requirements (TBBR) specification. + +The UniPhier BL does not implement the authentication functionality, that is, +it can not verify the BL2 image by itself. Instead, the UniPhier BL assures +the BL2 validity in a different way; BL2 is GZIP-compressed and appended to +the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL2 +fits in the 64KB limit. The concatenated image is loaded by the internal boot +ROM (and verified if the chip fuses are blown). + + +Boot Flow +--------- + +1. The Boot ROM + + This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with + compressed-BL2 appended) into the on-chip SRAM. If the SoC fuses are blown, + the image is verified by the SoC's own method. + +2. UniPhier BL + + This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM + setup, it decompresses the appended BL2 image into the DRAM, then jumps to + the BL2 entry. + +3. BL2 (at EL3) + + This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally + SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled, + they are all authenticated by the standard mechanism of TF-A. + After loading all the images, it jumps to the BL31 entry. + +4. BL31, BL32, and BL33 + + They all run in the DRAM. See :ref:`Firmware Design` for details. + + +Basic Build +----------- + +BL2 must be compressed for the reason above. The UniPhier's platform makefile +provides a build target ``bl2_gzip`` for this. + +For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier +SoCs. The U-Boot image (``u-boot.bin``) must be built in advance. For the build +procedure of U-Boot, refer to the document in the `U-Boot`_ project. + +To build minimum functionality for UniPhier (without TBB):: + + make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl2_gzip fip + +Output images: + +- ``bl2.bin.gz`` +- ``fip.bin`` + + +Optional features +----------------- + +- Trusted Board Boot + + `mbed TLS`_ is needed as the cryptographic and image parser modules. + Refer to the :ref:`Prerequisites` document for the appropriate version of + mbed TLS. + + To enable TBB, add the following options to the build command:: + + TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=<path-to-mbedtls> + +- System Control Processor (SCP) + + If desired, FIP can include an SCP BL2 image. If BL2 finds an SCP BL2 image + in FIP, BL2 loads it into DRAM and kicks the SCP. Most of UniPhier boards + still work without SCP, but SCP provides better power management support. + + To include SCP BL2, add the following option to the build command:: + + SCP_BL2=<path-to-SCP> + +- BL32 (Secure Payload) + + To enable BL32, add the following options to the build command:: + + SPD=<spd> BL32=<path-to-BL32> + + If you use TSP for BL32, ``BL32=<path-to-BL32>`` is not required. Just add the + following:: + + SPD=tspd + + +.. [1] Some SoCs can load 80KB, but the software implementation must be aligned + to the lowest common denominator. +.. _UniPhier BL: https://github.com/uniphier/uniphier-bl +.. _U-Boot: https://www.denx.de/wiki/U-Boot +.. _mbed TLS: https://tls.mbed.org/ diff --git a/docs/plat/st/index.rst b/docs/plat/st/index.rst new file mode 100644 index 0000000..95ec3d2 --- /dev/null +++ b/docs/plat/st/index.rst @@ -0,0 +1,14 @@ +STMicroelectronics STM32 MPUs +============================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + stm32mpus + stm32mp1 + stm32mp2 + +-------------- + +*Copyright (c) 2023, STMicroelectronics - All Rights Reserved* diff --git a/docs/plat/st/stm32mp1.rst b/docs/plat/st/stm32mp1.rst new file mode 100644 index 0000000..b6e4b0d --- /dev/null +++ b/docs/plat/st/stm32mp1.rst @@ -0,0 +1,220 @@ +STM32MP1 +======== + +STM32MP1 is a microprocessor designed by STMicroelectronics +based on Arm Cortex-A7. +It is an Armv7-A platform, using dedicated code from TF-A. +More information can be found on `STM32MP1 Series`_ page. + +For TF-A common configuration of STM32 MPUs, please check +:ref:`STM32 MPUs` page. + +STM32MP1 Versions +----------------- + +There are 2 variants for STM32MP1: STM32MP13 and STM32MP15 + +STM32MP13 Versions +~~~~~~~~~~~~~~~~~~ +The STM32MP13 series is available in 3 different lines which are pin-to-pin compatible: + +- STM32MP131: Single Cortex-A7 core +- STM32MP133: STM32MP131 + 2*CAN, ETH2(GMAC), ADC1 +- STM32MP135: STM32MP133 + DCMIPP, LTDC + +Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option: + +- A Cortex-A7 @ 650 MHz +- C Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz +- D Cortex-A7 @ 900 MHz +- F Secure Boot + HW Crypto + Cortex-A7 @ 900 MHz + +STM32MP15 Versions +~~~~~~~~~~~~~~~~~~ +The STM32MP15 series is available in 3 different lines which are pin-to-pin compatible: + +- STM32MP157: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz, 3D GPU, DSI display interface and CAN FD +- STM32MP153: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz and CAN FD +- STM32MP151: Single Cortex-A7 core, Cortex-M4 core @ 209 MHz + +Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option: + +- A Basic + Cortex-A7 @ 650 MHz +- C Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz +- D Basic + Cortex-A7 @ 800 MHz +- F Secure Boot + HW Crypto + Cortex-A7 @ 800 MHz + +The `STM32MP1 part number codification`_ page gives more information about part numbers. + +Memory mapping +-------------- + +:: + + 0x00000000 +-----------------+ + | | ROM + 0x00020000 +-----------------+ + | | + | ... | + | | + 0x2FFC0000 +-----------------+ \ + | BL32 DTB | | + 0x2FFC5000 +-----------------+ | + | BL32 | | + 0x2FFDF000 +-----------------+ | + | ... | | + 0x2FFE3000 +-----------------+ | + | BL2 DTB | | Embedded SRAM + 0x2FFEA000 +-----------------+ | + | BL2 | | + 0x2FFFF000 +-----------------+ | + | SCMI mailbox | | + 0x30000000 +-----------------+ / + | | + | ... | + | | + 0x40000000 +-----------------+ + | | + | | Devices + | | + 0xC0000000 +-----------------+ \ + | | | + 0xC0100000 +-----------------+ | + | BL33 | | Non-secure RAM (DDR) + | ... | | + | | | + 0xFFFFFFFF +-----------------+ / + + +Build Instructions +------------------ + +STM32MP1x specific flags +~~~~~~~~~~~~~~~~~~~~~~~~ + +Dedicated STM32MP1 flags: + +- | ``STM32_TF_VERSION``: to manage BL2 monotonic counter. + | Default: 0 +- | ``STM32MP13``: to select STM32MP13 variant configuration. + | Default: 0 +- | ``STM32MP15``: to select STM32MP15 variant configuration. + | Default: 1 + + +Boot with FIP +~~~~~~~~~~~~~ +You need to build BL2, BL32 (SP_min or OP-TEE) and BL33 (U-Boot) before building FIP binary. + +U-Boot +______ + +.. code:: bash + + cd <u-boot_directory> + make stm32mp15_trusted_defconfig + make DEVICE_TREE=stm32mp157c-ev1 all + +OP-TEE (optional) +_________________ + +.. code:: bash + + cd <optee_directory> + make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm PLATFORM=stm32mp1 \ + CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts + + +TF-A BL32 (SP_min) +__________________ +If you choose not to use OP-TEE, you can use TF-A SP_min. +To build TF-A BL32, and its device tree file: + +.. code:: bash + + make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + AARCH32_SP=sp_min DTB_FILE_NAME=stm32mp157c-ev1.dtb bl32 dtbs + +TF-A BL2 +________ +To build TF-A BL2 with its STM32 header for SD-card boot: + +.. code:: bash + + make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + DTB_FILE_NAME=stm32mp157c-ev1.dtb STM32MP_SDMMC=1 + +For other boot devices, you have to replace STM32MP_SDMMC in the previous command +with the desired device flag. + +This BL2 is independent of the BL32 used (SP_min or OP-TEE) + + +FIP +___ +With BL32 SP_min: + +.. code:: bash + + make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + AARCH32_SP=sp_min \ + DTB_FILE_NAME=stm32mp157c-ev1.dtb \ + BL33=<u-boot_directory>/u-boot-nodtb.bin \ + BL33_CFG=<u-boot_directory>/u-boot.dtb \ + fip + +With OP-TEE: + +.. code:: bash + + make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + AARCH32_SP=optee \ + DTB_FILE_NAME=stm32mp157c-ev1.dtb \ + BL33=<u-boot_directory>/u-boot-nodtb.bin \ + BL33_CFG=<u-boot_directory>/u-boot.dtb \ + BL32=<optee_directory>/tee-header_v2.bin \ + BL32_EXTRA1=<optee_directory>/tee-pager_v2.bin + BL32_EXTRA2=<optee_directory>/tee-pageable_v2.bin + fip + +Trusted Boot Board +__________________ + +.. code:: shell + + tools/cert_create/cert_create -n --rot-key build/stm32mp1/release/rot_key.pem \ + --tfw-nvctr 0 \ + --ntfw-nvctr 0 \ + --key-alg ecdsa --hash-alg sha256 \ + --trusted-key-cert build/stm32mp1/release/trusted_key.crt \ + --tos-fw <optee_directory>/tee-header_v2.bin \ + --tos-fw-extra1 <optee_directory>/tee-pager_v2.bin \ + --tos-fw-extra2 <optee_directory>/tee-pageable_v2.bin \ + --tos-fw-cert build/stm32mp1/release/tos_fw_content.crt \ + --tos-fw-key-cert build/stm32mp1/release/tos_fw_key.crt \ + --nt-fw <u-boot_directory>/u-boot-nodtb.bin \ + --nt-fw-cert build/stm32mp1/release/nt_fw_content.crt \ + --nt-fw-key-cert build/stm32mp1/release/nt_fw_key.crt \ + --hw-config <u-boot_directory>/u-boot.dtb \ + --fw-config build/stm32mp1/release/fdts/fw-config.dtb \ + --stm32mp-cfg-cert build/stm32mp1/release/stm32mp_cfg_cert.crt + + tools/fiptool/fiptool create --tos-fw <optee_directory>/tee-header_v2.bin \ + --tos-fw-extra1 <optee_directory>/tee-pager_v2.bin \ + --tos-fw-extra2 <optee_directory>/tee-pageable_v2.bin \ + --nt-fw <u-boot_directory>/u-boot-nodtb.bin \ + --hw-config <u-boot_directory>/u-boot.dtb \ + --fw-config build/stm32mp1/release/fdts/fw-config.dtb \ + --trusted-key-cert build/stm32mp1/release/trusted_key.crt \ + --tos-fw-cert build/stm32mp1/release/tos_fw_content.crt \ + --tos-fw-key-cert build/stm32mp1/release/tos_fw_key.crt \ + --nt-fw-cert build/stm32mp1/release/nt_fw_content.crt \ + --nt-fw-key-cert build/stm32mp1/release/nt_fw_key.crt \ + --stm32mp-cfg-cert build/stm32mp1/release/stm32mp_cfg_cert.crt \ + build/stm32mp1/release/stm32mp1.fip + + +.. _STM32MP1 Series: https://www.st.com/en/microcontrollers-microprocessors/stm32mp1-series.html +.. _STM32MP1 part number codification: https://wiki.st.com/stm32mpu/wiki/STM32MP15_microprocessor#Part_number_codification + +*Copyright (c) 2023, STMicroelectronics - All Rights Reserved* diff --git a/docs/plat/st/stm32mp2.rst b/docs/plat/st/stm32mp2.rst new file mode 100644 index 0000000..43e131d --- /dev/null +++ b/docs/plat/st/stm32mp2.rst @@ -0,0 +1,133 @@ +STM32MP2 +======== + +STM32MP2 is a microprocessor designed by STMicroelectronics +based on Arm Cortex-A35. + +For TF-A common configuration of STM32 MPUs, please check +:ref:`STM32 MPUs` page. + +STM32MP2 Versions +----------------- + +The STM32MP25 series is available in 4 different lines which are pin-to-pin compatible: + +- STM32MP257: Dual Cortex-A35 cores, Cortex-M33 core - 3x Ethernet (2+1 switch) - 3x CAN FD – H264 - 3D GPU – AI / NN - LVDS +- STM32MP255: Dual Cortex-A35 cores, Cortex-M33 core - 2x Ethernet – 3x CAN FD - H264 - 3D GPU – AI / NN - LVDS +- STM32MP253: Dual Cortex-A35 cores, Cortex-M33 core - 2x Ethernet – 3x CAN FD - LVDS +- STM32MP251: Single Cortex-A35 core, Cortex-M33 core - 1x Ethernet + +Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option: + +- A Basic + Cortex-A35 @ 1GHz +- C Secure Boot + HW Crypto + Cortex-A35 @ 1GHz +- D Basic + Cortex-A35 @ 1.5GHz +- F Secure Boot + HW Crypto + Cortex-A35 @ 1.5GHz + +Memory mapping +-------------- + +:: + + 0x00000000 +-----------------+ + | | + | ... | + | | + 0x0E000000 +-----------------+ \ + | BL31 | | + +-----------------+ | + | ... | | + 0x0E012000 +-----------------+ | + | BL2 DTB | | Embedded SRAM + 0x0E016000 +-----------------+ | + | BL2 | | + 0x0E040000 +-----------------+ / + | | + | ... | + | | + 0x40000000 +-----------------+ + | | + | | Devices + | | + 0x80000000 +-----------------+ \ + | | | + | | | Non-secure RAM (DDR) + | | | + 0xFFFFFFFF +-----------------+ / + + +Build Instructions +------------------ + +STM32MP2x specific flags +~~~~~~~~~~~~~~~~~~~~~~~~ + +Dedicated STM32MP2 build flags: + +- | ``STM32MP_DDR_FIP_IO_STORAGE``: to store DDR firmware in FIP. + | Default: 1 +- | ``STM32MP25``: to select STM32MP25 variant configuration. + | Default: 1 + +To compile the correct DDR driver, one flag must be set among: + +- | ``STM32MP_DDR3_TYPE``: to compile DDR3 driver and DT. + | Default: 0 +- | ``STM32MP_DDR4_TYPE``: to compile DDR4 driver and DT. + | Default: 0 +- | ``STM32MP_LPDDR4_TYPE``: to compile LpDDR4 driver and DT. + | Default: 0 + + +Boot with FIP +~~~~~~~~~~~~~ +You need to build BL2, BL31, BL32 (OP-TEE) and BL33 (U-Boot) before building FIP binary. + +U-Boot +______ + +.. code:: bash + + cd <u-boot_directory> + make stm32mp25_defconfig + make DEVICE_TREE=stm32mp257f-ev1 all + +OP-TEE +______ + +.. code:: bash + + cd <optee_directory> + make CROSS_COMPILE64=aarch64-none-elf- CROSS_COMPILE32=arm-none-eabi- + ARCH=arm PLATFORM=stm32mp2 \ + CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-ev1.dts + +TF-A BL2 & BL31 +_______________ +To build TF-A BL2 with its STM32 header and BL31 for SD-card boot: + +.. code:: bash + + make CROSS_COMPILE=aarch64-none-elf- PLAT=stm32mp2 \ + STM32MP_DDR4_TYPE=1 SPD=opteed \ + DTB_FILE_NAME=stm32mp257f-ev1.dtb STM32MP_SDMMC=1 + +For other boot devices, you have to replace STM32MP_SDMMC in the previous command +with the desired device flag. + + +FIP +___ + +.. code:: bash + + make CROSS_COMPILE=aarch64-none-elf- PLAT=stm32mp2 \ + STM32MP_DDR4_TYPE=1 SPD=opteed \ + DTB_FILE_NAME=stm32mp257f-ev1.dtb \ + BL33=<u-boot_directory>/u-boot-nodtb.bin \ + BL33_CFG=<u-boot_directory>/u-boot.dtb \ + BL32=<optee_directory>/tee-header_v2.bin \ + BL32_EXTRA1=<optee_directory>/tee-pager_v2.bin + fip + +*Copyright (c) 2023, STMicroelectronics - All Rights Reserved* diff --git a/docs/plat/st/stm32mpus.rst b/docs/plat/st/stm32mpus.rst new file mode 100644 index 0000000..931dd57 --- /dev/null +++ b/docs/plat/st/stm32mpus.rst @@ -0,0 +1,78 @@ +STM32 MPUs +========== + +STM32 MPUs are microprocessors designed by STMicroelectronics +based on Arm Cortex-A. This page presents the common configuration of STM32 +MPUs, more details and dedicated configuration can be found in each STM32 MPU +page (:ref:`STM32MP1` or :ref:`STM32MP2`) + +Design +------ +The STM32 MPU resets in the ROM code of the Cortex-A. +The primary boot core (core 0) executes the boot sequence while +secondary boot core (core 1) is kept in a holding pen loop. +The ROM code boot sequence loads the TF-A binary image from boot device +to embedded SRAM. + +The TF-A image must be properly formatted with a STM32 header structure +for ROM code is able to load this image. +Tool stm32image can be used to prepend this header to the generated TF-A binary. + +Boot +~~~~ +Only BL2 (with STM32 header) is loaded by ROM code. The other binaries are +inside the FIP binary: BL31 (for Aarch64 platforms), BL32 (OP-TEE), U-Boot +and their respective device tree blobs. + +Boot sequence +~~~~~~~~~~~~~ + +ROM code -> BL2 (compiled with RESET_TO_BL2) -> OP-TEE -> BL33 (U-Boot) + +Build Instructions +------------------ +Boot media(s) supported by BL2 must be specified in the build command. +Available storage medias are: + +- ``STM32MP_SDMMC`` +- ``STM32MP_EMMC`` +- ``STM32MP_RAW_NAND`` +- ``STM32MP_SPI_NAND`` +- ``STM32MP_SPI_NOR`` + +Serial boot devices: + +- ``STM32MP_UART_PROGRAMMER`` +- ``STM32MP_USB_PROGRAMMER`` + + +Other configuration flags: + +- | ``DTB_FILE_NAME``: to precise board device-tree blob to be used. + | Default: stm32mp157c-ev1.dtb +- | ``DWL_BUFFER_BASE``: the 'serial boot' load address of FIP, + | default location (end of the first 128MB) is used when absent +- | ``STM32MP_EARLY_CONSOLE``: to enable early traces before clock driver is setup. + | Default: 0 (disabled) +- | ``STM32MP_RECONFIGURE_CONSOLE``: to re-configure crash console (especially after BL2). + | Default: 0 (disabled) +- | ``STM32MP_UART_BAUDRATE``: to select UART baud rate. + | Default: 115200 + + +Populate SD-card +---------------- + +Boot with FIP +~~~~~~~~~~~~~ +The SD-card has to be formatted with GPT. +It should contain at least those partitions: + +- fsbl: to copy the tf-a-stm32mp157c-ev1.stm32 binary (BL2) +- fip (GUID 19d5df83-11b0-457b-be2c-7559c13142a5): which contains the FIP binary + +Usually, two copies of fsbl are used (fsbl1 and fsbl2) instead of one partition fsbl. + +-------------- + +*Copyright (c) 2023, STMicroelectronics - All Rights Reserved* diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst new file mode 100644 index 0000000..f2c8fd2 --- /dev/null +++ b/docs/plat/stm32mp1.rst @@ -0,0 +1,10 @@ +:orphan: + +STMicroelectronics STM32MP1 (old page) +====================================== + +Please check :ref:`STM32 MPUs` page for generic information about +STMicroelectronics STM32 microprocessors in TF-A, and :ref:`STM32MP1` page +for specificities on STM32MP1x platforms. + +*Copyright (c) 2018-2023, STMicroelectronics - All Rights Reserved* diff --git a/docs/plat/synquacer.rst b/docs/plat/synquacer.rst new file mode 100644 index 0000000..dd29d29 --- /dev/null +++ b/docs/plat/synquacer.rst @@ -0,0 +1,117 @@ +Socionext Synquacer +=================== + +Socionext's Synquacer SC2A11 is a multi-core processor with 24 cores of Arm +Cortex-A53. The Developerbox, of 96boards, is a platform that contains this +processor. This port of the Trusted Firmware only supports this platform at +the moment. + +More information are listed in `link`_. + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- edk2: + `link <https://github.com/tianocore/edk2>`__ + +- edk2-platforms: + `link <https://github.com/tianocore/edk2-platforms>`__ + +- edk2-non-osi: + `link <https://github.com/tianocore/edk2-non-osi>`__ + +Boot Flow +~~~~~~~~~ + +SCP firmware --> TF-A BL31 --> UEFI(edk2) + +Build Procedure +~~~~~~~~~~~~~~~ + +- Firstly, in addition to the “normal” build tools you will also need a + few specialist tools. On a Debian or Ubuntu operating system try: + + .. code:: shell + + sudo apt install acpica-tools device-tree-compiler uuid-dev + +- Secondly, create a new working directory and store the absolute path to this + directory in an environment variable, WORKSPACE. It does not matter where + this directory is created but as an example: + + .. code:: shell + + export WORKSPACE=$HOME/build/developerbox-firmware + mkdir -p $WORKSPACE + +- Run the following commands to clone the source code: + + .. code:: shell + + cd $WORKSPACE + git clone https://github.com/ARM-software/arm-trusted-firmware -b master + git clone https://github.com/tianocore/edk2.git -b master + git clone https://github.com/tianocore/edk2-platforms.git -b master + git clone https://github.com/tianocore/edk2-non-osi.git -b master + +- Build ATF: + + .. code:: shell + + cd $WORKSPACE/arm-trusted-firmware + make -j`nproc` PLAT=synquacer PRELOADED_BL33_BASE=0x8200000 bl31 fiptool + tools/fiptool/fiptool create \ + --tb-fw ./build/synquacer/release/bl31.bin \ + --soc-fw ./build/synquacer/release/bl31.bin \ + --scp-fw ./build/synquacer/release/bl31.bin \ + ../edk2-non-osi/Platform/Socionext/DeveloperBox/fip_all_arm_tf.bin + +- Build EDK2: + + .. code:: shell + + cd $WORKSPACE + export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms:$WORKSPACE/edk2-non-osi + export ACTIVE_PLATFORM="Platform/Socionext/DeveloperBox/DeveloperBox.dsc" + export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- + unset ARCH + + . edk2/edksetup.sh + make -C edk2/BaseTools + + build -p $ACTIVE_PLATFORM -b RELEASE -a AARCH64 -t GCC5 -n `nproc` -D DO_X86EMU=TRUE + +- The firmware image, which comprises the option ROM, ARM trusted firmware and + EDK2 itself, can be found $WORKSPACE/../Build/DeveloperBox/RELEASE_GCC5/FV/. + Use SYNQUACERFIRMWAREUPDATECAPSULEFMPPKCS7.Cap for UEFI capsule update and + SPI_NOR_IMAGE.fd for the serial flasher. + + Note #1: -t GCC5 can be loosely translated as “enable link-time-optimization”; + any version of gcc >= 5 will support this feature and may be used to build EDK2. + + Note #2: Replace -b RELEASE with -b DEBUG to build a debug. + +Install the System Firmware +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Providing your Developerbox is fully working and has on operating system + installed then you can adopt your the newly compiled system firmware using + the capsule update method:. + + .. code:: shell + + sudo apt install fwupdate + sudo fwupdate --apply {50b94ce5-8b63-4849-8af4-ea479356f0e3} \ + SYNQUACERFIRMWAREUPDATECAPSULEFMPPKCS7.Cap + sudo reboot + +- Alternatively you can install SPI_NOR_IMAGE.fd using the `board recovery method`_. + +.. _link: https://www.96boards.org/product/developerbox/ +.. _board recovery method: https://www.96boards.org/documentation/enterprise/developerbox/installation/board-recovery.md.html diff --git a/docs/plat/ti-k3.rst b/docs/plat/ti-k3.rst new file mode 100644 index 0000000..4843227 --- /dev/null +++ b/docs/plat/ti-k3.rst @@ -0,0 +1,57 @@ +Texas Instruments K3 +==================== + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Texas Instruments K3 SoCs. + +Boot Flow +--------- + +:: + + R5(U-Boot) --> TF-A BL31 --> BL32(OP-TEE) --> TF-A BL31 --> BL33(U-Boot) --> Linux + \ + Optional direct to Linux boot + \ + --> BL33(Linux) + +Texas Instruments K3 SoCs contain an R5 processor used as the boot master, it +loads the needed images for A53 startup, because of this we do not need BL1 or +BL2 TF-A stages. + +Build Instructions +------------------ + +https://github.com/ARM-software/arm-trusted-firmware.git + +TF-A: + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=k3 SPD=opteed all + +OP-TEE: + +.. code:: shell + + make ARCH=arm CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3 CFG_ARM64_core=y all + +R5 U-Boot: + +.. code:: shell + + make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- am65x_evm_r5_defconfig + make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- SYSFW=<path to SYSFW> + +A53 U-Boot: + +.. code:: shell + + make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- am65x_evm_a53_defconfig + make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- ATF=<path> TEE=<path> + +Deploy Images +------------- + +.. code:: shell + + cp tiboot3.bin tispl.bin u-boot.img /sdcard/boot/ diff --git a/docs/plat/warp7.rst b/docs/plat/warp7.rst new file mode 100644 index 0000000..f98a76f --- /dev/null +++ b/docs/plat/warp7.rst @@ -0,0 +1,210 @@ +NXP i.MX7 WaRP7 +=============== + +The Trusted Firmware-A port for the i.MX7Solo WaRP7 implements BL2 at EL3. +The i.MX7S contains a BootROM with a High Assurance Boot (HAB) functionality. +This functionality provides a mechanism for establishing a root-of-trust from +the reset vector to the command-line in user-space. + +Boot Flow +--------- + +BootROM --> TF-A BL2 --> BL32(OP-TEE) --> BL33(U-Boot) --> Linux + +In the WaRP7 port we encapsulate OP-TEE, DTB and U-Boot into a FIP. This FIP is +expected and required + +Build Instructions +------------------ + +We need to use a file generated by u-boot in order to generate a .imx image the +BootROM will boot. It is therefore _required_ to build u-boot before TF-A and +furthermore it is _recommended_ to use the mkimage in the u-boot/tools directory +to generate the TF-A .imx image. + +U-Boot +~~~~~~ + +https://git.linaro.org/landing-teams/working/mbl/u-boot.git + +.. code:: shell + + git checkout -b rms-atf-optee-uboot linaro-mbl/rms-atf-optee-uboot + make warp7_bl33_defconfig; + make u-boot.imx arch=ARM CROSS_COMPILE=arm-linux-gnueabihf- + +OP-TEE +~~~~~~ + +https://github.com/OP-TEE/optee_os.git + +.. code:: shell + + make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- PLATFORM=imx PLATFORM_FLAVOR=mx7swarp7 ARCH=arm CFG_PAGEABLE_ADDR=0 CFG_DT_ADDR=0x83000000 CFG_NS_ENTRY_ADDR=0x87800000 + +TF-A +~~~~ + +https://github.com/ARM-software/arm-trusted-firmware.git + +The following commands assume that a directory exits in the top-level TFA build +directory "fiptool_images". "fiptool_images" contains + +- u-boot.bin + The binary output from the u-boot instructions above + +- tee-header_v2.bin +- tee-pager_v2.bin +- tee-pageable_v2.bin + Binary outputs from the previous OPTEE build steps + +It is also assumed copy of mbedtls is available on the path path ../mbedtls + https://github.com/ARMmbed/mbedtls.git + At the time of writing HEAD points to 0592ea772aee48ca1e6d9eb84eca8e143033d973 + +.. code:: shell + + mkdir fiptool_images + cp /path/to/optee/out/arm-plat-imx/core/tee-header_v2.bin fiptool_images + cp /path/to/optee/out/arm-plat-imx/core/tee-pager_v2.bin fiptool_images + cp /path/to/optee/out/arm-plat-imx/core/tee-pageable_v2.bin fiptool_images + + make CROSS_COMPILE=${CROSS_COMPILE} PLAT=warp7 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + ARM_CORTEX_A7=yes AARCH32_SP=optee PLAT_WARP7_UART=1 GENERATE_COT=1 \ + TRUSTED_BOARD_BOOT=1 USE_TBBR_DEFS=1 MBEDTLS_DIR=../mbedtls \ + NEED_BL32=yes BL32=fiptool_images/tee-header_v2.bin \ + BL32_EXTRA1=fiptool_images/tee-pager_v2.bin \ + BL32_EXTRA2=fiptool_images/tee-pageable_v2.bin \ + BL33=fiptool_images/u-boot.bin certificates all + + /path/to/u-boot/tools/mkimage -n /path/to/u-boot/u-boot.cfgout -T imximage -e 0x9df00000 -d ./build/warp7/debug/bl2.bin ./build/warp7/debug/bl2.bin.imx + +FIP +~~~ + +.. code:: shell + + cp /path/to/uboot/u-boot.bin fiptool_images + cp /path/to/linux/arch/boot/dts/imx7s-warp.dtb fiptool_images + + tools/cert_create/cert_create -n --rot-key "build/warp7/debug/rot_key.pem" \ + --tfw-nvctr 0 \ + --ntfw-nvctr 0 \ + --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \ + --tb-fw=build/warp7/debug/bl2.bin \ + --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt\ + --tos-fw fiptool_images/tee-header_v2.bin \ + --tos-fw-cert fiptool_images/tee-header_v2.bin.crt \ + --tos-fw-key-cert fiptool_images/tee-header_v2.bin.key-crt \ + --tos-fw-extra1 fiptool_images/tee-pager_v2.bin \ + --tos-fw-extra2 fiptool_images/tee-pageable_v2.bin \ + --nt-fw fiptool_images/u-boot.bin \ + --nt-fw-cert fiptool_images/u-boot.bin.crt \ + --nt-fw-key-cert fiptool_images/u-boot.bin.key-crt \ + --hw-config fiptool_images/imx7s-warp.dtb + + tools/fiptool/fiptool create --tos-fw fiptool_images/tee-header_v2.bin \ + --tos-fw-extra1 fiptool_images/tee-pager_v2.bin \ + --tos-fw-extra2 fiptool_images/tee-pageable_v2.bin \ + --nt-fw fiptool_images/u-boot.bin \ + --hw-config fiptool_images/imx7s-warp.dtb \ + --tos-fw-cert fiptool_images/tee-header_v2.bin.crt \ + --tos-fw-key-cert fiptool_images/tee-header_v2.bin.key-crt \ + --nt-fw-cert fiptool_images/u-boot.bin.crt \ + --nt-fw-key-cert fiptool_images/u-boot.bin.key-crt \ + --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \ + --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt warp7.fip + +Deploy Images +------------- + +First place the WaRP7 into UMS mode in u-boot this should produce an entry in +/dev like /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 + +.. code:: shell + + => ums 0 mmc 0 + +Next flash bl2.imx and warp7.fip + +bl2.imx is flashed @ 1024 bytes +warp7.fip is flash @ 1048576 bytes + +.. code:: shell + + sudo dd if=bl2.bin.imx of=/dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 bs=512 seek=2 conv=notrunc + # Offset is 1MB 1048576 => 1048576 / 512 = 2048 + sudo dd if=./warp7.fip of=/dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 bs=512 seek=2048 conv=notrunc + +Remember to umount the USB device pefore proceeding + +.. code:: shell + + sudo umount /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0* + + +Signing BL2 +----------- + +A further step is to sign BL2. + +The image_sign.sh and bl2_sign.csf files alluded to blow are available here. + +https://github.com/bryanodonoghue/atf-code-signing + +It is suggested you use this script plus the example CSF file in order to avoid +hard-coding data into your CSF files. + +Download both "image_sign.sh" and "bl2_sign.csf" to your +arm-trusted-firmware top-level directory. + +.. code:: shell + + #!/bin/bash + SIGN=image_sign.sh + TEMP=`pwd`/temp + BL2_CSF=bl2_sign.csf + BL2_IMX=bl2.bin.imx + CST_PATH=/path/to/cst-2.3.2 + CST_BIN=${CST_PATH}/linux64/cst + + #Remove temp + rm -rf ${TEMP} + mkdir ${TEMP} + + # Generate IMX header + /path/to/u-boot/tools/mkimage -n u-boot.cfgout.warp7 -T imximage -e 0x9df00000 -d ./build/warp7/debug/bl2.bin ./build/warp7/debug/bl2.bin.imx > ${TEMP}/${BL2_IMX}.log + + # Copy required items to $TEMP + cp build/warp7/debug/bl2.bin.imx ${TEMP} + cp ${CST_PATH}/keys/* ${TEMP} + cp ${CST_PATH}/crts/* ${TEMP} + cp ${BL2_CSF} ${TEMP} + + # Generate signed BL2 image + ./${SIGN} image_sign_mbl_binary ${TEMP} ${BL2_CSF} ${BL2_IMX} ${CST_BIN} + + # Copy signed BL2 to top-level directory + cp ${TEMP}/${BL2_IMX}-signed . + cp ${BL2_RECOVER_CSF} ${TEMP} + + +The resulting bl2.bin.imx-signed can replace bl2.bin.imx in the Deploy +Images section above, once done. + +Suggested flow for verifying. + +1. Followed all previous steps above and verify a non-secure ATF boot +2. Down the NXP Code Singing Tool +3. Generate keys +4. Program the fuses on your board +5. Replace bl2.bin.imx with bl2.bin.imx-signed +6. Verify inside u-boot that "hab_status" shows no events +7. Subsequently close your board. + +If you have HAB events @ step 6 - do not lock your board. + +To get a good over-view of generating keys and programming the fuses on the +board read "High Assurance Boot for Dummies" by Boundary Devices. + +https://boundarydevices.com/high-assurance-boot-hab-dummies/ diff --git a/docs/plat/xilinx-versal-net.rst b/docs/plat/xilinx-versal-net.rst new file mode 100644 index 0000000..1db7695 --- /dev/null +++ b/docs/plat/xilinx-versal-net.rst @@ -0,0 +1,42 @@ +Xilinx Versal NET +================= + +Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal NET. +The platform only uses the runtime part of TF-A as Xilinx Versal NET already +has a BootROM (BL1) and PMC FW (BL2). + +BL31 is TF-A. +BL32 is an optional Secure Payload. +BL33 is the non-secure world software (U-Boot, Linux etc). + +To build: +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal_net bl31 +``` + +To build bl32 TSP you have to rebuild bl31 too +```bash +make CROSS_COMPILE=aarch64-none-elf- PLAT=versal_net SPD=tspd RESET_TO_BL31=1 bl31 bl32 +``` + +To build TF-A for JTAG DCC console: +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal_net VERSAL_NET_CONSOLE=dcc bl31 +``` + +Xilinx Versal NET platform specific build options +------------------------------------------------- + +* `VERSAL_NET_ATF_MEM_BASE`: Specifies the base address of the bl31 binary. +* `VERSAL_NET_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary. +* `VERSAL_NET_BL32_MEM_BASE`: Specifies the base address of the bl32 binary. +* `VERSAL_NET_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary. + +* `VERSAL_NET_CONSOLE`: Select the console driver. Options: + - `pl011`, `pl011_0`: ARM pl011 UART 0 (default) + - `pl011_1` : ARM pl011 UART 1 + - `dcc` : JTAG Debug Communication Channel(DCC) + +* `TFA_NO_PM` : Platform Management support. + - 0 : Enable Platform Management (Default) + - 1 : Disable Platform Management diff --git a/docs/plat/xilinx-versal.rst b/docs/plat/xilinx-versal.rst new file mode 100644 index 0000000..b71776d --- /dev/null +++ b/docs/plat/xilinx-versal.rst @@ -0,0 +1,60 @@ +Xilinx Versal +============= + +Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal. +The platform only uses the runtime part of TF-A as Xilinx Versal already has a +BootROM (BL1) and PMC FW (BL2). + +BL31 is TF-A. +BL32 is an optional Secure Payload. +BL33 is the non-secure world software (U-Boot, Linux etc). + +To build: +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 +``` + +To build ATF for different platform (supported are "silicon"(default) and "versal_virt") +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal VERSAL_PLATFORM=versal_virt bl31 +``` + +To build bl32 TSP you have to rebuild bl31 too +```bash +make CROSS_COMPILE=aarch64-none-elf- PLAT=versal SPD=tspd RESET_TO_BL31=1 bl31 bl32 +``` + +To build TF-A for JTAG DCC console +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 VERSAL_CONSOLE=dcc +``` + +To build TF-A with Straight-Line Speculation(SLS) +```bash +make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 HARDEN_SLS_ALL=1 +``` + +Xilinx Versal platform specific build options +--------------------------------------------- + +* `VERSAL_ATF_MEM_BASE`: Specifies the base address of the bl31 binary. +* `VERSAL_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary. +* `VERSAL_BL32_MEM_BASE`: Specifies the base address of the bl32 binary. +* `VERSAL_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary. + +* `VERSAL_CONSOLE`: Select the console driver. Options: + - `pl011`, `pl011_0`: ARM pl011 UART 0 + - `pl011_1` : ARM pl011 UART 1 + +* `VERSAL_PLATFORM`: Select the platform. Options: + - `versal_virt` : Versal Virtual platform + - `spp_itr6` : SPP ITR6 + - `emu_itr6` : EMU ITR6 + +# PLM->TF-A Parameter Passing +------------------------------ +The PLM populates a data structure with image information for the TF-A. The TF-A +uses that data to hand off to the loaded images. The address of the handoff +data structure is passed in the ```PMC_GLOBAL_GLOB_GEN_STORAGE4``` register. +The register is free to be used by other software once the TF-A is bringing up +further firmware images. diff --git a/docs/plat/xilinx-zynqmp.rst b/docs/plat/xilinx-zynqmp.rst new file mode 100644 index 0000000..4fe0d2f --- /dev/null +++ b/docs/plat/xilinx-zynqmp.rst @@ -0,0 +1,168 @@ +Xilinx Zynq UltraScale+ MPSoC +============================= + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq +UltraScale + MPSoC. +The platform only uses the runtime part of TF-A as ZynqMP already has a +BootROM (BL1) and FSBL (BL2). + +BL31 is TF-A. +BL32 is an optional Secure Payload. +BL33 is the non-secure world software (U-Boot, Linux etc). + +To build: + +.. code:: bash + + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 bl31 + +To build bl32 TSP you have to rebuild bl31 too: + +.. code:: bash + + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd RESET_TO_BL31=1 bl31 bl32 + +To build TF-A for JTAG DCC console: + +.. code:: bash + + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 bl31 ZYNQMP_CONSOLE=dcc + +ZynqMP platform specific build options +-------------------------------------- + +- ``XILINX_OF_BOARD_DTB_ADDR`` : Specifies the base address of Device tree. +- ``ZYNQMP_ATF_MEM_BASE``: Specifies the base address of the bl31 binary. +- ``ZYNQMP_ATF_MEM_SIZE``: Specifies the size of the memory region of the bl31 binary. +- ``ZYNQMP_BL32_MEM_BASE``: Specifies the base address of the bl32 binary. +- ``ZYNQMP_BL32_MEM_SIZE``: Specifies the size of the memory region of the bl32 binary. + +- ``ZYNQMP_CONSOLE``: Select the console driver. Options: + + - ``cadence``, ``cadence0``: Cadence UART 0 + - ``cadence1`` : Cadence UART 1 + +ZynqMP Debug behavior +--------------------- + +With DEBUG=1, TF-A for ZynqMP uses DDR memory range instead of OCM memory range +due to size constraints. +For DEBUG=1 configuration for ZynqMP the BL31_BASE is set to the DDR location +of 0x1000 and BL31_LIMIT is set to DDR location of 0x7FFFF. By default the +above memory range will NOT be reserved in device tree. + +To reserve the above memory range in device tree, the device tree base address +must be provided during build as, + +make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 DEBUG=1 \ + XILINX_OF_BOARD_DTB_ADDR=<DTB address> bl31 + +The default DTB base address for ZynqMP platform is 0x100000. This default value +is not set in the code and to use this default address, user still needs to +provide it through the build command as above. + +If the user wants to move the bl31 to a different DDR location, user can provide +the DDR address location using the build time parameters ZYNQMP_ATF_MEM_BASE and +ZYNQMP_ATF_MEM_SIZE. + +The DDR address must be reserved in the DTB by the user, either by manually +adding the reserved memory node, in the device tree, with the required address +range OR let TF-A modify the device tree on the run. + +To let TF-A access and modify the device tree, the DTB address must be provided +to the build command as follows, + +make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 DEBUG=1 \ + ZYNQMP_ATF_MEM_BASE=<DDR address> ZYNQMP_ATF_MEM_SIZE=<size> \ + XILINX_OF_BOARD_DTB_ADDR=<DTB address> bl31 + +DDR Address Range Usage +----------------------- + +When FSBL runs on RPU and TF-A is to be placed in DDR address range, +then the user needs to make sure that the DDR address is beyond 256KB. +In the RPU view, the first 256 KB is TCM memory. + +For this use case, with the minimum base address in DDR for TF-A, +the build command example is; + +make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 DEBUG=1 \ + ZYNQMP_ATF_MEM_BASE=0x40000 ZYNQMP_ATF_MEM_SIZE=<size> + +Configurable Stack Size +----------------------- + +The stack size in TF-A for ZynqMP platform is configurable. +The custom package can define the desired stack size as per the requirement in +the make file as follows, + +PLATFORM_STACK_SIZE := <value> +$(eval $(call add_define,PLATFORM_STACK_SIZE)) + +FSBL->TF-A Parameter Passing +---------------------------- + +The FSBL populates a data structure with image information for TF-A. TF-A uses +that data to hand off to the loaded images. The address of the handoff data +structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The +register is free to be used by other software once TF-A has brought up +further firmware images. + +Power Domain Tree +----------------- + +The following power domain tree represents the power domain model used by TF-A +for ZynqMP: + +:: + + +-+ + |0| + +-+ + +-------+---+---+-------+ + | | | | + | | | | + v v v v + +-+ +-+ +-+ +-+ + |0| |1| |2| |3| + +-+ +-+ +-+ +-+ + +The 4 leaf power domains represent the individual A53 cores, while resources +common to the cluster are grouped in the power domain on the top. + +CUSTOM SIP service support +-------------------------- + +- Dedicated SMC FID ZYNQMP_SIP_SVC_CUSTOM(0x82002000)(32-bit)/ + (0xC2002000)(64-bit) to be used by a custom package for + providing CUSTOM SIP service. + +- by default platform provides bare minimum definition for + custom_smc_handler in this service. + +- to use this service, custom package should implement their + smc handler with the name custom_smc_handler. once custom package is + included in TF-A build, their definition of custom_smc_handler is + enabled. + +Custom package makefile fragment inclusion in TF-A build +-------------------------------------------------------- + +- custom package is not directly part of TF-A source. + +- <CUSTOM_PKG_PATH> is the location at which user clones a + custom package locally. + +- custom package needs to implement makefile fragment named + custom_pkg.mk so as to get included in TF-A build. + +- custom_pkg.mk specify all the rules to include custom package + specific header files, dependent libs, source files that are + supposed to be included in TF-A build. + +- when <CUSTOM_PKG_PATH> is specified in TF-A build command, + custom_pkg.mk is included from <CUSTOM_PKG_PATH> in TF-A build. + +- TF-A build command: + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 + bl31 CUSTOM_PKG_PATH=<...> |