blob: ae9ca80313a72123f8d1ec9bddf70ff490c822a4 [file] [log] [blame]
Joanna Farleyadd34512018-09-28 08:38:17 +01001Trusted Firmware-A - version 2.0
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`_
Paul Beesley2bb814c2019-01-10 15:42:39 +000012- `System Control and Management Interface (SCMI)`_
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
Antonio Nino Diazcf0f8052018-08-17 10:45:47 +010033- The libc source code is derived from `FreeBSD`_ and `SCC`_. FreeBSD uses
34 various BSD licenses, including BSD-3-Clause and BSD-2-Clause. The SCC code
35 is used under the BSD-3-Clause license with the author's permission.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010036
Dan Handley5274dc22018-07-25 16:42:10 +010037- The libfdt source code is disjunctively dual licensed
38 (GPL-2.0+ OR BSD-2-Clause). It is used by this project under the terms of
39 the BSD-2-Clause license. Any contributions to this code must be made under
40 the terms of both licenses.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010041
Dan Handley5274dc22018-07-25 16:42:10 +010042- The LLVM compiler-rt source code is disjunctively dual licensed
43 (NCSA OR MIT). It is used by this project under the terms of the NCSA
44 license (also known as the University of Illinois/NCSA Open Source License),
45 which is a permissive license compatible with BSD-3-Clause. Any
46 contributions to this code must be made under the terms of both licenses.
Dan Handleyed09d382017-07-05 17:40:29 +010047
Dan Handleycc573cb2018-03-14 13:01:39 +000048- The zlib source code is licensed under the Zlib license, which is a
49 permissive license compatible with BSD-3-Clause.
50
Dan Handley5274dc22018-07-25 16:42:10 +010051- Some STMicroelectronics platform source code is disjunctively dual licensed
52 (GPL-2.0+ OR BSD-3-Clause). It is used by this project under the terms of the
53 BSD-3-Clause license. Any contributions to this code must be made under the
54 terms of both licenses.
55
Dan Handleycc573cb2018-03-14 13:01:39 +000056This release
Douglas Raillardd7c21b72017-06-28 15:23:03 +010057------------
58
59This release provides a suitable starting point for productization of secure
Dan Handleyed09d382017-07-05 17:40:29 +010060world boot and runtime firmware, in either the AArch32 or AArch64 execution
Paul Beesley640e5d32019-01-10 16:14:04 +000061states.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010062
63Users are encouraged to do their own security validation, including penetration
Dan Handley610e7e12018-03-01 18:44:00 +000064testing, on any secure world code derived from TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010065
66Functionality
67~~~~~~~~~~~~~
68
Dan Handleyed09d382017-07-05 17:40:29 +010069- Initialization of the secure world, for example exception vectors, control
70 registers and interrupts for the platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010071
72- Library support for CPU specific reset and power down sequences. This
Dan Handley610e7e12018-03-01 18:44:00 +000073 includes support for errata workarounds and the latest Arm DynamIQ CPUs.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010074
Dan Handley610e7e12018-03-01 18:44:00 +000075- Drivers to enable standard initialization of Arm System IP, for example
Dan Handleyed09d382017-07-05 17:40:29 +010076 Generic Interrupt Controller (GIC), Cache Coherent Interconnect (CCI),
77 Cache Coherent Network (CCN), Network Interconnect (NIC) and TrustZone
78 Controller (TZC).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010079
Dan Handleyed09d382017-07-05 17:40:29 +010080- A generic `SCMI`_ driver to interface with conforming power controllers, for
Dan Handley610e7e12018-03-01 18:44:00 +000081 example the Arm System Control Processor (SCP).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010082
Dan Handleyed09d382017-07-05 17:40:29 +010083- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling
84 Convention`_ using an EL3 runtime services framework.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010085
Dan Handleyed09d382017-07-05 17:40:29 +010086- `PSCI`_ library support for CPU, cluster and system power management
87 use-cases.
88 This library is pre-integrated with the AArch64 EL3 Runtime Software, and
89 is also suitable for integration with other AArch32 EL3 Runtime Software,
90 for example an AArch32 Secure OS.
91
92- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library
93 integration with AArch32 EL3 Runtime Software.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010094
95- Secure Monitor library code such as world switching, EL1 context management
96 and interrupt routing.
Dan Handleyed09d382017-07-05 17:40:29 +010097 When a Secure-EL1 Payload (SP) is present, for example a Secure OS, the
Paul Beesley640e5d32019-01-10 16:14:04 +000098 AArch64 EL3 Runtime Software must be integrated with a Secure Payload
99 Dispatcher (SPD) component to customize the interaction with the SP.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100100
Paul Beesley640e5d32019-01-10 16:14:04 +0000101- A Test SP and SPD to demonstrate AArch64 Secure Monitor functionality and SP
Dan Handleyed09d382017-07-05 17:40:29 +0100102 interaction with PSCI.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100103
Paul Beesleyfb80fe02019-01-10 15:53:12 +0000104- SPDs for the `OP-TEE Secure OS`_, `NVIDIA Trusted Little Kernel`_
Dan Handleyed09d382017-07-05 17:40:29 +0100105 and `Trusty Secure OS`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100106
107- A Trusted Board Boot implementation, conforming to all mandatory TBBR
Dan Handleyed09d382017-07-05 17:40:29 +0100108 requirements. This includes image authentication, Firmware Update (or
109 recovery mode), and packaging of the various firmware images into a
110 Firmware Image Package (FIP).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100111
Dan Handleycc573cb2018-03-14 13:01:39 +0000112- Pre-integration of TBB with the Arm CryptoCell product, to take advantage of
113 its hardware Root of Trust and crypto acceleration services.
114
115- Reliability, Availability, and Serviceability (RAS) functionality, including
116
117 - A Secure Partition Manager (SPM) to manage Secure Partitions in
118 Secure-EL0, which can be used to implement simple management and
119 security services.
120
121 - An SDEI dispatcher to route interrupt-based SDEI events.
122
123 - An Exception Handling Framework (EHF) that allows dispatching of EL3
124 interrupts to their registered handlers, to facilitate firmware-first
125 error handling.
126
127- A dynamic configuration framework that enables each of the firmware images
128 to be configured at runtime if required by the platform. It also enables
129 loading of a hardware configuration (for example, a kernel device tree)
130 as part of the FIP, to be passed through the firmware stages.
Dan Handleyed09d382017-07-05 17:40:29 +0100131
132- Support for alternative boot flows, for example to support platforms where
133 the EL3 Runtime Software is loaded using other firmware or a separate
Dan Handleycc573cb2018-03-14 13:01:39 +0000134 secure system processor, or where a non-TF-A ROM expects BL2 to be loaded
135 at EL3.
Dan Handleyed09d382017-07-05 17:40:29 +0100136
Dan Handley610e7e12018-03-01 18:44:00 +0000137- Support for the GCC, LLVM and Arm Compiler 6 toolchains.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100138
Paul Beesley640e5d32019-01-10 16:14:04 +0000139- Support for combining several libraries into a self-called "romlib" image
140 that may be shared across images to reduce memory footprint. The romlib image
Joanna Farley325ef902018-09-11 15:51:31 +0100141 is stored in ROM but is accessed through a jump-table that may be stored
142 in read-write memory, allowing for the library code to be patched.
143
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100144For a full description of functionality and implementation details, please
145see the `Firmware Design`_ and supporting documentation. The `Change Log`_
146provides details of changes made since the last release.
147
148Platforms
149~~~~~~~~~
150
Paul Beesley640e5d32019-01-10 16:14:04 +0000151Various AArch32 and AArch64 builds of this release have been tested on r0, r1
152and r2 variants of the `Juno Arm Development Platform`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100153
Dan Handley610e7e12018-03-01 18:44:00 +0000154Various AArch64 builds of this release have been tested on the following Arm
Joanna Farley325ef902018-09-11 15:51:31 +0100155Fixed Virtual Platforms (`FVP`_) without shifted affinities that do not
Dan Handleycc573cb2018-03-14 13:01:39 +0000156support threaded CPU cores (64-bit host machine only):
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100157
Joanna Farley325ef902018-09-11 15:51:31 +0100158NOTE: Unless otherwise stated, the model version is Version 11.4 Build 37.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100159
Joanna Farley325ef902018-09-11 15:51:31 +0100160- ``FVP_Base_Aresx4``
161- ``FVP_Base_AEMv8A-AEMv8A``
162- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
163- ``FVP_Base_AEMv8A-AEMv8A``
164- ``FVP_Base_RevC-2xAEMv8A``
165- ``FVP_Base_Cortex-A32x4``
Dan Handleyed09d382017-07-05 17:40:29 +0100166- ``FVP_Base_Cortex-A35x4``
167- ``FVP_Base_Cortex-A53x4``
Joanna Farley325ef902018-09-11 15:51:31 +0100168- ``FVP_Base_Cortex-A55x4+Cortex-A75x4``
169- ``FVP_Base_Cortex-A55x4``
Dan Handleyed09d382017-07-05 17:40:29 +0100170- ``FVP_Base_Cortex-A57x4-A53x4``
171- ``FVP_Base_Cortex-A57x4``
172- ``FVP_Base_Cortex-A72x4-A53x4``
173- ``FVP_Base_Cortex-A72x4``
174- ``FVP_Base_Cortex-A73x4-A53x4``
175- ``FVP_Base_Cortex-A73x4``
Joanna Farley325ef902018-09-11 15:51:31 +0100176- ``FVP_Base_Cortex-A75x4``
177- ``FVP_Base_Cortex-A76x4``
178- ``FVP_CSS_SGI-575`` (Version 11.3 build 40)
179- ``Foundation_Platform``
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100180
Joanna Farley325ef902018-09-11 15:51:31 +0100181The latest version of the AArch32 build of TF-A has been tested on the following
182Arm FVPs without shifted affinities that do not support threaded CPU cores
183(64-bit host machine only).
Dan Handleyed09d382017-07-05 17:40:29 +0100184
Dan Handleycc573cb2018-03-14 13:01:39 +0000185- ``FVP_Base_AEMv8A-AEMv8A``
Dan Handleyed09d382017-07-05 17:40:29 +0100186- ``FVP_Base_Cortex-A32x4``
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100187
188The Foundation FVP can be downloaded free of charge. The Base FVPs can be
Dan Handley610e7e12018-03-01 18:44:00 +0000189licensed from Arm. See the `Arm FVP website`_.
Dan Handleyed09d382017-07-05 17:40:29 +0100190
Joanna Farley325ef902018-09-11 15:51:31 +0100191All the above platforms have been tested with `Linaro Release 18.04`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100192
193This release also contains the following platform support:
194
Joanna Farley325ef902018-09-11 15:51:31 +0100195- Allwinner sun50i_64 and sun50i_h6
Antonio Nino Diazfe75b052018-10-10 23:52:39 +0100196- Amlogic Meson S905 (GXBB)
Chandni Cherukuri533b5542019-02-22 16:44:49 +0530197- Arm SGI-575, RDN1Edge, RDE1Edge and SGM-775
John Tsichritzis56369c12019-02-19 13:49:06 +0000198- Arm Neoverse N1 System Development Platform
Dan Handleycc573cb2018-03-14 13:01:39 +0000199- HiKey, HiKey960 and Poplar boards
Antonio Nino Diaz31291532019-01-17 12:16:07 +0000200- Marvell Armada 3700 and 8K
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100201- MediaTek MT6795 and MT8173 SoCs
Antonio Nino Diaz31291532019-01-17 12:16:07 +0000202- NVIDIA T132, T186 and T210 SoCs
203- NXP QorIQ LS1043A, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7
204- QEMU
205- Raspberry Pi 3
206- R-Car Generation 3
Dan Handleyed09d382017-07-05 17:40:29 +0100207- RockChip RK3328, RK3368 and RK3399 SoCs
Sumit Garg760c1d32018-06-21 11:28:18 +0530208- Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs
Joanna Farley325ef902018-09-11 15:51:31 +0100209- STMicroelectronics STM32MP1
Nishanth Menon0192f892016-10-14 01:13:34 +0000210- Texas Instruments K3 SoCs
Antonio Nino Diaz31291532019-01-17 12:16:07 +0000211- Xilinx Versal and Zynq UltraScale + MPSoC
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100212
Dan Handleycc573cb2018-03-14 13:01:39 +0000213Still to come
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100214~~~~~~~~~~~~~
215
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100216- More platform support.
217
Joanna Farley325ef902018-09-11 15:51:31 +0100218- Position independent executable (PIE) support.
Dan Handleycc573cb2018-03-14 13:01:39 +0000219
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100220- Ongoing support for new architectural features, CPUs and System IP.
221
Dan Handleycc573cb2018-03-14 13:01:39 +0000222- Ongoing support for new Arm system architecture specifications.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100223
224- Ongoing security hardening, optimization and quality improvements.
225
Dan Handleyed09d382017-07-05 17:40:29 +0100226For a full list of detailed issues in the current code, please see the `Change
227Log`_ and the `GitHub issue tracker`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100228
Dan Handleycc573cb2018-03-14 13:01:39 +0000229Getting started
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100230---------------
231
Dan Handley610e7e12018-03-01 18:44:00 +0000232Get the TF-A source code from `GitHub`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100233
Paul Beesley640e5d32019-01-10 16:14:04 +0000234See the `User Guide`_ for instructions on how to install, build and use TF-A
235with the Arm `FVP`_\ s.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100236
Paul Beesley640e5d32019-01-10 16:14:04 +0000237See the `Firmware Design`_ for information on how TF-A works.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100238
239See the `Porting Guide`_ as well for information about how to use this
Dan Handleycc573cb2018-03-14 13:01:39 +0000240software on another Armv7-A or Armv8-A platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100241
242See the `Contributing Guidelines`_ for information on how to contribute to this
243project and the `Acknowledgments`_ file for a list of contributors to the
244project.
245
Dimitris Papastamosfc62ebd2018-07-30 15:38:04 +0100246IRC channel
247~~~~~~~~~~~
248
249Development discussion takes place on the #trusted-firmware-a channel
250on the Freenode IRC network. This is not an official support channel.
251If you have an issue to raise, please use the `GitHub issue tracker`_.
252
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100253Feedback and support
254~~~~~~~~~~~~~~~~~~~~
255
Dan Handley610e7e12018-03-01 18:44:00 +0000256Arm welcomes any feedback on TF-A. If you think you have found a security
257vulnerability, please report this using the process defined in the TF-A
258`Security Centre`_. For all other feedback, please use the
Dan Handleyed09d382017-07-05 17:40:29 +0100259`GitHub issue tracker`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100260
Dan Handley610e7e12018-03-01 18:44:00 +0000261Arm licensees may contact Arm directly via their partner managers.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100262
263--------------
264
Antonio Nino Diaz31291532019-01-17 12:16:07 +0000265*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100266
Dan Handleycc573cb2018-03-14 13:01:39 +0000267.. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100268.. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php
Dan Handleyed09d382017-07-05 17:40:29 +0100269.. _Power State Coordination Interface (PSCI): PSCI_
270.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
271.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
Paul Beesley2bb814c2019-01-10 15:42:39 +0000272.. _System Control and Management Interface (SCMI): SCMI_
Dan Handleyed09d382017-07-05 17:40:29 +0100273.. _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 +0000274.. _Software Delegated Exception Interface (SDEI): SDEI_
Dan Handleycc573cb2018-03-14 13:01:39 +0000275.. _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 +0000276.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
277.. _Arm FVP website: FVP_
Dan Handleyed09d382017-07-05 17:40:29 +0100278.. _FVP: https://developer.arm.com/products/system-design/fixed-virtual-platforms
Joanna Farley325ef902018-09-11 15:51:31 +0100279.. _Linaro Release 18.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease18.04
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100280.. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os
Paul Beesleyfb80fe02019-01-10 15:53:12 +0000281.. _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 +0100282.. _Trusty Secure OS: https://source.android.com/security/trusty
283.. _GitHub: https://www.github.com/ARM-software/arm-trusted-firmware
284.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues
285.. _Security Centre: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Security-Centre
286.. _license: ./license.rst
287.. _Contributing Guidelines: ./contributing.rst
288.. _Acknowledgments: ./acknowledgements.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100289.. _Firmware Design: ./docs/firmware-design.rst
290.. _Change Log: ./docs/change-log.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100291.. _User Guide: ./docs/user-guide.rst
292.. _Porting Guide: ./docs/porting-guide.rst
Antonio Nino Diazcf0f8052018-08-17 10:45:47 +0100293.. _FreeBSD: http://www.freebsd.org
294.. _SCC: http://www.simple-cc.org/