docs: update build and sw requirement docs
Updated build and software requirements documentation
1. Simplified Linux and Windows build environment setup
2. Updated tools version dependencies
3. Removed some docs compilation warnings
Signed-off-by: Subhasish Ghosh <subhasish.ghosh@arm.com>
Change-Id: Ia0655e509d4a6424068b6113cc8a80f4b93fe8bd
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index 9779d09..403fccd 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -253,12 +253,16 @@
TF-M build examples
*******************
+.. Note::
+ By default, CMAKE_BUILD_TYPE is set to Release, for debug support change
+ this to Debug. See below for an example.
+
Example: building TF-M for AN521 platform using GCC:
====================================================
.. code-block:: bash
cd <TF-M base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake
+ cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake_build -- install
Alternately using traditional cmake syntax
@@ -286,6 +290,7 @@
specify in the command line
.. code-block:: bash
+
cd <TF-M base folder>
cmake -S . -B cmake_build -DTFM_PLATFORM=mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DTEST_S=ON -DTEST_NS=ON
cmake --build cmake_build -- install
@@ -323,7 +328,7 @@
The value of the TEST_PSA_API variable is the suite to be run.
-.. code-block::
+.. code-block:: bash
-DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
-DTEST_PSA_API=PROTECTED_STORAGE
@@ -356,7 +361,7 @@
The build system provides support for building and integrating the PSA FF
compliance test. This support is controlled by the TEST_PSA_API variable:
-.. code-block::
+.. code-block:: bash
-DTEST_PSA_API=IPC
diff --git a/docs/getting_started/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst
index f734105..e720647 100644
--- a/docs/getting_started/tfm_sw_requirement.rst
+++ b/docs/getting_started/tfm_sw_requirement.rst
@@ -23,7 +23,6 @@
The following environments are supported:
- - Ubuntu 16.04 x64
- Ubuntu 18.04 x64
- Windows 10 x64
@@ -104,27 +103,73 @@
Please also check the `Exceptions and special cases`_ chapter for any special
requirements depending on the tools you are using.
+The build system can generate two documents: The Reference Manual and the
+User Guide. Both documents can be generated in HTML and PDF format.
+
+.. Note::
+ Support for document generation in the build environment is not mandatory.
+ Missing document generation tools will not block building the
+ TF-M firmware.
+
Ubuntu
======
-Install the following tools:
+Setup needed tools for Ubuntu
+-----------------------------
- - Arm DS |DEV_STUDIO_VERSION|.
+Tools required to build sources:
+
+ - Arm DS |DEV_STUDIO_VERSION| (Arm DS Ultimate Edition)
+ or GNU Arm compiler v7.3.1+
- Git tools v2.10.0
- CMake (see the `CMake`_ chapter)
- GNU Make (see the `GNU make`_ chapter)
- - SRecord v1.58 (for Musca test chip boards)
+ - `SRecord v1.58 <http://srecord.sourceforge.net/download.html/>`__
+ (for Musca test chip boards)
- Python3 and the pip package manager (from Python 3.4 it's included)
- - The necessary Python3 packages are listed in the requirements.txt file.
- To install all needed just do:
+ - Python3 packages as listed in tools/requirements.txt file
+
+Tools required to generate documentation:
+
+ - Doxygen v1.8.0 or later - for reference manual
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+ - LaTeX - for PDF generation only
+ - PdfLaTeX - for PDF generation only
+ - Python3 packages as listed in tools/requirements.txt - for user manual
+
+Download and install the required tools:
.. code-block:: bash
- pip install -r tools/requirements.txt
+ sudo apt-get update
+ sudo apt-get install -y git curl wget build-essential libssl-dev python3 \
+ python3-pip doxygen graphviz default-jre doxygen-latex
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+Clone the TF-M Sources
+(see :ref:`docs/getting_started/tfm_build_instruction:Getting the source-code`),
+then
-Setup environment variables in Linux
-------------------------------------
+.. code-block:: bash
+
+ pip3 install --upgrade pip
+ cd trusted-firmware-m
+ pip3 install -r tools/requirements.txt
+
+Finally, install C compiler (see `C compilers`_), CMake (see `CMake`_)
+and SRecord as required.
+
+Setup environment variables for Ubuntu
+--------------------------------------
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=<CMake path>/bin:$PATH
To import Arm Compiler v6.13 in your bash shell console:
@@ -135,12 +180,6 @@
export ARM_PRODUCT_PATH=<ARM_DS_PATH>/sw/mappings
export ARMLMD_LICENSE_FILE=<LICENSE_FILE_PATH>
-To import CMake in your bash shell console:
-
-.. code-block:: bash
-
- export PATH=<CMake path>/bin:$PATH
-
To import GNU Arm in your bash shell console:
.. code-block:: bash
@@ -153,42 +192,97 @@
export PATH=<IAR compiler path>/bin:$PATH
+To import PLATUML:
+
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
Windows
=======
-Install the following tools:
+Setup needed tools for Windows
+------------------------------
+
+Tools required to build sources:
- uVision |KEIL_VERSION| or Arm DS |DEV_STUDIO_VERSION| (Arm DS Ultimate Edition)
or GNU Arm compiler v7.3.1+
- Git client latest version (https://git-scm.com/download/win)
- CMake (`native Windows version <https://cmake.org/download/>`__,
see the `CMake`_ chapter)
- - GNU make
+ - GNU make (http://gnuwin32.sourceforge.net/packages/make.htm)
- `SRecord v1.63 <https://sourceforge.net/projects/srecord/>`__ (for Musca test
chip boards)
- Python3 `(native Windows version) <https://www.python.org/downloads/>`__ and
the pip package manager (from Python 3.4 it's included)
- - The necessary Python3 packages are listed in the requirements.txt file.
- To install all needed just do:
+ - Python3 packages as listed in tools/requirements.txt file
+
+Tools required to generate documentation:
+
+ - `Doxygen v1.8.0
+ <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/
+ windows/doxygenw20140924_1_8_8.zip/download>`__
+ or later - for reference manual
+ - `Graphviz dot v2.38.0
+ <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ or later
+ - `PlantUML v1.2018.11
+ <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+ or later
+ - The Java runtime 1.8 or later (for running PlantUML) is part of the Arm DS
+ installation or can be downloaded from
+ `here <https://www.java.com/en/download/>`__
+ - LaTeX - for PDF generation only
+ - PdfLaTeX - for PDF generation only
+ - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
+ - Python3 packages as listed in tools/requirements.txt - for user manual
+
+Download and install the required tools from above.
+
+Clone the TF-M Sources
+(see :ref:`docs/getting_started/tfm_build_instruction:Getting the source-code`),
+then
.. code-block:: bash
+ cd trusted-firmware-m
pip install -r tools\requirements.txt
-Setup environment variables in Windows
---------------------------------------
+Finally, install C compiler (see `C compilers`_), CMake (see `CMake`_)
+and SRecord as required.
-Add CMake to your PATH variable:
+Setup environment variables for Windows
+---------------------------------------
+Set the environment variables, assuming that:
+
+ - CMake, doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from Arm DS installation.
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+
+To import CMake to your PATH variable:
.. code-block:: bash
set PATH=<CMake_Path>\bin;$PATH
+To import PLATUML:
+
+.. code-block:: bash
+
+ set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
+
+To set PATH for ARMDS:
+
+.. code-block:: bash
+
+ set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
+
There are several configurations depending on a toolset you are using.
The typical cases are listed below.
Armclang + Arm DS
-^^^^^^^^^^^^^^^^^
+
.. code-block:: bash
set PATH=<ARM_DS_PATH>\sw\ARMCompiler6.13\bin;$PATH
@@ -197,150 +291,17 @@
set ARMLMD_LICENSE_FILE=<LICENSE_FILE_PATH>
Armclang + Keil MDK Arm
-^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
set PATH=<uVision path>\ARM\ARMCLANG\bin;$PATH
GNU Arm
-^^^^^^^
.. code-block:: bash
set PATH=<GNU Arm path>\bin;$PATH
-**************************
-Building the documentation
-**************************
-
-The build system is prepared to support generation of two documents:
-The Reference Manual and the User Guide.
-The Reference Manual is Doxygen based, while the User Guide is
-Sphinx based. Both document can be generated in HTML and PDF format.
-
-Support for document generation in the build environment is not mandatory.
-Missing document generation tools will not block building the TF-M firmware.
-
-To compile the TF-M Reference Manual
-====================================
-
-The following additional tools are needed:
-
- - Doxygen v1.8.0 or later
- - Graphviz dot v2.38.0 or later
- - PlantUML v1.2018.11 or later
- - Java runtime environment 1.8 or later (for running PlantUML)
- - LaTeX - for PDF generation only
- - PdfLaTeX - for PDF generation only
-
-Set-up the needed tools and environment in Linux
-------------------------------------------------
-
-.. code-block:: bash
-
- sudo apt-get install -y doxygen graphviz default-jre
- mkdir ~/plantuml
- curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
- export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
-
-For PDF generation:
-
-.. code-block:: bash
-
- sudo apt-get install -y doxygen-latex
-
-Set-up the needed tools and environment in Windows
---------------------------------------------------
-
-Download and install the following tools:
-
- - `Doxygen
- 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
- - `Graphviz
- 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- - The Java runtime is part of the Arm DS installation or can be
- `downloaded from here <https://www.java.com/en/download/>`__
- - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
- - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
-
-Set the environment variables, assuming that:
-
- - doxygen, dot, and MikTeX binaries are available on the PATH.
- - Java JVM is used from Arm DS installation.
-
-::
-
- set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
- set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
-
-To compile the TF-M User Guide
-==============================
-
-The following additional tools are needed:
-
- - Python3 and the following modules:
- - Sphinx v1.7.9
- - m2r v0.2.0
- - sphinxcontrib-plantuml
- - sphinxcontrib-svg2pdfconverter
- - sphinx-rtd-theme
- - Graphviz dot v2.38.0 or later
- - PlantUML v1.2018.11 or later
- - Java runtime environment 1.8 or later (for running PlantUML)
- - LaTeX - for PDF generation only
- - PdfLaTeX - for PDF generation only
-
-Set-up the tools and environment in Linux
------------------------------------------
-
-.. code-block:: bash
-
- sudo apt-get install -y python3 graphviz default-jre
- pip install -r tools/requirements.txt
- mkdir ~/plantuml
- curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
-
-For PDF generation:
-
-.. code-block:: bash
-
- sudo apt-get install -y doxygen-latex
- export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
-
-Set-up the tools and environment in Windows
--------------------------------------------
-
-Download and install the following tools:
-
- - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- - The Java runtime is part of the Arm DS installation or can be `downloaded from here <https://www.java.com/en/download/>`__
- - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
- - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
- - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
- - The necessary Python3 packages are listed in the requirements.txt file.
- To install all needed packages just do:
-
-.. code-block:: bash
-
- pip install -r tools\requirements.txt
-
-.. Note::
- When building the documentation the first time, MikTeX might
- prompt for installing missing LaTeX components. Please allow the MikTeX
- package manager to set-up these.
-
-Set the environment variables, assuming that:
-
- - plantuml.jar is available at c:\\plantuml\\plantuml.jar
- - doxygen, dot, and MikTeX binaries are available on the PATH.
- - Java JVM is used from DS5 installation.
-
-.. code-block:: bash
-
- set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
- set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
-
****************************
Exceptions and special cases
****************************
@@ -381,7 +342,7 @@
"click",,"Firmware"
"imgtool",,"Firmware"
"Doxygen",">1.8","Reference manual"
- "Sphinx",">1.4","User Guide"
+ "Sphinx","=1.7.9","User Guide"
"sphinxcontrib-plantuml",,"User Guide"
"sphinxcontrib-svg2pdfconverter",,"User Guide"
"sphinx-trd-theme",,"User Guide"