1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2015-2017, Linaro Limited 4 */ 5 #ifndef _OPTEE_MSG_H 6 #define _OPTEE_MSG_H 7 8 #include <xen/bitops.h> 9 #include <xen/types.h> 10 11 /* 12 * This file defines the OP-TEE message protocol used to communicate 13 * with an instance of OP-TEE running in secure world. 14 */ 15 16 /***************************************************************************** 17 * Part 1 - formatting of messages 18 *****************************************************************************/ 19 20 #define OPTEE_MSG_ATTR_TYPE_NONE 0x0 21 #define OPTEE_MSG_ATTR_TYPE_VALUE_INPUT 0x1 22 #define OPTEE_MSG_ATTR_TYPE_VALUE_OUTPUT 0x2 23 #define OPTEE_MSG_ATTR_TYPE_VALUE_INOUT 0x3 24 #define OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 0x5 25 #define OPTEE_MSG_ATTR_TYPE_RMEM_OUTPUT 0x6 26 #define OPTEE_MSG_ATTR_TYPE_RMEM_INOUT 0x7 27 #define OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 0x9 28 #define OPTEE_MSG_ATTR_TYPE_TMEM_OUTPUT 0xa 29 #define OPTEE_MSG_ATTR_TYPE_TMEM_INOUT 0xb 30 31 #define OPTEE_MSG_ATTR_TYPE_MASK GENMASK(7, 0) 32 33 /* 34 * Meta parameter to be absorbed by the Secure OS and not passed 35 * to the Trusted Application. 36 * 37 * Currently only used with OPTEE_MSG_CMD_OPEN_SESSION. 38 */ 39 #define OPTEE_MSG_ATTR_META BIT(8, UL) 40 41 /* 42 * Pointer to a list of pages used to register user-defined SHM buffer. 43 * Used with OPTEE_MSG_ATTR_TYPE_TMEM_*. 44 * buf_ptr should point to the beginning of the buffer. Buffer will contain 45 * list of page addresses. OP-TEE core can reconstruct contiguous buffer from 46 * that page addresses list. Page addresses are stored as 64 bit values. 47 * Last entry on a page should point to the next page of buffer. 48 * Every entry in buffer should point to a 4k page beginning (12 least 49 * significant bits must be equal to zero). 50 * 51 * 12 least significant of optee_msg_param.u.tmem.buf_ptr should hold page 52 * offset of user buffer. 53 * 54 * So, entries should be placed like members of this structure: 55 * 56 * struct page_data { 57 * uint64_t pages_array[OPTEE_MSG_NONCONTIG_PAGE_SIZE/sizeof(uint64_t) - 1]; 58 * uint64_t next_page_data; 59 * }; 60 * 61 * Structure is designed to exactly fit into the page size 62 * OPTEE_MSG_NONCONTIG_PAGE_SIZE which is a standard 4KB page. 63 * 64 * The size of 4KB is chosen because this is the smallest page size for ARM 65 * architectures. If REE uses larger pages, it should divide them to 4KB ones. 66 */ 67 #define OPTEE_MSG_ATTR_NONCONTIG BIT(9, UL) 68 69 /* 70 * Memory attributes for caching passed with temp memrefs. The actual value 71 * used is defined outside the message protocol with the exception of 72 * OPTEE_MSG_ATTR_CACHE_PREDEFINED which means the attributes already 73 * defined for the memory range should be used. If optee_smc.h is used as 74 * bearer of this protocol OPTEE_SMC_SHM_* is used for values. 75 */ 76 #define OPTEE_MSG_ATTR_CACHE_SHIFT 16 77 #define OPTEE_MSG_ATTR_CACHE_MASK GENMASK(2, 0) 78 #define OPTEE_MSG_ATTR_CACHE_PREDEFINED 0 79 80 /* 81 * Same values as TEE_LOGIN_* from TEE Internal API 82 */ 83 #define OPTEE_MSG_LOGIN_PUBLIC 0x00000000 84 #define OPTEE_MSG_LOGIN_USER 0x00000001 85 #define OPTEE_MSG_LOGIN_GROUP 0x00000002 86 #define OPTEE_MSG_LOGIN_APPLICATION 0x00000004 87 #define OPTEE_MSG_LOGIN_APPLICATION_USER 0x00000005 88 #define OPTEE_MSG_LOGIN_APPLICATION_GROUP 0x00000006 89 90 /* 91 * Page size used in non-contiguous buffer entries 92 */ 93 #define OPTEE_MSG_NONCONTIG_PAGE_SIZE 4096 94 95 #ifndef ASM 96 /** 97 * struct optee_msg_param_tmem - temporary memory reference parameter 98 * @buf_ptr: Address of the buffer 99 * @size: Size of the buffer 100 * @shm_ref: Temporary shared memory reference, pointer to a struct tee_shm 101 * 102 * Secure and normal world communicates pointers as physical address 103 * instead of the virtual address. This is because secure and normal world 104 * have completely independent memory mapping. Normal world can even have a 105 * hypervisor which need to translate the guest physical address (AKA IPA 106 * in ARM documentation) to a real physical address before passing the 107 * structure to secure world. 108 */ 109 struct optee_msg_param_tmem { 110 uint64_t buf_ptr; 111 uint64_t size; 112 uint64_t shm_ref; 113 }; 114 115 /** 116 * struct optee_msg_param_rmem - registered memory reference parameter 117 * @offs: Offset into shared memory reference 118 * @size: Size of the buffer 119 * @shm_ref: Shared memory reference, pointer to a struct tee_shm 120 */ 121 struct optee_msg_param_rmem { 122 uint64_t offs; 123 uint64_t size; 124 uint64_t shm_ref; 125 }; 126 127 /** 128 * struct optee_msg_param_value - values 129 * @a: first value 130 * @b: second value 131 * @c: third value 132 */ 133 struct optee_msg_param_value { 134 uint64_t a; 135 uint64_t b; 136 uint64_t c; 137 }; 138 139 /** 140 * struct optee_msg_param - parameter 141 * @attr: attributes 142 * @memref: a memory reference 143 * @value: a value 144 * 145 * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in 146 * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value, 147 * OPTEE_MSG_ATTR_TYPE_TMEM_* indicates tmem and 148 * OPTEE_MSG_ATTR_TYPE_RMEM_* indicates rmem. 149 * OPTEE_MSG_ATTR_TYPE_NONE indicates that none of the members are used. 150 */ 151 struct optee_msg_param { 152 uint64_t attr; 153 union { 154 struct optee_msg_param_tmem tmem; 155 struct optee_msg_param_rmem rmem; 156 struct optee_msg_param_value value; 157 } u; 158 }; 159 160 /** 161 * struct optee_msg_arg - call argument 162 * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_* 163 * @func: Trusted Application function, specific to the Trusted Application, 164 * used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND 165 * @session: In parameter for all OPTEE_MSG_CMD_* except 166 * OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead 167 * @cancel_id: Cancellation id, a unique value to identify this request 168 * @ret: return value 169 * @ret_origin: origin of the return value 170 * @num_params: number of parameters supplied to the OS Command 171 * @params: the parameters supplied to the OS Command 172 * 173 * All normal calls to Trusted OS uses this struct. If cmd requires further 174 * information than what these fields hold it can be passed as a parameter 175 * tagged as meta (setting the OPTEE_MSG_ATTR_META bit in corresponding 176 * attrs field). All parameters tagged as meta have to come first. 177 */ 178 struct optee_msg_arg { 179 uint32_t cmd; 180 uint32_t func; 181 uint32_t session; 182 uint32_t cancel_id; 183 uint32_t pad; 184 uint32_t ret; 185 uint32_t ret_origin; 186 uint32_t num_params; 187 188 /* num_params tells the actual number of element in params */ 189 struct optee_msg_param params[]; 190 }; 191 192 /** 193 * OPTEE_MSG_GET_ARG_SIZE - return size of struct optee_msg_arg 194 * 195 * @num_params: Number of parameters embedded in the struct optee_msg_arg 196 * 197 * Returns the size of the struct optee_msg_arg together with the number 198 * of embedded parameters. 199 */ 200 #define OPTEE_MSG_GET_ARG_SIZE(num_params) \ 201 (sizeof(struct optee_msg_arg) + \ 202 sizeof(struct optee_msg_param) * (num_params)) 203 204 /* 205 * Defines the maximum value of @num_params that can be passed to 206 * OPTEE_MSG_GET_ARG_SIZE without a risk of crossing page boundary. 207 */ 208 #define OPTEE_MSG_MAX_NUM_PARAMS \ 209 ((OPTEE_MSG_NONCONTIG_PAGE_SIZE - sizeof(struct optee_msg_arg)) / \ 210 sizeof(struct optee_msg_param)) 211 212 #endif /*ASM*/ 213 214 /***************************************************************************** 215 * Part 2 - requests from normal world 216 *****************************************************************************/ 217 218 /* 219 * Return the following UID if using API specified in this file without 220 * further extensions: 221 * 384fb3e0-e7f8-11e3-af63-0002a5d5c51b. 222 * Represented in 4 32-bit words in OPTEE_MSG_UID_0, OPTEE_MSG_UID_1, 223 * OPTEE_MSG_UID_2, OPTEE_MSG_UID_3. 224 */ 225 #define OPTEE_MSG_UID_0 0x384fb3e0 226 #define OPTEE_MSG_UID_1 0xe7f811e3 227 #define OPTEE_MSG_UID_2 0xaf630002 228 #define OPTEE_MSG_UID_3 0xa5d5c51b 229 #define OPTEE_MSG_FUNCID_CALLS_UID 0xFF01 230 231 /* 232 * Returns 2.0 if using API specified in this file without further 233 * extensions. Represented in 2 32-bit words in OPTEE_MSG_REVISION_MAJOR 234 * and OPTEE_MSG_REVISION_MINOR 235 */ 236 #define OPTEE_MSG_REVISION_MAJOR 2 237 #define OPTEE_MSG_REVISION_MINOR 0 238 #define OPTEE_MSG_FUNCID_CALLS_REVISION 0xFF03 239 240 /* 241 * Get UUID of Trusted OS. 242 * 243 * Used by non-secure world to figure out which Trusted OS is installed. 244 * Note that returned UUID is the UUID of the Trusted OS, not of the API. 245 * 246 * Returns UUID in 4 32-bit words in the same way as 247 * OPTEE_MSG_FUNCID_CALLS_UID described above. 248 */ 249 #define OPTEE_MSG_OS_OPTEE_UUID_0 0x486178e0 250 #define OPTEE_MSG_OS_OPTEE_UUID_1 0xe7f811e3 251 #define OPTEE_MSG_OS_OPTEE_UUID_2 0xbc5e0002 252 #define OPTEE_MSG_OS_OPTEE_UUID_3 0xa5d5c51b 253 #define OPTEE_MSG_FUNCID_GET_OS_UUID 0x0000 254 255 /* 256 * Get revision of Trusted OS. 257 * 258 * Used by non-secure world to figure out which version of the Trusted OS 259 * is installed. Note that the returned revision is the revision of the 260 * Trusted OS, not of the API. 261 * 262 * Returns revision in 2 32-bit words in the same way as 263 * OPTEE_MSG_CALLS_REVISION described above. 264 */ 265 #define OPTEE_MSG_FUNCID_GET_OS_REVISION 0x0001 266 267 /* 268 * Do a secure call with struct optee_msg_arg as argument 269 * The OPTEE_MSG_CMD_* below defines what goes in struct optee_msg_arg::cmd 270 * 271 * OPTEE_MSG_CMD_OPEN_SESSION opens a session to a Trusted Application. 272 * The first two parameters are tagged as meta, holding two value 273 * parameters to pass the following information: 274 * param[0].u.value.a-b uuid of Trusted Application 275 * param[1].u.value.a-b uuid of Client 276 * param[1].u.value.c Login class of client OPTEE_MSG_LOGIN_* 277 * 278 * OPTEE_MSG_CMD_INVOKE_COMMAND invokes a command a previously opened 279 * session to a Trusted Application. struct optee_msg_arg::func is Trusted 280 * Application function, specific to the Trusted Application. 281 * 282 * OPTEE_MSG_CMD_CLOSE_SESSION closes a previously opened session to 283 * Trusted Application. 284 * 285 * OPTEE_MSG_CMD_CANCEL cancels a currently invoked command. 286 * 287 * OPTEE_MSG_CMD_REGISTER_SHM registers a shared memory reference. The 288 * information is passed as: 289 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 290 * [| OPTEE_MSG_ATTR_NONCONTIG] 291 * [in] param[0].u.tmem.buf_ptr physical address (of first fragment) 292 * [in] param[0].u.tmem.size size (of first fragment) 293 * [in] param[0].u.tmem.shm_ref holds shared memory reference 294 * 295 * OPTEE_MSG_CMD_UNREGISTER_SHM unregisteres a previously registered shared 296 * memory reference. The information is passed as: 297 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 298 * [in] param[0].u.rmem.shm_ref holds shared memory reference 299 * [in] param[0].u.rmem.offs 0 300 * [in] param[0].u.rmem.size 0 301 */ 302 #define OPTEE_MSG_CMD_OPEN_SESSION 0 303 #define OPTEE_MSG_CMD_INVOKE_COMMAND 1 304 #define OPTEE_MSG_CMD_CLOSE_SESSION 2 305 #define OPTEE_MSG_CMD_CANCEL 3 306 #define OPTEE_MSG_CMD_REGISTER_SHM 4 307 #define OPTEE_MSG_CMD_UNREGISTER_SHM 5 308 #define OPTEE_MSG_FUNCID_CALL_WITH_ARG 0x0004 309 310 #endif /* _OPTEE_MSG_H */ 311