diff --git a/docs/acknowledgements.rst b/docs/about/acknowledgements.rst similarity index 88% rename from docs/acknowledgements.rst rename to docs/about/acknowledgements.rst index 74b77ff16..a9f64511f 100644 --- a/docs/acknowledgements.rst +++ b/docs/about/acknowledgements.rst @@ -15,3 +15,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..af6668dda --- /dev/null +++ b/docs/about/contact.rst @@ -0,0 +1,17 @@ +Support & Contact +----------------- + +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 +:ref:`Security Handling` document. + +For all other feedback, please use the `issue tracker`_ or our `mailing list`_. + +Arm licensees may contact Arm directly via their partner managers. + +.. _issue tracker: https://issues.trustedfirmware.org +.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a + +-------------- + +*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..9df289468 --- /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 +:ref:`Firmware Design` and supporting documentation. + +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. + +- 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. + +.. _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 similarity index 100% rename from docs/maintainers.rst rename to docs/about/maintainers.rst diff --git a/docs/process/release-information.rst b/docs/about/release-information.rst similarity index 100% rename from docs/process/release-information.rst rename to docs/about/release-information.rst diff --git a/docs/index.rst b/docs/index.rst index 4cd17988c..8981072a5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Trusted Firmware-A Documentation :hidden: Home + about/index getting_started/index process/index components/index @@ -14,14 +15,9 @@ Trusted Firmware-A Documentation perf/index security_advisories/index change-log - acknowledgements 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, @@ -47,101 +43,41 @@ 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. -Functionality -------------- +Getting Started +--------------- -- Initialization of the secure world, for example exception vectors, control - registers and interrupts for the platform. +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. -- Library support for CPU specific reset and power down sequences. This - includes support for errata workarounds and the latest Arm DynamIQ CPUs. +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. -- 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). +Refer to the documents in the **Getting Started** chapter for information about +the prerequisites and requirements for building |TF-A|. -- A generic `SCMI`_ driver to interface with conforming power controllers, for - example the Arm System Control Processor (SCP). +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). -- SMC (Secure Monitor Call) handling, conforming to the `SMC Calling - Convention`_ using an EL3 runtime services framework. +The **Components** chapter holds documents that explain specific components +that make up the |TF-A| software, the :ref:`Exception Handling Framework`, for +example. -- `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. +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. -- A minimal AArch32 Secure Payload (SP\_MIN) to demonstrate `PSCI`_ library - integration with AArch32 EL3 Runtime Software. +**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. -- 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. +The results of any performance evaluations are added to the +**Performance & Testing** chapter. -- 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. - -For a full description of functionality and implementation details, please -see :ref:`Firmware Design` and supporting documentation. The -:ref:`Change Log & Release Notes` provides details of changes made since the -last release. +**Security Advisories** holds a list of documents relating to |CVE| entries that +have previously been raised against the software. Platforms --------- @@ -224,74 +160,17 @@ This release also contains the following platform support: - 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. - -For a full list of detailed issues in the current code, please see the -:ref:`Change Log & Release Notes` and the `issue tracker`_. - -Getting started ---------------- - -See the :ref:`User Guide` for instructions on how to download, install, build -and use TF-A with the Arm `FVP`_\ s. - -See the :ref:`Firmware Design` for information on how TF-A works. - -See the :ref:`Porting Guide` as well for information about how to use this -software on another Armv7-A or Armv8-A platform. - -See the :ref:`Contributor's Guide` for information on how to contribute to this -project and the :ref:`Contributor Acknowledgements` file for a list of -contributors to the project. - -Contact Us -~~~~~~~~~~ - -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 -:ref:`Security Handling` document. - -For all other feedback, please use the `issue tracker`_ or our `mailing list`_. - -Arm licensees may contact Arm directly via their partner managers. - -------------- *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* .. _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 -.. _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 +.. _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 .. _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 +.. _Arm FVP website: https://developer.arm.com/products/system-design/fixed-virtual-platforms .. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06 -.. _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 +.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf 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