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