diff options
Diffstat (limited to 'docs/user-guide.md')
| -rw-r--r-- | docs/user-guide.md | 154 |
1 files changed, 115 insertions, 39 deletions
diff --git a/docs/user-guide.md b/docs/user-guide.md index 3337f88d..767fc42a 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -413,6 +413,25 @@ performed. any register that is not part of the SBSA generic UART specification. Default value is 0 (a full PL011 compliant UART is present). +* `CTX_INCLUDE_FPREGS`: Boolean option that, when set to 1, will cause the FP + registers to be included when saving and restoring the CPU context. Default + is 0. + +* `DISABLE_PEDANTIC`: When set to 1 it will disable the -pedantic option in + the GCC command line. Default is 0. + +* `BUILD_STRING`: Input string for VERSION_STRING, which allows the TF build + to be uniquely identified. Defaults to the current git commit id. + +* `VERSION_STRING`: String used in the log output for each TF image. Defaults + to a string formed by concatenating the version number, build type and build + string. + +* `BUILD_MESSAGE_TIMESTAMP`: String used to identify the time and date of the + compilation of each build. It must be set to a C string (including quotes + where applicable). Defaults to a string that contains the time and date of + the compilation. + #### ARM development platform specific build options * `ARM_TSP_RAM_LOCATION`: location of the TSP binary. Options: @@ -456,6 +475,12 @@ map is explained in the [Firmware Design]. Trusted Watchdog may be disabled at build time for testing or development purposes. +* `ARM_CONFIG_CNTACR`: boolean option to unlock access to the CNTBase<N> + frame registers by setting the CNTCTLBase.CNTACR<N> register bits. The + frame number <N> is defined by 'PLAT_ARM_NSTIMER_FRAME_ID', which should + match the frame used by the Non-Secure image (normally the Linux kernel). + Default is true (access to the frame is allowed). + #### ARM CSS platform specific build options * `CSS_DETECT_PRE_1_7_0_SCP`: Boolean flag to detect SCP version @@ -465,6 +490,10 @@ map is explained in the [Firmware Design]. set to 1 then Trusted Firmware will detect if an earlier version is in use. Default is 1. +* `CSS_LOAD_SCP_IMAGES`: Boolean flag, which when set, adds SCP_BL2 and + SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded + during boot. Default is 1. + #### ARM FVP platform specific build options * `FVP_USE_GIC_DRIVER` : Selects the GIC driver to be built. Options: @@ -853,6 +882,84 @@ flow. In particular: * MMU disabled; * Caches disabled. +### Booting an EL3 payload + +The EL3 payload image is a standalone image and is not part of the FIP. It is +not loaded by the Trusted Firmware. 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 the TF. + +* 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. + +#### Booting an EL3 payload on FVP + +The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for +the secondary CPUs holding pen to work properly. Unfortunately, its reset value +is undefined on the FVP platform and the FVP platform code doesn't clear it. +Therefore, one must modify the way the model is normally invoked in order to +clear the mailbox at start-up. + +One way to do that is to create an 8-byte file containing all zero bytes using +the following command: + + dd if=/dev/zero of=mailbox.dat bs=1 count=8 + +and pre-load it into the FVP memory at the mailbox address (i.e. `0x04000000`) +using the following model parameters: + + --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs] + --data=mailbox.dat@0x04000000 [Foundation FVP] + +To provide the model with the EL3 payload image, the following methods may be +used: + +1. If the EL3 payload is able to execute in place, it may be programmed into + flash memory. On Base Cortex and AEM FVPs, the following model parameter + loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already + used for the FIP): + + -C bp.flashloader1.fname="/path/to/el3-payload" + + On Foundation FVP, there is no flash loader component and the EL3 payload + may be programmed anywhere in flash using method 3 below. + +2. When using the `SPIN_ON_BL1_EXIT=1` loading method, the following DS-5 + command may be used to load the EL3 payload ELF image over JTAG: + + load /path/to/el3-payload.elf + +3. The EL3 payload may be pre-loaded in volatile memory using the following + model parameters: + + --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs] + --data="/path/to/el3-payload"@address [Foundation FVP] + + The address provided to the FVP must match the `EL3_PAYLOAD_BASE` address + used when building the Trusted Firmware. + +#### Booting an EL3 payload on Juno + +If the EL3 payload is able to execute in place, it may be programmed in flash +memory by adding an entry in the `SITE1/HBI0262x/images.txt` configuration file +on the Juno SD card (where `x` depends on the revision of the Juno board). +Refer to the [Juno Getting Started Guide], section 2.3 "Flash memory +programming" for more information. + +Alternatively, the same DS-5 command mentioned in the FVP section above can +be used to load the EL3 payload's ELF file over JTAG on Juno. + 8. Preparing the images to run on FVP -------------------------------------- @@ -913,14 +1020,15 @@ which the FVP is launched. Alternatively a symbolic link may be used. This version of the ARM Trusted Firmware has been tested on the following ARM FVPs (64-bit versions only). -* `Foundation_Platform` (Version 9.4, Build 9.4.59) -* `FVP_Base_AEMv8A-AEMv8A` (Version 7.0, Build 0.8.7004) -* `FVP_Base_Cortex-A57x4-A53x4` (Version 7.0, Build 0.8.7004) -* `FVP_Base_Cortex-A57x1-A53x1` (Version 7.0, Build 0.8.7004) -* `FVP_Base_Cortex-A57x2-A53x4` (Version 7.0, Build 0.8.7004) +* `Foundation_Platform` (Version 9.5, Build 9.5.40) +* `FVP_Base_AEMv8A-AEMv8A` (Version 7.2, Build 0.8.7202) +* `FVP_Base_Cortex-A57x4-A53x4` (Version 7.2, Build 0.8.7202) +* `FVP_Base_Cortex-A57x1-A53x1` (Version 7.2, Build 0.8.7202) +* `FVP_Base_Cortex-A57x2-A53x4` (Version 7.2, Build 0.8.7202) NOTE: The build numbers quoted above are those reported by launching the FVP -with the `--version` parameter. +with the `--version` parameter. `Foundation_Platform` tarball for `--version` +9.5.40 is labeled as version 9.5.41. 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. @@ -1205,38 +1313,6 @@ The `bp.variant` parameter corresponds to the build variant field of the `SYS_ID` register. Setting this to `0x0` allows the ARM Trusted Firmware to detect the legacy VE memory map while configuring the GIC. -### Booting an EL3 payload on FVP - -Booting an EL3 payload on FVP requires a couple of changes to the way the -model is normally invoked. - -First of all, the EL3 payload image is not part of the FIP and is not loaded by -the Trusted Firmware. Therefore, it must be loaded in memory some other way. -There are 2 ways of doing that: - -1. It can be loaded over JTAG at the appropriate time. The infinite loop - introduced in BL1 when compiling the Trusted Firmware with - `SPIN_ON_BL1_EXIT=1` stops execution at the right moment for a debugger to - take control of the target and load the payload. - -2. It can be pre-loaded in the FVP memory using the following model parameter: - - --data="<path-to-binary>"@<base-address-of-binary> - - The base address provided to the FVP must match the `EL3_PAYLOAD_BASE` - address used when building the Trusted Firmware. - -Secondly, the EL3 payloads boot flow requires the CPUs mailbox to be cleared -at reset for the secondary CPUs holding pen to work properly. Unfortunately, -its reset value is undefined on FVP. One way to clear it is to create an -8-byte file containing all zero bytes and pre-load it into the FVP memory at the -mailbox address (i.e. `0x04000000`) using the same `--data` FVP parameter as -described above. - -The following command creates such a file called `mailbox.dat`: - - dd if=/dev/zero of=mailbox.dat bs=1 count=8 - 10. Running the software on Juno --------------------------------- @@ -1338,7 +1414,7 @@ used to test the GICv3 kernel on the respective FVP models. - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._ +_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ [Firmware Design]: firmware-design.md |