1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2019-2025, Linaro Limited 4 */ 5 6 /* 7 * This file is exported by OP-TEE and is kept in sync between secure world 8 * and normal world drivers. We're using ARM FF-A 1.0 specification. 9 */ 10 11 #ifndef __OPTEE_FFA_H 12 #define __OPTEE_FFA_H 13 14 #include <ffa.h> 15 16 /* 17 * Normal world sends requests with FFA_MSG_SEND_DIRECT_REQ and 18 * responses are returned with FFA_MSG_SEND_DIRECT_RESP for normal 19 * messages. 20 * 21 * All requests with FFA_MSG_SEND_DIRECT_REQ and FFA_MSG_SEND_DIRECT_RESP 22 * are using the AArch32 SMC calling convention with register usage as 23 * defined in FF-A specification: 24 * w0: Function ID (0x8400006F or 0x84000070) 25 * w1: Source/Destination IDs 26 * w2: Reserved (MBZ) 27 * w3-w7: Implementation defined, free to be used below 28 */ 29 30 #define OPTEE_FFA_VERSION_MAJOR UINT32_C(1) 31 #define OPTEE_FFA_VERSION_MINOR UINT32_C(0) 32 33 #define OPTEE_FFA_BLOCKING_CALL(id) UINT32_C(id) 34 #define OPTEE_FFA_YIELDING_CALL_BIT U(31) 35 #define OPTEE_FFA_YIELDING_CALL(id) (UINT32_C(id) | \ 36 BIT32(OPTEE_FFA_YIELDING_CALL_BIT)) 37 38 /* 39 * Returns the API version implemented, currently follows the FF-A version. 40 * Call register usage: 41 * w3: Service ID, OPTEE_FFA_GET_API_VERSION 42 * w4-w7: Not used (MBZ) 43 * 44 * Return register usage: 45 * w3: OPTEE_FFA_VERSION_MAJOR 46 * w4: OPTEE_FFA_VERSION_MINOR 47 * w5-w7: Not used (MBZ) 48 */ 49 #define OPTEE_FFA_GET_API_VERSION OPTEE_FFA_BLOCKING_CALL(0) 50 51 /* 52 * Returns the revision of OP-TEE. 53 * 54 * Used by non-secure world to figure out which version of the Trusted OS 55 * is installed. Note that the returned revision is the revision of the 56 * Trusted OS, not of the API. 57 * 58 * Call register usage: 59 * w3: Service ID, OPTEE_FFA_GET_OS_VERSION 60 * w4-w7: Unused (MBZ) 61 * 62 * Return register usage: 63 * w3: CFG_OPTEE_REVISION_MAJOR 64 * w4: CFG_OPTEE_REVISION_MINOR 65 * w5: TEE_IMPL_GIT_SHA1 (or zero if not supported) 66 */ 67 #define OPTEE_FFA_GET_OS_VERSION OPTEE_FFA_BLOCKING_CALL(1) 68 69 /* 70 * Exchange capabilities between normal world and secure world. 71 * 72 * Currently there are no defined capabilities. When features are added new 73 * capabilities may be added. 74 * 75 * Call register usage: 76 * w3: Service ID, OPTEE_FFA_EXCHANGE_CAPABILITIES 77 * w4-w7: Not used (MBZ) 78 * 79 * Return register usage: 80 * w3: Error code, 0 on success 81 * w4: Bit[7:0]: Number of parameters needed for RPC to be supplied 82 * as the second MSG arg struct for 83 * OPTEE_FFA_YIELDING_CALL_WITH_ARG. 84 * Bit[31:8]: Reserved (MBZ) 85 * w5: Bitfield of OP-TEE capabilities OPTEE_FFA_SEC_CAP_* 86 * w6: The maximum secure world notification number 87 * w7: Not used (MBZ) 88 */ 89 /* 90 * Secure world supports giving an offset into the argument shared memory 91 * object, see also OPTEE_FFA_YIELDING_CALL_WITH_ARG 92 */ 93 #define OPTEE_FFA_SEC_CAP_ARG_OFFSET BIT(0) 94 /* OP-TEE supports asynchronous notification via FF-A */ 95 #define OPTEE_FFA_SEC_CAP_ASYNC_NOTIF BIT(1) 96 /* OP-TEE supports probing for RPMB device if needed */ 97 #define OPTEE_FFA_SEC_CAP_RPMB_PROBE BIT(2) 98 /* OP-TEE supports Protected Memory for secure data path */ 99 #define OPTEE_FFA_SEC_CAP_PROTMEM BIT(3) 100 101 #define OPTEE_FFA_EXCHANGE_CAPABILITIES OPTEE_FFA_BLOCKING_CALL(2) 102 103 /* 104 * Unregister shared memory 105 * 106 * Call register usage: 107 * w3: Service ID, OPTEE_FFA_YIELDING_CALL_UNREGISTER_SHM 108 * w4: Shared memory handle, lower bits 109 * w5: Shared memory handle, higher bits 110 * w6-w7: Not used (MBZ) 111 * 112 * Return register usage: 113 * w3: Error code, 0 on success 114 * w4-w7: Not used (MBZ) 115 */ 116 #define OPTEE_FFA_UNREGISTER_SHM OPTEE_FFA_BLOCKING_CALL(3) 117 118 /* 119 * Inform OP-TEE that the normal world is able to receive asynchronous 120 * notifications. 121 * 122 * Call register usage: 123 * w3: Service ID, OPTEE_FFA_ENABLE_ASYNC_NOTIF 124 * w4: Notification value to request bottom half processing, should be 125 * less than OPTEE_FFA_MAX_ASYNC_NOTIF_VALUE 126 * w5-w7: Not used (MBZ) 127 * 128 * Return register usage: 129 * w3: Error code, 0 on success 130 * w4-w7: Not used (MBZ) 131 */ 132 #define OPTEE_FFA_ENABLE_ASYNC_NOTIF OPTEE_FFA_BLOCKING_CALL(5) 133 134 #define OPTEE_FFA_MAX_ASYNC_NOTIF_VALUE 64 135 136 /* 137 * Release Protected memory 138 * 139 * Call register usage: 140 * w3: Service ID, OPTEE_FFA_RECLAIM_PROTMEM 141 * w4: Shared memory handle, lower bits 142 * w5: Shared memory handle, higher bits 143 * w6-w7: Not used (MBZ) 144 * 145 * Return register usage: 146 * w3: Error code, 0 on success 147 * w4-w7: Note used (MBZ) 148 */ 149 #define OPTEE_FFA_RELEASE_PROTMEM OPTEE_FFA_BLOCKING_CALL(8) 150 151 /* 152 * Call with struct optee_msg_arg as argument in the supplied shared memory 153 * with a zero internal offset and normal cached memory attributes. 154 * Register usage: 155 * w3: Service ID, OPTEE_FFA_YIELDING_CALL_WITH_ARG 156 * w4: Lower 32 bits of a 64-bit Shared memory handle 157 * w5: Upper 32 bits of a 64-bit Shared memory handle 158 * w6: Offset into shared memory pointing to a struct optee_msg_arg 159 * right after the parameters of this struct (at offset 160 * OPTEE_MSG_GET_ARG_SIZE(num_params) follows a struct optee_msg_arg 161 * for RPC, this struct has reserved space for the number of RPC 162 * parameters as returned by OPTEE_FFA_EXCHANGE_CAPABILITIES. 163 * MBZ unless the bit OPTEE_FFA_SEC_CAP_ARG_OFFSET is received with 164 * OPTEE_FFA_EXCHANGE_CAPABILITIES. 165 * w7: Not used (MBZ) 166 * Resume from RPC. Register usage: 167 * w3: Service ID, OPTEE_FFA_YIELDING_CALL_RESUME 168 * w4-w6: Not used (MBZ) 169 * w7: Resume info 170 * 171 * Normal return (yielding call is completed). Register usage: 172 * w3: Error code, 0 on success 173 * w4: OPTEE_FFA_YIELDING_CALL_RETURN_DONE 174 * w5-w7: Not used (MBZ) 175 * 176 * RPC interrupt return (RPC from secure world). Register usage: 177 * w3: Error code == 0 178 * w4: Any defined RPC code but OPTEE_FFA_YIELDING_CALL_RETURN_DONE 179 * w5-w6: Not used (MBZ) 180 * w7: Resume info 181 * 182 * Possible error codes in register w3: 183 * 0: Success 184 * FFA_DENIED: w4 isn't one of OPTEE_FFA_YIELDING_CALL_START 185 * OPTEE_FFA_YIELDING_CALL_RESUME 186 * 187 * Possible error codes for OPTEE_FFA_YIELDING_CALL_START, 188 * FFA_BUSY: Number of OP-TEE OS threads exceeded, 189 * try again later 190 * FFA_DENIED: RPC shared memory object not found 191 * FFA_INVALID_PARAMETER: Bad shared memory handle or offset into the memory 192 * 193 * Possible error codes for OPTEE_FFA_YIELDING_CALL_RESUME 194 * FFA_INVALID_PARAMETER: Bad resume info 195 */ 196 #define OPTEE_FFA_YIELDING_CALL_WITH_ARG OPTEE_FFA_YIELDING_CALL(0) 197 #define OPTEE_FFA_YIELDING_CALL_RESUME OPTEE_FFA_YIELDING_CALL(1) 198 199 #define OPTEE_FFA_YIELDING_CALL_RETURN_DONE U(0) 200 #define OPTEE_FFA_YIELDING_CALL_RETURN_RPC_CMD U(1) 201 #define OPTEE_FFA_YIELDING_CALL_RETURN_INTERRUPT U(2) 202 203 #endif /*__OPTEE_FFA_H*/ 204