From 02cc2efb6abaa418c3342f0161804cd170f9807f Mon Sep 17 00:00:00 2001 From: Harrison Mutai Date: Tue, 16 Apr 2024 08:35:50 +0000 Subject: [PATCH] refactor(docs): restructure min requirements section The ordering of the setup guide is quite confusing, primarly because the min requirements section is overly verbose. Reconcile this information into a single table, and present the most important information at the start of the document i.e. how to get the source, and the tools to compile. Change-Id: I1c4d708259e152b101c7282dad19e467d6c36519 Signed-off-by: Harrison Mutai --- docs/getting_started/prerequisites.rst | 182 ++++++++++++------------- 1 file changed, 91 insertions(+), 91 deletions(-) diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst index 3498ac5f0..0d4331fb1 100644 --- a/docs/getting_started/prerequisites.rst +++ b/docs/getting_started/prerequisites.rst @@ -8,32 +8,53 @@ It may possible to build |TF-A| with combinations of software packages that are different from those listed below, however only the software described in this document can be officially supported. -Build Host ----------- +Getting the TF-A Source +----------------------- -|TF-A| can be compiled on both Linux and Windows-based machines. -However, we strongly recommend using a UNIX-compatible build environment. +Source code for |TF-A| is maintained in a Git repository hosted on +`TrustedFirmware.org`_. To clone this repository from the server, run the following +in your shell: -Testing is performed using Ubuntu 22.04 LTS (64-bit), but other distributions -should also work, provided the necessary tools and libraries are installed. +.. code:: shell -.. _prerequisites_toolchain: + git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" + + +Requirements +------------ + +======================== ===================== + Program Min supported version +======================== ===================== +Arm Compiler 6.18 +Arm GNU Compiler 13.2 +Clang/LLVM 11.0.0 +Device Tree Compiler 1.4.7 +GNU make 3.81 +mbed TLS\ [#f1]_ 3.4.1 +Node.js [#f2]_ 16 +OpenSSL 1.0.0 +Poetry [#f2]_ 1.3.2 +QCBOR\ [#f3]_ 1.2 +Sphinx\ [#f2]_ 2.4.4 +======================== ===================== + +.. [#f1] Required for Trusted Board Boot and Measured Boot. +.. [#f2] Required only for building TF-A documentation. +.. [#f3] Required only when enabling DICE Protection Environment support. Toolchain ---------- +^^^^^^^^^ -|TF-A| can be built with any of the following *cross-compiler* toolchains that -target the Armv7-A or Armv8-A architectures: +|TF-A| can be compiled using any cross-compiler toolchain specified in the +preceding table that target Armv7-A or Armv8-A. For AArch32 and +AArch64 builds, the respective targets required are ``arm-none-eabi`` and +``aarch64-none-elf``. -- TF-A has been tested with version 13.2.Rel1 (gcc 13.2) from the `Arm Developer website`_ +Testing has been performed with version 13.2.Rel1 (gcc 13.2) of the Arm +GNU compiler, which can be installed from the `Arm Developer website`_. - You will need the targets ``arm-none-eabi`` and ``aarch64-none-elf`` for - AArch32 and AArch64 builds respectively. - -- Clang == 14.0.0 -- Arm Compiler == 6.18 - -In addition, a native compiler is required to build the supporting tools. +In addition, a native compiler is required to build supporting tools. .. note:: Versions greater than the ones specified are likely but not guaranteed to @@ -45,74 +66,63 @@ In addition, a native compiler is required to build the supporting tools. For instructions on how to select the cross compiler refer to :ref:`Performing an Initial Build`. +OpenSSL +^^^^^^^ + +OpenSSL is required to build the cert_create, encrypt_fw, and fiptool tools. + +If using OpenSSL 3, older Linux versions may require it to be built from +source code, as it may not be available in the default package repositories. +Please refer to the OpenSSL project documentation for more information. + +.. warning:: + Versions 1.0.x and from v3.0.0 up to v3.0.6 are strongly advised against due + to concerns regarding security vulnerabilities! + +Device Tree Compiler (DTC) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Needed if you want to rebuild the provided Flattened Device Tree (FDT) +source files (``.dts`` files). DTC is available for Linux through the package +repositories of most distributions. + +Arm Development Studio (`Arm-DS`_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The standard software package used for debugging software on Arm development +platforms and |FVP| models. + +Node.js +^^^^^^^ + +Highly recommended, and necessary in order to install and use the packaged +Git hooks and helper tools. Without these tools you will need to rely on the +CI for feedback on commit message conformance. + +Poetry +^^^^^^ + +Required for managing Python dependencies, this will allow you to reliably +reproduce a Python environment to build documentation and run analysis tools. +Most importantly, it ensures your system environment will not be affected by +dependencies in the Python scripts. + .. _prerequisites_software_and_libraries: -Software and Libraries ----------------------- - -The following tools are required to obtain and build |TF-A|: - -- An appropriate toolchain (see :ref:`prerequisites_toolchain`) -- GNU Make -- Git - -The following libraries must be available to build one or more components or -supporting tools: - -- OpenSSL >= 1.0.0 (1.0.x, v3.0.0 to v3.0.6 highly discouraged due to security issues) - - Required to build the cert_create, encrypt_fw, and fiptool tools. - - .. note:: - - If using OpenSSL 3, older Linux versions may require it to be built from - source code, as it may not be available in the default package repositories. - Please refer to the OpenSSL project documentation for more information. - -The following libraries are required for Trusted Board Boot and Measured Boot -support: - -- mbed TLS == 3.4.1 (tag: ``mbedtls-3.4.1``) - -The following libraries are required for DICE Protection Environment support: - -- QCBOR == 1.2 (tag: ``v1.2``) - -These tools are optional: - -- Device Tree Compiler (DTC) >= 1.4.7 - - Needed if you want to rebuild the provided Flattened Device Tree (FDT) - source files (``.dts`` files). DTC is available for Linux through the package - repositories of most distributions. - -- Arm `Development Studio (Arm-DS)`_ - - The standard software package used for debugging software on Arm development - platforms and |FVP| models. - -- Node.js >= 16 - - Highly recommended, and necessary in order to install and use the packaged - Git hooks and helper tools. Without these tools you will need to rely on the - CI for feedback on commit message conformance. - -- Poetry >= 1.3.2 - - Required for managing Python dependencies, this will allow you to reliably - reproduce a Python environment to build documentation and run analysis tools. - Most importantly, it ensures your system environment will not be affected by - dependencies in the Python scripts. - Package Installation (Linux) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- -If you are using the recommended Ubuntu distribution then you can install the -required packages with the following command: +|TF-A| can be compiled on both Linux and Windows-based machines. +However, we strongly recommend using a UNIX-compatible build environment. + +Testing is performed using Ubuntu 22.04 LTS (64-bit), but other distributions +should also work, provided the necessary tools and libraries are installed. + +The following are steps to install the required packages: .. code:: shell - sudo apt install build-essential git + sudo apt install build-essential The optional packages can be installed using: @@ -141,17 +151,6 @@ instructions in :ref:`Performing an Initial Build`. .. _prerequisites_get_source: -Getting the TF-A Source ------------------------ - -Source code for |TF-A| is maintained in a Git repository hosted on -TrustedFirmware.org. To clone this repository from the server, run the following -in your shell: - -.. code:: shell - - git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" - Additional Steps for Contributors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -189,5 +188,6 @@ documentation, available `here `_. .. _Gerrit Code Review: https://www.gerritcodereview.com/ .. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes .. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables -.. _Development Studio (Arm-DS): https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio +.. _Arm-DS: https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio .. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01 +.. _TrustedFirmware.org: https://www.trustedfirmware.org/