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