This patch adds design documentation for the Firmware Update (FWU)
feature in `firmware-update.md`. It provides an overview of FWU,
describes the BL1 SMC interface, and includes diagrams showing
an example FWU boot flow and the FWU state machine.
This patch also updates the existing TF documents where needed:
* `porting-guide.md`
* `user-guide.md`
* `firmware-design.md`
* `rt-svc-writers-guide.md`
* `trusted_board_boot.md`
Change-Id: Ie6de31544429b18f01327bd763175e218299a4ce
Co-Authored-By: Dan Handley <dan.handley@arm.com>
This patch introduces a new document presenting the ARM Trusted
Firmware Reset Design. It shows the reset code flow, lists the
different build options that affect it, in which case to use them
and what their exact effect is.
The section about using BL31 entrypoint as the reset address has
been moved from the general firmware design document to this one.
It's also been improved to explain why the FVP port supports the
RESET_TO_BL31 configuration, even though the reset vector address
can't be programmed dynamically.
This document includes some images, which have been generated using
Dia version 0.97.2. This tool can be obtained from:
https://wiki.gnome.org/Apps/Dia/Download
This patch provides:
- the image files describing the different reset flow diagrams;
- the source '.dia' file;
- a script automating the generation of the images from the '.dia'
file.
Note that the 2 latter files are not actually needed for the document
and are provided for convenience only, in case the reset images need
to be modified.
Change-Id: Ib6302e8209d418a5b31c4e85e55fd9e83caf2ca2
This patch updates the relevant documentation in ARM Trusted Firmware
for the new GIC drivers. The user-guide.md and porting-guide.md have been
updated as follows:
* The build option to compile Trusted Firmware with different GIC drivers
for FVP has been explained in the user-guide.md.
* The implementation details of interrupt management framework porting
APIs for GICv3 have been added in porting-guide.md.
* The Linaro tracking kernel release does not work OOB in GICv3 mode.
The instructions for changing UEFI configuration in order to run with
the new GICv3 driver in ARM TF have been added to user-guide.md.
The interrupt-framework-design.md has been updated as follows:
* Describes support for registering and handling interrupts targeted to EL3
e.g. Group 0 interrupts in GICv3.
* Describes the build option `TSP_NS_INTR_ASYNC_PREEMPT` in detail.
* Describes preemption of TSP in S-EL1 by non secure interrupts and
also possibly by higher priority EL3 interrupts.
* Describes the normal world sequence for issuing `standard` SMC calls.
* Modifies the document to correspond to the current state of interrupt
handling in TSPD and TSP.
* Modifies the various functions names in the document to reflect
the current names used in code.
Change-Id: I78c9514b5be834f193405aad3c1752a4a9e27a6c
This patch removes the dash character from the image name, to
follow the image terminology in the Trusted Firmware Wiki page:
https://github.com/ARM-software/arm-trusted-firmware/wiki
Changes apply to output messages, comments and documentation.
non-ARM platform files have been left unmodified.
Change-Id: Ic2a99be4ed929d52afbeb27ac765ceffce46ed76
This patch replaces all references to the SCP Firmware (BL0, BL30,
BL3-0, bl30) with the image terminology detailed in the TF wiki
(https://github.com/ARM-software/arm-trusted-firmware/wiki):
BL0 --> SCP_BL1
BL30, BL3-0 --> SCP_BL2
bl30 --> scp_bl2
This change affects code, documentation, build system, tools and
platform ports that load SCP firmware. ARM plaforms have been
updated to the new porting API.
IMPORTANT: build option to specify the SCP FW image has changed:
BL30 --> SCP_BL2
IMPORTANT: This patch breaks compatibility for platforms that use BL2
to load SCP firmware. Affected platforms must be updated as follows:
BL30_IMAGE_ID --> SCP_BL2_IMAGE_ID
BL30_BASE --> SCP_BL2_BASE
bl2_plat_get_bl30_meminfo() --> bl2_plat_get_scp_bl2_meminfo()
bl2_plat_handle_bl30() --> bl2_plat_handle_scp_bl2()
Change-Id: I24c4c1a4f0e4b9f17c9e4929da815c4069549e58
The mbed TLS library has introduced some changes in the API from
the 1.3.x to the 2.x releases. Using the 2.x releases requires
some changes to the crypto and transport modules.
This patch updates both modules to the mbed TLS 2.x API.
All references to the mbed TLS library in the code or documentation
have been updated to 'mbed TLS'. Old references to PolarSSL have
been updated to 'mbed TLS'.
User guide updated to use mbed TLS 2.2.0.
NOTE: moving up to mbed TLS 2.x from 1.3.x is not backward compatible.
Applying this patch will require an mbed TLS 2.x release to be used.
Also note that the mbed TLS license changed to Apache version 2.0.
Change-Id: Iba4584408653cf153091f2ca2ee23bc9add7fda4
Move up the version numbers in the user guide of:
* DS-5 (to v5.22)
* Base FVP (to 7.0)
* Foundation FVP (to 9.4)
* Linaro release (to 15.10)
Note that, starting from Linaro release 15.10, the related release
instructions have migrated from http://releases.linaro.org to the
ARM Connected Community website. The URLs in the User Guide have
been updated accordingly.
The 'libssl-dev' package has been removed from the list of
prerequisite tools, as it is already referenced on the ARM Connected
Community page. Also, the 'device-tree-compiler' package has been
marked as an optional dependency, since the Trusted Firmware
repository provides the prebuilt DTB files. Hence, this tool is
needed only when the user wants to rebuild the DTS files.
Change-Id: I4a172ece60bf90437131c6b96e73a9f1e9b40117
The Server Base System Architecture document (ARM-DEN-0029)
specifies a generic UART device. The programmer's view of this
generic UART is a subset of the ARM PL011 UART. However, the
current PL011 driver in Trusted Firmware uses some features
that are outside the generic UART specification.
This patch modifies the PL011 driver to exclude features outside
the SBSA generic UART specification by setting the boolean build
option 'PL011_GENERIC_UART=1'. Default value is 0 (use full
PL011 features).
User guide updated.
FixesARM-software/tf-issues#216
Change-Id: I6e0eb86f9d69569bc3980fb57e70d6da5d91a737
This patch overrides the default weak definition of
`bl31_plat_runtime_setup()` for ARM Standard platforms to
specify a BL31 runtime console. ARM Standard platforms are
now expected to define `PLAT_ARM_BL31_RUN_UART_BASE` and
`PLAT_ARM_BL31_RUN_UART_CLK_IN_HZ` macros which is required
by `arm_bl31_plat_runtime_setup()` to initialize the runtime
console.
The system suspend resume helper `arm_system_pwr_domain_resume()`
is fixed to initialize the runtime console rather than the boot
console on resumption from system suspend.
FixesARM-software/tf-issues#220
Change-Id: I80eafe5b6adcfc7f1fdf8b99659aca1c64d96975
It is not ideal for BL31 to continue to use boot console at
runtime which could be potentially uninitialized. This patch
introduces a new optional platform porting API
`bl31_plat_runtime_setup()` which allows the platform to perform
any BL31 runtime setup just prior to BL31 exit during cold boot.
The default weak implementation of this function will invoke
`console_uninit()` which will suppress any BL31 runtime logs.
On the ARM Standard platforms, there is an anomaly that
the boot console will be reinitialized on resumption from
system suspend in `arm_system_pwr_domain_resume()`. This
will be resolved in the following patch.
NOTE: The default weak definition of `bl31_plat_runtime_setup()`
disables the BL31 console. To print the BL31 runtime
messages, platforms must override this API and initialize a
runtime console.
FixesARM-software/tf-issues#328
Change-Id: Ibaf8346fcceb447fe1a5674094c9f8eb4c09ac4a
On a GICv2 system, interrupts that should be handled in the secure world are
typically signalled as FIQs. On a GICv3 system, these interrupts are signalled
as IRQs instead. The mechanism for handling both types of interrupts is the same
in both cases. This patch enables the TSP to run on a GICv3 system by:
1. adding support for handling IRQs in the exception handling code.
2. removing use of "fiq" in the names of data structures, macros and functions.
The build option TSPD_ROUTE_IRQ_TO_EL3 is deprecated and is replaced with a
new build flag TSP_NS_INTR_ASYNC_PREEMPT. For compatibility reasons, if the
former build flag is defined, it will be used to define the value for the
new build flag. The documentation is also updated accordingly.
Change-Id: I1807d371f41c3656322dd259340a57649833065e
This patch adds watchdog support on ARM platforms (FVP and Juno).
A secure instance of SP805 is used as Trusted Watchdog. It is
entirely managed in BL1, being enabled in the early platform setup
hook and disabled in the exit hook. By default, the watchdog is
enabled in every build (even when TBB is disabled).
A new ARM platform specific build option `ARM_DISABLE_TRUSTED_WDOG`
has been introduced to allow the user to disable the watchdog at
build time. This feature may be used for testing or debugging
purposes.
Specific error handlers for Juno and FVP are also provided in this
patch. These handlers will be called after an image load or
authentication error. On FVP, the Table of Contents (ToC) in the FIP
is erased. On Juno, the corresponding error code is stored in the
V2M Non-Volatile flags register. In both cases, the CPU spins until
a watchdog reset is generated after 256 seconds (as specified in
the TBBR document).
Change-Id: I9ca11dcb0fe15af5dbc5407ab3cf05add962f4b4
The implications of the 'PROGRAMMABLE_RESET_ADDRESS' build option on
the platform porting layer are simple enough to be described in the
User Guide directly. This patch removes the reference to the Porting
Guide.
Change-Id: I7f753b18abd20effc4fd30836609e1fd51d9221d
This patch introduces a new build option named COLD_BOOT_SINGLE_CPU,
which allows platforms that only release a single CPU out of reset to
slightly optimise their cold boot code, both in terms of code size
and performance.
COLD_BOOT_SINGLE_CPU defaults to 0, which assumes that the platform
may release several CPUs out of reset. In this case, the cold reset
code needs to coordinate all CPUs via the usual primary/secondary
CPU distinction.
If a platform guarantees that only a single CPU will ever be released
out of reset, there is no need to arbitrate execution ; the notion of
primary and secondary CPUs itself no longer exists. Such platforms
may set COLD_BOOT_SINGLE_CPU to 1 in order to compile out the
primary/secondary CPU identification in the cold reset code.
All ARM standard platforms can release several CPUs out of reset
so they use COLD_BOOT_SINGLE_CPU=0. However, on CSS platforms like
Juno, bringing up more than one CPU at reset should only be attempted
when booting an EL3 payload, as it is not fully supported in the
normal boot flow.
For platforms using COLD_BOOT_SINGLE_CPU=1, the following 2 platform
APIs become optional:
- plat_secondary_cold_boot_setup();
- plat_is_my_cpu_primary().
The Porting Guide has been updated to reflect that.
User Guide updated as well.
Change-Id: Ic5b474e61b7aec1377d1e0b6925d17dfc376c46b
- Document the new build option EL3_PAYLOAD_BASE
- Document the EL3 payload boot flow
- Document the FVP model parameters to boot an EL3 payload
Change-Id: Ie6535914a9a68626e4401659bee4fcfd53d4bd37
Normally, in the FVP port, secondary CPUs are immediately powered
down if they are powered on at reset. However, when booting an EL3
payload, we need to keep them powered on as the requirement is for
all CPUs to enter the EL3 payload image. This patch puts them in a
holding pen instead of powering them off.
Change-Id: I6526a88b907a0ddb820bead72f1d350a99b1692c
This patch adds support for booting EL3 payloads on CSS platforms,
for example Juno. In this scenario, the Trusted Firmware follows
its normal boot flow up to the point where it would normally pass
control to the BL31 image. At this point, it jumps to the EL3
payload entry point address instead.
Before handing over to the EL3 payload, the data SCP writes for AP
at the beginning of the Trusted SRAM is restored, i.e. we zero the
first 128 bytes and restore the SCP Boot configuration. The latter
is saved before transferring the BL30 image to SCP and is restored
just after the transfer (in BL2). The goal is to make it appear that
the EL3 payload is the first piece of software to run on the target.
The BL31 entrypoint info structure is updated to make the primary
CPU jump to the EL3 payload instead of the BL31 image.
The mailbox is populated with the EL3 payload entrypoint address,
which releases the secondary CPUs out of their holding pen (if the
SCP has powered them on). The arm_program_trusted_mailbox() function
has been exported for this purpose.
The TZC-400 configuration in BL2 is simplified: it grants secure
access only to the whole DRAM. Other security initialization is
unchanged.
This alternative boot flow is disabled by default. A new build option
EL3_PAYLOAD_BASE has been introduced to enable it and provide the EL3
payload's entry point address. The build system has been modified
such that BL31 and BL33 are not compiled and/or not put in the FIP in
this case, as those images are not used in this boot flow.
Change-Id: Id2e26fa57988bbc32323a0effd022ab42f5b5077
This patch modifies the prototype of the bl1_plat_prepare_exit()
platform API to pass the address of the entry point info structure
received from BL2. The structure contains information that can be
useful, depending on the kind of clean up or bookkeeping operations
to perform.
The weak implementation of this function ignores this argument to
preserve platform backwards compatibility.
NOTE: THIS PATCH MAY BREAK PLATFORM PORTS THAT ARE RELYING ON THE
FORMER PROTOTYPE OF THE BL1_PLAT_PREPARE_EXIT() API.
Change-Id: I3fc18f637de06c85719c4ee84c85d6a4572a0fdb
This patch introduces a new build flag, SPIN_ON_BL1_EXIT, which
puts an infinite loop in BL1. It is intended to help debugging
the post-BL2 phase of the Trusted Firmware by stopping execution
in BL1 just before handing over to BL31. At this point, the
developer may take control of the target using a debugger.
This feature is disabled by default and can be enabled by
rebuilding BL1 with SPIN_ON_BL1_EXIT=1.
User Guide updated accordingly.
Change-Id: I6b6779d5949c9e5571dd371255520ef1ac39685c
The IMF_READ_INTERRUPT_ID build option enables a feature where the interrupt
ID of the highest priority pending interrupt is passed as a parameter to the
interrupt handler registered for that type of interrupt. This additional read
of highest pending interrupt id from GIC is problematic as it is possible that
the original interrupt may get deasserted and another interrupt of different
type maybe become the highest pending interrupt. Hence it is safer to prevent
such behaviour by removing the IMF_READ_INTERRUPT_ID build option.
The `id` parameter of the interrupt handler `interrupt_type_handler_t` is
now made a reserved parameter with this patch. It will always contain
INTR_ID_UNAVAILABLE.
FixesARM-software/tf-issues#307
Change-Id: I2173aae1dd37edad7ba6bdfb1a99868635fa34de
This patch changes the build time behaviour when using deprecated API within
Trusted Firmware. Previously the use of deprecated APIs would only trigger a
build warning (which was always treated as a build error), when
WARN_DEPRECATED = 1. Now, the use of deprecated C declarations will always
trigger a build time warning. Whether this warning is treated as error or not
is determined by the build flag ERROR_DEPRECATED which is disabled by default.
When the build flag ERROR_DEPRECATED=1, the invocation of deprecated API or
inclusion of deprecated headers will result in a build error.
Also the deprecated context management helpers in context_mgmt.c are now
conditionally compiled depending on the value of ERROR_DEPRECATED flag
so that the APIs themselves do not result in a build error when the
ERROR_DEPRECATED flag is set.
NOTE: Build systems that use the macro WARN_DEPRECATED must migrate to
using ERROR_DEPRECATED, otherwise deprecated API usage will no longer
trigger a build error.
Change-Id: I843bceef6bde979af7e9b51dddf861035ec7965a
This patch adds an optional API to the platform port:
void plat_error_handler(int err) __dead2;
The platform error handler is called when there is a specific error
condition after which Trusted Firmware cannot continue. While panic()
simply prints the crash report (if enabled) and spins, the platform
error handler can be used to hand control over to the platform port
so it can perform specific bookeeping or post-error actions (for
example, reset the system). This function must not return.
The parameter indicates the type of error using standard codes from
errno.h. Possible errors reported by the generic code are:
-EAUTH : a certificate or image could not be authenticated
(when Trusted Board Boot is enabled)
-ENOENT : the requested image or certificate could not be found
or an IO error was detected
-ENOMEM : resources exhausted. Trusted Firmware does not use
dynamic memory, so this error is usually an indication
of an incorrect array size
A default weak implementation of this function has been provided.
It simply implements an infinite loop.
Change-Id: Iffaf9eee82d037da6caa43b3aed51df555e597a3
This patch is a complete rework of the main Makefile. Functionality
remains the same but the code has been reorganized in sections in
order to improve readability and facilitate adding future extensions.
A new file 'build_macros.mk' has been created and will contain common
definitions (variables, macros, etc) that may be used from the main
Makefile and other platform specific makefiles.
A new macro 'FIP_ADD_IMG' has been introduced and it will allow the
platform to specify binary images and the necessary checks for a
successful build. Platforms that require a BL30 image no longer need
to specify the NEED_BL30 option. The main Makefile is now completely
unaware of additional images not built as part of Trusted Firmware,
like BL30. It is the platform responsibility to specify images using
the macro 'FIP_ADD_IMG'. Juno uses this macro to include the BL30
image in the build.
BL33 image is specified in the main Makefile to preserve backward
compatibility with the NEED_BL33 option. Otherwise, platform ports
that rely on the definition of NEED_BL33 might break.
All Trusted Board Boot related definitions have been moved to a
separate file 'tbbr_tools.mk'. The main Makefile will include this
file unless the platform indicates otherwise by setting the variable
'INCLUDE_TBBR_MK := 0' in the corresponding platform.mk file. This
will keep backward compatibility but ideally each platform should
include the corresponding TBB .mk file in platform.mk.
Change-Id: I35e7bc9930d38132412e950e20aa2a01e2b26801
This patch redefines the values of IO_FAIL, IO_NOT_SUPPORTED and
IO_RESOURCES_EXHAUSTED to match the corresponding definitions in
errno.h:
#define IO_FAIL (-ENOENT)
#define IO_NOT_SUPPORTED (-ENODEV)
#define IO_RESOURCES_EXHAUSTED (-ENOMEM)
NOTE: please note that the IO_FAIL, IO_NOT_SUPPORTED and
IO_RESOURCES_EXHAUSTED definitions are considered deprecated
and their usage should be avoided. Callers should rely on errno.h
definitions when checking the return values of IO functions.
Change-Id: Ic8491aa43384b6ee44951ebfc053a3ded16a80be
This patch adds an optional API to the platform port:
void bl1_plat_prepare_exit(void);
This function is called prior to exiting BL1 in response to the
RUN_IMAGE_SMC request raised by BL2. It should be used to perform
platform specific clean up or bookkeeping operations before
transferring control to the next image.
A weak empty definition of this function has been provided to
preserve platform backwards compatibility.
Change-Id: Iec09697de5c449ae84601403795cdb6aca166ba1
When a platform port does not define PLAT_PERCPU_BAKERY_LOCK_SIZE, the total
memory that should be allocated per-cpu to accommodate all bakery locks is
calculated by the linker in bl31.ld.S. The linker stores this value in the
__PERCPU_BAKERY_LOCK_SIZE__ linker symbol. The runtime value of this symbol is
different from the link time value as the symbol is relocated into the current
section (.bss). This patch fixes this issue by marking the symbol as ABSOLUTE
which allows it to retain its correct value even at runtime.
The description of PLAT_PERCPU_BAKERY_LOCK_SIZE in the porting-guide.md has been
made clearer as well.
Change-Id: Ia0cfd42f51deaf739d792297e60cad5c6e6e610b
This patch unifies the bakery lock api's across coherent and normal
memory implementation of locks by using same data type `bakery_lock_t`
and similar arguments to functions.
A separate section `bakery_lock` has been created and used to allocate
memory for bakery locks using `DEFINE_BAKERY_LOCK`. When locks are
allocated in normal memory, each lock for a core has to spread
across multiple cache lines. By using the total size allocated in a
separate cache line for a single core at compile time, the memory for
other core locks is allocated at link time by multiplying the single
core locks size with (PLATFORM_CORE_COUNT - 1). The normal memory lock
algorithm now uses lock address instead of the `id` in the per_cpu_data.
For locks allocated in coherent memory, it moves locks from
tzfw_coherent_memory to bakery_lock section.
The bakery locks are allocated as part of bss or in coherent memory
depending on usage of coherent memory. Both these regions are
initialised to zero as part of run_time_init before locks are used.
Hence, bakery_lock_init() is made an empty function as the lock memory
is already initialised to zero.
The above design lead to the removal of psci bakery locks from
non_cpu_power_pd_node to psci_locks.
NOTE: THE BAKERY LOCK API WHEN USE_COHERENT_MEM IS NOT SET HAS CHANGED.
THIS IS A BREAKING CHANGE FOR ALL PLATFORM PORTS THAT ALLOCATE BAKERY
LOCKS IN NORMAL MEMORY.
Change-Id: Ic3751c0066b8032dcbf9d88f1d4dc73d15f61d8b
ARM TF configures all interrupts as non-secure except those which
are present in irq_sec_array. This patch updates the irq_sec_array
with the missing secure interrupts for ARM platforms.
It also updates the documentation to be inline with the latest
implementation.
FixesARM-software/tf-issues#312
Change-Id: I39956c56a319086e3929d1fa89030b4ec4b01fcc
This patch corrects some typos in the platform migration guide. More
importantly, the commit ID of the patch that implements migration of ARM
Reference platforms to the new platform API has been corrected.
Change-Id: Ib0109ea42c3d2bad2c6856ab725862652da7f3c8
This patch adds the necessary documentation updates to porting_guide.md
for the changes in the platform interface mandated as a result of the new
PSCI Topology and power state management frameworks. It also adds a
new document `platform-migration-guide.md` to aid the migration of existing
platform ports to the new API.
The patch fixes the implementation and callers of
plat_is_my_cpu_primary() to use w0 as the return parameter as implied by
the function signature rather than x0 which was used previously.
Change-Id: Ic11e73019188c8ba2bd64c47e1729ff5acdcdd5b
Since there is a unique warm reset entry point, the FVP and Juno
port can use a single mailbox instead of maintaining one per core.
The mailbox gets programmed only once when plat_setup_psci_ops()
is invoked during PSCI initialization. This means mailbox is not
zeroed out during wakeup.
Change-Id: Ieba032a90b43650f970f197340ebb0ce5548d432
This patch adds support to the Juno and FVP ports for composite power states
with both the original and extended state-id power-state formats. Both the
platform ports use the recommended state-id encoding as specified in
Section 6.5 of the PSCI specification (ARM DEN 0022C). The platform build flag
ARM_RECOM_STATE_ID_ENC is used to include this support.
By default, to maintain backwards compatibility, the original power state
parameter format is used and the state-id field is expected to be zero.
Change-Id: Ie721b961957eaecaca5bf417a30952fe0627ef10
This patch defines deprecated platform APIs to enable Trusted
Firmware components like Secure Payload and their dispatchers(SPD)
to continue to build and run when platform compatibility is disabled.
This decouples the migration of platform ports to the new platform API
from SPD and enables them to be migrated independently. The deprecated
platform APIs defined in this patch are : platform_get_core_pos(),
platform_get_stack() and platform_set_stack().
The patch also deprecates MPIDR based context management helpers like
cm_get_context_by_mpidr(), cm_set_context_by_mpidr() and cm_init_context().
A mechanism to deprecate APIs and identify callers of these APIs during
build is introduced, which is controlled by the build flag WARN_DEPRECATED.
If WARN_DEPRECATED is defined to 1, the users of the deprecated APIs will be
flagged either as a link error for assembly files or compile time warning
for C files during build.
Change-Id: Ib72c7d5dc956e1a74d2294a939205b200f055613
