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
diff --git a/docs/getting_started/tfm_getting_started.rst b/docs/getting_started/tfm_getting_started.rst
new file mode 100644
index 0000000..b6c52a4
--- /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.*