doc: Move "About" content from index.rst to a new chapter
The index.rst page is now the primary landing page for the TF-A
documentation. It contains quite a lot of content these days,
including:
- The project purpose and general intro
- A list of functionality
- A list of planned functionality
- A list of supported platforms
- "Getting started" links to other documents
- Contact information for raising issues
This patch creates an "About" chapter in the table
of contents and moves some content there. In order,
the above listed content:
- Stayed where it is. This is the right place for it.
- Moved to About->Features
- Moved to About->Features (in subsection)
- Stayed where it is. Moved in a later patch.
- Was expanded in-place
- Moved to About->Contact
Change-Id: I254bb87560fd09140b9e485cf15246892aa45943
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
diff --git a/docs/acknowledgements.rst b/docs/about/acknowledgements.rst
similarity index 87%
rename from docs/acknowledgements.rst
rename to docs/about/acknowledgements.rst
index 74b77ff..a9f6451 100644
--- a/docs/acknowledgements.rst
+++ b/docs/about/acknowledgements.rst
@@ -15,3 +15,7 @@
- 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 0000000..af6668d
--- /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 0000000..9df2894
--- /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 0000000..3a10266
--- /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 4cd1798..8981072 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,7 @@
:hidden:
Home<self>
+ about/index
getting_started/index
process/index
components/index
@@ -14,14 +15,9 @@
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 @@
with reference implementations of Arm standards to benefit 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.
+Getting Started
+---------------
- - An Exception Handling Framework (EHF) that allows dispatching of EL3
- interrupts to their registered handlers, to facilitate firmware-first
- error handling.
+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.
-- 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.
+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.
-- 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.
+Refer to the documents in the **Getting Started** chapter for information about
+the prerequisites and requirements for building |TF-A|.
-- Support for the GCC, LLVM and Arm Compiler 6 toolchains.
+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).
-- 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.
+The **Components** chapter holds documents that explain specific components
+that make up the |TF-A| software, the :ref:`Exception Handling Framework`, for
+example.
-- A prototype implementation of a Secure Partition Manager (SPM) that is based
- on the SPCI Alpha 1 and SPRT draft specifications.
+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.
-- 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.
+**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.
-- Position-Independent Executable (PIE) support. Initially for BL31 only, with
- further support to be added in a future release.
+The results of any performance evaluations are added to the
+**Performance & Testing** chapter.
-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 @@
- 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 a870c8f..9c12de8 100644
--- a/docs/process/index.rst
+++ b/docs/process/index.rst
@@ -6,7 +6,6 @@
:caption: Contents
:numbered:
- release-information
security
platform-compatibility-policy
coding-guidelines