Arm Trusted Firmware





Table of Contents


Introduction:

ARM Trusted Firmware provides a reference to secure software for ARMv8-A architecture and it provides implementations of various interface standards like PSCI(Power State Coordination Interface) and Secure monitor code for interfacing to Normal world software. Xilinx ARM trusted firmware is based on arm trusted firmware at https://github.com/ARM-software/arm-trusted-firmware.
Xilinx's ARM Trusted Firmware port is released and available at https://github.com/Xilinx/arm-trusted-firmware.

Xilinx software stacks running on the Zynq US+ MPSoC/Versal  APU conform to the standard ARMv8 topology where Linux running at ARM EL1/0 has hardware-limited access to system or security-critical registers or devices. All interactions from Linux to those devices, or registers are routed through ARM Trusted Firmware which runs at EL3. More complete information is available in the Zynq US+ MPSoC/Versal Embedded Methodology Development Guide.

Zynq US+ MPSoC/Versal uses ATF in a manner similar to other ARMv8-based SoCs. ATF acts as a proxy to modify system-critical settings on behalf of the operating system running at EL1. Chapter 16 of Zynq UltraScale+ MPSoC TRM UG1085 – includes the hardware-information necessary for a developer to run their operating system at EL1.

Within Zynq US+ MPSoC/ Versal, ATF provides access and functions that are similar to other SoC’s, and it also provides functions and access to unique Zynq US+ MPSoC/Versal-specific devices or features.

In order for the operating system to gain access to these underlying functions, it must be modified to support the Secure Monitor Calls exported by ATF to the OS itself.



Xilinx ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq UltraScale + MPSoC/Versal. The platform only uses the runtime part of ATF(EL3 firmware) as ZynqMP already has a BootROM (BL1) and FSBL (BL2).

Documentation

Detailed documentation on ATF can be found with in source(docs/) at https://github.com/Xilinx/arm-trusted-firmware/tree/master/docs
Upgraded ATF to V2.2 for 2020.1.
Build Procedure:
The Xilinx ARM Trusted Firmware can be built as per procedure mentioned below

More information on the build procedure and build options specific to Xilinx can be found at

Building ATF to DDR location

For ZYNQMP:

By default, the Arm-trusted firmware builds for OCM space at address 0xFFFEA000. But, with DEBUG flag set to 1, it can't fit in OCM, so by default with DEBUG=1, it builds for DDR location 0x1000 with build flag DEBUG=1 mentioned while building. Alternatively, user has always an option to build for the location of their choice by specifying  the build flags ZYNQMP_ATF_MEM_BASE, ZYNQMP_ATF_MEM_SIZE while building. The flag ZYNQMP_ATF_MEM_BASE specifies the base address of ATF and flag ZYNQMP_ATF_MEM_SIZE specifies the maximum size the ATF image can be.

Example build command:

  • make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31 ZYNQMP_ATF_MEM_BASE=0x10000 ZYNQMP_ATF_MEM_SIZE=0x40000

The above commands builds ATF for DDR location 0x10000 with image size restricted to 0x40000 which means ATF image can span from 0x10000 to 0x50000 in DDR.

For VERSAL:

By default, the Arm-trusted firmware builds for OCM space at address 0xFFFEA000. Currently it can fit in OCM, so with DEBUG=1 it builds for the location 0xFFFEA0000. Alternatively, user has always an option to build for the location of their choice by specifying  the build flags VERSAL_ATF_MEM_BASE, VERSAL_ATF_MEM_SIZE while building. The flag VERSAL_ATF_MEM_BASE specifies the base address of ATF and flag VERSAL_ATF_MEM_SIZE specifies the maximum size the ATF image can be.

Example build command:

  • make CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 VERSAL_ATF_MEM_BASE=0x10000 VERSAL_ATF_MEM_SIZE=0x40000

The above commands builds ATF for DDR location 0x10000 with image size restricted to 0x40000 which means ATF image can span from 0x10000 to 0x50000 in DDR.


SMC Handling

SMC(Secure Monitor call) is an instruction which is used to generate a synchronous exception which will be handled by Secure Monitor code running in EL3. The SMC will generally be invoked by a software running in Normal world/any Secure software (ex: EL1-Secure) for access to functionality which has to be handled in secure level i.e EL3. The arguments and return values are passed in Aarch64 general purpose registers. Once the smc is handled by the ATF, the result from this will be passed on to a Trusted OS or some other entity in the secure software stack.

PSCI(Power State Coordination Interface)

As of now, ATF supports PSCI standard 1.0. All PSCI operations can be performed using corresponding SMC from upper level software. Xilinx ATF handles power management related psci ops (ex: cpu standy, cpu suspend, power on, power off, system off, system reset etc..) in PMU FW and ATF take care of passing the respective operation to PMUFW using IPI.

For more information on PSCI, please refer to PSCI specification at http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf

For information on PSCI implemenation in ATF , please refer to docs/psci-lib-integration-guide.md and psci-pd-tree.md.

FunctionalityOverviewCorresponding Linux SourceATF SMC(s) UsedComments
PSCIPower State Coordination Interface is used to coordinate power control among supervisory systems concurrently running on a device which allows a supervisory system to request cores to be powered up or down, and torequest context transfer where necessary and soon.drivers/firmware/psci.c
include/linux/psci.h
include/uapi/linux/psci.h
Refer include/lib/psci/psci.h in ATF source

Zynq US+ Power Management

Below are the Zynq US+ specific SMC ID's list which are mostly the Power Management functionalities that are being handled by ATF through SMC calls from upper level software. For all the SMC ID's in ZynqMP, the ATF acts a pass through for handling it in Platform Management Unit(PMU) Firmware. Upon receiving the Synchronous exception through SMC, ATF checks for the SMC ID and accordingly communicates with PMU through IPI for handling it in PMU firmware and gets the response/result from it to pass the same to upper level software. More details on the functionalities of each can be found in Chapter11 Power Management Framework of Zynq UltraScale+ MPSoCSoftware Developer Guide (ug1137).

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Various Power Management functionsEnables OS to exercise Platform Management on platformdrivers/firmware/xilinx/zynqmp/firmware.cRefer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
Refer to UG1137 ch-11 for more information on below SMC's

PM APISMC ID
PM_GET_API_VERSION0xC2000001
PM_SET_CONFIGURATION0xC2000002
PM_GET_NODE_STATUS0xC2000003
PM_GET_OP_CHARACTERISTIC0xC2000004
PM_REGISTER_NOTIFIER0xC2000005
PM_REQ_SUSPEND0xC2000006
PM_SELF_SUSPEND,0xC2000007
PM_FORCE_POWERDOWN0xC2000008
PM_ABORT_SUSPEND0xC2000009
PM_REQ_WAKEUP0xC200000A
PM_SET_WAKEUP_SOURCE0xC200000B
PM_SYSTEM_SHUTDOWN0xC200000C
PM_REQ_NODE0xC200000D
PM_RELEASE_NODE0xC200000E
PM_SET_REQUIREMENT0xC200000F
PM_SET_MAX_LATENCY0xC2000010
PM_RESET_ASSERT0xC2000011
PM_RESET_GET_STATUS0xC2000012
PM_MMIO_WRITE0xC2000013
PM_MMIO_READ0xC2000014
PM_INIT_FINALIZE0xC2000015
PM_GET_CHIPID0xC2000018
PM_REGISTER_ACCESS0xC2000034
PM_EFUSE_ACCESS0xC2000035

Zynq US+ FPGA access

In Zynq US+, the PL programming is carried out at higher privilege level by performing corresponding SMC's from the higher level software(ex: u-boot, Linux or any other OS). The Below SMC's are responsible for loading the PL bit stream and its status. Here also, ATF responsible for passing it PMU firmware which was integrated with xilfpga library.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
FPGA LoadFPGA PL bitstream programmingdrivers/firmware/xilinx/zynqmp/firmware.cRefer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_main.c


PM_FPGA_LOAD0xC2000016
PM_FPGA_GET_STATUS0xC2000017
PM_FPGA_READ0xC200002E

Zynq US+ Crypto
In Zynq US+, the security/crypto functionality also carried out at higher privilege levels with the fact that the crypto engines should be accessible only at higher privileged software. The below SMC is responsible for authentication and decryption of images. The upper level software can authenticate or decrypt an image only through ATF using the below SMC.


FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
CryptoAt u-boot level authentication and decryption of secure images and
at linux level one can use crypto functions generic way to calculate SHA3 hash and RSA encryption with
public key and decryption with private key..
u-boot:
board/xilinx/zynqmp/zynqmp.c
Linux:
drivers/firmware/xilinx/zynqmp/firmware.c
Refer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_main.c


PM APISMC IDComment
PM_SECURE_RSA_AES0xC2000019This is used for authentication and decryption of secure images at u-boot level to mainly load secure dtb and secure linux image.
PM_SECURE_SHA0xC200001ATo calculate SHA3 hash - At linux level
PM_SECURE_RSA0xC200001BTo calculate RSA encrypted data with public key and decrypt with RSA signature with provided key size.
PM_SECURE_AES0xC200002F
PM_SECURE_IMAGE0xC200002D

Zynq US+ Query data

In Zynq US+, the high privileged level software maintains platform specific data. Higher level software (e.g. Linux) can query platform specific data (e.g. clock information, pin information, etc) from firmware. Underneath firmware (ATF or PMU) contains these information and returns requested data.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Query dataRequest platform specific data from firmware.Linux:
drivers/firmware/xilinx/zynqmp/firmware.c
Refer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_svc_main.c
plat/xilinx/zynqmp/pm_service/pm_api_pinctrl.c
plat/xilinx/zynqmp/pm_service/pm_api_clock.c


PM_APISMC_ID
PM_QUERY_DATA0xC2000023

Zynq US+ Device control

In Zynq US+, the device control and configurations are carried out at higher privilege level by performing corresponding SMC's from the higher level software(ex: u-boot, Linux or any other OS). The Below SMC's are responsible for device control and configurations. Here also, ATF responsible for handling them or passing to PMUFW for requested action.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Device ControlControl and configure devices.Linux:
drivers/firmware/xilinx/zynqmp/firmware.c
Refer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_svc_main.c
plat/xilinx/zynqmp/pm_service/pm_api_ioctl.c


PM_APISMC_ID
PM_IOCTL0xC2000022

Zynq US+ Clock

In Zynq US+, the clock control is carried out at higher privilege level by performing corresponding SMC's from the higher level Linux. The Below SMC's are responsible for controlling clocks. Here ATF calls MMIO read/write to perform clock management.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
ClockControl clocks in following ways:
  • Enable/Disable clocks
  • Set/Get rate of clocks (not implemented in 2018.1)
  • Set/Get divider of clock
  • Set/Get current parent clock
Linux:
drivers/firmware/xilinx/zynqmp/firmware.c
Refer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_svc_main.c
plat/xilinx/zynqmp/pm_service/pm_api_clock.c


PM_APISMC_ID
PM_CLOCK_ENABLE0xC2000024
PM_CLOCK_DISABLE0xC2000025
PM_CLOCK_GETSTATE0xC2000026
PM_CLOCK_SETDIVIDER0xC2000027
PM_CLOCK_GETDIVIDER0xC2000028
PM_CLOCK_SETRATE0xC2000029
PM_CLOCK_GETRATE0xC200002A
PM_CLOCK_SETPARENT0xC200002B
PM_CLOCK_GETPARENT0xC200002C
PM_PLL_SET_PARAMETER0xC2000030
PM_PLL_GET_PARAMETER0xC2000031
PM_PLL_SET_MODE0xC2000032
PM_PLL_GET_MODE0xC2000033

Zynq US+ Pin control

In Zynq US+, the pin control and configurations are carried out at higher privilege level by performing corresponding SMC's from the higher level Linux. The Below SMC's are responsible for pin control and configurations. Here ATF calls MMIO read/write to perform pinmux and pin configurations.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Pin controlControl pins in following ways:
  • Set/Get pin functions
  • Set/Get pin configurations (e.g. slew rate, pull settings, etc)
Linux:
drivers/firmware/xilinx/zynqmp/firmware.c
Refer table below.
ATF source:
plat/xilinx/zynqmp/pm_service/pm_defs.h
plat/xilinx/zynqmp/pm_service/pm_svc_main.c
plat/xilinx/zynqmp/pm_service/pm_api_pinctrl.c


PM_APISMC_ID
PM_PINCTRL_REQUEST0xC200001C
PM_PINCTRL_RELEASE0xC200001D
PM_PINCTRL_GET_FUNCTION0xC200001E
PM_PINCTRL_SET_FUNCTION0xC200001F
PM_PINCTRL_CONFIG_PARAM_GET0xC2000020
PM_PINCTRL_CONFIG_PARAM_SET0xC2000021


Versal Power Management

Below are the Versal specific SMC ID's list which are mostly the Power Management functionalities that are being handled by ATF through SMC calls from upper level software. For all the SMC ID's in Versal, the ATF acts a pass through for handling it in Platform Management Unit(PMU) Firmware. Upon receiving the Synchronous exception through SMC, ATF checks for the SMC ID and accordingly communicates with PMU through IPI for handling it in PMU firmware and gets the response/result from it to pass the same to upper level software. 

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Various Power Management functionsEnables OS to exercise Platform Management on platformdrivers/firmware/xilinx/zynqmp.cRefer table below.
ATF source:
plat/xilinx/versal/pm_service/pm_defs.h

PM APISMC ID
PM_GET_API_VERSION0xC2000001
PM_GET_DEVICE_STATUS0xC2000003
PM_GET_OP_CHARACTERISTIC0xC2000004
PM_REQ_SUSPEND0xC2000006
PM_SELF_SUSPEND,0xC2000007
PM_FORCE_POWERDOWN0xC2000008
PM_ABORT_SUSPEND0xC2000009
PM_REQ_WAKEUP0xC200000A
PM_SET_WAKEUP_SOURCE0xC200000B
PM_SYSTEM_SHUTDOWN0xC200000C
PM_REQUEST_DEVICE0xC200000D
PM_RELEASE_DEVICE0xC200000E
PM_SET_REQUIREMENT0xC200000F
PM_RESET_ASSERT0xC2000011
PM_RESET_GET_STATUS0xC2000012
PM_INIT_FINALIZE0xC2000015
PM_GET_CHIPID0xC2000018

Versal Query data

In Versal, the high privileged level software maintains platform specific data. Higher level software (e.g. Linux) can query platform specific data (e.g. clock information, pin information, etc) from firmware. Underneath firmware (ATF or PMU) contains these information and returns requested data.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Query dataRequest platform specific data from firmware.Linux:
drivers/firmware/xilinx/zynqmp.c
Refer table below.
ATF source:
plat/xilinx/versal/pm_service/pm_defs.h
plat/xilinx/versal/pm_service/pm_svc_main.c
plat/xilinx/versal/pm_service/pm_client.c


PM_APISMC_ID
PM_QUERY_DATA0xC2000023

Versal Device control

In Versal, the device control and configurations are carried out at higher privilege level by performing corresponding SMC's from the higher level software(ex: u-boot, Linux or any other OS). The Below SMC's are responsible for device control and configurations. Here also, ATF responsible for handling them or passing to PMUFW for requested action.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Device ControlControl and configure devices.Linux:
drivers/firmware/xilinx/zynqmp.c
Refer table below.
ATF source:
plat/xilinx/versal/pm_service/pm_defs.h
plat/xilinx/versal/pm_service/pm_svc_main.c
plat/xilinx/versal/pm_service/pm_api_sys.c

PM_APISMC_ID
PM_IOCTL0xC2000022

Versal Clock

In Versal, the clock control is carried out at higher privilege level by performing corresponding SMC's from the higher level Linux. The Below SMC's are responsible for controlling clocks. Here ATF calls MMIO read/write to perform clock management.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
ClockControl clocks in following ways:
  • Enable/Disable clocks
  • Set/Get rate of clocks 
  • Set/Get divider of clock
  • Set/Get current parent clock
Linux:
drivers/firmware/xilinx/zynqmp.c
Refer table below.
ATF source:
plat/xilinx/versal/pm_service/pm_defs.h
plat/xilinx/versal/pm_service/pm_svc_main.c
plat/xilinx/versal/pm_service/pm_api_sys.c

PM_APISMC_ID
PM_CLOCK_ENABLE0xC2000024
PM_CLOCK_DISABLE0xC2000025
PM_CLOCK_GETSTATE0xC2000026
PM_CLOCK_SETDIVIDER0xC2000027
PM_CLOCK_GETDIVIDER0xC2000028
PM_CLOCK_SETRATE0xC2000029
PM_CLOCK_GETRATE0xC200002A
PM_CLOCK_SETPARENT0xC200002B
PM_CLOCK_GETPARENT0xC200002C
PM_PLL_SET_PARAMETER0xC2000030
PM_PLL_GET_PARAMETER0xC2000031
PM_PLL_SET_MODE0xC2000032
PM_PLL_GET_MODE0xC2000033

Versal Pin control

In Versal, the pin control and configurations are carried out at higher privilege level by performing corresponding SMC's from the higher level Linux. The Below SMC's are responsible for pin control and configurations. Here ATF calls MMIO read/write to perform pinmux and pin configurations.

FunctionOverviewCorresponding Linux SourceATF SMC(s) UsedComments
Pin controlControl pins in following ways:
  • Set/Get pin functions
  • Set/Get pin configurations (e.g. slew rate, pull settings, etc)
Linux:
drivers/firmware/xilinx/zynqmp.c
Refer table below.
ATF source:
plat/xilinx/versal/pm_service/pm_defs.h
plat/xilinx/versal/pm_service/pm_svc_main.c
plat/xilinx/versal/pm_service/pm_api_sys.c

PM_APISMC_ID
PM_PINCTRL_REQUEST0xC200001C
PM_PINCTRL_RELEASE0xC200001D
PM_PINCTRL_GET_FUNCTION0xC200001E
PM_PINCTRL_SET_FUNCTION0xC200001F
PM_PINCTRL_CONFIG_PARAM_GET0xC2000020
PM_PINCTRL_CONFIG_PARAM_SET0xC2000021

Release Notes



NOTE

Vivado allows assigning different IPI channels to each processor. So APU can be assigned any channel based on user's choice and the XPPU is configured accordingly to enforce this allocation. However, ATF uses a fixed IPI configuration without any way for user to specify the IPI slot. So, user has to modify this explicitly if there are any modification from default channel allocation. The below definitions in ATF file (plat/xilinx/zynqmp/pm_service/pm_ipi.c) has to be modified if any change is performed during IPI channel allocation.

#define IPI_BUFFER_RPU_0_BASE (IPI_BUFFER_BASEADDR + 0x0U)
#define IPI_BUFFER_RPU_1_BASE (IPI_BUFFER_BASEADDR + 0x200U)
#define IPI_BUFFER_APU_BASE (IPI_BUFFER_BASEADDR + 0x400U)
#define IPI_BUFFER_PL_0_BASE (IPI_BUFFER_BASEADDR + 0x600U)
#define IPI_BUFFER_PL_1_BASE (IPI_BUFFER_BASEADDR + 0x800U)
#define IPI_BUFFER_PL_2_BASE (IPI_BUFFER_BASEADDR + 0xA00U)
#define IPI_BUFFER_PL_3_BASE (IPI_BUFFER_BASEADDR + 0xC00U)
#define IPI_BUFFER_PMU_BASE (IPI_BUFFER_BASEADDR + 0xE00U)

Known Issues(If any)


Function Overview Corresponding Linux Source ATF SMC(s) Used ATF Dependencies For More Information
Various Power Management functions Enables OS to exercise power management on platform .c, .lib, See UG1199