diff options
author | Summer Qin <summer.qin@arm.com> | 2021-05-24 15:32:44 +0800 |
---|---|---|
committer | Summer Qin <summer.qin@arm.com> | 2021-06-23 11:21:07 +0800 |
commit | 6d5c91c4581197cbef92ba6e167b4fdc9eafa809 (patch) | |
tree | 6cc72662248c5e41b55e57bba5e9de71563ac6fe | |
parent | 0de91c96e73d38ac294e90ec4e06c3f6ad2bbb94 (diff) | |
download | trusted-firmware-m-6d5c91c4581197cbef92ba6e167b4fdc9eafa809.tar.gz |
Docs: Refine tfm_sw_requirement.rst
Simplify the tfm software requirement document and change the document
to 'tfm_getting_started.rst', let it more
suitable for new starter.
Signed-off-by: Summer Qin <summer.qin@arm.com>
Change-Id: I10379aa92ac2c6cd784f0fd1b1b5431243716d74
-rw-r--r-- | docs/contributing/contributing_process.rst | 2 | ||||
-rw-r--r-- | docs/contributing/doc_guidelines.rst | 8 | ||||
-rw-r--r-- | docs/contributing/tfm_design_proposal_process.rst | 4 | ||||
-rw-r--r-- | docs/getting_started/index.rst | 2 | ||||
-rw-r--r-- | docs/getting_started/tfm_getting_started.rst | 465 | ||||
-rw-r--r-- | docs/getting_started/tfm_sw_requirement.rst | 440 | ||||
-rw-r--r-- | docs/introduction/readme.rst | 2 | ||||
-rw-r--r-- | docs/releases/1.3.0.rst | 2 | ||||
-rw-r--r-- | docs/technical_references/instructions/tfm_build_instruction.rst | 4 | ||||
-rw-r--r-- | platform/ext/target/cypress/psoc64/cypress_psoc64_spec.rst | 2 | ||||
-rw-r--r-- | readme.rst | 4 |
11 files changed, 480 insertions, 455 deletions
diff --git a/docs/contributing/contributing_process.rst b/docs/contributing/contributing_process.rst index 002df7e856..8bd7e52281 100644 --- a/docs/contributing/contributing_process.rst +++ b/docs/contributing/contributing_process.rst @@ -26,7 +26,7 @@ Contributions to the TF-M project need to follow the process below. - Clone the TF-M code on your own machine from `TF-M git repository <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`_. - - Follow the :doc:`SW Requirements </docs/getting_started/tfm_sw_requirement>`, + - Follow the :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`, :doc:`Build Instructions </docs/technical_references/instructions/tfm_build_instruction>` and :doc:`Coding Guide </docs/contributing/coding_guide>` for the TF-M project. - Make your changes in logical chunks to help reviewers. Each commit should diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst index 41f4e05c98..607097de80 100644 --- a/docs/contributing/doc_guidelines.rst +++ b/docs/contributing/doc_guidelines.rst @@ -20,7 +20,7 @@ The following short-list provides a quick summary of the rules. - If the patch modifies a present file, the file's style should be followed - If creating a new file, - :doc:`integration guide </docs/getting_started/tfm_sw_requirement>` can be used as a reference. + :doc:`integration guide </docs/integration_guide/tfm_integration_guide>` can be used as a reference. - When a new style is to be expressed, consult the `Python Documentation Guidelines`_ ************* @@ -186,7 +186,7 @@ will not be added to the index (So it cannot be referenced if needed) +--------------+--------------+-------------+ Other types of tables such as list-tables and csv-tables are also permitted, as -seen on :doc:`/docs/getting_started/tfm_sw_requirement` and +seen on :doc:`/docs/getting_started/tfm_getting_started` and :doc:`/docs/releases/1.0` @@ -236,7 +236,7 @@ A document included in the documentation can be referenced by the `doc:` notatio .. code-block:: restructuredtext - :doc:`integration guide </docs/getting_started/tfm_sw_requirement>` + :doc:`integration guide </docs/integration_guide/tfm_integration_guide>` The path is relative to the root of the Trusted Firmware-M code. @@ -248,7 +248,7 @@ In order to reference a specific section of a document, up to level 4 headers .. code-block:: restructuredtext - :ref:`docs/getting_started/tfm_sw_requirement:Tool & Dependency overview` + :ref:`docs/getting_started/tfm_getting_started:Tool & Dependency overview` This can also be used to quickly scroll to the specific section of the current document. This technique can be used to add complex table in the bottom of a diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst index 49ff7e70d5..0c10b7bcea 100644 --- a/docs/contributing/tfm_design_proposal_process.rst +++ b/docs/contributing/tfm_design_proposal_process.rst @@ -69,8 +69,8 @@ In order to work on TF-M documentation the TF-M git repository has to be available locally. Setting up the documentation tools will allow pre-viewing the documentation file in preparation. For information on what tools are needed please refer to -:doc:`sw requirements </docs/getting_started/tfm_sw_requirement>`. To see how to get -a local copy of the TF-M repository please see +:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. To see +how to get a local copy of the TF-M repository please see :doc:`build instructions </docs/technical_references/instructions/tfm_build_instruction>` Process steps diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 9ddb2d09cc..a3e729b745 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -5,7 +5,7 @@ Getting Started Guides :glob: :numbered: - tfm_sw_requirement + tfm_getting_started -------------- diff --git a/docs/getting_started/tfm_getting_started.rst b/docs/getting_started/tfm_getting_started.rst new file mode 100644 index 0000000000..b6c52a4a05 --- /dev/null +++ b/docs/getting_started/tfm_getting_started.rst @@ -0,0 +1,465 @@ +#################################### +Select and set up 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: + +.. tabs:: + + .. group-tab:: Linux + + 1. version supported: + + Ubuntu 18.04 x64+ + + 2. install dependencies: + + .. code-block:: bash + + sudo apt-get install -y git curl wget build-essential libssl-dev python3 \ + python3-pip cmake make + + 3. verify cmake version: + + .. code-block:: bash + + cmake --version + + .. note:: + + Please download cmake 3.15 or later version from https://cmake.org/download/. + + 4. add CMake path into environment: + + .. code-block:: bash + + export PATH=<CMake path>/bin:$PATH + + .. group-tab:: Windows + + 1. version supported: + + Windows 10 x64 + + 2. install dependecies: + + - Git client latest version (https://git-scm.com/download/win) + - CMake (`native Windows version <https://cmake.org/download/>`__) + - GNU make (http://gnuwin32.sourceforge.net/packages/make.htm) + - Python3 `(native Windows version) <https://www.python.org/downloads/>`__ and + the pip package manager (from Python 3.4 it's included) + + 3. add CMake path into environment: + + .. code-block:: bash + + set PATH=<CMake_Path>\bin;$PATH + +########################### +Install python dependencies +########################### + +Clone the TF-M source code, and then install the TF-M's additional Python +dependencies. + +.. tabs:: + + .. group-tab:: Linux + + 1. get the TF-M source code: + + .. code-block:: bash + + cd <base folder> + git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git + + 2. TF-M's ``tools/requirements.txt`` file declares additional Python + dependencies. Install them with ``pip3``: + + .. code-block:: bash + + pip3 install --upgrade pip + cd trusted-firmware-m + pip3 install -r tools/requirements.txt + + .. group-tab:: Windows + + 1. get the TF-M source code: + + .. code-block:: bash + + cd <base folder> + git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git + + 2. TF-M's ``tools/requirements.txt`` file declares additional Python + dependencies. Install them with ``pip3``: + + .. code-block:: bash + + cd trusted-firmware-m + pip3 install -r tools\requirements.txt + +################### +Install a toolchain +################### + +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.10.1+ + + .. tabs:: + + .. group-tab:: Linux + + - Download the standalone packages from `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__. + - Add Arm Compiler into environment: + + .. code-block:: bash + + export PATH=<ARM_CLANG_PATH>/sw/ARMCompiler6.10.1/bin:$PATH + export ARM_PRODUCT_PATH=<ARM_CLANG_PATH>/sw/mappings + + .. group-tab:: Windows + + - Download the standalone packages from `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__. + - Add Arm Compiler into environment: + + .. code-block:: bash + + set PATH=<ARM_CLANG_PATH>\sw\ARMCompiler6.10.1\bin;$PATH + set ARM_PRODUCT_PATH=<ARM_CLANG_PATH>\sw\mappings + + - GNU Arm compiler v7.3.1+ + + .. tabs:: + + .. group-tab:: Linux + + - Download the GNU Arm compiler from `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__. + - Add GNU Arm into environment: + + .. code-block:: bash + + export PATH=<GNU_ARM_PATH>/bin:$PATH + + .. group-tab:: Windows + + - Download the GNU Arm compiler from `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__. + - Add GNU Arm into environment: + + .. code-block:: bash + + export PATH=<GNU_ARM_PATH>\bin;$PATH + + .. note:: + + GNU Arm compiler version *10-2020-q4-major* has an issue in CMSE + support. The bug is reported in `here <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157>`__. + Select other GNU Arm compiler versions instead. + + - IAR Arm compiler v8.42.x, v8.50.x + + .. tabs:: + + .. group-tab:: Linux + + - Download IAR build tools from `here <https://www.iar.com/iar-embedded-workbench/build-tools-for-linux/>`__. + - Add IAR Arm compiler into environment: + + .. code-block:: bash + + export PATH=<IAR_COMPILER_PATH>/bin:$PATH + + .. group-tab:: Windows + + - Download IAR build tools from `here <https://www.iar.com/iar-embedded-workbench/#!?architecture=Arm>`__. + - Add IAR Arm compiler into environment: + + .. code-block:: bash + + export PATH=<IAR_COMPILER_PATH>\bin;$PATH + +############################# +Build AN521 regression sample +############################# + +Here, we take building TF-M for AN521 platform with regression tests using GCC +as an example: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + cd trusted-firmware-m + cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug -DTEST_S=ON -DTEST_NS=ON + cmake --build cmake_build -- install + + Alternately using traditional cmake syntax + + .. code-block:: bash + + cd trusted-firmware-m + mkdir cmake_build + cd cmake_build + cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON + make install + + .. group-tab:: Windows + + .. code-block:: bash + + cd trusted-firmware-m + cmake -G"Unix Makefiles" -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug -DTEST_S=ON -DTEST_NS=ON + cmake --build cmake_build -- install + + Alternately using traditional cmake syntax + + .. code-block:: bash + + cd trusted-firmware-m + mkdir cmake_build + cd cmake_build + cmake -G"Unix Makefiles" .. -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON + make install + +########################### +Run AN521 regression sample +########################### + +Run the sample code on SSE-200 Fast-Model, using FVP_MPS2_AEMv8M provided by +Arm Development Studio. + +.. note:: + + Arm Development Studio is not essential to develop TF-M, you can skip this + section if don't want to try on Arm develop boards. + +.. tabs:: + + .. group-tab:: Linux + + 1. install Arm Development Studio to get the fast-model. + + Download Arm Development Studio from `here <https://developer.arm.com/tools-and-software/embedded/arm-development-studio>`__. + + 2. Add ``bl2.axf`` and ``tfm_s_ns_signed.bin`` to symbol files in Debug + Configuration menu. + + .. code-block:: bash + + <DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \ + --parameter fvp_mps2.platform_type=2 \ + --parameter cpu0.baseline=0 \ + --parameter cpu0.INITVTOR_S=0x10000000 \ + --parameter cpu0.semihosting-enable=0 \ + --parameter fvp_mps2.DISABLE_GATING=0 \ + --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ + --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ + --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ + --parameter fvp_mps2.telnetterminal0.quiet=0 \ + --parameter fvp_mps2.telnetterminal1.quiet=1 \ + --parameter fvp_mps2.telnetterminal2.quiet=1 \ + --application cpu0=<build_dir>/bin/bl2.axf \ + --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 + + .. group-tab:: Windows + + 1. install Arm Development Studio to get the fast-model. + + Download Arm Development Studio from `here <https://developer.arm.com/tools-and-software/embedded/arm-development-studio>`__. + + 2. Add ``bl2.axf`` and ``tfm_s_ns_signed.bin`` to symbol files in Debug + Configuration menu. + + .. code-block:: bash + + <DS_PATH>\sw\models\bin\FVP_MPS2_AEMv8M \ + --parameter fvp_mps2.platform_type=2 \ + --parameter cpu0.baseline=0 \ + --parameter cpu0.INITVTOR_S=0x10000000 \ + --parameter cpu0.semihosting-enable=0 \ + --parameter fvp_mps2.DISABLE_GATING=0 \ + --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ + --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ + --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ + --parameter fvp_mps2.telnetterminal0.quiet=0 \ + --parameter fvp_mps2.telnetterminal1.quiet=1 \ + --parameter fvp_mps2.telnetterminal2.quiet=1 \ + --application cpu0=<build_dir>/bin/bl2.axf \ + --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 + +After completing the procedure you should see the following messages on the +DAPLink UART (baud 115200 8n1):: + + [INF] Starting bootloader + [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff + [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9 + [INF] Boot source: primary slot + [INF] Swap type: none + [INF] Bootloader chainload address offset: 0x20000 + [INF] Jumping to the first image slot + [Sec Thread] Secure image initializing! + + #### Execute test suites for the protected storage service #### + Running Test Suite PS secure interface tests (TFM_PS_TEST_2XXX)... + > Executing 'TFM_PS_TEST_2001' + Description: 'Create interface' + TEST PASSED! + > Executing 'TFM_PS_TEST_2002' + Description: 'Get handle interface (DEPRECATED)' + This test is DEPRECATED and the test execution was SKIPPED + TEST PASSED! + > Executing 'TFM_PS_TEST_2003' + Description: 'Get handle with null handle pointer (DEPRECATED)' + This test is DEPRECATED and the test execution was SKIPPED + TEST PASSED! + > Executing 'TFM_PS_TEST_2004' + Description: 'Get attributes interface' + TEST PASSED! + > Executing 'TFM_PS_TEST_2005' + Description: 'Get attributes with null attributes struct pointer' + .... + +########################## +Tool & Dependency overview +########################## + +To build the TF-M firmware the following tools are needed: + +.. csv-table:: Tool dependencies + :header: "Name", "Version", "Component" + + "C compiler",,"Firmware" + "CMake",, + "GNU Make",, + "tf-m-tests",CMake handles it, + "mbed-crypto",CMake handles it, + "MCUboot",CMake handles it, + "Python",3.x,"Firmware, User Guide" + "yaml",,"Firmware" + "pyasn1",,"Firmware" + "jinja2",,"Firmware" + "cryptography",,"Firmware" + "cbor",,"Firmware" + "click",,"Firmware" + "imgtool",,"Firmware" + "Doxygen",">1.8","Reference manual" + "Sphinx","=1.7.9","User Guide" + "sphinxcontrib-plantuml",,"User Guide" + "sphinxcontrib-svg2pdfconverter",,"User Guide" + "sphinx-rtd-theme",,"User Guide" + "sphinx-tabs",,"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 tabs as "sphinx-tabs" <<doc>> + state sphnix_puml as "sphinxcontrib-plantuml" <<doc>> + state sphnix_svg as "sphinxcontrib-svg2pdfconverter" <<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 + fw --> click + fw --> imgtool + cryptography --> Python3 + pyasn1 --> Python3 + yaml --> Python3 + jinja2 --> Python3 + cbor --> Python3 + click --> Python3 + imgtool --> Python3 + + [*] --> u_guide + u_guide --> Sphinx + Sphinx --> m2r + Sphinx --> rtd_theme + Sphinx --> tabs + Sphinx --> sphnix_puml + Sphinx --> sphnix_svg + m2r --> Python3 + rtd_theme --> Python3 + tabs --> Python3 + sphnix_puml --> Python3 + sphnix_svg --> 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 + +########## +Next steps +########## + +Here are some next steps for exploring TF-M: + + - Detailed :doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>`. + - :doc:`IAR Build instructions </docs/technical_references/instructions/tfm_build_instruction_iar>`. + - Try other :doc:`Samples and Demos </docs/technical_references/instructions/run_tfm_examples_on_arm_platforms>`. + - :doc:`Documentation generation </docs/technical_references/instructions/documentation_generation>`. + +-------------- + +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst deleted file mode 100644 index 71972599a2..0000000000 --- a/docs/getting_started/tfm_sw_requirement.rst +++ /dev/null @@ -1,440 +0,0 @@ -##################### -Software requirements -##################### - -.. |KEIL_VERSION| replace:: v5.25.2 -.. |DEV_STUDIO_VERSION| replace:: 2019.1 - -A quick reference table is included in the -:ref:`docs/getting_started/tfm_sw_requirement:Tool & Dependency overview` section -of this document. - -**************************** -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: - - - Ubuntu 18.04 x64 - - Windows 10 x64 - -*********** -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.10.1+ - - GNU Arm compiler v7.3.1+ - - IAR Arm compiler v8.42.x, v8.50.x - -.. Note:: - - The Arm compilers above are provided via Keil uVision |KEIL_VERSION| - or greater and Arm Development Studio - |DEV_STUDIO_VERSION| or greater, or they can be downloaded as standalone - packages from - `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__. - - - 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: 7-2018-q2-update* or an - above version. - - - GNU Arm compiler version *10-2020-q4-major* has an issue in CMSE support. - The bug is reported in `here <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157>`__. - Select other GNU Arm compiler versions instead. - - - The IAR Arm compilers above are provided via IAR Embedded Workbench (Windows) or - IAR build tools for linux. - For information, see - `here <https://www.iar.com/iar-embedded-workbench/#!?architecture=Arm>`__ or - `here <https://www.iar.com/iar-embedded-workbench/build-tools-for-linux/>`__. - -***** -CMake -***** - -The build-system is CMake based and supports the version 3.15 or higher. - - - Please use the latest build version available. - - Recent versions of CMake can be downloaded from - https://cmake.org/download/, and older releases are available from - https://cmake.org/files. - -CMake handles all external dependencies, but if you wish to alter this -behaviour, see :ref:`docs/technical_references/instructions/tfm_build_instruction:Manual -dependency management` - -******** -GNU make -******** - -TF-M project builds using the "Unix Makefiles" generator of CMake -and thus GNU make is needed for the build. - - - On Linux please use the version available in your distribution. - - On Windows, GNU make v3.81 or higher shall work fine. - -CMake generators other than "Unix Makefiles" may work too, but are not -officially supported. You may have a good luck with Ninja. - -******************************************** -Tools for configuring and programming boards -******************************************** - -Please follow a board secific documentation for building and programming -tools. - -************** -Typical setups -************** - -This section lists steps to set-up TF-M build environment under Linux and Windows. -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 -====== - -Setup needed tools for Ubuntu ------------------------------ - -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 <http://srecord.sourceforge.net/download.html/>`__ - (for Musca test chip boards) - - Python3 and the pip package manager (from Python 3.4 it's included) - - 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 - - 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:`Getting the source-code`), -then - -.. 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: - -.. code-block:: bash - - export PATH=<ARM_DS_PATH>/sw/ARMCompiler6.13/bin:$PATH - export ARM_TOOL_VARIANT=ult - export ARM_PRODUCT_PATH=<ARM_DS_PATH>/sw/mappings - export ARMLMD_LICENSE_FILE=<LICENSE_FILE_PATH> - -To import GNU Arm in your bash shell console: - -.. code-block:: bash - - export PATH=<bash path>/bin:$PATH - -To import IAR Arm compiler in your bash shell console: - -.. code-block:: bash - - export PATH=<IAR compiler path>/bin:$PATH - -To import PLATUML: - -.. code-block:: bash - - export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar - -Windows -======= - -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 (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) - - 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:`Getting the source-code`), -then - -.. code-block:: bash - - cd trusted-firmware-m - pip install -r tools\requirements.txt - -Finally, install C compiler (see `C compilers`_), CMake (see `CMake`_) -and SRecord as required. - -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 - set ARM_PRODUCT_PATH=<ARM_DS_PATH>\sw\mappings - set ARM_TOOL_VARIANT=ult - 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 - -**************************** -Exceptions and special cases -**************************** - -ArmClang -======== - - 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>`__. - -MikTeX -====== - - 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. - -************************** -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 `C compilers`_,"Firmware" - "CMake",See `CMake`_, - "GNU Make",See `GNU make`_, - "tf-m-tests",`CMake`_ handles it, - "mbed-crypto",`CMake`_ handles it, - "MCUboot",`CMake`_ handles it, - "Python",3.x,"Firmware, User Guide" - "yaml",,"Firmware" - "pyasn1",,"Firmware" - "jinja2",,"Firmware" - "cryptography",,"Firmware" - "cbor",,"Firmware" - "click",,"Firmware" - "imgtool",,"Firmware" - "Doxygen",">1.8","Reference manual" - "Sphinx","=1.7.9","User Guide" - "sphinxcontrib-plantuml",,"User Guide" - "sphinxcontrib-svg2pdfconverter",,"User Guide" - "sphinx-rtd-theme",,"User Guide" - "sphinx-tabs",,"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 tabs as "sphinx-tabs" <<doc>> - state sphnix_puml as "sphinxcontrib-plantuml" <<doc>> - state sphnix_svg as "sphinxcontrib-svg2pdfconverter" <<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 - fw --> click - fw --> imgtool - cryptography --> Python3 - pyasn1 --> Python3 - yaml --> Python3 - jinja2 --> Python3 - cbor --> Python3 - click --> Python3 - imgtool --> Python3 - - [*] --> u_guide - u_guide --> Sphinx - Sphinx --> m2r - Sphinx --> rtd_theme - Sphinx --> tabs - Sphinx --> sphnix_puml - Sphinx --> sphnix_svg - m2r --> Python3 - rtd_theme --> Python3 - tabs --> Python3 - sphnix_puml --> Python3 - sphnix_svg --> 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-2021, Arm Limited. All rights reserved.* diff --git a/docs/introduction/readme.rst b/docs/introduction/readme.rst index 2e67961a4e..c3a31593a5 100644 --- a/docs/introduction/readme.rst +++ b/docs/introduction/readme.rst @@ -84,7 +84,7 @@ Trusted Firmware M source code is available on To build & run TF-M: - - Follow the :doc:`SW requirements guide </docs/getting_started/tfm_sw_requirement>` + - Follow the :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>` to set up your environment. - Follow the :doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>` diff --git a/docs/releases/1.3.0.rst b/docs/releases/1.3.0.rst index a68dbc9dbc..9e281cb05f 100644 --- a/docs/releases/1.3.0.rst +++ b/docs/releases/1.3.0.rst @@ -148,7 +148,7 @@ TF-M. | 10-2020-q4-major. | The support for CMSE feature is broken in version 10-2020-q4-major. The | fix will be available in future release version. - | A note is added in :ref:`docs/getting_started/tfm_sw_requirement:C compilers`. + | A note is added in :ref:`docs/getting_started/tfm_getting_started:Install a toolchain`. - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157 Reference diff --git a/docs/technical_references/instructions/tfm_build_instruction.rst b/docs/technical_references/instructions/tfm_build_instruction.rst index 116b5d1bad..49bdeffc2b 100644 --- a/docs/technical_references/instructions/tfm_build_instruction.rst +++ b/docs/technical_references/instructions/tfm_build_instruction.rst @@ -2,7 +2,7 @@ Build instructions ################## Please make sure you have all required software installed as explained in the -:doc:`software requirements </docs/getting_started/tfm_sw_requirement>`. +:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. **************** TF-M build steps @@ -31,7 +31,7 @@ dependency management` .. Note:: - For building with Armclang compiler version 6.10.0+, please follow the note - in :doc:`software requirements </docs/getting_started/tfm_sw_requirement>`. + in :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. - For building with the IAR toolchain, please see the notes in :doc:`IAR software requirements <tfm_build_instruction_iar>` diff --git a/platform/ext/target/cypress/psoc64/cypress_psoc64_spec.rst b/platform/ext/target/cypress/psoc64/cypress_psoc64_spec.rst index f55eecacad..9d88b43900 100644 --- a/platform/ext/target/cypress/psoc64/cypress_psoc64_spec.rst +++ b/platform/ext/target/cypress/psoc64/cypress_psoc64_spec.rst @@ -13,7 +13,7 @@ Use the following policy file for provisioning and signing: policy_multi_CM0_CM4_tfm.json Please make sure you have all required software installed as explained in the -:doc:`software requirements </docs/getting_started/tfm_sw_requirement>`. +:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. Please also make sure that all the source code are fetched by following :doc:`general building instruction </docs/technical_references/instructions/tfm_build_instruction>`. diff --git a/readme.rst b/readme.rst index 27458828fb..35a3f96656 100644 --- a/readme.rst +++ b/readme.rst @@ -21,7 +21,7 @@ Quick Links * `PSA certified`_ * `Documentation home`_ * `Release notes`_ -* `Software requirements`_ +* `TF-M getting started`_ * `Build instructions`_ * `Run TF-M examples on Arm platforms`_ * `Contribution guidelines`_ @@ -36,7 +36,7 @@ Feedback can be submitted via email to .. _License: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/license.html .. _Contribution guidelines: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/contributing/contributing_process.html .. _Build instructions: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/technical_references/instructions/tfm_build_instruction.html -.. _Software requirements: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/getting_started/tfm_sw_requirement.html +.. _TF-M getting started: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/getting_started/tfm_getting_started.html .. _Run TF-M examples on Arm platforms: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/technical_references/instructions/run_tfm_examples_on_arm_platforms.html .. _ARMv7-M and Armv8-M: https://developer.arm.com/architectures/cpu-architecture/m-profile .. _ARMv8-M Architecture: https://developer.arm.com/docs/100688/latest/an-introduction-to-the-armv8-m-architecture |