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 ARM Trusted Firmware tree will be released and available at https://github.com/Xilinx/arm-trusted-firmware.

Xilinx software stacks running on the Zynq US+ MPSoC 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 Embedded Methodology Development Guide.

Zynq US+ MPSoC 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, ATF provides access and functions that are similar to other SoC’s, and it also provides functions and access to unique Zynq US+ MPSoC-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. 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


Build Procedure:


The Xilinx ARM Trusted Firmware can be build as per procedure mentioned below

More information on Build procedure and build options specific to xilinx can be found at https://github.com/Xilinx/arm-trusted-firmware/blob/master/docs/plat/xilinx-zynqmp.md

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_INIT
0xC2000015
PM_GET_CHIPID
0xC2000018

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

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
0xC2000020
To calculate SHA3 hash - At linux level
PM_SECURE_RSA
0xC2000021
To calculate RSA encrypted data with public key and decrypt with RSA signature with provided key size.

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

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

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