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