diff options
Diffstat (limited to 'docs/getting_started/user-guide.rst')
| -rw-r--r-- | docs/getting_started/user-guide.rst | 149 |
1 files changed, 86 insertions, 63 deletions
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index 42040275f..606546447 100644 --- a/docs/getting_started/user-guide.rst +++ b/docs/getting_started/user-guide.rst @@ -96,9 +96,10 @@ targets which both utilise the `checkpatch.pl` script that ships with the Linux source tree. The project also defines certain *checkpatch* options in the ``.checkpatch.conf`` file in the top-level directory. -**Note:** Checkpatch errors will gate upstream merging of pull requests. -Checkpatch warnings will not gate merging but should be reviewed and fixed if -possible. +.. note:: + Checkpatch errors will gate upstream merging of pull requests. + Checkpatch warnings will not gate merging but should be reviewed and fixed if + possible. To check the entire source tree, you must first download copies of ``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available @@ -718,8 +719,9 @@ Common build options of certificates in the FIP and FWU_FIP depends upon the value of the ``GENERATE_COT`` option. - Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys - already exist in disk, they will be overwritten without further notice. + .. warning:: + This option depends on ``CREATE_KEYS`` to be enabled. If the keys + already exist in disk, they will be overwritten without further notice. - ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the file that contains the Trusted World private key in PEM @@ -739,8 +741,9 @@ Common build options interrupts to TSP allowing it to save its context and hand over synchronously to EL3 via an SMC. - Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` - must also be set to ``1``. + .. note:: + When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` + must also be set to ``1``. - ``USE_ARM_LINK``: This flag determines whether to enable support for ARM linker. When the ``LINKER`` build variable points to the armlink linker, @@ -948,9 +951,10 @@ version to 2 is recommended for DS-5 versions older than 5.16. When debugging logic problems it might also be useful to disable all compiler optimizations by using ``-O0``. -NOTE: Using ``-O0`` could cause output images to be larger and base addresses -might need to be recalculated (see the **Memory layout on Arm development -platforms** section in the `Firmware Design`_). +.. warning:: + Using ``-O0`` could cause output images to be larger and base addresses + might need to be recalculated (see the **Memory layout on Arm development + platforms** section in the `Firmware Design`_). Extra debug options can be passed to the build system by setting ``CFLAGS`` or ``LDFLAGS``: @@ -1205,12 +1209,14 @@ images with support for these features: 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:: + 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. + .. 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 @@ -1252,21 +1258,26 @@ This section provides Juno and FVP specific instructions to build Trusted Firmware, obtain the additional required firmware, and pack it all together in a single FIP binary. It assumes that a `Linaro Release`_ has been installed. -Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12 -onwards. Before that release, pre-built binaries are only available for AArch64. +.. note:: + Pre-built binaries for AArch32 are available from Linaro Release 16.12 + onwards. Before that release, pre-built binaries are only available for + AArch64. -Note: Follow the full instructions for one platform before switching to a -different one. Mixing instructions for different platforms may result in -corrupted binaries. +.. warning:: + Follow the full instructions for one platform before switching to a + different one. Mixing instructions for different platforms may result in + corrupted binaries. -Note: The uboot image downloaded by the Linaro workspace script does not always -match the uboot image packaged as BL33 in the corresponding fip file. It is -recommended to use the version that is packaged in the fip file using the -instructions below. +.. warning:: + The uboot image downloaded by the Linaro workspace script does not always + match the uboot image packaged as BL33 in the corresponding fip file. It is + recommended to use the version that is packaged in the fip file using the + instructions below. -Note: For the FVP, the kernel FDT is packaged in FIP during build and loaded -by the firmware at runtime. See `Obtaining the Flattened Device Trees`_ -section for more info on selecting the right FDT to use. +.. note:: + For the FVP, the kernel FDT is packaged in FIP during build and loaded + by the firmware at runtime. See `Obtaining the Flattened Device Trees`_ + section for more info on selecting the right FDT to use. #. Clean the working directory @@ -1291,12 +1302,14 @@ section for more info on selecting the right FDT to use. current working directory. The SCP_BL2 image corresponds to ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``. - Note: The fiptool will complain if the images to be unpacked already - exist in the current directory. If that is the case, either delete those - files or use the ``--force`` option to overwrite. + .. note:: + The fiptool will complain if the images to be unpacked already + exist in the current directory. If that is the case, either delete those + files or use the ``--force`` option to overwrite. - Note: For AArch32, the instructions below assume that nt-fw.bin is a normal - world boot loader that supports AArch32. + .. note:: + For AArch32, the instructions below assume that nt-fw.bin is a + normal world boot loader that supports AArch32. #. Build TF-A images and create a new FIP for FVP @@ -1662,7 +1675,8 @@ The latest version of the AArch64 build of TF-A has been tested on the following Arm FVPs without shifted affinities, and that do not support threaded CPU cores (64-bit host machine only). -The FVP models used are Version 11.6 Build 45, unless otherwise stated. +.. note:: + The FVP models used are Version 11.6 Build 45, unless otherwise stated. - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` @@ -1699,30 +1713,36 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_Cortex-A32x4`` -NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which -is not compatible with legacy GIC configurations. Therefore this FVP does not -support these legacy GIC configurations. - -NOTE: The build numbers quoted above are those reported by launching the FVP -with the ``--version`` parameter. - -NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full -file systems that can be downloaded separately. To run an FVP with a virtio -file system image an additional FVP configuration option -``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be -used. - -NOTE: The software will not work on Version 1.0 of the Foundation FVP. -The commands below would report an ``unhandled argument`` error in this case. - -NOTE: FVPs can be launched with ``--cadi-server`` option such that a -CADI-compliant debugger (for example, Arm DS-5) can connect to and control its -execution. - -NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 -the internal synchronisation timings changed compared to older versions of the -models. The models can be launched with ``-Q 100`` option if they are required -to match the run time characteristics of the older versions. +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which + is not compatible with legacy GIC configurations. Therefore this FVP does not + support these legacy GIC configurations. + +.. note:: + The build numbers quoted above are those reported by launching the FVP + with the ``--version`` parameter. + +.. note:: + Linaro provides a ramdisk image in prebuilt FVP configurations and full + file systems that can be downloaded separately. To run an FVP with a virtio + file system image an additional FVP configuration option + ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be + used. + +.. note:: + The software will not work on Version 1.0 of the Foundation FVP. + The commands below would report an ``unhandled argument`` error in this case. + +.. note:: + FVPs can be launched with ``--cadi-server`` option such that a + CADI-compliant debugger (for example, Arm DS-5) can connect to and control + its execution. + +.. warning:: + Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 + the internal synchronisation timings changed compared to older versions of + the models. The models can be launched with ``-Q 100`` option if they are + required to match the run time characteristics of the older versions. The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be downloaded for free from `Arm's website`_. @@ -1743,8 +1763,9 @@ be found in the TF-A source directory under ``fdts/``. The Foundation FVP has a subset of the Base FVP components. For example, the Foundation FVP lacks CLCD and MMC support, and has only one CPU cluster. -Note: It is not recommended to use the FDTs built along the kernel because not -all FDTs are available from there. +.. note:: + It is not recommended to use the FDTs built along the kernel because not + all FDTs are available from there. The dynamic configuration capability is enabled in the firmware for FVPs. This means that the firmware can authenticate and load the FDT if present in @@ -1851,8 +1872,9 @@ with 8 CPUs using the AArch64 build of TF-A. --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 -Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a -specific DTS for all the CPUs to be loaded. +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires + a specific DTS for all the CPUs to be loaded. Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2010,8 +2032,9 @@ with 8 CPUs using the AArch32 build of TF-A. --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 -Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``. -It should match the address programmed into the RVBAR register as well. +.. note:: + The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``. + It should match the address programmed into the RVBAR register as well. Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |