Merge pull request #1906 from pbeesley-arm/pb/readme

doc: Prepare readme for 2.1 release

2 files changed, 216 insertions, 25 deletions

diff --git a/docs/contents.rst b/docs/contents.rst
new file mode 100644
index 00000000..4b3f74fd
--- /dev/null
+++ b/docs/contents.rst
@@ -0,0 +1,165 @@
+Trusted Firmware-A Documentation Contents
+=========================================
+
+This document serves as a list of the documentation that is included with the
+Trusted Firmware-A source.
+
+Introduction
+------------
+
+`About Trusted Firmware-A`_
+
+Getting Started
+---------------
+
+`Frequently-Asked Questions (FAQ)`_
+
+`Image Terminology`_
+
+`Porting Guide`_
+
+`User Guide`_
+
+Contributing
+------------
+
+`Coding Style and Guidelines`_
+
+`Contributor Acknowledgements`_
+
+`Contributor's Guide`_
+
+`License`_
+
+`Maintainers`_
+
+Processes and Policies
+----------------------
+
+`Platform Compatibility Policy`_
+
+`Release Processes`_
+
+Secure Payload Dispatch
+-----------------------
+
+`OP-TEE Dispatcher`_
+
+`Trusted Little Kernel (TLK) Dispatcher`_
+
+`Trusty Dispatcher`_
+
+System Design and Components
+----------------------------
+
+`Arm CPU Specific Build Macros`_
+
+`Arm SiP Services`_
+
+`Authentication Framework & Chain of Trust`_
+
+`CPU Reset`_
+
+`EL3 Runtime Service Writer’s Guide`_
+
+`Exception Handling Framework`_
+
+`Firmware Design Overview`_
+
+`Firmware Update (FWU)`_
+
+`Interrupt Management Framework`_
+
+`Library at ROM`_
+
+`Platform Interrupt Controller API`_
+
+`PSCI Library Integration Guide for Armv8-A AArch32 systems`_
+
+`PSCI Power Domain Tree design`_
+
+`Reliability, Availability, and Serviceability (RAS) Extensions`_
+
+`Secure Partition Manager`_
+
+`Software Delegated Exception Interface`_
+
+`Translation (XLAT) Tables Library`_
+
+`Trusted Board Boot Design Guide`_
+
+Performance and Testing
+-----------------------
+
+`PSCI Performance Measurements on Arm Juno Development Platform`_
+
+Security and Advisories
+-----------------------
+
+`Security Processes`_
+
+`TFV-1`_
+
+`TFV-2`_
+
+`TFV-3`_
+
+`TFV-4`_
+
+`TFV-5`_
+
+`TFV-6`_
+
+`TFV-7`_
+
+`TFV-8`_
+
+Other Documents
+---------------
+
+`Change Log`_
+
+.. _About Trusted Firmware-A: ../readme.rst
+.. _Frequently-Asked Questions (FAQ): ./frequently-asked-questions.rst
+.. _Image Terminology: ./image-terminology.rst
+.. _Porting Guide: ./porting-guide.rst
+.. _User Guide: ./user-guide.rst
+.. _Coding Style and Guidelines: ./coding-guidelines.rst
+.. _Contributor Acknowledgements: ../acknowledgements.rst
+.. _`Contributor's Guide`: ../contributing.rst
+.. _License: ../license.rst
+.. _Maintainers: ../maintainers.rst
+.. _Platform Compatibility Policy: ./platform-compatibility-policy.rst
+.. _Release Processes: ./release-information.rst
+.. _Arm SiP Services: ./arm-sip-service.rst
+.. _Exception Handling Framework: ./exception-handling.rst
+.. _Firmware Update (FWU): ./firmware-update.rst
+.. _Interrupt Management Framework: ./interrupt-framework-design.rst
+.. _Library at ROM: ./romlib-design.rst
+.. _Platform Interrupt Controller API: ./platform-interrupt-controller-API.rst
+.. _`Reliability, Availability, and Serviceability (RAS) Extensions`: ./ras.rst
+.. _Secure Partition Manager: ./secure-partition-manager-design.rst
+.. _Software Delegated Exception Interface: ./sdei.rst
+.. _Translation (XLAT) Tables Library: ./xlat-tables-lib-v2-design.rst
+.. _OP-TEE Dispatcher: ./spd/optee-dispatcher.rst
+.. _Trusted Little Kernel (TLK) Dispatcher: ./spd/tlk-dispatcher.rst
+.. _Trusty Dispatcher: ./spd/trusty-dispatcher.rst
+.. _Arm CPU Specific Build Macros: ./cpu-specific-build-macros.rst
+.. _`Authentication Framework & Chain of Trust`: ./auth-framework.rst
+.. _CPU Reset: ./reset-design.rst
+.. _`EL3 Runtime Service Writer’s Guide`: ./rt-svc-writers-guide.rst
+.. _Firmware Design Overview: ./firmware-design.rst
+.. _PSCI Library Integration Guide for Armv8-A AArch32 systems: ./psci-lib-integration-guide.rst
+.. _PSCI Power Domain Tree design: ./psci-pd-tree.rst
+.. _Trusted Board Boot Design Guide: ./trusted-board-boot.rst
+.. _PSCI Performance Measurements on Arm Juno Development Platform: ./psci-performance-juno.rst
+.. _Security Processes: ./security-center.rst
+.. _Change Log: ./change-log.rst
+.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst
+.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst
+.. _TFV-3: ./security_advisories/security-advisory-tfv-3.rst
+.. _TFV-4: ./security_advisories/security-advisory-tfv-4.rst
+.. _TFV-5: ./security_advisories/security-advisory-tfv-5.rst
+.. _TFV-6: ./security_advisories/security-advisory-tfv-6.rst
+.. _TFV-7: ./security_advisories/security-advisory-tfv-7.rst
+.. _TFV-8: ./security_advisories/security-advisory-tfv-8.rst
diff --git a/readme.rst b/readme.rst
index 1df86371..2ccbbb2d 100644
--- a/readme.rst
+++ b/readme.rst
@@ -1,4 +1,4 @@
-Trusted Firmware-A - version 2.0
+Trusted Firmware-A - version 2.1
 ================================
 
 Trusted Firmware-A (TF-A) provides a reference implementation of secure world
@@ -15,6 +15,13 @@ such as:
 Where possible, the code is designed for reuse or porting to other Armv7-A and
 Armv8-A model and hardware platforms.
 
+This release provides a suitable starting point for productization of secure
+world boot and runtime firmware, in either the AArch32 or AArch64 execution
+states.
+
+Users are encouraged to do their own security validation, including penetration
+testing, on any secure world code derived from TF-A.
+
 Arm will continue development in collaboration with interested parties to
 provide a full reference implementation of Secure Monitor code and Arm standards
 to the benefit of all developers working with Armv7-A and Armv8-A TrustZone
@@ -53,18 +60,8 @@ license text is included in those source files.
    BSD-3-Clause license. Any contributions to this code must be made under the
    terms of both licenses.
 
-This release
-------------
-
-This release provides a suitable starting point for productization of secure
-world boot and runtime firmware, in either the AArch32 or AArch64 execution
-states.
-
-Users are encouraged to do their own security validation, including penetration
-testing, on any secure world code derived from TF-A.
-
 Functionality
-~~~~~~~~~~~~~
+-------------
 
 -  Initialization of the secure world, for example exception vectors, control
    registers and interrupts for the platform.
@@ -136,17 +133,30 @@ Functionality
 
 -  Support for the GCC, LLVM and Arm Compiler 6 toolchains.
 
--  Support for combining several libraries into a self-called "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
+-  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 and SPRT 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 ``ENABLE_PAUTH``
+   build flag to be set.
+
+-  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 the `Firmware Design`_ and supporting documentation. The `Change Log`_
 provides details of changes made since the last release.
 
 Platforms
-~~~~~~~~~
+---------
 
 Various AArch32 and AArch64 builds of this release have been tested on r0, r1
 and r2 variants of the `Juno Arm Development Platform`_.
@@ -192,18 +202,23 @@ All the above platforms have been tested with `Linaro Release 18.04`_.
 
 This release also contains the following platform support:
 
--  Allwinner sun50i_64 and sun50i_h6
+-  Allwinner sun50i_a64 and sun50i_h6
 -  Amlogic Meson S905 (GXBB)
--  Arm SGI-575, RDN1Edge, RDE1Edge and SGM-775
--  Arm Neoverse N1 System Development Platform
+-  Arm Juno Software Development Platform
+-  Arm Neoverse N1 System Development Platform (N1SDP)
+-  Arm Neoverse Reference Design N1 Edge (RD-N1-Edge) FVP
+-  Arm Neoverse Reference Design E1 Edge (RD-E1-Edge) FVP
+-  Arm SGI-575 and SGM-775
+-  Arm Versatile Express FVP
 -  HiKey, HiKey960 and Poplar boards
+-  Intel Stratix 10 SoC FPGA
 -  Marvell Armada 3700 and 8K
 -  MediaTek MT6795 and MT8173 SoCs
 -  NVIDIA T132, T186 and T210 SoCs
--  NXP QorIQ LS1043A, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7
+-  NXP QorIQ LS1043A, i.MX8MM, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7
 -  QEMU
 -  Raspberry Pi 3
--  R-Car Generation 3
+-  Renesas R-Car Generation 3
 -  RockChip RK3328, RK3368 and RK3399 SoCs
 -  Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs
 -  STMicroelectronics STM32MP1
@@ -211,11 +226,15 @@ This release also contains the following platform support:
 -  Xilinx Versal and Zynq UltraScale + MPSoC
 
 Still to come
-~~~~~~~~~~~~~
+-------------
+
+-  Support for additional platforms.
+
+-  Refinements to Position Independent Executable (PIE) support.
 
--  More platform support.
+-  Refinements to SPCI-compliant SPM implementation.
 
--  Position independent executable (PIE) support.
+-  Documentation enhancements.
 
 -  Ongoing support for new architectural features, CPUs and System IP.
 
@@ -243,6 +262,12 @@ See the `Contributing Guidelines`_ for information on how to contribute to this
 project and the `Acknowledgments`_ file for a list of contributors to the
 project.
 
+Documentation contents
+~~~~~~~~~~~~~~~~~~~~~~
+
+The `Trusted Firmware-A Documentation Contents`_ page contains an overview of
+the documentation that is available, with links to facilitate easier browsing.
+
 IRC channel
 ~~~~~~~~~~~
 
@@ -261,7 +286,7 @@ vulnerability, please report this using the process defined in the TF-A
 Arm licensees may contact Arm directly via their partner managers.
 
 Security advisories
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 -  `Security Advisory TFV-1`_
 -  `Security Advisory TFV-2`_
@@ -313,3 +338,4 @@ Security advisories
 .. _Security Advisory TFV-6: ./docs/security_advisories/security-advisory-tfv-6.rst
 .. _Security Advisory TFV-7: ./docs/security_advisories/security-advisory-tfv-7.rst
 .. _Security Advisory TFV-8: ./docs/security_advisories/security-advisory-tfv-8.rst
+.. _Trusted Firmware-A Documentation Contents: ./docs/contents.rst