1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2015-2018, Linaro Limited 4 */ 5 6 #ifndef _OPTEE_MSG_H 7 #define _OPTEE_MSG_H 8 9 #include <linux/bitops.h> 10 #include <linux/types.h> 11 12 /* 13 * This file defines the OP-TEE message protocol used to communicate with 14 * an instance of OP-TEE running in secure world. This file is based on 15 * https://github.com/OP-TEE/optee_os/blob/master/core/include/optee_msg.h 16 * and may need to be updated when introducing new features. 17 * 18 * This file is divided into three sections. 19 * 1. Formatting of messages. 20 * 2. Requests from normal world 21 * 3. Requests from secure world, Remote Procedure Call (RPC), handled by 22 * tee-supplicant. 23 */ 24 25 /***************************************************************************** 26 * Part 1 - formatting of messages 27 *****************************************************************************/ 28 29 #define OPTEE_MSG_ATTR_TYPE_NONE 0x0 30 #define OPTEE_MSG_ATTR_TYPE_VALUE_INPUT 0x1 31 #define OPTEE_MSG_ATTR_TYPE_VALUE_OUTPUT 0x2 32 #define OPTEE_MSG_ATTR_TYPE_VALUE_INOUT 0x3 33 #define OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 0x5 34 #define OPTEE_MSG_ATTR_TYPE_RMEM_OUTPUT 0x6 35 #define OPTEE_MSG_ATTR_TYPE_RMEM_INOUT 0x7 36 #define OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 0x9 37 #define OPTEE_MSG_ATTR_TYPE_TMEM_OUTPUT 0xa 38 #define OPTEE_MSG_ATTR_TYPE_TMEM_INOUT 0xb 39 40 #define OPTEE_MSG_ATTR_TYPE_MASK GENMASK(7, 0) 41 42 /* 43 * Meta parameter to be absorbed by the Secure OS and not passed 44 * to the Trusted Application. 45 * 46 * Currently only used with OPTEE_MSG_CMD_OPEN_SESSION. 47 */ 48 #define OPTEE_MSG_ATTR_META BIT(8) 49 50 /* 51 * Pointer to a list of pages used to register user-defined SHM buffer. 52 * Used with OPTEE_MSG_ATTR_TYPE_TMEM_*. 53 * buf_ptr should point to the beginning of the buffer. Buffer will contain 54 * list of page addresses. OP-TEE core can reconstruct contiguous buffer from 55 * that page addresses list. Page addresses are stored as 64 bit values. 56 * Last entry on a page should point to the next page of buffer. 57 * Every entry in buffer should point to a 4k page beginning (12 least 58 * significant bits must be equal to zero). 59 * 60 * 12 least significant bints of optee_msg_param.u.tmem.buf_ptr should hold page 61 * offset of the user buffer. 62 * 63 * So, entries should be placed like members of this structure: 64 * 65 * struct page_data { 66 * uint64_t pages_array[OPTEE_MSG_NONCONTIG_PAGE_SIZE/sizeof(uint64_t) - 1]; 67 * uint64_t next_page_data; 68 * }; 69 * 70 * Structure is designed to exactly fit into the page size 71 * OPTEE_MSG_NONCONTIG_PAGE_SIZE which is a standard 4KB page. 72 * 73 * The size of 4KB is chosen because this is the smallest page size for ARM 74 * architectures. If REE uses larger pages, it should divide them to 4KB ones. 75 */ 76 #define OPTEE_MSG_ATTR_NONCONTIG BIT(9) 77 78 /* 79 * Memory attributes for caching passed with temp memrefs. The actual value 80 * used is defined outside the message protocol with the exception of 81 * OPTEE_MSG_ATTR_CACHE_PREDEFINED which means the attributes already 82 * defined for the memory range should be used. If optee_smc.h is used as 83 * bearer of this protocol OPTEE_SMC_SHM_* is used for values. 84 */ 85 #define OPTEE_MSG_ATTR_CACHE_SHIFT 16 86 #define OPTEE_MSG_ATTR_CACHE_MASK GENMASK(2, 0) 87 #define OPTEE_MSG_ATTR_CACHE_PREDEFINED 0 88 89 /* 90 * Same values as TEE_LOGIN_* from TEE Internal API 91 */ 92 #define OPTEE_MSG_LOGIN_PUBLIC 0x00000000 93 #define OPTEE_MSG_LOGIN_USER 0x00000001 94 #define OPTEE_MSG_LOGIN_GROUP 0x00000002 95 #define OPTEE_MSG_LOGIN_APPLICATION 0x00000004 96 #define OPTEE_MSG_LOGIN_APPLICATION_USER 0x00000005 97 #define OPTEE_MSG_LOGIN_APPLICATION_GROUP 0x00000006 98 99 /* 100 * Page size used in non-contiguous buffer entries 101 */ 102 #define OPTEE_MSG_NONCONTIG_PAGE_SIZE 4096 103 104 /** 105 * struct optee_msg_param_tmem - temporary memory reference parameter 106 * @buf_ptr: Address of the buffer 107 * @size: Size of the buffer 108 * @shm_ref: Temporary shared memory reference, pointer to a struct tee_shm 109 * 110 * Secure and normal world communicates pointers as physical address 111 * instead of the virtual address. This is because secure and normal world 112 * have completely independent memory mapping. Normal world can even have a 113 * hypervisor which need to translate the guest physical address (AKA IPA 114 * in ARM documentation) to a real physical address before passing the 115 * structure to secure world. 116 */ 117 struct optee_msg_param_tmem { 118 u64 buf_ptr; 119 u64 size; 120 u64 shm_ref; 121 }; 122 123 /** 124 * struct optee_msg_param_rmem - registered memory reference parameter 125 * @offs: Offset into shared memory reference 126 * @size: Size of the buffer 127 * @shm_ref: Shared memory reference, pointer to a struct tee_shm 128 */ 129 struct optee_msg_param_rmem { 130 u64 offs; 131 u64 size; 132 u64 shm_ref; 133 }; 134 135 /** 136 * struct optee_msg_param_value - opaque value parameter 137 * 138 * Value parameters are passed unchecked between normal and secure world. 139 */ 140 struct optee_msg_param_value { 141 u64 a; 142 u64 b; 143 u64 c; 144 }; 145 146 /** 147 * struct optee_msg_param - parameter used together with struct optee_msg_arg 148 * @attr: attributes 149 * @tmem: parameter by temporary memory reference 150 * @rmem: parameter by registered memory reference 151 * @value: parameter by opaque value 152 * 153 * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in 154 * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value, 155 * OPTEE_MSG_ATTR_TYPE_TMEM_* indicates @tmem and 156 * OPTEE_MSG_ATTR_TYPE_RMEM_* indicates @rmem, 157 * OPTEE_MSG_ATTR_TYPE_NONE indicates that none of the members are used. 158 */ 159 struct optee_msg_param { 160 u64 attr; 161 union { 162 struct optee_msg_param_tmem tmem; 163 struct optee_msg_param_rmem rmem; 164 struct optee_msg_param_value value; 165 } u; 166 }; 167 168 /** 169 * struct optee_msg_arg - call argument 170 * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_* 171 * @func: Trusted Application function, specific to the Trusted Application, 172 * used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND 173 * @session: In parameter for all OPTEE_MSG_CMD_* except 174 * OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead 175 * @cancel_id: Cancellation id, a unique value to identify this request 176 * @ret: return value 177 * @ret_origin: origin of the return value 178 * @num_params: number of parameters supplied to the OS Command 179 * @params: the parameters supplied to the OS Command 180 * 181 * All normal calls to Trusted OS uses this struct. If cmd requires further 182 * information than what these field holds it can be passed as a parameter 183 * tagged as meta (setting the OPTEE_MSG_ATTR_META bit in corresponding 184 * attrs field). All parameters tagged as meta has to come first. 185 * 186 * Temp memref parameters can be fragmented if supported by the Trusted OS 187 * (when optee_smc.h is bearer of this protocol this is indicated with 188 * OPTEE_SMC_SEC_CAP_UNREGISTERED_SHM). If a logical memref parameter is 189 * fragmented then has all but the last fragment the 190 * OPTEE_MSG_ATTR_FRAGMENT bit set in attrs. Even if a memref is fragmented 191 * it will still be presented as a single logical memref to the Trusted 192 * Application. 193 */ 194 struct optee_msg_arg { 195 u32 cmd; 196 u32 func; 197 u32 session; 198 u32 cancel_id; 199 u32 pad; 200 u32 ret; 201 u32 ret_origin; 202 u32 num_params; 203 204 /* num_params tells the actual number of element in params */ 205 struct optee_msg_param params[0]; 206 }; 207 208 /** 209 * OPTEE_MSG_GET_ARG_SIZE - return size of struct optee_msg_arg 210 * 211 * @num_params: Number of parameters embedded in the struct optee_msg_arg 212 * 213 * Returns the size of the struct optee_msg_arg together with the number 214 * of embedded parameters. 215 */ 216 #define OPTEE_MSG_GET_ARG_SIZE(num_params) \ 217 (sizeof(struct optee_msg_arg) + \ 218 sizeof(struct optee_msg_param) * (num_params)) 219 220 /***************************************************************************** 221 * Part 2 - requests from normal world 222 *****************************************************************************/ 223 224 /* 225 * Return the following UID if using API specified in this file without 226 * further extensions: 227 * 384fb3e0-e7f8-11e3-af63-0002a5d5c51b. 228 * Represented in 4 32-bit words in OPTEE_MSG_UID_0, OPTEE_MSG_UID_1, 229 * OPTEE_MSG_UID_2, OPTEE_MSG_UID_3. 230 */ 231 #define OPTEE_MSG_UID_0 0x384fb3e0 232 #define OPTEE_MSG_UID_1 0xe7f811e3 233 #define OPTEE_MSG_UID_2 0xaf630002 234 #define OPTEE_MSG_UID_3 0xa5d5c51b 235 #define OPTEE_MSG_FUNCID_CALLS_UID 0xFF01 236 237 /* 238 * Returns 2.0 if using API specified in this file without further 239 * extensions. Represented in 2 32-bit words in OPTEE_MSG_REVISION_MAJOR 240 * and OPTEE_MSG_REVISION_MINOR 241 */ 242 #define OPTEE_MSG_REVISION_MAJOR 2 243 #define OPTEE_MSG_REVISION_MINOR 0 244 #define OPTEE_MSG_FUNCID_CALLS_REVISION 0xFF03 245 246 /* 247 * Get UUID of Trusted OS. 248 * 249 * Used by non-secure world to figure out which Trusted OS is installed. 250 * Note that returned UUID is the UUID of the Trusted OS, not of the API. 251 * 252 * Returns UUID in 4 32-bit words in the same way as 253 * OPTEE_MSG_FUNCID_CALLS_UID described above. 254 */ 255 #define OPTEE_MSG_OS_OPTEE_UUID_0 0x486178e0 256 #define OPTEE_MSG_OS_OPTEE_UUID_1 0xe7f811e3 257 #define OPTEE_MSG_OS_OPTEE_UUID_2 0xbc5e0002 258 #define OPTEE_MSG_OS_OPTEE_UUID_3 0xa5d5c51b 259 #define OPTEE_MSG_FUNCID_GET_OS_UUID 0x0000 260 261 /* 262 * Get revision of Trusted OS. 263 * 264 * Used by non-secure world to figure out which version of the Trusted OS 265 * is installed. Note that the returned revision is the revision of the 266 * Trusted OS, not of the API. 267 * 268 * Returns revision in 2 32-bit words in the same way as 269 * OPTEE_MSG_CALLS_REVISION described above. 270 */ 271 #define OPTEE_MSG_FUNCID_GET_OS_REVISION 0x0001 272 273 /* 274 * Do a secure call with struct optee_msg_arg as argument 275 * The OPTEE_MSG_CMD_* below defines what goes in struct optee_msg_arg::cmd 276 * 277 * OPTEE_MSG_CMD_OPEN_SESSION opens a session to a Trusted Application. 278 * The first two parameters are tagged as meta, holding two value 279 * parameters to pass the following information: 280 * param[0].u.value.a-b uuid of Trusted Application 281 * param[1].u.value.a-b uuid of Client 282 * param[1].u.value.c Login class of client OPTEE_MSG_LOGIN_* 283 * 284 * OPTEE_MSG_CMD_INVOKE_COMMAND invokes a command a previously opened 285 * session to a Trusted Application. struct optee_msg_arg::func is Trusted 286 * Application function, specific to the Trusted Application. 287 * 288 * OPTEE_MSG_CMD_CLOSE_SESSION closes a previously opened session to 289 * Trusted Application. 290 * 291 * OPTEE_MSG_CMD_CANCEL cancels a currently invoked command. 292 * 293 * OPTEE_MSG_CMD_REGISTER_SHM registers a shared memory reference. The 294 * information is passed as: 295 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 296 * [| OPTEE_MSG_ATTR_FRAGMENT] 297 * [in] param[0].u.tmem.buf_ptr physical address (of first fragment) 298 * [in] param[0].u.tmem.size size (of first fragment) 299 * [in] param[0].u.tmem.shm_ref holds shared memory reference 300 * ... 301 * The shared memory can optionally be fragmented, temp memrefs can follow 302 * each other with all but the last with the OPTEE_MSG_ATTR_FRAGMENT bit set. 303 * 304 * OPTEE_MSG_CMD_UNREGISTER_SHM unregisteres a previously registered shared 305 * memory reference. The information is passed as: 306 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 307 * [in] param[0].u.rmem.shm_ref holds shared memory reference 308 * [in] param[0].u.rmem.offs 0 309 * [in] param[0].u.rmem.size 0 310 */ 311 #define OPTEE_MSG_CMD_OPEN_SESSION 0 312 #define OPTEE_MSG_CMD_INVOKE_COMMAND 1 313 #define OPTEE_MSG_CMD_CLOSE_SESSION 2 314 #define OPTEE_MSG_CMD_CANCEL 3 315 #define OPTEE_MSG_CMD_REGISTER_SHM 4 316 #define OPTEE_MSG_CMD_UNREGISTER_SHM 5 317 #define OPTEE_MSG_FUNCID_CALL_WITH_ARG 0x0004 318 319 /***************************************************************************** 320 * Part 3 - Requests from secure world, RPC 321 *****************************************************************************/ 322 323 /* 324 * All RPC is done with a struct optee_msg_arg as bearer of information, 325 * struct optee_msg_arg::arg holds values defined by OPTEE_MSG_RPC_CMD_* below 326 * 327 * RPC communication with tee-supplicant is reversed compared to normal 328 * client communication desribed above. The supplicant receives requests 329 * and sends responses. 330 */ 331 332 /* 333 * Load a TA into memory, defined in tee-supplicant 334 */ 335 #define OPTEE_MSG_RPC_CMD_LOAD_TA 0 336 337 /* 338 * Reserved 339 */ 340 #define OPTEE_MSG_RPC_CMD_RPMB 1 341 342 /* 343 * File system access, defined in tee-supplicant 344 */ 345 #define OPTEE_MSG_RPC_CMD_FS 2 346 347 /* 348 * Get time 349 * 350 * Returns number of seconds and nano seconds since the Epoch, 351 * 1970-01-01 00:00:00 +0000 (UTC). 352 * 353 * [out] param[0].u.value.a Number of seconds 354 * [out] param[0].u.value.b Number of nano seconds. 355 */ 356 #define OPTEE_MSG_RPC_CMD_GET_TIME 3 357 358 /* 359 * Wait queue primitive, helper for secure world to implement a wait queue. 360 * 361 * If secure world need to wait for a secure world mutex it issues a sleep 362 * request instead of spinning in secure world. Conversely is a wakeup 363 * request issued when a secure world mutex with a thread waiting thread is 364 * unlocked. 365 * 366 * Waiting on a key 367 * [in] param[0].u.value.a OPTEE_MSG_RPC_WAIT_QUEUE_SLEEP 368 * [in] param[0].u.value.b wait key 369 * 370 * Waking up a key 371 * [in] param[0].u.value.a OPTEE_MSG_RPC_WAIT_QUEUE_WAKEUP 372 * [in] param[0].u.value.b wakeup key 373 */ 374 #define OPTEE_MSG_RPC_CMD_WAIT_QUEUE 4 375 #define OPTEE_MSG_RPC_WAIT_QUEUE_SLEEP 0 376 #define OPTEE_MSG_RPC_WAIT_QUEUE_WAKEUP 1 377 378 /* 379 * Suspend execution 380 * 381 * [in] param[0].value .a number of milliseconds to suspend 382 */ 383 #define OPTEE_MSG_RPC_CMD_SUSPEND 5 384 385 /* 386 * Allocate a piece of shared memory 387 * 388 * Shared memory can optionally be fragmented, to support that additional 389 * spare param entries are allocated to make room for eventual fragments. 390 * The spare param entries has .attr = OPTEE_MSG_ATTR_TYPE_NONE when 391 * unused. All returned temp memrefs except the last should have the 392 * OPTEE_MSG_ATTR_FRAGMENT bit set in the attr field. 393 * 394 * [in] param[0].u.value.a type of memory one of 395 * OPTEE_MSG_RPC_SHM_TYPE_* below 396 * [in] param[0].u.value.b requested size 397 * [in] param[0].u.value.c required alignment 398 * 399 * [out] param[0].u.tmem.buf_ptr physical address (of first fragment) 400 * [out] param[0].u.tmem.size size (of first fragment) 401 * [out] param[0].u.tmem.shm_ref shared memory reference 402 * ... 403 * [out] param[n].u.tmem.buf_ptr physical address 404 * [out] param[n].u.tmem.size size 405 * [out] param[n].u.tmem.shm_ref shared memory reference (same value 406 * as in param[n-1].u.tmem.shm_ref) 407 */ 408 #define OPTEE_MSG_RPC_CMD_SHM_ALLOC 6 409 /* Memory that can be shared with a non-secure user space application */ 410 #define OPTEE_MSG_RPC_SHM_TYPE_APPL 0 411 /* Memory only shared with non-secure kernel */ 412 #define OPTEE_MSG_RPC_SHM_TYPE_KERNEL 1 413 414 /* 415 * Free shared memory previously allocated with OPTEE_MSG_RPC_CMD_SHM_ALLOC 416 * 417 * [in] param[0].u.value.a type of memory one of 418 * OPTEE_MSG_RPC_SHM_TYPE_* above 419 * [in] param[0].u.value.b value of shared memory reference 420 * returned in param[0].u.tmem.shm_ref 421 * above 422 */ 423 #define OPTEE_MSG_RPC_CMD_SHM_FREE 7 424 425 #endif /* _OPTEE_MSG_H */ 426