blob: c87936ceddf19c468eefc14697c69b876fb58103 [file] [log] [blame]
Dan Handleycc573cb2018-03-14 13:01:39 +00001Trusted Firmware-A - version 1.5
Dan Handley610e7e12018-03-01 18:44:00 +00002================================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
Dan Handley610e7e12018-03-01 18:44:00 +00004Trusted Firmware-A (TF-A) provides a reference implementation of secure world
Dan Handleycc573cb2018-03-14 13:01:39 +00005software for `Armv7-A and Armv8-A`_, including a `Secure Monitor`_ executing
6at Exception Level 3 (EL3). It implements various Arm interface standards,
7such as:
Dan Handleyed09d382017-07-05 17:40:29 +01008
9- The `Power State Coordination Interface (PSCI)`_
Dan Handley610e7e12018-03-01 18:44:00 +000010- Trusted Board Boot Requirements (TBBR, Arm DEN0006C-1)
Dan Handleyed09d382017-07-05 17:40:29 +010011- `SMC Calling Convention`_
12- `System Control and Management Interface`_
Dan Handleycc573cb2018-03-14 13:01:39 +000013- `Software Delegated Exception Interface (SDEI)`_
Dan Handleyed09d382017-07-05 17:40:29 +010014
Dan Handleycc573cb2018-03-14 13:01:39 +000015Where possible, the code is designed for reuse or porting to other Armv7-A and
16Armv8-A model and hardware platforms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010017
Dan Handley610e7e12018-03-01 18:44:00 +000018Arm will continue development in collaboration with interested parties to
19provide a full reference implementation of Secure Monitor code and Arm standards
Dan Handleycc573cb2018-03-14 13:01:39 +000020to the benefit of all developers working with Armv7-A and Armv8-A TrustZone
21technology.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010022
23License
24-------
25
26The software is provided under a BSD-3-Clause `license`_. Contributions to this
27project are accepted under the same license with developer sign-off as
28described in the `Contributing Guidelines`_.
29
30This project contains code from other projects as listed below. The original
31license text is included in those source files.
32
Dan Handley4463db82017-07-17 15:19:37 +010033- The stdlib source code is derived from FreeBSD code, which uses various
34 BSD licenses, including BSD-3-Clause and BSD-2-Clause.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010035
36- The libfdt source code is dual licensed. It is used by this project under
37 the terms of the BSD-2-Clause license.
38
Dan Handleyed09d382017-07-05 17:40:29 +010039- The LLVM compiler-rt source code is dual licensed. It is used by this
Dan Handley4463db82017-07-17 15:19:37 +010040 project under the terms of the NCSA license (also known as the University of
41 Illinois/NCSA Open Source License).
Dan Handleyed09d382017-07-05 17:40:29 +010042
Dan Handleycc573cb2018-03-14 13:01:39 +000043- The zlib source code is licensed under the Zlib license, which is a
44 permissive license compatible with BSD-3-Clause.
45
46This release
Douglas Raillardd7c21b72017-06-28 15:23:03 +010047------------
48
49This release provides a suitable starting point for productization of secure
Dan Handleyed09d382017-07-05 17:40:29 +010050world boot and runtime firmware, in either the AArch32 or AArch64 execution
51state.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010052
53Users are encouraged to do their own security validation, including penetration
Dan Handley610e7e12018-03-01 18:44:00 +000054testing, on any secure world code derived from TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010055
56Functionality
57~~~~~~~~~~~~~
58
Dan Handleyed09d382017-07-05 17:40:29 +010059- Initialization of the secure world, for example exception vectors, control
60 registers and interrupts for the platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010061
62- Library support for CPU specific reset and power down sequences. This
Dan Handley610e7e12018-03-01 18:44:00 +000063 includes support for errata workarounds and the latest Arm DynamIQ CPUs.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010064
Dan Handley610e7e12018-03-01 18:44:00 +000065- Drivers to enable standard initialization of Arm System IP, for example
Dan Handleyed09d382017-07-05 17:40:29 +010066 Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI),
67 Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone
68 Controller (TZC).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010069
Dan Handleyed09d382017-07-05 17:40:29 +010070- A generic `SCMI`_ driver to interface with conforming power controllers, for
Dan Handley610e7e12018-03-01 18:44:00 +000071 example the Arm System Control Processor (SCP).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010072
Dan Handleyed09d382017-07-05 17:40:29 +010073- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling
74 Convention`_ using an EL3 runtime services framework.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010075
Dan Handleyed09d382017-07-05 17:40:29 +010076- `PSCI`_ library support for CPU, cluster and system power management
77 use-cases.
78 This library is pre-integrated with the AArch64 EL3 Runtime Software, and
79 is also suitable for integration with other AArch32 EL3 Runtime Software,
80 for example an AArch32 Secure OS.
81
82- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library
83 integration with AArch32 EL3 Runtime Software.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010084
85- Secure Monitor library code such as world switching, EL1 context management
86 and interrupt routing.
Dan Handleyed09d382017-07-05 17:40:29 +010087 When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the
88 AArch64 EL3 Runtime Software must be integrated with a dispatcher component
89 (SPD) to customize the interaction with the SP.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010090
Dan Handleyed09d382017-07-05 17:40:29 +010091- A Test SP/SPD to demonstrate AArch64 Secure Monitor functionality and SP
92 interaction with PSCI.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010093
Dan Handleyed09d382017-07-05 17:40:29 +010094- SPDs for the `OP-TEE Secure OS`_, `NVidia Trusted Little Kernel`_
95 and `Trusty Secure OS`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010096
97- A Trusted Board Boot implementation, conforming to all mandatory TBBR
Dan Handleyed09d382017-07-05 17:40:29 +010098 requirements. This includes image authentication, Firmware Update (or
99 recovery mode), and packaging of the various firmware images into a
100 Firmware Image Package (FIP).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100101
Dan Handleycc573cb2018-03-14 13:01:39 +0000102- Pre-integration of TBB with the Arm CryptoCell product, to take advantage of
103 its hardware Root of Trust and crypto acceleration services.
104
105- Reliability, Availability, and Serviceability (RAS) functionality, including
106
107 - A Secure Partition Manager (SPM) to manage Secure Partitions in
108 Secure-EL0, which can be used to implement simple management and
109 security services.
110
111 - An SDEI dispatcher to route interrupt-based SDEI events.
112
113 - An Exception Handling Framework (EHF) that allows dispatching of EL3
114 interrupts to their registered handlers, to facilitate firmware-first
115 error handling.
116
117- A dynamic configuration framework that enables each of the firmware images
118 to be configured at runtime if required by the platform. It also enables
119 loading of a hardware configuration (for example, a kernel device tree)
120 as part of the FIP, to be passed through the firmware stages.
Dan Handleyed09d382017-07-05 17:40:29 +0100121
122- Support for alternative boot flows, for example to support platforms where
123 the EL3 Runtime Software is loaded using other firmware or a separate
Dan Handleycc573cb2018-03-14 13:01:39 +0000124 secure system processor, or where a non-TF-A ROM expects BL2 to be loaded
125 at EL3.
Dan Handleyed09d382017-07-05 17:40:29 +0100126
Dan Handley610e7e12018-03-01 18:44:00 +0000127- Support for the GCC, LLVM and Arm Compiler 6 toolchains.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100128
129For a full description of functionality and implementation details, please
130see the `Firmware Design`_ and supporting documentation. The `Change Log`_
131provides details of changes made since the last release.
132
133Platforms
134~~~~~~~~~
135
Dan Handleyed09d382017-07-05 17:40:29 +0100136Various AArch32 and AArch64 builds of this release has been tested on variants
Dan Handley610e7e12018-03-01 18:44:00 +0000137r0, r1 and r2 of the `Juno Arm Development Platform`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100138
Dan Handley610e7e12018-03-01 18:44:00 +0000139Various AArch64 builds of this release have been tested on the following Arm
Dan Handleycc573cb2018-03-14 13:01:39 +0000140Fixed Virtual Platforms (`FVP`_) without shifted affinities, and that do not
141support threaded CPU cores (64-bit host machine only):
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100142
Dan Handleycc573cb2018-03-14 13:01:39 +0000143NOTE: Unless otherwise stated, the FVP Version is 11.2 Build 11.2.33.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100144
Dan Handleyed09d382017-07-05 17:40:29 +0100145- ``Foundation_Platform``
Dan Handleycc573cb2018-03-14 13:01:39 +0000146- ``FVP_Base_AEMv8A-AEMv8A`` (and also Version 9.0, Build 0.8.9005)
Dan Handleyed09d382017-07-05 17:40:29 +0100147- ``FVP_Base_Cortex-A35x4``
148- ``FVP_Base_Cortex-A53x4``
149- ``FVP_Base_Cortex-A57x4-A53x4``
150- ``FVP_Base_Cortex-A57x4``
151- ``FVP_Base_Cortex-A72x4-A53x4``
152- ``FVP_Base_Cortex-A72x4``
153- ``FVP_Base_Cortex-A73x4-A53x4``
154- ``FVP_Base_Cortex-A73x4``
Dan Handleycc573cb2018-03-14 13:01:39 +0000155
156Additionally, various AArch64 builds were tested on the following Arm `FVP`_ s
157with shifted affinities, supporting threaded CPU cores (64-bit host machine
158only).
159
160- ``FVP_Base_Cortex-A55x4-A75x4`` (Version 0.0, build 0.0.4395)
161- ``FVP_Base_Cortex-A55x4`` (Version 0.0, build 0.0.4395)
162- ``FVP_Base_Cortex-A75x4`` (Version 0.0, build 0.0.4395)
163- ``FVP_Base_RevC-2xAEMv8A``
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100164
Dan Handley610e7e12018-03-01 18:44:00 +0000165Various AArch32 builds of this release has been tested on the following Arm
Dan Handleycc573cb2018-03-14 13:01:39 +0000166`FVP`_\ s without shifted affinities, and that do not support threaded CPU cores
167(64-bit host machine only):
Dan Handleyed09d382017-07-05 17:40:29 +0100168
Dan Handleycc573cb2018-03-14 13:01:39 +0000169- ``FVP_Base_AEMv8A-AEMv8A``
Dan Handleyed09d382017-07-05 17:40:29 +0100170- ``FVP_Base_Cortex-A32x4``
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100171
172The Foundation FVP can be downloaded free of charge. The Base FVPs can be
Dan Handley610e7e12018-03-01 18:44:00 +0000173licensed from Arm. See the `Arm FVP website`_.
Dan Handleyed09d382017-07-05 17:40:29 +0100174
Dan Handleycc573cb2018-03-14 13:01:39 +0000175All the above platforms have been tested with `Linaro Release 17.10`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100176
177This release also contains the following platform support:
178
Dan Handleycc573cb2018-03-14 13:01:39 +0000179- HiKey, HiKey960 and Poplar boards
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100180- MediaTek MT6795 and MT8173 SoCs
Dan Handleyed09d382017-07-05 17:40:29 +0100181- NVidia T132, T186 and T210 SoCs
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100182- QEMU emulator
Dan Handleycc573cb2018-03-14 13:01:39 +0000183- Raspberry Pi 3 board
Dan Handleyed09d382017-07-05 17:40:29 +0100184- RockChip RK3328, RK3368 and RK3399 SoCs
Sumit Garg760c1d32018-06-21 11:28:18 +0530185- Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs
Nishanth Menon0192f892016-10-14 01:13:34 +0000186- Texas Instruments K3 SoCs
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100187- Xilinx Zynq UltraScale + MPSoC
188
Dan Handleycc573cb2018-03-14 13:01:39 +0000189Still to come
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100190~~~~~~~~~~~~~
191
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100192- More platform support.
193
Dan Handleycc573cb2018-03-14 13:01:39 +0000194- Improved dynamic configuration support.
195
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100196- Ongoing support for new architectural features, CPUs and System IP.
197
Dan Handleycc573cb2018-03-14 13:01:39 +0000198- Ongoing support for new Arm system architecture specifications.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100199
200- Ongoing security hardening, optimization and quality improvements.
201
Dan Handleyed09d382017-07-05 17:40:29 +0100202For a full list of detailed issues in the current code, please see the `Change
203Log`_ and the `GitHub issue tracker`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100204
Dan Handleycc573cb2018-03-14 13:01:39 +0000205Getting started
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100206---------------
207
Dan Handley610e7e12018-03-01 18:44:00 +0000208Get the TF-A source code from `GitHub`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100209
210See the `User Guide`_ for instructions on how to install, build and use
Dan Handley610e7e12018-03-01 18:44:00 +0000211the TF-A with the Arm `FVP`_\ s.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100212
Dan Handley610e7e12018-03-01 18:44:00 +0000213See the `Firmware Design`_ for information on how the TF-A works.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100214
215See the `Porting Guide`_ as well for information about how to use this
Dan Handleycc573cb2018-03-14 13:01:39 +0000216software on another Armv7-A or Armv8-A platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100217
218See the `Contributing Guidelines`_ for information on how to contribute to this
219project and the `Acknowledgments`_ file for a list of contributors to the
220project.
221
222Feedback and support
223~~~~~~~~~~~~~~~~~~~~
224
Dan Handley610e7e12018-03-01 18:44:00 +0000225Arm welcomes any feedback on TF-A. If you think you have found a security
226vulnerability, please report this using the process defined in the TF-A
227`Security Centre`_. For all other feedback, please use the
Dan Handleyed09d382017-07-05 17:40:29 +0100228`GitHub issue tracker`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100229
Dan Handley610e7e12018-03-01 18:44:00 +0000230Arm licensees may contact Arm directly via their partner managers.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100231
232--------------
233
Dan Handley610e7e12018-03-01 18:44:00 +0000234*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100235
Dan Handleycc573cb2018-03-14 13:01:39 +0000236.. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100237.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php
Dan Handleyed09d382017-07-05 17:40:29 +0100238.. _Power State Coordination Interface (PSCI): PSCI_
239.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
240.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
241.. _System Control and Management Interface: SCMI_
242.. _SCMI: http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf
danh-arm190e4fa2018-03-20 17:01:39 +0000243.. _Software Delegated Exception Interface (SDEI): SDEI_
Dan Handleycc573cb2018-03-14 13:01:39 +0000244.. _SDEI: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
Dan Handley610e7e12018-03-01 18:44:00 +0000245.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
246.. _Arm FVP website: FVP_
Dan Handleyed09d382017-07-05 17:40:29 +0100247.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
Dan Handleycc573cb2018-03-14 13:01:39 +0000248.. _Linaro Release 17.10: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.10
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100249.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os
250.. _NVidia Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary
Dan Handleyed09d382017-07-05 17:40:29 +0100251.. _Trusty Secure OS: https://source.android.com/security/trusty
252.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware
253.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
254.. _Security Centre: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Security-Centre
255.. _license: ./license.rst
256.. _Contributing Guidelines: ./contributing.rst
257.. _Acknowledgments: ./acknowledgements.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100258.. _Firmware Design: ./docs/firmware-design.rst
259.. _Change Log: ./docs/change-log.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100260.. _User Guide: ./docs/user-guide.rst
261.. _Porting Guide: ./docs/porting-guide.rst