Merge changes I10b5cc17,I382d599f into integration
* changes:
docs(prerequisites): add `--no-save` to `npm install`
fix(hooks): downgrade `package-lock.json` version
diff --git a/Makefile b/Makefile
index 219413e..2376b9a 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,7 @@
# Trusted Firmware Version
#
VERSION_MAJOR := 2
-VERSION_MINOR := 4
+VERSION_MINOR := 5
# Default goal is build all images
.DEFAULT_GOAL := all
diff --git a/docs/change-log.rst b/docs/change-log.rst
index ec88df9..4e7c96f 100644
--- a/docs/change-log.rst
+++ b/docs/change-log.rst
@@ -4,6 +4,675 @@
This document contains a summary of the new features, changes, fixes and known
issues in each release of Trusted Firmware-A.
+Version 2.5
+-----------
+
+New Features
+^^^^^^^^^^^^
+
+- Architecture support
+ - Added support for speculation barrier(``FEAT_SB``) for non-Armv8.5
+ platforms starting from Armv8.0
+ - Added support for Activity Monitors Extension version 1.1(``FEAT_AMUv1p1``)
+ - Added helper functions for Random number generator(``FEAT_RNG``) registers
+ - Added support for Armv8.6 Multi-threaded PMU extensions (``FEAT_MTPMU``)
+ - Added support for MTE Asymmetric Fault Handling extensions(``FEAT_MTE3``)
+ - Added support for Privileged Access Never extensions(``FEAT_PANx``)
+
+- Bootloader images
+ - Added PIE support for AArch32 builds
+ - Enable Trusted Random Number Generator service for BL32(sp_min)
+
+- Build System
+ - Added build option for Arm Feature Modifiers
+
+- Drivers
+ - Added support for interrupts in TZC-400 driver
+
+ - Broadcom
+ - Added support for I2C, MDIO and USB drivers
+
+ - Marvell
+ - Added support for secure read/write of dfc register-set
+ - Added support for thermal sensor driver
+ - Implement a3700_core_getc API in console driver
+ - Added rx training on 10G port
+
+ - Marvell Mochi
+ - Added support for cn913x in PCIe mode
+
+ - Marvell Armada A8K
+ - Added support for TRNG-IP-76 driver and accessing RNG register
+
+ - Mediatek MT8192
+ - Added support for following drivers
+ - MPU configuration for SCP/PCIe
+ - SPM suspend
+ - Vcore DVFS
+ - LPM
+ - PTP3
+ - UART save and restore
+ - Power-off
+ - PMIC
+ - CPU hotplug and MCDI support
+ - SPMC
+ - MPU
+
+ - Mediatek MT8195
+ - Added support for following drivers
+ - GPIO, NCDI, SPMC drivers
+ - Power-off
+ - CPU hotplug, reboot and MCDI
+ - Delay timer and sys timer
+ - GIC
+
+ - NXP
+ - Added support for
+ - non-volatile storage API
+ - chain of trust and trusted board boot using two modes: MBEDTLS and CSF
+ - fip-handler necessary for DDR initialization
+ - SMMU and console drivers
+ - crypto hardware accelerator driver
+ - following drivers: SD, EMMC, QSPI, FLEXSPI, GPIO, GIC, CSU, PMU, DDR
+ - NXP Security Monitor and SFP driver
+ - interconnect config APIs using ARM CCN-CCI driver
+ - TZC APIs to configure DDR region
+ - generic timer driver
+ - Device configuration driver
+
+ - IMX
+ - Added support for image loading and io-storage driver for TBBR fip booting
+
+ - Renesas
+ - Added support for PFC and EMMC driver
+
+ - RZ Family:
+ - G2N, G2E and G2H SoCs
+ - Added support for watchdog, QoS, PFC and DRAM initialization
+
+ - RZG Family:
+ - G2M
+ - Added support for QoS and DRAM initialization
+
+ - Xilinx
+ - Added JTAG DCC support for Versal and ZynqMP SoC family.
+
+- Libraries
+ - C standard library
+ - Added support to print ``%`` in ``snprintf()`` and ``printf()`` APIs
+ - Added support for strtoull, strtoll, strtoul, strtol APIs from FreeBSD project
+
+ - CPU support
+ - Added support for
+ - Cortex_A78C CPU
+ - Makalu ELP CPU
+ - Makalu CPU
+ - Matterhorn CPU
+ - Neoverse-N2 CPU
+
+ - CPU Errata
+ - Arm Cortex-A76: Added workaround for erratum 1946160
+
+ - Arm Cortex-A77: Added workaround for erratum 1946167
+
+ - Arm Cortex-A78: Added workaround for erratum 1941498 and 1951500
+
+ - Arm Neoverse-N1: Added workaround for erratum 1946160
+
+ - Flattened device tree(libfdt)
+ - Added support for wrapper function to read UUIDs in string format from dtb
+
+- Platforms
+ - Added support for MediaTek MT8195
+ - Added support for Arm RD-N2 board
+
+ - Allwinner
+ - Added support for H616 SoC
+
+ - Arm
+ - Added support for GPT parser
+ - Protect GICR frames for fused/unused cores
+
+ - Arm Morello
+ - Added VirtIO network device to Morello FVP fdts
+
+ - Arm RD-N2
+ - Added support for variant 1 of RD-N2 platform
+ - Enable AMU support
+
+ - Arm RD-V1
+ - Enable AMU support
+
+ - Arm SGI
+ - Added support for platform variant build option
+
+ - Arm TC0
+ - Added Matterhorn ELP CPU support
+ - Added support for opteed
+
+ - Arm Juno
+ - Added support to use hw_config in BL31
+ - Use TRNG entropy source for SMCCC TRNG interface
+ - Condition Juno entropy source with CRC instructions
+
+ - Marvell Mochi
+ - Added support for detection of secure mode
+
+ - Marvell ARMADA
+ - Added support for new compile option A3720_DB_PM_WAKEUP_SRC
+ - Added support doing system reset via CM3 secure coprocessor
+ - Made several makefile enhancements required to build WTMI_MULTI_IMG and TIMDDRTOOL
+ - Added support for building DOIMAGETOOL tool
+ - Added new target mrvl_bootimage
+
+ - Mediatek MT8192
+ - Added support for rtc power off sequence
+
+ - Mediatek MT8195
+ - Added support for SiP service
+
+ - STM32MP1
+ - Added support for
+ - Seeed ODYSSEY SoM and board
+ - SDMMC2 and I2C2 pins in pinctrl
+ - I2C2 peripheral in DTS
+ - PIE for BL32
+ - TZC-400 interrupt managament
+ - Linux Automation MC-1 board
+
+ - Renesas RZG
+ - Added support for identifying EK874 RZ/G2E board
+ - Added support for identifying HopeRun HiHope RZ/G2H and RZ/G2H boards
+
+ - Rockchip
+ - Added support for stack protector
+
+ - QEMU
+ - Added support for ``max`` CPU
+ - Added Cortex-A72 support to ``virt`` platform
+ - Enabled trigger reboot from secure pl061
+
+ - QEMU SBSA
+ - Added support for sbsa-ref Embedded Controller
+
+ - NXP
+ - Added support for warm reset to retain ddr content
+ - Added support for image loader necessary for loading fip image
+
+ - lx2160a SoC Family
+ - Added support for
+ - new platform lx2160a-aqds
+ - new platform lx2160a-rdb
+ - new platform lx2162a-aqds
+ - errata handling
+
+ - IMX imx8mm
+ - Added support for trusted board boot
+
+ - TI K3
+ - Added support for lite device board
+ - Enabled Cortex-A72 erratum 1319367
+ - Enabled Cortex-A53 erratum 1530924
+
+ - Xilinx ZynqMP
+ - Added support for PS and system reset on WDT restart
+ - Added support for error management
+ - Enable support for log messages necessary for debug
+ - Added support for PM API SMC call for efuse and register access
+
+- Processes
+ - Introduced process for platform deprecation
+ - Added documentation for TF-A threat model
+ - Provided a copy of the MIT license to comply with the license
+ requirements of the arm-gic.h source file (originating from the Linux
+ kernel project and re-distributed in TF-A).
+
+- Services
+ - Added support for TRNG firmware interface service
+
+ - Arm
+ - Added SiP service to configure Ethos-N NPU
+
+ - SPMC
+ - Added documentation for SPM(Hafnium) SMMUv3 driver
+
+ - SPMD
+ - Added support for
+ - FFA_INTERRUPT forwading ABI
+ - FFA_SECONDARY_EP_REGISTER ABI
+ - FF-A v1.0 boot time power management, SPMC secondary core boot and
+ early run-time power management
+
+- Tools
+
+ - FIPTool
+ - Added mechanism to allow platform specific image UUID
+
+ - git hooks
+ - Added support for conventional commits through commitlint hook,
+ commitizen hook and husky configuration files.
+
+ - NXP tool
+ - Added support for a tool that creates pbl file from BL2
+
+ - Renesas RZ/G2
+ - Added tool support for creating bootparam and cert_header images
+
+ - CertCreate
+ - Added support for platform-defined certificates, keys, and extensions using
+ the platform's makefile
+
+ - shared tools
+ - Added EFI_GUID representation to uuid helper data structure
+
+Changed
+^^^^^^^
+
+- Common components
+ - Print newline after hex address in aarch64 el3_panic function
+ - Use proper ``#address-cells`` and ``#size-cells`` for reserved-memory in dtbs
+
+- Drivers
+
+ - Move SCMI driver from ST platform directory and make it common to all platforms
+
+ - Arm GICv3
+ - Shift eSPI register offset in GICD_OFFSET_64()
+ - Use mpidr to probe GICR for current CPU
+
+ - Arm TZC-400
+ - Adjust filter tag if it set to FILTER_BIT_ALL
+
+ - Cadence
+ - Enhance UART driver APIs to put characters to fifo
+
+ - Mediatek MT8192
+ - Move timer driver to common folder
+ - Enhanced sys_cirq driver to add more IC services
+
+ - Renesas
+ - Move ddr and delay driver to common directory
+
+ - Renesas rcar
+ - Treat log as device memory in console driver
+
+ - Renesas RZ Family:
+ - G2N and G2H SoCs
+ - Select MMC_CH1 for eMMC channel
+
+ - Marvell
+ - Added support for checking if TRNG unit is present
+
+ - Marvell A3K
+ - Set TXDCLK_2X_SEL bit during PCIe initialization
+ - Set mask parameter for every reg_set call
+
+ - Marvell Mochi
+ - Added missing stream IDs configurations
+
+ - MbedTLS
+ - Migrated to Mbed TLS v2.26.0
+
+ - IMX imx8mp
+ - Change the bl31 physical load address
+
+ - QEMU SBSA
+ - Enable secure variable storage
+
+ - SCMI
+ - Update power domain protocol version to 2.0
+
+ - STM32
+ - Remove dead code from nand FMC driver
+
+- Libraries
+ - C Standard Library
+ - Use macros to reduce duplicated code between snprintf and printf
+
+ - CPU support
+ - Sanity check pointers before use in AArch32 builds
+
+ - Arm Cortex-A78
+ - Remove rainier cpu workaround for errata 1542319
+
+ - Arm Makalu ELP
+ - Added "_arm" suffix to Makalu ELP CPU lib
+
+
+- Miscellaneous
+ - Editorconfig
+ - set max line length to 100
+
+- Platforms
+ - Allwinner
+ - Added reserved-memory node to DT
+ - Express memmap more dynamically
+ - Move SEPARATE_NOBITS_REGION to platforms
+ - Limit FDT checks to reduce code size
+ - Use CPUIDLE hardware when available
+ - Allow conditional compilation of SCPI and native PSCI ops
+ - Always use a 3MHz RSB bus clock
+ - Enable workaround for Cortex-A53 erratum 1530924
+ - Fixed non-default PRELOADED_BL33_BASE
+ - Leave CPU power alone during BL31 setup
+ - Added several psci hooks enhancements to improve system shutdown/reset
+ sequence
+ - Return the PMIC to I2C mode after use
+ - Separate code to power off self and other CPUs
+ - Split native and SCPI-based PSCI implementations
+
+ - Allwinner H6
+ - Added R_PRCM security setup for H6 board
+ - Added SPC security setup for H6 board
+ - Use RSB for the PMIC connection on H6
+
+ - Arm
+ - Store UUID as a string, rather than ints
+ - Replace FIP base and size macro with a generic name
+ - Move compile time switch from source to dt file
+ - Don't provide NT_FW_CONFIG when booting hafnium
+ - Do not setup 'disabled' regulator
+ - Increase SP max size
+ - Remove false dependency of ARM_LINUX_KERNEL_AS_BL33 on RESET_TO_BL31
+ and allow it to be enabled independently
+
+ - Arm FVP
+ - Do not map GIC region in BL1 and BL2
+
+ - Arm Juno
+ - Refactor juno_getentropy() to return 64 bits on each call
+
+ - Arm Morello
+ - Remove "virtio-rng" from Morello FVP
+ - Enable virtIO P9 device for Morello fvp
+
+ - Arm RDV1
+ - Allow all PSCI callbacks on RD-V1
+ - Rename rddaniel to rdv1
+
+ - Arm RDV1MC
+ - Rename rddanielxlr to rdv1mc
+ - Initialize TZC-400 controllers
+
+ - Arm TC0
+ - Updated GICR base address
+ - Use scmi_dvfs clock index 1 for cores 4-7 through fdt
+ - Added reserved-memory node for OP-TEE fdts
+ - Enabled Theodul DSU in TC platform
+ - OP-TEE as S-EL1 SP with SPMC at S-EL2
+ - Update Matterhorm ELP DVFS clock index
+
+ - Arm SGI
+ - Allow access to TZC controller on all chips
+ - Define memory regions for multi-chip platforms
+ - Allow access to nor2 flash and system registers from S-EL0
+ - Define default list of memory regions for DMC-620 TZC
+ - Improve macros defining cper buffer memory region
+ - Refactor DMC-620 error handling SMC function id
+ - Refactor SDEI specific macros
+ - Added platform id value for RDN2 platform
+ - Refactored header file inclusions and inclusion of memory mapping
+
+ - Arm RDN2
+ - Allow usage of secure partitions on RDN2 platform
+ - Update GIC redistributor and TZC base address
+
+ - Arm SGM775
+ - Deprecate Arm sgm775 FVP platform
+
+ - Marvell
+ - Increase TX FIFO EMPTY timeout from 2ms to 3ms
+ - Update delay code to be compatible with 1200 MHz CPU
+
+ - Marvell ARMADA
+ - Postpone MSS CPU startup to BL31 stage
+ - Allow builds without MSS support
+ - Use MSS SRAM in secure mode
+ - Added missing FORCE, .PHONY and clean targets
+ - Cleanup MSS SRAM if used for copy
+ - Move definition of mrvl_flash target to common marvell_common.mk file
+ - Show informative build messages and blank lines
+
+ - Marvell ARMADA A3K
+ - Added a new target mrvl_uart which builds UART image
+ - Added checks that WTP, MV_DDR_PATH and CRYPTOPP_PATH are correctly defined
+ - Allow use of the system Crypto++ library
+ - Build $(WTMI_ENC_IMG) in $(BUILD_PLAT) directory
+ - Build intermediate files in $(BUILD_PLAT) directory
+ - Build UART image files directly in $(BUILD_UART) subdirectory
+ - Correctly set DDR_TOPOLOGY and CLOCKSPRESET for WTMI
+ - Do not use 'echo -e' in Makefile
+ - Improve 4GB DRAM usage from 3.375 GB to 3.75 GB
+ - Remove unused variable WTMI_SYSINIT_IMG from Makefile
+ - Simplify check if WTP variable is defined
+ - Split building $(WTMI_MULTI_IMG) and $(TIMDDRTOOL)
+
+ - Marvell ARMADA A8K
+ - Allow CP1/CP2 mapping at BLE stage
+
+ - Mediatek MT8183
+ - Added timer V20 compensation
+
+ - Nvidia Tegra
+ - Rename SMC API
+
+ - TI K3
+ - Make plat_get_syscnt_freq2 helper check CNT_FID0 register
+ - Fill non-message data fields in sec_proxy with 0x0
+ - Update ti_sci_msg_req_reboot ABI to include domain
+ - Enable USE_COHERENT_MEM only for the generic board
+ - Explicitly map SEC_SRAM_BASE to 0x0
+ - Use BL31_SIZE instead of computing
+ - Define the correct number of max table entries and increase SRAM size
+ to account for additional table
+
+ - Raspberry Pi4
+ - Switch to gicv2.mk and GICV2_SOURCES
+
+ - Renesas
+ - Move headers and assembly files to common folder
+
+ - Renesas rzg
+ - Added device tree memory node enhancements
+
+ - Rockchip
+ - Switch to using common gicv3.mk
+
+ - STM32MP1
+ - Set BL sizes regardless of flags
+
+ - QEMU
+ - Include gicv2.mk for compiling GICv2 source files
+ - Change DEVICE2 definition for MMU
+ - Added helper to calculate the position shift from MPIDR
+
+ - QEMU SBSA
+ - Include libraries for Cortex-A72
+ - Increase SHARED_RAM_SIZE
+ - Addes support in spm_mm for upto 512 cores
+ - Added support for topology handling
+
+ - QTI
+ - Mandate SMC implementation
+
+ - Xilinx
+ - Rename the IPI CRC checksum macro
+ - Use fno-jump-tables flag in CPPFLAGS
+
+ - Xilinx versal
+ - Added the IPI CRC checksum macro support
+ - Mark IPI calls secure/non-secure
+ - Enable sgi to communicate with linux using IPI
+ - Remove Cortex-A53 compilation
+
+ - Xilinx ZynqMP
+ - Configure counter frequency during initialization
+ - Filter errors related to clock gate permissions
+ - Implement pinctrl request/release EEMI API
+ - Reimplement pinctrl get/set config parameter EEMI API calls
+ - Reimplement pinctrl set/get function EEMI API
+ - Update error codes to match Linux and PMU Firmware
+ - Update PM version and support PM version check
+ - Update return type in query functions
+ - Added missing ids for 43/46/47dr devices
+ - Checked for DLL status before doing reset
+ - Disable ITAPDLYENA bit for zero ITAP delay
+ - Include GICv2 makefile
+ - Remove the custom crash implementation
+
+- Services
+
+ - SPMD
+ - Lock the g_spmd_pm structure
+ - Declare third cactus instance as UP SP
+ - Provide number of vCPUs and VM size for first SP
+ - Remove ``chosen`` node from SPMC manifests
+ - Move OP-TEE SP manifest DTS to FVP platform
+ - Update OP-TEE SP manifest with device-regions node
+ - Remove device-memory node from SPMC manifests
+
+ - SPM_MM
+ - Use sp_boot_info to set SP context
+
+ - SDEI
+ - Updata the affinity of shared event
+
+- Tools
+ - FIPtool
+ - Do not print duplicate verbose lines about building fiptool
+
+ - CertCreate
+ - Updated tool for platform defined certs, keys & extensions
+ - Create only requested certificates
+ - Avoid duplicates in extension stack
+
+Resolved Issues
+^^^^^^^^^^^^^^^
+- Several fixes for typos and mis-spellings in documentation
+
+- Build system
+ - Fixed ${FIP_NAME} to be rebuilt only when needed in Makefile
+ - Do not mark file targets as .PHONY target in Makefile
+
+- Drivers
+ - Authorization
+ - Avoid NV counter upgrade without certificate validation
+
+ - Arm GICv3
+ - Fixed logical issue for num_eints
+ - Limit SPI ID to avoid misjudgement in GICD_OFFSET()
+ - Fixed potential GICD context override with ESPI enabled
+
+ - Marvell A3700
+ - Fixed configuring polarity invert bits
+
+ - Arm TZC-400
+ - Correct FAIL_CONTROL Privileged bit
+ - Fixed logical error in FILTER_BIT definitions
+
+ - Renesas rcar
+ - Fixed several coding style violations reported by checkpatch
+
+- Libraries
+ - Arch helpers
+ - Fixed assertions in processing dynamic relocations for AArch64 builds
+
+ - C standard library
+ - Fixed MISRA issues in memset() ABI
+
+ - RAS
+ - Fixed bug of binary search in RAS interrupt handler
+
+- Platforms
+
+ - Arm
+ - Fixed missing copyrights in arm-gic.h file
+ - Fixed the order of header files in several dts files
+ - Fixed error message printing in board makefile
+ - Fixed bug of overriding the last node in image load helper API
+ - Fixed stdout-path in fdts files of TC0 and N1SDP platforms
+ - Turn ON/OFF redistributor in sync with GIC CPU interface ON/OFF for css platforms
+
+ - Arm FVP
+ - Fixed Generic Timer interrupt types in platform dts files
+
+ - Arm Juno
+ - Fixed parallel build issue for romlib config
+
+ - Arm SGI
+ - Fixed bug in SDEI receive event of RAS handler
+
+ - Intel Agilex
+ - Fixed PLAT_MAX_PWR_LVL value
+
+ - Marvell
+ - Fixed SPD handling in dram port
+
+ - Marvell ARMADA
+ - Fixed TRNG return SMC handling
+ - Fixed the logic used for LD selector mask
+ - Fixed MSS firmware loader for A8K family
+
+ - ST
+ - Fixed few violations reported by coverity static checks
+
+ - STM32MP1
+ - Fixed SELFREF_TO_X32 mask in ddr driver
+ - Do not keep mmc_device_info in stack
+ - Correct plat_crash_console_flush()
+
+ - QEMU SBSA
+ - Fixed memory type of secure NOR flash
+
+ - QTI
+ - Fixed NUM_APID and REG_APID_MAP() argument in SPMI driver
+
+ - Intel
+ - Do not keep mmc_device_info in stack
+
+ - Hisilicon
+ - Do not keep mmc_device_info in stack
+
+
+- Services
+
+ - EL3 runtime
+ - Fixed the EL2 context save/restore routine by removing EL2 generic
+ timer system registers
+ - Added fix for exception handler in BL31 by synchronizing pending EA
+ using DSB barrier
+
+ - SPMD
+ - Fixed error codes to use int32_t type
+
+ - TSPD
+ - Added bug fix in tspd interrupt handling when TSP_NS_INTR_ASYNC_PREEMPT is enabled
+
+ - TRNG
+ - Fixed compilation errors with -O0 compile option
+
+ - DebugFS
+ - Checked channel index before calling clone function
+
+ - PSCI
+ - Fixed limit of 256 CPUs caused by cast to unsigned char
+
+ - TSP
+ - Fixed compilation erros when built with GCC 11.0.0 toolchain
+
+- Tools
+ - FIPtool
+ - Do not call ``make clean`` for ``all`` target
+
+ - CertCreate
+ - Fixed bug to avoid cleaning when building the binary
+ - Used preallocated parts of the HASH struct to avoid leaking HASH struct fields
+ - Free arguments copied with strdup
+ - Free keys after use
+ - Free X509_EXTENSION structures on stack to avoid leaking them
+ - Optimized the code to avoid unnecessary attempts to create non-requested
+ certificates
+
Version 2.4
-----------
@@ -89,7 +758,7 @@
- Added workaround for erratum 1800714
- Added workaround for erratum 1925769
- - Arm Neoverse N1
+ - Arm Neoverse-N1
- Added workaround for erratum 1868343
- EL3 Runtime
diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst
index 8b02e7d..a5e7e8e 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -7,6 +7,8 @@
========
+--------+-----------------------------------+
+| CoT | Chain of Trust |
++--------+-----------------------------------+
| DMA | Direct Memory Access |
+--------+-----------------------------------+
| DTB | Device Tree Blob |
@@ -17,7 +19,7 @@
+--------+-----------------------------------+
| FIP | Firmware Image Package |
+--------+-----------------------------------+
-| FF-A | Firmware Framework for A-class |
+| FF-A | Firmware Framework for Armv8-A |
+--------+-----------------------------------+
| IPA | Intermediate Physical Address |
+--------+-----------------------------------+
@@ -31,12 +33,16 @@
+--------+-----------------------------------+
| PE | Processing Element |
+--------+-----------------------------------+
+| PM | Power Management |
++--------+-----------------------------------+
| PVM | Primary VM |
+--------+-----------------------------------+
| SMMU | System Memory Management Unit |
+--------+-----------------------------------+
| SP | Secure Partition |
+--------+-----------------------------------+
+| SPD | Secure Payload Dispatcher |
++--------+-----------------------------------+
| SPM | Secure Partition Manager |
+--------+-----------------------------------+
| SPMC | SPM Core |
@@ -59,111 +65,117 @@
Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
-- SPM based on the FF-A specification `[1]`_.
-- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
+- SPM based on the FF-A specification `[1]`_.
+- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
Both implementations differ in their architectures and only one can be selected
at build time.
This document:
-- describes the FF-A implementation where the Secure Partition Manager
- resides at EL3 and S-EL2 (or EL3 and S-EL1).
-- is not an architecture specification and it might provide assumptions
- on sections mandated as implementation-defined in the specification.
-- covers the implications to TF-A used as a bootloader, and Hafnium
- used as a reference code base for an S-EL2 secure firmware on
- platforms implementing Armv8.4-SecEL2.
+- describes the FF-A implementation where the Secure Partition Manager
+ resides at EL3 and S-EL2 (or EL3 and S-EL1).
+- is not an architecture specification and it might provide assumptions
+ on sections mandated as implementation-defined in the specification.
+- covers the implications to TF-A used as a bootloader, and Hafnium
+ used as a reference code base for an S-EL2 secure firmware on
+ platforms implementing the FEAT_SEL2 (formerly Armv8.4 Secure EL2)
+ architecture extension.
Terminology
-----------
-- Hypervisor refers to the NS-EL2 component managing Virtual Machines (or
- partitions) in the Normal World.
-- SPMC refers to the S-EL2 component managing Virtual Machines (or Secure
- Partitions) in the Secure World when Armv8.4-SecEL2 extension is implemented.
-- Alternatively, SPMC can refer to an S-EL1 component, itself being a Secure
- Partition and implementing the FF-A ABI on pre-Armv8.4 platforms.
-- VM refers to a Normal World Virtual Machine managed by an Hypervisor.
-- SP refers to a Secure World "Virtual Machine" managed by the SPMC component.
+- The term Hypervisor refers to the NS-EL2 component managing Virtual Machines
+ (or partitions) in the normal world.
+- The term SPMC refers to the S-EL2 component managing secure partitions in
+ the secure world when the FEAT_SEL2 architecture extension is implemented.
+- Alternatively, SPMC can refer to an S-EL1 component, itself being a secure
+ partition and implementing the FF-A ABI on platforms not implementing the
+ FEAT_SEL2 architecture extension.
+- The term VM refers to a normal world Virtual Machine managed by an Hypervisor.
+- The term SP refers to a secure world "Virtual Machine" managed by an SPMC.
Support for legacy platforms
----------------------------
-In the implementation, the SPM is split into SPMD and SPMC components
-(although not strictly mandated by the specification). SPMD is located
-at EL3 and principally relays FF-A messages from NWd (Hypervisor or OS
-kernel) to SPMC located either at S-EL1 or S-EL2.
+In the implementation, the SPM is split into SPMD and SPMC components.
+The SPMD is located at EL3 and mainly relays FF-A messages from
+NWd (Hypervisor or OS kernel) to SPMC located either at S-EL1 or S-EL2.
-Hence TF-A must support both cases where SPMC is either located at:
+Hence TF-A supports both cases where the SPMC is located either at:
-- S-EL1 supporting pre-Armv8.4 platforms. SPMD conveys FF-A protocol
- from EL3 to S-EL1.
-- S-EL2 supporting platforms implementing Armv8.4-SecEL2 extension.
- SPMD conveys FF-A protocol from EL3 to S-EL2.
+- S-EL1 supporting platforms not implementing the FEAT_SEL2 architecture
+ extension. The SPMD relays the FF-A protocol from EL3 to S-EL1.
+- or S-EL2 supporting platforms implementing the FEAT_SEL2 architecture
+ extension. The SPMD relays the FF-A protocol from EL3 to S-EL2.
-The same SPMD component is used to support both configurations. The SPMC
-execution level is a build time choice.
+The same TF-A SPMD component is used to support both configurations.
+The SPMC exception level is a build time choice.
Sample reference stack
======================
-The following diagram illustrates a possible configuration with SPMD and SPMC,
-one or multiple Secure Partitions, with or without an optional Hypervisor:
+The following diagram illustrates a possible configuration when the
+FEAT_SEL2 architecture extension is implemented, showing the SPMD
+and SPMC, one or multiple secure partitions, with an optional
+Hypervisor:
.. image:: ../resources/diagrams/ff-a-spm-sel2.png
TF-A build options
==================
-The following TF-A build options are provisioned:
+This section explains the TF-A build options involved in building with
+support for an FF-A based SPM where the SPMD is located at EL3 and the
+SPMC located at S-EL1 or S-EL2:
-- **SPD=spmd**: this option selects the SPMD component to relay FF-A
- protocol from NWd to SWd back and forth. It is not possible to
- enable another Secure Payload Dispatcher when this option is chosen.
-- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC execution
- level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when
- SPD=spmd is chosen.
-- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
- restoring) the EL2 system register context before entering (resp.
- after leaving) the SPMC. It is mandatory when ``SPMD_SPM_AT_SEL2`` is
- enabled. The context save/restore routine and exhaustive list of
- registers is visible at `[4]`_.
-- **SP_LAYOUT_FILE**: this option provides a text description file
- providing paths to SP binary images and DTS format manifests
- (see `Specifying partition binary image and DT`_). It
- is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
- secure partitions are to be loaded on behalf of SPMC.
+- **SPD=spmd**: this option selects the SPMD component to relay the FF-A
+ protocol from NWd to SWd back and forth. It is not possible to
+ enable another Secure Payload Dispatcher when this option is chosen.
+- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC exception
+ level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when
+ SPD=spmd is chosen.
+- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
+ restoring) the EL2 system register context before entering (resp.
+ after leaving) the SPMC. It is mandatorily enabled when
+ ``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine
+ and exhaustive list of registers is visible at `[4]`_.
+- **SP_LAYOUT_FILE**: this option specifies a text description file
+ providing paths to SP binary images and manifests in DTS format
+ (see `Describing secure partitions`_). It
+ is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
+ secure partitions are to be loaded on behalf of the SPMC.
-+------------------------------+----------------------+------------------+
-| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 |
-+------------------------------+----------------------+------------------+
-| SPMC at S-EL1 (e.g. OP-TEE) | 0 | 0 |
-+------------------------------+----------------------+------------------+
-| SPMC at S-EL2 (e.g. Hafnium) | 1 | 1 (default when |
-| | | SPD=spmd) |
-+------------------------------+----------------------+------------------+
++---------------+----------------------+------------------+
+| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 |
++---------------+----------------------+------------------+
+| SPMC at S-EL1 | 0 | 0 |
++---------------+----------------------+------------------+
+| SPMC at S-EL2 | 1 | 1 (default when |
+| | | SPD=spmd) |
++---------------+----------------------+------------------+
Other combinations of such build options either break the build or are not
supported.
-Note, the ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
-barely saving/restoring EL2 registers from an Arm arch perspective. As such
-it is decoupled from the ``SPD=spmd`` option.
+Notes:
-BL32 option is re-purposed to specify the SPMC image. It can specify either the
-Hafnium binary path (built for the secure world) or the path to a TEE binary
-implementing the FF-A protocol.
-
-BL33 option can specify either:
-
-- the TFTF binary or
-- the Hafnium binary path (built for the normal world) if VMs were loaded by
- TF-A beforehand or
-- a minimal loader performing the loading of VMs and Hafnium.
+- Only Arm's FVP platform is supported to use with the TF-A reference software
+ stack.
+- The reference software stack uses FEAT_PAuth (formerly Armv8.3-PAuth) and
+ FEAT_BTI (formerly Armv8.5-BTI) architecture extensions by default at EL3
+ and S-EL2.
+- The ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
+ barely saving/restoring EL2 registers from an Arm arch perspective. As such
+ it is decoupled from the ``SPD=spmd`` option.
+- BL32 option is re-purposed to specify the SPMC image. It can specify either
+ the Hafnium binary path (built for the secure world) or the path to a TEE
+ binary implementing FF-A interfaces.
+- BL33 option can specify the TFTF binary or a normal world loader
+ such as U-Boot or the UEFI framework.
Sample TF-A build command line when SPMC is located at S-EL1
-(typically pre-Armv8.4):
+(e.g. when the FEAT_EL2 architecture extension is not implemented):
.. code:: shell
@@ -172,67 +184,108 @@
SPD=spmd \
SPMD_SPM_AT_SEL2=0 \
BL32=<path-to-tee-binary> \
- BL33=<path-to-nwd-binary> \
+ BL33=<path-to-bl33-binary> \
PLAT=fvp \
all fip
-Sample TF-A build command line for an Armv8.4-SecEL2 enabled system
-where SPMC is located at S-EL2:
+Sample TF-A build command line for a FEAT_SEL2 enabled system where the SPMC is
+located at S-EL2:
.. code:: shell
make \
CROSS_COMPILE=aarch64-none-elf- \
+ PLAT=fvp \
SPD=spmd \
CTX_INCLUDE_EL2_REGS=1 \
- ARM_ARCH_MINOR=4 \
- BL32=<path-to-swd-hafnium-binary>
- BL33=<path-to-nwd-binary> \
+ ARM_ARCH_MINOR=5 \
+ BRANCH_PROTECTION=1 \
+ CTX_INCLUDE_PAUTH_REGS=1 \
+ BL32=<path-to-hafnium-binary> \
+ BL33=<path-to-bl33-binary> \
SP_LAYOUT_FILE=sp_layout.json \
- PLAT=fvp \
all fip
-Build options to enable secure boot:
+Same as above with enabling secure boot in addition:
.. code:: shell
make \
CROSS_COMPILE=aarch64-none-elf- \
+ PLAT=fvp \
SPD=spmd \
CTX_INCLUDE_EL2_REGS=1 \
- ARM_ARCH_MINOR=4 \
- BL32=<path-to-swd-hafnium-binary>
- BL33=<path-to-nwd-binary> \
- SP_LAYOUT_FILE=../tf-a-tests/build/fvp/debug/sp_layout.json \
+ ARM_ARCH_MINOR=5 \
+ BRANCH_PROTECTION=1 \
+ CTX_INCLUDE_PAUTH_REGS=1 \
+ BL32=<path-to-hafnium-binary> \
+ BL33=<path-to-bl33-binary> \
+ SP_LAYOUT_FILE=sp_layout.json \
MBEDTLS_DIR=<path-to-mbedtls-lib> \
TRUSTED_BOARD_BOOT=1 \
COT=dualroot \
ARM_ROTPK_LOCATION=devel_rsa \
ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
GENERATE_COT=1 \
- PLAT=fvp \
all fip
+FVP model invocation
+====================
+
+The FVP command line needs the following options to exercise the S-EL2 SPMC:
+
++---------------------------------------------------+------------------------------------+
+| - cluster0.has_arm_v8-5=1 | Implements FEAT_SEL2, FEAT_PAuth, |
+| - cluster1.has_arm_v8-5=1 | and FEAT_BTI. |
++---------------------------------------------------+------------------------------------+
+| - pci.pci_smmuv3.mmu.SMMU_AIDR=2 | Parameters required for the |
+| - pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B | SMMUv3.2 modeling. |
+| - pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 | |
+| - pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 | |
+| - pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 | |
++---------------------------------------------------+------------------------------------+
+| - cluster0.has_branch_target_exception=1 | Implements FEAT_BTI. |
+| - cluster1.has_branch_target_exception=1 | |
++---------------------------------------------------+------------------------------------+
+| - cluster0.restriction_on_speculative_execution=2 | Required by the EL2 context |
+| - cluster1.restriction_on_speculative_execution=2 | save/restore routine. |
++---------------------------------------------------+------------------------------------+
+
+Sample FVP command line invocation:
+
+.. code:: shell
+
+ <path-to-fvp-model>/FVP_Base_RevC-2xAEMv8A -C pctl.startup=0.0.0.0
+ -C cluster0.NUM_CORES=4 -C cluster1.NUM_CORES=4 -C bp.secure_memory=1 \
+ -C bp.secureflashloader.fname=trusted-firmware-a/build/fvp/debug/bl1.bin \
+ -C bp.flashloader0.fname=trusted-firmware-a/build/fvp/debug/fip.bin \
+ -C bp.pl011_uart0.out_file=fvp-uart0.log -C bp.pl011_uart1.out_file=fvp-uart1.log \
+ -C bp.pl011_uart2.out_file=fvp-uart2.log \
+ -C cluster0.has_arm_v8-5=1 -C cluster1.has_arm_v8-5=1 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \
+ -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \
+ -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 \
+ -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \
+ -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 \
+ -C cluster0.has_branch_target_exception=1 \
+ -C cluster1.has_branch_target_exception=1 \
+ -C cluster0.restriction_on_speculative_execution=2 \
+ -C cluster1.restriction_on_speculative_execution=2
+
Boot process
============
-Loading Hafnium and Secure Partitions in the secure world
+Loading Hafnium and secure partitions in the secure world
---------------------------------------------------------
-The Hafnium implementation in normal world requires VMs to be loaded in
-memory prior to booting. The mechanism upon which VMs are loaded and
-exposed to Hafnium are either:
+TF-A BL2 is the bootlader for the SPMC and SPs in the secure world.
-- by supplying a ramdisk image where VM images are concatenated (1)
-- or by providing VM load addresses within Hafnium manifest (2)
-
-TF-A is the bootlader for the Hafnium and SPs in the secure world. TF-A
-does not provide tooling or libraries manipulating ramdisks as required
-by (1). Thus BL2 loads SPs payloads independently.
SPs may be signed by different parties (SiP, OEM/ODM, TOS vendor, etc.).
-Thus they are supplied as distinct “self-contained” signed entities within
-the FIP flash image. The FIP image itself is not signed hence providing
-ability to upgrade SPs in the field.
+Thus they are supplied as distinct signed entities within the FIP flash
+image. The FIP image itself is not signed hence this provides the ability
+to upgrade SPs in the field.
Booting through TF-A
--------------------
@@ -241,26 +294,27 @@
~~~~~~~~~~~~
An SP manifest describes SP attributes as defined in `[1]`_
-section 3.1 (partition manifest at virtual FF-A instance) in DTS text format. It
-is represented as a single file associated with the SP. A sample is
+(partition manifest at virtual FF-A instance) in DTS format. It is
+represented as a single file associated with the SP. A sample is
provided by `[5]`_. A binding document is provided by `[6]`_.
Secure Partition packages
~~~~~~~~~~~~~~~~~~~~~~~~~
-Secure Partitions are bundled as independent package files consisting
+Secure partitions are bundled as independent package files consisting
of:
-- a header
-- a DTB
-- an image payload
+- a header
+- a DTB
+- an image payload
The header starts with a magic value and offset values to SP DTB and
image payload. Each SP package is loaded independently by BL2 loader
and verified for authenticity and integrity.
-The SP package identified by its UUID (matching FF-A uuid) is inserted
-as a single entry into the FIP at end of the TF-A build flow as shown:
+The SP package identified by its UUID (matching FF-A uuid property) is
+inserted as a single entry into the FIP at end of the TF-A build flow
+as shown:
.. code:: shell
@@ -278,18 +332,17 @@
.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml
-Specifying partition binary image and DT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Describing secure partitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A description file (json format) is passed to the build flow specifying
-paths to the SP binary image and associated DTS partition manifest file.
-The latter is going through the dtc compiler to generate the dtb fed into
-the SP package.
-This file also specifies the owner of the SP, which is an optional field and
-identifies the signing domain in case of dualroot CoT.
-The possible owner of an SP could either be Silicon Provider or Platform, and
-the corresponding "owner" field value could either be "SiP" or "Plat".
-In absence of "owner" field, it defaults to "SiP".
+A json-formatted description file is passed to the build flow specifying paths
+to the SP binary image and associated DTS partition manifest file. The latter
+is processed by the dtc compiler to generate a DTB fed into the SP package.
+This file also specifies the SP owner (as an optional field) identifying the
+signing domain in case of dual root CoT.
+The SP owner can either be the silicon or the platform provider. The
+corresponding "owner" field value can either take the value of "SiP" or "Plat".
+In absence of "owner" field, it defaults to "SiP" owner.
.. code:: shell
@@ -310,14 +363,16 @@
SPMC manifest
~~~~~~~~~~~~~
-This manifest contains an SPMC attributes node consumed by SPMD at boot time. It
-is implementing the description from `[1]`_ section 3.2 (SP manifest at physical
-FF-A instance). The SP manifest at physical FF-A instance is used by the SPMD to
-setup a SP that co-resides with the SPMC and executes at S-EL1 or Secure
-Supervisor mode.
+This manifest contains the SPMC *attribute* node consumed by the SPMD at boot
+time. It implements `[1]`_ (SP manifest at physical FF-A instance) and serves
+two different cases:
-In this implementation its usage is extended to the secure physical FF-A
-instance where SPMC executes at S-EL2.
+- The SPMC resides at S-EL1: the SPMC manifest is used by the SPMD to setup a
+ SP that co-resides with the SPMC and executes at S-EL1 or Secure Supervisor
+ mode.
+- The SPMC resides at S-EL2: the SPMC manifest is used by the SPMD to setup
+ the environment required by the SPMC to run at S-EL2. SPs run at S-EL1 or
+ S-EL0.
.. code:: shell
@@ -331,28 +386,28 @@
binary_size = <0x60000>;
};
-- *spmc_id* defines the endpoint ID value that SPMC can query through
- ``FFA_ID_GET``.
-- *maj_ver/min_ver*. SPMD checks provided version versus its internal
- version and aborts if not matching.
-- *exec_state* defines SPMC execution state (can be AArch64 for
- Hafnium, or AArch64/AArch32 for OP-TEE at S-EL1).
-- *load_address* and *binary_size* are mostly used to verify secondary
- entry points fit into the loaded binary image.
-- *entrypoint* defines the cold boot primary core entry point used by
- SPMD (currently matches ``BL32_BASE``)
+- *spmc_id* defines the endpoint ID value that SPMC can query through
+ ``FFA_ID_GET``.
+- *maj_ver/min_ver*. SPMD checks provided version versus its internal
+ version and aborts if not matching.
+- *exec_state* defines the SPMC execution state (AArch64 or AArch32).
+ Notice Hafnium used as a SPMC only supports AArch64.
+- *load_address* and *binary_size* are mostly used to verify secondary
+ entry points fit into the loaded binary image.
+- *entrypoint* defines the cold boot primary core entry point used by
+ SPMD (currently matches ``BL32_BASE``) to enter the SPMC.
Other nodes in the manifest are consumed by Hafnium in the secure world.
A sample can be found at [7]:
-- The *chosen* node is currently unused in SWd. It is meant for NWd to
- specify the init ramdisk image.
-- The *hypervisor* node describes SPs. *is_ffa_partition* boolean
- attribute indicates an SP. Load-addr field specifies the load address
- at which TF-A loaded the SP package.
-- *cpus* node provide the platform topology and allows MPIDR to VMPIDR
- mapping. Notice with current implementation primary cpu is declared
- first, then secondary cpus must be declared in reverse order.
+- The *hypervisor* node describes SPs. *is_ffa_partition* boolean attribute
+ indicates a FF-A compliant SP. The *load_address* field specifies the load
+ address at which TF-A loaded the SP package.
+- *cpus* node provide the platform topology and allows MPIDR to VMPIDR mapping.
+ Note the primary core is declared first, then secondary core are declared
+ in reverse order.
+- The *memory* node provides platform information on the ranges of memory
+ available to the SPMC.
SPMC boot
~~~~~~~~~
@@ -363,134 +418,111 @@
BL2 passes the SPMC manifest address to BL31 through a register.
-BL31(SPMD) runs from primary core, initializes the core contexts and
-launches BL32 passing the SPMC manifest address through a register.
+At boot time, the SPMD in BL31 runs from the primary core, initializes the core
+contexts and launches the SPMC (BL32) passing the SPMC manifest address through
+a register.
Loading of SPs
~~~~~~~~~~~~~~
+At boot time, BL2 loads SPs sequentially in addition to the SPMC as depicted
+below:
+
.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml
-
-Notice this boot flow is an implementation sample on Arm's FVP platform. Platforms
-not using FW_CONFIG would adjust to a different implementation.
+Note this boot flow is an implementation sample on Arm's FVP platform.
+Platforms not using TF-A's *Firmware CONFiguration* framework would adjust to a
+different implementation.
Secure boot
~~~~~~~~~~~
The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC,
-SPMC manifest and Secure Partitions and verifies them for authenticity and integrity.
+SPMC manifest, secure partitions and verifies them for authenticity and integrity.
Refer to TBBR specification `[3]`_.
-The multiple-signing domain feature (in current state dual signing domain) allows
-the use of two root keys namely S-ROTPK and NS-ROTPK (see `[8]`_):
+The multiple-signing domain feature (in current state dual signing domain `[8]`_) allows
+the use of two root keys namely S-ROTPK and NS-ROTPK:
-- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
-- BL33 may be signed by the OEM using NS-ROTPK.
-- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
+- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
+- BL33 may be signed by the OEM using NS-ROTPK.
+- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
-Longer term multiple signing domain will allow additional signing keys, e.g.
-if SPs originate from different parties.
-
-See `TF-A build options`_ for a sample build command line.
+Also refer to `Describing secure partitions`_ and `TF-A build options`_ sections.
Hafnium in the secure world
===========================
-**NOTE: this section is work in progress. Descriptions and implementation choices
-are subject to evolve.**
-
General considerations
----------------------
Build platform for the secure world
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The implementation might add specific code parts only relevant to the
-secure world. Such code parts might be isolated into different files
-and/or conditional code enclosed by a ``SECURE_WORLD`` macro.
+In the Hafnium reference implementation specific code parts are only relevant to
+the secure world. Such portions are isolated in architecture specific files
+and/or enclosed by a ``SECURE_WORLD`` macro.
-Secure Partitions CPU scheduling
+Secure partitions CPU scheduling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the normal world, VMs are scheduled by the FFA_RUN ABI invoked from the
-primary scheduler (in the primary VM), or by a direct message request or
-response.
+The FF-A v1.0 specification `[1]`_ provides two ways to relinquinsh CPU time to
+secure partitions. For this a VM (Hypervisor or OS kernel), or SP invokes one of:
-With the FF-A EAC specification, Secure Partitions are scheduled by direct
-message invocations from a NWd VM or another SP.
+- the FFA_MSG_SEND_DIRECT_REQ interface.
+- the FFA_RUN interface.
Platform topology
~~~~~~~~~~~~~~~~~
-As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes the
+The *execution-ctx-count* SP manifest field can take the value of one or the
+total number of PEs. The FF-A v1.0 specification `[1]`_ recommends the
following SP types:
-- Pinned MP SPs: an Execution Context id matches a physical PE id. MP
- SPs must implement the same number of ECs as the number of PEs in the
- platform. Hence the *execution-ctx-count* as defined by
- `[1]`_ (or NWd-Hafnium *vcpu_count*) can only take the
- value of one or the number of physical PEs.
-- Migratable UP SPs: a single execution context can run and be migrated
- on any physical PE. It declares a single EC in its SP manifest. An UP
- SP can receive a direct message request on any physical core.
-
-Usage of PSCI services in the secure world
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- The normal world Hypervisor (optional) or OS kernel issues PSCI service
- invocations e.g. to request PSCI version, wake-up a secondary core, or request
- core suspend. This happens at the non-secure physical FF-A instance. In the
- example case of Hafnium in the normal world, it boots on the primary core and
- one of the first initialization step is to request the PSCI version. It then
- launches the primary VM. The primary VM upon initializing performs PSCI service
- calls (at non-secure virtual FF-A instance) which are trapped by the
- Hypervisor. Invocation from OS Kernel ends straight at EL3. The PVM issues
- ``PSCI_CPU_ON`` service calls to wake-up secondary cores by passing an
- ``MPIDR``, entry point address and a CPU context address. The EL3 PSCI layer
- then performs an exception return to the secondary core entry point on the
- targeted core. Other PSCI calls can happen at run-time from the PVM e.g. to
- request core suspend.
-- In the existing TF-A PSCI standard library, PSCI service calls are filtered at
- EL3 to only originate from the NWd. Thus concerning the SPMC (at secure
- physical FF-A instance) the PSCI service invocations cannot happen as in the
- normal world. For example, a ``PSCI_CPU_ON`` service invocation from the SPMC
- does not reach the PSCI layer.
+- Pinned MP SPs: an execution context matches a physical PE. MP SPs must
+ implement the same number of ECs as the number of PEs in the platform.
+- Migratable UP SPs: a single execution context can run and be migrated on any
+ physical PE. Such SP declares a single EC in its SP manifest. An UP SP can
+ receive a direct message request originating from any physical core targeting
+ the single execution context.
Parsing SP partition manifests
------------------------------
-Hafnium must be able to consume SP manifests as defined in
-`[1]`_ section 3.1, at least for the mandatory fields.
+Hafnium consumes SP manifests as defined in `[1]`_ and `SP manifests`_.
+Note the current implementation may not implement all optional fields.
-The SP manifest may contain memory and device regions nodes.
+The SP manifest may contain memory and device regions nodes. In case of
+an S-EL2 SPMC:
-- Memory regions shall be mapped in the SP Stage-2 translation regime at
- load time. A memory region node can specify RX/TX buffer regions in which
- case it is not necessary for an SP to explicitly call the ``FFA_RXTX_MAP``
- service.
-- Device regions shall be mapped in SP Stage-2 translation regime as
- peripherals and possibly allocate additional resources (e.g. interrupts)
+- Memory regions are mapped in the SP EL1&0 Stage-2 translation regime at
+ load time (or EL1&0 Stage-1 for an S-EL1 SPMC). A memory region node can
+ specify RX/TX buffer regions in which case it is not necessary for an SP
+ to explicitly invoke the ``FFA_RXTX_MAP`` interface.
+- Device regions are mapped in the SP EL1&0 Stage-2 translation regime (or
+ EL1&0 Stage-1 for an S-EL1 SPMC) as peripherals and possibly allocate
+ additional resources (e.g. interrupts).
-Base addresses for memory and device region nodes are IPAs provided SPMC
-identity maps IPAs to PAs within SP Stage-2 translation regime.
+For the S-EL2 SPMC, base addresses for memory and device region nodes are IPAs
+provided the SPMC identity maps IPAs to PAs within SP EL1&0 Stage-2 translation
+regime.
-Note: currently both VTTBR_EL2 and VSTTBR_EL2 resolve to the same set of page
-tables. It is still open whether two sets of page tables shall be provided per
-SP. The memory region node as defined in the spec (section 3.1 Table 10)
+Note: in the current implementation both VTTBR_EL2 and VSTTBR_EL2 point to the
+same set of page tables. It is still open whether two sets of page tables shall
+be provided per SP. The memory region node as defined in the specification
provides a memory security attribute hinting to map either to the secure or
-non-secure stage-2 table.
+non-secure EL1&0 Stage-2 table if it exists.
Passing boot data to the SP
---------------------------
-`[1]`_ Section 3.4.2 “Protocol for passing data” defines a
-method to passing boot data to SPs (not currently implemented).
+In `[1]`_ , the "Protocol for passing data" section defines a method for passing
+boot data to SPs (not currently implemented).
-Provided that the whole Secure Partition package image (see `Secure
-Partition packages`_) is mapped to the SP's secure Stage-2 translation
-regime, an SP can access its own manifest DTB blob and extract its partition
-manifest properties.
+Provided that the whole secure partition package image (see
+`Secure Partition packages`_) is mapped to the SP secure EL1&0 Stage-2
+translation regime, an SP can access its own manifest DTB blob and extract its
+partition manifest properties.
SP Boot order
-------------
@@ -499,343 +531,284 @@
dependencies such as an SP providing a service required to properly boot
another SP.
+It is possible for an SP to call into another SP through a direct request
+provided the latter SP has already been booted.
+
Boot phases
-----------
Primary core boot-up
~~~~~~~~~~~~~~~~~~~~
-The SPMC performs its platform initializations then loads and creates
-secure partitions based on SP packages and manifests. Then each secure
-partition is launched in sequence (see `SP Boot order`_) on their primary
-Execution Context.
+Upon boot-up, BL31 hands over to the SPMC (BL32) on the primary boot physical
+core. The SPMC performs its platform initializations and registers the SPMC
+secondary physical core entry point physical address by the use of the
+FFA_SECONDARY_EP_REGISTER interface (SMC invocation from the SPMC to the SPMD
+at secure physical FF-A instance). This interface is implementation-defined in
+context of FF-A v1.0.
-Notice the primary physical core may not be core 0. Hence if the primary
-core linear id is N, the 1:1 mapping requires MP SPs are launched using
-EC[N] on PE[N] (see `Platform topology`_).
+The SPMC then creates secure partitions based on SP packages and manifests. Each
+secure partition is launched in sequence (`SP Boot order`_) on their "primary"
+execution context. If the primary boot physical core linear id is N, an MP SP is
+started using EC[N] on PE[N] (see `Platform topology`_). If the partition is a
+UP SP, it is started using its unique EC0 on PE[N].
-The SP's primary Execution Context (or the EC used when the partition is booted)
-exits through ``FFA_MSG_WAIT`` to indicate successful initialization.
+The SP primary EC (or the EC used when the partition is booted as described
+above):
-Secondary physical core boot-up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Performs the overall SP boot time initialization, and in case of a MP SP,
+ prepares the SP environment for other execution contexts.
+- In the case of a MP SP, it invokes the FFA_SECONDARY_EP_REGISTER at secure
+ virtual FF-A instance (SMC invocation from SP to SPMC) to provide the IPA
+ entry point for other execution contexts.
+- Exits through ``FFA_MSG_WAIT`` to indicate successful initialization or
+ ``FFA_ERROR`` in case of failure.
-Upon boot-up, the SPMC running on the primary core performs
-implementation-defined SPMD service calls at secure physical FF-A instance
-to register the secondary physical cores entry points and context information:
+Secondary cores boot-up
+~~~~~~~~~~~~~~~~~~~~~~~
-- This is done through a direct message request invocation to the SPMD
- (``SET_ENTRY_POINT``). This service call does not wake-up the targeted
- core immediately. The secondary core is woken up later by a NWd
- ``PSCI_CPU_ON`` service invocation. A notification is passed from EL3
- PSCI layer to the SPMD, and then to SPMC through an implementation-defined
- interface.
-- The SPMC/SPMD interface can consist of FF-A direct message requests/responses
- transporting PM events.
+Once the system is started and NWd brought up, a secondary physical core is
+woken up by the ``PSCI_CPU_ON`` service invocation. The TF-A SPD hook mechanism
+calls into the SPMD on the newly woken up physical core. Then the SPMC is
+entered at the secondary physical core entry point.
-If there is no Hypervisor in the normal world, the OS Kernel issues
-``PSCI_CPU_ON`` calls that are directly trapped to EL3.
+In the current implementation, the first SP is resumed on the coresponding EC
+(the virtual CPU which matches the physical core). The implication is that the
+first SP must be a MP SP.
-When a secondary physical core wakes-up the SPMD notifies the SPMC which updates
-its internal states reflecting current physical core is being turned on.
-It might then return straight to the SPMD and then to the NWd.
+In a linux based system, once secure and normal worlds are booted but prior to
+a NWd FF-A driver has been loaded:
-*(under discussion)* There may be possibility that an SP registers "PM events"
-(during primary EC boot stage) through an ad-hoc interface. Such events would
-be relayed by SPMC to one or more registered SPs on need basis
-(see `Power management`_).
+- The first SP has initialized all its ECs in response to primary core boot up
+ (at system initialization) and secondary core boot up (as a result of linux
+ invoking PSCI_CPU_ON for all secondary cores).
+- Other SPs have their first execution context initialized as a result of secure
+ world initialization on the primary boot core. Other ECs for those SPs have to
+ be run first through ffa_run to complete their initialization (which results
+ in the EC completing with FFA_MSG_WAIT).
-Secondary virtual core boot-up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the example case where Hafnium exists in the normal world, secondary VMs
-issue a ``PSCI_CPU_ON`` service call which is trapped to the Hypervisor. The
-latter then enables the vCPU context for the targeted core, and switches to
-the PVM down to the kernel driver with an ``HF_WAKE_UP`` message. The NWd
-driver in PVM can then schedule the newly woken up vCPU context.
-
-In the secure world the primary EC of a given SP passes the secondary EC entry
-point and context. The SMC service call is trapped into the SPMC. This can be
-either *(under discussion)*:
-
-- a specific interface registering the secondary EC entry point,
- similarly to above ``SET_ENTRY_POINT`` service.
-- Re-purposing the ``PSCI_CPU_ON`` function id. It is
- assumed that even if the input arguments are the same as the ones defined in
- the PSCI standard, the usage deviates by the fact the secondary EC is not
- woken up immediately. At least for the FF-A EAC where only
- direct messaging is allowed, it is only after the first direct
- message invocation that the secondary EC is entered. This option
- might be preferred when the same code base is re-used for a VM or
- an SP. The ABI to wake-up a secondary EC can remain similar.
-
-SPs are always scheduled from the NWd, this paradigm did not change from legacy
-TEEs. There must always be some logic (or driver) in the NWd to relinquish CPU
-cycles to the SWd. If primary core is 0, an SP EC[x>0] entry point is supplied
-by the SP EC[0] when the system boots in SWd. But this EC[x] is not immediately
-entered at boot. Later in the boot process when NWd is up, a direct message
-request issued from physical core 1 ends up in SP EC[1], and only at this stage
-this context is effectively scheduled.
-
-It should be possible for an SP to call into another SP through direct message
-provided the latter SP has been booted already. The "boot-order" field in
-partition manifests (`SP Boot order`_) fulfills the dependency towards availability
-of a service within an SP offered to another SP.
+Refer to `Power management`_ for further details.
Mandatory interfaces
--------------------
-The following interfaces must be exposed to any VM or SP:
+The following interfaces are exposed to SPs:
-- ``FFA_STATUS``
-- ``FFA_ERROR``
-- ``FFA_INTERRUPT``
- ``FFA_VERSION``
- ``FFA_FEATURES``
- ``FFA_RX_RELEASE``
- ``FFA_RXTX_MAP``
-- ``FFA_RXTX_UNMAP``
+- ``FFA_RXTX_UNMAP`` (not implemented)
- ``FFA_PARTITION_INFO_GET``
- ``FFA_ID_GET``
+- ``FFA_MSG_WAIT``
+- ``FFA_MSG_SEND_DIRECT_REQ``
+- ``FFA_MSG_SEND_DIRECT_RESP``
+- ``FFA_MEM_DONATE``
+- ``FFA_MEM_LEND``
+- ``FFA_MEM_SHARE``
+- ``FFA_MEM_RETRIEVE_REQ``
+- ``FFA_MEM_RETRIEVE_RESP``
+- ``FFA_MEM_RELINQUISH``
+- ``FFA_MEM_RECLAIM``
+- ``FFA_SECONDARY_EP_REGISTER``
FFA_VERSION
~~~~~~~~~~~
-Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a
-*requested_version* parameter from the caller.
+``FFA_VERSION`` requires a *requested_version* parameter from the caller.
+The returned value depends on the caller:
-In the current implementation when ``FFA_VERSION`` is invoked from:
-
-- Hypervisor in NS-EL2: the SPMD returns the SPMC version specified
- in the SPMC manifest.
-- OS kernel in NS-EL1 when NS-EL2 is not present: the SPMD returns the
- SPMC version specified in the SPMC manifest.
-- VM in NWd: the Hypervisor returns its implemented version.
-- SP in SWd: the SPMC returns its implemented version.
-- SPMC at S-EL1/S-EL2: the SPMD returns its implemented version.
+- Hypervisor or OS kernel in NS-EL1/EL2: the SPMD returns the SPMC version
+ specified in the SPMC manifest.
+- SP: the SPMC returns its own implemented version.
+- SPMC at S-EL1/S-EL2: the SPMD returns its own implemented version.
FFA_FEATURES
~~~~~~~~~~~~
-FF-A features may be discovered by Secure Partitions while booting
-through the SPMC. However, SPMC cannot get features from Hypervisor
-early at boot time as NS world is not setup yet.
+FF-A features supported by the SPMC may be discovered by secure partitions at
+boot (that is prior to NWd is booted) or run-time.
-The Hypervisor may decide to gather FF-A features from SPMC through SPMD
-once at boot time and store the result. Later when a VM requests FF-A
-features, the Hypervisor can adjust its own set of features with what
-SPMC advertised, if necessary. Another approach is to always forward FF-A
-features to the SPMC when a VM requests it to the Hypervisor. Although
-the result is not supposed to change over time so there may not be added
-value doing the systematic forwarding.
+The SPMC calling FFA_FEATURES at secure physical FF-A instance always get
+FFA_SUCCESS from the SPMD.
+
+The request made by an Hypervisor or OS kernel is forwarded to the SPMC and
+the response relayed back to the NWd.
FFA_RXTX_MAP/FFA_RXTX_UNMAP
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-VM mailboxes are re-purposed to serve as SP RX/TX buffers. The RX/TX
-map API maps the send and receive buffer IPAs to the SP Stage-2 translation regime.
+When invoked from a secure partition FFA_RXTX_MAP maps the provided send and
+receive buffers described by their IPAs to the SP EL1&0 Stage-2 translation
+regime as secure buffers in the MMU descriptors.
-Hafnium in the normal world defines VMs and their attributes as logical structures,
-including a mailbox used for FF-A indirect messaging, memory sharing, or the
-`FFA_PARTITION_INFO_GET`_ ABI.
-This same mailbox structure is re-used in the SPMC. `[1]`_ states only direct
-messaging is allowed to SPs. Thus mailbox usage is restricted to implementing
-`FFA_PARTITION_INFO_GET`_ and memory sharing ABIs.
+When invoked from the Hypervisor or OS kernel, the buffers are mapped into the
+SPMC EL2 Stage-1 translation regime and marked as NS buffers in the MMU
+descriptors.
+
+Note:
+
+- FFA_RXTX_UNMAP is not implemented.
FFA_PARTITION_INFO_GET
~~~~~~~~~~~~~~~~~~~~~~
-Partition info get service call can originate:
+Partition info get call can originate:
-- from SP to SPM
-- from VM to Hypervisor
-- from Hypervisor to SPM
-
-For the latter case, the service call must be forwarded through the SPMD.
+- from SP to SPMC
+- from Hypervisor or OS kernel to SPMC. The request is relayed by the SPMD.
FFA_ID_GET
~~~~~~~~~~
-The SPMD returns:
-
-- a default zero value on invocation from the Hypervisor.
-- The ``spmc_id`` value specified in the SPMC manifest on invocation from
- the SPMC (see `SPMC manifest`_)
-
The FF-A id space is split into a non-secure space and secure space:
-- FF-A id with bit 15 clear refer to normal world VMs.
-- FF-A id with bit 15 set refer to secure world SPs
+- FF-A ID with bit 15 clear relates to VMs.
+- FF-A ID with bit 15 set related to SPs.
+- FF-A IDs 0, 0xffff, 0x8000 are assigned respectively to the Hypervisor, SPMD
+ and SPMC.
-Such convention helps the SPMC discriminating the origin and destination worlds
-in an FF-A service invocation. In particular the SPMC shall filter unauthorized
+The SPMD returns:
+
+- The default zero value on invocation from the Hypervisor.
+- The ``spmc_id`` value specified in the SPMC manifest on invocation from
+ the SPMC (see `SPMC manifest`_)
+
+This convention helps the SPMC to determine the origin and destination worlds in
+an FF-A ABI invocation. In particular the SPMC shall filter unauthorized
transactions in its world switch routine. It must not be permitted for a VM to
-use a secure FF-A id as origin world through spoofing:
+use a secure FF-A ID as origin world by spoofing:
-- A VM-to-SP messaging passing shall have an origin world being non-secure
- (FF-A id bit 15 clear) and destination world being secure (FF-A id bit 15
- set).
-- Similarly, an SP-to-SP message shall have FF-A id bit 15 set for both origin
- and destination ids.
+- A VM-to-SP direct request/response shall set the origin world to be non-secure
+ (FF-A ID bit 15 clear) and destination world to be secure (FF-A ID bit 15
+ set).
+- Similarly, an SP-to-SP direct request/response shall set the FF-A ID bit 15
+ for both origin and destination IDs.
An incoming direct message request arriving at SPMD from NWd is forwarded to
SPMC without a specific check. The SPMC is resumed through eret and "knows" the
message is coming from normal world in this specific code path. Thus the origin
-endpoint id must be checked by SPMC for being a normal world id.
+endpoint ID must be checked by SPMC for being a normal world ID.
An SP sending a direct message request must have bit 15 set in its origin
-endpoint id and this can be checked by the SPMC when the SP invokes the ABI.
+endpoint ID and this can be checked by the SPMC when the SP invokes the ABI.
The SPMC shall reject the direct message if the claimed world in origin endpoint
-id is not consistent:
+ID is not consistent:
-- It is either forwarded by SPMD and thus origin endpoint id must be a "normal
- world id",
-- or initiated by an SP and thus origin endpoint id must be a "secure world id".
+- It is either forwarded by SPMD and thus origin endpoint ID must be a "normal
+ world ID",
+- or initiated by an SP and thus origin endpoint ID must be a "secure world ID".
-Direct messaging
-----------------
-This is a mandatory interface for Secure Partitions consisting in direct
-message request and responses.
+FFA_MSG_SEND_DIRECT_REQ/FFA_MSG_SEND_DIRECT_RESP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``ffa_handler`` Hafnium function may:
+This is a mandatory interface for secure partitions consisting in direct request
+and responses with the following rules:
-- trigger a world change e.g. when an SP invokes the direct message
- response ABI to a VM.
-- handle multiple requests from the NWd without resuming an SP.
+- An SP can send a direct request to another SP.
+- An SP can receive a direct request from another SP.
+- An SP can send a direct response to another SP.
+- An SP cannot send a direct request to an Hypervisor or OS kernel.
+- An Hypervisor or OS kernel can send a direct request to an SP.
+- An SP can send a direct response to an Hypervisor or OS kernel.
-SP-to-SP
-~~~~~~~~
+SPMC-SPMD direct requests/responses
+-----------------------------------
-- An SP can send a direct message request to another SP
-- An SP can receive a direct message response from another SP.
+Implementation-defined FF-A IDs are allocated to the SPMC and SPMD.
+Using those IDs in source/destination fields of a direct request/response
+permits SPMD to SPMC communication and either way.
-VM-to-SP
-~~~~~~~~
+- SPMC to SPMD direct request/response uses SMC conduit.
+- SPMD to SPMC direct request/response uses ERET conduit.
-- A VM can send a direct message request to an SP
-- An SP can send a direct message response to a VM
+PE MMU configuration
+--------------------
-SPMC-SPMD messaging
-~~~~~~~~~~~~~~~~~~~
+With secure virtualization enabled, two IPA spaces are output from the secure
+EL1&0 Stage-1 translation (secure and non-secure). The EL1&0 Stage-2 translation
+hardware is fed by:
-Specific implementation-defined endpoint IDs are allocated to the SPMC and SPMD.
-Referring those IDs in source/destination fields of a direct message
-request/response permits SPMD to SPMC messaging back and forth.
+- A single secure IPA space when the SP EL1&0 Stage-1 MMU is disabled.
+- Two IPA spaces (secure and non-secure) when the SP EL1&0 Stage-1 MMU is
+ enabled.
-Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance):
+``VTCR_EL2`` and ``VSTCR_EL2`` provide configuration bits for controlling the
+NS/S IPA translations.
+``VSTCR_EL2.SW`` = 0, ``VSTCR_EL2.SA`` = 0,``VTCR_EL2.NSW`` = 0, ``VTCR_EL2.NSA`` = 1:
-- SPMC=>SPMD direct message request uses SMC conduit
-- SPMD=>SPMC direct message request uses ERET conduit
+- Stage-2 translations for the NS IPA space access the NS PA space.
+- Stage-2 translation table walks for the NS IPA space are to the secure PA space.
-Per `[1]`_ Table 118 Config No. 1 (physical FF-A instance):
-
-- SPMC=>SPMD direct message response uses SMC conduit
-- SPMD=>SPMC direct message response uses ERET conduit
-
-Memory management
------------------
-
-This section only deals with the PE MMU configuration.
-
-Hafnium in the normal world deals with NS buffers only and provisions
-a single root page table directory to VMs. In context of S-EL2 enabled
-firmware, two IPA spaces are output from Stage-1 translation (secure
-and non-secure). The Stage-2 translation handles:
-
-- A single secure IPA space when an SP Stage-1 MMU is disabled.
-- Two IPA spaces (secure and non-secure) when Stage-1 MMU is enabled.
-
-``VTCR_EL2`` and ``VSTCR_EL2`` provide additional bits for controlling the
-NS/S IPA translations (``VSTCR_EL2.SW``, ``VSTCR_EL2.SA``, ``VTCR_EL2.NSW``,
-``VTCR_EL2.NSA``). There may be two approaches:
-
-- secure and non-secure mappings are rooted as two separate root page
- tables
-- secure and non-secure mappings use the same root page table. Access
- from S-EL1 to an NS region translates to a secure physical address
- space access.
+Secure and non-secure IPA regions use the same set of Stage-2 page tables within
+a SP.
Interrupt management
--------------------
-Road to a para-virtualized interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+GIC ownership
+~~~~~~~~~~~~~
-Current Hafnium implementation uses an ad-hoc mechanism for a VM to get
-a pending interrupt number through an hypercall. The PVM injects
-interrupts to VMs by delegation from the Hypervisor. The PVM probes a
-pending interrupt directly from the GIC distributor.
+The SPMC owns the GIC configuration. Secure and non-secure interrupts are
+trapped at S-EL2. The SPMC manages interrupt resources and allocates interrupt
+IDs based on SP manifests. The SPMC acknowledges physical interrupts and injects
+virtual interrupts by setting the use of vIRQ/vFIQ bits before resuming a SP.
-The short-term plan is to have Hafnium/SPMC in the secure world owner
-of the GIC configuration.
+Non-secure interrupt handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The SPMC fully owns the GIC configuration at S-EL2. The SPMC manages
-interrupt resources and allocates interrupt ID based on SP manifests.
-The SPMC acknowledges physical interrupts and injects virtual interrupts
-by setting the vIRQ bit when resuming an SP. A Secure Partition gathers
-the interrupt number through an hypercall.
+The following illustrate the scenarios of non secure physical interrupts trapped
+by the SPMC:
-Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition
-to Group1 S/NS interrupts.
+- The SP handles a managed exit operation:
+
+.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
+
+- The SP is pre-empted without managed exit:
+
+.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
+
+Secure interrupt handling
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The current implementation does not support handling of secure interrupts
+trapped by the SPMC at S-EL2. This is work in progress planned for future
+releases.
Power management
----------------
-Assumption on the Nwd:
+In platforms with or without secure virtualization:
-- NWd is the best candidate to own the platform Power Management
- policy. It is master to invoking PSCI service calls from physical
- CPUs.
-- EL3 monitor is in charge of the PM control part (its PSCI layer
- actually writing to platform registers).
-- It is fine for the Hypervisor to trap PSCI calls and relay to EL3, or
- OS kernel driver to emit PSCI service calls.
+- The NWd owns the platform PM policy.
+- The Hypervisor or OS kernel is the component initiating PSCI service calls.
+- The EL3 PSCI library is in charge of the PM coordination and control
+ (eventually writing to platform registers).
+- While coordinating PM events, the PSCI library calls backs into the Secure
+ Payload Dispatcher for events the latter has statically registered to.
-PSCI notification are relayed through the SPMD/SPD PM hooks to the SPMC.
-This can either be through re-use of PSCI FIDs or an FF-A direct message
-from SPMD to SPMC.
+When using the SPMD as a Secure Payload Dispatcher:
-The SPMD performs an exception return to the SPMC which is resumed to
-its ``eret_handler`` routine. It is then either consuming a PSCI FID or
-an FF-A FID. Depending on the servicing, the SPMC may return directly to
-the SPMD (and then NWd) without resuming an SP at this stage. An example
-of this is invocation of ``FFA_PARTITION_INFO_GET`` from NWd relayed by
-the SPMD to the SPMC. The SPMC returns the needed partition information
-to the SPMD (then NWd) without actually resuming a partition in secure world.
+- A power management event is relayed through the SPD hook to the SPMC.
+- In the current implementation only cpu on (svc_on_finish) and cpu off
+ (svc_off) hooks are registered.
+- The behavior for the cpu on event is described in `Secondary cores boot-up`_.
+ The SPMC is entered through its secondary physical core entry point.
+- The cpu off event occurs when the NWd calls PSCI_CPU_OFF. The method by which
+ the PM event is conveyed to the SPMC is implementation-defined in context of
+ FF-A v1.0 (`SPMC-SPMD direct requests/responses`_). It consists in a SPMD-to-SPMC
+ direct request/response conveying the PM event details and SPMC response.
+ The SPMD performs a synchronous entry into the SPMC. The SPMC is entered and
+ updates its internal state to reflect the physical core is being turned off.
+ In the current implementation no SP is resumed as a consequence. This behavior
+ ensures a minimal support for CPU hotplug e.g. when initiated by the NWd linux
+ userspace.
-*(under discussion)*
-About using PSCI FIDs from SPMD to SPMC to notify of PM events, it is still
-questioned what to use as the return code from the SPMC.
-If the function ID used by the SPMC is not an FF-A ID when doing SMC, then the
-EL3 std svc handler won't route the response to the SPMD. That's where comes the
-idea to embed the notification into an FF-A message. The SPMC can discriminate
-this message as being a PSCI event, process it, and reply with an FF-A return
-message that the SPMD receives as an acknowledgement.
-
-SP notification
----------------
-
-Power management notifications are conveyed from PSCI library to the
-SPMD / SPD hooks. A range of events can be relayed to SPMC.
-
-SPs may need to be notified about specific PM events.
-
-- SPs might register PM events to the SPMC
-- On SPMD to SPMC notification, a limited range of SPs may be notified
- through a direct message.
-- This assumes the mentioned SPs supports managed exit.
-
-The SPMC is the first to be notified about PM events from the SPMD. It is up
-to the SPMC to arbitrate to which SP it needs to send PM events.
-An SP explicitly registers to receive notifications to specific PM events.
-The register operation can either be an implementation-defined service call
-to the SPMC when the primary SP EC boots, or be supplied through the SP
-manifest.
-
-Support for SMMUv3 in Hafnium
-=============================
+SMMUv3 support in Hafnium
+=========================
An SMMU is analogous to an MMU in a CPU. It performs address translations for
Direct Memory Access (DMA) requests from system I/O devices.
@@ -856,7 +829,7 @@
.. image:: ../resources/diagrams/MMU-600.png
SMMU has several versions including SMMUv1, SMMUv2 and SMMUv3. Hafnium provides
-support for SMMUv3 driver in both Normal and Secure World. A brief introduction
+support for SMMUv3 driver in both normal and secure world. A brief introduction
of SMMUv3 functionality and the corresponding software support in Hafnium is
provided here.
@@ -956,7 +929,7 @@
.. _[3]:
[3] `Trusted Boot Board Requirements
-Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a>`__
+Client <https://developer.arm.com/documentation/den0006/d/>`__
.. _[4]:
@@ -964,7 +937,7 @@
.. _[5]:
-[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts
+[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/plat/arm/fvp/fdts/cactus.dts
.. _[6]:
@@ -976,7 +949,7 @@
.. _[8]:
-[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/
+[8] https://lists.trustedfirmware.org/pipermail/tf-a/2020-February/000296.html
--------------
diff --git a/docs/plat/arm/juno/index.rst b/docs/plat/arm/juno/index.rst
index cf328fa..8b9d453 100644
--- a/docs/plat/arm/juno/index.rst
+++ b/docs/plat/arm/juno/index.rst
@@ -12,24 +12,21 @@
This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
-To execute the software stack on Juno, the version of the Juno board recovery
-image indicated in the `Linaro Release Notes`_ must be installed. If you have an
-earlier version installed or are unsure which version is installed, please
-re-install the recovery image by following the
-`Instructions for using Linaro's deliverables on Juno`_.
+To run TF-A on Juno, you need to first prepare an SD card with Juno software
+stack that includes TF-A. This version of TF-A is tested with pre-built
+`Linaro release software stack`_ version 20.01. You can alternatively
+build the software stack yourself by following the
+`Juno platform software user guide`_. Once you prepare the software stack
+on an SD card, you can replace the ``bl1.bin`` and ``fip.bin``
+binaries in the ``SOFTWARE/`` directory with custom built TF-A binaries.
Preparing TF-A images
---------------------
-After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the
-``SOFTWARE/`` directory of the Juno SD card.
-
-Creating a Firmware Image Package (FIP)
----------------------------------------
-
This section provides Juno and FVP specific instructions to build Trusted
Firmware, obtain the additional required firmware, and pack it all together in
-a single FIP binary. It assumes that a Linaro release has been installed.
+a single FIP binary. It assumes that a Linaro release software stack has been
+installed.
.. note::
Pre-built binaries for AArch32 are available from Linaro Release 16.12
@@ -57,9 +54,16 @@
make realclean
-#. Obtain SCP_BL2 (Juno) and BL33 (all platforms)
+#. Obtain SCP binaries (Juno)
- Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
+ This version of TF-A is tested with SCP version 2.8.0 on Juno. You can
+ download pre-built SCP binaries (``scp_bl1.bin`` and ``scp_bl2.bin``)
+ from `TF-A downloads page`_. Alternatively, you can `build
+ the binaries from source`_.
+
+#. Obtain BL33 (all platforms)
+
+ Use the fiptool to extract the BL33 image from the FIP
package included in the Linaro release:
.. code:: shell
@@ -71,8 +75,7 @@
./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin
The unpack operation will result in a set of binary images extracted to the
- current working directory. The SCP_BL2 image corresponds to
- ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
+ current working directory. BL33 corresponds to ``nt-fw.bin``.
.. note::
The fiptool will complain if the images to be unpacked already
@@ -102,7 +105,7 @@
.. code:: shell
- make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip
+ make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp_bl2.bin all fip
For AArch32:
@@ -144,7 +147,7 @@
.. code:: shell
make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
- BL33=nt-fw.bin SCP_BL2=scp-fw.bin \
+ BL33=nt-fw.bin SCP_BL2=scp_bl2.bin \
BL32=<path-to-temporary>/bl32.bin all fip
The resulting BL1 and FIP images may be found in:
@@ -159,6 +162,8 @@
./build/fvp/release/bl1.bin
./build/fvp/release/fip.bin
+After building TF-A, the files ``bl1.bin``, ``fip.bin`` and ``scp_bl1.bin``
+need to be copied to the ``SOFTWARE/`` directory on the Juno SD card.
Booting Firmware Update images
------------------------------
@@ -236,10 +241,12 @@
--------------
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
-.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
-.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno
+.. _Linaro release software stack: http://releases.linaro.org/members/arm/platforms/
+.. _Juno platform software user guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/juno/user-guide.rst
+.. _TF-A downloads page: https://downloads.trustedfirmware.org/tf-a/css_scp_2.8.0/juno/
+.. _build the binaries from source: https://github.com/ARM-software/SCP-firmware/blob/master/user_guide.md#scp-firmware-user-guide
.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
diff --git a/docs/resources/diagrams/ff-a-spm-sel2.png b/docs/resources/diagrams/ff-a-spm-sel2.png
index 6479ff5..605fd9b 100644
--- a/docs/resources/diagrams/ff-a-spm-sel2.png
+++ b/docs/resources/diagrams/ff-a-spm-sel2.png
Binary files differ
diff --git a/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png b/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
new file mode 100644
index 0000000..0619cf2
--- /dev/null
+++ b/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
Binary files differ
diff --git a/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png b/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
new file mode 100644
index 0000000..f110028
--- /dev/null
+++ b/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
Binary files differ
