Doc: Restructured user-guide/requirements for readability.
This patch modifies the tfm-user-guide and software-requirements
documents, by moving long tables and UML code in the bottom of the
document, and referencing it using `autosectionlabel`. The aim is to
improve readability using command line tools.
Change-Id: Iec42b860291a60f3243ef820fecb056d44ac0199
Signed-off-by: Galanakis, Minos <minos.galanakis@arm.com>
diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/user_guides/tfm_build_instruction.rst
index 6232b3b..934b2a5 100644
--- a/docs/user_guides/tfm_build_instruction.rst
+++ b/docs/user_guides/tfm_build_instruction.rst
@@ -4,71 +4,12 @@
Please make sure you have all required software installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.
-*********************
-Configuring the build
-*********************
-The build configuration for TF-M is provided to the build system using command
-line arguments:
+The external dependecies are briefly listed in the
+:ref:`docs/user_guides/tfm_build_instruction:External dependencies` section.
-.. list-table::
- :widths: 20 80
-
- * - -DPROJ_CONFIG=<file>
- - Specifies the way the application is built.
-
- | <file> is the absolute path to configurations file
- named as ``Config<APP_NAME>.cmake``.
- | i.e. On Linux:
- ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```
-
- * - -DTARGET_PLATFORM=<target platform name>
- - Specifies the target platform.
- Supported platforms:
-
- - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
- ``-DTARGET_PLATFORM=AN521``
- - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
- ``-DTARGET_PLATFORM=AN519``
- - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
- ``-DTARGET_PLATFORM=MUSCA_A``
- - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
- ``-DTARGET_PLATFORM=MUSCA_B1``
- - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
- ``-DTARGET_PLATFORM=AN524``
-
- * - -DCOMPILER=<compiler name>
- - Specifies the compiler toolchain
- The possible values are:
-
- - ``ARMCLANG``
- - ``GNUARM``
- * - -DCMAKE_BUILD_TYPE=<build type>
- - Configures debugging support.
- The possible values are:
-
- - ``Debug``
- - ``Release``
- - ``Relwithdebinfo``
- - ``Minsizerel``
- * - -DMBEDTLS_DEBUG=<ON|OFF>
- - Enables debug symbols for the Mbed TLS and Mbed Crypto libraries.
- * - -DBUILD_DWARF_VERSION=<dwarf version>
- - Configures DWARF version.
- The possible values are:
-
- - 2
- - 3
- - 4
-
-.. Note::
- Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
- without BL2 bootloader.
-
-*******************
-External dependency
-*******************
-- `CMSIS_5` is used to import RTX for the example non-secure app
-- Mbed TLS and Mbed Crypto are used as crypto libraries on the secure side
+The configuration-table
+:ref:`docs/user_guides/tfm_build_instruction:Configuring the build` section
+explains all the supported build parameters:
****************
TF-M build steps
@@ -231,6 +172,72 @@
cmake_doc/install/doc/user_guide
+*********************
+External dependencies
+*********************
+- `CMSIS_5` is used to import RTX for the example non-secure app
+- `Mbed Crypto` is used as crypto library on the secure side
+
+*********************
+Configuring the build
+*********************
+The build configuration for TF-M is provided to the build system using command
+line arguments:
+
+.. list-table::
+ :widths: 20 80
+
+ * - -DPROJ_CONFIG=<file>
+ - Specifies the way the application is built.
+
+ | <file> is the absolute path to configurations file
+ named as ``Config<APP_NAME>.cmake``.
+ | i.e. On Linux:
+ ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```
+
+ * - -DTARGET_PLATFORM=<target platform name>
+ - Specifies the target platform.
+ Supported platforms:
+
+ - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+ ``-DTARGET_PLATFORM=AN521``
+ - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+ ``-DTARGET_PLATFORM=AN519``
+ - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_A``
+ - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_B1``
+ - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
+ ``-DTARGET_PLATFORM=AN524``
+
+ * - -DCOMPILER=<compiler name>
+ - Specifies the compiler toolchain
+ The possible values are:
+
+ - ``ARMCLANG``
+ - ``GNUARM``
+ * - -DCMAKE_BUILD_TYPE=<build type>
+ - Configures debugging support.
+ The possible values are:
+
+ - ``Debug``
+ - ``Release``
+ - ``Relwithdebinfo``
+ - ``Minsizerel``
+ * - -DMBEDTLS_DEBUG=<ON|OFF>
+ - Enables debug symbols for the Mbed TLS and Mbed Crypto libraries.
+ * - -DBUILD_DWARF_VERSION=<dwarf version>
+ - Configures DWARF version.
+ The possible values are:
+
+ - 2
+ - 3
+ - 4
+
+.. Note::
+ Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
+ without BL2 bootloader.
+
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_sw_requirement.rst b/docs/user_guides/tfm_sw_requirement.rst
index aa87962..89dabed 100644
--- a/docs/user_guides/tfm_sw_requirement.rst
+++ b/docs/user_guides/tfm_sw_requirement.rst
@@ -6,101 +6,9 @@
.. |KEIL_VERSION| replace:: v5.25.2
.. |DEV_STUDIO_VERSION| replace:: 2018.0
-To build the TF-M firmware the following tools are needed:
-
-.. csv-table:: Tool dependencies
- :header: "Name", "Version", "Component"
-
- "C compiler",See `Supported C compilers`_,"Firmware"
- "CMake",See `Supported CMake versions`_,
- "GNU Make",See `Supported GNU make versions`_,
- "Python",3.x,"Firmware, User Guide"
- "yaml",,"Firmware"
- "pyasn1",,"Firmware"
- "jinja2",,"Firmware"
- "cryptography",,"Firmware"
- "cbor",,"Firmware"
- "Doxygen",">1.8","Reference manual"
- "Sphinx",">1.4","User Guide"
- "sphinxcontrib-plantuml",,"User Guide"
- "sphinx-trd-theme",,"User Guide"
- "Git",,
- "PlantUML",">v1.2018.11","Reference Manual, User Guide"
- "Graphviz dot",">v2.38.0","Reference manual"
- "Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
- "LaTex",,"pdf version of Reference Manual and User Guide"
- "PdfLaTex",,"pdf version of Reference Manual and User Guide"
-
-Dependency chain:
-
-.. uml::
-
- @startuml
- skinparam state {
- BackgroundColor #92AEE0
- FontColor black
- FontSize 16
- AttributeFontColor black
- AttributeFontSize 16
- BackgroundColor<<pdf>> #A293E2
- BackgroundColor<<doc>> #90DED6
- }
- state fw as "Firmware" : TF-M binary
- state c_comp as "C Compiler" : C99
- state gmake as "GNU make"
- state u_guide as "User Guide" <<doc>>
- state refman as "Reference Manual" <<doc>>
- state rtd_theme as "sphinx-rtd-theme" <<doc>>
- state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
- state JRE as "JRE" <<doc>> : Java Runtime Environment
- state gwiz as "Graphwiz dot" <<doc>>
- state Sphinx as "Sphinx" <<doc>>
- state m2r as "m2r" <<doc>>
- state PlantUML as "PlantUML" <<doc>>
- state LaTex as "LaTex" <<pdf>>
- state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
- state Doxygen as "Doxygen" <<doc>>
-
- [*] --> fw
- fw --> c_comp
- fw --> CMake
- CMake --> gmake
- fw --> cryptography
- fw --> pyasn1
- fw --> yaml
- fw --> jinja2
- fw --> cbor
- cryptography --> Python3
- pyasn1 --> Python3
- yaml --> Python3
- jinja2 --> Python3
- cbor --> Python3
-
- [*] --> u_guide
- u_guide --> Sphinx
- Sphinx --> m2r
- Sphinx --> rtd_theme
- Sphinx --> sphnix_puml
- m2r --> Python3
- rtd_theme --> Python3
- sphnix_puml --> Python3
- Sphinx --> PlantUML
- PlantUML --> JRE
- PlantUML --> gwiz
- Sphinx --> LaTex
- LaTex --> PdfLaTex
-
- [*] --> refman
- refman --> Doxygen
- Doxygen --> PlantUML
- Doxygen --> LaTex
- state Legend {
- state x as "For PDF generation only" <<pdf>>
- state y as "For document generation only" <<doc>>
- state z as "Mandatory"
- }
-
- @enduml
+A quick reference table is included in the
+:ref:`docs/user_guides/tfm_sw_requirement:Tool & Dependency overview` section
+of this document.
****************************
Supported build environments
@@ -514,6 +422,106 @@
export PLANTUML_JAR_PATH=c:/plantuml/plantuml.jar
export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+**************************
+Tool & Dependency overview
+**************************
+
+To build the TF-M firmware the following tools are needed:
+
+.. csv-table:: Tool dependencies
+ :header: "Name", "Version", "Component"
+
+ "C compiler",See `Supported C compilers`_,"Firmware"
+ "CMake",See `Supported CMake versions`_,
+ "GNU Make",See `Supported GNU make versions`_,
+ "Python",3.x,"Firmware, User Guide"
+ "yaml",,"Firmware"
+ "pyasn1",,"Firmware"
+ "jinja2",,"Firmware"
+ "cryptography",,"Firmware"
+ "cbor",,"Firmware"
+ "Doxygen",">1.8","Reference manual"
+ "Sphinx",">1.4","User Guide"
+ "sphinxcontrib-plantuml",,"User Guide"
+ "sphinx-trd-theme",,"User Guide"
+ "Git",,
+ "PlantUML",">v1.2018.11","Reference Manual, User Guide"
+ "Graphviz dot",">v2.38.0","Reference manual"
+ "Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
+ "LaTex",,"pdf version of Reference Manual and User Guide"
+ "PdfLaTex",,"pdf version of Reference Manual and User Guide"
+
+Dependency chain:
+
+.. uml::
+
+ @startuml
+ skinparam state {
+ BackgroundColor #92AEE0
+ FontColor black
+ FontSize 16
+ AttributeFontColor black
+ AttributeFontSize 16
+ BackgroundColor<<pdf>> #A293E2
+ BackgroundColor<<doc>> #90DED6
+ }
+ state fw as "Firmware" : TF-M binary
+ state c_comp as "C Compiler" : C99
+ state gmake as "GNU make"
+ state u_guide as "User Guide" <<doc>>
+ state refman as "Reference Manual" <<doc>>
+ state rtd_theme as "sphinx-rtd-theme" <<doc>>
+ state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
+ state JRE as "JRE" <<doc>> : Java Runtime Environment
+ state gwiz as "Graphwiz dot" <<doc>>
+ state Sphinx as "Sphinx" <<doc>>
+ state m2r as "m2r" <<doc>>
+ state PlantUML as "PlantUML" <<doc>>
+ state LaTex as "LaTex" <<pdf>>
+ state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
+ state Doxygen as "Doxygen" <<doc>>
+
+ [*] --> fw
+ fw --> c_comp
+ fw --> CMake
+ CMake --> gmake
+ fw --> cryptography
+ fw --> pyasn1
+ fw --> yaml
+ fw --> jinja2
+ fw --> cbor
+ cryptography --> Python3
+ pyasn1 --> Python3
+ yaml --> Python3
+ jinja2 --> Python3
+ cbor --> Python3
+
+ [*] --> u_guide
+ u_guide --> Sphinx
+ Sphinx --> m2r
+ Sphinx --> rtd_theme
+ Sphinx --> sphnix_puml
+ m2r --> Python3
+ rtd_theme --> Python3
+ sphnix_puml --> Python3
+ Sphinx --> PlantUML
+ PlantUML --> JRE
+ PlantUML --> gwiz
+ Sphinx --> LaTex
+ LaTex --> PdfLaTex
+
+ [*] --> refman
+ refman --> Doxygen
+ Doxygen --> PlantUML
+ Doxygen --> LaTex
+ state Legend {
+ state x as "For PDF generation only" <<pdf>>
+ state y as "For document generation only" <<doc>>
+ state z as "Mandatory"
+ }
+
+ @enduml
+
--------------
*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*