GitLab

Remove the following redundant sentence from the user guide, which
implies the user should use the TF version from the Linaro release,
which was not the intention:

"However, the rest of this document assumes that you got the
Trusted Firmware as part of the Linaro release."

Also, tidied up the grammar in this section.

Change-Id: I5dae0b68d3683e2a85a7b3c6a31222182a66f6c8

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>

`FVP_TSP_RAM_LOCATION` has been renamed into `ARM_TSP_RAM_LOCATION`.

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.

Fixes ARM-software/tf-issues#216

Change-Id: I6e0eb86f9d69569bc3980fb57e70d6da5d91a737

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

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.

Fixes ARM-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 instructions to the user-guide.md to test SYSTEM SUSPEND
on Juno.

Change-Id: Icd01d10e1c1fb14b0db880d0ff134e505f097d2b

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

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

The state-id field in the power-state parameter of a CPU_SUSPEND call can be
used to describe composite power states specific to a platform. The current PSCI
implementation does not interpret the state-id field. It relies on the target
power level and the state type fields in the power-state parameter to perform
state coordination and power management operations. The framework introduced
in this patch allows the PSCI implementation to intepret generic global states
like RUN, RETENTION or OFF from the State-ID to make global state coordination
decisions and reduce the complexity of platform ports. It adds support to
involve the platform in state coordination which facilitates the use of
composite power states and improves the support for entering standby states
at multiple power domains.

The patch also includes support for extended state-id format for the power
state parameter as specified by PSCIv1.0.

The PSCI implementation now defines a generic representation of the power-state
parameter. It depends on the platform port to convert the power-state parameter
(possibly encoding a composite power state) passed in a CPU_SUSPEND call to this
representation via the `validate_power_state()` plat_psci_ops handler. It is an
array where each index corresponds to a power level. Each entry contains the
local power state the power domain at that power level could enter.

The meaning of the local power state values is platform defined, and may vary
between levels in a single platform. The PSCI implementation constrains the
values only so that it can classify the state as RUN, RETENTION or OFF as
required by the specification:
   * zero means RUN
   * all OFF state values at all levels must be higher than all RETENTION
     state values at all levels
   * the platform provides PLAT_MAX_RET_STATE and PLAT_MAX_OFF_STATE values
     to the framework

The platform also must define the macros PLAT_MAX_RET_STATE and
PLAT_MAX_OFF_STATE which lets the PSCI implementation find out which power
domains have been requested to enter a retention or power down state. The PSCI
implementation does not interpret the local power states defined by the
platform. The only constraint is that the PLAT_MAX_RET_STATE <
PLAT_MAX_OFF_STATE.

For a power domain tree, the generic implementation maintains an array of local
power states. These are the states requested for each power domain by all the
cores contained within the domain. During a request to place multiple power
domains in a low power state, the platform is passed an array of requested
power-states for each power domain through the plat_get_target_pwr_state()
API. It coordinates amongst these states to determine a target local power
state for the power domain. A default weak implementation of this API is
provided in the platform layer which returns the minimum of the requested
power-states back to the PSCI state coordination.

Finally, the plat_psci_ops power management handlers are passed the target
local power states for each affected power domain using the generic
representation described above. The platform executes operations specific to
these target states.

The platform power management handler for placing a power domain in a standby
state (plat_pm_ops_t.pwr_domain_standby()) is now only used as a fast path for
placing a core power domain into a standby or retention state should now be
used to only place the core power domain in a standby or retention state.

The extended state-id power state format can be enabled by setting the
build flag PSCI_EXTENDED_STATE_ID=1 and it is disabled by default.

Change-Id: I9d4123d97e179529802c1f589baaa4101759d80c

Linaro produce monthly software releases for the Juno and AEMv8-FVP
platforms. These provide an integrated set of software components
that have been tested together on these platforms.

From now on, it is recommend that Trusted Firmware developers use the
Linaro releases (currently 15.06) as a baseline for the dependent
software components: normal world firmware, Linux kernel and device
tree, file system as well as any additional micro-controller firmware
required by the platform.

This patch updates the user guide to document this new process. It
changes the instructions to get the source code of the full software
stack (including Trusted Firmware) and updates the dependency build
instructions to make use of the build scripts that the Linaro releases
provide.

Change-Id: Ia8bd043f4b74f1e1b10ef0d12cc8a56ed3c92b6e

This patch updates the user guide, adding instructions to build the
Trusted Firmware with Trusted Board Support using the new framework.

It also provides documentation about the framework itself, including
a detailed section about the TBBR implementation using the framework.

Change-Id: I0849fce9c5294cd4f52981e7a8423007ac348ec6

This patch modifies the Trusted Board Boot implementation to use
the new authentication framework, making use of the authentication
module, the cryto module and the image parser module to
authenticate the images in the Chain of Trust.

A new function 'load_auth_image()' has been implemented. When TBB
is enabled, this function will call the authentication module to
authenticate parent images following the CoT up to the root of
trust to finally load and authenticate the requested image.

The platform is responsible for picking up the right makefiles to
build the corresponding cryptographic and image parser libraries.
ARM platforms use the mbedTLS based libraries.

The platform may also specify what key algorithm should be used
to sign the certificates. This is done by declaring the 'KEY_ALG'
variable in the platform makefile. FVP and Juno use ECDSA keys.

On ARM platforms, BL2 and BL1-RW regions have been increased 4KB
each to accommodate the ECDSA code.

REMOVED BUILD OPTIONS:

  * 'AUTH_MOD'

Change-Id: I47d436589fc213a39edf5f5297bbd955f15ae867

This patch extends the platform port by adding an API that returns
either the Root of Trust public key (ROTPK) or its hash. This is
usually stored in ROM or eFUSE memory. The ROTPK returned must be
encoded in DER format according to the following ASN.1 structure:

    SubjectPublicKeyInfo  ::=  SEQUENCE  {
        algorithm           AlgorithmIdentifier,
        subjectPublicKey    BIT STRING
    }

In case the platform returns a hash of the key:

    DigestInfo  ::= SEQUENCE {
        digestAlgorithm     AlgorithmIdentifier,
        keyDigest           OCTET STRING
    }

An implementation for ARM development platforms is provided in this
patch. When TBB is enabled, the ROTPK hash location must be specified
using the build option 'ARM_ROTPK_LOCATION'. Available options are:

    - 'regs' : return the ROTPK hash stored in the Trusted
      root-key storage registers.

    - 'devel_rsa' : return a ROTPK hash embedded in the BL1 and
      BL2 binaries. This hash has been obtained from the development
      RSA public key located in 'plat/arm/board/common/rotpk'.

On FVP, the number of MMU tables has been increased to map and
access the ROTPK registers.

A new file 'board_common.mk' has been added to improve code sharing
in the ARM develelopment platforms.

Change-Id: Ib25862e5507d1438da10773e62bd338da8f360bf

This patch adds a boolean build option 'SAVE_KEYS' to indicate the
certificate generation tool that it must save the private keys used
to establish the chain of trust. This option depends on 'CREATE_KEYS'
to be enabled. Default is '0' (do not save).

Because the same filenames are used as outputs to save the keys,
they are no longer a dependency to the cert_tool. This dependency
has been removed from the Makefile.

Documentation updated accordingly.

Change-Id: I67ab1c2b1f8a25793f0de95e8620ce7596a6bc3b

The 'ARM_TSP_RAM_LOCATION_ID' option specified in the user guide
corresponds to the internal definition not visible to the final
user. The proper build option is 'ARM_TSP_RAM_LOCATION'. This
patch fixes it.

Fixes ARM-software/tf-issues#308

Change-Id: Ica8cb72c0c5e8b3503f60b5357d16698e869b1bd

This patch introduces a new platform build option, called
PROGRAMMABLE_RESET_ADDRESS, which tells whether the platform has
a programmable or fixed reset vector address.

If the reset vector address is fixed then the code relies on the
platform_get_entrypoint() mailbox mechanism to figure out where
it is supposed to jump. On the other hand, if it is programmable
then it is assumed that the platform code will program directly
the right address into the RVBAR register (instead of using the
mailbox redirection) so the mailbox is ignored in this case.

Change-Id: If59c3b11fb1f692976e1d8b96c7e2da0ebfba308

Move up the version numbers in the user guide of:

 * DS-5 (to v5.21)
 * EDK2 (to v3.0)
 * Linux Kernel (to 1.6-Juno)
 * Linaro file-system (to 15.03)
 * Juno SCP binary (to v1.7.0 within board recovery image 0.11.3).

Change-Id: Ieb09e633acc2b33823ddf35f77f44e7da60b99ba

There has been a breaking change in the communication protocols used
between the AP cores and the SCP on CSS based platforms like Juno.
This means both the AP Trusted Firmware and SCP firmware must be
updated at the same time.

In case the user forgets to update the SCP ROM firmware, this patch
detects when it still uses the previous version of the communication
protocol. It will then output a comprehensive error message that helps
trouble-shoot the issue.

Change-Id: I7baf8f05ec0b7d8df25e0ee53df61fe7be0207c2

Update the User Guide, Porting Guide and Firmware Design documents
to align them with the recent changes made to the FVP and Juno
platform ports.

Also fix some other historical inaccuracies.

Change-Id: I37aba4805f9044b1a047996d3e396c75f4a09176

Even though both CCI-400 and CCI-500 IPs have different configurations
with respect to the number and types of supported interfaces, their
register offsets and programming sequences are similar. This patch
creates a common driver for enabling and disabling snoop transactions
and DVMs with both the IPs.

New platform ports which implement one of these IPs should use this
common driver. Existing platform ports which implement CCI-400 should
migrate to the common driver as the standalone CCI-400 will be
deprecated in the future.

Change-Id: I3ccd0eb7b062922d2e4a374ff8c21e79fa357556

The 'libssl-dev' package must be installed on the host to build the
certificate generation tool. This patch adds it to the list of
required tools in the User Guide.

Change-Id: I018381fb14b7c2d2bd6f2b7929aaad0571f7eb2e

The command line options specified in the User Guide to run the AEMv8 Base FVP
with the legacy VE memory map apply only when the model is configured to use GIC
v2.0. This patch adds the 'gicv3.gicv2-only=1' to the command line to ensure
that the right version of GIC is used.

Change-Id: I34c44e19fd42c29818b734ac8f6aa9bf97b4e891

This patch updates the user-guide.md with the various build options related to
Trusted Board Boot and steps to build a FIP image which includes this
support. It also adds a trusted-board-boot.md which describes the scope and
design of this feature.

Change-Id: Ifb421268ebf7e06a135684c8ebb04c94835ce061

Move up the version numbers in the user guide of:

* DS-5 (to v5.20)
* EDK2 (to v2.1-rc0)
* Linux Kernel (to 1.3-Juno)
* Linaro file-system (to 14.12)
* Juno SCP binary (to 1.5.0-rc0 within board recovery image 0.10.1).
  Also remove duplicate information that is available from the
  ARM Connected Community website.
* Base FVP (to 6.2)
* Foundation FVP (to 9.1). Also update the name of the Foundation
  FVP binary since it has changed since version 2.1.
Co-Authored-By: Dan Handley <dan.handley@arm.com>

Change-Id: I1cf2f2b1a3f1b997ac905a4ab440876d265698c0

Change-Id: Iaf9d6305edc478d39cf1b37c8a70ccdf723e8ef9

This patch provides an option to specify a interrupt routing model
where non-secure interrupts (IRQs) are routed to EL3 instead of S-EL1.
When such an interrupt occurs, the TSPD arranges a return to
the normal world after saving any necessary context. The interrupt
routing model to route IRQs to EL3 is enabled only during STD SMC
processing. Thus the pre-emption of S-EL1 is disabled during Fast SMC
and Secure Interrupt processing.

A new build option TSPD_ROUTE_NS_INT_EL3 is introduced to change
the non secure interrupt target execution level to EL3.

Fixes ARM-software/tf-issues#225

Change-Id: Ia1e779fbbb6d627091e665c73fa6315637cfdd32