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