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 <boyan.karatotev@arm.com>
Change-Id: I02e88f8c279db6d8eda68f634e8473c02b733963

diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst
index a90ec0b3fd8d1291ed9060e85f1b142800f3dd9d..66f47e8ac39ce2731c7a3233fc938a849c29ba94 100644 (file)
--- 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 817beaf8e04c161dfecdcddc9efaca8ce7a9e8bf..7171303989fcfef60a2d1bc2b23f15953c41c6dd 100644 (file)
--- 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 62f1941b13615dad347fe307eda89e959bb133f2..4f41be413410f4b1c2f37b8bcf22fce7c0b1d087 100644 (file)
--- 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 62ef8263ebfb2c48aceb3024778fdd1e57360269..7eabfa35e4cfe9c2b63628d3c5d8b8680ad8badb 100644 (file)
--- 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 daf7e06a9fb388db5d1aadbe4e81deb87972c819..166b527d41ca75d72886df0e9add926f892003a7 100644 (file)
--- 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<Image Terminology>` 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 <filename>`` 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/