From b50838bae79953178c3fc856c0ee015cce94e3ec Mon Sep 17 00:00:00 2001 From: Boyan Karatotev Date: Thu, 27 Oct 2022 14:47:18 +0100 Subject: [PATCH] docs(build): clarify getting started section The Getting started section is very difficult to follow. Building the fip comes before building the files it needs, the BL33 requirement is given in a somewhat hand wavy way, and the Arm Developer website download provides a lot of targets and the guide is not clear which ones are needed on download. Swapping the initial build and supporting tools sections makes the flow more natural and the supporting tools section then becomes clear. Explicitly mentioning the GCC targets avoids confusion for people less familiar with the project (eg. new starters). Signed-off-by: Boyan Karatotev Change-Id: I02e88f8c279db6d8eda68f634e8473c02b733963 --- docs/getting_started/image-terminology.rst | 13 +++++++++++-- docs/getting_started/index.rst | 2 +- docs/getting_started/initial-build.rst | 2 +- docs/getting_started/prerequisites.rst | 4 ++++ docs/getting_started/tools-build.rst | 14 ++++++++------ 5 files changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst index a90ec0b3f..66f47e8ac 100644 --- a/docs/getting_started/image-terminology.rst +++ b/docs/getting_started/image-terminology.rst @@ -4,8 +4,8 @@ Image Terminology This page contains the current name, abbreviated name and purpose of the various images referred to in the Trusted Firmware project. -General Notes -------------- +Common Image Features +--------------------- - Some of the names and abbreviated names have changed to accommodate new requirements. The changed names are as backward compatible as possible to @@ -40,6 +40,15 @@ General Notes Trusted Firmware Images ----------------------- +Firmware Image Package: ``FIP`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a packaging format used by TF-A to package firmware images in a single +binary. The number and type of images that should be packed in a FIP is +platform-specific and may include TF-A images and other firmware images +required by the platform. For example, most platforms require a BL33 image +which corresponds to the normal world bootloader (e.g. UEFI or U-Boot). + AP Boot ROM: ``AP_BL1`` ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 817beaf8e..717130398 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -8,8 +8,8 @@ Getting Started prerequisites docs-build - tools-build initial-build + tools-build build-options image-terminology porting-guide diff --git a/docs/getting_started/initial-build.rst b/docs/getting_started/initial-build.rst index 62f1941b1..4f41be413 100644 --- a/docs/getting_started/initial-build.rst +++ b/docs/getting_started/initial-build.rst @@ -2,7 +2,7 @@ Performing an Initial Build =========================== - Before building TF-A, the environment variable ``CROSS_COMPILE`` must point - to the Linaro cross compiler. + to your cross compiler. For AArch64: diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst index 62ef8263e..7eabfa35e 100644 --- a/docs/getting_started/prerequisites.rst +++ b/docs/getting_started/prerequisites.rst @@ -27,6 +27,10 @@ Toolchain target the Armv7-A or Armv8-A architectures: - GCC >= 11.3.Rel1 (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 diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst index daf7e06a9..166b527d4 100644 --- a/docs/getting_started/tools-build.rst +++ b/docs/getting_started/tools-build.rst @@ -14,12 +14,11 @@ Building Supporting Tools Building and using the FIP tool ------------------------------- -Firmware Image Package (FIP) is a packaging format used by TF-A to package -firmware images in a single binary. The number and type of images that should -be packed in a FIP is platform specific and may include TF-A images and other -firmware images required by the platform. For example, most platforms require -a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or -U-Boot). +The following snippets build a :ref:`FIP` for the FVP +platform. While it is not an intrinsic part of the FIP format, a BL33 image is +required for these examples. For the purposes of experimentation, `Trusted +Firmware-A Tests`_ (`tftf.bin``) may be used. Refer to to the `TFTF +documentation`_ for instructions on building a TFTF binary. The TF-A build system provides the make target ``fip`` to create a FIP file for the specified platform using the FIP creation tool included in the TF-A @@ -175,3 +174,6 @@ via using ``cat `` instead of a hex string. -------------- *Copyright (c) 2019-2022, Arm Limited. All rights reserved.* + +.. _Trusted Firmware-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/ +.. _TFTF documentation: https://trustedfirmware-a-tests.readthedocs.io/en/latest/ -- 2.39.5