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>

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

docs/exception-handling.rst → 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,

docs/firmware-update.rst → 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

docs/components/index.rst

+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

docs/platform-interrupt-controller-API.rst → docs/components/platform-interrupt-controller-API.rst

 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]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/ras.rst → docs/components/ras.rst

 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
 -----------------------------

docs/sdei.rst → docs/components/sdei.rst

-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

docs/secure-partition-manager-design.rst → 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

docs/components/spd/index.rst

+Secure Payload Dispatcher (SPD)
+===============================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   optee-dispatcher
+   tlk-dispatcher
+   trusty-dispatcher

docs/xlat-tables-lib-v2-design.rst → 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

docs/contents.rst

-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

docs/auth-framework.rst → 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

docs/cpu-specific-build-macros.rst → docs/design/cpu-specific-build-macros.rst

@@ -2,8 +2,7 @@ Arm CPU Specific Build Macros
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 

docs/firmware-design.rst → 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