Merge pull request #732 from dp-arm/dp/pmf-doc ...

PMF: Add documentation

PMF: Add documentation ...

Add a Performance Measurement Framework (PMF) section
to the firmware design document.

Change-Id: I5953bd3b1067501f190164c8827d2b0d8022fc0b
Signed-off-by: dp-arm <dimitris.papastamos@arm.com>

AArch32: Update firmware-design.md ...

This patch updates the firmware-design.md for AArch32 related changes.

Change-Id: Idf392a44861ab9c1f59f3de4f3435f508b17c678

Docs: Add the PSCI library integration guide ...

This patch adds the PSCI library integration guide for AArch32 ARMv8-A
systems `psci-lib-integration-guide.md` to the documentation. The
patch also adds appropriate reference to the new document in
the `firmware-design.md` document.

Change-Id: I2d5b5c6b612452371713399702e318e3c73a8ee0

PSCI: Add support for PSCI NODE_HW_STATE API ...

This patch adds support for NODE_HW_STATE PSCI API by introducing a new
PSCI platform hook (get_node_hw_state). The implementation validates
supplied arguments, and then invokes this platform-defined hook and
returns its result to the caller. PSCI capabilities are updated
accordingly.

Also updates porting and firmware design guides.

Change-Id: I808e55bdf0c157002a7c104b875779fe50a68a30

Merge pull request #661 from dp-arm/master ...

Replace fip_create with fiptool

Replace fip_create with fiptool ...

fiptool provides a more consistent and intuitive interface compared to
the fip_create program.  It serves as a better base to build on more
features in the future.

fiptool supports various subcommands.  Below are the currently
supported subcommands:

1) info   - List the images contained in a FIP file.
2) create - Create a new FIP file with the given images.
3) update - Update an existing FIP with the given images.
4) unpack - Extract a selected set or all the images from a FIP file.
5) remove - Remove images from a FIP file.  This is a new command that
   was not present in fip_create.

To create a new FIP file, replace "fip_create" with "fiptool create".

To update a FIP file, replace "fip_create" with "fiptool update".

To dump the contents of a FIP file, replace "fip_create --dump" with
"fiptool info".

A compatibility script that emulates the basic functionality of
fip_create is provided.  Existing scripts might or might not work with
the compatibility script.  Users are strongly encouraged to migrate to
fiptool.

Fixes ARM-Software/tf-issues#87
Fixes ARM-Software/tf-issues#108
Fixes ARM-Software/tf-issues#361

Change-Id: I7ee4da7ac60179cc83cf46af890fd8bc61a53330

Documentation for SEPARATE_CODE_AND_RODATA build flag ...

This patch documents the effect, cost and benefits of the
SEPARATE_CODE_AND_RODATA build flag.

Change-Id: Ic8daf0563fa6335930ad6c70b9c35f678e84d39d

Introduce `el3_runtime` and `PSCI` libraries ...

This patch moves the PSCI services and BL31 frameworks like context
management and per-cpu data into new library components `PSCI` and
`el3_runtime` respectively. This enables PSCI to be built independently from
BL31. A new `psci_lib.mk` makefile is introduced which adds the relevant
PSCI library sources and gets included by `bl31.mk`. Other changes which
are done as part of this patch are:

* The runtime services framework is now moved to the `common/` folder to
  enable reuse.
* The `asm_macros.S` and `assert_macros.S` helpers are moved to architecture
  specific folder.
* The `plat_psci_common.c` is moved from the `plat/common/aarch64/` folder
  to `plat/common` folder. The original file location now has a stub which
  just includes the file from new location to maintain platform compatibility.

Most of the changes wouldn't affect platform builds as they just involve
changes to the generic bl1.mk and bl31.mk makefiles.

NOTE: THE `plat_psci_common.c` FILE HAS MOVED LOCATION AND THE STUB FILE AT
THE ORIGINAL LOCATION IS NOW DEPRECATED. PLATFORMS SHOULD MODIFY THEIR
MAKEFILES TO INCLUDE THE FILE FROM THE NEW LOCATION.

Change-Id: I6bd87d5b59424995c6a65ef8076d4fda91ad5e86

Introduce SEPARATE_CODE_AND_RODATA build flag ...

At the moment, all BL images share a similar memory layout: they start
with their code section, followed by their read-only data section.
The two sections are contiguous in memory. Therefore, the end of the
code section and the beginning of the read-only data one might share
a memory page. This forces both to be mapped with the same memory
attributes. As the code needs to be executable, this means that the
read-only data stored on the same memory page as the code are
executable as well. This could potentially be exploited as part of
a security attack.

This patch introduces a new build flag called
SEPARATE_CODE_AND_RODATA, which isolates the code and read-only data
on separate memory pages. This in turn allows independent control of
the access permissions for the code and read-only data.

This has an impact on memory footprint, as padding bytes need to be
introduced between the code and read-only data to ensure the
segragation of the two. To limit the memory cost, the memory layout
of the read-only section has been changed in this case.

 - When SEPARATE_CODE_AND_RODATA=0, the layout is unchanged, i.e.
   the read-only section still looks like this (padding omitted):

   |        ...        |
   +-------------------+
   | Exception vectors |
   +-------------------+
   |  Read-only data   |
   +-------------------+
   |       Code        |
   +-------------------+ BLx_BASE

   In this case, the linker script provides the limits of the whole
   read-only section.

 - When SEPARATE_CODE_AND_RODATA=1, the exception vectors and
   read-only data are swapped, such that the code and exception
   vectors are contiguous, followed by the read-only data. This
   gives the following new layout (padding omitted):

   |        ...        |
   +-------------------+
   |  Read-only data   |
   +-------------------+
   | Exception vectors |
   +-------------------+
   |       Code        |
   +-------------------+ BLx_BASE

   In this case, the linker script now exports 2 sets of addresses
   instead: the limits of the code and the limits of the read-only
   data. Refer to the Firmware Design guide for more details. This
   provides platform code with a finer-grained view of the image
   layout and allows it to map these 2 regions with the appropriate
   access permissions.

Note that SEPARATE_CODE_AND_RODATA applies to all BL images.

Change-Id: I936cf80164f6b66b6ad52b8edacadc532c935a49

BL1: Add linker symbol identifying end of ROM content ...

This patch adds a new linker symbol in BL1's linker script named
'__BL1_ROM_END__', which marks the end of BL1's ROM content. This
covers BL1's code, read-only data and read-write data to relocate
in Trusted SRAM. The address of this new linker symbol is exported
to C code through the 'BL1_ROM_END' macro.

The section related to linker symbols in the Firmware Design guide
has been updated and improved.

Change-Id: I5c442ff497c78d865ffba1d7d044511c134e11c7

Add optional PSCI STAT residency & count functions ...

This patch adds following optional PSCI STAT functions:

- PSCI_STAT_RESIDENCY: This call returns the amount of time spent
  in power_state in microseconds, by the node represented by the
  `target_cpu` and the highest level of `power_state`.

- PSCI_STAT_COUNT: This call returns the number of times a
  `power_state` has been used by the node represented by the
  `target_cpu` and the highest power level of `power_state`.

These APIs provides residency statistics for power states that has
been used by the platform. They are implemented according to v1.0
of the PSCI specification.

By default this optional feature is disabled in the PSCI
implementation. To enable it, set the boolean flag
`ENABLE_PSCI_STAT` to 1. This also sets `ENABLE_PMF` to 1.

Change-Id: Ie62e9d37d6d416ccb1813acd7f616d1ddd3e8aff

Enable SCR_EL3.SIF bit ...

This patch enables the SCR_EL3.SIF (Secure Instruction Fetch) bit in BL1 and
BL31 common architectural setup code. When in secure state, this disables
instruction fetches from Non-secure memory.

NOTE: THIS COULD BREAK PLATFORMS THAT HAVE SECURE WORLD CODE EXECUTING FROM
NON-SECURE MEMORY, BUT THIS IS CONSIDERED UNLIKELY AND IS A SERIOUS SECURITY
RISK.

Fixes ARM-Software/tf-issues#372

Change-Id: I684e84b8d523c3b246e9a5fabfa085b6405df319

Enable asynchronous abort exceptions during boot ...

Asynchronous abort exceptions generated by the platform during cold boot are
not taken in EL3 unless SCR_EL3.EA is set.

Therefore EA bit is set along with RES1 bits in early BL1 and BL31 architecture
initialisation. Further write accesses to SCR_EL3 preserve these bits during
cold boot.

A build flag controls SCR_EL3.EA value to keep asynchronous abort exceptions
being trapped by EL3 after cold boot or not.

For further reference SError Interrupts are also known as asynchronous external
aborts.

On Cortex-A53 revisions below r0p2, asynchronous abort exceptions are taken in
EL3 whatever the SCR_EL3.EA value is.

Fixes arm-software/tf-issues#368

Signed-off-by: Gerald Lejeune <gerald.lejeune@st.com>

Simplify Firmware Design document ...

The Firmware Design document is meant to provide a general overview
of the Trusted Firmware code. Although it is useful to provide some
guidance around the responsibilities of the platform layer, it should
not provide too much platform specific implementation details. Right
now, some sections are too tied to the implementation on ARM
platforms. This makes the Firmware Design document harder to digest.

This patch simplifies this aspect of the Firmware Design document.
The sections relating the platform initialisations performed by the
different BL stages have been simplified and the extra details about
the ARM platforms implementation have been moved to the Porting Guide
when appropriate.

This patch also provides various documentation fixes and additions
in the Firmware Design and Platform Porting Guide. In particular:

 - Update list of SMCs supported by BL1.

 - Remove MMU setup from architectural inits, as it is actually
   performed by platform code.

 - Similarly, move runtime services initialisation, BL2 image
   initialization and BL33 execution out of the platform
   initialisation paragraph.

 - List SError interrupt unmasking as part of BL1 architectural
   initialization.

 - Mention Trusted Watchdog enabling in BL1 on ARM platforms.

 - Fix order of steps in "BL2 image load and execution" section.

 - Refresh section about GICv3/GICv2 drivers initialisation on
   ARM platforms.

Change-Id: I32113c4ffdc26687042629cd8bbdbb34d91e3c14

Improve memory layout documentation ...

This patch adds a brief explanation of the top/bottom load approach
to the Firmware Design guide and how Trusted Firmware keeps track of
the free memory at boot time. This will help platform developers to
avoid unexpected results in the memory layout.

Fixes ARM-software/tf-issues#319

Change-Id: I04be7e24c1f3b54d28cac29701c24bf51a5c00ad

Doc: Update out-dated info about Juno's mailbox ...

Since commit 804040d106, the Juno port has moved from per-CPU mailboxes
to a single shared one. This patch updates an out-dated reference to
the former per-CPU mailboxes mechanism in the Firmware Design.

Change-Id: I355b54156b1ace1b3df4c4416e1e8625211677fc

Documentation: Fix broken links in ToCs ...

Change-Id: I4fcdb8e813e0392c2cd3d0623698e8319b3b0593

Fixes in CPU specific operations framework doc ...

This patch fixes a couple of issues in the "CPU specific operations
framework" section in the Firmware Design document.

 * Fix broken link to the CPU Specific Build Macros document.

 * Fix the path to the cortex_a53.S file.

 * Fix power levels terminology.

Change-Id: Ib610791eaba13dab2823b7699bb63534bcd1c8fb

Miscellaneous doc fixes for v1.2 ...

Change-Id: I6f49bd779f2a4d577c6443dd160290656cdbc59b

Merge pull request #472 from danh-arm/dh/fwu-docs ...

FWU: Add documentation for Firmware Update feature

FWU: Add documentation for Firmware Update feature ...

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>

Introduce the ARM TF reset design document ...

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

Remove dashes from image names: 'BL3-x' --> 'BL3x' ...

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

Replace all SCP FW (BL0, BL3-0) references ...

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

Re-design bakery lock memory allocation and algorithm ...

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

Configure all secure interrupts on ARM platforms ...

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.

Fixes ARM-software/tf-issues#312

Change-Id: I39956c56a319086e3929d1fa89030b4ec4b01fcc

Merge pull request #324 from soby-mathew/sm/sys_suspend ...

PSCI: Add SYSTEM_SUSPEND API support

PSCI: Add SYSTEM_SUSPEND API support ...

This patch adds support for SYSTEM_SUSPEND API as mentioned in the PSCI 1.0
specification. This API, on being invoked on the last running core on a
supported platform, will put the system into a low power mode with memory
retention.

The psci_afflvl_suspend() internal API has been reused as most of the actions
to suspend a system are the same as invoking the PSCI CPU_SUSPEND API with the
target affinity level as 'system'. This API needs the 'power state' parameter
for the target low power state. This parameter is not passed by the caller of
the SYSTEM_SUSPEND API. Hence, the platform needs to implement the
get_sys_suspend_power_state() platform function to provide this information.
Also, the platform also needs to add support for suspending the system to the
existing 'plat_pm_ops' functions: affinst_suspend() and
affinst_suspend_finish().

Change-Id: Ib6bf10809cb4e9b92f463755608889aedd83cef5

Rationalize reset handling code ...

The attempt to run the CPU reset code as soon as possible after reset
results in highly complex conditional code relating to the
RESET_TO_BL31 option.

This patch relaxes this requirement a little. In the BL1, BL3-1 and
PSCI entrypoints code, the sequence of operations is now as follows:
 1) Detect whether it is a cold or warm boot;
 2) For cold boot, detect whether it is the primary or a secondary
    CPU. This is needed to handle multiple CPUs entering cold reset
    simultaneously;
 3) Run the CPU init code.

This patch also abstracts the EL3 registers initialisation done by
the BL1, BL3-1 and PSCI entrypoints into common code.

This improves code re-use and consolidates the code flows for
different types of systems.

NOTE: THE FUNCTION plat_secondary_cold_boot() IS NOW EXPECTED TO
NEVER RETURN. THIS PATCH FORCES PLATFORM PORTS THAT RELIED ON THE
FORMER RETRY LOOP AT THE CALL SITE TO MODIFY THEIR IMPLEMENTATION.
OTHERWISE, SECONDARY CPUS WILL PANIC.

Change-Id: If5ecd74d75bee700b1bd718d23d7556b8f863546