diff options
Diffstat (limited to 'docs')
92 files changed, 5203 insertions, 3645 deletions
diff --git a/docs/acknowledgements.rst b/docs/about/acknowledgements.rst index 74b77ff16..dfc66c8f7 100644 --- a/docs/acknowledgements.rst +++ b/docs/about/acknowledgements.rst @@ -6,7 +6,8 @@ Contributor Acknowledgements specific contributors referred to in "Arm Limited and Contributors" copyright notices. As contributors are now encouraged to put their name or company name directly into the copyright notices, this file is not relevant for new - contributions. + contributions. See the :ref:`License` document for the correct template to + use for new contributions. - Linaro Limited - Marvell International Ltd. @@ -15,3 +16,7 @@ Contributor Acknowledgements - Socionext Inc. - STMicroelectronics - Xilinx, Inc. + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/about/contact.rst b/docs/about/contact.rst new file mode 100644 index 000000000..9cb25ef47 --- /dev/null +++ b/docs/about/contact.rst @@ -0,0 +1,47 @@ +Support & Contact +----------------- + +We welcome any feedback on |TF-A| and there are several methods for providing +it or for obtaining support. + +.. warning:: + If you think you have found a security vulnerability, please report this using + the process defined in the :ref:`Security Handling` document. + +Mailing Lists +^^^^^^^^^^^^^ + +Public mailing lists for TF-A and the wider Trusted Firmware project are +hosted on TrustedFirmware.org. The mailing lists can be used for general +enquiries, enhancement requests and issue reports, or to follow and participate +in technical or organizational discussions around the project. These discussions +include design proposals, advance notice of changes and upcoming events. + +The relevant lists for the TF-A project are: + +- `TF-A development`_ +- `TF-A-Tests development`_ + +You can see a `summary of all the lists`_ on the TrustedFirmware.org website. + +Issue Tracker +^^^^^^^^^^^^^ + +Specific issues may be raised using the `issue tracker`_ on the +TrustedFirmware.org website. Using this tracker makes it easy for the +maintainers to prioritise and respond to your ticket. + +Arm Licensees +^^^^^^^^^^^^^ + +Arm licensees have an additional support conduit - they may contact Arm directly +via their partner managers. + +.. _`issue tracker`: https://developer.trustedfirmware.org +.. _`TF-A development`: https://lists.trustedfirmware.org/pipermail/tf-a/ +.. _`TF-A-Tests development`: https://lists.trustedfirmware.org/pipermail/tf-a-tests/ +.. _`summary of all the lists`: https://lists.trustedfirmware.org + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/about/features.rst b/docs/about/features.rst new file mode 100644 index 000000000..3441c5ebe --- /dev/null +++ b/docs/about/features.rst @@ -0,0 +1,127 @@ +Feature Overview +================ + +This page provides an overview of the current |TF-A| feature set. For a full +description of these features and their implementation details, please see +the documents that are part of the *Components* and *System Design* chapters. + +The :ref:`Change Log & Release Notes` provides details of changes made since the +last release. + +Current features +---------------- + +- Initialization of the secure world, for example exception vectors, control + registers and interrupts for the platform. + +- Library support for CPU specific reset and power down sequences. This + includes support for errata workarounds and the latest Arm DynamIQ CPUs. + +- Drivers to enable standard initialization of Arm System IP, for example + Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI), + Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone + Controller (TZC). + +- A generic |SCMI| driver to interface with conforming power controllers, for + example the Arm System Control Processor (SCP). + +- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling + Convention`_ using an EL3 runtime services framework. + +- |PSCI| library support for CPU, cluster and system power management + use-cases. + This library is pre-integrated with the AArch64 EL3 Runtime Software, and + is also suitable for integration with other AArch32 EL3 Runtime Software, + for example an AArch32 Secure OS. + +- A minimal AArch32 Secure Payload (*SP_MIN*) to demonstrate |PSCI| library + integration with AArch32 EL3 Runtime Software. + +- Secure Monitor library code such as world switching, EL1 context management + and interrupt routing. + When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the + AArch64 EL3 Runtime Software must be integrated with a Secure Payload + Dispatcher (SPD) component to customize the interaction with the SP. + +- A Test SP and SPD to demonstrate AArch64 Secure Monitor functionality and SP + interaction with PSCI. + +- SPDs for the `OP-TEE Secure OS`_, `NVIDIA Trusted Little Kernel`_ + and `Trusty Secure OS`_. + +- A Trusted Board Boot implementation, conforming to all mandatory TBBR + requirements. This includes image authentication, Firmware Update (or + recovery mode), and packaging of the various firmware images into a + Firmware Image Package (FIP). + +- Pre-integration of TBB with the Arm CryptoCell product, to take advantage of + its hardware Root of Trust and crypto acceleration services. + +- Reliability, Availability, and Serviceability (RAS) functionality, including + + - A Secure Partition Manager (SPM) to manage Secure Partitions in + Secure-EL0, which can be used to implement simple management and + security services. + + - An |SDEI| dispatcher to route interrupt-based |SDEI| events. + + - An Exception Handling Framework (EHF) that allows dispatching of EL3 + interrupts to their registered handlers, to facilitate firmware-first + error handling. + +- A dynamic configuration framework that enables each of the firmware images + to be configured at runtime if required by the platform. It also enables + loading of a hardware configuration (for example, a kernel device tree) + as part of the FIP, to be passed through the firmware stages. + +- Support for alternative boot flows, for example to support platforms where + the EL3 Runtime Software is loaded using other firmware or a separate + secure system processor, or where a non-TF-A ROM expects BL2 to be loaded + at EL3. + +- Support for the GCC, LLVM and Arm Compiler 6 toolchains. + +- Support for combining several libraries into a "romlib" image that may be + shared across images to reduce memory footprint. The romlib image is stored + in ROM but is accessed through a jump-table that may be stored + in read-write memory, allowing for the library code to be patched. + +- A prototype implementation of a Secure Partition Manager (SPM) that is based + on the SPCI Alpha 1 and SPRT draft specifications. + +- Support for ARMv8.3 pointer authentication in the normal and secure worlds. + The use of pointer authentication in the normal world is enabled whenever + architectural support is available, without the need for additional build + flags. Use of pointer authentication in the secure world remains an + experimental configuration at this time and requires the + ``BRANCH_PROTECTION`` option to be set to non-zero. + +- Position-Independent Executable (PIE) support. Initially for BL31 only, with + further support to be added in a future release. + +Still to come +------------- + +- Support for additional platforms. + +- Refinements to Position Independent Executable (PIE) support. + +- Continued support for the draft SPCI specification, to enable the use of + secure partition management in the secure world. + +- Documentation enhancements. + +- Ongoing support for new architectural features, CPUs and System IP. + +- Ongoing support for new Arm system architecture specifications. + +- Ongoing security hardening, optimization and quality improvements. + +.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os +.. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary +.. _Trusty Secure OS: https://source.android.com/security/trusty + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/about/index.rst b/docs/about/index.rst new file mode 100644 index 000000000..3a102668c --- /dev/null +++ b/docs/about/index.rst @@ -0,0 +1,13 @@ +About +===== + +.. toctree:: + :maxdepth: 1 + :caption: Contents + :numbered: + + features + release-information + maintainers + contact + acknowledgements diff --git a/docs/maintainers.rst b/docs/about/maintainers.rst index cbfc652fb..d9d7f84fd 100644 --- a/docs/maintainers.rst +++ b/docs/about/maintainers.rst @@ -17,10 +17,18 @@ Main maintainers :G: `sandrine-bailleux-arm`_ :M: Alexei Fedorov <alexei.fedorov@arm.com> :G: `AlexeiFedorov`_ -:M: Paul Beesley <paul.beesley@arm.com> -:G: `pbeesley-arm`_ -:M: John Tsichritzis <john.tsichritzis@arm.com> -:G: `jts-arm`_ +:M: György Szing <gyorgy.szing@arm.com> +:G: `gyuri-szing`_ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:M: Mark Dykes <mark.dykes@arm.com> +:G: `mardyk01`_ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:M: Bipin Ravi <bipin.ravi@arm.com> +:G: `bipinravi-arm`_ +:M: Joanna Farley <joanna.farley@arm.com> +:G: `joannafarley-arm`_ Allwinner ARMv8 platform port ----------------------------- @@ -37,16 +45,24 @@ Amlogic Meson S905 (GXBB) platform port :M: Andre Przywara <andre.przywara@arm.com> :G: `Andre-ARM`_ :F: docs/plat/meson-gxbb.rst -:F: drivers/meson/ -:F: plat/meson/gxbb/ +:F: drivers/amlogic/ +:F: plat/amlogic/gxbb/ Amlogic Meson S905x (GXL) platform port --------------------------------------- :M: Remi Pommarel <repk@triplefau.lt> :G: `remi-triplefault`_ :F: docs/plat/meson-gxl.rst -:F: drivers/meson/gxl -:F: plat/meson/gxl/ +:F: drivers/amlogic/gxl +:F: plat/amlogic/gxl/ + +Amlogic Meson S905X2 (G12A) platform port +----------------------------------------- +:M: Carlo Caione <ccaione@baylibre.com> +:G: `carlocaione`_ +:F: docs/plat/meson-g12a.rst +:F: drivers/amlogic/g12a +:F: plat/amlogic/g12a/ Armv7-A architecture port ------------------------- @@ -114,7 +130,7 @@ Intel SocFPGA platform ports :M: Tien Hock Loh <tien.hock.loh@intel.com> :G: `thloh85-intel`_ :M: Hadi Asyrafi <muhammad.hadi.asyrafi.abdul.halim@intel.com> -:G: `mabdulha`_ +:G: mabdulha :F: plat/intel/soc :F: drivers/intel/soc/ @@ -274,14 +290,15 @@ Xilinx platform port .. _Anson-Huang: https://github.com/Anson-Huang .. _bryanodonoghue: https://github.com/bryanodonoghue .. _b49020: https://github.com/b49020 +.. _carlocaione: https://github.com/carlocaione .. _danh-arm: https://github.com/danh-arm .. _etienne-lms: https://github.com/etienne-lms .. _glneo: https://github.com/glneo .. _grandpaul: https://github.com/grandpaul +.. _gyuri-szing: https://github.com/gyuri-szing .. _hzhuang1: https://github.com/hzhuang1 .. _JackyBai: https://github.com/JackyBai .. _jenswi-linaro: https://github.com/jenswi-linaro -.. _jts-arm: https://github.com/jts-arm .. _jwerner-chromium: https://github.com/jwerner-chromium .. _kostapr: https://github.com/kostapr .. _ldts: https://github.com/ldts @@ -291,7 +308,6 @@ Xilinx platform port .. _mtk09422: https://github.com/mtk09422 .. _niej: https://github.com/niej .. _npoushin: https://github.com/npoushin -.. _pbeesley-arm: https://github.com/pbeesley-arm .. _qoriq-open-source: https://github.com/qoriq-open-source .. _remi-triplefault: https://github.com/repk .. _rockchip-linux: https://github.com/rockchip-linux @@ -300,7 +316,13 @@ Xilinx platform port .. _sivadur: https://github.com/sivadur .. _smaeul: https://github.com/smaeul .. _soby-mathew: https://github.com/soby-mathew +.. _thloh85-intel: https://github.com/thloh85-intel .. _thomas-arm: https://github.com/thomas-arm .. _TonyXie06: https://github.com/TonyXie06 .. _vwadekar: https://github.com/vwadekar .. _Yann-lms: https://github.com/Yann-lms +.. _manish-pandey-arm: https://github.com/manish-pandey-arm +.. _mardyk01: https://github.com/mardyk01 +.. _odeprez: https://github.com/odeprez +.. _bipinravi-arm: https://github.com/bipinravi-arm +.. _joannafarley-arm: https://github.com/joannafarley-arm diff --git a/docs/about/release-information.rst b/docs/about/release-information.rst new file mode 100644 index 000000000..c230e605d --- /dev/null +++ b/docs/about/release-information.rst @@ -0,0 +1,68 @@ +Release Processes +================= + +Project Release Cadence +----------------------- + +The project currently aims to do a release once every 6 months which will be +tagged on the master branch. There will be a code freeze (stop merging +non-essential changes) up to 4 weeks prior to the target release date. The release +candidates will start appearing after this and only bug fixes or updates +required for the release will be merged. The maintainers are free to use their +judgement on what changes are essential for the release. A release branch may be +created after code freeze if there are significant changes that need merging onto +the integration branch during the merge window. + +The release testing will be performed on release candidates and depending on +issues found, additional release candidates may be created to fix the issues. + +:: + + |<----------6 months---------->| + |<---4 weeks--->| |<---4 weeks--->| + +-----------------------------------------------------------> time + | | | | + code freeze ver w.x code freeze ver y.z + + +Upcoming Releases +~~~~~~~~~~~~~~~~~ + +These are the estimated dates for the upcoming release. These may change +depending on project requirement and partner feedback. + ++-----------------+---------------------------+------------------------------+ +| Release Version | Target Date | Expected Code Freeze | ++=================+===========================+==============================+ +| v2.0 | 1st week of Oct '18 | 1st week of Sep '18 | ++-----------------+---------------------------+------------------------------+ +| v2.1 | 5th week of Mar '19 | 1st week of Mar '19 | ++-----------------+---------------------------+------------------------------+ +| v2.2 | 4th week of Oct '19 | 1st week of Oct '19 | ++-----------------+---------------------------+------------------------------+ +| v2.3 | 4th week of Mar '20 | 1st week of Mar '20 | ++-----------------+---------------------------+------------------------------+ + +Removal of Deprecated Interfaces +-------------------------------- + +As mentioned in the :ref:`Platform Compatibility Policy`, this is a live +document cataloging all the deprecated interfaces in TF-A project and the +Release version after which it will be removed. + ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Interface | Deprecation | Removed | Comments | +| | Date | after | | +| | | Release | | ++================================+=============+=========+=========================================================+ +| ``AARCH32``/``AARCH64`` macros | Oct '19 | v2.3 | Deprecated in favor of ``__aarch64__`` | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| ``__ASSEMBLY__`` macro | Oct '19 | v2.3 | Deprecated in favor of ``__ASSEMBLER__`` | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Prototype SPCI-based SPM | Oct '19 | v2.2 | Based on outdated Alpha 1 spec. Will be replaced with | +| (services/std_svc/spm) | | | alternative methods of secure partitioning support. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ + +-------------- + +*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/change-log-upcoming.rst b/docs/change-log-upcoming.rst new file mode 100644 index 000000000..14280cbf7 --- /dev/null +++ b/docs/change-log-upcoming.rst @@ -0,0 +1,145 @@ +Change Log for Upcoming Release +=============================== + +This document contains a summary of the new features, changes, fixes and known +issues to be included in the upcoming release of Trusted Firmware-A. The contents +of this file will be moved to the collective change-log.rst file at the time of +release code freeze. + + +Upcoming Release Version 2.3 +---------------------------- + +**Trusted Firmware-A Contributors, +Please log all relevant new features, changes, fixes, and known issues for the +upcoming release. For the CPU support, drivers, and tools sections please preface +the log description with the relevant key word, example: "<CPU>: <CPU Support +addition>". Use the RST format convention already used in the Change Log.** + +New Features +^^^^^^^^^^^^ + +- Arm Architecture + - Example: "Add support for Branch Target Identification (BTI)" + +- Build System + - Add support for documentation build as a target in Makefile + +- CPU Support + - Example: "cortex-a55: Workaround for erratum 1221012" + +- Drivers + - Example: "console: Allow the console to register multiple times" + +- Libraries + - Example: "Introduce BTI support in Library at ROM (romlib)" + +- New Platforms Support + - Example: "qemu/qemu_sbsa: New platform support added for QEMU SBSA platform" + +- Platforms + - Example: "arm/common: Introduce wrapper functions to setup secure watchdog" + +- PSCI + - Example: "Adding new optional PSCI hook ``pwr_domain_on_finish_late``" + +- Security + - Example: "UBSAN support and handlers" + +- Tools + - Example: "fiptool: Add support to build fiptool on Windows." + + +Changed +^^^^^^^ + +- Arm Architecture + - Example: "Refactor ARMv8.3 Pointer Authentication support code" + +- BL-Specific + - Example: "BL2: Invalidate dcache build option for BL2 entry at EL3" + +- Boot Flow + - Example: "Add helper to parse BL31 parameters (both versions)" + +- Drivers + - Example: "gicv3: Prevent pending G1S interrupt from becoming G0 interrupt" + +- Platforms + - Example: "arm/common: Shorten the Firmware Update (FWU) process" + +- PSCI + - Example: "PSCI: Lookup list of parent nodes to lock only once" + +- Secure Partition Manager (SPM) + - Example: "Move shim layer to TTBR1_EL1" + +- Security + - Example: "Refactor SPSR initialisation code" + +- Tools + - Example: "cert_create: Remove RSA PKCS#1 v1.5 support" + + +Resolved Issues +^^^^^^^^^^^^^^^ + +- Arm Architecture + - Example: "Fix restoration of PAuth context" + +- BL-Specific + - Example: "Fix BL31 crash reporting on AArch64 only platforms" + +- Build System + - Example: "Remove several warnings reported with W=2 and W=1" + +- Code Quality + - Example: "Unify type of "cpu_idx" across PSCI module" + +- CPU Support + - Example: "cortex-a12: Fix MIDR mask" + +- Drivers + - Example: "scmi: Fix wrong payload length" + +- Library Code + - Example: "libc: Fix memchr implementation" + +- Platforms + - Example: "rpi: rpi3: Fix compilation error when stack protector is enabled" + +- Security + - Example: "AArch32: Disable Secure Cycle Counter" + +Deprecations +^^^^^^^^^^^^ + +- Common Code + - Example: "Remove MULTI_CONSOLE_API flag and references to it" + +- Drivers + - Example: "console: Remove deprecated finish_console_register" + +- Secure Partition Manager (SPM): + - Example: "Prototype SPCI-based SPM (services/std_svc/spm) will be replaced + with alternative methods of secure partitioning support." + +Known Issues +^^^^^^^^^^^^ + +- Build System + - dtb: DTB creation not supported when building on a Windows host. + + This step in the build process is skipped when running on a Windows host. A + known issue from the 1.6 release. + +- Platforms + - arm/juno: System suspend from Linux does not function as documented in the + user guide + + Following the instructions provided in the user guide document does not + result in the platform entering system suspend state as expected. A message + relating to the hdlcd driver failing to suspend will be emitted on the + Linux terminal. + + - mediatek/mt6795: This platform does not build in this release diff --git a/docs/change-log.rst b/docs/change-log.rst index 70aafc063..cf5b57ac6 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -4,6 +4,426 @@ Change Log & Release Notes This document contains a summary of the new features, changes, fixes and known issues in each release of Trusted Firmware-A. +Version 2.2 +----------- + +New Features +^^^^^^^^^^^^ + +- Architecture + - Enable Pointer Authentication (PAuth) support for Secure World + - Adds support for ARMv8.3-PAuth in BL1 SMC calls and + BL2U image for firmware updates. + + - Enable Memory Tagging Extension (MTE) support in both secure and non-secure + worlds + - Adds support for the new Memory Tagging Extension arriving in + ARMv8.5. MTE support is now enabled by default on systems that + support it at EL0. + - To enable it at ELx for both the non-secure and the secure + world, the compiler flag ``CTX_INCLUDE_MTE_REGS`` includes register + saving and restoring when necessary in order to prevent information + leakage between the worlds. + + - Add support for Branch Target Identification (BTI) + +- Build System + - Modify FVP makefile for CPUs that support both AArch64/32 + + - AArch32: Allow compiling with soft-float toolchain + + - Makefile: Add default warning flags + + - Add Makefile check for PAuth and AArch64 + + - Add compile-time errors for HW_ASSISTED_COHERENCY flag + + - Apply compile-time check for AArch64-only CPUs + + - build_macros: Add mechanism to prevent bin generation. + + - Add support for default stack-protector flag + + - spd: opteed: Enable NS_TIMER_SWITCH + + - plat/arm: Skip BL2U if RESET_TO_SP_MIN flag is set + + - Add new build option to let each platform select which implementation of spinlocks + it wants to use + +- CPU Support + - DSU: Workaround for erratum 798953 and 936184 + + - Neoverse N1: Force cacheable atomic to near atomic + - Neoverse N1: Workaround for erratum 1073348, 1130799, 1165347, 1207823, + 1220197, 1257314, 1262606, 1262888, 1275112, 1315703, 1542419 + + - Neoverse Zeus: Apply the MSR SSBS instruction + + - cortex-Hercules/HerculesAE: Support added for Cortex-Hercules and + Cortex-HerculesAE CPUs + - cortex-Hercules/HerculesAE: Enable AMU for Cortex-Hercules and Cortex-HerculesAE + + - cortex-a76AE: Support added for Cortex-A76AE CPU + - cortex-a76: Workaround for erratum 1257314, 1262606, 1262888, 1275112, + 1286807 + + - cortex-a65/a65AE: Support added for Cortex-A65 and Cortex-A65AE CPUs + - cortex-a65: Enable AMU for Cortex-A65 + + - cortex-a55: Workaround for erratum 1221012 + + - cortex-a35: Workaround for erratum 855472 + + - cortex-a9: Workaround for erratum 794073 + +- Drivers + - console: Allow the console to register multiple times + + - delay: Timeout detection support + + - gicv3: Enabled multi-socket GIC redistributor frame discovery and migrated + ARM platforms to the new API + - Adds ``gicv3_rdistif_probe`` function that delegates the responsibility + of discovering the corresponding redistributor base frame to each CPU + itself. + + - sbsa: Add SBSA watchdog driver + + - st/stm32_hash: Add HASH driver + + - ti/uart: Add an AArch32 variant + +- Library at ROM (romlib) + - Introduce BTI support in Library at ROM (romlib) + +- New Platforms Support + - amlogic: g12a: New platform support added for the S905X2 (G12A) platform + - amlogic: meson/gxl: New platform support added for Amlogic Meson + S905x (GXL) + + - arm/a5ds: New platform support added for A5 DesignStart + + - arm/corstone: New platform support added for Corstone-700 + + - intel: New platform support added for Agilex + + - mediatek: New platform support added for MediaTek mt8183 + + - qemu/qemu_sbsa: New platform support added for QEMU SBSA platform + + - renesas/rcar_gen3: plat: New platform support added for D3 + + - rockchip: New platform support added for px30 + - rockchip: New platform support added for rk3288 + + - rpi: New platform support added for Raspberry Pi 4 + +- Platforms + - arm/common: Introduce wrapper functions to setup secure watchdog + + - arm/fvp: Add Delay Timer driver to BL1 and BL31 and option for defining + platform DRAM2 base + - arm/fvp: Add Linux DTS files for 32 bit threaded FVPs + + - arm/n1sdp: Add code for DDR ECC enablement and BL33 copy to DDR, Initialise CNTFRQ + in Non Secure CNTBaseN + + - arm/juno: Use shared mbedtls heap between BL1 and BL2 and add basic support for + dynamic config + + - imx: Basic support for PicoPi iMX7D, rdc module init, caam module init, + aipstz init, IMX_SIP_GET_SOC_INFO, IMX_SIP_BUILDINFO added + + - intel: Add ncore ccu driver + + - mediatek/mt81*: Use new bl31_params_parse() helper + + - nvidia: tegra: Add support for multi console interface + + - qemu/qemu_sbsa: Adding memory mapping for both FLASH0/FLASH1 + - qemu: Added gicv3 support, new console interface in AArch32, and sub-platforms + + - renesas/rcar_gen3: plat: Add R-Car V3M support, new board revision for H3ULCB, DBSC4 + setting before self-refresh mode + + - socionext/uniphier: Support console based on multi-console + + - st: stm32mp1: Add OP-TEE, Avenger96, watchdog, LpDDR3, authentication support + and general SYSCFG management + + - ti/k3: common: Add support for J721E, Use coherent memory for shared data, Trap all + asynchronous bus errors to EL3 + + - xilinx/zynqmp: Add support for multi console interface, Initialize IPI table from + zynqmp_config_setup() + +- PSCI + - Adding new optional PSCI hook ``pwr_domain_on_finish_late`` + - This PSCI hook ``pwr_domain_on_finish_late`` is similar to + ``pwr_domain_on_finish`` but is guaranteed to be invoked when the + respective core and cluster are participating in coherency. + +- Security + - Speculative Store Bypass Safe (SSBS): Further enhance protection against Spectre + variant 4 by disabling speculative loads/stores (SPSR.SSBS bit) by default. + + - UBSAN support and handlers + - Adds support for the Undefined Behaviour sanitizer. There are two types of + support offered - minimalistic trapping support which essentially immediately + crashes on undefined behaviour and full support with full debug messages. + +- Tools + - cert_create: Add support for bigger RSA key sizes (3KB and 4KB), + previously the maximum size was 2KB. + + - fiptool: Add support to build fiptool on Windows. + + +Changed +^^^^^^^ + +- Architecture + - Refactor ARMv8.3 Pointer Authentication support code + + - backtrace: Strip PAC field when PAUTH is enabled + + - Prettify crash reporting output on AArch64. + + - Rework smc_unknown return code path in smc_handler + - Leverage the existing ``el3_exit()`` return routine for smc_unknown return + path rather than a custom set of instructions. + +- BL-Specific + - Invalidate dcache build option for BL2 entry at EL3 + + - Add missing support for BL2_AT_EL3 in XIP memory + +- Boot Flow + - Add helper to parse BL31 parameters (both versions) + + - Factor out cross-BL API into export headers suitable for 3rd party code + + - Introduce lightweight BL platform parameter library + +- Drivers + - auth: Memory optimization for Chain of Trust (CoT) description + + - bsec: Move bsec_mode_is_closed_device() service to platform + + - cryptocell: Move Cryptocell specific API into driver + + - gicv3: Prevent pending G1S interrupt from becoming G0 interrupt + + - mbedtls: Remove weak heap implementation + + - mmc: Increase delay between ACMD41 retries + - mmc: stm32_sdmmc2: Correctly manage block size + - mmc: stm32_sdmmc2: Manage max-frequency property from DT + + - synopsys/emmc: Do not change FIFO TH as this breaks some platforms + - synopsys: Update synopsys drivers to not rely on undefined overflow behaviour + + - ufs: Extend the delay after reset to wait for some slower chips + +- Platforms + - amlogic/meson/gxl: Remove BL2 dependency from BL31 + + - arm/common: Shorten the Firmware Update (FWU) process + + - arm/fvp: Remove GIC initialisation from secondary core cold boot + + - arm/sgm: Temporarily disable shared Mbed TLS heap for SGM + + - hisilicon: Update hisilicon drivers to not rely on undefined overflow behaviour + + - imx: imx8: Replace PLAT_IMX8* with PLAT_imx8*, remove duplicated linker symbols and + deprecated code include, keep only IRQ 32 unmasked, enable all power domain by default + + - marvell: Prevent SError accessing PCIe link, Switch to xlat_tables_v2, do not rely on + argument passed via smc, make sure that comphy init will use correct address + + - mediatek: mt8173: Refactor RTC and PMIC drivers + - mediatek: mt8173: Apply MULTI_CONSOLE framework + + - nvidia: Tegra: memctrl_v2: fix "overflow before widen" coverity issue + + - qemu: Simplify the image size calculation, Move and generalise FDT PSCI fixup, move + gicv2 codes to separate file + + - renesas/rcar_gen3: Convert to multi-console API, update QoS setting, Update IPL and + Secure Monitor Rev2.0.4, Change to restore timer counter value at resume, Update DDR + setting rev.0.35, qos: change subslot cycle, Change periodic write DQ training option. + + - rockchip: Allow SOCs with undefined wfe check bits, Streamline and complete UARTn_BASE + macros, drop rockchip-specific imported linker symbols for bl31, Disable binary generation + for all SOCs, Allow console device to be set by DTB, Use new bl31_params_parse functions + + - rpi/rpi3: Move shared rpi3 files into common directory + + - socionext/uniphier: Set CONSOLE_FLAG_TRANSLATE_CRLF and clean up console driver + - socionext/uniphier: Replace DIV_ROUND_UP() with div_round_up() from utils_def.h + + - st/stm32mp: Split stm32mp_io_setup function, move stm32_get_gpio_bank_clock() to private + file, correctly handle Clock Spreading Generator, move oscillator functions to generic file, + realign device tree files with internal devs, enable RTCAPB clock for dual-core chips, use a + common function to check spinlock is available, move check_header() to common code + + - ti/k3: Enable SEPARATE_CODE_AND_RODATA by default, Remove shared RAM space, + Drop _ADDRESS from K3_USART_BASE to match other defines, Remove MSMC port + definitions, Allow USE_COHERENT_MEM for K3, Set L2 latency on A72 cores + +- PSCI + - PSCI: Lookup list of parent nodes to lock only once + +- Secure Partition Manager (SPM): SPCI Prototype + - Fix service UUID lookup + + - Adjust size of virtual address space per partition + + - Refactor xlat context creation + + - Move shim layer to TTBR1_EL1 + + - Ignore empty regions in resource description + +- Security + - Refactor SPSR initialisation code + + - SMMUv3: Abort DMA transactions + - For security DMA should be blocked at the SMMU by default unless explicitly + enabled for a device. SMMU is disabled after reset with all streams bypassing + the SMMU, and abortion of all incoming transactions implements a default deny + policy on reset. + - Moves ``bl1_platform_setup()`` function from arm_bl1_setup.c to FVP platforms' + fvp_bl1_setup.c and fvp_ve_bl1_setup.c files. + +- Tools + - cert_create: Remove RSA PKCS#1 v1.5 support + + +Resolved Issues +^^^^^^^^^^^^^^^ + +- Architecture + - Fix the CAS spinlock implementation by adding a missing DSB in ``spin_unlock()`` + + - AArch64: Fix SCTLR bit definitions + - Removes incorrect ``SCTLR_V_BIT`` definition and adds definitions for + ARMv8.3-Pauth `EnIB`, `EnDA` and `EnDB` bits. + + - Fix restoration of PAuth context + - Replace call to ``pauth_context_save()`` with ``pauth_context_restore()`` in + case of unknown SMC call. + +- BL-Specific Issues + - Fix BL31 crash reporting on AArch64 only platforms + +- Build System + - Remove several warnings reported with W=2 and W=1 + +- Code Quality Issues + - SCTLR and ACTLR are 32-bit for AArch32 and 64-bit for AArch64 + - Unify type of "cpu_idx" across PSCI module. + - Assert if power level value greater then PSCI_INVALID_PWR_LVL + - Unsigned long should not be used as per coding guidelines + - Reduce the number of memory leaks in cert_create + - Fix type of cot_desc_ptr + - Use explicit-width data types in AAPCS parameter structs + - Add python configuration for editorconfig + - BL1: Fix type consistency + + - Enable -Wshift-overflow=2 to check for undefined shift behavior + - Updated upstream platforms to not rely on undefined overflow behaviour + +- Coverity Quality Issues + - Remove GGC ignore -Warray-bounds + - Fix Coverity #261967, Infinite loop + - Fix Coverity #343017, Missing unlock + - Fix Coverity #343008, Side affect in assertion + - Fix Coverity #342970, Uninitialized scalar variable + +- CPU Support + - cortex-a12: Fix MIDR mask + +- Drivers + - console: Remove Arm console unregister on suspend + + - gicv3: Fix support for full SPI range + + - scmi: Fix wrong payload length + +- Library Code + - libc: Fix sparse warning for __assert() + + - libc: Fix memchr implementation + +- Platforms + - rpi: rpi3: Fix compilation error when stack protector is enabled + + - socionext/uniphier: Fix compilation fail for SPM support build config + + - st/stm32mp1: Fix TZC400 configuration against non-secure DDR + + - ti/k3: common: Fix RO data area size calculation + +- Security + - AArch32: Disable Secure Cycle Counter + - Changes the implementation for disabling Secure Cycle Counter. + For ARMv8.5 the counter gets disabled by setting ``SDCR.SCCD`` bit on + CPU cold/warm boot. For the earlier architectures PMCR register is + saved/restored on secure world entry/exit from/to Non-secure state, + and cycle counting gets disabled by setting PMCR.DP bit. + - AArch64: Disable Secure Cycle Counter + - For ARMv8.5 the counter gets disabled by setting ``MDCR_El3.SCCD`` bit on + CPU cold/warm boot. For the earlier architectures PMCR_EL0 register is + saved/restored on secure world entry/exit from/to Non-secure state, + and cycle counting gets disabled by setting PMCR_EL0.DP bit. + +Deprecations +^^^^^^^^^^^^ + +- Common Code + - Remove MULTI_CONSOLE_API flag and references to it + + - Remove deprecated `plat_crash_console_*` + + - Remove deprecated interfaces `get_afflvl_shift`, `mpidr_mask_lower_afflvls`, `eret` + + - AARCH32/AARCH64 macros are now deprecated in favor of ``__aarch64__`` + + - ``__ASSEMBLY__`` macro is now deprecated in favor of ``__ASSEMBLER__`` + +- Drivers + - console: Removed legacy console API + - console: Remove deprecated finish_console_register + + - tzc: Remove deprecated types `tzc_action_t` and `tzc_region_attributes_t` + +- Secure Partition Manager (SPM): + - Prototype SPCI-based SPM (services/std_svc/spm) will be replaced with alternative + methods of secure partitioning support. + +Known Issues +^^^^^^^^^^^^ + +- Build System Issues + - dtb: DTB creation not supported when building on a Windows host. + + This step in the build process is skipped when running on a Windows host. A + known issue from the 1.6 release. + +- Platform Issues + - arm/juno: System suspend from Linux does not function as documented in the + user guide + + Following the instructions provided in the user guide document does not + result in the platform entering system suspend state as expected. A message + relating to the hdlcd driver failing to suspend will be emitted on the + Linux terminal. + + - mediatek/mt6795: This platform does not build in this release + Version 2.1 ----------- @@ -22,8 +442,8 @@ New Features and ``CTX_INCLUDE_PAUTH_REGS`` build flags, pointer authentication can be enabled in EL3 and S-EL1/0. - See the `Firmware Design`_ document for additional details on the use of - pointer authentication. + See the :ref:`Firmware Design` document for additional details on the use + of pointer authentication. - Enable Data Independent Timing (DIT) in EL3, where supported @@ -1359,7 +1779,7 @@ New features The PSCI library has been refactored to allow integration with **EL3 Runtime Software**. This is software that is executing at the highest secure privilege which is EL3 in AArch64 or Secure SVC/Monitor mode in AArch32. See - `PSCI Integration Guide`_. + :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`. Included is a minimal AArch32 Secure Payload, **SP-MIN**, that illustrates the usage and integration of the PSCI library with EL3 Runtime Software @@ -1402,11 +1822,11 @@ New features Commits now must have a 'Signed-off-by:' field to certify that the contribution has been made under the terms of the - `Developer Certificate of Origin`_. + :download:`Developer Certificate of Origin <../dco.txt>`. A signed CLA is no longer required. - The `Contribution Guide`_ has been updated to reflect this change. + The :ref:`Contributor's Guide` has been updated to reflect this change. - Introduced Performance Measurement Framework (PMF) which provides support for capturing, storing, dumping and retrieving time-stamps to measure the @@ -1620,13 +2040,13 @@ New features - Added the following new design documents: - - `Authentication framework`_ - - `Firmware Update`_ - - `TF-A Reset Design`_ - - `Power Domain Topology Design`_ + - :ref:`Authentication Framework & Chain of Trust` + - :ref:`Firmware Update (FWU)` + - :ref:`CPU Reset` + - :ref:`PSCI Power Domain Tree Structure` - Applied the new image terminology to the code base and documentation, as - described in the `image terminology document`_. + described in the :ref:`Image Terminology` document. - The build system has been reworked to improve readability and facilitate adding future extensions. @@ -1694,7 +2114,8 @@ Issues resolved since last release ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The Trusted Board Boot implementation has been redesigned to provide greater - modularity and scalability. See the `Authentication Framework`_ document. + modularity and scalability. See the + :ref:`Authentication Framework & Chain of Trust` document. All missing mandatory features are now implemented. - The FVP and Juno ports may now use the hash of the ROTPK stored in the @@ -1826,7 +2247,7 @@ New features create mappings only for areas in the memory map that it needs. - A Secure Payload Dispatcher (OPTEED) for the OP-TEE Trusted OS has been - added. Details of using it with TF-A can be found in `OP-TEE Dispatcher`_ + added. Details of using it with TF-A can be found in :ref:`OP-TEE Dispatcher` Issues resolved since last release ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2423,16 +2844,6 @@ releases of TF-A. *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _PSCI Integration Guide: ./getting_started/psci-lib-integration-guide.rst -.. _Developer Certificate of Origin: ../dco.txt -.. _Contribution Guide: ./process/contributing.rst -.. _Authentication framework: ./design/auth-framework.rst -.. _Firmware Update: ./design/firmware-update.rst -.. _Firmware Design: ./design/firmware-design.rst -.. _TF-A Reset Design: ./design/reset-design.rst -.. _Power Domain Topology Design: ./design/psci-pd-tree.rst -.. _image terminology document: ./getting_started/image-terminology.rst -.. _Authentication Framework: ./design/auth-framework.rst -.. _OP-TEE Dispatcher: ./spd/optee-dispatcher.rst .. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501 .. _PR#1002: https://github.com/ARM-software/arm-trusted-firmware/pull/1002#issuecomment-312650193 +.. _mbed TLS releases: https://tls.mbed.org/tech-updates/releases diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst index e450d3756..01bc04d71 100644 --- a/docs/components/arm-sip-service.rst +++ b/docs/components/arm-sip-service.rst @@ -17,6 +17,7 @@ The Arm SiP implementation offers the following services: - Performance Measurement Framework (PMF) - Execution State Switching service +- DebugFS interface Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header file. @@ -24,9 +25,9 @@ file. Performance Measurement Framework (PMF) --------------------------------------- -The `Performance Measurement Framework`_ +The :ref:`Performance Measurement Framework <firmware_design_pmf>` allows callers to retrieve timestamps captured at various paths in TF-A -execution. It's described in detail in `Firmware Design document`_. +execution. Execution State Switching service --------------------------------- @@ -87,10 +88,348 @@ Instead, execution starts at the supplied entry point, with the CPU registers 0 and 1 populated with the supplied *Cookie hi* and *Cookie lo* values, respectively. +DebugFS interface +----------------- + +The optional DebugFS interface is accessed through an SMC SiP service. Refer +to the component documentation for details. + +String parameters are passed through a shared buffer using a specific union: + +.. code:: c + + union debugfs_parms { + struct { + char fname[MAX_PATH_LEN]; + } open; + + struct mount { + char srv[MAX_PATH_LEN]; + char where[MAX_PATH_LEN]; + char spec[MAX_PATH_LEN]; + } mount; + + struct { + char path[MAX_PATH_LEN]; + dir_t dir; + } stat; + + struct { + char oldpath[MAX_PATH_LEN]; + char newpath[MAX_PATH_LEN]; + } bind; + }; + +Format of the dir_t structure as such: + +.. code:: c + + typedef struct { + char name[NAMELEN]; + long length; + unsigned char mode; + unsigned char index; + unsigned char dev; + qid_t qid; + } dir_t; + + +* Identifiers + +======================== ============================================= +SMC_OK 0 +SMC_UNK -1 +DEBUGFS_E_INVALID_PARAMS -2 +======================== ============================================= + +======================== ============================================= +MOUNT 0 +CREATE 1 +OPEN 2 +CLOSE 3 +READ 4 +WRITE 5 +SEEK 6 +BIND 7 +STAT 8 +INIT 10 +VERSION 11 +======================== ============================================= + +MOUNT +~~~~~ + +Description +^^^^^^^^^^^ +This operation mounts a blob of data pointed to by path stored in `src`, at +filesystem location pointed to by path stored in `where`, using driver pointed +to by path in `spec`. + +Parameters +^^^^^^^^^^ +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``MOUNT`` +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if mount operation failed +=============== ========================================================== + +OPEN +~~~~ + +Description +^^^^^^^^^^^ +This operation opens the file path pointed to by `fname`. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``OPEN`` +uint32_t mode +======== ============================================================ + +mode can be one of: + +.. code:: c + + enum mode { + O_READ = 1 << 0, + O_WRITE = 1 << 1, + O_RDWR = 1 << 2, + O_BIND = 1 << 3, + O_DIR = 1 << 4, + O_STAT = 1 << 5 + }; + +Return values +^^^^^^^^^^^^^ + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if open operation failed + +uint32_t w1: file descriptor id on success. +=============== ========================================================== + +CLOSE +~~~~~ + +Description +^^^^^^^^^^^ + +This operation closes a file described by a file descriptor obtained by a +previous call to OPEN. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``CLOSE`` +uint32_t File descriptor id returned by OPEN +======== ============================================================ + +Return values +^^^^^^^^^^^^^ +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if close operation failed +=============== ========================================================== + +READ +~~~~ + +Description +^^^^^^^^^^^ + +This operation reads a number of bytes from a file descriptor obtained by +a previous call to OPEN. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``READ`` +uint32_t File descriptor id returned by OPEN +uint32_t Number of bytes to read +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +On success, the read data is retrieved from the shared buffer after the +operation. + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if read operation failed + +uint32_t w1: number of bytes read on success. +=============== ========================================================== + +SEEK +~~~~ + +Description +^^^^^^^^^^^ + +Move file pointer for file described by given `file descriptor` of given +`offset` related to `whence`. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``SEEK`` +uint32_t File descriptor id returned by OPEN +sint32_t offset in the file relative to whence +uint32_t whence +======== ============================================================ + +whence can be one of: + +========= ============================================================ +KSEEK_SET 0 +KSEEK_CUR 1 +KSEEK_END 2 +========= ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if seek operation failed +=============== ========================================================== + +BIND +~~~~ + +Description +^^^^^^^^^^^ + +Create a link from `oldpath` to `newpath`. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``BIND`` +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if bind operation failed +=============== ========================================================== + +STAT +~~~~ + +Description +^^^^^^^^^^^ + +Perform a stat operation on provided file `name` and returns the directory +entry statistics into `dir`. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``STAT`` +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ========================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if stat operation failed +=============== ========================================================== + +INIT +~~~~ + +Description +^^^^^^^^^^^ +Initial call to setup the shared exchange buffer. Notice if successful once, +subsequent calls fail after a first initialization. The caller maps the same +page frame in its virtual space and uses this buffer to exchange string +parameters with filesystem primitives. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``INIT`` +uint64_t Physical address of the shared buffer. +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ====================================================== +int32_t w0 == SMC_OK on success + + w0 == DEBUGFS_E_INVALID_PARAMS if already initialized, + or internal error occurred. +=============== ====================================================== + +VERSION +~~~~~~~ + +Description +^^^^^^^^^^^ +Returns the debugfs interface version if implemented in TF-A. + +Parameters +^^^^^^^^^^ + +======== ============================================================ +uint32_t FunctionID (0x82000030 / 0xC2000030) +uint32_t ``VERSION`` +======== ============================================================ + +Return values +^^^^^^^^^^^^^ + +=============== ====================================================== +int32_t w0 == SMC_OK on success + + w0 == SMC_UNK if interface is not implemented + +uint32_t w1: On success, debugfs interface version, 32 bits + value with major version number in upper 16 bits and + minor version in lower 16 bits. +=============== ====================================================== + +* CREATE(1) and WRITE (5) command identifiers are unimplemented and + return `SMC_UNK`. + -------------- -*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html -.. _Performance Measurement Framework: ../design/firmware-design.rst#user-content-performance-measurement-framework -.. _Firmware Design document: ../design/firmware-design.rst diff --git a/docs/components/debugfs-design.rst b/docs/components/debugfs-design.rst new file mode 100644 index 000000000..06916f3d9 --- /dev/null +++ b/docs/components/debugfs-design.rst @@ -0,0 +1,132 @@ +======== +Debug FS +======== + +.. contents:: + +Overview +-------- + +The *DebugFS* feature is primarily aimed at exposing firmware debug data to +higher SW layers such as a non-secure component. Such component can be the +TFTF test payload or a Linux kernel module. + +Virtual filesystem +------------------ + +The core functionality lies in a virtual file system based on a 9p file server +interface (`Notes on the Plan 9 Kernel Source`_). The implementation permits +exposing virtual files, firmware drivers, and file blobs. + +Namespace +~~~~~~~~~ + +Two namespaces are exposed: + + - # is used as root for drivers (e.g. #t0 is the first uart) + - / is used as root for virtual "files" (e.g. /fip, or /dev/uart) + +9p interface +~~~~~~~~~~~~ + +The associated primitives are: + +- Unix-like: + + - open(): create a file descriptor that acts as a handle to the file passed as + an argument. + - close(): close the file descriptor created by open(). + - read(): read from a file to a buffer. + - write(): write from a buffer to a file. + - seek(): set the file position indicator of a file descriptor either to a + relative or an absolute offset. + - stat(): get information about a file (type, mode, size, ...). + +.. code:: c + + int open(const char *name, int flags); + int close(int fd); + int read(int fd, void *buf, int n); + int write(int fd, void *buf, int n); + int seek(int fd, long off, int whence); + int stat(char *path, dir_t *dir); + +- Specific primitives : + + - mount(): create a link between a driver and spec. + - create(): create a file in a specific location. + - bind(): expose the content of a directory to another directory. + +.. code:: c + + int mount(char *srv, char *mnt, char *spec); + int create(const char *name, int flags); + int bind(char *path, char *where); + +This interface is embedded into the BL31 run-time payload when selected by build +options. The interface multiplexes drivers or emulated "files": + +- Debug data can be partitioned into different virtual files e.g. expose PMF + measurements through a file, and internal firmware state counters through + another file. +- This permits direct access to a firmware driver, mainly for test purposes + (e.g. a hardware device that may not be accessible to non-privileged/ + non-secure layers, or for which no support exists in the NS side). + +SMC interface +------------- + +The communication with the 9p layer in BL31 is made through an SMC conduit +(`SMC Calling Convention PDD`_), using a specific SiP Function Id. An NS shared +buffer is used to pass path string parameters, or e.g. to exchange data on a +read operation. Refer to `ARM SiP Services`_ for a description of the SMC +interface. + +Security considerations +----------------------- + +- Due to the nature of the exposed data, the feature is considered experimental + and importantly **shall only be used in debug builds**. +- Several primitive imply string manipulations and usage of string formats. +- Special care is taken with the shared buffer to avoid TOCTOU attacks. + +Limitations +----------- + +- In order to setup the shared buffer, the component consuming the interface + needs to allocate a physical page frame and transmit its address. +- In order to map the shared buffer, BL31 requires enabling the dynamic xlat + table option. +- Data exchange is limited by the shared buffer length. A large read operation + might be split into multiple read operations of smaller chunks. +- On concurrent access, a spinlock is implemented in the BL31 service to protect + the internal work buffer, and re-entrancy into the filesystem layers. +- Notice, a physical device driver if exposed by the firmware may conflict with + the higher level OS if the latter implements its own driver for the same + physical device. + +Applications +------------ + +The SMC interface is accessible from an NS environment, that is: + +- a test payload, bootloader or hypervisor running at NS-EL2 +- a Linux kernel driver running at NS-EL1 +- a Linux userspace application through the kernel driver + +References +---------- + +.. [#] `SMC Calling Convention PDD`_ +.. [#] `Notes on the Plan 9 Kernel Source`_ +.. [#] `Linux 9p remote filesystem protocol`_ +.. [#] `ARM SiP Services`_ + +-------------- + +*Copyright (c) 2019, Arm Limited and Contributors. All rights reserved.* + +.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ +.. _Notes on the Plan 9 Kernel Source: http://lsub.org/who/nemo/9.pdf +.. _Linux 9p remote filesystem protocol: https://www.kernel.org/doc/Documentation/filesystems/9p.txt +.. _ARM SiP Services: arm-sip-service.rst diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 0d0173318..3f386854f 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -26,8 +26,8 @@ Introduction Through various control bits in the ``SCR_EL3`` register, the Arm architecture allows for asynchronous exceptions to be routed to EL3. As described in the -`Interrupt Framework Design`_ document, depending on the chosen interrupt -routing model, TF-A appropriately sets the ``FIQ`` and ``IRQ`` bits of +:ref:`Interrupt Management Framework` document, depending on the chosen +interrupt routing model, TF-A appropriately sets the ``FIQ`` and ``IRQ`` bits of ``SCR_EL3`` register to effect this routing. For most use cases, other than for the purpose of facilitating context switch between Normal and Secure worlds, FIQs and IRQs routed to EL3 are not required to be handled in EL3. @@ -143,8 +143,9 @@ Interrupt handling ------------------ The |EHF| is a client of *Interrupt Management Framework*, and registers the -top-level handler for interrupts that target EL3, as described in the `Interrupt -Framework Design`_ document. This has the following implications. +top-level handler for interrupts that target EL3, as described in the +:ref:`Interrupt Management Framework` document. This has the following +implications: - On GICv3 systems, when executing in S-EL1, pending Non-secure interrupts of sufficient priority are signalled as FIQs, and therefore will be routed to @@ -618,9 +619,8 @@ The |EHF| has the following limitations: exception descriptor and the programmed priority of interrupts handled by the dispatcher match. The |EHF| cannot verify that this has been followed. ----- +-------------- -*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* -.. _Interrupt Framework Design: ../design/interrupt-framework-design.rst .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index 30bdc24b2..a59156568 100644 --- a/docs/components/firmware-update.rst +++ b/docs/components/firmware-update.rst @@ -7,15 +7,15 @@ Introduction This document describes the design of the Firmware Update (FWU) feature, which enables authenticated firmware to update firmware images from external interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile -memories such as NAND Flash, LPPDR2-NVM or any memory determined by the +memories such as NAND Flash, LPDDR2-NVM or any memory determined by the platform. This feature functions even when the current firmware in the system is corrupt or missing; it therefore may be used as a recovery mode. It may also be complemented by other, higher level firmware update software. FWU implements a specific part of the Trusted Board Boot Requirements (TBBR) specification, Arm DEN0006C-1. It should be used in conjunction with the -`Trusted Board Boot`_ design document, which describes the image authentication -parts of the Trusted Firmware-A (TF-A) TBBR implementation. +:ref:`Trusted Board Boot` design document, which describes the image +authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation. Scope ~~~~~ @@ -53,10 +53,11 @@ The primary requirements of the FWU feature are: at other Exception Levels. #. Export a platform interface to provide FWU common code with the information it needs, and to enable platform specific FWU functionality. See the - `Porting Guide`_ for details of this interface. + :ref:`Porting Guide` for details of this interface. TF-A uses abbreviated image terminology for FWU images like for other TF-A -images. An overview of this terminology can be found `here`_. +images. See the :ref:`Image Terminology` document for an explanation of these +terms. The following diagram shows the FWU boot flow for Arm development platforms. Arm CSS platforms like Juno have a System Control Processor (SCP), and these @@ -70,8 +71,8 @@ Image Identification Each FWU image and certificate is identified by a unique ID, defined by the platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the -Chain of Trust (Refer to the `Authentication Framework Design`_ -for more information). +Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust` +document for more information). The image descriptor includes the following information: @@ -394,11 +395,6 @@ This is only allowed if the image is not being executed. *Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* -.. _Trusted Board Boot: ../design/trusted-board-boot.rst -.. _Porting Guide: ../getting_started/porting-guide.rst -.. _here: ../getting_started/image-terminology.rst -.. _Authentication Framework Design: ../design/auth-framework.rst .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt - .. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png .. |FWU state machine| image:: ../resources/diagrams/fwu_states.png diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst index 7890cd38f..9d02f45c0 100644 --- a/docs/components/platform-interrupt-controller-API.rst +++ b/docs/components/platform-interrupt-controller-API.rst @@ -3,9 +3,8 @@ Platform Interrupt Controller API This document lists the optional platform interrupt controller API that abstracts the runtime configuration and control of interrupt controller from the -generic code. The mandatory APIs are described in the `porting guide`__. - -.. __: ../getting_started/porting-guide.rst#interrupt-management-framework-in-bl31 +generic code. The mandatory APIs are described in the +:ref:`Porting Guide <porting_guide_imf_in_bl31>`. Function: unsigned int plat_ic_get_running_priority(void); [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -303,6 +302,6 @@ should return ``INTR_ID_UNAVAILABLE``. In case of Arm standard platforms using GIC, the implementation of the API masks out the interrupt ID field from the acknowledged value from GIC. ----- +-------------- -*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 137c0c301..3d81f17e9 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -1,9 +1,6 @@ Reliability, Availability, and Serviceability (RAS) Extensions ============================================================== -.. |EHF| replace:: Exception Handling Framework -.. |TF-A| replace:: Trusted Firmware-A - This document describes |TF-A| support for Arm Reliability, Availability, and Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and later CPUs, and also an optional extension to the base Armv8.0 architecture. @@ -247,6 +244,6 @@ explicit using `EHF APIs`__. .. __: exception-handling.rst#non-interrupt-flow .. __: exception-handling.rst#activating-and-deactivating-priorities ----- +-------------- -*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst index d8bc89cea..d34b3cc58 100644 --- a/docs/components/romlib-design.rst +++ b/docs/components/romlib-design.rst @@ -111,10 +111,31 @@ The calling sequence for a patched function is as follows: BL image --> function +Memory impact +~~~~~~~~~~~~~ + +Using library at ROM will modify the memory layout of the BL images: + +- The ROM library needs a page aligned RAM section to hold the RW data. This + section is defined by the ROMLIB_RW_BASE and ROMLIB_RW_END macros. + On Arm platforms a section of 1 page (0x1000) is allocated at the top of SRAM. + This will have for effect to shift down all the BL images by 1 page. + +- Depending on the functions moved to the ROM library, the size of the BL images + will be reduced. + For example: moving MbedTLS function into the ROM library reduces BL1 and + BL2, but not BL31. + +- This change in BL images size can be taken into consideration to optimize the + memory layout when defining the BLx_BASE macros. + Build library at ROM ~~~~~~~~~~~~~~~~~~~~~ -The environment variable ``CROSS_COMPILE`` must be set as per the user guide. +The environment variable ``CROSS_COMPILE`` must be set appropriately. Refer to +:ref:`Performing an Initial Build` for more information about setting this +variable. + In the below example the usage of ROMLIB together with mbed TLS is demonstrated to showcase the benefits of library at ROM - it's not mandatory. diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index 2a777b385..c5275a0b7 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -7,7 +7,7 @@ Trusted Firmware-A (TF-A). Introduction ------------ -`Software Delegated Exception Interface`_ (SDEI) is an Arm specification for +Software Delegated Exception Interface (|SDEI|) is an Arm specification for Non-secure world to register handlers with firmware to receive notifications about system events. Firmware will first receive the system events by way of asynchronous exceptions and, in response, arranges for the registered handler to @@ -50,9 +50,6 @@ The remainder of this document only discusses the design and implementation of SDEI dispatcher in TF-A, and assumes that the reader is familiar with the SDEI specification, the interfaces, and their requirements. -.. [#std-event] Except event 0, which is defined by the SDEI specification as a - standard event. - Defining events --------------- @@ -78,12 +75,10 @@ event descriptors. Both macros take 3 arguments: To define event 0, the macro ``SDEI_DEFINE_EVENT_0()`` should be used. This macro takes only one parameter: an SGI number to signal other PEs. -To define an event that's meant to be `explicitly dispatched`__ (i.e., not as a +To define an event that's meant to be explicitly dispatched (i.e., not as a result of receiving an SDEI interrupt), the macro ``SDEI_EXPLICIT_EVENT()`` should be used. It accepts two parameters: -.. __: `Explicit dispatch of events`_ - - The event number (as above); - Event priority: ``SDEI_MAPF_CRITICAL`` or ``SDEI_MAPF_NORMAL``, as described @@ -110,9 +105,7 @@ Regarding event descriptors: - Statically bound shared and private interrupts must be bound to shared and private interrupts on the platform, respectively. See the section on - `interrupt configuration`__. - - .. __: `Configuration within Exception Handling Framework`_ + `Configuration within Exception Handling Framework`_. - Both arrays should be one-dimensional. The ``REGISTER_SDEI_MAP()`` macro takes care of replicating private events for each PE on the platform. @@ -130,9 +123,8 @@ Event flags ~~~~~~~~~~~ Event flags describe the properties of the event. They are bit maps that can be -``OR``\ ed to form parameters to macros that `define events`__. - -.. __: `Defining events`_ +``OR``\ ed to form parameters to macros that define events (see +`Defining events`_). - ``SDEI_MAPF_DYNAMIC``: Marks the event as dynamic. Dynamic events can be bound to (or released from) any Non-secure interrupt at runtime via the @@ -196,7 +188,7 @@ interrupts for the platform: be configured as *Group 0*. Additionally, on GICv2 systems, the build option ``GICV2_G0_FOR_EL3`` must be set to ``1``. -See also `SDEI porting requirements`_. +See also :ref:`porting_guide_sdei_requirements`. Determining client EL --------------------- @@ -250,10 +242,6 @@ rest of the sequence is similar to that in the `general SDEI dispatch`_: the requested event is dispatched to the client (assuming all the conditions are met), and when the handler completes, the preempted execution resumes. -.. [#critical-event] Examples of critical event are *SError*, *Synchronous - External Abort*, *Fault Handling interrupt*, or *Error - Recovery interrupt* from one of RAS nodes in the system. - Conditions for event dispatch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -307,10 +295,8 @@ dispatcher: Porting requirements -------------------- -The porting requirements of the SDEI dispatcher are outlined in the `porting -guide`__. - -.. __: `SDEI porting requirements`_ +The porting requirements of the SDEI dispatcher are outlined in the +:ref:`Porting Guide <porting_guide_sdei_requirements>`. Note on writing SDEI event handlers ----------------------------------- @@ -364,10 +350,18 @@ implemented in assembly, following a similar pattern as below: smc #0 b . ----- +-------------- + +*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* -*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* +.. rubric:: Footnotes + +.. [#std-event] Except event 0, which is defined by the SDEI specification as a + standard event. + +.. [#critical-event] Examples of critical events are *SError*, *Synchronous + External Abort*, *Fault Handling interrupt* or *Error + Recovery interrupt* from one of RAS nodes in the system. .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _SDEI porting requirements: ../getting_started/porting-guide.rst#sdei-porting-requirements .. _Software Delegated Exception Interface: `SDEI specification`_ diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst index de0792d15..52b1c03e8 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-design.rst @@ -119,7 +119,7 @@ Interface). This will be referred to as the *Standalone MM Secure Partition* in the rest of this document. To enable SPM support in TF-A, the source code must be compiled with the build -flag ``ENABLE_SPM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm +flag ``SPM_MM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the location of the binary that contains the BL32 image (``BL32=path/to/image.bin``) must be specified. @@ -133,7 +133,7 @@ image in the FIP: .. code:: shell BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \ - make PLAT=fvp ENABLE_SPM=1 ARM_BL31_IN_DRAM=1 fip all + make PLAT=fvp SPM_MM=1 EL3_EXCEPTION_HANDLING=1 ARM_BL31_IN_DRAM=1 all fip Describing Secure Partition resources ------------------------------------- @@ -160,7 +160,7 @@ are implemented. Partition. - ``plat_get_secure_partition_boot_info()`` returns a - ``secure_partition_boot_info_t`` struct that is populated by the platform + ``spm_mm_boot_info_t`` struct that is populated by the platform with information about the memory map of the Secure Partition. For an example of all the changes in context, you may refer to commit @@ -308,8 +308,8 @@ allows the Secure Partition to: Miscellaneous interfaces ------------------------ -``SPM_VERSION_AARCH32`` -^^^^^^^^^^^^^^^^^^^^^^^ +``SPM_MM_VERSION_AARCH32`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Description @@ -369,7 +369,7 @@ Secure Partition Initialisation The SPM is responsible for initialising the architectural execution context to enable initialisation of a service in S-EL0. The responsibilities of the SPM are listed below. At the end of initialisation, the partition issues a -``SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for +``MM_SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for handling requests for services implemented by the Secure Partition. The initialisation event is executed as a Fast Call. @@ -488,12 +488,12 @@ Runtime Event Delegation The SPM receives requests for Secure Partition services through a synchronous invocation (i.e. a SMC from the Non-secure world). These requests are delegated to the partition by programming a return from the last -``SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call +``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call was made to signal either completion of Secure Partition initialisation or completion of a partition service request. -``SP_EVENT_COMPLETE_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``MM_SP_EVENT_COMPLETE_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Description @@ -569,7 +569,7 @@ completion of a partition service request. - Caller responsibilities - A Secure Partition must only call ``SP_EVENT_COMPLETE_AARCH64`` to signal + A Secure Partition must only call ``MM_SP_EVENT_COMPLETE_AARCH64`` to signal completion of a request that was delegated to it by the SPM. - Callee responsibilities @@ -613,18 +613,19 @@ data and code) will be known only when the file is loaded into memory. In this case, the Secure Partition needs a way to change the access permissions of its memory regions. The SPM provides this feature through the -``SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is available -to the Secure Partition during a specific time window: from the first entry into -the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that signals the -Secure Partition has finished its initialisation. Once the initialisation is -complete, the SPM does not allow changes to the memory attributes. +``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is +available to the Secure Partition during a specific time window: from the first +entry into the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that +signals the Secure Partition has finished its initialisation. Once the +initialisation is complete, the SPM does not allow changes to the memory +attributes. This section describes the standard SVC interface that is implemented by the SPM to determine and change permission attributes of memory regions that belong to a Secure Partition. -``SP_MEMORY_ATTRIBUTES_GET_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``MM_SP_MEMORY_ATTRIBUTES_GET_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Description @@ -673,7 +674,7 @@ Secure Partition. - ``NOT_SUPPORTED`` : The SPM does not support retrieval of attributes of any memory page that is accessible by the Secure Partition, or the function was called from the Non-secure world. Also returned if it is - used after ``SP_EVENT_COMPLETE_AARCH64``. + used after ``MM_SP_EVENT_COMPLETE_AARCH64``. See `Error Codes`_ for integer values that are associated with each return code. @@ -696,8 +697,8 @@ Secure Partition. The SPM must not return the memory access controls for a page of memory that is not accessible from a Secure Partition. -``SP_MEMORY_ATTRIBUTES_SET_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Description @@ -762,7 +763,7 @@ Secure Partition. - ``NOT_SUPPORTED``: The SPM does not permit change of attributes of any memory region that is accessible by the Secure Partition. Function was called from the Non-secure world. Also returned if it is used after - ``SP_EVENT_COMPLETE_AARCH64``. + ``MM_SP_EVENT_COMPLETE_AARCH64``. See `Error Codes`_ for integer values that are associated with each return code. @@ -776,8 +777,8 @@ Secure Partition. currently supported. This function is only available at boot time. This interface is revoked after - the Secure Partition sends the first ``SP_EVENT_COMPLETE_AARCH64`` to signal - that it is initialised and ready to receive run-time requests. + the Secure Partition sends the first ``MM_SP_EVENT_COMPLETE_AARCH64`` to + signal that it is initialised and ready to receive run-time requests. - Caller responsibilities diff --git a/docs/components/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst index 786dd3bcb..af5151f70 100644 --- a/docs/components/xlat-tables-lib-v2-design.rst +++ b/docs/components/xlat-tables-lib-v2-design.rst @@ -30,8 +30,8 @@ About version 1 and version 2 ----------------------------- This document focuses on version 2 of the library, whose sources are available -in the `lib/xlat_tables_v2`_ directory. Version 1 of the library can still be -found in `lib/xlat_tables`_ directory but it is less flexible and doesn't +in the ``lib/xlat_tables_v2`` directory. Version 1 of the library can still be +found in ``lib/xlat_tables`` directory but it is less flexible and doesn't support dynamic mapping. Although potential bug fixes will be applied to both versions, future features enhancements will focus on version 2 and might not be back-ported to version 1. Therefore, it is recommended to use version 2, @@ -62,7 +62,7 @@ map. It is one of the key interfaces to the library. It is identified by: - its attributes; - its mapping granularity (optional). -See the ``struct mmap_region`` type in `xlat_tables_v2.h`_. +See the ``struct mmap_region`` type in ``xlat_tables_v2.h``. The user usually provides a list of such mmap regions to map and lets the library transpose that in a set of translation tables. As a result, the library @@ -73,7 +73,7 @@ normal memory) as well as the memory access permissions (read-only or read-write, executable or not, secure or non-secure, and so on). In the case of the EL1&0 translation regime, the attributes also specify whether the region is a User region (EL0) or Privileged region (EL1). See the ``MT_xxx`` definitions -in `xlat_tables_v2.h`_. Note that for the EL1&0 translation regime the Execute +in ``xlat_tables_v2.h``. Note that for the EL1&0 translation regime the Execute Never attribute is set simultaneously for both EL1 and EL0. The granularity controls the translation table level to go down to when mapping @@ -162,7 +162,7 @@ coming (for the most part) from platform-specific defines: - size of the virtual address space: ``PLAT_VIRT_ADDR_SPACE_SIZE``; - size of the physical address space: ``PLAT_PHY_ADDR_SPACE_SIZE``. -Please refer to the `Porting Guide`_ for more details about these macros. +Please refer to the :ref:`Porting Guide` for more details about these macros. Static and dynamic memory regions @@ -201,7 +201,7 @@ Library APIs ------------ The external APIs exposed by this library are declared and documented in the -`xlat_tables_v2.h`_ header file. This should be the reference point for +``xlat_tables_v2.h`` header file. This should be the reference point for getting information about the usage of the different APIs this library provides. This section just provides some extra details and clarifications. @@ -284,7 +284,7 @@ The library is divided into 4 modules: provides functions such as ``mmap_add_region_ctx`` that let the caller specify the translation tables context affected by them. - See `xlat_tables_core.c`_. + See ``xlat_tables_core.c``. - **Active context module** @@ -293,14 +293,14 @@ The library is divided into 4 modules: This module provides functions such as ``mmap_add_region``, that directly affect the BL image using them. - See `xlat_tables_context.c`_. + See ``xlat_tables_context.c``. - **Utilities module** Provides additional functionality like debug print of the current state of the translation tables and helpers to query memory attributes and to modify them. - See `xlat_tables_utils.c`_. + See ``xlat_tables_utils.c``. - **Architectural module** @@ -309,7 +309,7 @@ The library is divided into 4 modules: MMU, or calculate the Physical Address Space size. They do not need a translation context to work on. - See `aarch32/xlat_tables_arch.c`_ and `aarch64/xlat_tables_arch.c`_. + See ``aarch32/xlat_tables_arch.c`` and ``aarch64/xlat_tables_arch.c``. From mmap regions to translation tables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -343,7 +343,7 @@ The mapping function is implemented as a recursive algorithm. It is however bound by the level of depth of the translation tables (the Armv8-A architecture allows up to 4 lookup levels). -By default [#granularity-ref]_, the algorithm will attempt to minimize the +By default [#granularity]_, the algorithm will attempt to minimize the number of translation tables created to satisfy the user's request. It will favour mapping a region using the biggest possible blocks, only creating a sub-table if it is strictly necessary. This is to reduce the memory footprint of @@ -374,9 +374,6 @@ entries in the translation tables are checked to ensure consistency. Please refer to the comments in the source code of the core module for more details about the sorting algorithm in use. -.. [#granularity-ref] That is, when mmap regions do not enforce their mapping - granularity. - TLB maintenance operations ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -402,20 +399,19 @@ descriptor. Given that the TLBs are not architecturally permitted to hold any invalid translation table entry [#tlb-no-invalid-entry]_, this means that this mapping cannot be cached in the TLBs. -.. [#tlb-reset-ref] See section D4.9 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev C.a. -.. [#tlb-no-invalid-entry] See section D4.10.1 `General TLB maintenance requirements` in Armv8-A, rev C.a. +.. rubric:: Footnotes + +.. [#granularity] That is, when mmap regions do not enforce their mapping + granularity. + +.. [#tlb-reset-ref] See section D4.9 ``Translation Lookaside Buffers (TLBs)``, + subsection ``TLB behavior at reset`` in Armv8-A, rev C.a. + +.. [#tlb-no-invalid-entry] See section D4.10.1 ``General TLB maintenance + requirements`` in Armv8-A, rev C.a. -------------- -*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* - -.. _lib/xlat_tables_v2: ../../lib/xlat_tables_v2 -.. _lib/xlat_tables: ../../lib/xlat_tables -.. _xlat_tables_v2.h: ../../include/lib/xlat_tables/xlat_tables_v2.h -.. _xlat_tables_context.c: ../../lib/xlat_tables_v2/xlat_tables_context.c -.. _xlat_tables_core.c: ../../lib/xlat_tables_v2/xlat_tables_core.c -.. _xlat_tables_utils.c: ../../lib/xlat_tables_v2/xlat_tables_utils.c -.. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c -.. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c -.. _Porting Guide: ../getting_started/porting-guide.rst +*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* + .. |Alignment Example| image:: ../resources/diagrams/xlat_align.png diff --git a/docs/conf.py b/docs/conf.py index b267de0e8..a100241c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,9 +15,6 @@ import os project = 'Trusted Firmware-A' -version = '2.1' -release = version # We don't need these to be distinct - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be diff --git a/docs/contents.rst b/docs/contents.rst deleted file mode 100644 index 4909dabe6..000000000 --- a/docs/contents.rst +++ /dev/null @@ -1,165 +0,0 @@ -Trusted Firmware-A Documentation Contents -========================================= - -This document serves as a list of the documentation that is included with the -Trusted Firmware-A source. - -Introduction ------------- - -`About Trusted Firmware-A`_ - -Getting Started ---------------- - -`Frequently-Asked Questions (FAQ)`_ - -`Image Terminology`_ - -`Porting Guide`_ - -`User Guide`_ - -Contributing ------------- - -`Coding Style and Guidelines`_ - -`Contributor Acknowledgements`_ - -`Contributor's Guide`_ - -`License`_ - -`Maintainers`_ - -Processes and Policies ----------------------- - -`Platform Compatibility Policy`_ - -`Release Processes`_ - -Secure Payload Dispatch ------------------------ - -`OP-TEE Dispatcher`_ - -`Trusted Little Kernel (TLK) Dispatcher`_ - -`Trusty Dispatcher`_ - -System Design and Components ----------------------------- - -`Arm CPU Specific Build Macros`_ - -`Arm SiP Services`_ - -`Authentication Framework & Chain of Trust`_ - -`CPU Reset`_ - -`EL3 Runtime Service Writer’s Guide`_ - -`Exception Handling Framework`_ - -`Firmware Design Overview`_ - -`Firmware Update (FWU)`_ - -`Interrupt Management Framework`_ - -`Library at ROM`_ - -`Platform Interrupt Controller API`_ - -`PSCI Library Integration Guide for Armv8-A AArch32 systems`_ - -`PSCI Power Domain Tree design`_ - -`Reliability, Availability, and Serviceability (RAS) Extensions`_ - -`Secure Partition Manager`_ - -`Software Delegated Exception Interface`_ - -`Translation (XLAT) Tables Library`_ - -`Trusted Board Boot Design Guide`_ - -Performance and Testing ------------------------ - -`PSCI Performance Measurements on Arm Juno Development Platform`_ - -Security and Advisories ------------------------ - -`Security Processes`_ - -`TFV-1`_ - -`TFV-2`_ - -`TFV-3`_ - -`TFV-4`_ - -`TFV-5`_ - -`TFV-6`_ - -`TFV-7`_ - -`TFV-8`_ - -Other Documents ---------------- - -`Change Log`_ - -.. _About Trusted Firmware-A: ../readme.rst -.. _Frequently-Asked Questions (FAQ): ./process/faq.rst -.. _Image Terminology: ./getting_started/image-terminology.rst -.. _Porting Guide: ./getting_started/porting-guide.rst -.. _User Guide: ./getting_started/user-guide.rst -.. _Coding Style and Guidelines: ./process/coding-guidelines.rst -.. _Contributor Acknowledgements: ./acknowledgements.rst -.. _`Contributor's Guide`: ./process/contributing.rst -.. _License: ../license.rst -.. _Maintainers: ./maintainers.rst -.. _Platform Compatibility Policy: ./process/platform-compatibility-policy.rst -.. _Release Processes: ./process/release-information.rst -.. _Arm SiP Services: ./components/arm-sip-service.rst -.. _Exception Handling Framework: ./components/exception-handling.rst -.. _Firmware Update (FWU): ./components/firmware-update.rst -.. _Interrupt Management Framework: ./design/interrupt-framework-design.rst -.. _Library at ROM: ./components/romlib-design.rst -.. _Platform Interrupt Controller API: ./components/platform-interrupt-controller-API.rst -.. _`Reliability, Availability, and Serviceability (RAS) Extensions`: ./components/ras.rst -.. _Secure Partition Manager: ./components/secure-partition-manager-design.rst -.. _Software Delegated Exception Interface: ./components/sdei.rst -.. _Translation (XLAT) Tables Library: ./components/xlat-tables-lib-v2-design.rst -.. _OP-TEE Dispatcher: ./components/spd/optee-dispatcher.rst -.. _Trusted Little Kernel (TLK) Dispatcher: ./components/spd/tlk-dispatcher.rst -.. _Trusty Dispatcher: ./components/spd/trusty-dispatcher.rst -.. _Arm CPU Specific Build Macros: ./design/cpu-specific-build-macros.rst -.. _`Authentication Framework & Chain of Trust`: ./design/auth-framework.rst -.. _CPU Reset: ./design/reset-design.rst -.. _`EL3 Runtime Service Writer’s Guide`: ./getting_started/rt-svc-writers-guide.rst -.. _Firmware Design Overview: ./design/firmware-design.rst -.. _PSCI Library Integration Guide for Armv8-A AArch32 systems: ./getting_started/psci-lib-integration-guide.rst -.. _PSCI Power Domain Tree design: ./design/psci-pd-tree.rst -.. _Trusted Board Boot Design Guide: ./design/trusted-board-boot.rst -.. _PSCI Performance Measurements on Arm Juno Development Platform: ./perf/psci-performance-juno.rst -.. _Security Processes: ./process/security.rst -.. _Change Log: ./change-log.rst -.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst -.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst -.. _TFV-3: ./security_advisories/security-advisory-tfv-3.rst -.. _TFV-4: ./security_advisories/security-advisory-tfv-4.rst -.. _TFV-5: ./security_advisories/security-advisory-tfv-5.rst -.. _TFV-6: ./security_advisories/security-advisory-tfv-6.rst -.. _TFV-7: ./security_advisories/security-advisory-tfv-7.rst -.. _TFV-8: ./security_advisories/security-advisory-tfv-8.rst diff --git a/docs/design/alt-boot-flows.rst b/docs/design/alt-boot-flows.rst new file mode 100644 index 000000000..b44c061d4 --- /dev/null +++ b/docs/design/alt-boot-flows.rst @@ -0,0 +1,84 @@ +Alternative Boot Flows +====================== + +EL3 payloads alternative boot flow +---------------------------------- + +On a pre-production system, the ability to execute arbitrary, bare-metal code at +the highest exception level is required. It allows full, direct access to the +hardware, for example to run silicon soak tests. + +Although it is possible to implement some baremetal secure firmware from +scratch, this is a complex task on some platforms, depending on the level of +configuration required to put the system in the expected state. + +Rather than booting a baremetal application, a possible compromise is to boot +``EL3 payloads`` through TF-A instead. This is implemented as an alternative +boot flow, where a modified BL2 boots an EL3 payload, instead of loading the +other BL images and passing control to BL31. It reduces the complexity of +developing EL3 baremetal code by: + +- putting the system into a known architectural state; +- taking care of platform secure world initialization; +- loading the SCP_BL2 image if required by the platform. + +When booting an EL3 payload on Arm standard platforms, the configuration of the +TrustZone controller is simplified such that only region 0 is enabled and is +configured to permit secure access only. This gives full access to the whole +DRAM to the EL3 payload. + +The system is left in the same state as when entering BL31 in the default boot +flow. In particular: + +- Running in EL3; +- Current state is AArch64; +- Little-endian data access; +- All exceptions disabled; +- MMU disabled; +- Caches disabled. + +.. _alt_boot_flows_el3_payload: + +Booting an EL3 payload +~~~~~~~~~~~~~~~~~~~~~~ + +The EL3 payload image is a standalone image and is not part of the FIP. It is +not loaded by TF-A. Therefore, there are 2 possible scenarios: + +- The EL3 payload may reside in non-volatile memory (NVM) and execute in + place. In this case, booting it is just a matter of specifying the right + address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A. + +- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at + run-time. + +To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be +used. The infinite loop that it introduces in BL1 stops execution at the right +moment for a debugger to take control of the target and load the payload (for +example, over JTAG). + +It is expected that this loading method will work in most cases, as a debugger +connection is usually available in a pre-production system. The user is free to +use any other platform-specific mechanism to load the EL3 payload, though. + + +Preloaded BL33 alternative boot flow +------------------------------------ + +Some platforms have the ability to preload BL33 into memory instead of relying +on TF-A to load it. This may simplify packaging of the normal world code and +improve performance in a development environment. When secure world cold boot +is complete, TF-A simply jumps to a BL33 base address provided at build time. + +For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be +used when compiling TF-A. For example, the following command will create a FIP +without a BL33 and prepare to jump to a BL33 image loaded at address +0x80000000: + +.. code:: shell + + make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index da958b7c2..93f691b7b 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -637,9 +637,9 @@ all CoTs must present: The TBBR specifies the additional certificates that must accompany these images for a proper authentication. Details about the TBBR CoT may be found in the -`Trusted Board Boot`_ document. +:ref:`Trusted Board Boot` document. -Following the `Platform Porting Guide`_, a platform must provide unique +Following the :ref:`Porting Guide`, a platform must provide unique identifiers for all the images and certificates that will be loaded during the boot process. If a platform is using the TBBR as a reference for trusted boot, these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``. @@ -704,7 +704,7 @@ Each image descriptor must specify: In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters extracted from the certificates. In the case of the TBBR CoT, these parameters -are hashes and public keys. In DER format, an RSA-2048 public key requires 294 +are hashes and public keys. In DER format, an RSA-4096 public key requires 550 bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication process, some of the buffers may be reused at different stages during the boot. @@ -946,12 +946,16 @@ three functions: int verify_hash(void *data_ptr, unsigned int data_len, void *digest_info_ptr, unsigned int digest_info_len); -The mbedTLS library algorithm support is configured by the -``TF_MBEDTLS_KEY_ALG`` variable which can take in 3 values: `rsa`, `ecdsa` or -`rsa+ecdsa`. This variable allows the Makefile to include the corresponding -sources in the build for the various algorithms. Setting the variable to -`rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS -library. +The mbedTLS library algorithm support is configured by both the +``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables. + +- ``TF_MBEDTLS_KEY_ALG`` can take in 3 values: `rsa`, `ecdsa` or `rsa+ecdsa`. + This variable allows the Makefile to include the corresponding sources in + the build for the various algorithms. Setting the variable to `rsa+ecdsa` + enables support for both rsa and ecdsa algorithms in the mbedTLS library. + +- ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values + include 1024, 2048, 3072 and 4096. .. note:: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can @@ -963,6 +967,4 @@ library. *Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* -.. _Trusted Board Boot: ./trusted-board-boot.rst -.. _Platform Porting Guide: ../getting_started/porting-guide.rst .. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst index d3fe89d62..f3096b418 100644 --- a/docs/design/cpu-specific-build-macros.rst +++ b/docs/design/cpu-specific-build-macros.rst @@ -29,6 +29,8 @@ vulnerability workarounds should be applied at runtime. platform contains at least 1 CPU that requires dynamic mitigation. Defaults to 0. +.. _arm_cpu_macros_errata_workarounds: + CPU Errata Workarounds ---------------------- @@ -47,9 +49,8 @@ errata notice document. The format of the define used to enable/disable the errata workaround is ``ERRATA_<Processor name>_<ID>``, where the ``Processor name`` is for example ``A57`` for the ``Cortex_A57`` CPU. -Refer to the section *CPU errata status reporting* in -`Firmware Design guide`_ for information on how to write errata workaround -functions. +Refer to :ref:`firmware_design_cpu_errata_reporting` for information on how to +write errata workaround functions. All workarounds are disabled by default. The platform is responsible for enabling these workarounds according to its requirement by defining the @@ -226,6 +227,12 @@ For Cortex-A76, the following errata build flags are defined : - ``ERRATA_A76_1275112``: This applies errata 1275112 workaround to Cortex-A76 CPU. This needs to be enabled only for revision <= r3p0 of the CPU. +For Hercules, the following errata build flags are defined : + +- ``ERRATA_HERCULES_1688305``: This applies errata 1688305 workaround to + Hercules CPU. This needs to be enabled only for revision r0p0 - r1p0 of + the CPU. + For Neoverse N1, the following errata build flags are defined : - ``ERRATA_N1_1073348``: This applies errata 1073348 workaround to Neoverse-N1 @@ -258,6 +265,9 @@ For Neoverse N1, the following errata build flags are defined : - ``ERRATA_N1_1315703``: This applies errata 1315703 workaround to Neoverse-N1 CPU. This needs to be enabled only for revision <= r3p0 of the CPU. +- ``ERRATA_N1_1542419``: This applies errata 1542419 workaround to Neoverse-N1 + CPU. This needs to be enabled only for revisions r3p0 - r4p0 of the CPU. + DSU Errata Workarounds ---------------------- @@ -314,6 +324,11 @@ architecture that can be enabled by the platform as desired. as recommended in section "4.7 Non-Temporal Loads/Stores" of the `Cortex-A57 Software Optimization Guide`_. +- ``NEOVERSE_N1_EXTERNAL_LLC``: This flag indicates that an external last + level cache(LLC) is present in the system, and that the DataSource field + on the master CHI interface indicates when data is returned from the LLC. + This is used to control how the LL_CACHE* PMU events count. + -------------- *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* @@ -323,6 +338,5 @@ architecture that can be enabled by the platform as desired. .. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html .. _Cortex-A57 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/index.html .. _Cortex-A72 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm012079/index.html -.. _Firmware Design guide: firmware-design.rst .. _Cortex-A57 Software Optimization Guide: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf .. _Arm DSU Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm138168/index.html diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 00e199a20..5fc1335b3 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -2,24 +2,27 @@ Firmware Design =============== Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot -Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference -platforms. The TBB sequence starts when the platform is powered on and runs up +Requirements (TBBR) Platform Design Document (PDD) for Arm reference +platforms. + +The TBB sequence starts when the platform is powered on and runs up to the stage where it hands-off control to firmware running in the normal world in DRAM. This is the cold boot path. -TF-A also implements the Power State Coordination Interface PDD [2]_ as a +TF-A also implements the `Power State Coordination Interface PDD`_ as a runtime service. PSCI is the interface from normal world software to firmware implementing power management use-cases (for example, secondary CPU boot, hotplug and idle). Normal world software can access TF-A runtime services via the Arm SMC (Secure Monitor Call) instruction. The SMC instruction must be -used as mandated by the SMC Calling Convention [3]_. +used as mandated by the SMC Calling Convention (`SMCCC`_). TF-A implements a framework for configuring and managing interrupts generated in either security state. The details of the interrupt management framework -and its design can be found in TF-A Interrupt Management Design guide [4]_. +and its design can be found in :ref:`Interrupt Management Framework`. TF-A also implements a library for setting up and managing the translation -tables. The details of this library can be found in `Translation tables design`_. +tables. The details of this library can be found in +:ref:`Translation (XLAT) Tables Library`. TF-A can be built to support either AArch64 or AArch32 execution state. @@ -34,7 +37,7 @@ executed by the primary CPU, other than essential CPU initialization executed by all CPUs. The secondary CPUs are kept in a safe platform-specific state until the primary CPU has performed enough initialization to boot them. -Refer to the `Reset Design`_ for more information on the effect of the +Refer to the :ref:`CPU Reset` for more information on the effect of the ``COLD_BOOT_SINGLE_CPU`` platform build option. The cold boot path in this implementation of TF-A depends on the execution @@ -136,15 +139,15 @@ Determination of boot path Whenever a CPU is released from reset, BL1 needs to distinguish between a warm boot and a cold boot. This is done using platform-specific mechanisms (see the -``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a -warm boot, a CPU is expected to continue execution from a separate +``plat_get_my_entrypoint()`` function in the :ref:`Porting Guide`). In the case +of a warm boot, a CPU is expected to continue execution from a separate entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in -the `Porting Guide`_) while the primary CPU executes the remaining cold boot path -as described in the following sections. +the :ref:`Porting Guide`) while the primary CPU executes the remaining cold boot +path as described in the following sections. This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the -`Reset Design`_ for more information on the effect of the +:ref:`CPU Reset` for more information on the effect of the ``PROGRAMMABLE_RESET_ADDRESS`` platform build option. Architectural initialization @@ -157,8 +160,8 @@ BL1 performs minimal architectural initialization as follows. BL1 sets up simple exception vectors for both synchronous and asynchronous exceptions. The default behavior upon receiving an exception is to populate a status code in the general purpose register ``X0/R0`` and call the - ``plat_report_exception()`` function (see the `Porting Guide`_). The status - code is one of: + ``plat_report_exception()`` function (see the :ref:`Porting Guide`). The + status code is one of: For AArch64: @@ -217,7 +220,7 @@ BL1 performs minimal architectural initialization as follows. - ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control to EL3 Runtime Software. - - All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_ + - All SMCs listed in section "BL1 SMC Interface" in the :ref:`Firmware Update (FWU)` Design Guide are supported for AArch64 only. These SMCs are currently not supported when BL1 is built for AArch32. @@ -307,14 +310,15 @@ Firmware Update detection and execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After performing platform setup, BL1 common code calls -``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or -to proceed with the normal boot process. If the platform code returns -``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the -next section, else BL1 assumes that `Firmware Update`_ is required and execution -passes to the first image in the `Firmware Update`_ process. In either case, BL1 -retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``. -The image descriptor contains an ``entry_point_info_t`` structure, which BL1 -uses to initialize the execution state of the next image. +``bl1_plat_get_next_image_id()`` to determine if :ref:`Firmware Update (FWU)` is +required or to proceed with the normal boot process. If the platform code +returns ``BL2_IMAGE_ID`` then the normal boot sequence is executed as described +in the next section, else BL1 assumes that :ref:`Firmware Update (FWU)` is +required and execution passes to the first image in the +:ref:`Firmware Update (FWU)` process. In either case, BL1 retrieves a descriptor +of the next image by calling ``bl1_plat_get_image_desc()``. The image descriptor +contains an ``entry_point_info_t`` structure, which BL1 uses to initialize the +execution state of the next image. BL2 image load and execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -440,7 +444,8 @@ initialization is complete. Hence, BL2 populates a platform-specific area of memory with the entrypoint and Saved Program Status Register (``SPSR``) of the normal world software image. The entrypoint is the load address of the BL33 image. The ``SPSR`` is determined as specified in Section 5.13 of the -`PSCI PDD`_. This information is passed to the EL3 Runtime Software. +`Power State Coordination Interface PDD`_. This information is passed to the +EL3 Runtime Software. AArch64 BL31 (EL3 Runtime Software) execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -539,7 +544,7 @@ It then replaces the exception vectors populated by BL1 with its own. BL31 exception vectors implement more elaborate support for handling SMCs since this is the only mechanism to access the runtime services implemented by BL31 (PSCI for example). BL31 checks each SMC for validity as specified by the -`SMC calling convention PDD`_ before passing control to the required SMC +`SMC Calling Convention PDD`_ before passing control to the required SMC handler routine. BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system @@ -592,7 +597,7 @@ registered function to initialize BL32 before running BL33. This initialization is not necessary for AArch32 SPs. Details on BL32 initialization and the SPD's role are described in the -"Secure-EL1 Payloads and Dispatchers" section below. +:ref:`firmware_design_sel1_spd` section below. BL33 (Non-trusted Firmware) execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -812,7 +817,8 @@ data access and all interrupt sources masked: The warm boot entrypoint may be implemented by using TF-A ``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil -the pre-requisites mentioned in the `PSCI Library integration guide`_. +the pre-requisites mentioned in the +:ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`. EL3 runtime services framework ------------------------------ @@ -862,7 +868,7 @@ not all been instantiated in the current implementation. TF-A provides a Test Secure-EL1 Payload (TSP) and its associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation are described in the - "Secure-EL1 Payloads and Dispatchers" section below. + :ref:`firmware_design_sel1_spd` section below. #. CPU implementation service @@ -972,8 +978,8 @@ manipulation; and with ``flags`` indicating the security state of the caller. Th framework finally sets up the execution stack for the handler, and invokes the services ``handle()`` function. -On return from the handler the result registers are populated in X0-X3 before -restoring the stack and CPU state and returning from the original SMC. +On return from the handler the result registers are populated in X0-X7 as needed +before restoring the stack and CPU state and returning from the original SMC. Exception Handling Framework ---------------------------- @@ -1051,7 +1057,9 @@ hooks to be registered with the generic PSCI code to be supported. The PSCI implementation in TF-A is a library which can be integrated with AArch64 or AArch32 EL3 Runtime Software for Armv8-A systems. A guide to integrating PSCI library with AArch32 EL3 Runtime Software can be found -`here`_. +at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`. + +.. _firmware_design_sel1_spd: Secure-EL1 Payloads and Dispatchers ----------------------------------- @@ -1258,7 +1266,7 @@ handling functions. Details for implementing a CPU specific reset handler can be found in Section 8. Details for implementing a platform specific reset handler can be -found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function). +found in the :ref:`Porting Guide` (see the ``plat_reset_handler()`` function). When adding functionality to a reset handler, keep in mind that if a different reset handling behavior is required between the first and the subsequent @@ -1292,6 +1300,8 @@ by the macro ``INTR_PROP_DESC()``. The macro takes the following arguments: - Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or ``GIC_INTR_CFG_EDGE``). +.. _firmware_design_cpu_ops_fwk: + CPU specific operations framework --------------------------------- @@ -1333,7 +1343,7 @@ different CPUs during power down and reset handling. The platform can specify any CPU optimization it wants to enable for each CPU. It can also specify the CPU errata workarounds to be applied for each CPU type during reset handling by defining CPU errata compile time macros. Details on these macros -can be found in `CPU specific build macros`_. +can be found in the :ref:`Arm CPU Specific Build Macros` document. The CPU specific operations framework depends on the ``cpu_ops`` structure which needs to be exported for each type of CPU in the platform. It is defined in @@ -1399,6 +1409,8 @@ reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching be reported and a pointer to the ASCII list of register names in a format expected by the crash reporting framework. +.. _firmware_design_cpu_errata_reporting: + CPU errata status reporting ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1408,8 +1420,8 @@ build options. Some errata workarounds have potential run-time implications; therefore some are enabled by default, others not. Platform ports shall override build options to enable or disable errata as appropriate. The CPU drivers take care of applying errata workarounds that are enabled and applicable -to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_ -for more information. +to a given CPU. Refer to :ref:`arm_cpu_macros_errata_workarounds` for more +information. Functions in CPU drivers that apply errata workaround must follow the conventions listed below. @@ -1488,6 +1500,11 @@ sections then the resulting binary file would contain zero bytes in place of this NOBITS section, making the image unnecessarily bigger. Smaller images allow faster loading from the FIP to the main memory. +For BL31, a platform can specify an alternate location for NOBITS sections +(other than immediately following PROGBITS sections) by setting +``SEPARATE_NOBITS_REGION`` to 1 and defining ``BL31_NOBITS_BASE`` and +``BL31_NOBITS_LIMIT``. + Linker scripts and symbols ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1660,7 +1677,7 @@ The following list describes the memory layout on the Arm development platforms: point during a cold boot. - On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory - region and transfered to the SCP before being overwritten by EL3 Runtime + region and transferred to the SCP before being overwritten by EL3 Runtime Software. - BL32 (for AArch64) can be loaded in one of the following locations: @@ -1863,10 +1880,7 @@ BL image during boot. | MHU | 0x04000000 +----------+ -Library at ROM ---------------- - -Please refer to the `ROMLIB Design`_ document. +.. _firmware_design_fip: Firmware Image Package (FIP) ---------------------------- @@ -1978,11 +1992,11 @@ is the smallest possible size of the coherent memory region. By default, all data structures which are susceptible to accesses with mismatched attributes from various CPUs are allocated in a coherent memory -region (refer to section 2.1 of `Porting Guide`_). The coherent memory region -accesses are Outer Shareable, non-cacheable and they can be accessed -with the Device nGnRE attributes when the MMU is turned on. Hence, at the -expense of at least an extra page of memory, TF-A is able to work around -coherency issues due to mismatched memory attributes. +region (refer to section 2.1 of :ref:`Porting Guide`). The coherent memory +region accesses are Outer Shareable, non-cacheable and they can be accessed with +the Device nGnRE attributes when the MMU is turned on. Hence, at the expense of +at least an extra page of memory, TF-A is able to work around coherency issues +due to mismatched memory attributes. The alternative to the above approach is to allocate the susceptible data structures in Normal WriteBack WriteAllocate Inner shareable memory. This @@ -2188,7 +2202,7 @@ As mentioned earlier, almost a page of memory can be saved by disabling whether coherent memory should be used. If a platform disables ``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the -`Porting Guide`_). Refer to the reference platform code for examples. +:ref:`Porting Guide`). Refer to the reference platform code for examples. Isolating code and read-only data on separate memory pages ---------------------------------------------------------- @@ -2381,6 +2395,8 @@ are changed within the ``bl31_plat_runtime_setup`` platform hook. The init section section can be reclaimed for any data which is accessed after cold boot initialization and it is upto the platform to make the decision. +.. _firmware_design_pmf: + Performance Measurement Framework --------------------------------- @@ -2529,7 +2545,7 @@ Architecture Extension-specific code is included in the build. Otherwise, TF-A targets the base Armv8.0-A architecture; i.e. as if ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` == 0, which are also their respective default values. -See also the *Summary of build options* in `User Guide`_. +.. seealso:: :ref:`Build Options` For details on the Architecture Extension and available features, please refer to the respective Architecture Extension Supplement. @@ -2540,8 +2556,11 @@ Armv8.1-A This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1. -- The Compare and Swap instruction is used to implement spinlocks. Otherwise, - the load-/store-exclusive instruction pair is used. +- By default, a load-/store-exclusive instruction pair is used to implement + spinlocks. The ``USE_SPINLOCK_CAS`` build option when set to 1 selects the + spinlock implementation using the ARMv8.1-LSE Compare and Swap instruction. + Notice this instruction is only available in AArch64 execution state, so + the option is only available to AArch64 builds. Armv8.2-A ~~~~~~~~~ @@ -2581,7 +2600,16 @@ Armv8.5-A ~~~~~~~~~ - Branch Target Identification feature is selected by ``BRANCH_PROTECTION`` - option set to 1. This option defaults to 0 and this is an experimental feature. + option set to 1. This option defaults to 0 and this is an experimental + feature. + +- Memory Tagging Extension feature is unconditionally enabled for both worlds + (at EL0 and S-EL0) if it is only supported at EL0. If instead it is + implemented at all ELs, it is unconditionally enabled for only the normal + world. To enable it for the secure world as well, the build option + ``CTX_INCLUDE_MTE_REGS`` is required. If the hardware does not implement + MTE support at all, it is always disabled, no matter what build options + are used. Armv7-A ~~~~~~~ @@ -2597,7 +2625,7 @@ Cortex-A architecture through ``ARM_CORTEX_A<X> = yes`` in their Cortex-A15 target. Platform can also set ``ARM_WITH_NEON=yes`` to enable neon support. -Note that using neon at runtime has constraints on non secure wolrd context. +Note that using neon at runtime has constraints on non secure world context. TF-A does not yet provide VFP context management. Directive ``ARM_CORTEX_A<x>`` and ``ARM_WITH_NEON`` are used to set @@ -2656,37 +2684,26 @@ linker scripts which have the extension ``.ld``. FDTs provide a description of the hardware platform and are used by the Linux kernel at boot time. These can be found in the ``fdts`` directory. -References ----------- +.. rubric:: References + +- `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_ -.. [#] `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_ -.. [#] `Power State Coordination Interface PDD`_ -.. [#] `SMC Calling Convention PDD`_ -.. [#] `TF-A Interrupt Management Design guide`_. +- `Power State Coordination Interface PDD`_ + +- `SMC Calling Convention PDD`_ + +- :ref:`Interrupt Management Framework` -------------- *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* -.. _Reset Design: ./reset-design.rst -.. _Porting Guide: ../getting_started/porting-guide.rst -.. _Firmware Update: ../components/firmware-update.rst -.. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf -.. _PSCI Library integration guide: ../getting_started/psci-lib-integration-guide.rst +.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _here: ../getting_started/psci-lib-integration-guide.rst -.. _CPU specific build macros: ./cpu-specific-build-macros.rst -.. _CPUBM: ./cpu-specific-build-macros.rst .. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html -.. _User Guide: ../getting_started/user-guide.rst .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf -.. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst -.. _Translation tables design: ../components/xlat-tables-lib-v2-design.rst -.. _Exception Handling Framework: ../components/exception-handling.rst -.. _ROMLIB Design: ../components/romlib-design.rst .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png diff --git a/docs/design/index.rst b/docs/design/index.rst index a51a4eb47..e3b8f7429 100644 --- a/docs/design/index.rst +++ b/docs/design/index.rst @@ -6,6 +6,7 @@ System Design :caption: Contents :numbered: + alt-boot-flows auth-framework cpu-specific-build-macros firmware-design @@ -13,3 +14,8 @@ System Design psci-pd-tree reset-design trusted-board-boot + trusted-board-boot-build + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index 4a864f9c8..d155cb356 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -177,10 +177,10 @@ uses this information to determine whether the IRQ or the FIQ bit should be programmed in ``SCR_EL3`` while applying the routing model for a type of interrupt. The platform provides this information through the ``plat_interrupt_type_to_line()`` API (described in the -`Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2 -interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal -while Non-secure interrupts are signaled through the IRQ signal. This applies -when execution is in either security state. +:ref:`Porting Guide`). For example, on the FVP port when the platform uses an +Arm GICv2 interrupt controller, Secure-EL1 interrupts are signaled through the +FIQ signal while Non-secure interrupts are signaled through the IRQ signal. +This applies when execution is in either security state. Effect of mapping of several interrupt types to one signal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -255,7 +255,7 @@ is expected to be aware of the secure devices present in the system and their associated interrupt numbers. It should configure the interrupt controller to enable the secure interrupts, ensure that their priority is always higher than the non-secure interrupts and target them to the primary CPU. It should also -export the interface described in the `Porting Guide`_ to enable +export the interface described in the :ref:`Porting Guide` to enable handling of interrupts. In the remainder of this document, for the sake of simplicity a Arm GICv2 system @@ -1013,7 +1013,6 @@ TSP by returning ``SMC_UNK`` error. *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* -.. _Porting Guide: ../getting_started/porting-guide.rst .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. |Image 1| image:: ../resources/diagrams/sec-int-handling.png diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst index ccd717a06..7b10c956c 100644 --- a/docs/design/reset-design.rst +++ b/docs/design/reset-design.rst @@ -6,9 +6,9 @@ resets in Trusted Firmware-A (TF-A). It also describes how the platform integrator can tailor this code to the system configuration to some extent, resulting in a simplified and more optimised boot flow. -This document should be used in conjunction with the `Firmware Design`_, which -provides greater implementation details around the reset code, specifically -for the cold boot path. +This document should be used in conjunction with the :ref:`Firmware Design` +document which provides greater implementation details around the reset code, +specifically for the cold boot path. General reset code flow ----------------------- @@ -109,11 +109,14 @@ images might be done by the Trusted Boot Firmware or by platform code in BL31. Although the Arm FVP platform does not support programming the reset base address dynamically at run-time, it is possible to set the initial value of the -``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP only. +``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP +only. + It allows the Arm FVP port to support the ``RESET_TO_BL31`` configuration, in which case the ``bl31.bin`` image must be loaded to its run address in Trusted SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run -address. See the `User Guide`_ for details of running the FVP models in this way. +address. See the :ref:`Arm Fixed Virtual Platforms (FVP)` for details of running +the FVP models in this way. Although technically it would be possible to program the reset base address with the right support in the SCP firmware, this is currently not implemented so the @@ -150,10 +153,7 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31. -------------- -*Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.* - -.. _Firmware Design: firmware-design.rst -.. _User Guide: ../getting_started/user-guide.rst +*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* .. |Default reset code flow| image:: ../resources/diagrams/default_reset_code.png .. |Reset code flow with programmable reset address| image:: ../resources/diagrams/reset_code_no_boot_type_check.png diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst new file mode 100644 index 000000000..202524316 --- /dev/null +++ b/docs/design/trusted-board-boot-build.rst @@ -0,0 +1,114 @@ +Building FIP images with support for Trusted Board Boot +======================================================= + +Trusted Board Boot primarily consists of the following two features: + +- Image Authentication, described in :ref:`Trusted Board Boot`, and +- Firmware Update, described in :ref:`Firmware Update (FWU)` + +The following steps should be followed to build FIP and (optionally) FWU_FIP +images with support for these features: + +#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser + modules by checking out a recent version of the `mbed TLS Repository`_. It + is important to use a version that is compatible with TF-A and fixes any + known security vulnerabilities. See `mbed TLS Security Center`_ for more + information. See the :ref:`Prerequisites` document for the appropriate + version of mbed TLS to use. + + The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS + source files the modules depend upon. + ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration + options required to build the mbed TLS sources. + + Note that the mbed TLS library is licensed under the Apache version 2.0 + license. Using mbed TLS source code will affect the licensing of TF-A + binaries that are built using this library. + +#. To build the FIP image, ensure the following command line variables are set + while invoking ``make`` to build TF-A: + + - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`` + - ``TRUSTED_BOARD_BOOT=1`` + - ``GENERATE_COT=1`` + + In the case of Arm platforms, the location of the ROTPK hash must also be + specified at build time. Two locations are currently supported (see + ``ARM_ROTPK_LOCATION`` build option): + + - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted + root-key storage registers present in the platform. On Juno, this + registers are read-only. On FVP Base and Cortex models, the registers + are read-only, but the value can be specified using the command line + option ``bp.trusted_key_storage.public_key`` when launching the model. + On both Juno and FVP models, the default value corresponds to an + ECDSA-SECP256R1 public key hash, whose private part is not currently + available. + + - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded + in the Arm platform port. The private/public RSA key pair may be + found in ``plat/arm/board/common/rotpk``. + + - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded + in the Arm platform port. The private/public ECDSA key pair may be + found in ``plat/arm/board/common/rotpk``. + + Example of command line using RSA development keys: + + .. code:: shell + + MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ + make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ + BL33=<path-to>/<bl33_image> \ + all fip + + The result of this build will be the bl1.bin and the fip.bin binaries. This + FIP will include the certificates corresponding to the Chain of Trust + described in the TBBR-client document. These certificates can also be found + in the output build directory. + +#. The optional FWU_FIP contains any additional images to be loaded from + Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the + FWU_FIP, any FWU images required by the platform must be specified on the + command line. On Arm development platforms like Juno, these are: + + - NS_BL2U. The AP non-secure Firmware Updater image. + - SCP_BL2U. The SCP Firmware Update Configuration image. + + Example of Juno command line for generating both ``fwu`` and ``fwu_fip`` + targets using RSA development: + + :: + + MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ + make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ + BL33=<path-to>/<bl33_image> \ + SCP_BL2=<path-to>/<scp_bl2_image> \ + SCP_BL2U=<path-to>/<scp_bl2u_image> \ + NS_BL2U=<path-to>/<ns_bl2u_image> \ + all fip fwu_fip + + .. note:: + The BL2U image will be built by default and added to the FWU_FIP. + The user may override this by adding ``BL2U=<path-to>/<bl2u_image>`` + to the command line above. + + .. note:: + Building and installing the non-secure and SCP FWU images (NS_BL1U, + NS_BL2U and SCP_BL2U) is outside the scope of this document. + + The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. + Both the FIP and FWU_FIP will include the certificates corresponding to the + Chain of Trust described in the TBBR-client document. These certificates + can also be found in the output build directory. + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* + +.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git +.. _mbed TLS Security Center: https://tls.mbed.org/security diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index 82be272bf..49e8adb98 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -8,8 +8,9 @@ Public-Key-Cryptography Standards (PKCS). This document describes the design of Trusted Firmware-A (TF-A) TBB, which is an implementation of the `Trusted Board Boot Requirements (TBBR)`_ specification, -Arm DEN0006D. It should be used in conjunction with the `Firmware Update`_ -design document, which implements a specific aspect of the TBBR. +Arm DEN0006D. It should be used in conjunction with the +:ref:`Firmware Update (FWU)` design document, which implements a specific aspect +of the TBBR. Chain of Trust -------------- @@ -186,7 +187,8 @@ The next step is executed for all the boot loader images. The Trusted Board Boot implementation spans both generic and platform-specific BL1 and BL2 code, and in tool code on the host build machine. The feature is -enabled through use of specific build flags as described in the `User Guide`_. +enabled through use of specific build flags as described in +:ref:`Build Options`. On the host machine, a tool generates the certificates, which are included in the FIP along with the boot loader images. These certificates are loaded in @@ -201,10 +203,11 @@ Authentication Framework The authentication framework included in TF-A provides support to implement the desired trusted boot sequence. Arm platforms use this framework to -implement the boot requirements specified in the `TBBR-client`_ document. +implement the boot requirements specified in the +`Trusted Board Boot Requirements (TBBR)`_ document. More information about the authentication framework can be found in the -`Auth Framework`_ document. +:ref:`Authentication Framework & Chain of Trust` document. Certificate Generation Tool --------------------------- @@ -219,17 +222,16 @@ passed as inputs to the ``fiptool`` utility for creating the FIP. The certificates are also stored individually in the in the output build directory. -The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL -library version 1.0.1 or later to generate the X.509 certificates. Instructions -for building and using the tool can be found in the `User Guide`_. +The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL +library version to generate the X.509 certificates. The specific version of the +library that is required is given in the :ref:`Prerequisites` document. + +Instructions for building and using the tool can be found at +:ref:`tools_build_cert_create`. -------------- *Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* -.. _Firmware Update: ../components/firmware-update.rst .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt -.. _User Guide: ../getting_started/user-guide.rst -.. _Auth Framework: auth-framework.rst -.. _TBBR-client: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a -.. _Trusted Board Boot Requirements (TBBR): `TBBR-client`_ +.. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst new file mode 100644 index 000000000..2f44fe817 --- /dev/null +++ b/docs/getting_started/build-options.rst @@ -0,0 +1,660 @@ +Build Options +============= + +The TF-A build system supports the following build options. Unless mentioned +otherwise, these options are expected to be specified at the build command +line and are not to be modified in any component makefiles. Note that the +build system doesn't track dependency for build options. Therefore, if any of +the build options are changed from a previous build, a clean build must be +performed. + +.. _build_options_common: + +Common build options +-------------------- + +- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the + compiler should use. Valid values are T32 and A32. It defaults to T32 due to + code having a smaller resulting size. + +- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as + as the BL32 image when ``ARCH=aarch32``. The value should be the path to the + directory containing the SP source, relative to the ``bl32/``; the directory + is expected to contain a makefile called ``<aarch32_sp-value>.mk``. + +- ``ARCH`` : Choose the target build architecture for TF-A. It can take either + ``aarch64`` or ``aarch32`` as values. By default, it is defined to + ``aarch64``. + +- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when + compiling TF-A. Its value must be numeric, and defaults to 8 . See also, + *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in + :ref:`Firmware Design`. + +- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when + compiling TF-A. Its value must be a numeric, and defaults to 0. See also, + *Armv8 Architecture Extensions* in :ref:`Firmware Design`. + +- ``BL2``: This is an optional build option which specifies the path to BL2 + image for the ``fip`` target. In this case, the BL2 in the TF-A will not be + built. + +- ``BL2U``: This is an optional build option which specifies the path to + BL2U image. In this case, the BL2U in TF-A will not be built. + +- ``BL2_AT_EL3``: This is an optional build option that enables the use of + BL2 at EL3 execution level. + +- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place + (XIP) memory, like BL1. In these use-cases, it is necessary to initialize + the RW sections in RAM, while leaving the RO sections in place. This option + enable this use-case. For now, this option is only supported when BL2_AT_EL3 + is set to '1'. + +- ``BL31``: This is an optional build option which specifies the path to + BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not + be built. + +- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the + file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``, + this file name will be used to save the key. + +- ``BL32``: This is an optional build option which specifies the path to + BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not + be built. + +- ``BL32_EXTRA1``: This is an optional build option which specifies the path to + Trusted OS Extra1 image for the ``fip`` target. + +- ``BL32_EXTRA2``: This is an optional build option which specifies the path to + Trusted OS Extra2 image for the ``fip`` target. + +- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the + file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``, + this file name will be used to save the key. + +- ``BL33``: Path to BL33 image in the host file system. This is mandatory for + ``fip`` target in case TF-A BL2 is used. + +- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the + file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``, + this file name will be used to save the key. + +- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication + and ARMv8.5 Branch Target Identification support for TF-A BL images themselves. + If enabled, it is needed to use a compiler that supports the option + ``-mbranch-protection``. Selects the branch protection features to use: +- 0: Default value turns off all types of branch protection +- 1: Enables all types of branch protection features +- 2: Return address signing to its standard level +- 3: Extend the signing to include leaf functions + + The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options + and resulting PAuth/BTI features. + + +-------+--------------+-------+-----+ + | Value | GCC option | PAuth | BTI | + +=======+==============+=======+=====+ + | 0 | none | N | N | + +-------+--------------+-------+-----+ + | 1 | standard | Y | Y | + +-------+--------------+-------+-----+ + | 2 | pac-ret | Y | N | + +-------+--------------+-------+-----+ + | 3 | pac-ret+leaf | Y | N | + +-------+--------------+-------+-----+ + + This option defaults to 0 and this is an experimental feature. + Note that Pointer Authentication is enabled for Non-secure world + irrespective of the value of this option if the CPU supports it. + +- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the + compilation of each build. It must be set to a C string (including quotes + where applicable). Defaults to a string that contains the time and date of + the compilation. + +- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A + build to be uniquely identified. Defaults to the current git commit id. + +- ``CFLAGS``: Extra user options appended on the compiler's command line in + addition to the options set by the build system. + +- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may + release several CPUs out of reset. It can take either 0 (several CPUs may be + brought up) or 1 (only one CPU will ever be brought up during cold reset). + Default is 0. If the platform always brings up a single CPU, there is no + need to distinguish between primary and secondary CPUs and the boot path can + be optimised. The ``plat_is_my_cpu_primary()`` and + ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need + to be implemented in this case. + +- ``COT``: When Trusted Boot is enabled, selects the desired chain of trust. + Defaults to ``tbbr``. + +- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor + register state when an unexpected exception occurs during execution of + BL31. This option defaults to the value of ``DEBUG`` - i.e. by default + this is only enabled for a debug build of the firmware. + +- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the + certificate generation tool to create new keys in case no valid keys are + present or specified. Allowed options are '0' or '1'. Default is '1'. + +- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause + the AArch32 system registers to be included when saving and restoring the + CPU context. The option must be set to 0 for AArch64-only platforms (that + is on hardware that does not implement AArch32, or at least not at EL1 and + higher ELs). Default value is 1. + +- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP + registers to be included when saving and restoring the CPU context. Default + is 0. + +- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables + Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth + registers to be included when saving and restoring the CPU context as + part of world switch. Default value is 0 and this is an experimental feature. + Note that Pointer Authentication is enabled for Non-secure world irrespective + of the value of this flag if the CPU supports it. + +- ``DEBUG``: Chooses between a debug and release build. It can take either 0 + (release) or 1 (debug) as values. 0 is the default. + +- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation + of the binary image. If set to 1, then only the ELF image is built. + 0 is the default. + +- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted + Board Boot authentication at runtime. This option is meant to be enabled only + for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this + flag has to be enabled. 0 is the default. + +- ``E``: Boolean option to make warnings into errors. Default is 1. + +- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of + the normal boot flow. It must specify the entry point address of the EL3 + payload. Please refer to the "Booting an EL3 payload" section for more + details. + +- ``ENABLE_AMU``: Boolean option to enable Activity Monitor Unit extensions. + This is an optional architectural feature available on v8.4 onwards. Some + v8.2 implementations also implement an AMU and this option can be used to + enable this feature on those systems as well. Default is 0. + +- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()`` + are compiled out. For debug builds, this option defaults to 1, and calls to + ``assert()`` are left in place. For release builds, this option defaults to 0 + and calls to ``assert()`` function are compiled out. This option can be set + independently of ``DEBUG``. It can also be used to hide any auxiliary code + that is only required for the assertion and does not fit in the assertion + itself. + +- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace + dumps or not. It is supported in both AArch64 and AArch32. However, in + AArch32 the format of the frame records are not defined in the AAPCS and they + are defined by the implementation. This implementation of backtrace only + supports the format used by GCC when T32 interworking is disabled. For this + reason enabling this option in AArch32 will force the compiler to only + generate A32 code. This option is enabled by default only in AArch64 debug + builds, but this behaviour can be overridden in each platform's Makefile or + in the build command line. + +- ``ENABLE_LTO``: Boolean option to enable Link Time Optimization (LTO) + support in GCC for TF-A. This option is currently only supported for + AArch64. Default is 0. + +- ``ENABLE_MPAM_FOR_LOWER_ELS``: Boolean option to enable lower ELs to use MPAM + feature. MPAM is an optional Armv8.4 extension that enables various memory + system components and resources to define partitions; software running at + various ELs can assign themselves to desired partition to control their + performance aspects. + + When this option is set to ``1``, EL3 allows lower ELs to access their own + MPAM registers without trapping into EL3. This option doesn't make use of + partitioning in EL3, however. Platform initialisation code should configure + and use partitions in EL3 as required. This option defaults to ``0``. + +- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE) + support within generic code in TF-A. This option is currently only supported + in BL2_AT_EL3, BL31, and BL32 (TSP). Default is 0. + +- ``ENABLE_PMF``: Boolean option to enable support for optional Performance + Measurement Framework(PMF). Default is 0. + +- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI + functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0. + In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must + be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in + software. + +- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime + instrumentation which injects timestamp collection points into TF-A to + allow runtime performance to be measured. Currently, only PSCI is + instrumented. Enabling this option enables the ``ENABLE_PMF`` build option + as well. Default is 0. + +- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling + extensions. This is an optional architectural feature for AArch64. + The default is 1 but is automatically disabled when the target architecture + is AArch32. + +- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension + (SVE) for the Non-secure world only. SVE is an optional architectural feature + for AArch64. Note that when SVE is enabled for the Non-secure world, access + to SIMD and floating-point functionality from the Secure world is disabled. + This is to avoid corruption of the Non-secure world data in the Z-registers + which are aliased by the SIMD and FP registers. The build option is not + compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an + assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS`` set to + 1. The default is 1 but is automatically disabled when the target + architecture is AArch32. + +- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection + checks in GCC. Allowed values are "all", "strong", "default" and "none". The + default value is set to "none". "strong" is the recommended stack protection + level if this feature is desired. "none" disables the stack protection. For + all values other than "none", the ``plat_get_stack_protector_canary()`` + platform hook needs to be implemented. The value is passed as the last + component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``. + +- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of + deprecated platform APIs, helper functions or drivers within Trusted + Firmware as error. It can take the value 1 (flag the use of deprecated + APIs as error) or 0. The default is 0. + +- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions + targeted at EL3. When set ``0`` (default), no exceptions are expected or + handled at EL3, and a panic will result. This is supported only for AArch64 + builds. + +- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault + injection from lower ELs, and this build option enables lower ELs to use + Error Records accessed via System Registers to inject faults. This is + applicable only to AArch64 builds. + + This feature is intended for testing purposes only, and is advisable to keep + disabled for production images. + +- ``FIP_NAME``: This is an optional build option which specifies the FIP + filename for the ``fip`` target. Default is ``fip.bin``. + +- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU + FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``. + +- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create`` + tool to create certificates as per the Chain of Trust described in + :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to + include the certificates in the FIP and FWU_FIP. Default value is '0'. + + Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support + for the Trusted Board Boot feature in the BL1 and BL2 images, to generate + the corresponding certificates, and to include those certificates in the + FIP and FWU_FIP. + + Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2 + images will not include support for Trusted Board Boot. The FIP will still + include the corresponding certificates. This FIP can be used to verify the + Chain of Trust on the host machine through other mechanisms. + + Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2 + images will include support for Trusted Board Boot, but the FIP and FWU_FIP + will not include the corresponding certificates, causing a boot failure. + +- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have + inherent support for specific EL3 type interrupts. Setting this build option + to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both + by `platform abstraction layer`__ and `Interrupt Management Framework`__. + This allows GICv2 platforms to enable features requiring EL3 interrupt type. + This also means that all GICv2 Group 0 interrupts are delivered to EL3, and + the Secure Payload interrupts needs to be synchronously handed over to Secure + EL1 for handling. The default value of this option is ``0``, which means the + Group 0 interrupts are assumed to be handled by Secure EL1. + + .. __: `platform-interrupt-controller-API.rst` + .. __: `interrupt-framework-design.rst` + +- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError + Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to + ``0`` (default), these exceptions will be trapped in the current exception + level (or in EL1 if the current exception level is EL0). + +- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific + software operations are required for CPUs to enter and exit coherency. + However, newer systems exist where CPUs' entry to and exit from coherency + is managed in hardware. Such systems require software to only initiate these + operations, and the rest is managed in hardware, minimizing active software + management. In such systems, this boolean option enables TF-A to carry out + build and run-time optimizations during boot and power management operations. + This option defaults to 0 and if it is enabled, then it implies + ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled. + + If this flag is disabled while the platform which TF-A is compiled for + includes cores that manage coherency in hardware, then a compilation error is + generated. This is based on the fact that a system cannot have, at the same + time, cores that manage coherency in hardware and cores that don't. In other + words, a platform cannot have, at the same time, cores that require + ``HW_ASSISTED_COHERENCY=1`` and cores that require + ``HW_ASSISTED_COHERENCY=0``. + + Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of + translation library (xlat tables v2) must be used; version 1 of translation + library is not supported. + +- ``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. + +- ``KEY_ALG``: This build flag enables the user to select the algorithm to be + used for generating the PKCS keys and subsequent signing of the certificate. + It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option + ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR + compliant and is retained only for compatibility. The default value of this + flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme. + +- ``KEY_SIZE``: This build flag enables the user to select the key size for + the algorithm specified by ``KEY_ALG``. The valid values for ``KEY_SIZE`` + depend on the chosen algorithm and the cryptographic module. + + +-----------+------------------------------------+ + | KEY_ALG | Possible key sizes | + +===========+====================================+ + | rsa | 1024 , 2048 (default), 3072, 4096* | + +-----------+------------------------------------+ + | ecdsa | unavailable | + +-----------+------------------------------------+ + + * Only 2048 bits size is available with CryptoCell 712 SBROM release 1. + Only 3072 bits size is available with CryptoCell 712 SBROM release 2. + +- ``HASH_ALG``: This build flag enables the user to select the secure hash + algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``. + The default value of this flag is ``sha256``. + +- ``LDFLAGS``: Extra user options appended to the linkers' command line in + addition to the one set by the build system. + +- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log + output compiled into the build. This should be one of the following: + + :: + + 0 (LOG_LEVEL_NONE) + 10 (LOG_LEVEL_ERROR) + 20 (LOG_LEVEL_NOTICE) + 30 (LOG_LEVEL_WARNING) + 40 (LOG_LEVEL_INFO) + 50 (LOG_LEVEL_VERBOSE) + + All log output up to and including the selected log level is compiled into + the build. The default value is 40 in debug builds and 20 in release builds. + +- ``MEASURED_BOOT``: Boolean flag to include support for the Measured Boot + feature. If this flag is enabled ``TRUSTED_BOARD_BOOT`` must be set. + This option defaults to 0 and is an experimental feature in the stage of + development. + +- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It + specifies the file that contains the Non-Trusted World private key in PEM + format. If ``SAVE_KEYS=1``, this file name will be used to save the key. + +- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is + optional. It is only needed if the platform makefile specifies that it + is required in order to build the ``fwu_fip`` target. + +- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register + contents upon world switch. It can take either 0 (don't save and restore) or + 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it + wants the timer registers to be saved and restored. + +- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc + for the BL image. It can be either 0 (include) or 1 (remove). The default + value is 0. + +- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that + the underlying hardware is not a full PL011 UART but a minimally compliant + generic UART, which is a subset of the PL011. The driver will not access + any register that is not part of the SBSA generic UART specification. + Default value is 0 (a full PL011 compliant UART is present). + +- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name + must be subdirectory of any depth under ``plat/``, and must contain a + platform makefile named ``platform.mk``. For example, to build TF-A for the + Arm Juno board, select PLAT=juno. + +- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image + instead of the normal boot flow. When defined, it must specify the entry + point address for the preloaded BL33 image. This option is incompatible with + ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority + over ``PRELOADED_BL33_BASE``. + +- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset + vector address can be programmed or is fixed on the platform. It can take + either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a + programmable reset address, it is expected that a CPU will start executing + code directly at the right address, both on a cold and warm reset. In this + case, there is no need to identify the entrypoint on boot and the boot path + can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface + does not need to be implemented in this case. + +- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats + possible for the PSCI power-state parameter: original and extended State-ID + formats. This flag if set to 1, configures the generic PSCI layer to use the + extended format. The default value of this flag is 0, which means by default + the original power-state format is used by the PSCI implementation. This flag + should be specified by the platform makefile and it governs the return value + of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is + enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be + set to 1 as well. + +- ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features + are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2 + or later CPUs. + + When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST`` must also be + set to ``1``. + + This option is disabled by default. + +- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead + of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 + entrypoint) or 1 (CPU reset to BL31 entrypoint). + The default value is 0. + +- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided + in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector + instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 + entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0. + +- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the + file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this + file name will be used to save the key. + +- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the + certificate generation tool to save the keys used to establish the Chain of + Trust. Allowed options are '0' or '1'. Default is '0' (do not save). + +- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional. + If a SCP_BL2 image is present then this option must be passed for the ``fip`` + target. + +- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the + file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``, + this file name will be used to save the key. + +- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is + optional. It is only needed if the platform makefile specifies that it + is required in order to build the ``fwu_fip`` target. + +- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software + Delegated Exception Interface to BL31 image. This defaults to ``0``. + + When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be + set to ``1``. + +- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be + isolated on separate memory pages. This is a trade-off between security and + memory usage. See "Isolating code and read-only data on separate memory + pages" section in :ref:`Firmware Design`. This flag is disabled by default and + affects all BL images. + +- ``SEPARATE_NOBITS_REGION``: Setting this option to ``1`` allows the NOBITS + sections of BL31 (.bss, stacks, page tables, and coherent memory) to be + allocated in RAM discontiguous from the loaded firmware image. When set, the + platform is expected to provide definitons for ``BL31_NOBITS_BASE`` and + ``BL31_NOBITS_LIMIT``. When the option is ``0`` (the default), NOBITS + sections are placed in RAM immediately following the loaded firmware image. + +- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A. + This build option is only valid if ``ARCH=aarch64``. The value should be + the path to the directory containing the SPD source, relative to + ``services/spd/``; the directory is expected to contain a makefile called + ``<spd-value>.mk``. + +- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can + take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops + execution in BL1 just before handing over to BL31. At this point, all + firmware images have been loaded in memory, and the MMU and caches are + turned off. Refer to the "Debugging options" section for more details. + +- ``SPM_MM`` : Boolean option to enable the Management Mode (MM)-based Secure + Partition Manager (SPM) implementation. The default value is ``0``. + +- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles + secure interrupts (caught through the FIQ line). Platforms can enable + this directive if they need to handle such interruption. When enabled, + the FIQ are handled in monitor mode and non secure world is not allowed + to mask these events. Platforms that enable FIQ handling in SP_MIN shall + implement the api ``sp_min_plat_fiq_handler()``. The default value is 0. + +- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board + Boot feature. When set to '1', BL1 and BL2 images include support to load + and verify the certificates and images in a FIP, and BL1 includes support + for the Firmware Update. The default value is '0'. Generation and inclusion + of certificates in the FIP and FWU_FIP depends upon the value of the + ``GENERATE_COT`` option. + + .. warning:: + This option depends on ``CREATE_KEYS`` to be enabled. If the keys + already exist in disk, they will be overwritten without further notice. + +- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It + specifies the file that contains the Trusted World private key in PEM + format. If ``SAVE_KEYS=1``, this file name will be used to save the key. + +- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or + synchronous, (see "Initializing a BL32 Image" section in + :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using + synchronous method) or 1 (BL32 is initialized using asynchronous method). + Default is 0. + +- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt + routing model which routes non-secure interrupts asynchronously from TSP + to EL3 causing immediate preemption of TSP. The EL3 is responsible + for saving and restoring the TSP context in this routing model. The + default routing model (when the value is 0) is to route non-secure + interrupts to TSP allowing it to save its context and hand over + synchronously to EL3 via an SMC. + + .. note:: + When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` + must also be set to ``1``. + +- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM + linker. When the ``LINKER`` build variable points to the armlink linker, + this flag is enabled automatically. To enable support for armlink, platforms + will have to provide a scatter file for the BL image. Currently, Tegra + platforms use the armlink support to compile BL3-1 images. + +- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent + memory region in the BL memory map or not (see "Use of Coherent memory in + TF-A" section in :ref:`Firmware Design`). It can take the value 1 + (Coherent memory region is included) or 0 (Coherent memory region is + excluded). Default is 1. + +- ``USE_DEBUGFS``: When set to 1 this option activates an EXPERIMENTAL feature + exposing a virtual filesystem interface through BL31 as a SiP SMC function. + Default is 0. + +- ``USE_ROMLIB``: This flag determines whether library at ROM will be used. + This feature creates a library of functions to be placed in ROM and thus + reduces SRAM usage. Refer to :ref:`Library at ROM` for further details. Default + is 0. + +- ``V``: Verbose build. If assigned anything other than 0, the build commands + are printed. Default is 0. + +- ``VERSION_STRING``: String used in the log output for each TF-A image. + Defaults to a string formed by concatenating the version number, build type + and build string. + +- ``W``: Warning level. Some compiler warning options of interest have been + regrouped and put in the root Makefile. This flag can take the values 0 to 3, + each level enabling more warning options. Default is 0. + +- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on + the CPU after warm boot. This is applicable for platforms which do not + require interconnect programming to enable cache coherency (eg: single + cluster platforms). If this option is enabled, then warm boot path + enables D-caches immediately after enabling MMU. This option defaults to 0. + +Debugging options +----------------- + +To compile a debug version and make the build more verbose use + +.. code:: shell + + make PLAT=<platform> DEBUG=1 V=1 all + +AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for +example DS-5) might not support this and may need an older version of DWARF +symbols to be emitted by GCC. This can be achieved by using the +``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the +version to 2 is recommended for DS-5 versions older than 5.16. + +When debugging logic problems it might also be useful to disable all compiler +optimizations by using ``-O0``. + +.. warning:: + Using ``-O0`` could cause output images to be larger and base addresses + might need to be recalculated (see the **Memory layout on Arm development + platforms** section in the :ref:`Firmware Design`). + +Extra debug options can be passed to the build system by setting ``CFLAGS`` or +``LDFLAGS``: + +.. code:: shell + + CFLAGS='-O0 -gdwarf-2' \ + make PLAT=<platform> DEBUG=1 V=1 all + +Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be +ignored as the linker is called directly. + +It is also possible to introduce an infinite loop to help in debugging the +post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the +``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the :ref:`build_options_common` +section. In this case, the developer may take control of the target using a +debugger when indicated by the console output. When using DS-5, the following +commands can be used: + +:: + + # Stop target execution + interrupt + + # + # Prepare your debugging environment, e.g. set breakpoints + # + + # Jump over the debug loop + set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4 + + # Resume execution + continue + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst new file mode 100644 index 000000000..91b1b3a39 --- /dev/null +++ b/docs/getting_started/docs-build.rst @@ -0,0 +1,88 @@ +Building Documentation +====================== + +To create a rendered copy of this documentation locally you can use the +`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted +pages. + +If you are building the documentation for the first time then you will need to +check that you have the required software packages, as described in the +*Prerequisites* section that follows. + +.. note:: + An online copy of the documentation is available at + https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered + copy without doing a local build. + +Prerequisites +------------- + +For building a local copy of the |TF-A| documentation you will need, at minimum: + +- Python 3 (3.5 or later) +- PlantUML (1.2017.15 or later) + +Optionally, the `Dia`_ application can be installed if you need to edit +existing ``.dia`` diagram files, or create new ones. + +You must also install the Python modules that are specified in the +``requirements.txt`` file in the root of the ``docs`` directory. These modules +can be installed using ``pip3`` (the Python Package Installer). Passing this +requirements file as an argument to ``pip3`` automatically installs the specific +module versions required by |TF-A|. + +An example set of installation commands for Ubuntu 18.04 LTS follows, assuming +that the working directory is ``docs``: + +.. code:: shell + + sudo apt install python3 python3-pip plantuml [dia] + pip3 install [--user] -r requirements.txt + +.. note:: + Several other modules will be installed as dependencies. Please review + the list to ensure that there will be no conflicts with other modules already + installed in your environment. + +Passing the optional ``--user`` argument to ``pip3`` will install the Python +packages only for the current user. Omitting this argument will attempt to +install the packages globally and this will likely require the command to be run +as root or using ``sudo``. + +.. note:: + More advanced usage instructions for *pip* are beyond the scope of this + document but you can refer to the `pip homepage`_ for detailed guides. + +Building rendered documentation +------------------------------- + +Documents can be built into HTML-formatted pages from project root directory by +running the following command. + +.. code:: shell + + make doc + +Output from the build process will be placed in: + +:: + + docs/build/html/ + +We also support building documentation in other formats. From the ``docs`` +directory of the project, run the following command to see the supported +formats. It is important to note that you will not get the correct result if +the command is run from the project root directory, as that would invoke the +top-level Makefile for |TF-A| itself. + +.. code:: shell + + make help + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* + +.. _Sphinx: http://www.sphinx-doc.org/en/master/ +.. _pip homepage: https://pip.pypa.io/en/stable/ +.. _Dia: https://wiki.gnome.org/Apps/Dia diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst index d9e08f76c..5993d6e7a 100644 --- a/docs/getting_started/image-terminology.rst +++ b/docs/getting_started/image-terminology.rst @@ -7,7 +7,7 @@ images referred to in the Trusted Firmware project. General Notes ------------- -- Some of the names and abbreviated names have changed to accomodate new +- Some of the names and abbreviated names have changed to accommodate new requirements. The changed names are as backward compatible as possible to minimize confusion. Where applicable, the previous names are indicated. Some code, documentation and build artefacts may still refer to the previous names; @@ -44,7 +44,7 @@ AP Boot ROM: ``AP_BL1`` ~~~~~~~~~~~~~~~~~~~~~~~ Typically, this is the first code to execute on the AP and cannot be modified. -Its primary purpose is to perform the minimum intialization necessary to load +Its primary purpose is to perform the minimum initialization necessary to load and authenticate an updateable AP firmware image into an executable RAM location, then hand-off control to that image. @@ -96,7 +96,7 @@ SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Typically, this is the first code to execute on the SCP and cannot be modified. -Its primary purpose is to perform the minimum intialization necessary to load +Its primary purpose is to perform the minimum initialization necessary to load and authenticate an updateable SCP firmware image into an executable RAM location, then hand-off control to that image. This may be performed in conjunction with other processor firmware (for example, ``AP_BL1`` and @@ -129,7 +129,7 @@ AP Firmware Update Boot ROM: ``AP_NS_BL1U`` Typically, this is the first normal world code to execute on the AP during a firmware update operation, and cannot be modified. Its primary purpose is to -load subequent firmware update images from an external interface and communicate +load subsequent firmware update images from an external interface and communicate with ``AP_BL1`` to authenticate those images. During firmware update, there are (potentially) multiple transitions between the diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 23608f860..817beaf8e 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -6,8 +6,16 @@ Getting Started :caption: Contents :numbered: - user-guide + prerequisites + docs-build + tools-build + initial-build + build-options image-terminology porting-guide psci-lib-integration-guide rt-svc-writers-guide + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/initial-build.rst b/docs/getting_started/initial-build.rst new file mode 100644 index 000000000..d4a8f0114 --- /dev/null +++ b/docs/getting_started/initial-build.rst @@ -0,0 +1,118 @@ +Performing an Initial Build +=========================== + +- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point + to the Linaro cross compiler. + + For AArch64: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + + For AArch32: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-none-eabi- + + It is possible to build TF-A using Clang or Arm Compiler 6. To do so + ``CC`` needs to point to the clang or armclang binary, which will + also select the clang or armclang assembler. Be aware that for Arm Compiler, + the GNU linker is used by default. However for Clang LLVM linker (LLD) + is used by default. In case of being needed the linker can be overridden + using the ``LD`` variable. LLVM linker (LLD) version 9 is + known to work with TF-A. + + In both cases ``CROSS_COMPILE`` should be set as described above. + + Arm Compiler 6 will be selected when the base name of the path assigned + to ``CC`` matches the string 'armclang'. + + For AArch64 using Arm Compiler 6: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all + + Clang will be selected when the base name of the path assigned to ``CC`` + contains the string 'clang'. This is to allow both clang and clang-X.Y + to work. + + For AArch64 using clang: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + make CC=<path-to-clang>/bin/clang PLAT=<platform> all + +- Change to the root directory of the TF-A source tree and build. + + For AArch64: + + .. code:: shell + + make PLAT=<platform> all + + For AArch32: + + .. code:: shell + + make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all + + Notes: + + - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the + :ref:`Build Options` document for more information on available build + options. + + - (AArch32 only) Currently only ``PLAT=fvp`` is supported. + + - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it + corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is + provided by TF-A to demonstrate how PSCI Library can be integrated with + an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may + include other runtime services, for example Trusted OS services. A guide + to integrate PSCI library with AArch32 EL3 Runtime Software can be found + at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`. + + - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32 + image, is not compiled in by default. Refer to the + :ref:`Test Secure Payload (TSP) and Dispatcher (TSPD)` document for + details on building the TSP. + + - By default this produces a release version of the build. To produce a + debug version instead, refer to the "Debugging options" section below. + + - The build process creates products in a ``build`` directory tree, building + the objects and binaries for each boot loader stage in separate + sub-directories. The following boot loader binary files are created + from the corresponding ELF files: + + - ``build/<platform>/<build-type>/bl1.bin`` + - ``build/<platform>/<build-type>/bl2.bin`` + - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only) + - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32) + + where ``<platform>`` is the name of the chosen platform and ``<build-type>`` + is either ``debug`` or ``release``. The actual number of images might differ + depending on the platform. + +- Build products for a specific build variant can be removed using: + + .. code:: shell + + make DEBUG=<D> PLAT=<platform> clean + + ... where ``<D>`` is ``0`` or ``1``, as specified when building. + + The build tree can be removed completely using: + + .. code:: shell + + make realclean + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index b327f6ee3..bb1471752 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -13,20 +13,18 @@ Modifications consist of: - Defining certain constants (for example #defines). The platform-specific functions and variables are declared in -`include/plat/common/platform.h`_. The firmware provides a default implementation -of variables and functions to fulfill the optional requirements. These -implementations are all weakly defined; they are provided to ease the porting -effort. Each platform port can override them with its own implementation if the -default implementation is inadequate. +``include/plat/common/platform.h``. The firmware provides a default +implementation of variables and functions to fulfill the optional requirements. +These implementations are all weakly defined; they are provided to ease the +porting effort. Each platform port can override them with its own implementation +if the default implementation is inadequate. Some modifications are common to all Boot Loader (BL) stages. Section 2 discusses these in detail. The subsequent sections discuss the remaining modifications for each BL stage in detail. -This document should be read in conjunction with the TF-A `User Guide`_. - -Please refer to the `Platform compatibility policy`_ for the policy regarding -compatibility and deprecation of these porting interfaces. +Please refer to the :ref:`Platform Compatibility Policy` for the policy +regarding compatibility and deprecation of these porting interfaces. Only Arm development platforms (such as FVP and Juno) may use the functions/definitions in ``include/plat/arm/common/`` and the corresponding @@ -98,7 +96,7 @@ Each platform must ensure that a header file of this name is in the system include path with the following constants defined. This will require updating the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. -Platform ports may optionally use the file `include/plat/common/common_def.h`_, +Platform ports may optionally use the file ``include/plat/common/common_def.h``, which provides typical values for some of the constants below. These values are likely to be suitable for all platform ports. @@ -115,8 +113,8 @@ likely to be suitable for all platform ports. - **#define : PLATFORM_STACK_SIZE** Defines the normal stack memory available to each CPU. This constant is used - by `plat/common/aarch64/platform_mp_stack.S`_ and - `plat/common/aarch64/platform_up_stack.S`_. + by ``plat/common/aarch64/platform_mp_stack.S`` and + ``plat/common/aarch64/platform_up_stack.S``. - **define : CACHE_WRITEBACK_GRANULE** @@ -542,10 +540,17 @@ optionally be defined: Maximum number of partition entries required by the platform. This allows control how much memory is allocated for partition entries. The default value is 128. - `For example, define the build flag in platform.mk`_: + For example, define the build flag in ``platform.mk``: PLAT_PARTITION_MAX_ENTRIES := 12 $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES)) +- **PLAT_PARTITION_BLOCK_SIZE** + The size of partition block. It could be either 512 bytes or 4096 bytes. + The default value is 512. + For example, define the build flag in ``platform.mk``: + PLAT_PARTITION_BLOCK_SIZE := 4096 + $(eval $(call add_define,PLAT_PARTITION_BLOCK_SIZE)) + The following constant is optional. It should be defined to override the default behaviour of the ``assert()`` function (for example, to save memory). @@ -821,7 +826,8 @@ runtime environment. This function can clobber x0 - x8 and must preserve x9 - x29. This function plays a crucial role in the power domain topology framework in -PSCI and details of this can be found in `Power Domain Topology Design`_. +PSCI and details of this can be found in +:ref:`PSCI Power Domain Tree Structure`. Function : plat_core_pos_by_mpidr() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -837,7 +843,7 @@ case the ``MPIDR`` is invalid, this function returns -1. This function will only be invoked by BL31 after the power domain topology is initialized and can utilize the C runtime environment. For further details about how TF-A represents the power domain topology and how this relates to the linear CPU -index, please refer `Power Domain Topology Design`_. +index, please refer :ref:`PSCI Power Domain Tree Structure`. Function : plat_get_mbedtls_heap() [when TRUSTED_BOARD_BOOT == 1] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -888,8 +894,8 @@ of the stack allocated to each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``. Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform_up_stack.S`_ and -`plat/common/aarch64/platform_mp_stack.S`_ +provided in ``plat/common/aarch64/platform_up_stack.S`` and +``plat/common/aarch64/platform_mp_stack.S`` Function : plat_get_my_stack() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -906,8 +912,8 @@ of the stack allocated to each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``. Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform_up_stack.S`_ and -`plat/common/aarch64/platform_mp_stack.S`_ +provided in ``plat/common/aarch64/platform_up_stack.S`` and +``plat/common/aarch64/platform_mp_stack.S`` Function : plat_report_exception() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -930,12 +936,12 @@ about the way the platform displays its status information. For AArch64, this function receives the exception type as its argument. Possible values for exceptions types are listed in the -`include/common/bl_common.h`_ header file. Note that these constants are not +``include/common/bl_common.h`` header file. Note that these constants are not related to any architectural exception code; they are just a TF-A convention. For AArch32, this function receives the exception mode as its argument. Possible values for exception modes are listed in the -`include/lib/aarch32/arch.h`_ header file. +``include/lib/aarch32/arch.h`` header file. Function : plat_reset_handler() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -946,12 +952,12 @@ Function : plat_reset_handler() Return : void A platform may need to do additional initialization after reset. This function -allows the platform to do the platform specific intializations. Platform +allows the platform to do the platform specific initializations. Platform specific errata workarounds could also be implemented here. The API should preserve the values of callee saved registers x19 to x29. The default implementation doesn't do anything. If a platform needs to override -the default implementation, refer to the `Firmware Design`_ for general +the default implementation, refer to the :ref:`Firmware Design` for general guidelines. Function : plat_disable_acp() @@ -1468,8 +1474,8 @@ Boot Loader Stage 2 (BL2) at EL3 When the platform has a non-TF-A Boot ROM it is desirable to jump directly to BL2 instead of TF-A BL1. In this case BL2 is expected to -execute at EL3 instead of executing at EL1. Refer to the `Firmware -Design`_ for more information. +execute at EL3 instead of executing at EL1. Refer to the :ref:`Firmware Design` +document for more information. All mandatory functions of BL2 must be implemented, except the functions bl2_early_platform_setup and bl2_el3_plat_arch_setup, because @@ -1796,21 +1802,21 @@ defined by the translation library, and can be found in the file On DynamIQ systems, this function must not use stack while enabling MMU, which is how the function in xlat table library version 2 is implemented. -Function : plat_init_apiakey [optional] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Function : plat_init_apkey [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: Argument : void - Return : uint64_t * + Return : uint128_t -This function populates the ``plat_apiakey`` array that contains the values used -to set the ``APIAKey{Hi,Lo}_EL1`` registers. It returns a pointer to this array. +This function returns the 128-bit value which can be used to program ARMv8.3 +pointer authentication keys. The value should be obtained from a reliable source of randomness. This function is only needed if ARMv8.3 pointer authentication is used in the -Trusted Firmware by building with ``ENABLE_PAUTH=1``. +Trusted Firmware by building with ``BRANCH_PROTECTION`` option set to non-zero. Function : plat_get_syscnt_freq2() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1845,6 +1851,8 @@ calculated by the linker then a link time assertion is raised. A compile time assertion is raised if the value of the constant is not aligned to the cache line boundary. +.. _porting_guide_sdei_requirements: + SDEI porting requirements ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1929,7 +1937,7 @@ example, a CPU) is at level 0. If the *power domain* node above a CPU is a logical grouping of CPUs that share some state, then level 1 is that group of CPUs (for example, a cluster), and level 2 is a group of clusters (for example, the system). More details on the power domain topology and its -organization can be found in `Power Domain Topology Design`_. +organization can be found in :ref:`PSCI Power Domain Tree Structure`. BL31's platform initialization code exports a pointer to the platform-specific power management operations required for the PSCI implementation to function @@ -1991,7 +1999,7 @@ Function : plat_psci_stat_get_residency() [optional] :: - Argument : unsigned int, const psci_power_state_t *, int + Argument : unsigned int, const psci_power_state_t *, unsigned int Return : u_register_t This is an optional interface that is is invoked after resuming from a low power @@ -2041,13 +2049,13 @@ Function : plat_get_power_domain_tree_desc() [mandatory] This function returns a pointer to the byte array containing the power domain topology tree description. The format and method to construct this array are -described in `Power Domain Topology Design`_. The BL31 PSCI initialization code -requires this array to be described by the platform, either statically or -dynamically, to initialize the power domain topology tree. In case the array -is populated dynamically, then plat_core_pos_by_mpidr() and -plat_my_core_pos() should also be implemented suitably so that the topology -tree description matches the CPU indices returned by these APIs. These APIs -together form the platform interface for the PSCI topology framework. +described in :ref:`PSCI Power Domain Tree Structure`. The BL31 PSCI +initialization code requires this array to be described by the platform, either +statically or dynamically, to initialize the power domain topology tree. In case +the array is populated dynamically, then plat_core_pos_by_mpidr() and +plat_my_core_pos() should also be implemented suitably so that the topology tree +description matches the CPU indices returned by these APIs. These APIs together +form the platform interface for the PSCI topology framework. Function : plat_setup_psci_ops() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2069,10 +2077,10 @@ pointer with a pointer to BL31's private ``plat_psci_ops`` structure. A description of each member of this structure is given below. Please refer to the Arm FVP specific implementation of these handlers in -`plat/arm/board/fvp/fvp_pm.c`_ as an example. For each PSCI function that the +``plat/arm/board/fvp/fvp_pm.c`` as an example. For each PSCI function that the platform wants to support, the associated operation or operations in this structure must be provided and implemented (Refer section 4 of -`Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI +:ref:`Firmware Design` for the PSCI API supported in TF-A). To disable a PSCI function in a platform port, the operation should be removed from this structure instead of providing an empty implementation. @@ -2202,6 +2210,19 @@ immediately before the CPU was turned on. It indicates which power domains above the CPU might require initialization due to having previously been in low power states. The generic code expects the handler to succeed. +plat_psci_ops.pwr_domain_on_finish_late() [optional] +........................................................... + +This optional function is called by the PSCI implementation after the calling +CPU is fully powered on with respective data caches enabled. The calling CPU and +the associated cluster are guaranteed to be participating in coherency. This +function gives the flexibility to perform any platform-specific actions safely, +such as initialization or modification of shared data structures, without the +overhead of explicit cache maintainace operations. + +The ``target_state`` has a similar meaning as described in the ``pwr_domain_on_finish()`` +operation. The generic code expects the handler to succeed. + plat_psci_ops.pwr_domain_suspend_finish() ......................................... @@ -2347,13 +2368,15 @@ region defined by a base address ``base`` and with a size of ``length`` bytes is protected by ``MEM_PROTECT``. If the region is protected then it must return 0, otherwise it must return a negative number. +.. _porting_guide_imf_in_bl31: + Interrupt Management framework (in BL31) ---------------------------------------- BL31 implements an Interrupt Management Framework (IMF) to manage interrupts generated in either security state and targeted to EL1 or EL2 in the non-secure state or EL3/S-EL1 in the secure state. The design of this framework is -described in the `IMF Design Guide`_ +described in the :ref:`Interrupt Management Framework` A platform should export the following APIs to support the IMF. The following text briefly describes each API and its implementation in Arm standard @@ -2362,8 +2385,8 @@ present in the platform. Arm standard platform layer supports both `Arm Generic Interrupt Controller version 2.0 (GICv2)`_ and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the FVP can be configured to use either GICv2 or GICv3 depending on the build flag -``FVP_USE_GIC_DRIVER`` (See FVP platform specific build options in -`User Guide`_ for more details). +``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more +details). See also: `Interrupt Controller Abstraction APIs`__. @@ -2385,10 +2408,10 @@ the platform IC uses to signal each type of interrupt supported by the framework from a given security state. This API must be invoked at EL3. The first parameter will be one of the ``INTR_TYPE_*`` values (see -`IMF Design Guide`_) indicating the target type of the interrupt, the second parameter is the -security state of the originating execution context. The return result is the -bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1, -FIQ=2. +:ref:`Interrupt Management Framework`) indicating the target type of the +interrupt, the second parameter is the security state of the originating +execution context. The return result is the bit position in the ``SCR_EL3`` +register of the respective interrupt trap: IRQ=1, FIQ=2. In the case of Arm standard platforms using GICv2, S-EL1 interrupts are configured as FIQs and Non-secure interrupts as IRQs from either security @@ -2752,7 +2775,7 @@ more functionality is required, the needed library functions will need to be added to the local implementation. Some C headers have been obtained from `FreeBSD`_ and `SCC`_, while others have -been written specifically for TF-A. Fome implementation files have been obtained +been written specifically for TF-A. Some implementation files have been obtained from `FreeBSD`_, others have been written specifically for TF-A as well. The files can be found in ``include/lib/libc`` and ``lib/libc``. @@ -2771,10 +2794,10 @@ storage access is only required by BL1 and BL2 phases and performed inside the It is mandatory to implement at least one storage driver. For the Arm development platforms the Firmware Image Package (FIP) driver is provided as -the default means to load data from storage (see the "Firmware Image Package" -section in the `User Guide`_). The storage layer is described in the header file -``include/drivers/io/io_storage.h``. The implementation of the common library -is in ``drivers/io/io_storage.c`` and the driver files are located in +the default means to load data from storage (see :ref:`firmware_design_fip`). +The storage layer is described in the header file +``include/drivers/io/io_storage.h``. The implementation of the common library is +in ``drivers/io/io_storage.c`` and the driver files are located in ``drivers/io/``. .. uml:: ../resources/diagrams/plantuml/io_arm_class_diagram.puml @@ -2823,22 +2846,7 @@ amount of open resources per driver. *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* -.. _include/plat/common/platform.h: ../include/plat/common/platform.h -.. _include/plat/arm/common/plat_arm.h: ../include/plat/arm/common/plat_arm.h%5D -.. _User Guide: user-guide.rst -.. _include/plat/common/common_def.h: ../include/plat/common/common_def.h -.. _include/plat/arm/common/arm_def.h: ../include/plat/arm/common/arm_def.h -.. _plat/common/aarch64/platform_mp_stack.S: ../plat/common/aarch64/platform_mp_stack.S -.. _plat/common/aarch64/platform_up_stack.S: ../plat/common/aarch64/platform_up_stack.S -.. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160 -.. _Power Domain Topology Design: ../design/psci-pd-tree.rst -.. _include/common/bl_common.h: ../include/common/bl_common.h -.. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h -.. _Firmware Design: ../design/firmware-design.rst .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _plat/arm/board/fvp/fvp_pm.c: ../plat/arm/board/fvp/fvp_pm.c -.. _Platform compatibility policy: ../process/platform-compatibility-policy.rst -.. _IMF Design Guide: ../design/interrupt-framework-design.rst .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html .. _FreeBSD: https://www.freebsd.org diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst new file mode 100644 index 000000000..3e0c8fff2 --- /dev/null +++ b/docs/getting_started/prerequisites.rst @@ -0,0 +1,136 @@ +Prerequisites +============= + +This document describes the software requirements for building |TF-A| for +AArch32 and AArch64 target platforms. + +It may possible to build |TF-A| with combinations of software packages that are +different from those listed below, however only the software described in this +document can be officially supported. + +Build Host +---------- + +|TF-A| can be built using either a Linux or a Windows machine as the build host. + +A relatively recent Linux distribution is recommended for building |TF-A|. We +have performed tests using Ubuntu 16.04 LTS (64-bit) but other distributions +should also work fine as a base, provided that the necessary tools and libraries +can be installed. + +.. _prerequisites_toolchain: + +Toolchain +--------- + +|TF-A| can be built with any of the following *cross-compiler* toolchains that +target the Armv7-A or Armv8-A architectures: + +- GCC >= 9.2-2019.12 (from the `Arm Developer website`_) +- Clang >= 4.0 +- Arm Compiler >= 6.0 + +In addition, a native compiler is required to build the supporting tools. + +.. note:: + The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE, + Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain. + +.. note:: + For instructions on how to select the cross compiler refer to + :ref:`Performing an Initial Build`. + +.. _prerequisites_software_and_libraries: + +Software and Libraries +---------------------- + +The following tools are required to obtain and build |TF-A|: + +- An appropriate toolchain (see :ref:`prerequisites_toolchain`) +- GNU Make +- Git + +The following libraries must be available to build one or more components or +supporting tools: + +- OpenSSL >= 1.0.1 + + Required to build the cert_create tool. + +The following libraries are required for Trusted Board Boot support: + +- mbed TLS == 2.16.2 (tag: ``mbedtls-2.16.2``) + +These tools are optional: + +- Device Tree Compiler (DTC) >= 1.4.6 + + Needed if you want to rebuild the provided Flattened Device Tree (FDT) + source files (``.dts`` files). DTC is available for Linux through the package + repositories of most distributions. + +- Arm `Development Studio 5 (DS-5)`_ + + The standard software package used for debugging software on Arm development + platforms and |FVP| models. + +Package Installation (Linux) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are using the recommended Ubuntu distribution then you can install the +required packages with the following command: + +.. code:: shell + + sudo apt install build-essential git libssl-dev + +The optional packages can be installed using: + +.. code:: shell + + sudo apt install device-tree-compiler + +Supporting Files +---------------- + +TF-A has been tested with pre-built binaries and file systems from `Linaro +Release 19.06`_. Alternatively, you can build the binaries from source using +instructions in :ref:`Performing an Initial Build`. + +.. _prerequisites_get_source: + +Getting the TF-A Source +----------------------- + +Source code for |TF-A| is maintained in a Git repository hosted on +TrustedFirmware.org. To clone this repository from the server, run the following +in your shell: + +.. code:: shell + + git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" && (cd "trusted-firmware-a" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg) + +This will clone the Git repository also install a *commit hook* that +automatically inserts appropriate *Change-Id:* lines at the end of your +commit messages. These change IDs are required when committing changes that you +intend to push for review via our Gerrit system. + +You can read more about Git hooks in the *githooks* page of the Git documentation, +available at: https://git-scm.com/docs/githooks + +Alternatively, you can clone without the commit hook using: + +.. code:: shell + + git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* + +.. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads +.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes +.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables +.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio +.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06 diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst index 25936d900..1351fff00 100644 --- a/docs/getting_started/psci-lib-integration-guide.rst +++ b/docs/getting_started/psci-lib-integration-guide.rst @@ -437,13 +437,13 @@ The mandatory platform macros are: - PLAT_MAX_PWR_LVL_STATES (optional) - PLAT_PCPU_DATA_SIZE (optional) -The details of these APIs/macros can be found in `Porting Guide`_. +The details of these APIs/macros can be found in the :ref:`Porting Guide`. All platform specific operations for power management are done via ``plat_psci_ops_t`` callbacks registered by the platform when ``plat_setup_psci_ops()`` API is called. The description of each of the callbacks in ``plat_psci_ops_t`` can be found in PSCI section of the -`Porting Guide`_. If any these callbacks are not registered, then the +:ref:`Porting Guide`. If any these callbacks are not registered, then the PSCI API associated with that callback will not be supported by PSCI library. @@ -524,12 +524,12 @@ CPU operations ~~~~~~~~~~~~~~ The CPU operations (cpu_ops) framework implement power down sequence specific -to the CPU and the details of which can be found in the -``CPU specific operations framework`` section of `Firmware Design`_. The TF-A -tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime -Software needs to include the required ``cpu_ops`` in its build. The start and -end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software -via the ``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols. +to the CPU and the details of which can be found at +:ref:`firmware_design_cpu_ops_fwk`. The TF-A tree implements the ``cpu_ops`` +for various supported CPUs and the EL3 Runtime Software needs to include the +required ``cpu_ops`` in its build. The start and end of the ``cpu_ops`` +descriptors must be exported by the EL3 Runtime Software via the +``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols. The ``cpu_ops`` descriptors also include reset sequences and may include errata workarounds for the CPU. The EL3 Runtime Software can choose to call this @@ -538,11 +538,9 @@ workarounds. -------------- -*Copyright (c) 2016-2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2016-2019, Arm Limited and Contributors. All rights reserved.* .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _Porting Guide: ./porting-guide.rst -.. _Firmware Design: ../design/firmware-design.rst diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 6c17a1fb4..5375b659d 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -21,8 +21,8 @@ independent implementation of services for each group, which are then compiled into the BL31 image. This simplifies the integration of common software from Arm to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific software. The common runtime services framework ensures that SMC Functions are -dispatched to their respective service implementation - the `Firmware Design`_ -provides details of how this is achieved. +dispatched to their respective service implementation - the +:ref:`Firmware Design` document provides details of how this is achieved. The interface and operation of the runtime services depends heavily on the concepts and definitions described in the `SMCCC`_, in particular SMC Function @@ -79,11 +79,11 @@ handler will be responsible for all SMC Functions within a given service type. Getting started --------------- -TF-A has a `services`_ directory in the source tree under which +TF-A has a ``services`` directory in the source tree under which each owning entity can place the implementation of its runtime service. The -`PSCI`_ implementation is located here in the `lib/psci`_ directory. +`PSCI`_ implementation is located here in the ``lib/psci`` directory. -Runtime service sources will need to include the `runtime_svc.h`_ header file. +Runtime service sources will need to include the ``runtime_svc.h`` header file. Registering a runtime service ----------------------------- @@ -100,7 +100,7 @@ initialization and call handler functions. is also used for diagnostic purposes - ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in - `smccc.h`_ + ``smccc.h`` - ``_type`` must be one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD`` @@ -132,7 +132,7 @@ to ensure that the following conditions are met: #. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD`` #. ``_setup`` and ``_smch`` routines have been specified -`std_svc_setup.c`_ provides an example of registering a runtime service: +``std_svc_setup.c`` provides an example of registering a runtime service: .. code:: c @@ -244,17 +244,35 @@ The handler is responsible for: TF-A expects owning entities to follow this recommendation. -#. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits - of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The - framework provides a family of macros to set the multi-register return - value and complete the handler: +#. Returning the result to the caller. Based on `SMCCC`_ spec, results are + returned in W0-W7(X0-X7) registers for SMC32(SMC64) calls from AArch64 + state. Results are returned in R0-R7 registers for SMC32 calls from AArch32 + state. The framework provides a family of macros to set the multi-register + return value and complete the handler: .. code:: c + AArch64 state: + SMC_RET1(handle, x0); SMC_RET2(handle, x0, x1); SMC_RET3(handle, x0, x1, x2); SMC_RET4(handle, x0, x1, x2, x3); + SMC_RET5(handle, x0, x1, x2, x3, x4); + SMC_RET6(handle, x0, x1, x2, x3, x4, x5); + SMC_RET7(handle, x0, x1, x2, x3, x4, x5, x6); + SMC_RET8(handle, x0, x1, x2, x3, x4, x5, x6, x7); + + AArch32 state: + + SMC_RET1(handle, r0); + SMC_RET2(handle, r0, r1); + SMC_RET3(handle, r0, r1, r2); + SMC_RET4(handle, r0, r1, r2, r3); + SMC_RET5(handle, r0, r1, r2, r3, r4); + SMC_RET6(handle, r0, r1, r2, r3, r4, r5); + SMC_RET7(handle, r0, r1, r2, r3, r4, r5, r6); + SMC_RET8(handle, r0, r1, r2, r3, r4, r5, r6, r7); The ``cookie`` parameter to the handler is reserved for future use and can be ignored. The ``handle`` is returned by the SMC handler - completion of the @@ -296,13 +314,7 @@ provide this information.... -------------- -*Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _Firmware Design: ../design/firmware-design.rst -.. _services: ../../services -.. _lib/psci: ../../lib/psci -.. _runtime_svc.h: ../../include/common/runtime_svc.h -.. _smccc.h: ../../include/lib/smccc.h -.. _std_svc_setup.c: ../../services/std_svc/std_svc_setup.c diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst new file mode 100644 index 000000000..bb707cb7c --- /dev/null +++ b/docs/getting_started/tools-build.rst @@ -0,0 +1,140 @@ +Building Supporting Tools +========================= + +Building and using the FIP tool +------------------------------- + +Firmware Image Package (FIP) is a packaging format used by TF-A to package +firmware images in a single binary. The number and type of images that should +be packed in a FIP is platform specific and may include TF-A images and other +firmware images required by the platform. For example, most platforms require +a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or +U-Boot). + +The TF-A build system provides the make target ``fip`` to create a FIP file +for the specified platform using the FIP creation tool included in the TF-A +project. Examples below show how to build a FIP file for FVP, packaging TF-A +and BL33 images. + +For AArch64: + +.. code:: shell + + make PLAT=fvp BL33=<path-to>/bl33.bin fip + +For AArch32: + +.. code:: shell + + make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip + +The resulting FIP may be found in: + +:: + + build/fvp/<build-type>/fip.bin + +For advanced operations on FIP files, it is also possible to independently build +the tool and create or modify FIPs using this tool. To do this, follow these +steps: + +It is recommended to remove old artifacts before building the tool: + +.. code:: shell + + make -C tools/fiptool clean + +Build the tool: + +.. code:: shell + + make [DEBUG=1] [V=1] fiptool + +The tool binary can be located in: + +:: + + ./tools/fiptool/fiptool + +Invoking the tool with ``help`` will print a help message with all available +options. + +Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: + +.. code:: shell + + ./tools/fiptool/fiptool create \ + --tb-fw build/<platform>/<build-type>/bl2.bin \ + --soc-fw build/<platform>/<build-type>/bl31.bin \ + fip.bin + +Example 2: view the contents of an existing Firmware package: + +.. code:: shell + + ./tools/fiptool/fiptool info <path-to>/fip.bin + +Example 3: update the entries of an existing Firmware package: + +.. code:: shell + + # Change the BL2 from Debug to Release version + ./tools/fiptool/fiptool update \ + --tb-fw build/<platform>/release/bl2.bin \ + build/<platform>/debug/fip.bin + +Example 4: unpack all entries from an existing Firmware package: + +.. code:: shell + + # Images will be unpacked to the working directory + ./tools/fiptool/fiptool unpack <path-to>/fip.bin + +Example 5: remove an entry from an existing Firmware package: + +.. code:: shell + + ./tools/fiptool/fiptool remove \ + --tb-fw build/<platform>/debug/fip.bin + +Note that if the destination FIP file exists, the create, update and +remove operations will automatically overwrite it. + +The unpack operation will fail if the images already exist at the +destination. In that case, use -f or --force to continue. + +More information about FIP can be found in the :ref:`Firmware Design` document. + +.. _tools_build_cert_create: + +Building the Certificate Generation Tool +---------------------------------------- + +The ``cert_create`` tool is built as part of the TF-A build process when the +``fip`` make target is specified and TBB is enabled (as described in the +previous section), but it can also be built separately with the following +command: + +.. code:: shell + + make PLAT=<platform> [DEBUG=1] [V=1] certtool + +For platforms that require their own IDs in certificate files, the generic +'cert_create' tool can be built with the following command. Note that the target +platform must define its IDs within a ``platform_oid.h`` header file for the +build to succeed. + +.. code:: shell + + make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool + +``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more +verbose. The following command should be used to obtain help about the tool: + +.. code:: shell + + ./tools/cert_create/cert_create -h + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst deleted file mode 100644 index b447f1493..000000000 --- a/docs/getting_started/user-guide.rst +++ /dev/null @@ -1,2183 +0,0 @@ -User Guide -========== - -This document describes how to build Trusted Firmware-A (TF-A) and run it with a -tested set of other software components using defined configurations on the Juno -Arm development platform and Arm Fixed Virtual Platform (FVP) models. It is -possible to use other software components, configurations and platforms but that -is outside the scope of this document. - -This document assumes that the reader has previous experience running a fully -bootable Linux software stack on Juno or FVP using the prebuilt binaries and -filesystems provided by `Linaro`_. Further information may be found in the -`Linaro instructions`_. It also assumes that the user understands the role of -the different software components required to boot a Linux system: - -- Specific firmware images required by the platform (e.g. SCP firmware on Juno) -- Normal world bootloader (e.g. UEFI or U-Boot) -- Device tree -- Linux kernel image -- Root filesystem - -This document also assumes that the user is familiar with the `FVP models`_ and -the different command line options available to launch the model. - -This document should be used in conjunction with the `Firmware Design`_. - -Host machine requirements -------------------------- - -The minimum recommended machine specification for building the software and -running the FVP models is a dual-core processor running at 2GHz with 12GB of -RAM. For best performance, use a machine with a quad-core processor running at -2.6GHz with 16GB of RAM. - -The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for -building the software were installed from that distribution unless otherwise -specified. - -The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE, -Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain. - -Tools ------ - -Install the required packages to build TF-A with the following command: - -.. code:: shell - - sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev - -TF-A has been tested with Linaro Release 18.04. - -Download and install the AArch32 (arm-eabi) or AArch64 little-endian -(aarch64-linux-gnu) GCC cross compiler. If you would like to use the latest -features available, download GCC 8.3-2019.03 compiler from -`arm Developer page`_. Otherwise, the `Linaro Release Notes`_ documents which -version of the compiler to use for a given Linaro Release. Also, these -`Linaro instructions`_ provide further guidance and a script, which can be used -to download Linaro deliverables automatically. - -Optionally, TF-A can be built using clang version 4.0 or newer or Arm -Compiler 6. See instructions below on how to switch the default compiler. - -In addition, the following optional packages and tools may be needed: - -- ``device-tree-compiler`` (dtc) package if you need to rebuild the Flattened Device - Tree (FDT) source files (``.dts`` files) provided with this software. The - version of dtc must be 1.4.6 or above. - -- For debugging, Arm `Development Studio 5 (DS-5)`_. - -- To create and modify the diagram files included in the documentation, `Dia`_. - This tool can be found in most Linux distributions. Inkscape is needed to - generate the actual \*.png files. - -Getting the TF-A source code ----------------------------- - -Clone the repository from the Gerrit server. The project details may be found -on the `arm-trusted-firmware-a project page`_. We recommend the "`Clone with -commit-msg hook`" clone method, which will setup the git commit hook that -automatically generates and inserts appropriate `Change-Id:` lines in your -commit messages. - -Checking source code style -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Trusted Firmware follows the `Linux Coding Style`_ . When making changes to the -source, for submission to the project, the source must be in compliance with -this style guide. - -Additional, project-specific guidelines are defined in the `Trusted Firmware-A -Coding Guidelines`_ document. - -To assist with coding style compliance, the project Makefile contains two -targets which both utilise the `checkpatch.pl` script that ships with the Linux -source tree. The project also defines certain *checkpatch* options in the -``.checkpatch.conf`` file in the top-level directory. - -.. note:: - Checkpatch errors will gate upstream merging of pull requests. - Checkpatch warnings will not gate merging but should be reviewed and fixed if - possible. - -To check the entire source tree, you must first download copies of -``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available -in the `Linux master tree`_ *scripts* directory, then set the ``CHECKPATCH`` -environment variable to point to ``checkpatch.pl`` (with the other 2 files in -the same directory) and build the `checkcodebase` target: - -.. code:: shell - - make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase - -To just check the style on the files that differ between your local branch and -the remote master, use: - -.. code:: shell - - make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch - -If you wish to check your patch against something other than the remote master, -set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT`` -is set to ``origin/master``. - -Building TF-A -------------- - -- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point - to the Linaro cross compiler. - - For AArch64: - - .. code:: shell - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - - For AArch32: - - .. code:: shell - - export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi- - - It is possible to build TF-A using Clang or Arm Compiler 6. To do so - ``CC`` needs to point to the clang or armclang binary, which will - also select the clang or armclang assembler. Be aware that the - GNU linker is used by default. In case of being needed the linker - can be overridden using the ``LD`` variable. Clang linker version 6 is - known to work with TF-A. - - In both cases ``CROSS_COMPILE`` should be set as described above. - - Arm Compiler 6 will be selected when the base name of the path assigned - to ``CC`` matches the string 'armclang'. - - For AArch64 using Arm Compiler 6: - - .. code:: shell - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all - - Clang will be selected when the base name of the path assigned to ``CC`` - contains the string 'clang'. This is to allow both clang and clang-X.Y - to work. - - For AArch64 using clang: - - .. code:: shell - - export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- - make CC=<path-to-clang>/bin/clang PLAT=<platform> all - -- Change to the root directory of the TF-A source tree and build. - - For AArch64: - - .. code:: shell - - make PLAT=<platform> all - - For AArch32: - - .. code:: shell - - make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all - - Notes: - - - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the - `Summary of build options`_ for more information on available build - options. - - - (AArch32 only) Currently only ``PLAT=fvp`` is supported. - - - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it - corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is - provided by TF-A to demonstrate how PSCI Library can be integrated with - an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may - include other runtime services, for example Trusted OS services. A guide - to integrate PSCI library with AArch32 EL3 Runtime Software can be found - `here`_. - - - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32 - image, is not compiled in by default. Refer to the - `Building the Test Secure Payload`_ section below. - - - By default this produces a release version of the build. To produce a - debug version instead, refer to the "Debugging options" section below. - - - The build process creates products in a ``build`` directory tree, building - the objects and binaries for each boot loader stage in separate - sub-directories. The following boot loader binary files are created - from the corresponding ELF files: - - - ``build/<platform>/<build-type>/bl1.bin`` - - ``build/<platform>/<build-type>/bl2.bin`` - - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only) - - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32) - - where ``<platform>`` is the name of the chosen platform and ``<build-type>`` - is either ``debug`` or ``release``. The actual number of images might differ - depending on the platform. - -- Build products for a specific build variant can be removed using: - - .. code:: shell - - make DEBUG=<D> PLAT=<platform> clean - - ... where ``<D>`` is ``0`` or ``1``, as specified when building. - - The build tree can be removed completely using: - - .. code:: shell - - make realclean - -Summary of build options -~~~~~~~~~~~~~~~~~~~~~~~~ - -The TF-A build system supports the following build options. Unless mentioned -otherwise, these options are expected to be specified at the build command -line and are not to be modified in any component makefiles. Note that the -build system doesn't track dependency for build options. Therefore, if any of -the build options are changed from a previous build, a clean build must be -performed. - -Common build options -^^^^^^^^^^^^^^^^^^^^ - -- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the - compiler should use. Valid values are T32 and A32. It defaults to T32 due to - code having a smaller resulting size. - -- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as - as the BL32 image when ``ARCH=aarch32``. The value should be the path to the - directory containing the SP source, relative to the ``bl32/``; the directory - is expected to contain a makefile called ``<aarch32_sp-value>.mk``. - -- ``ARCH`` : Choose the target build architecture for TF-A. It can take either - ``aarch64`` or ``aarch32`` as values. By default, it is defined to - ``aarch64``. - -- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when - compiling TF-A. Its value must be numeric, and defaults to 8 . See also, - *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in - `Firmware Design`_. - -- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when - compiling TF-A. Its value must be a numeric, and defaults to 0. See also, - *Armv8 Architecture Extensions* in `Firmware Design`_. - -- ``BL2``: This is an optional build option which specifies the path to BL2 - image for the ``fip`` target. In this case, the BL2 in the TF-A will not be - built. - -- ``BL2U``: This is an optional build option which specifies the path to - BL2U image. In this case, the BL2U in TF-A will not be built. - -- ``BL2_AT_EL3``: This is an optional build option that enables the use of - BL2 at EL3 execution level. - -- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place - (XIP) memory, like BL1. In these use-cases, it is necessary to initialize - the RW sections in RAM, while leaving the RO sections in place. This option - enable this use-case. For now, this option is only supported when BL2_AT_EL3 - is set to '1'. - -- ``BL31``: This is an optional build option which specifies the path to - BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not - be built. - -- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``, - this file name will be used to save the key. - -- ``BL32``: This is an optional build option which specifies the path to - BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not - be built. - -- ``BL32_EXTRA1``: This is an optional build option which specifies the path to - Trusted OS Extra1 image for the ``fip`` target. - -- ``BL32_EXTRA2``: This is an optional build option which specifies the path to - Trusted OS Extra2 image for the ``fip`` target. - -- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``, - this file name will be used to save the key. - -- ``BL33``: Path to BL33 image in the host file system. This is mandatory for - ``fip`` target in case TF-A BL2 is used. - -- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``, - this file name will be used to save the key. - -- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication - and ARMv8.5 Branch Target Identification support for TF-A BL images themselves. - If enabled, it is needed to use a compiler that supports the option - ``-mbranch-protection``. Selects the branch protection features to use: -- 0: Default value turns off all types of branch protection -- 1: Enables all types of branch protection features -- 2: Return address signing to its standard level -- 3: Extend the signing to include leaf functions - - The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options - and resulting PAuth/BTI features. - - +-------+--------------+-------+-----+ - | Value | GCC option | PAuth | BTI | - +=======+==============+=======+=====+ - | 0 | none | N | N | - +-------+--------------+-------+-----+ - | 1 | standard | Y | Y | - +-------+--------------+-------+-----+ - | 2 | pac-ret | Y | N | - +-------+--------------+-------+-----+ - | 3 | pac-ret+leaf | Y | N | - +-------+--------------+-------+-----+ - - This option defaults to 0 and this is an experimental feature. - Note that Pointer Authentication is enabled for Non-secure world - irrespective of the value of this option if the CPU supports it. - -- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the - compilation of each build. It must be set to a C string (including quotes - where applicable). Defaults to a string that contains the time and date of - the compilation. - -- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A - build to be uniquely identified. Defaults to the current git commit id. - -- ``CFLAGS``: Extra user options appended on the compiler's command line in - addition to the options set by the build system. - -- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may - release several CPUs out of reset. It can take either 0 (several CPUs may be - brought up) or 1 (only one CPU will ever be brought up during cold reset). - Default is 0. If the platform always brings up a single CPU, there is no - need to distinguish between primary and secondary CPUs and the boot path can - be optimised. The ``plat_is_my_cpu_primary()`` and - ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need - to be implemented in this case. - -- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor - register state when an unexpected exception occurs during execution of - BL31. This option defaults to the value of ``DEBUG`` - i.e. by default - this is only enabled for a debug build of the firmware. - -- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the - certificate generation tool to create new keys in case no valid keys are - present or specified. Allowed options are '0' or '1'. Default is '1'. - -- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause - the AArch32 system registers to be included when saving and restoring the - CPU context. The option must be set to 0 for AArch64-only platforms (that - is on hardware that does not implement AArch32, or at least not at EL1 and - higher ELs). Default value is 1. - -- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP - registers to be included when saving and restoring the CPU context. Default - is 0. - -- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables - Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth - registers to be included when saving and restoring the CPU context as - part of world switch. Default value is 0 and this is an experimental feature. - Note that Pointer Authentication is enabled for Non-secure world irrespective - of the value of this flag if the CPU supports it. - -- ``DEBUG``: Chooses between a debug and release build. It can take either 0 - (release) or 1 (debug) as values. 0 is the default. - -- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation - of the binary image. If set to 1, then only the ELF image is built. - 0 is the default. - -- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted - Board Boot authentication at runtime. This option is meant to be enabled only - for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this - flag has to be enabled. 0 is the default. - -- ``E``: Boolean option to make warnings into errors. Default is 1. - -- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of - the normal boot flow. It must specify the entry point address of the EL3 - payload. Please refer to the "Booting an EL3 payload" section for more - details. - -- ``ENABLE_AMU``: Boolean option to enable Activity Monitor Unit extensions. - This is an optional architectural feature available on v8.4 onwards. Some - v8.2 implementations also implement an AMU and this option can be used to - enable this feature on those systems as well. Default is 0. - -- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()`` - are compiled out. For debug builds, this option defaults to 1, and calls to - ``assert()`` are left in place. For release builds, this option defaults to 0 - and calls to ``assert()`` function are compiled out. This option can be set - independently of ``DEBUG``. It can also be used to hide any auxiliary code - that is only required for the assertion and does not fit in the assertion - itself. - -- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace - dumps or not. It is supported in both AArch64 and AArch32. However, in - AArch32 the format of the frame records are not defined in the AAPCS and they - are defined by the implementation. This implementation of backtrace only - supports the format used by GCC when T32 interworking is disabled. For this - reason enabling this option in AArch32 will force the compiler to only - generate A32 code. This option is enabled by default only in AArch64 debug - builds, but this behaviour can be overridden in each platform's Makefile or - in the build command line. - -- ``ENABLE_MPAM_FOR_LOWER_ELS``: Boolean option to enable lower ELs to use MPAM - feature. MPAM is an optional Armv8.4 extension that enables various memory - system components and resources to define partitions; software running at - various ELs can assign themselves to desired partition to control their - performance aspects. - - When this option is set to ``1``, EL3 allows lower ELs to access their own - MPAM registers without trapping into EL3. This option doesn't make use of - partitioning in EL3, however. Platform initialisation code should configure - and use partitions in EL3 as required. This option defaults to ``0``. - -- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE) - support within generic code in TF-A. This option is currently only supported - in BL31. Default is 0. - -- ``ENABLE_PMF``: Boolean option to enable support for optional Performance - Measurement Framework(PMF). Default is 0. - -- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI - functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0. - In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must - be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in - software. - -- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime - instrumentation which injects timestamp collection points into TF-A to - allow runtime performance to be measured. Currently, only PSCI is - instrumented. Enabling this option enables the ``ENABLE_PMF`` build option - as well. Default is 0. - -- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling - extensions. This is an optional architectural feature for AArch64. - The default is 1 but is automatically disabled when the target architecture - is AArch32. - -- ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM). - Refer to the `Secure Partition Manager Design guide`_ for more details about - this feature. Default is 0. - -- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension - (SVE) for the Non-secure world only. SVE is an optional architectural feature - for AArch64. Note that when SVE is enabled for the Non-secure world, access - to SIMD and floating-point functionality from the Secure world is disabled. - This is to avoid corruption of the Non-secure world data in the Z-registers - which are aliased by the SIMD and FP registers. The build option is not - compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an - assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS`` set to - 1. The default is 1 but is automatically disabled when the target - architecture is AArch32. - -- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection - checks in GCC. Allowed values are "all", "strong", "default" and "none". The - default value is set to "none". "strong" is the recommended stack protection - level if this feature is desired. "none" disables the stack protection. For - all values other than "none", the ``plat_get_stack_protector_canary()`` - platform hook needs to be implemented. The value is passed as the last - component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``. - -- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of - deprecated platform APIs, helper functions or drivers within Trusted - Firmware as error. It can take the value 1 (flag the use of deprecated - APIs as error) or 0. The default is 0. - -- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions - targeted at EL3. When set ``0`` (default), no exceptions are expected or - handled at EL3, and a panic will result. This is supported only for AArch64 - builds. - -- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault - injection from lower ELs, and this build option enables lower ELs to use - Error Records accessed via System Registers to inject faults. This is - applicable only to AArch64 builds. - - This feature is intended for testing purposes only, and is advisable to keep - disabled for production images. - -- ``FIP_NAME``: This is an optional build option which specifies the FIP - filename for the ``fip`` target. Default is ``fip.bin``. - -- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU - FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``. - -- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create`` - tool to create certificates as per the Chain of Trust described in - `Trusted Board Boot`_. The build system then calls ``fiptool`` to - include the certificates in the FIP and FWU_FIP. Default value is '0'. - - Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support - for the Trusted Board Boot feature in the BL1 and BL2 images, to generate - the corresponding certificates, and to include those certificates in the - FIP and FWU_FIP. - - Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2 - images will not include support for Trusted Board Boot. The FIP will still - include the corresponding certificates. This FIP can be used to verify the - Chain of Trust on the host machine through other mechanisms. - - Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2 - images will include support for Trusted Board Boot, but the FIP and FWU_FIP - will not include the corresponding certificates, causing a boot failure. - -- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have - inherent support for specific EL3 type interrupts. Setting this build option - to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both - by `platform abstraction layer`__ and `Interrupt Management Framework`__. - This allows GICv2 platforms to enable features requiring EL3 interrupt type. - This also means that all GICv2 Group 0 interrupts are delivered to EL3, and - the Secure Payload interrupts needs to be synchronously handed over to Secure - EL1 for handling. The default value of this option is ``0``, which means the - Group 0 interrupts are assumed to be handled by Secure EL1. - - .. __: `platform-interrupt-controller-API.rst` - .. __: `interrupt-framework-design.rst` - -- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError - Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to - ``0`` (default), these exceptions will be trapped in the current exception - level (or in EL1 if the current exception level is EL0). - -- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific - software operations are required for CPUs to enter and exit coherency. - However, newer systems exist where CPUs' entry to and exit from coherency - is managed in hardware. Such systems require software to only initiate these - operations, and the rest is managed in hardware, minimizing active software - management. In such systems, this boolean option enables TF-A to carry out - build and run-time optimizations during boot and power management operations. - This option defaults to 0 and if it is enabled, then it implies - ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled. - - If this flag is disabled while the platform which TF-A is compiled for - includes cores that manage coherency in hardware, then a compilation error is - generated. This is based on the fact that a system cannot have, at the same - time, cores that manage coherency in hardware and cores that don't. In other - words, a platform cannot have, at the same time, cores that require - ``HW_ASSISTED_COHERENCY=1`` and cores that require - ``HW_ASSISTED_COHERENCY=0``. - - Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of - translation library (xlat tables v2) must be used; version 1 of translation - library is not supported. - -- ``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. - -- ``KEY_ALG``: This build flag enables the user to select the algorithm to be - used for generating the PKCS keys and subsequent signing of the certificate. - It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option - ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR - compliant and is retained only for compatibility. The default value of this - flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme. - -- ``HASH_ALG``: This build flag enables the user to select the secure hash - algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``. - The default value of this flag is ``sha256``. - -- ``LDFLAGS``: Extra user options appended to the linkers' command line in - addition to the one set by the build system. - -- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log - output compiled into the build. This should be one of the following: - - :: - - 0 (LOG_LEVEL_NONE) - 10 (LOG_LEVEL_ERROR) - 20 (LOG_LEVEL_NOTICE) - 30 (LOG_LEVEL_WARNING) - 40 (LOG_LEVEL_INFO) - 50 (LOG_LEVEL_VERBOSE) - - All log output up to and including the selected log level is compiled into - the build. The default value is 40 in debug builds and 20 in release builds. - -- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It - specifies the file that contains the Non-Trusted World private key in PEM - format. If ``SAVE_KEYS=1``, this file name will be used to save the key. - -- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is - optional. It is only needed if the platform makefile specifies that it - is required in order to build the ``fwu_fip`` target. - -- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register - contents upon world switch. It can take either 0 (don't save and restore) or - 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it - wants the timer registers to be saved and restored. - -- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc - for the BL image. It can be either 0 (include) or 1 (remove). The default - value is 0. - -- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that - the underlying hardware is not a full PL011 UART but a minimally compliant - generic UART, which is a subset of the PL011. The driver will not access - any register that is not part of the SBSA generic UART specification. - Default value is 0 (a full PL011 compliant UART is present). - -- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name - must be subdirectory of any depth under ``plat/``, and must contain a - platform makefile named ``platform.mk``. For example, to build TF-A for the - Arm Juno board, select PLAT=juno. - -- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image - instead of the normal boot flow. When defined, it must specify the entry - point address for the preloaded BL33 image. This option is incompatible with - ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority - over ``PRELOADED_BL33_BASE``. - -- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset - vector address can be programmed or is fixed on the platform. It can take - either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a - programmable reset address, it is expected that a CPU will start executing - code directly at the right address, both on a cold and warm reset. In this - case, there is no need to identify the entrypoint on boot and the boot path - can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface - does not need to be implemented in this case. - -- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats - possible for the PSCI power-state parameter: original and extended State-ID - formats. This flag if set to 1, configures the generic PSCI layer to use the - extended format. The default value of this flag is 0, which means by default - the original power-state format is used by the PSCI implementation. This flag - should be specified by the platform makefile and it governs the return value - of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is - enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be - set to 1 as well. - -- ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features - are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2 - or later CPUs. - - When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST`` must also be - set to ``1``. - - This option is disabled by default. - -- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead - of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 - entrypoint) or 1 (CPU reset to BL31 entrypoint). - The default value is 0. - -- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided - in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector - instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 - entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0. - -- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this - file name will be used to save the key. - -- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the - certificate generation tool to save the keys used to establish the Chain of - Trust. Allowed options are '0' or '1'. Default is '0' (do not save). - -- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional. - If a SCP_BL2 image is present then this option must be passed for the ``fip`` - target. - -- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``, - this file name will be used to save the key. - -- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is - optional. It is only needed if the platform makefile specifies that it - is required in order to build the ``fwu_fip`` target. - -- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software - Delegated Exception Interface to BL31 image. This defaults to ``0``. - - When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be - set to ``1``. - -- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be - isolated on separate memory pages. This is a trade-off between security and - memory usage. See "Isolating code and read-only data on separate memory - pages" section in `Firmware Design`_. This flag is disabled by default and - affects all BL images. - -- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A. - This build option is only valid if ``ARCH=aarch64``. The value should be - the path to the directory containing the SPD source, relative to - ``services/spd/``; the directory is expected to contain a makefile called - ``<spd-value>.mk``. - -- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can - take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops - execution in BL1 just before handing over to BL31. At this point, all - firmware images have been loaded in memory, and the MMU and caches are - turned off. Refer to the "Debugging options" section for more details. - -- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles - secure interrupts (caught through the FIQ line). Platforms can enable - this directive if they need to handle such interruption. When enabled, - the FIQ are handled in monitor mode and non secure world is not allowed - to mask these events. Platforms that enable FIQ handling in SP_MIN shall - implement the api ``sp_min_plat_fiq_handler()``. The default value is 0. - -- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board - Boot feature. When set to '1', BL1 and BL2 images include support to load - and verify the certificates and images in a FIP, and BL1 includes support - for the Firmware Update. The default value is '0'. Generation and inclusion - of certificates in the FIP and FWU_FIP depends upon the value of the - ``GENERATE_COT`` option. - - .. warning:: - This option depends on ``CREATE_KEYS`` to be enabled. If the keys - already exist in disk, they will be overwritten without further notice. - -- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It - specifies the file that contains the Trusted World private key in PEM - format. If ``SAVE_KEYS=1``, this file name will be used to save the key. - -- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or - synchronous, (see "Initializing a BL32 Image" section in - `Firmware Design`_). It can take the value 0 (BL32 is initialized using - synchronous method) or 1 (BL32 is initialized using asynchronous method). - Default is 0. - -- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt - routing model which routes non-secure interrupts asynchronously from TSP - to EL3 causing immediate preemption of TSP. The EL3 is responsible - for saving and restoring the TSP context in this routing model. The - default routing model (when the value is 0) is to route non-secure - interrupts to TSP allowing it to save its context and hand over - synchronously to EL3 via an SMC. - - .. note:: - When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` - must also be set to ``1``. - -- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM - linker. When the ``LINKER`` build variable points to the armlink linker, - this flag is enabled automatically. To enable support for armlink, platforms - will have to provide a scatter file for the BL image. Currently, Tegra - platforms use the armlink support to compile BL3-1 images. - -- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent - memory region in the BL memory map or not (see "Use of Coherent memory in - TF-A" section in `Firmware Design`_). It can take the value 1 - (Coherent memory region is included) or 0 (Coherent memory region is - excluded). Default is 1. - -- ``USE_ROMLIB``: This flag determines whether library at ROM will be used. - This feature creates a library of functions to be placed in ROM and thus - reduces SRAM usage. Refer to `Library at ROM`_ for further details. Default - is 0. - -- ``V``: Verbose build. If assigned anything other than 0, the build commands - are printed. Default is 0. - -- ``VERSION_STRING``: String used in the log output for each TF-A image. - Defaults to a string formed by concatenating the version number, build type - and build string. - -- ``W``: Warning level. Some compiler warning options of interest have been - regrouped and put in the root Makefile. This flag can take the values 0 to 3, - each level enabling more warning options. Default is 0. - -- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on - the CPU after warm boot. This is applicable for platforms which do not - require interconnect programming to enable cache coherency (eg: single - cluster platforms). If this option is enabled, then warm boot path - enables D-caches immediately after enabling MMU. This option defaults to 0. - -Arm development platform specific 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 hash 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. The private key corresponding to this ROTPK hash is not - currently available. - - ``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. - -- ``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_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm® - TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm - platforms. If this option is specified, then the path to the CryptoCell - SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag. - -For a better understanding of these options, the Arm development platform memory -map is explained in the `Firmware Design`_. - -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. - -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_GIC600`` : The GIC600 implementation of GICv3 is selected - - ``FVP_GICV2`` : The GICv2 only driver is selected - - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) - -- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer - for functions that wait for an arbitrary time length (udelay and mdelay). - The default value is 0. - -- ``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 `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 `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. - -ARM JUNO 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. - -Debugging options -~~~~~~~~~~~~~~~~~ - -To compile a debug version and make the build more verbose use - -.. code:: shell - - make PLAT=<platform> DEBUG=1 V=1 all - -AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for -example DS-5) might not support this and may need an older version of DWARF -symbols to be emitted by GCC. This can be achieved by using the -``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the -version to 2 is recommended for DS-5 versions older than 5.16. - -When debugging logic problems it might also be useful to disable all compiler -optimizations by using ``-O0``. - -.. warning:: - Using ``-O0`` could cause output images to be larger and base addresses - might need to be recalculated (see the **Memory layout on Arm development - platforms** section in the `Firmware Design`_). - -Extra debug options can be passed to the build system by setting ``CFLAGS`` or -``LDFLAGS``: - -.. code:: shell - - CFLAGS='-O0 -gdwarf-2' \ - make PLAT=<platform> DEBUG=1 V=1 all - -Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be -ignored as the linker is called directly. - -It is also possible to introduce an infinite loop to help in debugging the -post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the -``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_ -section. In this case, the developer may take control of the target using a -debugger when indicated by the console output. When using DS-5, the following -commands can be used: - -:: - - # Stop target execution - interrupt - - # - # Prepare your debugging environment, e.g. set breakpoints - # - - # Jump over the debug loop - set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4 - - # Resume execution - continue - -Building the Test Secure Payload -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The TSP is coupled with a companion runtime service in the BL31 firmware, -called the TSPD. Therefore, if you intend to use the TSP, the BL31 image -must be recompiled as well. For more information on SPs and SPDs, see the -`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_. - -First clean the TF-A build directory to get rid of any previous BL31 binary. -Then to build the TSP image use: - -.. code:: shell - - make PLAT=<platform> SPD=tspd all - -An additional boot loader binary file is created in the ``build`` directory: - -:: - - build/<platform>/<build-type>/bl32.bin - - -Building and using the FIP tool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Firmware Image Package (FIP) is a packaging format used by TF-A to package -firmware images in a single binary. The number and type of images that should -be packed in a FIP is platform specific and may include TF-A images and other -firmware images required by the platform. For example, most platforms require -a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or -U-Boot). - -The TF-A build system provides the make target ``fip`` to create a FIP file -for the specified platform using the FIP creation tool included in the TF-A -project. Examples below show how to build a FIP file for FVP, packaging TF-A -and BL33 images. - -For AArch64: - -.. code:: shell - - make PLAT=fvp BL33=<path-to>/bl33.bin fip - -For AArch32: - -.. code:: shell - - make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip - -The resulting FIP may be found in: - -:: - - build/fvp/<build-type>/fip.bin - -For advanced operations on FIP files, it is also possible to independently build -the tool and create or modify FIPs using this tool. To do this, follow these -steps: - -It is recommended to remove old artifacts before building the tool: - -.. code:: shell - - make -C tools/fiptool clean - -Build the tool: - -.. code:: shell - - make [DEBUG=1] [V=1] fiptool - -The tool binary can be located in: - -:: - - ./tools/fiptool/fiptool - -Invoking the tool with ``help`` will print a help message with all available -options. - -Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: - -.. code:: shell - - ./tools/fiptool/fiptool create \ - --tb-fw build/<platform>/<build-type>/bl2.bin \ - --soc-fw build/<platform>/<build-type>/bl31.bin \ - fip.bin - -Example 2: view the contents of an existing Firmware package: - -.. code:: shell - - ./tools/fiptool/fiptool info <path-to>/fip.bin - -Example 3: update the entries of an existing Firmware package: - -.. code:: shell - - # Change the BL2 from Debug to Release version - ./tools/fiptool/fiptool update \ - --tb-fw build/<platform>/release/bl2.bin \ - build/<platform>/debug/fip.bin - -Example 4: unpack all entries from an existing Firmware package: - -.. code:: shell - - # Images will be unpacked to the working directory - ./tools/fiptool/fiptool unpack <path-to>/fip.bin - -Example 5: remove an entry from an existing Firmware package: - -.. code:: shell - - ./tools/fiptool/fiptool remove \ - --tb-fw build/<platform>/debug/fip.bin - -Note that if the destination FIP file exists, the create, update and -remove operations will automatically overwrite it. - -The unpack operation will fail if the images already exist at the -destination. In that case, use -f or --force to continue. - -More information about FIP can be found in the `Firmware Design`_ document. - -Building FIP images with support for Trusted Board Boot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Trusted Board Boot primarily consists of the following two features: - -- Image Authentication, described in `Trusted Board Boot`_, and -- Firmware Update, described in `Firmware Update`_ - -The following steps should be followed to build FIP and (optionally) FWU_FIP -images with support for these features: - -#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser - modules by checking out a recent version of the `mbed TLS Repository`_. It - is important to use a version that is compatible with TF-A and fixes any - known security vulnerabilities. See `mbed TLS Security Center`_ for more - information. The latest version of TF-A is tested with tag - ``mbedtls-2.16.0``. - - The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS - source files the modules depend upon. - ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration - options required to build the mbed TLS sources. - - Note that the mbed TLS library is licensed under the Apache version 2.0 - license. Using mbed TLS source code will affect the licensing of TF-A - binaries that are built using this library. - -#. To build the FIP image, ensure the following command line variables are set - while invoking ``make`` to build TF-A: - - - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`` - - ``TRUSTED_BOARD_BOOT=1`` - - ``GENERATE_COT=1`` - - In the case of Arm platforms, the location of the ROTPK hash must also be - specified at build time. Two locations are currently supported (see - ``ARM_ROTPK_LOCATION`` build option): - - - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted - root-key storage registers present in the platform. On Juno, this - registers are read-only. On FVP Base and Cortex models, the registers - are read-only, but the value can be specified using the command line - option ``bp.trusted_key_storage.public_key`` when launching the model. - On both Juno and FVP models, the default value corresponds to an - ECDSA-SECP256R1 public key hash, whose private part is not currently - available. - - - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded - in the Arm platform port. The private/public RSA key pair may be - found in ``plat/arm/board/common/rotpk``. - - - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded - in the Arm platform port. The private/public ECDSA key pair may be - found in ``plat/arm/board/common/rotpk``. - - Example of command line using RSA development keys: - - .. code:: shell - - MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ - make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ - ARM_ROTPK_LOCATION=devel_rsa \ - ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ - BL33=<path-to>/<bl33_image> \ - all fip - - The result of this build will be the bl1.bin and the fip.bin binaries. This - FIP will include the certificates corresponding to the Chain of Trust - described in the TBBR-client document. These certificates can also be found - in the output build directory. - -#. The optional FWU_FIP contains any additional images to be loaded from - Non-Volatile storage during the `Firmware Update`_ process. To build the - FWU_FIP, any FWU images required by the platform must be specified on the - command line. On Arm development platforms like Juno, these are: - - - NS_BL2U. The AP non-secure Firmware Updater image. - - SCP_BL2U. The SCP Firmware Update Configuration image. - - Example of Juno command line for generating both ``fwu`` and ``fwu_fip`` - targets using RSA development: - - :: - - MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ - make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ - ARM_ROTPK_LOCATION=devel_rsa \ - ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ - BL33=<path-to>/<bl33_image> \ - SCP_BL2=<path-to>/<scp_bl2_image> \ - SCP_BL2U=<path-to>/<scp_bl2u_image> \ - NS_BL2U=<path-to>/<ns_bl2u_image> \ - all fip fwu_fip - - .. note:: - The BL2U image will be built by default and added to the FWU_FIP. - The user may override this by adding ``BL2U=<path-to>/<bl2u_image>`` - to the command line above. - - .. note:: - Building and installing the non-secure and SCP FWU images (NS_BL1U, - NS_BL2U and SCP_BL2U) is outside the scope of this document. - - The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. - Both the FIP and FWU_FIP will include the certificates corresponding to the - Chain of Trust described in the TBBR-client document. These certificates - can also be found in the output build directory. - -Building the Certificate Generation Tool -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``cert_create`` tool is built as part of the TF-A build process when the -``fip`` make target is specified and TBB is enabled (as described in the -previous section), but it can also be built separately with the following -command: - -.. code:: shell - - make PLAT=<platform> [DEBUG=1] [V=1] certtool - -For platforms that require their own IDs in certificate files, the generic -'cert_create' tool can be built with the following command. Note that the target -platform must define its IDs within a ``platform_oid.h`` header file for the -build to succeed. - -.. code:: shell - - make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool - -``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more -verbose. The following command should be used to obtain help about the tool: - -.. code:: shell - - ./tools/cert_create/cert_create -h - -Building a FIP for Juno and FVP -------------------------------- - -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`_ 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. See `Obtaining the Flattened Device Trees`_ - section for more info on selecting the right FDT to use. - -#. Clean the working directory - - .. code:: shell - - make realclean - -#. Obtain SCP_BL2 (Juno) and BL33 (all platforms) - - Use the fiptool to extract the SCP_BL2 and BL33 images 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>/fip.bin - - The unpack operation will result in a set of binary images extracted to the - current working directory. The SCP_BL2 image corresponds to - ``scp-fw.bin`` and 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-fw.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-linux-gnu- - - - 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-fw.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 - - -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. - -Juno -~~~~ - -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. - -FVP -~~~ - -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. - - -EL3 payloads alternative boot flow ----------------------------------- - -On a pre-production system, the ability to execute arbitrary, bare-metal code at -the highest exception level is required. It allows full, direct access to the -hardware, for example to run silicon soak tests. - -Although it is possible to implement some baremetal secure firmware from -scratch, this is a complex task on some platforms, depending on the level of -configuration required to put the system in the expected state. - -Rather than booting a baremetal application, a possible compromise is to boot -``EL3 payloads`` through TF-A instead. This is implemented as an alternative -boot flow, where a modified BL2 boots an EL3 payload, instead of loading the -other BL images and passing control to BL31. It reduces the complexity of -developing EL3 baremetal code by: - -- putting the system into a known architectural state; -- taking care of platform secure world initialization; -- loading the SCP_BL2 image if required by the platform. - -When booting an EL3 payload on Arm standard platforms, the configuration of the -TrustZone controller is simplified such that only region 0 is enabled and is -configured to permit secure access only. This gives full access to the whole -DRAM to the EL3 payload. - -The system is left in the same state as when entering BL31 in the default boot -flow. In particular: - -- Running in EL3; -- Current state is AArch64; -- Little-endian data access; -- All exceptions disabled; -- MMU disabled; -- Caches disabled. - -Booting an EL3 payload -~~~~~~~~~~~~~~~~~~~~~~ - -The EL3 payload image is a standalone image and is not part of the FIP. It is -not loaded by TF-A. Therefore, there are 2 possible scenarios: - -- The EL3 payload may reside in non-volatile memory (NVM) and execute in - place. In this case, booting it is just a matter of specifying the right - address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A. - -- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at - run-time. - -To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be -used. The infinite loop that it introduces in BL1 stops execution at the right -moment for a debugger to take control of the target and load the payload (for -example, over JTAG). - -It is expected that this loading method will work in most cases, as a debugger -connection is usually available in a pre-production system. The user is free to -use any other platform-specific mechanism to load the EL3 payload, though. - -Booting an EL3 payload on FVP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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 an EL3 payload on Juno -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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. - -Preloaded BL33 alternative boot flow ------------------------------------- - -Some platforms have the ability to preload BL33 into memory instead of relying -on TF-A to load it. This may simplify packaging of the normal world code and -improve performance in a development environment. When secure world cold boot -is complete, TF-A simply jumps to a BL33 base address provided at build time. - -For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be -used when compiling TF-A. For example, the following command will create a FIP -without a BL33 and prepare to jump to a BL33 image loaded at address -0x80000000: - -.. code:: shell - - make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip - -Boot of a preloaded kernel image on 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-linux-gnu- \ - 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=0x04020000 \ - -C cluster0.cpu1.RVBAR=0x04020000 \ - -C cluster0.cpu2.RVBAR=0x04020000 \ - -C cluster0.cpu3.RVBAR=0x04020000 \ - -C cluster1.cpu0.RVBAR=0x04020000 \ - -C cluster1.cpu1.RVBAR=0x04020000 \ - -C cluster1.cpu2.RVBAR=0x04020000 \ - -C cluster1.cpu3.RVBAR=0x04020000 \ - --data cluster0.cpu0="<path-to>/bl31.bin"@0x04020000 \ - --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \ - --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ - --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000 - -Boot of a preloaded kernel image on Juno -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 -`Booting an EL3 payload on Juno`_. - -Running the software on FVP ---------------------------- - -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.6 Build 45, unless otherwise stated. - -- ``FVP_Base_AEMv8A-AEMv8A`` -- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` -- ``FVP_Base_RevC-2xAEMv8A`` -- ``FVP_Base_Cortex-A32x4`` -- ``FVP_Base_Cortex-A35x4`` -- ``FVP_Base_Cortex-A53x4`` -- ``FVP_Base_Cortex-A55x4+Cortex-A75x4`` -- ``FVP_Base_Cortex-A55x4`` -- ``FVP_Base_Cortex-A57x1-A53x1`` -- ``FVP_Base_Cortex-A57x2-A53x4`` -- ``FVP_Base_Cortex-A57x4-A53x4`` -- ``FVP_Base_Cortex-A57x4`` -- ``FVP_Base_Cortex-A72x4-A53x4`` -- ``FVP_Base_Cortex-A72x4`` -- ``FVP_Base_Cortex-A73x4-A53x4`` -- ``FVP_Base_Cortex-A73x4`` -- ``FVP_Base_Cortex-A75x4`` -- ``FVP_Base_Cortex-A76x4`` -- ``FVP_Base_Cortex-A76AEx4`` -- ``FVP_Base_Cortex-A76AEx8`` -- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36) -- ``FVP_Base_Neoverse-N1x4`` -- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) -- ``FVP_CSS_SGM-775`` (Version 11.3 build 42) -- ``FVP_RD_E1Edge`` (Version 11.3 build 42) -- ``FVP_RD_N1Edge`` -- ``Foundation_Platform`` - -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_AEMv8A-AEMv8A`` -- ``FVP_Base_Cortex-A32x4`` - -.. note:: - The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which - is not compatible with legacy GIC configurations. Therefore this FVP does not - support these legacy GIC configurations. - -.. 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. - -The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be -downloaded for free from `Arm's website`_. - -The Cortex-A models listed above are also available to download from -`Arm's website`_. - -Please refer to the FVP documentation for a detailed description of the model -parameter options. A brief description of the important ones that affect TF-A -and normal world software behavior is provided below. - -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 the -`Arm FVP platform specific build options`_ section for detail on the options). - -- ``fvp-base-gicv2-psci.dts`` - - For use with models such as the Cortex-A57-A53 Base FVPs without shifted - affinities and with Base memory map configuration. - -- ``fvp-base-gicv2-psci-aarch32.dts`` - - For use with models such as the Cortex-A32 Base FVPs without shifted - affinities and running Linux in AArch32 state with Base memory map - configuration. - -- ``fvp-base-gicv3-psci.dts`` - - For use with models such as the Cortex-A57-A53 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-base-gicv3-psci-aarch32.dts`` - - For use with models such as the Cortex-A32 Base FVPs without shifted - affinities and running Linux in AArch32 state with 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 ``hw_config_addr`` property in `TB_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: - -- If Position Independent Executable (PIE) support is enabled for BL31 - in this config, it can 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:: - The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``. - It should match the address programmed into the RVBAR register as well. - -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 - -Running the software on Juno ----------------------------- - -This version of TF-A has been tested on variants r0, r1 and r2 of Juno. - -To execute the software stack on Juno, the version of the Juno board recovery -image indicated in the `Linaro Release Notes`_ must be installed. If you have an -earlier version installed or are unsure which version is installed, please -re-install the recovery image by following the -`Instructions for using Linaro's deliverables on Juno`_. - -Preparing TF-A images -~~~~~~~~~~~~~~~~~~~~~ - -After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the -``SOFTWARE/`` directory of the Juno SD card. - -Other Juno software information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -Testing SYSTEM SUSPEND on Juno -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - --------------- - -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* - -.. _arm Developer page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads -.. _Linaro: `Linaro Release Notes`_ -.. _Linaro Release: `Linaro Release Notes`_ -.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes -.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables -.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno -.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/ -.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio -.. _arm-trusted-firmware-a project page: https://review.trustedfirmware.org/admin/projects/TF-A/trusted-firmware-a -.. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html -.. _Linux master tree: https://github.com/torvalds/linux/tree/master/ -.. _Dia: https://wiki.gnome.org/Apps/Dia/Download -.. _here: psci-lib-integration-guide.rst -.. _Trusted Board Boot: ../design/trusted-board-boot.rst -.. _TB_FW_CONFIG for FVP: ../../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts -.. _Secure-EL1 Payloads and Dispatchers: ../design/firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers -.. _Firmware Update: ../components/firmware-update.rst -.. _Firmware Design: ../design/firmware-design.rst -.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git -.. _mbed TLS Security Center: https://tls.mbed.org/security -.. _Arm's website: `FVP models`_ -.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms -.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _Secure Partition Manager Design guide: ../components/secure-partition-manager-design.rst -.. _`Trusted Firmware-A Coding Guidelines`: ../process/coding-guidelines.rst -.. _Library at ROM: ../components/romlib-design.rst diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt index 242e62c7c..491b160e6 100644 --- a/docs/global_substitutions.txt +++ b/docs/global_substitutions.txt @@ -1,11 +1,13 @@ .. |AArch32| replace:: :term:`AArch32` .. |AArch64| replace:: :term:`AArch64` .. |API| replace:: :term:`API` +.. |BTI| replace:: :term:`BTI` .. |CoT| replace:: :term:`CoT` .. |COT| replace:: :term:`COT` .. |CSS| replace:: :term:`CSS` .. |CVE| replace:: :term:`CVE` .. |DS-5| replace:: :term:`DS-5` +.. |DSU| replace:: :term:`DSU` .. |DT| replace:: :term:`DT` .. |EL| replace:: :term:`EL` .. |EHF| replace:: :term:`EHF` @@ -19,10 +21,12 @@ .. |MMU| replace:: :term:`MMU` .. |MPAM| replace:: :term:`MPAM` .. |MPIDR| replace:: :term:`MPIDR` +.. |MTE| replace:: :term:`MTE` .. |OEN| replace:: :term:`OEN` .. |OP-TEE| replace:: :term:`OP-TEE` .. |OTE| replace:: :term:`OTE` .. |PDD| replace:: :term:`PDD` +.. |PAUTH| replace:: :term:`PAUTH` .. |PMF| replace:: :term:`PMF` .. |PSCI| replace:: :term:`PSCI` .. |RAS| replace:: :term:`RAS` @@ -38,8 +42,10 @@ .. |SMCCC| replace:: :term:`SMCCC` .. |SoC| replace:: :term:`SoC` .. |SP| replace:: :term:`SP` +.. |SPCI| replace:: :term:`SPCI` .. |SPD| replace:: :term:`SPD` .. |SPM| replace:: :term:`SPM` +.. |SSBS| replace:: :term:`SSBS` .. |SVE| replace:: :term:`SVE` .. |TBB| replace:: :term:`TBB` .. |TBBR| replace:: :term:`TBBR` @@ -50,6 +56,7 @@ .. |TLK| replace:: :term:`TLK` .. |TSP| replace:: :term:`TSP` .. |TZC| replace:: :term:`TZC` +.. |UBSAN| replace:: :term:`UBSAN` .. |UEFI| replace:: :term:`UEFI` .. |WDOG| replace:: :term:`WDOG` -.. |XLAT| replace:: :term:`XLAT`
\ No newline at end of file +.. |XLAT| replace:: :term:`XLAT` diff --git a/docs/glossary.rst b/docs/glossary.rst index afe0acf75..2f19df59c 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -18,6 +18,10 @@ You can find additional definitions in the `Arm Glossary`_. API Application Programming Interface + BTI + Branch Target Identification. An Armv8.5 extension providing additional + control flow integrity around indirect branches and their targets. + CoT COT Chain of Trust @@ -32,6 +36,9 @@ You can find additional definitions in the `Arm Glossary`_. DS-5 Arm Development Studio 5 + DSU + DynamIQ Shared Unit + DT Device Tree @@ -72,6 +79,10 @@ You can find additional definitions in the `Arm Glossary`_. MPIDR Multiprocessor Affinity Register + MTE + Memory Tagging Extension. An optional Armv8.5 extension that enables + hardware-assisted memory tagging. + OEN Owning Entity Number @@ -84,6 +95,9 @@ You can find additional definitions in the `Arm Glossary`_. PDD Platform Design Document + PAUTH + Pointer Authentication. An optional extension introduced in Armv8.3. + PMF Performance Measurement Framework @@ -129,12 +143,20 @@ You can find additional definitions in the `Arm Glossary`_. SP Secure Partition + SPCI + Secure Partition Client Interface + SPD Secure Payload Dispatcher SPM Secure Partition Manager + SSBS + Speculative Store Bypass Safe. Introduced in Armv8.5, this configuration + bit can be set by software to allow or prevent the hardware from + performing speculative operations. + SVE Scalable Vector Extension @@ -165,6 +187,9 @@ You can find additional definitions in the `Arm Glossary`_. TZC TrustZone Controller + UBSAN + Undefined Behavior Sanitizer + UEFI Unified Extensible Firmware Interface @@ -174,4 +199,4 @@ You can find additional definitions in the `Arm Glossary`_. XLAT Translation (abbr.). For example, "XLAT table". -.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
\ No newline at end of file +.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary diff --git a/docs/index.rst b/docs/index.rst index 2023ceb1d..5088bfd87 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Trusted Firmware-A Documentation :hidden: Home<self> + about/index getting_started/index process/index components/index @@ -14,14 +15,10 @@ Trusted Firmware-A Documentation perf/index security_advisories/index change-log - acknowledgements + change-log-upcoming glossary - maintainers license -.. contents:: On This Page - :depth: 3 - Trusted Firmware-A (TF-A) provides a reference implementation of secure world software for `Armv7-A and Armv8-A`_, including a `Secure Monitor`_ executing at Exception Level 3 (EL3). It implements various Arm interface standards, @@ -43,232 +40,45 @@ states. Users are encouraged to do their own security validation, including penetration testing, on any secure world code derived from TF-A. -Arm will continue development in collaboration with interested parties to -provide a full reference implementation of Secure Monitor code and Arm standards -to the benefit of all developers working with Armv7-A and Armv8-A TrustZone -technology. - -Functionality -------------- - -- Initialization of the secure world, for example exception vectors, control - registers and interrupts for the platform. - -- Library support for CPU specific reset and power down sequences. This - includes support for errata workarounds and the latest Arm DynamIQ CPUs. - -- Drivers to enable standard initialization of Arm System IP, for example - Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI), - Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone - Controller (TZC). - -- A generic `SCMI`_ driver to interface with conforming power controllers, for - example the Arm System Control Processor (SCP). - -- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling - Convention`_ using an EL3 runtime services framework. - -- `PSCI`_ library support for CPU, cluster and system power management - use-cases. - This library is pre-integrated with the AArch64 EL3 Runtime Software, and - is also suitable for integration with other AArch32 EL3 Runtime Software, - for example an AArch32 Secure OS. - -- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library - integration with AArch32 EL3 Runtime Software. - -- Secure Monitor library code such as world switching, EL1 context management - and interrupt routing. - When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the - AArch64 EL3 Runtime Software must be integrated with a Secure Payload - Dispatcher (SPD) component to customize the interaction with the SP. - -- A Test SP and SPD to demonstrate AArch64 Secure Monitor functionality and SP - interaction with PSCI. - -- SPDs for the `OP-TEE Secure OS`_, `NVIDIA Trusted Little Kernel`_ - and `Trusty Secure OS`_. - -- A Trusted Board Boot implementation, conforming to all mandatory TBBR - requirements. This includes image authentication, Firmware Update (or - recovery mode), and packaging of the various firmware images into a - Firmware Image Package (FIP). - -- Pre-integration of TBB with the Arm CryptoCell product, to take advantage of - its hardware Root of Trust and crypto acceleration services. - -- Reliability, Availability, and Serviceability (RAS) functionality, including - - - A Secure Partition Manager (SPM) to manage Secure Partitions in - Secure-EL0, which can be used to implement simple management and - security services. - - - An |SDEI| dispatcher to route interrupt-based |SDEI| events. - - - An Exception Handling Framework (EHF) that allows dispatching of EL3 - interrupts to their registered handlers, to facilitate firmware-first - error handling. - -- A dynamic configuration framework that enables each of the firmware images - to be configured at runtime if required by the platform. It also enables - loading of a hardware configuration (for example, a kernel device tree) - as part of the FIP, to be passed through the firmware stages. - -- Support for alternative boot flows, for example to support platforms where - the EL3 Runtime Software is loaded using other firmware or a separate - secure system processor, or where a non-TF-A ROM expects BL2 to be loaded - at EL3. - -- Support for the GCC, LLVM and Arm Compiler 6 toolchains. - -- Support for combining several libraries into a "romlib" image that may be - shared across images to reduce memory footprint. The romlib image is stored - in ROM but is accessed through a jump-table that may be stored - in read-write memory, allowing for the library code to be patched. - -- A prototype implementation of a Secure Partition Manager (SPM) that is based - on the SPCI Alpha 1 and SPRT draft specifications. - -- Support for ARMv8.3 pointer authentication in the normal and secure worlds. - The use of pointer authentication in the normal world is enabled whenever - architectural support is available, without the need for additional build - flags. Use of pointer authentication in the secure world remains an - experimental configuration at this time and requires the ``ENABLE_PAUTH`` - build flag to be set. +In collaboration with interested parties, we will continue to enhance |TF-A| +with reference implementations of Arm standards to benefit developers working +with Armv7-A and Armv8-A TrustZone technology. -- Position-Independent Executable (PIE) support. Initially for BL31 only, with - further support to be added in a future release. - -For a full description of functionality and implementation details, please -see the `Firmware Design`_ and supporting documentation. The `Change Log`_ -provides details of changes made since the last release. - -Platforms ---------- - -Various AArch32 and AArch64 builds of this release have been tested on r0, r1 -and r2 variants of the `Juno Arm Development Platform`_. - -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.5 Build 33, unless otherwise stated. - -- ``FVP_Base_AEMv8A-AEMv8A`` -- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` -- ``FVP_Base_RevC-2xAEMv8A`` -- ``FVP_Base_Cortex-A32x4`` -- ``FVP_Base_Cortex-A35x4`` -- ``FVP_Base_Cortex-A53x4`` -- ``FVP_Base_Cortex-A55x4+Cortex-A75x4`` -- ``FVP_Base_Cortex-A55x4`` -- ``FVP_Base_Cortex-A57x1-A53x1`` -- ``FVP_Base_Cortex-A57x2-A53x4`` -- ``FVP_Base_Cortex-A57x4-A53x4`` -- ``FVP_Base_Cortex-A57x4`` -- ``FVP_Base_Cortex-A72x4-A53x4`` -- ``FVP_Base_Cortex-A72x4`` -- ``FVP_Base_Cortex-A73x4-A53x4`` -- ``FVP_Base_Cortex-A73x4`` -- ``FVP_Base_Cortex-A75x4`` -- ``FVP_Base_Cortex-A76x4`` -- ``FVP_Base_Cortex-A76AEx4`` (Tested with internal model) -- ``FVP_Base_Cortex-A76AEx8`` (Tested with internal model) -- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36) -- ``FVP_Base_Neoverse-N1x4`` (Tested with internal model) -- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) -- ``FVP_CSS_SGM-775`` (Version 11.3 build 42) -- ``FVP_RD_E1Edge`` (Version 11.3 build 42) -- ``FVP_RD_N1Edge`` (Version 11.3 build 42) -- ``Foundation_Platform`` - -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_AEMv8A-AEMv8A`` -- ``FVP_Base_Cortex-A32x4`` - -.. note:: - The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities. - -The Foundation FVP can be downloaded free of charge. The Base FVPs can be -licensed from Arm. See the `Arm FVP website`_. - -All the above platforms have been tested with `Linaro Release 18.04`_. - -This release also contains the following platform support: - -- Allwinner sun50i_a64 and sun50i_h6 -- Amlogic Meson S905 (GXBB) -- Arm Juno Software Development Platform -- 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 and SGM-775 -- Arm Versatile Express FVP -- HiKey, HiKey960 and Poplar boards -- Intel Stratix 10 SoC FPGA -- Marvell Armada 3700 and 8K -- MediaTek MT6795 and MT8173 SoCs -- NVIDIA T132, T186 and T210 SoCs -- NXP QorIQ LS1043A, i.MX8MM, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7 -- QEMU -- Raspberry Pi 3 -- Renesas R-Car Generation 3 -- RockChip RK3328, RK3368 and RK3399 SoCs -- Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs -- STMicroelectronics STM32MP1 -- Texas Instruments K3 SoCs -- Xilinx Versal and Zynq UltraScale + MPSoC - -Still to come -------------- - -- Support for additional platforms. - -- Refinements to Position Independent Executable (PIE) support. - -- Refinements to the SPCI-based SPM implementation as the draft SPCI and SPRT - specifications continue to evolve. - -- Documentation enhancements. - -- Ongoing support for new architectural features, CPUs and System IP. - -- Ongoing support for new Arm system architecture specifications. - -- Ongoing security hardening, optimization and quality improvements. +Getting Started +--------------- -For a full list of detailed issues in the current code, please see the `Change -Log`_ and the `issue tracker`_. +The |TF-A| documentation contains guidance for obtaining and building the +software for existing, supported platforms, as well as supporting information +for porting the software to a new platform. -Getting started ---------------- +The **About** chapter gives a high-level overview of |TF-A| features as well as +some information on the project and how it is organized. -See the `User Guide`_ for instructions on how to download, install, build and -use TF-A with the Arm `FVP`_\ s. +Refer to the documents in the **Getting Started** chapter for information about +the prerequisites and requirements for building |TF-A|. -See the `Firmware Design`_ for information on how TF-A works. +The **Processes & Policies** chapter explains the project's release schedule +and process, how security disclosures are handled, and the guidelines for +contributing to the project (including the coding style). -See the `Porting Guide`_ as well for information about how to use this -software on another Armv7-A or Armv8-A platform. +The **Components** chapter holds documents that explain specific components +that make up the |TF-A| software, the :ref:`Exception Handling Framework`, for +example. -See the `Contributing Guidelines`_ for information on how to contribute to this -project and the `Acknowledgments`_ file for a list of contributors to the -project. +In the **System Design** chapter you will find documents that explain the +design of portions of the software that involve more than one component, such +as the :ref:`Trusted Board Boot` process. -Contact us -~~~~~~~~~~ +**Platform Ports** provides a list of the supported hardware and software-model +platforms that are supported upstream in |TF-A|. Most of these platforms also +have additional documentation that has been provided by the maintainers of the +platform. -We welcome any feedback on TF-A. If you think you have found a security -vulnerability, please report this using the process defined in the TF-A -`Security Center`_. For all other feedback, you can use either the -`issue tracker`_ or our `mailing list`_. +The results of any performance evaluations are added to the +**Performance & Testing** chapter. -Arm licensees may contact Arm directly via their partner managers. +**Security Advisories** holds a list of documents relating to |CVE| entries that +have previously been raised against the software. -------------- @@ -276,29 +86,8 @@ Arm licensees may contact Arm directly via their partner managers. .. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile .. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php -.. _Power State Coordination Interface (PSCI): PSCI_ -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf +.. _Power State Coordination Interface (PSCI): http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a +.. _System Control and Management Interface (SCMI): http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf +.. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf -.. _System Control and Management Interface (SCMI): SCMI_ -.. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf -.. _Software Delegated Exception Interface (SDEI): SDEI_ -.. _SDEI: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php -.. _Arm FVP website: FVP_ -.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms -.. _Linaro Release 18.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease18.04 -.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os -.. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary -.. _Trusty Secure OS: https://source.android.com/security/trusty -.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git -.. _issue tracker: https://issues.trustedfirmware.org -.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a -.. _Security Center: ./process/security.rst -.. _license: ./license.rst -.. _Contributing Guidelines: ./process/contributing.rst -.. _Acknowledgments: ./acknowledgements.rst -.. _Firmware Design: ./design/firmware-design.rst -.. _Change Log: ./change-log.rst -.. _User Guide: ./getting_started/user-guide.rst -.. _Porting Guide: ./getting_started/porting-guide.rst diff --git a/docs/license.rst b/docs/license.rst index b62286fa9..2f9704335 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -3,7 +3,7 @@ License The software is provided under a BSD-3-Clause license (below). Contributions to this project are accepted under the same license with developer sign-off as -described in the :ref:`contributor_guide`. +described in the :ref:`Contributor's Guide`. :: @@ -77,4 +77,4 @@ license text is included in those source files. terms of both licenses. .. _FreeBSD: http://www.freebsd.org -.. _SCC: http://www.simple-cc.org/
\ No newline at end of file +.. _SCC: http://www.simple-cc.org/ diff --git a/docs/perf/index.rst b/docs/perf/index.rst index 50833b8c8..0f49b4810 100644 --- a/docs/perf/index.rst +++ b/docs/perf/index.rst @@ -7,3 +7,8 @@ Performance & Testing :numbered: psci-performance-juno + tsp + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/perf/psci-performance-juno.rst b/docs/perf/psci-performance-juno.rst index 4cc430265..c127c1c4a 100644 --- a/docs/perf/psci-performance-juno.rst +++ b/docs/perf/psci-performance-juno.rst @@ -168,7 +168,7 @@ the cache associated with power level 0 is flushed (L1). | 5 | 21 | 17 | 6 | +-------+---------------------+--------------------+--------------------------+ -The ``CLUSH_OVERHEAD`` times for lead CPU 4 and all CPUs in the non-lead cluster +The ``CFLUSH_OVERHEAD`` times for lead CPU 4 and all CPUs in the non-lead cluster are large because all other CPUs in the cluster are powered down during the test. The ``CPU_SUSPEND`` call powers down to the cluster level, requiring a flush of both L1 and L2 caches. diff --git a/docs/perf/tsp.rst b/docs/perf/tsp.rst new file mode 100644 index 000000000..f8b0048bf --- /dev/null +++ b/docs/perf/tsp.rst @@ -0,0 +1,27 @@ +Test Secure Payload (TSP) and Dispatcher (TSPD) +=============================================== + +Building the Test Secure Payload +-------------------------------- + +The TSP is coupled with a companion runtime service in the BL31 firmware, +called the TSPD. Therefore, if you intend to use the TSP, the BL31 image +must be recompiled as well. For more information on SPs and SPDs, see the +:ref:`firmware_design_sel1_spd` section in the :ref:`Firmware Design`. + +First clean the TF-A build directory to get rid of any previous BL31 binary. +Then to build the TSP image use: + +.. code:: shell + + make PLAT=<platform> SPD=tspd all + +An additional boot loader binary file is created in the ``build`` directory: + +:: + + build/<platform>/<build-type>/bl32.bin + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst new file mode 100644 index 000000000..d24ad231d --- /dev/null +++ b/docs/plat/arm/arm-build-options.rst @@ -0,0 +1,114 @@ +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 hash 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. The private key corresponding to this ROTPK hash is not + currently available. + - ``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. + +- ``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_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm® + TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm + platforms. If this option is specified, then the path to the CryptoCell + SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag. + +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. + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/plat/fvp_ve.rst b/docs/plat/arm/fvp-ve/index.rst index 6abf9e5f7..8ac07418a 100644 --- a/docs/plat/fvp_ve.rst +++ b/docs/plat/arm/fvp-ve/index.rst @@ -78,3 +78,7 @@ Trusted Firmware-A made using the above make commands: -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 000000000..37010e1a5 --- /dev/null +++ b/docs/plat/arm/fvp/index.rst @@ -0,0 +1,637 @@ +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.6 Build 45, unless otherwise stated. + +- ``FVP_Base_AEMv8A-AEMv8A`` +- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` +- ``FVP_Base_RevC-2xAEMv8A`` +- ``FVP_Base_Cortex-A32x4`` +- ``FVP_Base_Cortex-A35x4`` +- ``FVP_Base_Cortex-A53x4`` +- ``FVP_Base_Cortex-A55x4+Cortex-A75x4`` +- ``FVP_Base_Cortex-A55x4`` +- ``FVP_Base_Cortex-A57x1-A53x1`` +- ``FVP_Base_Cortex-A57x2-A53x4`` +- ``FVP_Base_Cortex-A57x4-A53x4`` +- ``FVP_Base_Cortex-A57x4`` +- ``FVP_Base_Cortex-A72x4-A53x4`` +- ``FVP_Base_Cortex-A72x4`` +- ``FVP_Base_Cortex-A73x4-A53x4`` +- ``FVP_Base_Cortex-A73x4`` +- ``FVP_Base_Cortex-A75x4`` +- ``FVP_Base_Cortex-A76x4`` +- ``FVP_Base_Cortex-A76AEx4`` +- ``FVP_Base_Cortex-A76AEx8`` +- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36) +- ``FVP_Base_Neoverse-N1x4`` +- ``FVP_Base_Zeusx4`` +- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) +- ``FVP_CSS_SGM-775`` (Version 11.3 build 42) +- ``FVP_RD_E1Edge`` (Version 11.3 build 42) +- ``FVP_RD_N1Edge`` +- ``Foundation_Platform`` + +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_AEMv8A-AEMv8A`` +- ``FVP_Base_Cortex-A32x4`` + +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` 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 19.06`_. + +.. _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_GIC600`` : The GIC600 implementation of GICv3 is selected + - ``FVP_GICV2`` : The GICv2 only driver is selected + - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) + +- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer + for functions that wait for an arbitrary time length (udelay and mdelay). + The default value is 0. + +- ``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. + +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=0x04020000 \ + -C cluster0.cpu1.RVBAR=0x04020000 \ + -C cluster0.cpu2.RVBAR=0x04020000 \ + -C cluster0.cpu3.RVBAR=0x04020000 \ + -C cluster1.cpu0.RVBAR=0x04020000 \ + -C cluster1.cpu1.RVBAR=0x04020000 \ + -C cluster1.cpu2.RVBAR=0x04020000 \ + -C cluster1.cpu3.RVBAR=0x04020000 \ + --data cluster0.cpu0="<path-to>/bl31.bin"@0x04020000 \ + --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 Base FVPs without shifted + affinities and with Base memory map configuration. + +- ``fvp-base-gicv2-psci-aarch32.dts`` + + For use with models such as the Cortex-A32 Base FVPs without shifted + affinities and running Linux in AArch32 state with Base memory map + configuration. + +- ``fvp-base-gicv3-psci.dts`` + + For use with models such as the Cortex-A57-A53 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-base-gicv3-psci-aarch32.dts`` + + For use with models such as the Cortex-A32 Base FVPs without shifted + affinities and running Linux in AArch32 state with 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 ``hw_config_addr`` property in `TB_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: + +- If Position Independent Executable (PIE) support is enabled for BL31 + in this config, it can 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:: + The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``. + It should match the address programmed into the RVBAR register as well. + +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, Arm Limited. All rights reserved.* + +.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts +.. _Arm's website: `FVP models`_ +.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms +.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06 +.. _Arm FVP website: https://developer.arm.com/products/system-design/fixed-virtual-platforms diff --git a/docs/plat/arm/index.rst b/docs/plat/arm/index.rst new file mode 100644 index 000000000..e26f75e56 --- /dev/null +++ b/docs/plat/arm/index.rst @@ -0,0 +1,19 @@ +Arm Development Platforms +========================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + juno/index + fvp/index + fvp-ve/index + arm-build-options + +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, 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 000000000..cf328fac9 --- /dev/null +++ b/docs/plat/arm/juno/index.rst @@ -0,0 +1,246 @@ +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 execute the software stack on Juno, the version of the Juno board recovery +image indicated in the `Linaro Release Notes`_ must be installed. If you have an +earlier version installed or are unsure which version is installed, please +re-install the recovery image by following the +`Instructions for using Linaro's deliverables on Juno`_. + +Preparing TF-A images +--------------------- + +After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the +``SOFTWARE/`` directory of the Juno SD card. + +Creating a Firmware Image Package (FIP) +--------------------------------------- + +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 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_BL2 (Juno) and BL33 (all platforms) + + Use the fiptool to extract the SCP_BL2 and BL33 images 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. The SCP_BL2 image corresponds to + ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``. + + .. note:: + The fiptool will complain if the images to be unpacked already + 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-fw.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-fw.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 + + +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, Arm Limited. All rights reserved.* + +.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes +.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno +.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/ +.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf +.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf +.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst index 74ff2f46c..372d38867 100644 --- a/docs/plat/hikey.rst +++ b/docs/plat/hikey.rst @@ -1,15 +1,15 @@ -Description -=========== +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>`__ @@ -33,7 +33,7 @@ Code Locations `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}. diff --git a/docs/plat/hikey960.rst b/docs/plat/hikey960.rst index 7ddb0b104..3d42a77c5 100644 --- a/docs/plat/hikey960.rst +++ b/docs/plat/hikey960.rst @@ -1,15 +1,15 @@ -Description -=========== +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>`__ @@ -30,7 +30,7 @@ Code Locations `link <https://git.linaro.org/uefi/uefi-tools.git>`__ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Fetch all the above 5 repositories into local host. Make all the repositories in the same ${BUILD\_PATH}. diff --git a/docs/plat/index.rst b/docs/plat/index.rst index 595141372..63d29a9be 100644 --- a/docs/plat/index.rst +++ b/docs/plat/index.rst @@ -5,25 +5,52 @@ Platform Ports :maxdepth: 1 :caption: Contents :numbered: + :hidden: allwinner - fvp_ve - imx8 - imx8m - intel-stratix10 - ls1043a + arm/index meson-gxbb meson-gxl + meson-g12a + hikey + hikey960 + intel-agilex + intel-stratix10 + marvell/index mt8183 nvidia-tegra + warp7 + imx8 + imx8m + ls1043a + poplar qemu + qemu-sbsa + rpi3 + rpi4 rcar-gen3 rockchip - rpi3 socionext-uniphier - stm32mp1 synquacer + stm32mp1 ti-k3 - warp7 xilinx-versal xilinx-zynqmp + +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 and SGM-775 + - MediaTek MT6795 and MT8173 SoCs + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/plat/intel-agilex.rst b/docs/plat/intel-agilex.rst index 015a195a8..ff27b6b5f 100644 --- a/docs/plat/intel-agilex.rst +++ b/docs/plat/intel-agilex.rst @@ -67,6 +67,7 @@ Boot trace ---------- :: + INFO: DDR: DRAM calibration success. INFO: ECC is disabled. NOTICE: BL2: v2.1(debug) diff --git a/docs/plat/intel-stratix10.rst b/docs/plat/intel-stratix10.rst index 77a45a478..7f8d18e03 100644 --- a/docs/plat/intel-stratix10.rst +++ b/docs/plat/intel-stratix10.rst @@ -67,6 +67,7 @@ Boot trace ---------- :: + INFO: DDR: DRAM calibration success. INFO: ECC is disabled. INFO: Init HPS NOC's DDR Scheduler. diff --git a/docs/plat/marvell/build.rst b/docs/plat/marvell/build.rst new file mode 100644 index 000000000..c10bcff79 --- /dev/null +++ b/docs/plat/marvell/build.rst @@ -0,0 +1,253 @@ +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 Armada80x0) + + .. 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: + +- DEBUG + + Default is without debug information (=0). in order to enable it use ``DEBUG=1``. + Must be disabled when building UART recovery images due to current console driver + implementation that is not compatible with Xmodem protocol used for boot image download. + +- LOG_LEVEL + + Defines the level of logging which will be purged to the default output port. + + LOG_LEVEL_NONE 0 + LOG_LEVEL_ERROR 10 + LOG_LEVEL_NOTICE 20 + LOG_LEVEL_WARNING 30 + LOG_LEVEL_INFO 40 + LOG_LEVEL_VERBOSE 50 + +- USE_COHERENT_MEM + + This flag determines whether to include the coherent memory region in the + BL memory map or not. + +- LLC_ENABLE + + Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``). + +- MARVELL_SECURE_BOOT + + Build trusted(=1)/non trusted(=0) image, default is non trusted. + +- BLE_PATH + + Points to BLE (Binary ROM extension) sources folder. Only required for A8K builds. + The parameter is optional, its default value is ``plat/marvell/a8k/common/ble``. + +- MV_DDR_PATH + + For A7/8K, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0, + it is used for ddr_tool build. + + Usage example: MV_DDR_PATH=path/to/mv_ddr + + The parameter is optional for A7/8K, when this parameter is not set, the mv_ddr + sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter + is necessary for A37x0. + + For the mv_ddr source location, check the section "Tools and external components installation" + +- DDR_TOPOLOGY + + For Armada37x0 only, the DDR topology map index/name, default is 0. + + Supported Options: + - DDR3 1CS (0): DB-88F3720-DDR3-Modular (512MB); EspressoBIN (512MB) + - DDR4 1CS (1): DB-88F3720-DDR4-Modular (512MB) + - DDR3 2CS (2): EspressoBIN V3-V5 (1GB) + - DDR4 2CS (3): DB-88F3720-DDR4-Modular (4GB) + - DDR3 1CS (4): DB-88F3720-DDR3-Modular (1GB) + - DDR4 1CS (5): EspressoBin V7 (1GB) + - DDR4 2CS (6): EspressoBin V7 (2GB) + - CUSTOMER (CUST): Customer board, DDR3 1CS 512MB + +- CLOCKSPRESET + + For Armada37x0 only, 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 + +- BOOTDEV + + For Armada37x0 only, 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 + +- PARTNUM + + For Armada37x0 only, 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 + + For Armada37x0 only, the path of the WTMI image can point to an image which + does nothing, an image which supports EFUSE or a customized CM3 firmware + binary. The default image is wtmi.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. + +- WTP + + For Armada37x0 only, use this parameter to point to wtptools source code + directory, which can be found as a3700_utils.zip in the release. Usage + example: ``WTP=/path/to/a3700_utils`` + + 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> all fip + + 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 all fip + + Supported MARVELL_PLATFORM are: + - a3700 (for both A3720 DB and EspressoBin) + - a70x0 + - a70x0_amc (for AMC board) + - a80x0 + - a80x0_mcbin (for MacciatoBin) + +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 + a70x0 and a80x0 because of hardware limitation (boot from secondary image + can interrupt UART recovery process). This MACRO definition is set in + ``plat/marvell/a8k/common/include/platform_def.h`` file. + +For more information about build options, please refer to the +:ref:`Build Options` document. + + +Build output +------------ +Marvell's TF-A compilation generates 7 files: + + - ble.bin - BLe image + - 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 - Image which contains boot-image.bin and SPL image. + Should be placed on the boot flash/device. + + +Tools and external components installation +------------------------------------------ + +Armada37x0 Builds require installation of 3 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 "mv_ddr-armada-atf-mainline" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git + +(3) Armada3700 tools available at the following repository (use the latest release branch): + + https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git + +Armada70x0 and Armada80x0 Builds require installation of an additional component +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(1) DDR initialization library sources (mv_ddr) available at the following repository + (use the "mv_ddr-armada-atf-mainline" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git diff --git a/docs/plat/marvell/build.txt b/docs/plat/marvell/build.txt deleted file mode 100644 index 7b75196fa..000000000 --- a/docs/plat/marvell/build.txt +++ /dev/null @@ -1,194 +0,0 @@ -TF-A Build Instructions -====================== - -This section describes how to compile the ARM Trusted Firmware (TF-A) project for Marvell's platforms. - -Build Instructions ------------------- -(1) Set the cross compiler:: - - > 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):: - - > 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 Armada80x0):: - - > 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:: - - > sudo apt-get install gcc-arm-linux-gnueabi - -(4) Clean previous build residuals (if any):: - - > make distclean - -(5) Build TF-A: - - There are several build options: - - - DEBUG: default is without debug information (=0). in order to enable it use DEBUG=1 - Must be disabled when building UART recovery images due to current console driver - implementation that is not compatible with Xmodem protocol used for boot image download. - - - LOG_LEVEL: defines the level of logging which will be purged to the default output port. - - LOG_LEVEL_NONE 0 - LOG_LEVEL_ERROR 10 - LOG_LEVEL_NOTICE 20 - LOG_LEVEL_WARNING 30 - LOG_LEVEL_INFO 40 - LOG_LEVEL_VERBOSE 50 - - - USE_COHERENT_MEM: This flag determines whether to include the coherent memory region in the - BL memory map or not. - - - LLC_ENABLE: Flag defining the LLC (L3) cache state. The cache is enabled by default (LLC_ENABLE=1). - - - MARVELL_SECURE_BOOT: build trusted(=1)/non trusted(=0) image, default is non trusted. - - - BLE_PATH: - Points to BLE (Binary ROM extension) sources folder. Only required for A8K builds. - The parameter is optional, its default value is "plat/marvell/a8k/common/ble". - - - MV_DDR_PATH: - For A7/8K, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0, - it is used for ddr_tool build. - Usage example: MV_DDR_PATH=path/to/mv_ddr - The parameter is optional for A7/8K, when this parameter is not set, the mv_ddr - sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter - is necessary for A37x0. - For the mv_ddr source location, check the section "Tools and external components installation" - - - DDR_TOPOLOGY: For Armada37x0 only, the DDR topology map index/name, default is 0. - Supported Options: - - DDR3 1CS (0): DB-88F3720-DDR3-Modular (512MB); EspressoBIN (512MB) - - DDR4 1CS (1): DB-88F3720-DDR4-Modular (512MB) - - DDR3 2CS (2): EspressoBIN V3-V5 (1GB) - - DDR4 2CS (3): DB-88F3720-DDR4-Modular (4GB) - - DDR3 1CS (4): DB-88F3720-DDR3-Modular (1GB) - - DDR4 1CS (5): EspressoBin V7 (1GB) - - DDR4 2CS (6): EspressoBin V7 (2GB) - - CUSTOMER (CUST): Customer board, DDR3 1CS 512MB - - - CLOCKSPRESET: For Armada37x0 only, 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 - - - BOOTDEV: For Armada37x0 only, 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 - - - PARTNUM: For Armada37x0 only, 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: For Armada37x0 only, the path of the WTMI image can point to an image which does - nothing, an image which supports EFUSE or a customized CM3 firmware binary. The default image - is wtmi.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. - - - WTP: For Armada37x0 only, use this parameter to point to wtptools source code directory, which - can be found as a3700_utils.zip in the release. - Usage example: WTP=/path/to/a3700_utils - - For example, in order to build the image in debug mode with log level up to 'notice' level run:: - - > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> all fip - - 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:: - - > 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 all fip - - Supported MARVELL_PLATFORM are: - - a3700 (for both A3720 DB and EspressoBin) - - a70x0 - - a70x0_amc (for AMC board) - - a80x0 - - a80x0_mcbin (for MacciatoBin) - -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 a70x0 and a80x0 - because of hardware limitation (boot from secondary image can interrupt UART recovery process). - This MACRO definition is set in plat/marvell/a8k/common/include/platform_def.h file - -(for more information about build options, please refer to section 'Summary of build options' in TF-A user-guide: - https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md) - - -Build output -------------- -Marvell's TF-A compilation generates 7 files: - - ble.bin - BLe image - - 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 - Image which contains boot-image.bin and SPL image; - should be placed on the boot flash/device. - - -Tools and external components installation -========================================== - -Armada37x0 Builds require installation of 3 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:: - - > 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:: - - > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi - -(2) DDR initialization library sources (mv_ddr) available at the following repository - (use the "mv_ddr-armada-atf-mainline" branch):: - https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git - -(3) Armada3700 tools available at the following repository (use the latest release branch):: - https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git - -Armada70x0 and Armada80x0 Builds require installation of an additional component --------------------------------------------------------------------------------- - -(1) DDR initialization library sources (mv_ddr) available at the following repository - (use the "mv_ddr-armada-atf-mainline" branch):: - https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git - diff --git a/docs/plat/marvell/index.rst b/docs/plat/marvell/index.rst new file mode 100644 index 000000000..89ebdc0a4 --- /dev/null +++ b/docs/plat/marvell/index.rst @@ -0,0 +1,14 @@ +Marvell +======= + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + build + porting + misc/mvebu-a8k-addr-map + misc/mvebu-amb + misc/mvebu-ccu + misc/mvebu-io-win + misc/mvebu-iob diff --git a/docs/plat/marvell/misc/mvebu-a8k-addr-map.rst b/docs/plat/marvell/misc/mvebu-a8k-addr-map.rst new file mode 100644 index 000000000..e88a4582b --- /dev/null +++ b/docs/plat/marvell/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/misc/mvebu-a8k-addr-map.txt b/docs/plat/marvell/misc/mvebu-a8k-addr-map.txt deleted file mode 100644 index 586e8b732..000000000 --- a/docs/plat/marvell/misc/mvebu-a8k-addr-map.txt +++ /dev/null @@ -1,47 +0,0 @@ -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/misc/mvebu-amb.rst b/docs/plat/marvell/misc/mvebu-amb.rst new file mode 100644 index 000000000..d734003d6 --- /dev/null +++ b/docs/plat/marvell/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/misc/mvebu-amb.txt b/docs/plat/marvell/misc/mvebu-amb.txt deleted file mode 100644 index 2a7a41ec9..000000000 --- a/docs/plat/marvell/misc/mvebu-amb.txt +++ /dev/null @@ -1,45 +0,0 @@ -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 -SPI1 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: - struct addr_map_win amb_memory_map[] = { - {0xf900, AMB_DEV_CS0_ID}, - }; diff --git a/docs/plat/marvell/misc/mvebu-ccu.rst b/docs/plat/marvell/misc/mvebu-ccu.rst new file mode 100644 index 000000000..5bac11faf --- /dev/null +++ b/docs/plat/marvell/misc/mvebu-ccu.rst @@ -0,0 +1,33 @@ +Marvell CCU address decoding bindings +===================================== + +CCU configration 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/misc/mvebu-ccu.txt b/docs/plat/marvell/misc/mvebu-ccu.txt deleted file mode 100644 index 976402761..000000000 --- a/docs/plat/marvell/misc/mvebu-ccu.txt +++ /dev/null @@ -1,23 +0,0 @@ -Marvell CCU address decoding bindings -===================================== - -CCU configration 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: - struct addr_map_win ccu_memory_map[] = { - {0x00000000f2000000, 0x00000000e000000, IO_0_TID}, /* IO window */ - }; diff --git a/docs/plat/marvell/misc/mvebu-io-win.txt b/docs/plat/marvell/misc/mvebu-io-win.rst index c83ad1fd2..52845ca02 100644 --- a/docs/plat/marvell/misc/mvebu-io-win.txt +++ b/docs/plat/marvell/misc/mvebu-io-win.rst @@ -1,5 +1,5 @@ Marvell IO WIN address decoding bindings -===================================== +======================================== IO Window configration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs. @@ -8,26 +8,37 @@ 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: + +- **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: +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*/ diff --git a/docs/plat/marvell/misc/mvebu-iob.txt b/docs/plat/marvell/misc/mvebu-iob.rst index 97ec09d0e..d02a7e84c 100644 --- a/docs/plat/marvell/misc/mvebu-iob.txt +++ b/docs/plat/marvell/misc/mvebu-iob.rst @@ -10,28 +10,40 @@ 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 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 - -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: +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 */ diff --git a/docs/plat/marvell/porting.rst b/docs/plat/marvell/porting.rst new file mode 100644 index 000000000..0a71dbd54 --- /dev/null +++ b/docs/plat/marvell/porting.rst @@ -0,0 +1,163 @@ +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/<soc family>/<soc>_cust`` + (e.g. 'plat/marvell/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/<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/marvell/misc/mvebu-[ccu/iob/amb/io-win].txt`` 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/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/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. + + .. seealso:: + For XFI/SFI comphy type there is procedure "rx_training" which eases + process of suiting some of the parameters. Please see *uboot_cmd* + section: rx_training. + + 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/<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/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/<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/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/porting.txt b/docs/plat/marvell/porting.txt deleted file mode 100644 index f9a39a054..000000000 --- a/docs/plat/marvell/porting.txt +++ /dev/null @@ -1,118 +0,0 @@ -.. _porting: - -TF-A Porting Guide -================= - -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/<soc family>/<soc>_cust" - (e.g. 'plat/marvell/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/<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/marvell/misc/mvebu-[ccu/iob/amb/io-win].txt" 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/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/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. - - .. seealso:: - For XFI/SFI comphy type there is procedure "rx_training" which eases process of suiting some of - the parameters. Please see :ref:`uboot_cmd` section: rx_training. - - 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/<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/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/<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/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/meson-g12a.rst b/docs/plat/meson-g12a.rst new file mode 100644 index 000000000..7cd1bf746 --- /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/board/amlogic/sei510/README diff --git a/docs/plat/nvidia-tegra.rst b/docs/plat/nvidia-tegra.rst index bc9e35b4f..02ff38bef 100644 --- a/docs/plat/nvidia-tegra.rst +++ b/docs/plat/nvidia-tegra.rst @@ -1,6 +1,17 @@ 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 @@ -78,9 +89,10 @@ their dispatchers in the image without changing any makefiles. These are the supported Trusted OS' by Tegra platforms. -Tegra132: TLK -Tegra210: TLK and Trusty -Tegra186: Trusty +- Tegra132: TLK +- Tegra210: TLK and Trusty +- Tegra186: Trusty +- Tegra194: Trusty Scatter files ------------- @@ -98,7 +110,7 @@ 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. t186|t210|t132> SPD=<dispatcher e.g. trusty|tlkd> + TARGET_SOC=<target-soc e.g. t194|t186|t210|t132> SPD=<dispatcher e.g. trusty|tlkd> bl31 Platforms wanting to use different TZDRAM\_BASE, can add ``TZDRAM_BASE=<value>`` diff --git a/docs/plat/poplar.rst b/docs/plat/poplar.rst index 5884ed945..215f55142 100644 --- a/docs/plat/poplar.rst +++ b/docs/plat/poplar.rst @@ -1,5 +1,5 @@ -Description -=========== +Poplar +====== Poplar is the first development board compliant with the 96Boards Enterprise Edition TV Platform specification. @@ -35,10 +35,10 @@ 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>`__ @@ -50,7 +50,7 @@ Code Locations `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}. @@ -89,7 +89,7 @@ The system will boot into a u-boot shell which you can then use to write the working firmware to eMMC. Boot trace -========== +---------- :: diff --git a/docs/plat/qemu-sbsa.rst b/docs/plat/qemu-sbsa.rst new file mode 100644 index 000000000..51fe41404 --- /dev/null +++ b/docs/plat/qemu-sbsa.rst @@ -0,0 +1,48 @@ +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 +- No instructions for how to load a BL32 (Secure Payload) + +To build TF-A: + +:: + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa + cd tfa + export CROSS_COMPILE=aarch64-linux-gnu- + make PLAT=qemu_sbsa 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 index 4ebe64b85..88196bc93 100644 --- a/docs/plat/qemu.rst +++ b/docs/plat/qemu.rst @@ -10,7 +10,11 @@ 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. -An ARM64 defconfig v4.5 Linux kernel is known to boot, FDT doesn't need to be +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: @@ -20,7 +24,7 @@ Current limitations: - No instructions for how to load a BL32 (Secure Payload) ``QEMU_EFI.fd`` can be dowloaded from -http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC49/QEMU_EFI.fd +http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC5/QEMU_EFI.fd 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 @@ -29,7 +33,7 @@ is conveniently achieved with symlinks the local names as: - ``bl2.bin`` -> BL2 - ``bl31.bin`` -> BL31 - ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``) -- ``Image`` -> linux/Image +- ``Image`` -> linux/arch/arm64/boot/Image To build: @@ -37,12 +41,12 @@ To build: make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu -To start (QEMU v2.6.0): +To start (QEMU v4.1.0): .. code:: shell qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ -kernel Image \ - -append console=ttyAMA0,38400 keep_bootcon root=/dev/vda2 \ + -append "console=ttyAMA0,38400 keep_bootcon root=/dev/vda2" \ -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ -d unimp -semihosting-config enable,target=native diff --git a/docs/plat/rpi4.rst b/docs/plat/rpi4.rst new file mode 100644 index 000000000..beb0227c2 --- /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 compononents 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/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst index 82b9b503a..92881932c 100644 --- a/docs/plat/socionext-uniphier.rst +++ b/docs/plat/socionext-uniphier.rst @@ -8,10 +8,11 @@ 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 `Trusted Board Boot`_ (TBB) -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 +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 @@ -50,7 +51,7 @@ Boot Flow 4. BL31, BL32, and BL33 - They all run in the DRAM. See `Firmware Design`_ for details. + They all run in the DRAM. See :ref:`Firmware Design` for details. Basic Build @@ -79,7 +80,8 @@ Optional features - Trusted Board Boot `mbed TLS`_ is needed as the cryptographic and image parser modules. - Refer to the `User Guide`_ for the appropriate version of mbed TLS. + Refer to the :ref:`Prerequisites` document for the appropriate version of + mbed TLS. To enable TBB, add the following options to the build command:: @@ -109,9 +111,6 @@ Optional features .. [1] Some SoCs can load 80KB, but the software implementation must be aligned to the lowest common denominator. -.. _Trusted Board Boot: ../trusted-board-boot.rst .. _UniPhier BL: https://github.com/uniphier/uniphier-bl -.. _Firmware Design: ../firmware-design.rst .. _U-Boot: https://www.denx.de/wiki/U-Boot .. _mbed TLS: https://tls.mbed.org/ -.. _User Guide: ../user-guide.rst diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst index 88251d6af..2c372a6a3 100644 --- a/docs/plat/stm32mp1.rst +++ b/docs/plat/stm32mp1.rst @@ -76,21 +76,34 @@ ROM code -> BL2 (compiled with BL2_AT_EL3) -> 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`` -To build with SP_min: +To build with SP_min and support for all bootable devices: .. code:: bash - make CROSS_COMPILE=arm-linux-gnueabihf- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 AARCH32_SP=sp_min DTB_FILE_NAME=stm32mp157c-ev1.dtb + make CROSS_COMPILE=arm-linux-gnueabihf- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 AARCH32_SP=sp_min STM32MP_SDMMC=1 STM32MP_EMMC=1 STM32MP_RAW_NAND=1 STM32MP_SPI_NAND=1 + STM32MP_SPI_NOR=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb cd <u-boot_directory> make stm32mp15_trusted_defconfig make DEVICE_TREE=stm32mp157c-ev1 all -To build TF-A with with Op-TEE support: - +To build TF-A with OP-TEE support for all bootable devices: .. code:: bash - make CROSS_COMPILE=arm-linux-gnueabihf- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 AARCH32_SP=optee + make CROSS_COMPILE=arm-linux-gnueabihf- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 AARCH32_SP=optee STM32MP_SDMMC=1 STM32MP_EMMC=1 STM32MP_RAW_NAND=1 STM32MP_SPI_NAND=1 STM32MP_SPI_NOR=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb + cd <optee_directory> + make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts + cd <u-boot_directory> + make stm32mp15_optee_defconfig + make DEVICE_TREE=stm32mp157c-ev1 all + The following build options are supported: diff --git a/docs/plat/xilinx-versal.rst b/docs/plat/xilinx-versal.rst index 231286e7e..57a363bc9 100644 --- a/docs/plat/xilinx-versal.rst +++ b/docs/plat/xilinx-versal.rst @@ -14,7 +14,7 @@ To build: make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 ``` -To build ATF for different platform (for now its just versal virtual "versal_virt") +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 ``` @@ -33,3 +33,11 @@ Xilinx Versal platform specific build options * `VERSAL_PLATFORM`: Select the platform. Options: - `versal_virt` : Versal Virtual platform + +# 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/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index a53da77b9..cb8b89245 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -23,8 +23,8 @@ include: - ``**WARNING: Use of volatile is usually wrong``: see `Why the “volatile” type class should not be used`_ . Although this document - contains some very useful information, there are several legimate uses of the - volatile keyword within the TF codebase. + contains some very useful information, there are several legitimate uses of + the volatile keyword within the TF codebase. Headers and inclusion --------------------- diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst index 66b282c91..f569fcbe7 100644 --- a/docs/process/contributing.rst +++ b/docs/process/contributing.rst @@ -13,8 +13,8 @@ Getting Started raise a separate `issue`_ for this and ensure that the changes that include Third Party IP are made on a separate topic branch. -- Clone `Trusted Firmware-A`_ on your own machine as suggested on the - `User Guide`_. +- Clone `Trusted Firmware-A`_ on your own machine as described in + :ref:`prerequisites_get_source`. - Create a local topic branch based on the `Trusted Firmware-A`_ ``master`` branch. @@ -23,11 +23,10 @@ Making Changes - Make commits of logical units. See these general `Git guidelines`_ for contributing to a project. -- Follow the `Coding Guidelines`_. +- Follow the :ref:`Coding Style & Guidelines`. - Use the checkpatch.pl script provided with the Linux source tree. A - Makefile target is provided for convenience (see the "Checking source code - style" section in the `User Guide`_). + Makefile target is provided for convenience. - Keep the commits on topic. If you need to fix another bug or make another enhancement, please create a separate `issue`_ and address it on a separate @@ -38,12 +37,13 @@ Making Changes an `issue`_, include a reference. - Where appropriate, please update the documentation. - - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ - or other in-source documentation needs updating. + - Consider whether the :ref:`Porting Guide`, + :ref:`Firmware Design` document or other in-source documentation needs + updating. - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of contributions to this project should have a copyright notice and BSD-3-Clause SPDX license - identifier of the form as shown in `license.rst`_. Files that contain + identifier of the form as shown in :ref:`license`. Files that contain changes to imported Third Party IP files should retain their original copyright and license notices. For significant contributions you may add your own copyright notice in following format: @@ -57,15 +57,15 @@ Making Changes your company name. - If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform port), then also update - the `Maintainers`_ file. + the :ref:`maintainers` file. - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit of the series. Otherwise, include the documentation changes within the single commit. - Please test your changes. As a minimum, ensure that Linux boots on the - Foundation FVP. See `Running the software on FVP`_ for more information. For - more extensive testing, consider running the `TF-A Tests`_ against your - patches. + Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more + information. For more extensive testing, consider running the `TF-A Tests`_ + against your patches. Submitting Changes ------------------ @@ -75,13 +75,15 @@ Submitting Changes ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes to the commit, they must also add their own ``Signed-off-by:`` line. By adding this line the contributor certifies the contribution is made - under the terms of the `Developer Certificate of Origin (DCO)`_. + under the terms of the + :download:`Developer Certificate of Origin <../../dco.txt>`. More details may be found in the `Gerrit Signed-off-by Lines guidelines`_. - Ensure that each commit also has a unique ``Change-Id:`` line. If you have cloned the repository with the "`Clone with commit-msg hook`" clone method - (as advised on the `User Guide`_), this should already be the case. + (following the :ref:`Prerequisites` document), this should already be the + case. More details may be found in the `Gerrit Change-Ids documentation`_. @@ -89,22 +91,22 @@ Submitting Changes targeting the ``integration`` branch. - The changes will then undergo further review and testing by the - `Maintainers`_. Any review comments will be made directly on your patch. - This may require you to do some rework. + :ref:`maintainers`. Any review comments will be made directly on your + patch. This may require you to do some rework. Refer to the `Gerrit Uploading Changes documentation`_ for more details. -- When the changes are accepted, the `Maintainers`_ will integrate them. +- When the changes are accepted, the :ref:`maintainers` will integrate them. - - Typically, the `Maintainers`_ will merge the changes into the + - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch. - If the changes are not based on a sufficiently-recent commit, or if they - cannot be automatically rebased, then the `Maintainers`_ may rebase it on - the ``master`` branch or ask you to do so. + cannot be automatically rebased, then the :ref:`maintainers` may rebase it + on the ``master`` branch or ask you to do so. - After final integration testing, the changes will make their way into the ``master`` branch. If a problem is found during integration, the merge commit will be removed from the ``integration`` branch and the - `Maintainers`_ will ask you to create a new patch set to resolve the + :ref:`maintainers` will ask you to create a new patch set to resolve the problem. Binary Components @@ -132,15 +134,6 @@ Binary Components .. _issue: https://developer.trustedfirmware.org/project/board/1/ .. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git .. _Git guidelines: http://git-scm.com/book/ch5-2.html -.. _Coding Guidelines: ./coding-guidelines.rst -.. _User Guide: ../getting_started/user-guide.rst -.. _Porting Guide: ../getting_started/porting-guide.rst -.. _Firmware Design: ../design/firmware-design.rst -.. _license.rst: ../license.rst -.. _Acknowledgements: ../acknowledgements.rst -.. _Maintainers: ../maintainers.rst -.. _Running the software on FVP: ../getting_started/user-guide.rst#user-content-running-the-software-on-fvp -.. _Developer Certificate of Origin (DCO): ../../dco.txt .. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html .. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html .. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html diff --git a/docs/process/faq.rst b/docs/process/faq.rst index 6aa04f0a8..2c3658480 100644 --- a/docs/process/faq.rst +++ b/docs/process/faq.rst @@ -37,7 +37,7 @@ This can vary a lot, depending on: conflict between the topics. * If there is a code freeze in place in preparation for the release. Please - refer the `release information`_ for more details. + refer the :ref:`Release Processes` document for more details. * The workload of the TF maintainers. @@ -55,9 +55,9 @@ receiving patches that will not be merged into the release. In this case, the patches will be merged onto ``integration``, which will temporarily diverge from the release branch. The ``integration`` branch will be rebased onto ``master`` after the release, and then ``master`` will be fast-forwarded to ``integration`` -1-2 days later. This whole process could take up 4 weeks. Please refer the -`release information`_ for code freeze dates. The TF maintainers will inform the -patch owner if this is going to happen. +1-2 days later. This whole process could take up 4 weeks. Please refer to the +:ref:`Release Processes` document for code freeze dates. The TF maintainers +will inform the patch owner if this is going to happen. It is OK to create a patch based on commits that are only available in ``integration`` or another patch set, rather than ``master``. There is a risk @@ -73,7 +73,10 @@ but would be after the CI has been transitioned to `trustedfirmware.org`_. Please refer to https://github.com/ARM-software/tf-issues/issues/681 for more details on the timelines. -.. _release information: release-information.rst +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* + .. _Gerrit Upload Patch Set documentation: https://review.trustedfirmware.org/Documentation/intro-user.html#upload-patch-set .. _Gerrit Replace Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html#push_replace .. _trustedfirmware.org: https://www.trustedfirmware.org/ diff --git a/docs/process/index.rst b/docs/process/index.rst index a870c8f57..9c12de82f 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -6,7 +6,6 @@ Processes & Policies :caption: Contents :numbered: - release-information security platform-compatibility-policy coding-guidelines diff --git a/docs/process/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst index a11ba3860..be1f9bac3 100644 --- a/docs/process/platform-compatibility-policy.rst +++ b/docs/process/platform-compatibility-policy.rst @@ -11,7 +11,7 @@ Platform compatibility policy ----------------------------- Platform compatibility is mainly affected by changes to Platform APIs (as -documented in the `Porting Guide`_), driver APIs (like the GICv3 drivers) or +documented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or library interfaces (like xlat_table library). The project will try to maintain compatibility for upstream platforms. Due to evolving requirements and enhancements, there might be changes affecting platform compatibility which @@ -20,7 +20,7 @@ introduced to replace it. In case the migration to the new interface is trivial, the contributor of the change is expected to make good effort to migrate the upstream platforms to the new interface. -The deprecated interfaces are listed inside `Release information`_ as well as +The deprecated interfaces are listed inside :ref:`Release Processes` as well as the release after which each one will be removed. When an interface is deprecated, the page must be updated to indicate the release after which the interface will be removed. This must be at least 1 full release cycle in future. @@ -33,6 +33,4 @@ the deprecated interface. *Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* -.. _Porting Guide: ../getting_started/porting-guide.rst -.. _Release information: ./release-information.rst#removal-of-deprecated-interfaces .. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a diff --git a/docs/process/release-information.rst b/docs/process/release-information.rst deleted file mode 100644 index b81d42d59..000000000 --- a/docs/process/release-information.rst +++ /dev/null @@ -1,82 +0,0 @@ -Release Processes -================= - -Project Release Cadence ------------------------ - -The project currently aims to do a release once every 6 months which will be -tagged on the master branch. There will be a code freeze (stop merging -non-essential PRs) up to 4 weeks prior to the target release date. The release -candidates will start appearing after this and only bug fixes or updates -required for the release will be merged. The maintainers are free to use their -judgement on what PRs are essential for the release. A release branch may be -created after code freeze if there are significant PRs that need merging onto -the integration branch during the merge window. - -The release testing will be performed on release candidates and depending on -issues found, additional release candidates may be created to fix the issues. - -:: - - |<----------6 months---------->| - |<---4 weeks--->| |<---4 weeks--->| - +-----------------------------------------------------------> time - | | | | - code freeze ver w.x code freeze ver y.z - - -Upcoming Releases -~~~~~~~~~~~~~~~~~ - -These are the estimated dates for the upcoming release. These may change -depending on project requirement and partner feedback. - -+-----------------+---------------------------+------------------------------+ -| Release Version | Target Date | Expected Code Freeze | -+=================+===========================+==============================+ -| v2.0 | 1st week of Oct '18 | 1st week of Sep '18 | -+-----------------+---------------------------+------------------------------+ -| v2.1 | 5th week of Mar '19 | 1st week of Mar '19 | -+-----------------+---------------------------+------------------------------+ - -Removal of Deprecated Interfaces --------------------------------- - -As mentioned in the `Platform compatibility policy`_, this is a live document -cataloging all the deprecated interfaces in TF-A project and the Release version -after which it will be removed. - -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Interface | Deprecation | Removed | Comments | -| | Date | after | | -| | | Release | | -+================================+=============+=========+=========================================================+ -| Legacy Console API | Jan '18 | v2.1 | Deprecated in favour of ``MULTI_CONSOLE_API`` | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Weak default | Oct '18 | v2.1 | The default implementations are defined in | -| ``plat_crash_console_*`` | | | `crash_console_helpers.S`_. The platforms have to | -| APIs | | | define ``plat_crash_console_*``. | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| ``finish_console_register`` | Oct '18 | v2.1 | The old version of the macro is deprecated. See commit | -| macro in | | | cc5859c_ for more details. | -| ``MULTI_CONSOLE_API`` | | | | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Types ``tzc_action_t`` and | Oct '18 | v2.1 | Using logical operations such as OR in enumerations | -| ``tzc_region_attributes_t`` | | | goes against the MISRA guidelines. | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Macro ``EL_IMPLEMENTED()`` | Oct '18 | v2.1 | Deprecated in favour of ``el_implemented()``. | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| ``get_afflvl_shift()``, | Dec '18 | v2.1 | Removed. | -| ``mpidr_mask_lower_afflvls()``,| | | | -| and ``eret()``. | | | | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Extra include paths in the | Jan '18 | v2.1 | Now it is needed to use the full path of the common | -| Makefile in ``INCLUDES``. | | | header files. More information in commit 09d40e0e0828_. | -+--------------------------------+-------------+---------+---------------------------------------------------------+ - -*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* - -.. _Platform compatibility policy: platform-compatibility-policy.rst -.. _crash_console_helpers.S: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/common/aarch64/crash_console_helpers.S -.. _cc5859c: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=cc5859ca19ff546c35eb0331000dae090b6eabcf -.. _09d40e0e0828: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=09d40e0e08283a249e7dce0e106c07c5141f9b7e diff --git a/docs/process/security-hardening.rst b/docs/process/security-hardening.rst index e2c68b8fe..a18a79203 100644 --- a/docs/process/security-hardening.rst +++ b/docs/process/security-hardening.rst @@ -9,7 +9,7 @@ Build options ------------- Several build options can be used to check for security issues. Refer to the -`user guide`_ for detailed information on the specific build options. +:ref:`Build Options` for detailed information on these. - The ``BRANCH_PROTECTION`` build flag can be used to enable Pointer Authentication and Branch Target Identification. @@ -30,20 +30,18 @@ Several build options can be used to check for security issues. Refer to the - W=1 - Adds ``Wextra``, ``Wmissing-declarations``, ``Wmissing-format-attribute``, - ``Wmissing-prototypes``, ``Wold-style-definition`` and - ``Wunused-const-variable``. + Adds ``Wextra``, ``Wmissing-format-attribute``, ``Wmissing-prototypes``, + ``Wold-style-definition`` and ``Wunused-const-variable``. - W=2 Adds ``Waggregate-return``, ``Wcast-align``, ``Wnested-externs``, - ``Wshadow``, ``Wlogical-op``, ``Wmissing-field-initializers`` and - ``Wsign-compare``. + ``Wshadow``, ``Wlogical-op``. - W=3 Adds ``Wbad-function-cast``, ``Wcast-qual``, ``Wconversion``, ``Wpacked``, - ``Wpadded``, ``Wpointer-arith``, ``Wredundant-decls`` and + ``Wpointer-arith``, ``Wredundant-decls`` and ``Wswitch-default``. Refer to the GCC or Clang documentation for more information on the individual @@ -53,6 +51,6 @@ Several build options can be used to check for security issues. Refer to the NB: The ``Werror`` flag is enabled by default in TF-A and can be disabled by setting the ``E`` build flag to 0. -*Copyright (c) 2019, Arm Limited. All rights reserved.* +-------------- -.. _user guide: ../getting_started/user-guide.rst +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/process/security.rst b/docs/process/security.rst index 94eb9c3bf..c3935daa1 100644 --- a/docs/process/security.rst +++ b/docs/process/security.rst @@ -38,9 +38,11 @@ Please include: - Any additional software or tools required -We recommend using `this PGP/GPG key`_ for encrypting the information. This key -is also available at http://keyserver.pgp.com and LDAP port 389 of the same -server. The fingerprint for this key is: +We recommend using :download:`this PGP/GPG key <./security-reporting.asc>` for +encrypting the information. This key is also available at +http://keyserver.pgp.com and LDAP port 389 of the same server. + +The fingerprint for this key is: :: @@ -59,7 +61,7 @@ code. Attribution ----------- -We will name and thank you in the ``change-log.rst`` distributed with the source +We will name and thank you in the :ref:`Change Log & Release Notes` distributed with the source code and in any published security advisory. Security Advisories @@ -68,38 +70,43 @@ Security Advisories +-----------+------------------------------------------------------------------+ | ID | Title | +===========+==================================================================+ -| `TFV-1`_ | Malformed Firmware Update SMC can result in copy of unexpectedly | +| |TFV-1| | Malformed Firmware Update SMC can result in copy of unexpectedly | | | large data into secure memory | +-----------+------------------------------------------------------------------+ -| `TFV-2`_ | Enabled secure self-hosted invasive debug interface can allow | +| |TFV-2| | Enabled secure self-hosted invasive debug interface can allow | | | normal world to panic secure world | +-----------+------------------------------------------------------------------+ -| `TFV-3`_ | RO memory is always executable at AArch64 Secure EL1 | +| |TFV-3| | RO memory is always executable at AArch64 Secure EL1 | +-----------+------------------------------------------------------------------+ -| `TFV-4`_ | Malformed Firmware Update SMC can result in copy or | +| |TFV-4| | Malformed Firmware Update SMC can result in copy or | | | authentication of unexpected data in secure memory in AArch32 | | | state | +-----------+------------------------------------------------------------------+ -| `TFV-5`_ | Not initializing or saving/restoring PMCR_EL0 can leak secure | +| |TFV-5| | Not initializing or saving/restoring PMCR_EL0 can leak secure | | | world timing information | +-----------+------------------------------------------------------------------+ -| `TFV-6`_ | Trusted Firmware-A exposure to speculative processor | +| |TFV-6| | Trusted Firmware-A exposure to speculative processor | | | vulnerabilities using cache timing side-channels | +-----------+------------------------------------------------------------------+ -| `TFV-7`_ | Trusted Firmware-A exposure to cache speculation vulnerability | +| |TFV-7| | Trusted Firmware-A exposure to cache speculation vulnerability | | | Variant 4 | +-----------+------------------------------------------------------------------+ -| `TFV-8`_ | Not saving x0 to x3 registers can leak information from one | +| |TFV-8| | Not saving x0 to x3 registers can leak information from one | | | Normal World SMC client to another | +-----------+------------------------------------------------------------------+ .. _issue tracker: https://developer.trustedfirmware.org/project/board/1/ .. _this PGP/GPG key: security-reporting.asc -.. _TFV-1: ../security_advisories/security-advisory-tfv-1.rst -.. _TFV-2: ../security_advisories/security-advisory-tfv-2.rst -.. _TFV-3: ../security_advisories/security-advisory-tfv-3.rst -.. _TFV-4: ../security_advisories/security-advisory-tfv-4.rst -.. _TFV-5: ../security_advisories/security-advisory-tfv-5.rst -.. _TFV-6: ../security_advisories/security-advisory-tfv-6.rst -.. _TFV-7: ../security_advisories/security-advisory-tfv-7.rst -.. _TFV-8: ../security_advisories/security-advisory-tfv-8.rst + +.. |TFV-1| replace:: :ref:`Advisory TFV-1 (CVE-2016-10319)` +.. |TFV-2| replace:: :ref:`Advisory TFV-2 (CVE-2017-7564)` +.. |TFV-3| replace:: :ref:`Advisory TFV-3 (CVE-2017-7563)` +.. |TFV-4| replace:: :ref:`Advisory TFV-4 (CVE-2017-9607)` +.. |TFV-5| replace:: :ref:`Advisory TFV-5 (CVE-2017-15031)` +.. |TFV-6| replace:: :ref:`Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754)` +.. |TFV-7| replace:: :ref:`Advisory TFV-7 (CVE-2018-3639)` +.. |TFV-8| replace:: :ref:`Advisory TFV-8 (CVE-2018-19440)` + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml b/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml index 2752b3326..b7289a246 100644 --- a/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml +++ b/docs/resources/diagrams/plantuml/io_dev_init_and_check.puml @@ -1,7 +1,7 @@ @startuml -participant arm_io_storage order 1 -participant io_storage order 2 +participant arm_io_storage +participant io_storage -> arm_io_storage : plat_get_image_source(image_id, &dev_handle, &image_spec) diff --git a/docs/resources/diagrams/plantuml/io_dev_registration.puml b/docs/resources/diagrams/plantuml/io_dev_registration.puml index 114c3b778..c6f330e6a 100644 --- a/docs/resources/diagrams/plantuml/io_dev_registration.puml +++ b/docs/resources/diagrams/plantuml/io_dev_registration.puml @@ -1,9 +1,9 @@ @startuml -participant arm_io_storage order 1 -participant io_storage order 2 -participant io_fip order 3 -participant io_memmap order 4 +participant arm_io_storage +participant io_storage +participant io_fip +participant io_memmap -> arm_io_storage : arm_io_setup() diff --git a/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml b/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml index eb3e2b4c7..b21a0ae5d 100644 --- a/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml +++ b/docs/resources/diagrams/plantuml/io_framework_usage_overview.puml @@ -1,8 +1,8 @@ @startuml -participant bl_common order 1 -participant arm_io_storage order 2 -participant io_storage order 3 +participant bl_common +participant arm_io_storage +participant io_storage == Platform Setup == diff --git a/docs/security_advisories/security-advisory-tfv-5.rst b/docs/security_advisories/security-advisory-tfv-5.rst index 2214f2d50..97f7cd98c 100644 --- a/docs/security_advisories/security-advisory-tfv-5.rst +++ b/docs/security_advisories/security-advisory-tfv-5.rst @@ -7,9 +7,9 @@ Advisory TFV-5 (CVE-2017-15031) +================+=============================================================+ | CVE ID | `CVE-2017-15031`_ | +----------------+-------------------------------------------------------------+ -| Date | 02 Oct 2017 | +| Date | 02 Oct 2017, updated on 04 Nov 2019 | +----------------+-------------------------------------------------------------+ -| Versions | All, up to and including v1.4 | +| Versions | All, up to and including v2.1 | | Affected | | +----------------+-------------------------------------------------------------+ | Configurations | All | @@ -18,8 +18,12 @@ Advisory TFV-5 (CVE-2017-15031) | Impact | Leakage of sensitive secure world timing information | +----------------+-------------------------------------------------------------+ | Fix Version | `Pull Request #1127`_ (merged on 18 October 2017) | +| | | +| | `Commit e290a8fcbc`_ (merged on 23 August 2019) | +| | | +| | `Commit c3e8b0be9b`_ (merged on 27 September 2019) | +----------------+-------------------------------------------------------------+ -| Credit | Arm | +| Credit | Arm, Marek Bykowski | +----------------+-------------------------------------------------------------+ The ``PMCR_EL0`` (Performance Monitors Control Register) provides details of the @@ -28,10 +32,11 @@ implemented, and configures and controls the counters. If the ``PMCR_EL0.DP`` bit is set to zero, the cycle counter (when enabled) counts during secure world execution, even when prohibited by the debug signals. -Since Arm TF does not save and restore ``PMCR_EL0`` when switching between the +Since TF-A does not save and restore ``PMCR_EL0`` when switching between the normal and secure worlds, normal world code can set ``PMCR_EL0.DP`` to zero to cause leakage of secure world timing information. This register should be added -to the list of saved/restored registers. +to the list of saved/restored registers both when entering EL3 and also +transitioning to S-EL1. Furthermore, ``PMCR_EL0.DP`` has an architecturally ``UNKNOWN`` reset value. Since Arm TF does not initialize this register, it's possible that on at least @@ -42,5 +47,11 @@ sensible default values in the secure context. The same issue exists for the equivalent AArch32 register, ``PMCR``, except that here ``PMCR_EL0.DP`` architecturally resets to zero. +NOTE: The original pull request referenced above only fixed the issue for S-EL1 +whereas the EL3 was fixed in the later commits. + .. _CVE-2017-15031: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-15031 .. _Pull Request #1127: https://github.com/ARM-software/arm-trusted-firmware/pull/1127 +.. _Commit e290a8fcbc: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=e290a8fcbc +.. _Commit c3e8b0be9b: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=c3e8b0be9b + diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst index 495edddae..9eeaeec57 100644 --- a/docs/security_advisories/security-advisory-tfv-6.rst +++ b/docs/security_advisories/security-advisory-tfv-6.rst @@ -51,7 +51,7 @@ the MMU. For Cortex-A73 and Cortex-A75 CPUs, the PRs in this advisory invalidate the branch predictor when entering EL3 by temporarily dropping into AArch32 Secure-EL1 and executing the ``BPIALL`` instruction. This workaround is -signifiantly more complex than the "MMU disable/enable" workaround. The latter +significantly more complex than the "MMU disable/enable" workaround. The latter is not effective at invalidating the branch predictor on Cortex-A73/Cortex-A75. Note that if other privileged software, for example a Rich OS kernel, implements |