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