diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cpu-specific-build-macros.md | 23 | ||||
| -rw-r--r-- | docs/firmware-design.md | 110 | ||||
| -rw-r--r-- | docs/porting-guide.md | 22 | ||||
| -rw-r--r-- | docs/user-guide.md | 153 |
4 files changed, 257 insertions, 51 deletions
diff --git a/docs/cpu-specific-build-macros.md b/docs/cpu-specific-build-macros.md index d9b7108c..c57dc7ee 100644 --- a/docs/cpu-specific-build-macros.md +++ b/docs/cpu-specific-build-macros.md @@ -26,8 +26,8 @@ by ARM. The errata workarounds are implemented for a particular revision or a set of processor revisions. This is checked by reset handler at runtime. Each errata workaround is identified by its `ID` as specified in the processor's errata notice document. The format of the define used to enable/disable the -errata is `ERRATA_<Processor name>_<ID>` where the `Processor name` -is either `A57` for the `Cortex_A57` CPU or `A53` for `Cortex_A53` CPU. +errata workaround is `ERRATA_<Processor name>_<ID>`, where the `Processor name` +is for example `A57` for the `Cortex_A57` CPU. All workarounds are disabled by default. The platform is reponsible for enabling these workarounds according to its requirement by defining the @@ -74,6 +74,23 @@ architecture that can be enabled by the platform as desired. sequence. Each Cortex-A57 based platform must make its own decision on whether to use the optimization. +* `A53_DISABLE_NON_TEMPORAL_HINT`: This flag disables the cache non-temporal + hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave + in a way most programmers expect, and will most probably result in a + significant speed degradation to any code that employs them. The ARMv8-A + architecture (see ARM DDI 0487A.h, section D3.4.3) allows cores to ignore + the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this + flag enforces this behaviour. This needs to be enabled only for revisions + <= r0p3 of the CPU and is enabled by default. + +* `A57_DISABLE_NON_TEMPORAL_HINT`: This flag has the same behaviour as + `A53_DISABLE_NON_TEMPORAL_HINT` but for Cortex-A57. This needs to be + enabled only for revisions <= r1p2 of the CPU and is enabled by default, + as recommended in section "4.7 Non-Temporal Loads/Stores" of the + [Cortex-A57 Software Optimization Guide][A57 SW Optimization Guide]. + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._ +_Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved._ + +[A57 SW Optimization Guide]: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf diff --git a/docs/firmware-design.md b/docs/firmware-design.md index d0cb3994..cd8c7aaa 100644 --- a/docs/firmware-design.md +++ b/docs/firmware-design.md @@ -1194,6 +1194,72 @@ Additionally, if the platform memory layout implies some image overlaying like on FVP, BL31 and TSP need to know the limit address that their PROGBITS sections must not overstep. The platform code must provide those. +Trusted Firmware provides a mechanism to verify at boot time that the memory +to load a new image is free to prevent overwriting a previously loaded image. +For this mechanism to work, the platform must specify the memory available in +the system as regions, where each region consists of base address, total size +and the free area within it (as defined in the `meminfo_t` structure). Trusted +Firmware retrieves these memory regions by calling the corresponding platform +API: + +* `meminfo_t *bl1_plat_sec_mem_layout(void)` +* `meminfo_t *bl2_plat_sec_mem_layout(void)` +* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)` +* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)` +* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)` + +For example, in the case of BL1 loading BL2, `bl1_plat_sec_mem_layout()` will +return the region defined by the platform where BL1 intends to load BL2. The +`load_image()` function will check that the memory where BL2 will be loaded is +within the specified region and marked as free. + +The actual number of regions and their base addresses and sizes is platform +specific. The platform may return the same region or define a different one for +each API. However, the overlap verification mechanism applies only to a single +region. Hence, it is the platform responsibility to guarantee that different +regions do not overlap, or that if they do, the overlapping images are not +accessed at the same time. This could be used, for example, to load temporary +images (e.g. certificates) or firmware images prior to being transfered to its +corresponding processor (e.g. the SCP BL2 image). + +To reduce fragmentation and simplify the tracking of free memory, all the free +memory within a region is always located in one single buffer defined by its +base address and size. Trusted Firmware implements a top/bottom load approach: +after a new image is loaded, it checks how much memory remains free above and +below the image. The smallest area is marked as unavailable, while the larger +area becomes the new free memory buffer. Platforms should take this behaviour +into account when defining the base address for each of the images. For example, +if an image is loaded near the middle of the region, small changes in image size +could cause a flip between a top load and a bottom load, which may result in an +unexpected memory layout. + +The following diagram is an example of an image loaded in the bottom part of +the memory region. The region is initially free (nothing has been loaded yet): + + Memory region + +----------+ + | | + | | <<<<<<<<<<<<< Free + | | + |----------| +------------+ + | image | <<<<<<<<<<<<< | image | + |----------| +------------+ + | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable + +----------+ + +And the following diagram is an example of an image loaded in the top part: + + Memory region + +----------+ + | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable + |----------| +------------+ + | image | <<<<<<<<<<<<< | image | + |----------| +------------+ + | | + | | <<<<<<<<<<<<< Free + | | + +----------+ + #### Memory layout on ARM development platforms @@ -1229,9 +1295,47 @@ The following list describes the memory layout on the ARM development platforms: * Secure region of DRAM (top 16MB of DRAM configured by the TrustZone controller) -When BL32 is loaded into Trusted SRAM, its NOBITS sections are allowed to -overlay BL2. This memory layout is designed to give the BL32 image as much -memory as possible when it is loaded into Trusted SRAM. + When BL32 is loaded into Trusted SRAM, its NOBITS sections are allowed to + overlay BL2. This memory layout is designed to give the BL32 image as much + memory as possible when it is loaded into Trusted SRAM. + +The memory regions for the overlap detection mechanism at boot time are +defined as follows (shown per API): + +* `meminfo_t *bl1_plat_sec_mem_layout(void)` + + This region corresponds to the whole Trusted SRAM except for the shared + memory at the base. This region is initially free. At boot time, BL1 will + mark the BL1(rw) section within this region as occupied. The BL1(rw) section + is placed at the top of Trusted SRAM. + +* `meminfo_t *bl2_plat_sec_mem_layout(void)` + + This region corresponds to the whole Trusted SRAM as defined by + `bl1_plat_sec_mem_layout()`, but with the BL1(rw) section marked as + occupied. This memory region is used to check that BL2 and BL31 do not + overlap with each other. BL2_BASE and BL1_RW_BASE are carefully chosen so + that the memory for BL31 is top loaded above BL2. + +* `void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)` + + This region is an exact copy of the region defined by + `bl2_plat_sec_mem_layout()`. Being a disconnected copy means that all the + changes made to this region by the Trusted Firmware will not be propagated. + This approach is valid because the SCP BL2 image is loaded temporarily + while it is being transferred to the SCP, so this memory is reused + afterwards. + +* `void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)` + + This region depends on the location of the BL32 image. Currently, ARM + platforms support three different locations (detailed below): Trusted SRAM, + Trusted DRAM and the TZC-Secured DRAM. + +* `void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)` + + This region corresponds to the Non-Secure DDR-DRAM, excluding the + TZC-Secured area. The location of the BL32 image will result in different memory maps. This is illustrated for both FVP and Juno in the following diagrams, using the TSP as diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 89d8251e..004f70d6 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -72,10 +72,20 @@ either mandatory or optional. 2.1 Common mandatory modifications ---------------------------------- -A platform port must enable the Memory Management Unit (MMU) with identity -mapped page tables, and enable both the instruction and data caches for each BL -stage. In ARM standard platforms, each BL stage configures the MMU in -the platform-specific architecture setup function, `blX_plat_arch_setup()`. + +A platform port must enable the Memory Management Unit (MMU) as well as the +instruction and data caches for each BL stage. Setting up the translation +tables is the responsibility of the platform port because memory maps differ +across platforms. A memory translation library (see `lib/aarch64/xlat_helpers.c` +and `lib/aarch64/xlat_tables.c`) is provided to help in this setup. Note that +although this library supports non-identity mappings, this is intended only for +re-mapping peripheral physical addresses and allows platforms with high I/O +addresses to reduce their virtual address space. All other addresses +corresponding to code and data must currently use an identity mapping. + +In ARM standard platforms, each BL stage configures the MMU in the +platform-specific architecture setup function, `blX_plat_arch_setup()`, and uses +an identity mapping for all addresses. If the build option `USE_COHERENT_MEM` is enabled, each platform can allocate a block of identity mapped secure memory with Device-nGnRE attributes aligned to @@ -1872,7 +1882,7 @@ they can be invoked without a C Runtime stack. Return : int This API is used by the crash reporting mechanism to initialize the crash -console. It should only use the general purpose registers x0 to x2 to do the +console. It must only use the general purpose registers x0 to x4 to do the initialization and returns 1 on success. ### Function : plat_crash_console_putc @@ -1881,7 +1891,7 @@ initialization and returns 1 on success. Return : int This API is used by the crash reporting mechanism to print a character on the -designated crash console. It should only use general purpose registers x1 and +designated crash console. It must only use general purpose registers x1 and x2 to do its work. The parameter and the return value are in general purpose register x0. diff --git a/docs/user-guide.md b/docs/user-guide.md index 894d69bd..70e1abc3 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: @@ -471,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: @@ -482,6 +505,11 @@ map is explained in the [Firmware Design]. Trusted Firmware must be compiled with GICv2 only driver using `FVP_USE_GIC_DRIVER=FVP_GICV2` build option. +* `FVP_CLUSTER_COUNT` : Configures the cluster count to be used to + build the topology tree within Trusted Firmware. By default the + Trusted Firmware is configured for dual cluster topology and this option + can be used to override the default value. + ### Creating a Firmware Image Package FIPs are automatically created as part of the build instructions described in @@ -859,6 +887,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 -------------------------------------- @@ -919,14 +1025,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. @@ -1211,38 +1318,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 --------------------------------- @@ -1344,7 +1419,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 |