Add documentation for CPU specific abstraction and Errata workarounds
This patch adds documentation for CPU specific abstraction in the firmware-
design.md and adds a new document cpu-errata-workarounds.md to describe
the cpu errata workaround build flags.
Change-Id: Ia08c2fec0b868a0a107d0264e87a60182797a1bd
diff --git a/docs/cpu-errata-workarounds.md b/docs/cpu-errata-workarounds.md
new file mode 100644
index 0000000..73e8e18
--- /dev/null
+++ b/docs/cpu-errata-workarounds.md
@@ -0,0 +1,35 @@
+ARM CPU Errata Workarounds
+==========================
+
+ARM Trusted Firmware exports a series of build flags which controls the
+errata workarounds that are applied to each CPU by the reset handler. The
+errata details can be found in the CPU specifc errata documents published
+by ARM. The errata workarounds are implemented for a particular revision
+or a set of processor revisions. This check is done in the debug build.
+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.
+
+All workarounds are disabled by default. The platform is reponsible for
+enabling these workarounds according to its requirement by defining the
+errata workaround build flags in the platform specific makefile.
+
+In the current implementation, a platform which has more than 1 variant
+with different revisions of a processor has no runtime mechanism available
+for it to specify which errata workarounds should be enabled or not.
+
+The value of the build flags are 0 by default, that is disabled. Any other
+value will enable it.
+
+For Cortex A57, following errata build flags are defined :
+
+* `ERRATA_A57_806969`: This applies errata 806969 workaround to cortex a57
+ CPU. This needs to be enabled only for revision r0p0 of the CPU.
+
+* `ERRATA_A57_813420`: This applies errata 813420 workaround to cortex a57
+ CPU. This needs to be enabled only for revision r0p0 of the CPU.
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index e98c4fa..84684c3 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -9,10 +9,11 @@
4. Power State Coordination Interface
5. Secure-EL1 Payloads and Dispatchers
6. Crash Reporting in BL3-1
-7. Memory layout on FVP platforms
-8. Firmware Image Package (FIP)
-9. Code Structure
-10. References
+7. CPU specific operations framework
+8. Memory layout on FVP platforms
+9. Firmware Image Package (FIP)
+10. Code Structure
+11. References
1. Introduction
@@ -302,8 +303,8 @@
architectural initialization in BL3-1 allows override of any previous
initialization done by BL1. BL3-1 creates page tables to address the first
4GB of physical address space and initializes the MMU accordingly. It initializes
-a buffer of frequently used pointers, called per-cpu pointer cache, in memory for
-faster access. Currently the per-cpu pointer cache contains only the pointer
+a buffer of frequently used pointers, called per-CPU pointer cache, in memory for
+faster access. Currently the per-CPU pointer cache contains only the pointer
to crash stack. It then replaces the exception vectors populated by BL1 with its
own. BL3-1 exception vectors implement more elaborate support for
handling SMCs since this is the only mechanism to access the runtime services
@@ -845,8 +846,8 @@
register contents and report it via the default serial output. The general purpose
registers, EL3, Secure EL1 and some EL2 state registers are reported.
-A dedicated per-cpu crash stack is maintained by BL3-1 and this is retrieved via
-the per-cpu pointer cache. The implementation attempts to minimise the memory
+A dedicated per-CPU crash stack is maintained by BL3-1 and this is retrieved via
+the per-CPU pointer cache. The implementation attempts to minimise the memory
required for this feature. The file `crash_reporting.S` contains the
implementation for crash reporting.
@@ -931,8 +932,100 @@
fpexc32_el2 :0x0000000004000700
sp_el0 :0x0000000004010780
+7. CPU specific operations framework
+-----------------------------
-7. Memory layout on FVP platforms
+Certain aspects of the ARMv8 architecture are implementation defined,
+that is, certain behaviours are not architecturally defined, but must be defined
+and documented by individual processor implementations. The ARM Trusted
+Firmware implements a framework which categorises the common implementation
+defined behaviours and allows a processor to export its implementation of that
+behaviour. The categories are:
+
+1. Processor specific reset sequence.
+
+2. Processor specific power down sequences.
+
+3. Processor specific register dumping as a part of crash reporting.
+
+Each of the above categories fulfils a different requirement.
+
+1. allows any processor specific initialization before the caches and MMU
+ are turned on, like implementation of errata workarounds, entry into
+ the intra-cluster coherency domain etc.
+
+2. allows each processor to implement the power down sequence mandated in
+ its Technical Reference Manual (TRM).
+
+3. allows a processor to provide additional information to the developer
+ in the event of a crash, for example Cortex-A53 has registers which
+ can expose the data cache contents.
+
+Please note that only 2. is mandated by the TRM.
+
+The CPU specific operations framework scales to accommodate a large number of
+different CPUs during power down and reset handling. The platform can specify
+the CPU errata workarounds to be applied for each CPU type during reset
+handling by defining CPU errata compile time macros. Details on these macros
+can be found in the [cpu-errata-workarounds.md][ERRW] file.
+
+The CPU specific operations framework depends on the `cpu_ops` structure which
+needs to be exported for each type of CPU in the platform. It is defined in
+`include/lib/cpus/aarch64/cpu_macros.S` and has the following fields : `midr`,
+`reset_func()`, `core_pwr_dwn()`, `cluster_pwr_dwn()` and `cpu_reg_dump()`.
+
+The CPU specific files in `lib/cpus` export a `cpu_ops` data structure with
+suitable handlers for that CPU. For example, `lib/cpus/cortex_a53.S` exports
+the `cpu_ops` for Cortex-A53 CPU. According to the platform configuration,
+these CPU specific files must must be included in the build by the platform
+makefile. The generic CPU specific operations framework code exists in
+`lib/cpus/aarch64/cpu_helpers.S`.
+
+### CPU specific Reset Handling
+
+After a reset, the state of the CPU when it calls generic reset handler is:
+MMU turned off, both instruction and data caches turned off and not part
+of any coherency domain.
+
+The BL entrypoint code first invokes the `plat_reset_handler()` to allow
+the platform to perform any system initialization required and any system
+errata wrokarounds that needs to be applied. The `get_cpu_ops_ptr()` reads
+the current CPU midr, finds the matching `cpu_ops` entry in the `cpu_ops`
+array and returns it. Note that only the part number and implementator fields
+in midr are used to find the matching `cpu_ops` entry. The `reset_func()` in
+the returned `cpu_ops` is then invoked which executes the required reset
+handling for that CPU and also any errata workarounds enabled by the platform.
+
+### CPU specific power down sequence
+
+During the BL3-1 initialization sequence, the pointer to the matching `cpu_ops`
+entry is stored in per-CPU data by `init_cpu_ops()` so that it can be quickly
+retrieved during power down sequences.
+
+The PSCI service, upon receiving a power down request, determines the highest
+affinity level at which to execute power down sequence for a particular CPU and
+invokes the corresponding 'prepare' power down handler in the CPU specific
+operations framework. For example, when a CPU executes a power down for affinity
+level 0, the `prepare_core_pwr_dwn()` retrieves the `cpu_ops` pointer from the
+per-CPU data and the corresponding `core_pwr_dwn()` is invoked. Similarly when
+a CPU executes power down at affinity level 1, the `prepare_cluster_pwr_dwn()`
+retrieves the `cpu_ops` pointer and the corresponding `cluster_pwr_dwn()` is
+invoked.
+
+At runtime the platform hooks for power down are invoked by the PSCI service to
+perform platform specific operations during a power down sequence, for example
+turning off CCI coherency during a cluster power down.
+
+### CPU specific register reporting during crash
+
+If the crash reporting is enabled in BL3-1, when a crash occurs, the crash
+reporting framework calls `do_cpu_reg_dump` which retrieves the matching
+`cpu_ops` using `get_cpu_ops_ptr()` function. The `cpu_reg_dump()` in
+`cpu_ops` is invoked, which then returns the CPU specific register values to
+be reported and a pointer to the ASCII list of register names in a format
+expected by the crash reporting framework.
+
+8. Memory layout on FVP platforms
----------------------------------
Each bootloader image can be divided in 2 parts:
@@ -1189,7 +1282,7 @@
on FVP, BL3-1 and TSP need to know the limit address that their PROGBITS
sections must not overstep. The platform code must provide those.
-8. Firmware Image Package (FIP)
+9. Firmware Image Package (FIP)
--------------------------------
Using a Firmware Image Package (FIP) allows for packing bootloader images (and
@@ -1267,7 +1360,7 @@
platform policy can be modified to allow additional images.
-9. Code Structure
+10. Code Structure
------------------
Trusted Firmware code is logically divided between the three boot loader
@@ -1312,7 +1405,7 @@
kernel at boot time. These can be found in the `fdts` directory.
-10. References
+11. References
--------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
@@ -1324,7 +1417,6 @@
4. [ARM Trusted Firmware Interrupt Management Design guide][INTRG].
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
_Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
@@ -1335,3 +1427,4 @@
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
[User Guide]: ./user-guide.md
[INTRG]: ./interrupt-framework-design.md
+[ERRW]: ./cpu-errata-workarounds.md