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.8 for 2023.1.

Build Procedure:
The Xilinx ARM Trusted Firmware can be built as per procedure mentioned below

Build ARM Trusted Firmware

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

For ZYNQMP: https://github.com/Xilinx/arm-trusted-firmware/blob/master/docs/plat/xilinx-zynqmp.md

For VERSAL: https://github.com/Xilinx/arm-trusted-firmware/blob/master/docs/plat/xilinx-versal.md

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.

Functionality	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
PSCI	Power 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).

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Various Power Management functions	Enables OS to exercise Platform Management on platform	drivers/firmware/xilinx/zynqmp/firmware.c	Refer 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 API	SMC ID
PM_GET_API_VERSION	0xC2000001
PM_SET_CONFIGURATION	0xC2000002
PM_GET_NODE_STATUS	0xC2000003
PM_GET_OP_CHARACTERISTIC	0xC2000004
PM_REGISTER_NOTIFIER	0xC2000005
PM_REQ_SUSPEND	0xC2000006
PM_SELF_SUSPEND,	0xC2000007
PM_FORCE_POWERDOWN	0xC2000008
PM_ABORT_SUSPEND	0xC2000009
PM_REQ_WAKEUP	0xC200000A
PM_SET_WAKEUP_SOURCE	0xC200000B
PM_SYSTEM_SHUTDOWN	0xC200000C
PM_REQ_NODE	0xC200000D
PM_RELEASE_NODE	0xC200000E
PM_SET_REQUIREMENT	0xC200000F
PM_SET_MAX_LATENCY	0xC2000010
PM_RESET_ASSERT	0xC2000011
PM_RESET_GET_STATUS	0xC2000012
PM_MMIO_WRITE	0xC2000013
PM_MMIO_READ	0xC2000014
PM_INIT_FINALIZE	0xC2000015
PM_GET_CHIPID	0xC2000018
PM_REGISTER_ACCESS	0xC2000034
PM_EFUSE_ACCESS	0xC2000035

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
FPGA Load	FPGA PL bitstream programming	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_FPGA_LOAD	0xC2000016
PM_FPGA_GET_STATUS	0xC2000017
PM_FPGA_READ	0xC200002E

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Crypto	At 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 API	SMC ID	Comment
PM_SECURE_RSA_AES	0xC2000019	This is used for authentication and decryption of secure images at u-boot level to mainly load secure dtb and secure linux image.
PM_SECURE_SHA	0xC200001A	To calculate SHA3 hash - At linux level
PM_SECURE_RSA	0xC200001B	To calculate RSA encrypted data with public key and decrypt with RSA signature with provided key size.
PM_SECURE_AES	0xC200002F
PM_SECURE_IMAGE	0xC200002D

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Query data	Request 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_API	SMC_ID
PM_QUERY_DATA	0xC2000023

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Device Control	Control 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_API	SMC_ID
PM_IOCTL	0xC2000022

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Clock	Control 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_API	SMC_ID
PM_CLOCK_ENABLE	0xC2000024
PM_CLOCK_DISABLE	0xC2000025
PM_CLOCK_GETSTATE	0xC2000026
PM_CLOCK_SETDIVIDER	0xC2000027
PM_CLOCK_GETDIVIDER	0xC2000028
PM_CLOCK_SETRATE	0xC2000029
PM_CLOCK_GETRATE	0xC200002A
PM_CLOCK_SETPARENT	0xC200002B
PM_CLOCK_GETPARENT	0xC200002C
PM_PLL_SET_PARAMETER	0xC2000030
PM_PLL_GET_PARAMETER	0xC2000031
PM_PLL_SET_MODE	0xC2000032
PM_PLL_GET_MODE	0xC2000033

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Pin control	Control 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_API	SMC_ID
PM_PINCTRL_REQUEST	0xC200001C
PM_PINCTRL_RELEASE	0xC200001D
PM_PINCTRL_GET_FUNCTION	0xC200001E
PM_PINCTRL_SET_FUNCTION	0xC200001F
PM_PINCTRL_CONFIG_PARAM_GET	0xC2000020
PM_PINCTRL_CONFIG_PARAM_SET	0xC2000021

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Various Power Management functions	Enables OS to exercise Platform Management on platform	drivers/firmware/xilinx/zynqmp.c	Refer table below. ATF source: plat/xilinx/versal/pm_service/pm_defs.h

PM API	SMC ID
PM_GET_API_VERSION	0xC2000001
PM_GET_DEVICE_STATUS	0xC2000003
PM_GET_OP_CHARACTERISTIC	0xC2000004
PM_REQ_SUSPEND	0xC2000006
PM_SELF_SUSPEND,	0xC2000007
PM_FORCE_POWERDOWN	0xC2000008
PM_ABORT_SUSPEND	0xC2000009
PM_REQ_WAKEUP	0xC200000A
PM_SET_WAKEUP_SOURCE	0xC200000B
PM_SYSTEM_SHUTDOWN	0xC200000C
PM_REQUEST_DEVICE	0xC200000D
PM_RELEASE_DEVICE	0xC200000E
PM_SET_REQUIREMENT	0xC200000F
PM_RESET_ASSERT	0xC2000011
PM_RESET_GET_STATUS	0xC2000012
PM_INIT_FINALIZE	0xC2000015
PM_GET_CHIPID	0xC2000018

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Query data	Request 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_API	SMC_ID
PM_QUERY_DATA	0xC2000023

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Device Control	Control 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_API	SMC_ID
PM_IOCTL	0xC2000022

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Clock	Control 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_API	SMC_ID
PM_CLOCK_ENABLE	0xC2000024
PM_CLOCK_DISABLE	0xC2000025
PM_CLOCK_GETSTATE	0xC2000026
PM_CLOCK_SETDIVIDER	0xC2000027
PM_CLOCK_GETDIVIDER	0xC2000028
PM_CLOCK_SETRATE	0xC2000029
PM_CLOCK_GETRATE	0xC200002A
PM_CLOCK_SETPARENT	0xC200002B
PM_CLOCK_GETPARENT	0xC200002C
PM_PLL_SET_PARAMETER	0xC2000030
PM_PLL_GET_PARAMETER	0xC2000031
PM_PLL_SET_MODE	0xC2000032
PM_PLL_GET_MODE	0xC2000033

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.

Function	Overview	Corresponding Linux Source	ATF SMC(s) Used	Comments
Pin control	Control 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_API	SMC_ID
PM_PINCTRL_REQUEST	0xC200001C
PM_PINCTRL_RELEASE	0xC200001D
PM_PINCTRL_GET_FUNCTION	0xC200001E
PM_PINCTRL_SET_FUNCTION	0xC200001F
PM_PINCTRL_CONFIG_PARAM_GET	0xC2000020
PM_PINCTRL_CONFIG_PARAM_SET	0xC2000021

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

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

Xilinx Wiki

Arm Trusted Firmware