Skip to content

GitLab

Commit 2442d248 authored by Juan Castillo's avatar Juan Castillo Committed by Achin Gupta
Browse files

Add information about Juno in firmware-design.md 

This patch reorganizes the firmware design guide to add information about the
port of the ARM Trusted Firmware to the Juno ARM development platform.

Change-Id: I0b80e2e7a35ccad1af2e971506cfb7fe505f8b84
parent 17f89d08
Show whitespace changes
Inline Side-by-side
docs/firmware-design.md
View file @ 2442d248
......@@ -10,7 +10,7 @@ Contents :
5. Secure-EL1 Payloads and Dispatchers
6. Crash Reporting in BL3-1
7. CPU specific operations framework
8. Memory layout on FVP platforms
8. Memory layout of BL images
9. Firmware Image Package (FIP)
10. Code Structure
11. References
......@@ -58,9 +58,18 @@ into five steps (in order of execution):
* Boot Loader stage 3-2 (BL3-2) _Secure-EL1 Payload_ (optional)
* Boot Loader stage 3-3 (BL3-3) _Non-trusted Firmware_
The ARM Fixed Virtual Platforms (FVPs) provide trusted ROM, trusted SRAM and
trusted DRAM regions. Each boot loader stage uses one or more of these
memories for its code and data.
ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
combination of the following types of memory regions. Each bootloader stage uses
one or more of these memory regions.
* Regions accessible from both non-secure and secure states. For example,
non-trusted SRAM, ROM and DRAM.
* Regions accessible from only the secure state. For example, trusted SRAM and
ROM. The FVPs also implement the trusted DRAM which is statically
configured. Additionally, the Base FVPs and Juno development platform
configure the TrustZone Controller (TZC) to create a region in the DRAM
which is accessible only from the secure state.
The sections below provide the following details:
......@@ -73,23 +82,30 @@ The sections below provide the following details:
### BL1
This stage begins execution from the platform's reset vector in trusted ROM at
EL3. BL1 code starts at `0x00000000` (trusted ROM) in the FVP memory map. The
BL1 data section is placed at the start of trusted SRAM, `0x04000000`. The
functionality implemented by this stage is as follows.
This stage begins execution from the platform's reset vector at EL3. The reset
address is platform dependent but it is usually located in a Trusted ROM area.
The BL1 data section is copied to trusted SRAM at runtime.
On the ARM FVP port, BL1 code starts execution from the reset vector at address
`0x00000000` (trusted ROM). The BL1 data section is copied to the start of
trusted SRAM at address `0x04000000`.
On the Juno ARM development platform port, BL1 code starts execution at
`0x0BEC0000` (FLASH). The BL1 data section is copied to trusted SRAM at address
`0x04001000.
The functionality implemented by this stage is as follows.
#### Determination of boot path
Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
boot and a cold boot. This is done using a platform-specific mechanism. The
ARM FVPs implement a simple power controller at `0x1c100000`. The `PSYS`
register (`0x10`) is used to distinguish between a cold and warm boot. This
information is contained in the `PSYS.WK[25:24]` field. Additionally, a
per-CPU mailbox is maintained in trusted DRAM (`0x00600000`), to which BL1
writes an entrypoint. Each CPU jumps to this entrypoint upon warm boot. During
cold boot, BL1 places the secondary CPUs in a safe platform-specific state while
the primary CPU executes the remaining cold boot path as described in the
following sections.
boot and a cold boot. This is done using platform-specific mechanisms (see the
`platform_get_entrypoint()` function in the [Porting Guide]). In the case of a
warm boot, a CPU is expected to continue execution from a seperate
entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
platform-specific state (see the `plat_secondary_cold_boot_setup()` function in
the [Porting Guide]) while the primary CPU executes the remaining cold boot path
as described in the following sections.
#### Architectural initialization
......@@ -98,14 +114,10 @@ BL1 performs minimal architectural initialization as follows.
* Exception vectors
BL1 sets up simple exception vectors for both synchronous and asynchronous
exceptions. The default behavior upon receiving an exception is to set a
status code. In the case of the FVP this code is written to the Versatile
Express System LED register in the following format:
SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
SYS_LED[7:3] - Exception Class (Sync/Async & origin). The values for
each exception class are:
exceptions. The default behavior upon receiving an exception is to populate
a status code in the general purpose register `X0` and call the
`plat_report_exception()` function (see the [Porting Guide]). The status
code is one of:
0x0 : Synchronous exception from Current EL with SP_EL0
0x1 : IRQ exception from Current EL with SP_EL0
......@@ -124,15 +136,31 @@ BL1 performs minimal architectural initialization as follows.
0xe : FIQ exception from Lower EL using aarch32
0xf : System Error exception from Lower EL using aarch32
The `plat_report_exception()` implementation on the ARM FVP port programs
the Versatile Express System LED register in the following format to
indicate the occurence of an unexpected exception:
SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value
of the status code
A write to the LED register reflects in the System LEDs (S6LED0..7) in the
CLCD window of the FVP. This behavior is because this boot loader stage
does not expect to receive any exceptions other than the SMC exception.
CLCD window of the FVP.
BL1 does not expect to receive any exceptions other than the SMC exception.
For the latter, BL1 installs a simple stub. The stub expects to receive
only a single type of SMC (determined by its function ID in the general
purpose register `X0`). This SMC is raised by BL2 to make BL1 pass control
to BL3-1 (loaded by BL2) at EL3. Any other SMC leads to an assertion
failure.
* CPU initialization
BL1 calls the `reset_handler()` function which in turn calls the CPU
specific reset handler function (see the section: "CPU specific operations
framework").
* MMU setup
BL1 sets up EL3 memory translation by creating page tables to cover the
......@@ -145,17 +173,8 @@ BL1 performs minimal architectural initialization as follows.
`SCTLR_EL3.A` and `SCTLR_EL3.SA` bits. Exception endianness is set to
little-endian by clearing the `SCTLR_EL3.EE` bit.
- `CPUECTLR`. When the FVP includes a model of a specific ARM processor
implementation (for example A57 or A53), then intra-cluster coherency is
enabled by setting the `CPUECTLR.SMPEN` bit. The AEMv8 Base FVP is
inherently coherent so does not implement `CPUECTLR`.
- `SCR`. Use of the HVC instruction from EL1 is enabled by setting the
`SCR.HCE` bit. FIQ exceptions are configured to be taken in EL3 by
setting the `SCR.FIQ` bit. The register width of the next lower
exception level is set to AArch64 by setting the `SCR.RW` bit. External
Aborts and SError Interrupts are configured to be taken in EL3 by
setting the `SCR.EA` bit.
- `SCR_EL3`. The register width of the next lower exception level is set to
AArch64 by setting the `SCR.RW` bit.
- `CPTR_EL3`. Accesses to the `CPACR_EL1` register from EL1 or EL2, or the
`CPTR_EL2` register from EL2 are configured to not trap to EL3 by
......@@ -228,19 +247,19 @@ defined base address is used to specify the load address for the BL3-1 image.
It also defines the extents of memory available for use by the BL3-2 image.
BL2 also initializes UART0 (PL011 console), which enables access to the
`printf` family of functions in BL2. Platform security is initialized to allow
access to access controlled components. On the Base FVP a TrustZone controller
(TZC-400) is configured to give full access to the platform DRAM. The storage
abstraction layer is initialized which is used to load further bootloader
images.
access to controlled components. The storage abstraction layer is initialized
which is used to load further bootloader images.
#### BL3-0 (System Control Processor Firmware) image load
Some systems have a separate System Control Processor (SCP) for power, clock,
reset and system control. BL2 loads the optional BL3-0 image from platform
storage into a platform-specific region of secure memory. The subsequent
handling of BL3-0 is platform specific. Typically the image is transferred into
SCP memory using a platform-specific protocol. The SCP executes BL3-0 and
signals to the Application Processor (AP) for BL2 execution to continue.
handling of BL3-0 is platform specific. For example, on the Juno ARM development
platform port the image is transferred into SCP memory using the SCPI protocol
after being loaded in the trusted SRAM memory at address `0x04009000`. The SCP
executes BL3-0 and signals to the Application Processor (AP) for BL2 execution
to continue.
#### BL3-1 (EL3 Runtime Firmware) image load
......@@ -264,8 +283,7 @@ managing interaction with BL3-2. This information is passed to BL3-1.
#### BL3-3 (Non-trusted Firmware) image load
BL2 loads the BL3-3 image (e.g. UEFI or other test or boot software) from
platform storage into non-secure memory as defined by the platform
(`0x88000000` for FVPs).
platform storage into non-secure memory as defined by the platform.
BL2 relies on BL3-1 to pass control to BL3-3 once secure state initialization is
complete. Hence, BL2 populates a platform-specific area of memory with the
......@@ -723,6 +741,8 @@ currently implemented:
- `CPU_ON`
- `CPU_SUSPEND`
- `AFFINITY_INFO`
- `SYSTEM_OFF`
- `SYSTEM_RESET`
The `CPU_ON`, `CPU_OFF` and `CPU_SUSPEND` functions implement the warm boot
path in ARM Trusted Firmware. `CPU_ON` and `CPU_OFF` have undergone testing
......@@ -732,22 +752,14 @@ experimental. Support for `CPU_SUSPEND` is stable for entry into power down
states. Standby states are currently not supported. `PSCI_VERSION` is
present but completely untested in this version of the software.
Unsupported PSCI functions can be divided into ones that can return
execution to the caller and ones that cannot. The following functions
return with a error code as documented in the [Power State Coordination
Interface PDD] [PSCI].
The following unsupported functions return with a error code as documented in
the [Power State Coordination Interface PDD] [PSCI].
- `MIGRATE` : -1 (NOT_SUPPORTED)
- `MIGRATE_INFO_TYPE` : 2 (Trusted OS is either not present or does not
require migration)
- `MIGRATE_INFO_UP_CPU` : 0 (Return value is UNDEFINED)
The following unsupported functions do not return and signal an assertion
failure if invoked.
- `SYSTEM_OFF`
- `SYSTEM_RESET`
5. Secure-EL1 Payloads and Dispatchers
---------------------------------------
......@@ -838,8 +850,9 @@ before returning through EL3 and running the non-trusted firmware (BL3-3):
`bl31_main()` will set up the return to the normal world firmware BL3-3 and
continue the boot process in the normal world.
6. Crash Reporting in BL3-1
----------------------------------
----------------------------
The BL3-1 implements a scheme for reporting the processor state when an unhandled
exception is encountered. The reporting mechanism attempts to preserve all the
......@@ -932,6 +945,7 @@ The sample crash output is shown below.
fpexc32_el2 :0x0000000004000700
sp_el0 :0x0000000004010780
7. CPU specific operations framework
-----------------------------
......@@ -1025,8 +1039,9 @@ reporting framework calls `do_cpu_reg_dump` which retrieves the matching
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
----------------------------------
8. Memory layout of BL images
-----------------------------
Each bootloader image can be divided in 2 parts:
......@@ -1048,114 +1063,7 @@ PROGBITS sections then the resulting binary file would contain a bunch of zero
bytes at the location of this NOBITS section, making the image unnecessarily
bigger. Smaller images allow faster loading from the FIP to the main memory.
On FVP platforms, we use the Trusted ROM, Trusted SRAM and, optionally, Trusted
DRAM to store the trusted firmware binaries and shared data.
* A 4KB page of shared memory is used to store the entrypoint mailboxes
and the parameters passed between bootloaders. The shared memory can be
allocated either at the top of Trusted SRAM or at the base of Trusted
DRAM at build time. When allocated in Trusted SRAM, the amount of Trusted
SRAM available to load the bootloader images will be reduced by the size
of the shared memory.
* BL1 is originally sitting in the Trusted ROM at address `0x0`. Its
read-write data are relocated at the top of the Trusted SRAM at runtime.
If the shared memory is allocated in Trusted SRAM, the BL1 read-write data
is relocated just below the shared memory.
* BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
sections will overwrite BL1 R/W data.
* BL2 is loaded below BL3-1.
* The TSP is loaded as the BL3-2 image at the base of either the Trusted
SRAM or Trusted DRAM. When loaded into Trusted SRAM, its NOBITS sections
are allowed to overlay BL2. When loaded into Trusted DRAM, an offset
corresponding to the size of the shared memory is applied to avoid
overlap.
This memory layout is designed to give the BL3-2 image as much memory as
possible when it is loaded into Trusted SRAM. Depending on the location of the
shared memory page and the TSP, it will result in different memory maps,
illustrated by the following diagrams.
** Shared data & TSP in Trusted SRAM (default option): **
Trusted SRAM
0x04040000 +----------+
| Shared |
0x0403F000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
0x04000000 +----------+ ------------------
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
** Shared data & TSP in Trusted DRAM: **
Trusted DRAM
0x08000000 +----------+
| |
| BL3-2 |
| |
0x06001000 |----------|
| Shared |
0x06000000 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
| |
0x04000000 +----------+
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
** Shared data in Trusted DRAM, TSP in Trusted SRAM: **
Trusted DRAM
0x08000000 +----------+
| |
| |
| |
0x06001000 |----------|
| Shared |
0x06000000 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
0x04000000 +----------+ ------------------
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
Loading the TSP image in Trusted DRAM doesn't change the memory layout of the
other boot loader images in Trusted SRAM.
### Linker scripts and symbols
Each bootloader stage image layout is described by its own linker script. The
linker scripts export some symbols into the program symbol table. Their values
......@@ -1206,7 +1114,7 @@ The linker scripts define some extra, optional symbols. They are not actually
used by any code but they help in understanding the bootloader images' memory
layout as they are easy to spot in the link map files.
### Common linker symbols
#### Common linker symbols
Early setup code needs to know the extents of the BSS section to zero-initialise
it before executing any C code. The following linker symbols are defined for
......@@ -1223,7 +1131,7 @@ attributes for it. The following linker symbols are defined for this purpose:
* `__COHERENT_RAM_END__` This address must be aligned on a page-size boundary.
* `__COHERENT_RAM_UNALIGNED_SIZE__`
### BL1's linker symbols
#### BL1's linker symbols
BL1's early setup code needs to know the extents of the .data section to
relocate it from ROM to RAM before executing any C code. The following linker
......@@ -1240,7 +1148,7 @@ for this purpose:
* `__BL1_RAM_START__` This is the start address of BL1 RW data.
* `__BL1_RAM_END__` This is the end address of BL1 RW data.
### BL2's, BL3-1's and TSP's linker symbols
#### BL2's, BL3-1's and TSP's linker symbols
BL2, BL3-1 and TSP need to know the extents of their read-only section to set
the right memory attributes for this memory region in their MMU setup code. The
......@@ -1282,8 +1190,153 @@ Additionally, if the platform memory layout implies some image overlaying like
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.
#### Memory layout on ARM FVPs
The following list describes the memory layout on the FVP:
* A 4KB page of shared memory is used to store the entrypoint mailboxes
and the parameters passed between bootloaders. The shared memory can be
allocated either at the top of Trusted SRAM or at the base of Trusted
DRAM at build time. When allocated in Trusted SRAM, the amount of Trusted
SRAM available to load the bootloader images will be reduced by the size
of the shared memory.
* BL1 is originally sitting in the Trusted ROM at address `0x0`. Its
read-write data are relocated at the top of the Trusted SRAM at runtime.
If the shared memory is allocated in Trusted SRAM, the BL1 read-write data
is relocated just below the shared memory.
* BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
sections will overwrite BL1 R/W data.
* BL2 is loaded below BL3-1.
* The TSP is loaded as the BL3-2 image at the base of either the Trusted
SRAM or Trusted DRAM. When loaded into Trusted SRAM, its NOBITS sections
are allowed to overlay BL2. When loaded into Trusted DRAM, an offset
corresponding to the size of the shared memory is applied to avoid
overlap.
This memory layout is designed to give the BL3-2 image as much memory as
possible when it is loaded into Trusted SRAM. Depending on the location of the
shared memory page and the TSP, it will result in different memory maps,
illustrated by the following diagrams.
** Shared data & TSP in Trusted SRAM (default option): **
Trusted SRAM
0x04040000 +----------+
| Shared |
0x0403F000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
0x04000000 +----------+ ------------------
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
** Shared data & TSP in Trusted DRAM: **
Trusted DRAM
0x08000000 +----------+
| |
| BL3-2 |
| |
0x06001000 |----------|
| Shared |
0x06000000 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
| |
0x04000000 +----------+
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
** Shared data in Trusted DRAM, TSP in Trusted SRAM: **
Trusted DRAM
0x08000000 +----------+
| |
| |
| |
0x06001000 |----------|
| Shared |
0x06000000 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
0x04000000 +----------+ ------------------
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
Loading the TSP image in Trusted DRAM doesn't change the memory layout of the
other boot loader images in Trusted SRAM.
#### Memory layout on Juno ARM development platform
Flash0
0x0C000000 +----------+
: :
0x0BED0000 |----------|
| BL1 (ro) |
0x0BEC0000 |----------|
: :
| Bypass |
0x08000000 +----------+
Trusted SRAM
0x04040000 +----------+
| BL2 | BL3-1 is loaded
0x04033000 |----------| after BL3-0 has
| BL3-2 | been sent to SCP
0x04023000 |----------| ------------------
| BL3-0 | <<<<<<<<<<<<< | BL3-1 |
0x04009000 |----------| ------------------
| BL1 (rw) |
0x04001000 |----------|
| MHU |
0x04000000 +----------+
The Message Handling Unit (MHU) page contains the entrypoint mailboxes and a
shared memory area. This shared memory is used as a communication channel
between the AP and the SCP.
BL1 code starts at `0x0BEC0000`. The BL1 data section is copied to trusted SRAM
at `0x04001000`, right after the MHU page. Entrypoint mailboxes are stored in
the first 128 bytes of the MHU page.
9. Firmware Image Package (FIP)
--------------------------------
---------------------------------
Using a Firmware Image Package (FIP) allows for packing bootloader images (and
potentially other payloads) into a single archive that can be loaded by the ARM
......@@ -1361,7 +1414,7 @@ platform policy can be modified to allow additional images.
10. Code Structure
------------------
-------------------
Trusted Firmware code is logically divided between the three boot loader
stages mentioned in the previous sections. The code is also divided into the
......@@ -1406,7 +1459,7 @@ kernel at boot time. These can be found in the `fdts` directory.
11. References
--------------
---------------
1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
under NDA through your ARM account representative.
......@@ -1426,5 +1479,6 @@ _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"
[UUID]: https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"
[User Guide]: ./user-guide.md
[Porting Guide]: ./porting-guide.md
[INTRG]: ./interrupt-framework-design.md
[ERRW]: ./cpu-errata-workarounds.md
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment