.. SPDX-License-Identifier: GPL-2.0+ Arm FF-A Support ================ Summary ------- FF-A stands for Firmware Framework for Arm A-profile processors. FF-A specifies interfaces that enable a pair of software execution environments aka partitions to communicate with each other. A partition could be a VM in the Normal or Secure world, an application in S-EL0, or a Trusted OS in S-EL1. The U-Boot FF-A support (the bus) implements the interfaces to communicate with partitions in the Secure world aka Secure partitions (SPs). The FF-A support specifically focuses on communicating with SPs that isolate portions of EFI runtime services that must run in a protected environment which is inaccessible by the Host OS or Hypervisor. Examples of such services are set/get variables. The FF-A support uses the SMC ABIs defined by the FF-A specification to: - Discover the presence of SPs of interest - Access an SP's service through communication protocols e.g. EFI MM communication protocol At this stage of development only EFI boot-time services are supported. Runtime support will be added in future developments. The U-Boot FF-A support provides the following parts: - A Uclass driver providing generic FF-A methods. - An Arm FF-A device driver providing Arm-specific methods and reusing the Uclass methods. FF-A and SMC specifications ------------------------------------------- The current implementation of the U-Boot FF-A support relies on `FF-A v1.0 specification`_ and uses SMC32 calling convention which means using the first 32-bit data of the Xn registers. At this stage we only need the FF-A v1.0 features. The FF-A support has been tested with OP-TEE which supports SMC32 calling convention. Hypervisors are supported if they are configured to trap SMC calls. The FF-A support uses 64-bit registers as per `SMC Calling Convention v1.2 specification`_. Supported hardware -------------------------------- Aarch64 plaforms Configuration ---------------------- CONFIG_ARM_FFA_TRANSPORT Enables the FF-A support. Turn this on if you want to use FF-A communication. When using an Arm 64-bit platform, the Arm FF-A driver will be used. FF-A ABIs under the hood --------------------------------------- Invoking an FF-A ABI involves providing to the secure world/hypervisor the expected arguments from the ABI. On an Arm 64-bit platform, the ABI arguments are stored in x0 to x7 registers. Then, an SMC instruction is executed. At the secure side level or hypervisor the ABI is handled at a higher exception level and the arguments are read and processed. The response is put back through x0 to x7 registers and control is given back to the U-Boot Arm FF-A driver (non-secure world). The driver reads the response and processes it accordingly. This methodology applies to all the FF-A ABIs. FF-A bus discovery on Arm 64-bit platforms --------------------------------------------- When CONFIG_ARM_FFA_TRANSPORT is enabled, the FF-A bus is considered as an architecture feature and discovered using ARM_SMCCC_FEATURES mechanism. This discovery mechanism is performed by the PSCI driver. The PSCI driver comes with a PSCI device tree node which is the root node for all architecture features including FF-A bus. :: => dm tree Class Index Probed Driver Name ----------------------------------------------------------- ... firmware 0 [ + ] psci |-- psci ffa 0 [ ] arm_ffa | `-- arm_ffa ... The PSCI driver is bound to the PSCI device and when probed it tries to discover the architecture features by calling a callback the features drivers provide. In case of FF-A, the callback is arm_ffa_is_supported() which tries to discover the FF-A framework by querying the FF-A framework version from secure world using FFA_VERSION ABI. When discovery is successful, the ARM_SMCCC_FEATURES mechanism creates a U-Boot device for the FF-A bus and binds the Arm FF-A driver with the device using device_bind_driver(). At this stage the FF-A bus is registered with the DM and can be interacted with using the DM APIs. Clients are able to probe then use the FF-A bus by calling uclass_first_device(). When calling uclass_first_device(), the FF-A driver is probed and ends up calling ffa_do_probe() provided by the Uclass which does the following: - saving the FF-A framework version in uc_priv - querying from secure world the u-boot endpoint ID - querying from secure world the supported features of FFA_RXTX_MAP - mapping the RX/TX buffers - querying from secure world all the partitions information When one of the above actions fails, probing fails and the driver stays not active and can be probed again if needed. Requirements for clients ------------------------------------- When using the FF-A bus with EFI, clients must query the SPs they are looking for during EFI boot-time mode using the service UUID. The RX/TX buffers are only available at EFI boot-time. Querying partitions is done at boot time and data is cached for future use. RX/TX buffers should be unmapped before EFI runtime mode starts. The driver provides a bus operation for that called ffa_rxtx_unmap(). The user should call ffa_rxtx_unmap() to unmap the RX/TX buffers when required (e.g: at efi_exit_boot_services()). The Linux kernel allocates its own RX/TX buffers. To be able to register these kernel buffers with secure world, the U-Boot's RX/TX buffers should be unmapped before EFI runtime starts. When invoking FF-A direct messaging, clients should specify which ABI protocol they want to use (32-bit vs 64-bit). Selecting the protocol means using the 32-bit or 64-bit version of FFA_MSG_SEND_DIRECT_{REQ, RESP}. The calling convention between U-Boot and the secure world stays the same: SMC32. Requirements for user drivers ------------------------------------- Users who want to implement their custom FF-A device driver while reusing the FF-A Uclass can do so by implementing their own invoke_ffa_fn() in the user driver. The bus driver layer ------------------------------ FF-A support comes on top of the SMCCC layer and is implemented by the FF-A Uclass drivers/firmware/arm-ffa/arm-ffa-uclass.c The following features are provided: - Support for the 32-bit version of the following ABIs: - FFA_VERSION - FFA_ID_GET - FFA_FEATURES - FFA_PARTITION_INFO_GET - FFA_RXTX_UNMAP - FFA_RX_RELEASE - FFA_RUN - FFA_ERROR - FFA_SUCCESS - FFA_INTERRUPT - FFA_MSG_SEND_DIRECT_REQ - FFA_MSG_SEND_DIRECT_RESP - Support for the 64-bit version of the following ABIs: - FFA_RXTX_MAP - FFA_MSG_SEND_DIRECT_REQ - FFA_MSG_SEND_DIRECT_RESP - Processing the received data from the secure world/hypervisor and caching it - Hiding from upper layers the FF-A protocol and registers details. Upper layers focus on exchanged data, FF-A support takes care of how to transport that to the secure world/hypervisor using FF-A - FF-A support provides driver operations to be used by upper layers: - ffa_partition_info_get - ffa_sync_send_receive - ffa_rxtx_unmap - FF-A bus discovery makes sure FF-A framework is responsive and compatible with the driver - FF-A bus can be compiled and used without EFI Example of boot logs with FF-A enabled -------------------------------------- For example, when using FF-A with Corstone-1000 the logs are as follows: :: U-Boot 2023.01 (May 10 2023 - 11:08:07 +0000) corstone1000 aarch64 DRAM: 2 GiB Arm FF-A framework discovery FF-A driver 1.0 FF-A framework 1.0 FF-A versions are compatible ... FF-A driver 1.0 FF-A framework 1.0 FF-A versions are compatible EFI: MM partition ID 0x8003 ... EFI stub: Booting Linux Kernel... ... Linux version 6.1.9-yocto-standard (oe-user@oe-host) (aarch64-poky-linux-musl-gcc (GCC) 12.2.0, GNU ld (GNU Binutils) 2.40.202301193 Machine model: ARM Corstone1000 FPGA MPS3 board Contributors ------------ * Abdellatif El Khlifi .. _`FF-A v1.0 specification`: https://documentation-service.arm.com/static/5fb7e8a6ca04df4095c1d65e .. _`SMC Calling Convention v1.2 specification`: https://documentation-service.arm.com/static/5f8edaeff86e16515cdbe4c6