doc: Split the User Guide into multiple files
The User Guide document has grown organically over time and
now covers a wide range of topics, making it difficult to
skim read and extract information from. Currently, it covers
these topics and maybe a couple more:
- Requirements (hardware, tools, libs)
- Checking out the repo
- Basic build instructions
- A comprehensive list of build flags
- FIP packaging
- Building specifically for Juno
- Firmware update images
- EL3 payloads
- Preloaded BL33 boot flow
- Running on FVPs
- Running on Juno
I have separated these out into a few groups that become new
documents. Broadly speaking, build instructions for the tools,
for TF-A generally, and for specific scenarios are separated.
Content relating to specific platforms (Juno and the FVPs are
Arm-specific platforms, essentially) has been moved into the
documentation that is specific to those platforms, under
docs/plat/arm.
Change-Id: Ica87c52d8cd4f577332be0b0738998ea3ba3bbec
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
diff --git a/docs/design/alt-boot-flows.rst b/docs/design/alt-boot-flows.rst
new file mode 100644
index 0000000..b44c061
--- /dev/null
+++ b/docs/design/alt-boot-flows.rst
@@ -0,0 +1,84 @@
+Alternative Boot Flows
+======================
+
+EL3 payloads alternative boot flow
+----------------------------------
+
+On a pre-production system, the ability to execute arbitrary, bare-metal code at
+the highest exception level is required. It allows full, direct access to the
+hardware, for example to run silicon soak tests.
+
+Although it is possible to implement some baremetal secure firmware from
+scratch, this is a complex task on some platforms, depending on the level of
+configuration required to put the system in the expected state.
+
+Rather than booting a baremetal application, a possible compromise is to boot
+``EL3 payloads`` through TF-A instead. This is implemented as an alternative
+boot flow, where a modified BL2 boots an EL3 payload, instead of loading the
+other BL images and passing control to BL31. It reduces the complexity of
+developing EL3 baremetal code by:
+
+- putting the system into a known architectural state;
+- taking care of platform secure world initialization;
+- loading the SCP_BL2 image if required by the platform.
+
+When booting an EL3 payload on Arm standard platforms, the configuration of the
+TrustZone controller is simplified such that only region 0 is enabled and is
+configured to permit secure access only. This gives full access to the whole
+DRAM to the EL3 payload.
+
+The system is left in the same state as when entering BL31 in the default boot
+flow. In particular:
+
+- Running in EL3;
+- Current state is AArch64;
+- Little-endian data access;
+- All exceptions disabled;
+- MMU disabled;
+- Caches disabled.
+
+.. _alt_boot_flows_el3_payload:
+
+Booting an EL3 payload
+~~~~~~~~~~~~~~~~~~~~~~
+
+The EL3 payload image is a standalone image and is not part of the FIP. It is
+not loaded by TF-A. Therefore, there are 2 possible scenarios:
+
+- The EL3 payload may reside in non-volatile memory (NVM) and execute in
+ place. In this case, booting it is just a matter of specifying the right
+ address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A.
+
+- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
+ run-time.
+
+To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be
+used. The infinite loop that it introduces in BL1 stops execution at the right
+moment for a debugger to take control of the target and load the payload (for
+example, over JTAG).
+
+It is expected that this loading method will work in most cases, as a debugger
+connection is usually available in a pre-production system. The user is free to
+use any other platform-specific mechanism to load the EL3 payload, though.
+
+
+Preloaded BL33 alternative boot flow
+------------------------------------
+
+Some platforms have the ability to preload BL33 into memory instead of relying
+on TF-A to load it. This may simplify packaging of the normal world code and
+improve performance in a development environment. When secure world cold boot
+is complete, TF-A simply jumps to a BL33 base address provided at build time.
+
+For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
+used when compiling TF-A. For example, the following command will create a FIP
+without a BL33 and prepare to jump to a BL33 image loaded at address
+0x80000000:
+
+.. code:: shell
+
+ make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 4958fc0..eb0a366 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -597,7 +597,7 @@
is not necessary for AArch32 SPs.
Details on BL32 initialization and the SPD's role are described in the
-"Secure-EL1 Payloads and Dispatchers" section below.
+:ref:`firmware_design_sel1_spd` section below.
BL33 (Non-trusted Firmware) execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -868,7 +868,7 @@
TF-A provides a Test Secure-EL1 Payload (TSP) and its associated Dispatcher
(TSPD). Details of SPD design and TSP/TSPD operation are described in the
- "Secure-EL1 Payloads and Dispatchers" section below.
+ :ref:`firmware_design_sel1_spd` section below.
#. CPU implementation service
@@ -1875,10 +1875,7 @@
| MHU |
0x04000000 +----------+
-Library at ROM
----------------
-
-Please refer to the :ref:`Library at ROM` document.
+.. _firmware_design_fip:
Firmware Image Package (FIP)
----------------------------
@@ -2543,7 +2540,7 @@
targets the base Armv8.0-A architecture; i.e. as if ``ARM_ARCH_MAJOR`` == 8
and ``ARM_ARCH_MINOR`` == 0, which are also their respective default values.
-See also the *Summary of build options* in :ref:`User Guide`.
+.. seealso:: :ref:`Build Options`
For details on the Architecture Extension and available features, please refer
to the respective Architecture Extension Supplement.
diff --git a/docs/design/index.rst b/docs/design/index.rst
index a51a4eb..e3b8f74 100644
--- a/docs/design/index.rst
+++ b/docs/design/index.rst
@@ -6,6 +6,7 @@
:caption: Contents
:numbered:
+ alt-boot-flows
auth-framework
cpu-specific-build-macros
firmware-design
@@ -13,3 +14,8 @@
psci-pd-tree
reset-design
trusted-board-boot
+ trusted-board-boot-build
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst
index a92ceeb..7b10c95 100644
--- a/docs/design/reset-design.rst
+++ b/docs/design/reset-design.rst
@@ -115,8 +115,8 @@
It allows the Arm FVP port to support the ``RESET_TO_BL31`` configuration, in
which case the ``bl31.bin`` image must be loaded to its run address in Trusted
SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run
-address. See the :ref:`User Guide` for details of running the FVP models in this
-way.
+address. See the :ref:`Arm Fixed Virtual Platforms (FVP)` for details of running
+the FVP models in this way.
Although technically it would be possible to program the reset base address with
the right support in the SCP firmware, this is currently not implemented so the
diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst
new file mode 100644
index 0000000..2025243
--- /dev/null
+++ b/docs/design/trusted-board-boot-build.rst
@@ -0,0 +1,114 @@
+Building FIP images with support for Trusted Board Boot
+=======================================================
+
+Trusted Board Boot primarily consists of the following two features:
+
+- Image Authentication, described in :ref:`Trusted Board Boot`, and
+- Firmware Update, described in :ref:`Firmware Update (FWU)`
+
+The following steps should be followed to build FIP and (optionally) FWU_FIP
+images with support for these features:
+
+#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
+ modules by checking out a recent version of the `mbed TLS Repository`_. It
+ is important to use a version that is compatible with TF-A and fixes any
+ known security vulnerabilities. See `mbed TLS Security Center`_ for more
+ information. See the :ref:`Prerequisites` document for the appropriate
+ version of mbed TLS to use.
+
+ The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
+ source files the modules depend upon.
+ ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
+ options required to build the mbed TLS sources.
+
+ Note that the mbed TLS library is licensed under the Apache version 2.0
+ license. Using mbed TLS source code will affect the licensing of TF-A
+ binaries that are built using this library.
+
+#. To build the FIP image, ensure the following command line variables are set
+ while invoking ``make`` to build TF-A:
+
+ - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
+ - ``TRUSTED_BOARD_BOOT=1``
+ - ``GENERATE_COT=1``
+
+ In the case of Arm platforms, the location of the ROTPK hash must also be
+ specified at build time. Two locations are currently supported (see
+ ``ARM_ROTPK_LOCATION`` build option):
+
+ - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
+ root-key storage registers present in the platform. On Juno, this
+ registers are read-only. On FVP Base and Cortex models, the registers
+ are read-only, but the value can be specified using the command line
+ option ``bp.trusted_key_storage.public_key`` when launching the model.
+ On both Juno and FVP models, the default value corresponds to an
+ ECDSA-SECP256R1 public key hash, whose private part is not currently
+ available.
+
+ - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
+ in the Arm platform port. The private/public RSA key pair may be
+ found in ``plat/arm/board/common/rotpk``.
+
+ - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded
+ in the Arm platform port. The private/public ECDSA key pair may be
+ found in ``plat/arm/board/common/rotpk``.
+
+ Example of command line using RSA development keys:
+
+ .. code:: shell
+
+ MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
+ make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
+ BL33=<path-to>/<bl33_image> \
+ all fip
+
+ The result of this build will be the bl1.bin and the fip.bin binaries. This
+ FIP will include the certificates corresponding to the Chain of Trust
+ described in the TBBR-client document. These certificates can also be found
+ in the output build directory.
+
+#. The optional FWU_FIP contains any additional images to be loaded from
+ Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the
+ FWU_FIP, any FWU images required by the platform must be specified on the
+ command line. On Arm development platforms like Juno, these are:
+
+ - NS_BL2U. The AP non-secure Firmware Updater image.
+ - SCP_BL2U. The SCP Firmware Update Configuration image.
+
+ Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
+ targets using RSA development:
+
+ ::
+
+ MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
+ make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
+ BL33=<path-to>/<bl33_image> \
+ SCP_BL2=<path-to>/<scp_bl2_image> \
+ SCP_BL2U=<path-to>/<scp_bl2u_image> \
+ NS_BL2U=<path-to>/<ns_bl2u_image> \
+ all fip fwu_fip
+
+ .. note::
+ The BL2U image will be built by default and added to the FWU_FIP.
+ The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+ to the command line above.
+
+ .. note::
+ Building and installing the non-secure and SCP FWU images (NS_BL1U,
+ NS_BL2U and SCP_BL2U) is outside the scope of this document.
+
+ The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
+ Both the FIP and FWU_FIP will include the certificates corresponding to the
+ Chain of Trust described in the TBBR-client document. These certificates
+ can also be found in the output build directory.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
+.. _mbed TLS Security Center: https://tls.mbed.org/security
diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index f3b1c36..49e8adb 100644
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -187,8 +187,8 @@
The Trusted Board Boot implementation spans both generic and platform-specific
BL1 and BL2 code, and in tool code on the host build machine. The feature is
-enabled through use of specific build flags as described in the
-:ref:`User Guide`.
+enabled through use of specific build flags as described in
+:ref:`Build Options`.
On the host machine, a tool generates the certificates, which are included in
the FIP along with the boot loader images. These certificates are loaded in
@@ -222,9 +222,12 @@
The certificates are also stored individually in the in the output build
directory.
-The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL
-library version 1.0.1 or later to generate the X.509 certificates. Instructions
-for building and using the tool can be found in the :ref:`User Guide`.
+The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL
+library version to generate the X.509 certificates. The specific version of the
+library that is required is given in the :ref:`Prerequisites` document.
+
+Instructions for building and using the tool can be found at
+:ref:`tools_build_cert_create`.
--------------