1Trusted Firmware-A - version 2.1 2================================ 3 4Trusted Firmware-A (TF-A) provides a reference implementation of secure world 5software for `Armv7-A and Armv8-A`_, including a `Secure Monitor`_ executing 6at Exception Level 3 (EL3). It implements various Arm interface standards, 7such as: 8 9- The `Power State Coordination Interface (PSCI)`_ 10- Trusted Board Boot Requirements (TBBR, Arm DEN0006C-1) 11- `SMC Calling Convention`_ 12- `System Control and Management Interface (SCMI)`_ 13- `Software Delegated Exception Interface (SDEI)`_ 14 15Where possible, the code is designed for reuse or porting to other Armv7-A and 16Armv8-A model and hardware platforms. 17 18This release provides a suitable starting point for productization of secure 19world boot and runtime firmware, in either the AArch32 or AArch64 execution 20states. 21 22Users are encouraged to do their own security validation, including penetration 23testing, on any secure world code derived from TF-A. 24 25Arm will continue development in collaboration with interested parties to 26provide a full reference implementation of Secure Monitor code and Arm standards 27to the benefit of all developers working with Armv7-A and Armv8-A TrustZone 28technology. 29 30License 31------- 32 33The software is provided under a BSD-3-Clause `license`_. Contributions to this 34project are accepted under the same license with developer sign-off as 35described in the `Contributing Guidelines`_. 36 37This project contains code from other projects as listed below. The original 38license text is included in those source files. 39 40- The libc source code is derived from `FreeBSD`_ and `SCC`_. FreeBSD uses 41 various BSD licenses, including BSD-3-Clause and BSD-2-Clause. The SCC code 42 is used under the BSD-3-Clause license with the author's permission. 43 44- The libfdt source code is disjunctively dual licensed 45 (GPL-2.0+ OR BSD-2-Clause). It is used by this project under the terms of 46 the BSD-2-Clause license. Any contributions to this code must be made under 47 the terms of both licenses. 48 49- The LLVM compiler-rt source code is disjunctively dual licensed 50 (NCSA OR MIT). It is used by this project under the terms of the NCSA 51 license (also known as the University of Illinois/NCSA Open Source License), 52 which is a permissive license compatible with BSD-3-Clause. Any 53 contributions to this code must be made under the terms of both licenses. 54 55- The zlib source code is licensed under the Zlib license, which is a 56 permissive license compatible with BSD-3-Clause. 57 58- Some STMicroelectronics platform source code is disjunctively dual licensed 59 (GPL-2.0+ OR BSD-3-Clause). It is used by this project under the terms of the 60 BSD-3-Clause license. Any contributions to this code must be made under the 61 terms of both licenses. 62 63Functionality 64------------- 65 66- Initialization of the secure world, for example exception vectors, control 67 registers and interrupts for the platform. 68 69- Library support for CPU specific reset and power down sequences. This 70 includes support for errata workarounds and the latest Arm DynamIQ CPUs. 71 72- Drivers to enable standard initialization of Arm System IP, for example 73 Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI), 74 Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone 75 Controller (TZC). 76 77- A generic `SCMI`_ driver to interface with conforming power controllers, for 78 example the Arm System Control Processor (SCP). 79 80- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling 81 Convention`_ using an EL3 runtime services framework. 82 83- `PSCI`_ library support for CPU, cluster and system power management 84 use-cases. 85 This library is pre-integrated with the AArch64 EL3 Runtime Software, and 86 is also suitable for integration with other AArch32 EL3 Runtime Software, 87 for example an AArch32 Secure OS. 88 89- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library 90 integration with AArch32 EL3 Runtime Software. 91 92- Secure Monitor library code such as world switching, EL1 context management 93 and interrupt routing. 94 When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the 95 AArch64 EL3 Runtime Software must be integrated with a Secure Payload 96 Dispatcher (SPD) component to customize the interaction with the SP. 97 98- A Test SP and SPD to demonstrate AArch64 Secure Monitor functionality and SP 99 interaction with PSCI. 100 101- SPDs for the `OP-TEE Secure OS`_, `NVIDIA Trusted Little Kernel`_ 102 and `Trusty Secure OS`_. 103 104- A Trusted Board Boot implementation, conforming to all mandatory TBBR 105 requirements. This includes image authentication, Firmware Update (or 106 recovery mode), and packaging of the various firmware images into a 107 Firmware Image Package (FIP). 108 109- Pre-integration of TBB with the Arm CryptoCell product, to take advantage of 110 its hardware Root of Trust and crypto acceleration services. 111 112- Reliability, Availability, and Serviceability (RAS) functionality, including 113 114 - A Secure Partition Manager (SPM) to manage Secure Partitions in 115 Secure-EL0, which can be used to implement simple management and 116 security services. 117 118 - An SDEI dispatcher to route interrupt-based SDEI events. 119 120 - An Exception Handling Framework (EHF) that allows dispatching of EL3 121 interrupts to their registered handlers, to facilitate firmware-first 122 error handling. 123 124- A dynamic configuration framework that enables each of the firmware images 125 to be configured at runtime if required by the platform. It also enables 126 loading of a hardware configuration (for example, a kernel device tree) 127 as part of the FIP, to be passed through the firmware stages. 128 129- Support for alternative boot flows, for example to support platforms where 130 the EL3 Runtime Software is loaded using other firmware or a separate 131 secure system processor, or where a non-TF-A ROM expects BL2 to be loaded 132 at EL3. 133 134- Support for the GCC, LLVM and Arm Compiler 6 toolchains. 135 136- Support for combining several libraries into a "romlib" image that may be 137 shared across images to reduce memory footprint. The romlib image is stored 138 in ROM but is accessed through a jump-table that may be stored 139 in read-write memory, allowing for the library code to be patched. 140 141- A prototype implementation of a Secure Partition Manager (SPM) that is based 142 on the SPCI Alpha 1 and SPRT draft specifications. 143 144- Support for ARMv8.3 pointer authentication in the normal and secure worlds. 145 The use of pointer authentication in the normal world is enabled whenever 146 architectural support is available, without the need for additional build 147 flags. Use of pointer authentication in the secure world remains an 148 experimental configuration at this time and requires the ``ENABLE_PAUTH`` 149 build flag to be set. 150 151- Position-Independent Executable (PIE) support. Initially for BL31 only, with 152 further support to be added in a future release. 153 154For a full description of functionality and implementation details, please 155see the `Firmware Design`_ and supporting documentation. The `Change Log`_ 156provides details of changes made since the last release. 157 158Platforms 159--------- 160 161Various AArch32 and AArch64 builds of this release have been tested on r0, r1 162and r2 variants of the `Juno Arm Development Platform`_. 163 164The latest version of the AArch64 build of TF-A has been tested on the following 165Arm FVPs without shifted affinities, and that do not support threaded CPU cores 166(64-bit host machine only). 167 168The FVP models used are Version 11.5 Build 33, unless otherwise stated. 169 170- ``FVP_Base_AEMv8A-AEMv8A`` 171- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` 172- ``FVP_Base_RevC-2xAEMv8A`` 173- ``FVP_Base_Cortex-A32x4`` 174- ``FVP_Base_Cortex-A35x4`` 175- ``FVP_Base_Cortex-A53x4`` 176- ``FVP_Base_Cortex-A55x4+Cortex-A75x4`` 177- ``FVP_Base_Cortex-A55x4`` 178- ``FVP_Base_Cortex-A57x1-A53x1`` 179- ``FVP_Base_Cortex-A57x2-A53x4`` 180- ``FVP_Base_Cortex-A57x4-A53x4`` 181- ``FVP_Base_Cortex-A57x4`` 182- ``FVP_Base_Cortex-A72x4-A53x4`` 183- ``FVP_Base_Cortex-A72x4`` 184- ``FVP_Base_Cortex-A73x4-A53x4`` 185- ``FVP_Base_Cortex-A73x4`` 186- ``FVP_Base_Cortex-A75x4`` 187- ``FVP_Base_Cortex-A76x4`` 188- ``FVP_Base_Neoverse-N1x4`` (Tested with internal model) 189- ``FVP_Base_Deimos`` 190- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) 191- ``FVP_CSS_SGM-775`` (Version 11.3 build 42) 192- ``FVP_RD_E1Edge`` (Version 11.3 build 42) 193- ``FVP_RD_N1Edge`` (Version 11.3 build 42) 194- ``Foundation_Platform`` 195 196The latest version of the AArch32 build of TF-A has been tested on the following 197Arm FVPs without shifted affinities, and that do not support threaded CPU cores 198(64-bit host machine only). 199 200- ``FVP_Base_AEMv8A-AEMv8A`` 201- ``FVP_Base_Cortex-A32x4`` 202 203NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities. 204 205The Foundation FVP can be downloaded free of charge. The Base FVPs can be 206licensed from Arm. See the `Arm FVP website`_. 207 208All the above platforms have been tested with `Linaro Release 18.04`_. 209 210This release also contains the following platform support: 211 212- Allwinner sun50i_a64 and sun50i_h6 213- Amlogic Meson S905 (GXBB) 214- Amlogic Meson S905x (GXL) 215- Arm Juno Software Development Platform 216- Arm Neoverse N1 System Development Platform (N1SDP) 217- Arm Neoverse Reference Design N1 Edge (RD-N1-Edge) FVP 218- Arm Neoverse Reference Design E1 Edge (RD-E1-Edge) FVP 219- Arm SGI-575 and SGM-775 220- Arm Versatile Express FVP 221- HiKey, HiKey960 and Poplar boards 222- Intel Stratix 10 SoC FPGA 223- Marvell Armada 3700 and 8K 224- MediaTek MT6795 and MT8173 SoCs 225- NVIDIA T132, T186 and T210 SoCs 226- NXP QorIQ LS1043A, i.MX8MM, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7 227- QEMU 228- Raspberry Pi 3 229- Renesas R-Car Generation 3 230- RockChip RK3328, RK3368 and RK3399 SoCs 231- Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs 232- STMicroelectronics STM32MP1 233- Texas Instruments K3 SoCs 234- Xilinx Versal and Zynq UltraScale + MPSoC 235 236Still to come 237------------- 238 239- Support for additional platforms. 240 241- Refinements to Position Independent Executable (PIE) support. 242 243- Refinements to the SPCI-based SPM implementation as the draft SPCI and SPRT 244 specifications continue to evolve. 245 246- Documentation enhancements. 247 248- Ongoing support for new architectural features, CPUs and System IP. 249 250- Ongoing support for new Arm system architecture specifications. 251 252- Ongoing security hardening, optimization and quality improvements. 253 254For a full list of detailed issues in the current code, please see the `Change 255Log`_ and the `issue tracker`_. 256 257Getting started 258--------------- 259 260See the `User Guide`_ for instructions on how to download, install, build and 261use TF-A with the Arm `FVP`_\ s. 262 263See the `Firmware Design`_ for information on how TF-A works. 264 265See the `Porting Guide`_ as well for information about how to use this 266software on another Armv7-A or Armv8-A platform. 267 268See the `Contributing Guidelines`_ for information on how to contribute to this 269project and the `Acknowledgments`_ file for a list of contributors to the 270project. 271 272Documentation contents 273~~~~~~~~~~~~~~~~~~~~~~ 274 275The `Trusted Firmware-A Documentation Contents`_ page contains an overview of 276the documentation that is available, with links to facilitate easier browsing. 277 278IRC channel 279~~~~~~~~~~~ 280 281Development discussion takes place on the #trusted-firmware-a channel 282on the Freenode IRC network. This is not an official support channel. 283If you have an issue to raise, please use the `issue tracker`_. 284 285Feedback and support 286~~~~~~~~~~~~~~~~~~~~ 287 288Arm welcomes any feedback on TF-A. If you think you have found a security 289vulnerability, please report this using the process defined in the TF-A 290`Security Center`_. For all other feedback, please use the 291`issue tracker`_. 292 293Arm licensees may contact Arm directly via their partner managers. 294 295Security advisories 296------------------- 297 298- `Security Advisory TFV-1`_ 299- `Security Advisory TFV-2`_ 300- `Security Advisory TFV-3`_ 301- `Security Advisory TFV-4`_ 302- `Security Advisory TFV-5`_ 303- `Security Advisory TFV-6`_ 304- `Security Advisory TFV-7`_ 305- `Security Advisory TFV-8`_ 306 307 308-------------- 309 310*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* 311 312.. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile 313.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php 314.. _Power State Coordination Interface (PSCI): PSCI_ 315.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf 316.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf 317.. _System Control and Management Interface (SCMI): SCMI_ 318.. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf 319.. _Software Delegated Exception Interface (SDEI): SDEI_ 320.. _SDEI: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf 321.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php 322.. _Arm FVP website: FVP_ 323.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms 324.. _Linaro Release 18.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease18.04 325.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os 326.. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary 327.. _Trusty Secure OS: https://source.android.com/security/trusty 328.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 329.. _issue tracker: http://issues.trustedfirmware.org 330.. _Security Center: ./docs/security-center.rst 331.. _license: ./license.rst 332.. _Contributing Guidelines: ./contributing.rst 333.. _Acknowledgments: ./acknowledgements.rst 334.. _Firmware Design: ./docs/firmware-design.rst 335.. _Change Log: ./docs/change-log.rst 336.. _User Guide: ./docs/user-guide.rst 337.. _Porting Guide: ./docs/porting-guide.rst 338.. _FreeBSD: http://www.freebsd.org 339.. _SCC: http://www.simple-cc.org/ 340.. _Security Advisory TFV-1: ./docs/security_advisories/security-advisory-tfv-1.rst 341.. _Security Advisory TFV-2: ./docs/security_advisories/security-advisory-tfv-2.rst 342.. _Security Advisory TFV-3: ./docs/security_advisories/security-advisory-tfv-3.rst 343.. _Security Advisory TFV-4: ./docs/security_advisories/security-advisory-tfv-4.rst 344.. _Security Advisory TFV-5: ./docs/security_advisories/security-advisory-tfv-5.rst 345.. _Security Advisory TFV-6: ./docs/security_advisories/security-advisory-tfv-6.rst 346.. _Security Advisory TFV-7: ./docs/security_advisories/security-advisory-tfv-7.rst 347.. _Security Advisory TFV-8: ./docs/security_advisories/security-advisory-tfv-8.rst 348.. _Trusted Firmware-A Documentation Contents: ./docs/contents.rst 349