aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guides/tfm_sw_requirement.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user_guides/tfm_sw_requirement.rst')
-rw-r--r--docs/user_guides/tfm_sw_requirement.rst501
1 files changed, 501 insertions, 0 deletions
diff --git a/docs/user_guides/tfm_sw_requirement.rst b/docs/user_guides/tfm_sw_requirement.rst
new file mode 100644
index 0000000000..be5165f37b
--- /dev/null
+++ b/docs/user_guides/tfm_sw_requirement.rst
@@ -0,0 +1,501 @@
+##########################
+TF-M Software requirements
+##########################
+
+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"
+ "pycrypto",,"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 --> pycrypto
+ fw --> pyasn1
+ fw --> yaml
+ fw --> jinja2
+ pycrypto --> Python3
+ pyasn1 --> Python3
+ yaml --> Python3
+ jinja2 --> 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
+
+****************************
+Supported build environments
+****************************
+
+TF-M officially supports a limited set of build environments and setups. In
+this context, official support means that the environments listed below
+are actively used by team members and active developers hence users should
+be able to recreate the same configurations by following the instructions
+described below. In case of problems, the TF-M team provides support
+only for these environments, but building in other environments can still be
+possible.
+
+The following environments are supported:
+
+ - Windows 10 x64 + Cygwin x64 (example configuration is provided for
+ this Windows setup only).
+ - Windows 10 x64 + msys2 x64.
+ - Windows 10 x65 + git-bash (MinGW) + gnumake from DS-5 or msys2.
+ - Ubuntu 16.04 x64
+ - Ubuntu 18.04 x64
+
+*********************
+Supported C compilers
+*********************
+
+To compile TF-M code, at least one of the supported compiler toolchains have to
+be available in the build environment. The currently supported compiler
+versions are:
+
+ - Arm Compiler v6.7.1
+ - Arm Compiler v6.9
+ - Arm Compiler v6.10
+ - Arm Compiler v6.11
+ - GNU Arm compiler v6.3.1
+ - GNU Arm compiler v7.3
+
+.. Note::
+ - The Arm compilers above are provided via Keil uVision v5.24.1 or
+ greater, DS-5 v5.27.1 or greater, and Development Studio 2018.0, or they can
+ be downloaded as standalone packages from
+ `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__.
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+ - The GNU Arm compiler can be downloaded from
+ `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__.
+ On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update*
+ or *GNU Arm Embedded Toolchain: 7-2018-q2-update*
+
+************************
+Supported CMake versions
+************************
+
+The build-system is CMake based and supports the following versions:
+
+ - 3.7
+ - 3.10
+ - 3.11
+ - 3.12
+ - 3.13
+ - 3.14
+
+.. Note::
+ - Please use the latest build version available (i.e. 3.7.2 instead of
+ 3.7.0).
+ While it is preferable to use the newest version this is not required
+ and any version from the above list should work.
+ - Recent versions of CMake can be downloaded from
+ https://cmake.org/download/, and older releases are available from
+ https://cmake.org/files.
+
+***************************
+Supported GNU make versions
+***************************
+
+The TF-M team builds using the "Unix Makefiles" generator of CMake and
+thus GNU make is needed for the build. On Linux please use the version
+available from the official repository of your distribution.
+
+On Windows the following binaries are supported:
+
+ - GNU make v4.2.1 executable from Cygwin
+ - GNU make v4.2.1 executable from msys2
+ - GNU make v4.2 executable from DS5 v5.29.1 (see <DS5 install root>/bin)
+
+CMake is quiet tolerant to GNU make versions and basically any
+"reasonably recent" GNU make version shall work.
+
+CMake generators other than "Unix Makefiles" may work, but are not
+officially supported.
+
+**************
+Example setups
+**************
+
+This section lists dependencies and some exact and tested steps to set-up a
+TF-M-m build environment under various OSes.
+
+Ubuntu
+======
+
+- DS-5 v5.27.1.
+- Git tools v2.10.0
+- CMake (see the "Supported CMake versions" chapter)
+- GNU Make (see the "Supported make versions" chapter)
+- Python3, with the following libraries:
+- pycrypto
+- pyasn1
+- yaml
+- jinja2 v2.10
+- sudo apt-get install python3-crypto python3-pyasn1 python3-yaml
+ python3-jinja2
+- SRecord v1.58 (for Musca test chip boards)
+
+Setup a shell to enable compiler toolchain and CMake after installation.
+------------------------------------------------------------------------
+
+To import Arm Compiler v6.7.1 in your bash shell console:
+
+.. Warning::
+ Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
+ export ARM_TOOL_VARIANT="ult"
+ export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
+ export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+To import GNU Arm in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+Windows + Cygwin
+================
+
+- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which
+ provides the
+ Arm Compiler v6.7.1 compiler or GNU Arm compiler v6.3.1.
+- Git client latest version (https://git-scm.com/download/win)
+- CMake (see the "Supported CMake versions" chapter)
+- `Cygwin <https://www.cygwin.com/>`__. Tests done with version 2.877
+ (64 bits)
+- GNU make should be installed by selecting appropriate package during
+ cygwin
+ installation.
+- Python3 `(native Windows
+ version) <https://www.python.org/downloads/>`__, with the following
+ libraries:
+- pycryptodome (pip3 install --user pycryptodome)
+- pyasn1 (pip3 install --user pyasn1)
+- pyyaml (pip3 install --user pyyaml)
+- jinja2 (pip3 install --user jinja2)
+- Python3 pip
+- `SRecord v1.63 <https://sourceforge.net/projects/srecord/>`__ (for
+ Musca-A1 test chip board)
+
+Setup Cygwin to enable a compiler toolchain and CMake after installation.
+-------------------------------------------------------------------------
+
+If applicable, import Arm Compiler v6.7.1 in your shell console. To make this
+change permanent, add the command line into ~/.bashrc
+
+Armclang + DS-5
+^^^^^^^^^^^^^^^
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+ - Arm licensing related environment variables must use Windows paths, and not
+ the Cygwin specific one relative to */cygrive*.
+
+.. code-block:: bash
+
+ export PATH="/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.7.1/bin":$PATH
+ export ARM_PRODUCT_PATH="C:/<DS-5_PATH>/sw/mappings"
+ export ARM_TOOL_VARIANT="ult"
+ export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+
+Armclang + Keil MDK Arm
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH="/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin":$PATH
+
+GNU Arm
+^^^^^^^
+
+If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
+this change permanent, add the command line into ~/.bashrc
+
+.. code-block:: bash
+
+ export PATH=<GNU Arm path>/bin:$PATH
+
+CMake
+^^^^^
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/cygdrive/c/<CMake path>/bin:$PATH
+
+Building the documentation
+==========================
+
+The build system is prepared to support generation of two documents.
+The Reference Manual which is Doxygen based, and the User Guide which is
+Sphinx based. Both document 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.
+
+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)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+
+For PDF generation:
+
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen-latex
+
+Windows + Cygwin
+""""""""""""""""
+
+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 DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+ - `MikTeX <https://miktex.org/download>`__
+
+ .. 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.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+::
+
+ export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - 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.
+
+::
+
+ export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
+ export PATH=$PATH:/cygdrive/c/<DS-5 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
+ - 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)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+.. code-block:: bash
+
+ sudo apt-get install -y python3 graphviz default-jre
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+ 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
+
+Windows + Cygwin
+""""""""""""""""
+Download and install the following tools:
+ - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
+ - Pip packages *m2r, Sphinx, sphinx-rtd-theme sphinxcontrib-plantuml*
+
+ .. code-block:: bash
+
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+- `MikTeX <https://miktex.org/download>`__
+
+.. 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.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH="~/plantuml/plantuml.jar"
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - 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
+
+ export PLANTUML_JAR_PATH="c:/plantuml/plantuml.jar"
+ export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*