summaryrefslogtreecommitdiffstats
path: root/docs/getting_started/initial-build.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
commit102b0d2daa97dae68d3eed54d8fe37a9cc38a892 (patch)
treebcf648efac40ca6139842707f0eba5a4496a6dd2 /docs/getting_started/initial-build.rst
parentInitial commit. (diff)
downloadarm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.tar.xz
arm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.zip
Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--docs/getting_started/initial-build.rst118
1 files changed, 118 insertions, 0 deletions
diff --git a/docs/getting_started/initial-build.rst b/docs/getting_started/initial-build.rst
new file mode 100644
index 0000000..4f41be4
--- /dev/null
+++ b/docs/getting_started/initial-build.rst
@@ -0,0 +1,118 @@
+Performing an Initial Build
+===========================
+
+- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
+ to your cross compiler.
+
+ For AArch64:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+
+ For AArch32:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-none-eabi-
+
+ It is possible to build TF-A using Clang or Arm Compiler 6. To do so
+ ``CC`` needs to point to the clang or armclang binary, which will
+ also select the clang or armclang assembler. Arm Compiler 6 will be selected
+ when the base name of the path assigned to ``CC`` matches the string
+ 'armclang'. GNU binutils are required since the TF-A build system doesn't
+ currently support Arm Scatter files. Meaning the GNU linker is used by
+ default for Arm Compiler 6. Because of this dependency, ``CROSS_COMPILE``
+ should be set as described above.
+
+ For AArch64 using Arm Compiler 6:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+ make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
+
+ On the other hand, Clang uses LLVM linker (LLD) and other LLVM binutils by
+ default instead of GNU utilities (LLVM linker (LLD) 14.0.0 is known to
+ work with TF-A). ``CROSS_COMPILE`` need not be set for Clang. Please note,
+ that the default linker may be manually overridden using the ``LD`` variable.
+
+ Clang will be selected when the base name of the path assigned to ``CC``
+ contains the string 'clang'. This is to allow both clang and clang-X.Y
+ to work.
+
+ For AArch64 using clang:
+
+ .. code:: shell
+
+ make CC=<path-to-clang>/bin/clang PLAT=<platform> all
+
+- Change to the root directory of the TF-A source tree and build.
+
+ For AArch64:
+
+ .. code:: shell
+
+ make PLAT=<platform> all
+
+ For AArch32:
+
+ .. code:: shell
+
+ make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
+
+ Notes:
+
+ - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
+ :ref:`Build Options` document for more information on available build
+ options.
+
+ - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
+
+ - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
+ corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
+ provided by TF-A to demonstrate how PSCI Library can be integrated with
+ an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
+ include other runtime services, for example Trusted OS services. A guide
+ to integrate PSCI library with AArch32 EL3 Runtime Software can be found
+ at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
+
+ - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
+ image, is not compiled in by default. Refer to the
+ :ref:`Test Secure Payload (TSP) and Dispatcher (TSPD)` document for
+ details on building the TSP.
+
+ - By default this produces a release version of the build. To produce a
+ debug version instead, refer to the "Debugging options" section below.
+
+ - The build process creates products in a ``build`` directory tree, building
+ the objects and binaries for each boot loader stage in separate
+ sub-directories. The following boot loader binary files are created
+ from the corresponding ELF files:
+
+ - ``build/<platform>/<build-type>/bl1.bin``
+ - ``build/<platform>/<build-type>/bl2.bin``
+ - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
+ - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
+
+ where ``<platform>`` is the name of the chosen platform and ``<build-type>``
+ is either ``debug`` or ``release``. The actual number of images might differ
+ depending on the platform.
+
+- Build products for a specific build variant can be removed using:
+
+ .. code:: shell
+
+ make DEBUG=<D> PLAT=<platform> clean
+
+ ... where ``<D>`` is ``0`` or ``1``, as specified when building.
+
+ The build tree can be removed completely using:
+
+ .. code:: shell
+
+ make realclean
+
+--------------
+
+*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*