summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/firmware-design.md43
-rw-r--r--docs/plat/nvidia-tegra.md16
-rw-r--r--docs/plat/xilinx-zynqmp.md4
-rw-r--r--docs/porting-guide.md50
-rw-r--r--docs/user-guide.md45
5 files changed, 134 insertions, 24 deletions
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index bd6e2f69..523fa55c 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -16,8 +16,9 @@ Contents :
11. [Use of coherent memory in Trusted Firmware](#11--use-of-coherent-memory-in-trusted-firmware)
12. [Isolating code and read-only data on separate memory pages](#12--isolating-code-and-read-only-data-on-separate-memory-pages)
13. [Performance Measurement Framework](#13--performance-measurement-framework)
-14. [Code Structure](#14--code-structure)
-15. [References](#15--references)
+14. [ARMv8 Architecture Extensions](#14--armv8-architecture-extensions)
+15. [Code Structure](#15--code-structure)
+16. [References](#16--references)
1. Introduction
@@ -1342,7 +1343,7 @@ All BL images share the following requirements:
The following linker symbols are defined for this purpose:
-* `__BSS_START__` Must be aligned on a 16-byte boundary.
+* `__BSS_START__`
* `__BSS_SIZE__`
* `__COHERENT_RAM_START__` Must be aligned on a page-size boundary.
* `__COHERENT_RAM_END__` Must be aligned on a page-size boundary.
@@ -2208,7 +2209,39 @@ in this implementation.
5. `pmf_helpers.h` is an internal header used by `pmf.h`.
-14. Code Structure
+14. ARMv8 Architecture Extensions
+----------------------------------
+
+ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where
+applicable. This section lists the usage of Architecture Extensions, and build
+flags controlling them.
+
+In general, and unless individually mentioned, the build options
+`ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` selects the Architecture Extension to
+target when building ARM Trusted Firmware. Subsequent ARM Architecture
+Extensions are backward compatible with previous versions.
+
+The build system only requires that `ARM_ARCH_MAJOR` and `ARM_ARCH_MINOR` have a
+valid numeric value. These build options only control whether or not
+Architecture Extension-specific code is included in the build. Otherwise, ARM
+Trusted Firmware targets the base ARMv8.0 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 [User Guide].
+
+For details on the Architecture Extension and available features, please refer
+to the respective Architecture Extension Supplement.
+
+### ARMv8.1
+
+This Architecture Extension is targeted when `ARM_ARCH_MAJOR` >= 8, or when
+`ARM_ARCH_MAJOR` == 8 and `ARM_ARCH_MINOR` >= 1.
+
+* The Compare and Swap instruction is used to implement spinlocks. Otherwise,
+ the load-/store-exclusive instruction pair is used.
+
+15. Code Structure
-------------------
Trusted Firmware code is logically divided between the three boot loader
@@ -2252,7 +2285,7 @@ FDTs provide a description of the hardware platform and are used by the Linux
kernel at boot time. These can be found in the `fdts` directory.
-15. References
+16. References
---------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
diff --git a/docs/plat/nvidia-tegra.md b/docs/plat/nvidia-tegra.md
index b29532c9..f82085b1 100644
--- a/docs/plat/nvidia-tegra.md
+++ b/docs/plat/nvidia-tegra.md
@@ -62,6 +62,22 @@ TARGET_SOC=<target-soc e.g. t210|t132> SPD=<dispatcher e.g. tlkd> bl31'
Platforms wanting to use different TZDRAM_BASE, can add 'TZDRAM_BASE=<value>'
to the build command line.
+The Tegra platform code expects a pointer to the following platform specific
+structure via 'x1' register from the BL2 layer which is used by the
+bl31_early_platform_setup() handler to extract the TZDRAM carveout base and
+size for loading the Trusted OS and the UART port ID to be used. The Tegra
+memory controller driver programs this base/size in order to restrict NS
+accesses.
+
+typedef struct plat_params_from_bl2 {
+ /* TZ memory size */
+ uint64_t tzdram_size;
+ /* TZ memory base */
+ uint64_t tzdram_base;
+ /* UART port ID */
+ int uart_id;
+} plat_params_from_bl2_t;
+
Power Management
================
The PSCI implementation expects each platform to expose the 'power state'
diff --git a/docs/plat/xilinx-zynqmp.md b/docs/plat/xilinx-zynqmp.md
index 09546b01..d2dc8b76 100644
--- a/docs/plat/xilinx-zynqmp.md
+++ b/docs/plat/xilinx-zynqmp.md
@@ -12,12 +12,12 @@ BL33 is the non-secure world software (U-Boot, Linux etc).
To build:
```bash
-make ERROR_DEPRECATED=1 RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31
+make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31
```
To build bl32 TSP you have to rebuild bl31 too:
```bash
-make ERROR_DEPRECATED=1 RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32
+make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32
```
# ZynqMP platform specific build options
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index e8486f12..a5e59667 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -1707,10 +1707,56 @@ level could enter. It depends on the `validate_power_state()` handler to
convert the power-state parameter (possibly encoding a composite power state)
passed in a PSCI `CPU_SUSPEND` call to this representation.
-The following functions must be implemented to initialize PSCI functionality in
-the ARM Trusted Firmware.
+The following functions form part of platform port of PSCI functionality.
+### Function : plat_psci_stat_accounting_start() [optional]
+
+ Argument : const psci_power_state_t *
+ Return : void
+
+This is an optional hook that platforms can implement for residency statistics
+accounting before entering a low power state. The `pwr_domain_state` field of
+`state_info` (first argument) can be inspected if stat accounting is done
+differently at CPU level versus higher levels. As an example, if the element at
+index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down
+state, special hardware logic may be programmed in order to keep track of the
+residency statistics. For higher levels (array indices > 0), the residency
+statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the
+default implementation will use PMF to capture timestamps.
+
+### Function : plat_psci_stat_accounting_stop() [optional]
+
+ Argument : const psci_power_state_t *
+ Return : void
+
+This is an optional hook that platforms can implement for residency statistics
+accounting after exiting from a low power state. The `pwr_domain_state` field
+of `state_info` (first argument) can be inspected if stat accounting is done
+differently at CPU level versus higher levels. As an example, if the element at
+index 0 (CPU power level) in the `pwr_domain_state` array indicates a power down
+state, special hardware logic may be programmed in order to keep track of the
+residency statistics. For higher levels (array indices > 0), the residency
+statistics could be tracked in software using PMF. If `ENABLE_PMF` is set, the
+default implementation will use PMF to capture timestamps.
+
+### Function : plat_psci_stat_get_residency() [optional]
+
+ Argument : unsigned int, const psci_power_state_t *, int
+ Return : u_register_t
+
+This is an optional interface that is is invoked after resuming from a low power
+state and provides the time spent resident in that low power state by the power
+domain at a particular power domain level. When a CPU wakes up from suspend,
+all its parent power domain levels are also woken up. The generic PSCI code
+invokes this function for each parent power domain that is resumed and it
+identified by the `lvl` (first argument) parameter. The `state_info` (second
+argument) describes the low power state that the power domain has resumed from.
+The current CPU is the first CPU in the power domain to resume from the low
+power state and the `last_cpu_idx` (third parameter) is the index of the last
+CPU in the power domain to suspend and may be needed to calculate the residency
+for that power domain.
+
### Function : plat_get_target_pwr_state() [optional]
Argument : unsigned int, const plat_local_state_t *, unsigned int
diff --git a/docs/user-guide.md b/docs/user-guide.md
index ebdb5a25..091aeba0 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -37,6 +37,9 @@ the different software components required to boot a Linux system:
* Linux kernel image
* Root filesystem
+Note: the ARM TF v1.3 release was tested with Linaro Release 16.06, and the
+latest version of ARM TF is tested with Linaro Release 16.12.
+
This document also assumes that the user is familiar with the FVP models and
the different command line options available to launch the model.
@@ -181,6 +184,14 @@ performed.
is used to determine the number of valid slave interfaces available in the
ARM CCI driver. Default is 400 (that is, CCI-400).
+* `ARM_ARCH_MAJOR`: The major version of ARM Architecture to target when
+ compiling ARM Trusted Firmware. Its value must be numeric, and defaults to
+ 8. See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
+
+* `ARM_ARCH_MINOR`: The minor version of ARM Architecture to target when
+ compiling ARM Trusted Firmware. Its value must be a numeric, and defaults
+ to 0. See also, _ARMv8 Architecture Extensions_ in [Firmware Design].
+
* `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM
Legacy GIC driver for implementing the platform GIC API. This API is used
by the interrupt management framework. Default is 2 (that is, version 2.0).
@@ -274,8 +285,9 @@ performed.
* `ENABLE_PSCI_STAT`: Boolean option to enable support for optional PSCI
functions `PSCI_STAT_RESIDENCY` and `PSCI_STAT_COUNT`. Default is 0.
- Enabling this option enables the `ENABLE_PMF` build option as well.
- The PMF is used for collecting the statistics.
+ In the absence of an alternate stat collection backend, `ENABLE_PMF` must
+ be enabled. If `ENABLE_PMF` is set, the residency statistics are tracked in
+ software.
* `ENABLE_RUNTIME_INSTRUMENTATION`: Boolean option to enable runtime
instrumentation which injects timestamp collection points into
@@ -878,8 +890,8 @@ Firmware, obtain the additional required firmware, and pack it all together in
a single FIP binary. It assumes that a [Linaro Release][Linaro Release Notes]
has been installed.
-Note currently [Linaro Release][Linaro Release Notes] only includes pre-built
-binaries for AArch64. For AArch32, pre-built binaries are not available.
+Note: Linaro Release 16.06 only includes pre-built binaries for AArch64. For
+AArch32, pre-built binaries are only available from Linaro Release 16.12.
Note: follow the full instructions for one platform before switching to a
different one. Mixing instructions for different platforms may result in
@@ -1099,19 +1111,19 @@ to load the ELF file over JTAG on Juno.
9. Running the software on FVP
-------------------------------
-The AArch64 build of this version of ARM Trusted Firmware has been tested on
-the following ARM FVPs (64-bit host machine only).
+The latest version of the AArch64 build of ARM Trusted Firmware has been tested
+on the following ARM FVPs (64-bit host machine only).
* `Foundation_Platform` (Version 10.2, Build 10.2.20)
-* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x4-A53x4` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x1-A53x1` (Version 7.7, Build 0.8.7701)
-* `FVP_Base_Cortex-A57x2-A53x4` (Version 7.7, Build 0.8.7701)
+* `FVP_Base_AEMv8A-AEMv8A` (Version 8.2, Build 0.8.8202)
+* `FVP_Base_Cortex-A57x4-A53x4` (Version 8.2, Build 0.8.8202)
+* `FVP_Base_Cortex-A57x1-A53x1` (Version 8.2, Build 0.8.8202)
+* `FVP_Base_Cortex-A57x2-A53x4` (Version 8.2, Build 0.8.8202)
-The AArch32 build of this version of ARM Trusted Firmware has been tested on
-the following ARM FVPs (64-bit host machine only).
+The latest version of the AArch32 build of ARM Trusted Firmware has been tested
+on the following ARM FVPs (64-bit host machine only).
-* `FVP_Base_AEMv8A-AEMv8A` (Version 7.7, Build 0.8.7701)
+* `FVP_Base_AEMv8A-AEMv8A` (Version 8.2, Build 0.8.8202)
* `FVP_Base_Cortex-A32x4` (Version 10.1, Build 10.1.32)
NOTE: The build numbers quoted above are those reported by launching the FVP
@@ -1131,6 +1143,9 @@ Please refer to the FVP documentation for a detailed description of the model
parameter options. A brief description of the important ones that affect the ARM
Trusted Firmware and normal world software behavior is provided below.
+Note the instructions in the following sections assume that Linaro Release 16.06
+is being used.
+
### Obtaining the Flattened Device Trees
Depending on the FVP configuration and Linux configuration used, different
@@ -1436,12 +1451,12 @@ wakeup interrupt from RTC.
- - - - - - - - - - - - - - - - - - - - - - - - - -
-_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._
+_Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved._
[Firmware Design]: firmware-design.md
[ARM FVP website]: https://developer.arm.com/products/system-design/fixed-virtual-platforms
-[Linaro Release Notes]: https://community.arm.com/docs/DOC-10952#jive_content_id_Linaro_Release_1606
+[Linaro Release Notes]: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated
[ARM Platforms Portal]: https://community.arm.com/groups/arm-development-platforms
[Linaro SW Instructions]: https://community.arm.com/docs/DOC-10803
[Juno Instructions]: https://community.arm.com/docs/DOC-10804
generated by cgit v1.2.3 (git 2.0.4) at 2025-09-19 21:50:46 +0000