doc: Move documents into subdirectories

This change creates the following directories under docs/
in order to provide a grouping for the content:

- components
- design
- getting_started
- perf
- process

In each of these directories an index.rst file is created
and this serves as an index / landing page for each of the
groups when the pages are compiled. Proper layout of the
top-level table of contents relies on this directory/index
structure.

Without this patch it is possible to build the documents
correctly with Sphinx but the output looks messy because
there is no overall hierarchy.

Change-Id: I3c9f4443ec98571a56a6edf775f2c8d74d7f429f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

54 files changed, 1035 insertions, 301 deletions

diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst
new file mode 100644
index 000000000..095b5adbb
--- /dev/null
+++ b/docs/acknowledgements.rst
@@ -0,0 +1,28 @@
+**Note: This file is only relevant for legacy contributions, to acknowledge the
+specific contributors referred to in "Arm Limited and Contributors" copyright
+notices. As contributors are now encouraged to put their name or company name
+directly into the copyright notices, this file is not relevant for new
+contributions.**
+
+Contributor Acknowledgements
+============================
+
+Companies
+---------
+
+Linaro Limited
+
+NVIDIA Corporation
+
+Socionext Inc.
+
+Xilinx, Inc.
+
+NXP Semiconductors
+
+Marvell International Ltd.
+
+STMicroelectronics
+
+Individuals
+-----------
diff --git a/docs/change-log.rst b/docs/change-log.rst
index 1aca22b05..6893582a3 100644
--- a/docs/change-log.rst
+++ b/docs/change-log.rst
@@ -2417,15 +2417,15 @@ releases of TF-A.
 *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
-.. _PSCI Integration Guide: psci-lib-integration-guide.rst
+.. _PSCI Integration Guide: ./getting_started/psci-lib-integration-guide.rst
 .. _Developer Certificate of Origin: ../dco.txt
-.. _Contribution Guide: ../contributing.rst
-.. _Authentication framework: auth-framework.rst
-.. _Firmware Update: firmware-update.rst
-.. _TF-A Reset Design: reset-design.rst
-.. _Power Domain Topology Design: psci-pd-tree.rst
+.. _Contribution Guide: ./contributing.rst
+.. _Authentication framework: ./design/auth-framework.rst
+.. _Firmware Update: ./design/firmware-update.rst
+.. _TF-A Reset Design: ./design/reset-design.rst
+.. _Power Domain Topology Design: ./design/psci-pd-tree.rst
 .. _TF-A wiki on GitHub: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
-.. _Authentication Framework: auth-framework.rst
-.. _OP-TEE Dispatcher: optee-dispatcher.rst
+.. _Authentication Framework: ./design/auth-framework.rst
+.. _OP-TEE Dispatcher: ./spd/optee-dispatcher.rst
 .. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501
 .. _PR#1002: https://github.com/ARM-software/arm-trusted-firmware/pull/1002#issuecomment-312650193
diff --git a/docs/arm-sip-service.rst b/docs/components/arm-sip-service.rst
index 6cdac8357..6cdac8357 100644
--- a/docs/arm-sip-service.rst
+++ b/docs/components/arm-sip-service.rst
diff --git a/docs/exception-handling.rst b/docs/components/exception-handling.rst
index b7cd69d4c..e3684f133 100644
--- a/docs/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -2,8 +2,7 @@ Exception Handling Framework in Trusted Firmware-A
 ==================================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
     :depth: 2
@@ -117,7 +116,7 @@ for more than one priority level.
 
 .. _ehf-figure:
 
-.. image:: draw.io/ehf.svg
+.. image:: ../draw.io/ehf.svg
 
 A priority level is *active* when a handler at that priority level is currently
 executing in EL3, or has delegated the execution to a lower EL. For interrupts,
diff --git a/docs/firmware-update.rst b/docs/components/firmware-update.rst
index 1f07f7681..f3ad6af1f 100644
--- a/docs/firmware-update.rst
+++ b/docs/components/firmware-update.rst
@@ -2,8 +2,7 @@ Trusted Firmware-A - Firmware Update design guide
 =================================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -403,7 +402,7 @@ This is only allowed if the image is not being executed.
 *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _Trusted Board Boot: ./trusted-board-boot.rst
-.. _Porting Guide: ./porting-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
 .. _Authentication Framework Design: ./auth-framework.rst
 .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
diff --git a/docs/components/index.rst b/docs/components/index.rst
new file mode 100644
index 000000000..f1904c004
--- /dev/null
+++ b/docs/components/index.rst
@@ -0,0 +1,18 @@
+Components
+==========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   spd/index
+   arm-sip-service
+   exception-handling
+   firmware-update
+   platform-interrupt-controller-API
+   ras
+   romlib-design
+   sdei
+   secure-partition-manager-design
+   xlat-tables-lib-v2-design
diff --git a/docs/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst
index ad68709a3..42d92be2a 100644
--- a/docs/platform-interrupt-controller-API.rst
+++ b/docs/components/platform-interrupt-controller-API.rst
@@ -1,8 +1,7 @@
 Platform Interrupt Controller API documentation
 ===============================================
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -10,7 +9,7 @@ This document lists the optional platform interrupt controller API that
 abstracts the runtime configuration and control of interrupt controller from the
 generic code. The mandatory APIs are described in the `porting guide`__.
 
-.. __: porting-guide.rst#interrupt-management-framework-in-bl31
+.. __: ../getting_started/porting-guide.rst#interrupt-management-framework-in-bl31
 
 Function: unsigned int plat_ic_get_running_priority(void); [optional]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/ras.rst b/docs/components/ras.rst
index ac4d019f1..f329fb0b2 100644
--- a/docs/ras.rst
+++ b/docs/components/ras.rst
@@ -1,8 +1,7 @@
 RAS support in Trusted Firmware-A
 =================================
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
     :depth: 2
@@ -45,7 +44,7 @@ be set ``1``.
 
 .. _ras-figure:
 
-.. image:: draw.io/ras.svg
+.. image:: ../draw.io/ras.svg
 
 See more on `Engaging the RAS framework`_.
 
@@ -56,7 +55,7 @@ The RAS framework allows the platform to define handlers for External Abort,
 Uncontainable Errors, Double Fault, and errors rising from EL3 execution. Please
 refer to the porting guide for the `RAS platform API descriptions`__.
 
-.. __: porting-guide.rst#external-abort-handling-and-ras-support
+.. __: ../getting_started/porting-guide.rst#external-abort-handling-and-ras-support
 
 Registering RAS error records
 -----------------------------
diff --git a/docs/romlib-design.rst b/docs/components/romlib-design.rst
index 41957214d..41957214d 100644
--- a/docs/romlib-design.rst
+++ b/docs/components/romlib-design.rst
diff --git a/docs/sdei.rst b/docs/components/sdei.rst
index c52481706..aca1ccb06 100644
--- a/docs/sdei.rst
+++ b/docs/components/sdei.rst
@@ -1,9 +1,5 @@
-Software Delegated Exception Interface
-======================================
-
-
-.. section-numbering::
-    :suffix: .
+SDEI: Software Delegated Exception Interface
+============================================
 
 .. contents::
     :depth: 2
@@ -33,7 +29,7 @@ The following figure depicts a general sequence involving SDEI client executing
 at EL2 and an event dispatch resulting from the triggering of a bound interrupt.
 A commentary is provided below:
 
-.. image:: plantuml/sdei_general.svg
+.. image:: ../plantuml/sdei_general.svg
 
 As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and
 the SDEI dispatcher returns a platform dynamic event number [2]. The client then
@@ -241,7 +237,7 @@ on success, or ``-1`` on failure.
 The following figure depicts a scenario involving explicit dispatch of SDEI
 event. A commentary is provided below:
 
-.. image:: plantuml/sdei_explicit_dispatch.svg
+.. image:: ../plantuml/sdei_explicit_dispatch.svg
 
 As part of initialisation, the SDEI client registers a handler for a platform
 event [1], enables the event [3], and unmasks the current PE [5]. Note that,
@@ -376,4 +372,4 @@ implemented in assembly, following a similar pattern as below:
 *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
-.. _SDEI porting requirements: porting-guide.rst#sdei-porting-requirements
+.. _SDEI porting requirements: ../getting_started/porting-guide.rst#sdei-porting-requirements
diff --git a/docs/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst
index 3c301d0bf..2c32eba12 100644
--- a/docs/secure-partition-manager-design.rst
+++ b/docs/components/secure-partition-manager-design.rst
@@ -2,8 +2,7 @@
 Secure Partition Manager Design
 *******************************
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -820,5 +819,5 @@ Error Codes
 .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
 .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 
-.. |Image 1| image:: diagrams/secure_sw_stack_tos.png
-.. |Image 2| image:: diagrams/secure_sw_stack_sp.png
+.. |Image 1| image:: ../diagrams/secure_sw_stack_tos.png
+.. |Image 2| image:: ../diagrams/secure_sw_stack_sp.png
diff --git a/docs/components/spd/index.rst b/docs/components/spd/index.rst
new file mode 100644
index 000000000..e03bfe33d
--- /dev/null
+++ b/docs/components/spd/index.rst
@@ -0,0 +1,11 @@
+Secure Payload Dispatcher (SPD)
+===============================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   optee-dispatcher
+   tlk-dispatcher
+   trusty-dispatcher
diff --git a/docs/spd/optee-dispatcher.rst b/docs/components/spd/optee-dispatcher.rst
index 63baccc56..63baccc56 100644
--- a/docs/spd/optee-dispatcher.rst
+++ b/docs/components/spd/optee-dispatcher.rst
diff --git a/docs/spd/tlk-dispatcher.rst b/docs/components/spd/tlk-dispatcher.rst
index 90af5faf6..90af5faf6 100644
--- a/docs/spd/tlk-dispatcher.rst
+++ b/docs/components/spd/tlk-dispatcher.rst
diff --git a/docs/spd/trusty-dispatcher.rst b/docs/components/spd/trusty-dispatcher.rst
index be085705d..be085705d 100644
--- a/docs/spd/trusty-dispatcher.rst
+++ b/docs/components/spd/trusty-dispatcher.rst
diff --git a/docs/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst
index dbed7f8e2..d55f010a3 100644
--- a/docs/xlat-tables-lib-v2-design.rst
+++ b/docs/components/xlat-tables-lib-v2-design.rst
@@ -2,8 +2,7 @@ Translation Tables Library Design
 =================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -416,13 +415,13 @@ mapping cannot be cached in the TLBs.
 
 *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
 
-.. _lib/xlat_tables_v2: ../lib/xlat_tables_v2
-.. _lib/xlat_tables: ../lib/xlat_tables
-.. _xlat_tables_v2.h: ../include/lib/xlat_tables/xlat_tables_v2.h
-.. _xlat_tables_context.c: ../lib/xlat_tables_v2/xlat_tables_context.c
-.. _xlat_tables_core.c: ../lib/xlat_tables_v2/xlat_tables_core.c
-.. _xlat_tables_utils.c: ../lib/xlat_tables_v2/xlat_tables_utils.c
-.. _aarch32/xlat_tables_arch.c: ../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
-.. _aarch64/xlat_tables_arch.c: ../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
-.. _Porting Guide: porting-guide.rst
-.. |Alignment Example| image:: ./diagrams/xlat_align.png?raw=true
+.. _lib/xlat_tables_v2: ../../lib/xlat_tables_v2
+.. _lib/xlat_tables: ../../lib/xlat_tables
+.. _xlat_tables_v2.h: ../../include/lib/xlat_tables/xlat_tables_v2.h
+.. _xlat_tables_context.c: ../../lib/xlat_tables_v2/xlat_tables_context.c
+.. _xlat_tables_core.c: ../../lib/xlat_tables_v2/xlat_tables_core.c
+.. _xlat_tables_utils.c: ../../lib/xlat_tables_v2/xlat_tables_utils.c
+.. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
+.. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
+.. _Porting Guide: ../getting_started/porting-guide.rst
+.. |Alignment Example| image:: ../diagrams/xlat_align.png?raw=true
diff --git a/docs/contents.rst b/docs/contents.rst
deleted file mode 100644
index 4b3f74fde..000000000
--- a/docs/contents.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-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/docs/auth-framework.rst b/docs/design/auth-framework.rst
index 0142fbd3e..1bc501547 100644
--- a/docs/auth-framework.rst
+++ b/docs/design/auth-framework.rst
@@ -2,8 +2,7 @@ Abstracting a Chain of Trust
 ============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -968,5 +967,5 @@ of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
 *Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _Trusted Board Boot: ./trusted-board-boot.rst
-.. _Platform Porting Guide: ./porting-guide.rst
+.. _Platform Porting Guide: ../getting_started/porting-guide.rst
 .. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
diff --git a/docs/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst
index 493e07e9e..d099ebe26 100644
--- a/docs/cpu-specific-build-macros.rst
+++ b/docs/design/cpu-specific-build-macros.rst
@@ -2,8 +2,7 @@ Arm CPU Specific Build Macros
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
diff --git a/docs/firmware-design.rst b/docs/design/firmware-design.rst
index 8384c9c00..e7107ba1a 100644
--- a/docs/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -2,8 +2,7 @@ Trusted Firmware-A design
 =========================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -2665,19 +2664,19 @@ References
 *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _Reset Design: ./reset-design.rst
-.. _Porting Guide: ./porting-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _Firmware Update: ./firmware-update.rst
 .. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
-.. _PSCI Library integration guide: ./psci-lib-integration-guide.rst
+.. _PSCI Library integration guide: ../getting_started/psci-lib-integration-guide.rst
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
-.. _here: ./psci-lib-integration-guide.rst
+.. _here: ../getting_started/psci-lib-integration-guide.rst
 .. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
 .. _CPUBM: ./cpu-specific-build-macros.rst
 .. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
-.. _User Guide: ./user-guide.rst
+.. _User Guide: ../getting_started/user-guide.rst
 .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 .. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst
 .. _Xlat_tables design: xlat-tables-lib-v2-design.rst
diff --git a/docs/design/index.rst b/docs/design/index.rst
new file mode 100644
index 000000000..a51a4eb47
--- /dev/null
+++ b/docs/design/index.rst
@@ -0,0 +1,15 @@
+System Design
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   auth-framework
+   cpu-specific-build-macros
+   firmware-design
+   interrupt-framework-design
+   psci-pd-tree
+   reset-design
+   trusted-board-boot
diff --git a/docs/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst
index 58130cde0..e4ec65aa1 100644
--- a/docs/interrupt-framework-design.rst
+++ b/docs/design/interrupt-framework-design.rst
@@ -2,8 +2,7 @@ Trusted Firmware-A interrupt management design guide
 ====================================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -1018,7 +1017,7 @@ TSP by returning ``SMC_UNK`` error.
 
 *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Porting Guide: ./porting-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 
 .. |Image 1| image:: diagrams/sec-int-handling.png?raw=true
diff --git a/docs/psci-pd-tree.rst b/docs/design/psci-pd-tree.rst
index 9653725f9..2e2163af1 100644
--- a/docs/psci-pd-tree.rst
+++ b/docs/design/psci-pd-tree.rst
@@ -2,8 +2,7 @@ PSCI Power Domain Tree design
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
diff --git a/docs/reset-design.rst b/docs/design/reset-design.rst
index 44ab609ef..147385102 100644
--- a/docs/reset-design.rst
+++ b/docs/design/reset-design.rst
@@ -2,8 +2,7 @@ Trusted Firmware-A reset design
 ===============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -158,9 +157,9 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31.
 *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _Firmware Design: firmware-design.rst
-.. _User Guide: user-guide.rst
+.. _User Guide: ../getting_started/user-guide.rst
 
-.. |Default reset code flow| image:: diagrams/default_reset_code.png?raw=true
-.. |Reset code flow with programmable reset address| image:: diagrams/reset_code_no_boot_type_check.png?raw=true
-.. |Reset code flow with single CPU released out of reset| image:: diagrams/reset_code_no_cpu_check.png?raw=true
-.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: diagrams/reset_code_no_checks.png?raw=true
+.. |Default reset code flow| image:: ../diagrams/default_reset_code.png?raw=true
+.. |Reset code flow with programmable reset address| image:: ../diagrams/reset_code_no_boot_type_check.png?raw=true
+.. |Reset code flow with single CPU released out of reset| image:: ../diagrams/reset_code_no_cpu_check.png?raw=true
+.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../diagrams/reset_code_no_checks.png?raw=true
diff --git a/docs/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index 3ba963634..ae21bf05e 100644
--- a/docs/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -2,8 +2,7 @@ Trusted Board Boot Design Guide
 ===============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -234,7 +233,7 @@ for building and using the tool can be found in the `User Guide`_.
 
 .. _Firmware Update: firmware-update.rst
 .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
-.. _User Guide: user-guide.rst
+.. _User Guide: ../getting_started/user-guide.rst
 .. _Auth Framework: auth-framework.rst
 .. _TBBR-client: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
 .. _Trusted Board Boot Requirements (TBBR): `TBBR-client`_
diff --git a/docs/image-terminology.rst b/docs/getting_started/image-terminology.rst
index 4dc1d7346..4dc1d7346 100644
--- a/docs/image-terminology.rst
+++ b/docs/getting_started/image-terminology.rst
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 000000000..23608f860
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,13 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   user-guide
+   image-terminology
+   porting-guide
+   psci-lib-integration-guide
+   rt-svc-writers-guide
diff --git a/docs/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 6244a6387..cad8b5c9a 100644
--- a/docs/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -2,13 +2,9 @@ Trusted Firmware-A Porting Guide
 ================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
---------------
-
 Introduction
 ------------
 
@@ -2366,7 +2362,7 @@ FVP can be configured to use either GICv2 or GICv3 depending on the build flag
 
 See also: `Interrupt Controller Abstraction APIs`__.
 
-.. __: platform-interrupt-controller-API.rst
+.. __: ../design/platform-interrupt-controller-API.rst
 
 Function : plat_interrupt_type_to_line() [mandatory]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2493,7 +2489,7 @@ value obtained from the interrupt controller when acknowledging an interrupt.
 The actual interrupt number shall be extracted from this raw value using the API
 `plat_ic_get_interrupt_id()`__.
 
-.. __: platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
+.. __: ../design/platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
 
 This function in Arm standard platforms using GICv2, reads the *Interrupt
 Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
diff --git a/docs/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst
index 241ab3a06..c8cf3f393 100644
--- a/docs/psci-lib-integration-guide.rst
+++ b/docs/getting_started/psci-lib-integration-guide.rst
@@ -2,8 +2,6 @@ PSCI Library Integration guide for Armv8-A AArch32 systems
 ==========================================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
@@ -550,5 +548,5 @@ workarounds.
 .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
 .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Porting Guide: porting-guide.rst
-.. _Firmware Design: ./firmware-design.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
+.. _Firmware Design: ../design/firmware-design.rst
diff --git a/docs/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
index 4d4066c26..f4d786cd2 100644
--- a/docs/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -2,13 +2,9 @@ Trusted Firmware-A EL3 runtime service writer's guide
 =====================================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
---------------
-
 Introduction
 ------------
 
@@ -307,9 +303,9 @@ provide this information....
 
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Firmware Design: ./firmware-design.rst
-.. _services: ../services
-.. _lib/psci: ../lib/psci
-.. _runtime_svc.h: ../include/common/runtime_svc.h
-.. _smccc.h: ../include/lib/smccc.h
-.. _std_svc_setup.c: ../services/std_svc/std_svc_setup.c
+.. _Firmware Design: ../designb_documents/firmware-design.rst
+.. _services: ../../services
+.. _lib/psci: ../../lib/psci
+.. _runtime_svc.h: ../../include/common/runtime_svc.h
+.. _smccc.h: ../../include/lib/smccc.h
+.. _std_svc_setup.c: ../../services/std_svc/std_svc_setup.c
diff --git a/docs/user-guide.rst b/docs/getting_started/user-guide.rst
index 0079b1ad0..3cc5f3cc9 100644
--- a/docs/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
@@ -2,8 +2,7 @@ Trusted Firmware-A User Guide
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
diff --git a/docs/index.rst b/docs/index.rst
index a6c1ca92c..f4c738617 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,43 +1,21 @@
-Arm Trusted Firmware-A Documentation Index
-==========================================
+Trusted Firmware-A Documentation
+================================
 
 .. toctree::
    :maxdepth: 1
-   :caption: Design Documents
+   :caption: Contents
 
-   arm-sip-service
-   auth-framework
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Release Notes
+   getting_started/index
+   process/index
+   components/index
+   design/index
+   plat/index
+   perf/index
+   security_advisories/index
+   readme
    change-log
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Guides
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Policies
-   cpu-specific-build-macros
-   exception-handling
-   firmware-design
-   firmware-update
-   interrupt-framework-design
-   platform-compatibility-policy
-   platform-interrupt-controller-API
-   porting-guide
-   psci-lib-integration-guide
-   psci-pd-tree
-   ras
-   reset-design
-   rt-svc-writers-guide
-   sdei
-   secure-partition-manager-design
-   trusted-board-boot
-   user-guide
-   xlat-tables-lib-v2-design
+   maintainers
+   acknowledgements
 
 Indices and tables
 ==================
diff --git a/docs/maintainers.rst b/docs/maintainers.rst
new file mode 100644
index 000000000..0fa909fb6
--- /dev/null
+++ b/docs/maintainers.rst
@@ -0,0 +1,294 @@
+Trusted Firmware-A maintainers
+==============================
+
+Trusted Firmware-A (TF-A) is an Arm maintained project. All contributions are
+ultimately merged by the maintainers listed below. Technical ownership of some
+parts of the codebase is delegated to the sub-maintainers listed below. An
+acknowledgement from these sub-maintainers may be required before the
+maintainers merge a contribution.
+
+Main maintainers
+----------------
+:M: Dan Handley <dan.handley@arm.com>
+:G: `danh-arm`_
+:M: Dimitris Papastamos <dimitrs.papastamos@arm.com>
+:G: `dp-arm`_
+:M: Soby Mathew <soby.mathew@arm.com>
+:G: `soby-mathew`_
+
+Allwinner ARMv8 platform port
+-----------------------------
+:M: Andre Przywara <andre.przywara@arm.com>
+:G: `Andre-ARM`_
+:M: Samuel Holland <samuel@sholland.org>
+:G: `smaeul`_
+:F: docs/plat/allwinner.rst
+:F: plat/allwinner/
+:F: drivers/allwinner/
+
+Amlogic Meson S905 (GXBB) platform port
+---------------------------------------
+:M: Andre Przywara <andre.przywara@arm.com>
+:G: `Andre-ARM`_
+:F: docs/plat/meson-gxbb.rst
+:F: drivers/meson/
+:F: plat/meson/gxbb/
+
+Amlogic Meson S905x (GXL) platform port
+---------------------------------------
+:M: Remi Pommarel <repk@triplefau.lt>
+:G: `remi-triplefault`_
+:F: docs/plat/meson-gxl.rst
+:F: drivers/meson/gxl
+:F: plat/meson/gxl/
+
+Armv7-A architecture port
+-------------------------
+:M: Etienne Carriere <etienne.carriere@linaro.org>
+:G: `etienne-lms`_
+
+Arm System Guidance for Infrastructure / Mobile FVP platforms
+-------------------------------------------------------------
+:M: Nariman Poushin <nariman.poushin@linaro.org>
+:G: `npoushin`_
+:M: Thomas Abraham <thomas.abraham@arm.com>
+:G: `thomas-arm`_
+:F: plat/arm/css/sgi/
+:F: plat/arm/css/sgm/
+:F: plat/arm/board/sgi575/
+:F: plat/arm/board/sgm775/
+
+Console API framework
+---------------------
+:M: Julius Werner <jwerner@chromium.org>
+:G: `jwerner-chromium`_
+:F: drivers/console/
+:F: include/drivers/console.h
+:F: plat/common/aarch64/crash_console_helpers.S
+
+coreboot support libraries
+--------------------------
+:M: Julius Werner <jwerner@chromium.org>
+:G: `jwerner-chromium`_
+:F: drivers/coreboot/
+:F: include/drivers/coreboot/
+:F: include/lib/coreboot.h
+:F: lib/coreboot/
+
+eMMC/UFS drivers
+----------------
+:M: Haojian Zhuang <haojian.zhuang@linaro.org>
+:G: `hzhuang1`_
+:F: drivers/partition/
+:F: drivers/synopsys/emmc/
+:F: drivers/synopsys/ufs/
+:F: drivers/ufs/
+:F: include/drivers/dw_ufs.h
+:F: include/drivers/ufs.h
+:F: include/drivers/synopsys/dw_mmc.h
+
+HiSilicon HiKey and HiKey960 platform ports
+-------------------------------------------
+:M: Haojian Zhuang <haojian.zhuang@linaro.org>
+:G: `hzhuang1`_
+:F: docs/plat/hikey.rst
+:F: docs/plat/hikey960.rst
+:F: plat/hisilicon/hikey/
+:F: plat/hisilicon/hikey960/
+
+HiSilicon Poplar platform port
+------------------------------
+:M: Shawn Guo <shawn.guo@linaro.org>
+:G: `shawnguo2`_
+:F: docs/plat/poplar.rst
+:F: plat/hisilicon/poplar/
+
+Intel SocFPGA platform ports
+----------------------------
+:M: Tien Hock Loh <tien.hock.loh@intel.com>
+:G: `thloh85-intel`
+:F: plat/intel/soc
+
+MediaTek platform ports
+-----------------------
+:M: Yidi Lin (林以廸) <yidi.lin@mediatek.com>
+:G: `mtk09422`_
+:F: plat/mediatek/
+
+Marvell platform ports and SoC drivers
+--------------------------------------
+:M: Konstantin Porotchkin <kostap@marvell.com>
+:G: `kostapr`_
+:F: docs/marvell/
+:F: plat/marvell/
+:F: drivers/marvell/
+:F: tools/marvell/
+
+NVidia platform ports
+---------------------
+:M: Varun Wadekar <vwadekar@nvidia.com>
+:G: `vwadekar`_
+:F: docs/plat/nvidia-tegra.rst
+:F: include/lib/cpus/aarch64/denver.h
+:F: lib/cpus/aarch64/denver.S
+:F: plat/nvidia/
+
+NXP QorIQ Layerscape platform ports
+-----------------------------------
+:M: Jiafei Pan <jiafei.pan@nxp.com>
+:G: `qoriq-open-source`_
+:F: docs/plat/ls1043a.rst
+:F: plat/layerscape/
+
+NXP i.MX 7 WaRP7 platform port and SoC drivers
+----------------------------------------------
+:M: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+:G: `bryanodonoghue`_
+:M: Jun Nie <jun.nie@linaro.org>
+:G: `niej`_
+:F: docs/plat/warp7.rst
+:F: plat/imx/common/
+:F: plat/imx/imx7/
+:F: drivers/imx/timer/
+:F: drivers/imx/uart/
+:F: drivers/imx/usdhc/
+
+NXP i.MX 8 platform port
+------------------------
+:M: Anson Huang <Anson.Huang@nxp.com>
+:G: `Anson-Huang`_
+:F: docs/plat/imx8.rst
+:F: plat/imx/
+
+NXP i.MX8M platform port
+------------------------
+:M: Jacky Bai <ping.bai@nxp.com>
+:G: `JackyBai`_
+:F: doc/plat/imx8m.rst
+:F: plat/imx/imx8m/
+
+OP-TEE dispatcher
+-----------------
+:M: Jens Wiklander <jens.wiklander@linaro.org>
+:G: `jenswi-linaro`_
+:F: docs/spd/optee-dispatcher.rst
+:F: services/spd/opteed/
+
+QEMU platform port
+------------------
+:M: Jens Wiklander <jens.wiklander@linaro.org>
+:G: `jenswi-linaro`_
+:F: docs/plat/qemu.rst
+:F: plat/qemu/
+
+Raspberry Pi 3 platform port
+----------------------------
+:M: Ying-Chun Liu (PaulLiu) <paul.liu@linaro.org>
+:G: `grandpaul`_
+:F: docs/plat/rpi3.rst
+:F: plat/rpi3/
+:F: drivers/rpi3/
+:F: include/drivers/rpi3/
+
+Renesas rcar-gen3 platform port
+-------------------------------
+:M: Jorge Ramirez-Ortiz  <jramirez@baylibre.com>
+:G: `ldts`_
+:M: Marek Vasut <marek.vasut@gmail.com>
+:G: `marex`_
+:F: docs/plat/rcar-gen3.rst
+:F: plat/renesas/rcar
+:F: drivers/renesas/rcar
+:F: tools/renesas/rcar_layout_create
+
+RockChip platform port
+----------------------
+:M: Tony Xie <tony.xie@rock-chips.com>
+:G: `TonyXie06`_
+:G: `rockchip-linux`_
+:M: Heiko Stuebner <heiko@sntech.de>
+:G: `mmind`_
+:F: plat/rockchip/
+
+STM32MP1 platform port
+----------------------
+:M: Yann Gautier <yann.gautier@st.com>
+:G: `Yann-lms`_
+:F: docs/plat/stm32mp1.rst
+:F: drivers/st/
+:F: fdts/stm32\*
+:F: include/drivers/st/
+:F: include/dt-bindings/\*/stm32\*
+:F: plat/st/
+:F: tools/stm32image/
+
+Synquacer platform port
+-----------------------
+:M: Sumit Garg <sumit.garg@linaro.org>
+:G: `b49020`_
+:F: docs/plat/synquacer.rst
+:F: plat/socionext/synquacer/
+
+Texas Instruments platform port
+-------------------------------
+:M: Andrew F. Davis <afd@ti.com>
+:G: `glneo`_
+:F: docs/plat/ti-k3.rst
+:F: plat/ti/
+
+TLK/Trusty secure payloads
+--------------------------
+:M: Varun Wadekar <vwadekar@nvidia.com>
+:G: `vwadekar`_
+:F: docs/spd/tlk-dispatcher.rst
+:F: docs/spd/trusty-dispatcher.rst
+:F: include/bl32/payloads/tlk.h
+:F: services/spd/tlkd/
+:F: services/spd/trusty/
+
+UniPhier platform port
+----------------------
+:M: Masahiro Yamada <yamada.masahiro@socionext.com>
+:G: `masahir0y`_
+:F: docs/plat/socionext-uniphier.rst
+:F: plat/socionext/uniphier/
+
+Xilinx platform port
+--------------------
+:M: Siva Durga Prasad Paladugu <siva.durga.paladugu@xilinx.com>
+:G: `sivadur`_
+:F: docs/plat/xilinx-zynqmp.rst
+:F: plat/xilinx/
+
+.. _Andre-ARM: https://github.com/Andre-ARM
+.. _Anson-Huang: https://github.com/Anson-Huang
+.. _bryanodonoghue: https://github.com/bryanodonoghue
+.. _b49020: https://github.com/b49020
+.. _danh-arm: https://github.com/danh-arm
+.. _dp-arm: https://github.com/dp-arm
+.. _etienne-lms: https://github.com/etienne-lms
+.. _glneo: https://github.com/glneo
+.. _hzhuang1: https://github.com/hzhuang1
+.. _JackyBai: https://github.com/JackyBai
+.. _jenswi-linaro: https://github.com/jenswi-linaro
+.. _ldts: https://github.com/ldts
+.. _marex: https://github.com/marex
+.. _niej: https://github.com/niej
+.. _kostapr: https://github.com/kostapr
+.. _masahir0y: https://github.com/masahir0y
+.. _mmind: https://github.com/mmind
+.. _mtk09422: https://github.com/mtk09422
+.. _npoushin: https://github.com/npoushin
+.. _qoriq-open-source: https://github.com/qoriq-open-source
+.. _remi-triplefault: https://github.com/repk
+.. _rockchip-linux: https://github.com/rockchip-linux
+.. _shawnguo2: https://github.com/shawnguo2
+.. _sivadur: https://github.com/sivadur
+.. _smaeul: https://github.com/smaeul
+.. _soby-mathew: https://github.com/soby-mathew
+.. _thomas-arm: https://github.com/thomas-arm
+.. _TonyXie06: https://github.com/TonyXie06
+.. _vwadekar: https://github.com/vwadekar
+.. _Yann-lms: https://github.com/Yann-lms
+.. _grandpaul: https://github.com/grandpaul
+.. _jwerner-chromium: https://github.com/jwerner-chromium
diff --git a/docs/perf/index.rst b/docs/perf/index.rst
new file mode 100644
index 000000000..50833b8c8
--- /dev/null
+++ b/docs/perf/index.rst
@@ -0,0 +1,9 @@
+Performance & Testing
+=====================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   psci-performance-juno
diff --git a/docs/psci-performance-juno.rst b/docs/perf/psci-performance-juno.rst
index caed8bf9a..caed8bf9a 100644
--- a/docs/psci-performance-juno.rst
+++ b/docs/perf/psci-performance-juno.rst
diff --git a/docs/plat/index.rst b/docs/plat/index.rst
new file mode 100644
index 000000000..3a917f363
--- /dev/null
+++ b/docs/plat/index.rst
@@ -0,0 +1,29 @@
+Platform Ports
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   allwinner
+   fvp_ve
+   imx8
+   imx8m
+   intel-stratix10
+   ls1043a
+   meson-gxbb
+   meson-gxl
+   mt8183
+   nvidia-tegra
+   poplar
+   qemu
+   rcar-gen3
+   rockchip
+   rpi3
+   socionext-uniphier
+   stm32mp1
+   synquacer
+   ti-k3
+   warp7
+   xilinx-zynqmp
diff --git a/docs/marvell/build.txt b/docs/plat/marvell/build.txt
index 7b75196fa..7b75196fa 100644
--- a/docs/marvell/build.txt
+++ b/docs/plat/marvell/build.txt
diff --git a/docs/marvell/misc/mvebu-a8k-addr-map.txt b/docs/plat/marvell/misc/mvebu-a8k-addr-map.txt
index 586e8b732..586e8b732 100644
--- a/docs/marvell/misc/mvebu-a8k-addr-map.txt
+++ b/docs/plat/marvell/misc/mvebu-a8k-addr-map.txt
diff --git a/docs/marvell/misc/mvebu-amb.txt b/docs/plat/marvell/misc/mvebu-amb.txt
index 2a7a41ec9..2a7a41ec9 100644
--- a/docs/marvell/misc/mvebu-amb.txt
+++ b/docs/plat/marvell/misc/mvebu-amb.txt
diff --git a/docs/marvell/misc/mvebu-ccu.txt b/docs/plat/marvell/misc/mvebu-ccu.txt
index 976402761..976402761 100644
--- a/docs/marvell/misc/mvebu-ccu.txt
+++ b/docs/plat/marvell/misc/mvebu-ccu.txt
diff --git a/docs/marvell/misc/mvebu-io-win.txt b/docs/plat/marvell/misc/mvebu-io-win.txt
index c83ad1fd2..c83ad1fd2 100644
--- a/docs/marvell/misc/mvebu-io-win.txt
+++ b/docs/plat/marvell/misc/mvebu-io-win.txt
diff --git a/docs/marvell/misc/mvebu-iob.txt b/docs/plat/marvell/misc/mvebu-iob.txt
index 97ec09d0e..97ec09d0e 100644
--- a/docs/marvell/misc/mvebu-iob.txt
+++ b/docs/plat/marvell/misc/mvebu-iob.txt
diff --git a/docs/marvell/porting.txt b/docs/plat/marvell/porting.txt
index f9a39a054..f9a39a054 100644
--- a/docs/marvell/porting.txt
+++ b/docs/plat/marvell/porting.txt
diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst
index a22bfc6a9..122b1de61 100644
--- a/docs/plat/rpi3.rst
+++ b/docs/plat/rpi3.rst
@@ -1,8 +1,7 @@
 Trusted Firmware-A for Raspberry Pi 3
 =====================================
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
diff --git a/docs/coding-guidelines.rst b/docs/process/coding-guidelines.rst
index e8f365b36..644f82885 100644
--- a/docs/coding-guidelines.rst
+++ b/docs/process/coding-guidelines.rst
@@ -1,8 +1,7 @@
 Trusted Firmware-A Coding Guidelines
 ====================================
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst
new file mode 100644
index 000000000..bd950e511
--- /dev/null
+++ b/docs/process/contributing.rst
@@ -0,0 +1,149 @@
+Contributing to Trusted Firmware-A
+==================================
+
+Getting Started
+---------------
+
+-  Make sure you have a Github account and you are logged on
+   `developer.trustedfirmware.org`_.
+-  Create an `issue`_ for your work if one does not already exist. This gives
+   everyone visibility of whether others are working on something similar.
+
+   -  If you intend to include Third Party IP in your contribution, please
+      raise a separate `issue`_ for this and ensure that the changes that
+      include Third Party IP are made on a separate topic branch.
+
+-  Clone `arm-trusted-firmware-a`_ on your own machine as suggested on the
+   `User Guide`_.
+-  Create a local topic branch based on the `arm-trusted-firmware-a`_ ``master``
+   branch.
+
+Making Changes
+--------------
+
+-  Make commits of logical units. See these general `Git guidelines`_ for
+   contributing to a project.
+-  Follow the `Coding Guidelines`_.
+
+   -  Use the checkpatch.pl script provided with the Linux source tree. A
+      Makefile target is provided for convenience (see the "Checking source code
+      style" section in the `User Guide`_).
+
+-  Keep the commits on topic. If you need to fix another bug or make another
+   enhancement, please create a separate `issue`_ and address it on a separate
+   topic branch.
+-  Avoid long commit series. If you do have a long series, consider whether
+   some commits should be squashed together or addressed in a separate topic.
+-  Make sure your commit messages are in the proper format. If a commit fixes
+   an `issue`_, include a reference.
+-  Where appropriate, please update the documentation.
+
+   -  Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_
+      or other in-source documentation needs updating.
+   -  Ensure that each changed file has the correct copyright and license
+      information. Files that entirely consist of contributions to this
+      project should have a copyright notice and BSD-3-Clause SPDX license
+      identifier of the form as shown in `license.rst`_. Files that contain
+      changes to imported Third Party IP files should retain their original
+      copyright and license notices. For significant contributions you may
+      add your own copyright notice in following format:
+
+      ::
+
+          Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
+
+      where XXXX is the year of first contribution (if different to YYYY) and
+      YYYY is the year of most recent contribution. <OWNER> is your name or
+      your company name.
+   -  If you are submitting new files that you intend to be the technical
+      sub-maintainer for (for example, a new platform port), then also update
+      the `Maintainers`_ file.
+   -  For topics with multiple commits, you should make all documentation
+      changes (and nothing else) in the last commit of the series. Otherwise,
+      include the documentation changes within the single commit.
+
+-  Please test your changes. As a minimum, ensure that Linux boots on the
+   Foundation FVP. See `Running the software on FVP`_ for more information. For
+   more extensive testing, consider running the `TF-A Tests`_ against your
+   patches.
+
+Submitting Changes
+------------------
+
+-  Ensure that each commit in the series has at least one ``Signed-off-by:``
+   line, using your real name and email address. The names in the
+   ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else
+   contributes to the commit, they must also add their own ``Signed-off-by:``
+   line. By adding this line the contributor certifies the contribution is made
+   under the terms of the `Developer Certificate of Origin (DCO)`_.
+
+   More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
+
+-  Ensure that each commit also has a unique ``Change-Id:`` line. If you have
+   cloned the repository with the "`Clone with commit-msg hook`" clone method
+   (as advised on the `User Guide`_), this should already be the case.
+
+   More details may be found in the `Gerrit Change-Ids documentation`_.
+
+-  Submit your changes for review at https://review.trustedfirmware.org
+   targeting the ``integration`` branch.
+
+   -  The changes will then undergo further review and testing by the
+      `Maintainers`_. Any review comments will be made directly on your patch.
+      This may require you to do some rework.
+
+   Refer to the `Gerrit Uploading Changes documentation`_ for more details.
+
+-  When the changes are accepted, the `Maintainers`_ will integrate them.
+
+   -  Typically, the `Maintainers`_ will merge the changes into the
+      ``integration`` branch.
+   -  If the changes are not based on a sufficiently-recent commit, or if they
+      cannot be automatically rebased, then the `Maintainers`_ may rebase it on
+      the ``master`` branch or ask you to do so.
+   -  After final integration testing, the changes will make their way into the
+      ``master`` branch. If a problem is found during integration, the merge
+      commit will be removed from the ``integration`` branch and the
+      `Maintainers`_ will ask you to create a new patch set to resolve the
+      problem.
+
+Binary Components
+-----------------
+
+-  Platforms may depend on binary components submitted to the `Trusted Firmware
+   binary repository`_ if they require code that the contributor is unable or
+   unwilling to open-source. This should be used as a rare exception.
+-  All binary components must follow the contribution guidelines (in particular
+   licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of
+   the binary repository.
+-  Binary components must be restricted to only the specific functionality that
+   cannot be open-sourced and must be linked into a larger open-source platform
+   port. The majority of the platform port must still be implemented in open
+   source. Platform ports that are merely a thin wrapper around a binary
+   component that contains all the actual code will not be accepted.
+-  Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on
+   binary components. Generic code must always be fully open-source.
+
+--------------
+
+*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
+
+.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
+.. _issue: https://developer.trustedfirmware.org/project/board/1/
+.. _arm-trusted-firmware-a: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+.. _Git guidelines: http://git-scm.com/book/ch5-2.html
+.. _Coding Guidelines: ./docs/coding-guidelines.rst
+.. _User Guide: ./docs/user-guide.rst
+.. _Porting Guide: ./docs/porting-guide.rst
+.. _Firmware Design: ./docs/firmware-design.rst
+.. _license.rst: ./license.rst
+.. _Acknowledgements: ./acknowledgements.rst
+.. _Maintainers: ./maintainers.rst
+.. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp
+.. _Developer Certificate of Origin (DCO): ./dco.txt
+.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
+.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
+.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
+.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/
+.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries
+.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst
diff --git a/docs/frequently-asked-questions.rst b/docs/process/faq.rst
index 6aa04f0a8..6aa04f0a8 100644
--- a/docs/frequently-asked-questions.rst
+++ b/docs/process/faq.rst
diff --git a/docs/process/index.rst b/docs/process/index.rst
new file mode 100644
index 000000000..91f1beb2a
--- /dev/null
+++ b/docs/process/index.rst
@@ -0,0 +1,14 @@
+Processes & Policies
+====================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   release-information
+   security-center
+   platform-compatibility-policy
+   coding-guidelines
+   contributing
+   faq
diff --git a/docs/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst
index 6bab447ee..e977e63a8 100644
--- a/docs/platform-compatibility-policy.rst
+++ b/docs/process/platform-compatibility-policy.rst
@@ -2,8 +2,7 @@ TF-A Platform Compatibility Policy
 ==================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -40,6 +39,6 @@ migrate before the removal of the deprecated interface.
 
 *Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.*
 
-.. _Porting Guide: ./porting-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _Release information: https://github.com/ARM-software/arm-trusted-firmware/wiki/TF-A-Release-information#removal-of-deprecated-interfaces
 .. _tf-issue: https://github.com/ARM-software/tf-issues/issues
diff --git a/docs/release-information.rst b/docs/process/release-information.rst
index 553115036..553115036 100644
--- a/docs/release-information.rst
+++ b/docs/process/release-information.rst
diff --git a/docs/security-center.rst b/docs/process/security-center.rst
index 672c56322..672c56322 100644
--- a/docs/security-center.rst
+++ b/docs/process/security-center.rst
diff --git a/docs/security-reporting.asc b/docs/process/security-reporting.asc
index 8c41f7bf6..8c41f7bf6 100644
--- a/docs/security-reporting.asc
+++ b/docs/process/security-reporting.asc
diff --git a/docs/readme.rst b/docs/readme.rst
new file mode 100644
index 000000000..fc0355585
--- /dev/null
+++ b/docs/readme.rst
@@ -0,0 +1,356 @@
+Trusted Firmware-A - version 2.1
+================================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+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,
+such as:
+
+-  The `Power State Coordination Interface (PSCI)`_
+-  `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT)`_
+-  `SMC Calling Convention`_
+-  `System Control and Management Interface (SCMI)`_
+-  `Software Delegated Exception Interface (SDEI)`_
+
+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
+technology.
+
+Documentation contents
+----------------------
+
+The `Trusted Firmware-A Documentation Contents`_ page contains an overview of
+the documentation that is available, with links to facilitate easier browsing.
+
+License
+-------
+
+The software is provided under a BSD-3-Clause `license`_. Contributions to this
+project are accepted under the same license with developer sign-off as
+described in the `Contributing Guidelines`_.
+
+This project contains code from other projects as listed below. The original
+license text is included in those source files.
+
+-  The libc source code is derived from `FreeBSD`_ and `SCC`_. FreeBSD uses
+   various BSD licenses, including BSD-3-Clause and BSD-2-Clause. The SCC code
+   is used under the BSD-3-Clause license with the author's permission.
+
+-  The libfdt source code is disjunctively dual licensed
+   (GPL-2.0+ OR BSD-2-Clause). It is used by this project under the terms of
+   the BSD-2-Clause license. Any contributions to this code must be made under
+   the terms of both licenses.
+
+-  The LLVM compiler-rt source code is disjunctively dual licensed
+   (NCSA OR MIT). It is used by this project under the terms of the NCSA
+   license (also known as the University of Illinois/NCSA Open Source License),
+   which is a permissive license compatible with BSD-3-Clause. Any
+   contributions to this code must be made under the terms of both licenses.
+
+-  The zlib source code is licensed under the Zlib license, which is a
+   permissive license compatible with BSD-3-Clause.
+
+-  Some STMicroelectronics platform source code is disjunctively dual licensed
+   (GPL-2.0+ OR BSD-3-Clause). It is used by this project under the terms of the
+   BSD-3-Clause license. Any contributions to this code must be made under the
+   terms of both licenses.
+
+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.
+
+   -  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 ``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`_.
+
+The latest version of the AArch64 build of TF-A has been tested on the following
+Arm FVPs without shifted affinities, and that do not support threaded CPU cores
+(64-bit host machine only).
+
+The FVP models used are Version 11.5 Build 33, unless otherwise stated.
+
+-  ``FVP_Base_AEMv8A-AEMv8A``
+-  ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
+-  ``FVP_Base_RevC-2xAEMv8A``
+-  ``FVP_Base_Cortex-A32x4``
+-  ``FVP_Base_Cortex-A35x4``
+-  ``FVP_Base_Cortex-A53x4``
+-  ``FVP_Base_Cortex-A55x4+Cortex-A75x4``
+-  ``FVP_Base_Cortex-A55x4``
+-  ``FVP_Base_Cortex-A57x1-A53x1``
+-  ``FVP_Base_Cortex-A57x2-A53x4``
+-  ``FVP_Base_Cortex-A57x4-A53x4``
+-  ``FVP_Base_Cortex-A57x4``
+-  ``FVP_Base_Cortex-A72x4-A53x4``
+-  ``FVP_Base_Cortex-A72x4``
+-  ``FVP_Base_Cortex-A73x4-A53x4``
+-  ``FVP_Base_Cortex-A73x4``
+-  ``FVP_Base_Cortex-A75x4``
+-  ``FVP_Base_Cortex-A76x4``
+-  ``FVP_Base_Cortex-A76AEx4`` (Tested with internal model)
+-  ``FVP_Base_Cortex-A76AEx8`` (Tested with internal model)
+-  ``FVP_Base_Neoverse-N1x4`` (Tested with internal model)
+-  ``FVP_Base_Deimos``
+-  ``FVP_CSS_SGI-575`` (Version 11.3 build 42)
+-  ``FVP_CSS_SGM-775`` (Version 11.3 build 42)
+-  ``FVP_RD_E1Edge`` (Version 11.3 build 42)
+-  ``FVP_RD_N1Edge`` (Version 11.3 build 42)
+-  ``Foundation_Platform``
+
+The latest version of the AArch32 build of TF-A has been tested on the following
+Arm FVPs without shifted affinities, and that do not support threaded CPU cores
+(64-bit host machine only).
+
+-  ``FVP_Base_AEMv8A-AEMv8A``
+-  ``FVP_Base_Cortex-A32x4``
+
+NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities.
+
+The Foundation FVP can be downloaded free of charge. The Base FVPs can be
+licensed from Arm. See the `Arm FVP website`_.
+
+All the above platforms have been tested with `Linaro Release 18.04`_.
+
+This release also contains the following platform support:
+
+-  Allwinner sun50i_a64 and sun50i_h6
+-  Amlogic Meson S905 (GXBB)
+-  Amlogic Meson S905x (GXL)
+-  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.MX8MM, i.MX8MQ, i.MX8QX, i.MX8QM and i.MX7Solo WaRP7
+-  QEMU
+-  Raspberry Pi 3
+-  Renesas R-Car Generation 3
+-  RockChip RK3328, RK3368 and RK3399 SoCs
+-  Socionext UniPhier SoC family and SynQuacer SC2A11 SoCs
+-  STMicroelectronics STM32MP1
+-  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 `Change
+Log`_ and the `issue tracker`_.
+
+Getting started
+---------------
+
+See the `User Guide`_ for instructions on how to download, install, build and
+use TF-A with the Arm `FVP`_\ s.
+
+See the `Firmware Design`_ for information on how TF-A works.
+
+See the `Porting Guide`_ as well for information about how to use this
+software on another Armv7-A or Armv8-A platform.
+
+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.
+
+IRC channel
+~~~~~~~~~~~
+
+Development discussion takes place on the #trusted-firmware-a channel
+on the Freenode IRC network. This is not an official support channel.
+If you have an issue to raise, please use the `issue tracker`_.
+
+Feedback and support
+~~~~~~~~~~~~~~~~~~~~
+
+Arm welcomes 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
+`Security Center`_. For all other feedback, please use the
+`issue tracker`_.
+
+Arm licensees may contact Arm directly via their partner managers.
+
+Security advisories
+-------------------
+
+-  `Security Advisory TFV-1`_
+-  `Security Advisory TFV-2`_
+-  `Security Advisory TFV-3`_
+-  `Security Advisory TFV-4`_
+-  `Security Advisory TFV-5`_
+-  `Security Advisory TFV-6`_
+-  `Security Advisory TFV-7`_
+-  `Security Advisory TFV-8`_
+
+
+--------------
+
+*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
+.. _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
+.. _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
+.. _Linaro Release 18.04: https://community.arm.com/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease18.04
+.. _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://developer.trustedfirmware.org/project/board/1/
+.. _Security Center: ./docs/security-center.rst
+.. _license: ./license.rst
+.. _Contributing Guidelines: ./contributing.rst
+.. _Acknowledgments: ./acknowledgements.rst
+.. _Firmware Design: ./docs/firmware-design.rst
+.. _Change Log: ./docs/change-log.rst
+.. _User Guide: ./docs/user-guide.rst
+.. _Porting Guide: ./docs/porting-guide.rst
+.. _FreeBSD: http://www.freebsd.org
+.. _SCC: http://www.simple-cc.org/
+.. _Security Advisory TFV-1: ./docs/security_advisories/security-advisory-tfv-1.rst
+.. _Security Advisory TFV-2: ./docs/security_advisories/security-advisory-tfv-2.rst
+.. _Security Advisory TFV-3: ./docs/security_advisories/security-advisory-tfv-3.rst
+.. _Security Advisory TFV-4: ./docs/security_advisories/security-advisory-tfv-4.rst
+.. _Security Advisory TFV-5: ./docs/security_advisories/security-advisory-tfv-5.rst
+.. _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
diff --git a/docs/security_advisories/index.rst b/docs/security_advisories/index.rst
new file mode 100644
index 000000000..ce2c843e5
--- /dev/null
+++ b/docs/security_advisories/index.rst
@@ -0,0 +1,16 @@
+Security Advisories
+===================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   security-advisory-tfv-1.rst
+   security-advisory-tfv-2.rst
+   security-advisory-tfv-3.rst
+   security-advisory-tfv-4.rst
+   security-advisory-tfv-5.rst
+   security-advisory-tfv-6.rst
+   security-advisory-tfv-7.rst
+   security-advisory-tfv-8.rst