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