Commit 40d553cf authored by Paul Beesley's avatar Paul Beesley
Browse files

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: default avatarPaul Beesley <paul.beesley@arm.com>
parent 12b67439
......@@ -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
......@@ -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,
......
......@@ -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
......
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
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]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
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
-----------------------------
......
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
......@@ -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
Secure Payload Dispatcher (SPD)
===============================
.. toctree::
:maxdepth: 1
:caption: Contents
:numbered:
optee-dispatcher
tlk-dispatcher
trusty-dispatcher
......@@ -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
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
......@@ -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
......@@ -2,8 +2,7 @@ Arm CPU Specific Build Macros
=============================
.. section-numbering::
:suffix: .
.. contents::
......
......@@ -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
......
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
......@@ -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
......
......@@ -2,8 +2,7 @@ PSCI Power Domain Tree design
=============================
.. section-numbering::
:suffix: .
.. contents::
......
......@@ -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
......@@ -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`_
Getting Started
===============
.. toctree::
:maxdepth: 1
:caption: Contents
:numbered:
user-guide
image-terminology
porting-guide
psci-lib-integration-guide
rt-svc-writers-guide
......@@ -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
......
......@@ -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