1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2015-2017, Linaro Limited 4 */ 5 #ifndef _OPTEE_MSG_H 6 #define _OPTEE_MSG_H 7 8 #include <compiler.h> 9 #include <types_ext.h> 10 #include <util.h> 11 12 /* 13 * This file defines the OP-TEE message protocol used to communicate 14 * with an instance of OP-TEE running in secure world. 15 */ 16 17 /***************************************************************************** 18 * Part 1 - formatting of messages 19 *****************************************************************************/ 20 21 #define OPTEE_MSG_ATTR_TYPE_NONE 0x0 22 #define OPTEE_MSG_ATTR_TYPE_VALUE_INPUT 0x1 23 #define OPTEE_MSG_ATTR_TYPE_VALUE_OUTPUT 0x2 24 #define OPTEE_MSG_ATTR_TYPE_VALUE_INOUT 0x3 25 #define OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 0x5 26 #define OPTEE_MSG_ATTR_TYPE_RMEM_OUTPUT 0x6 27 #define OPTEE_MSG_ATTR_TYPE_RMEM_INOUT 0x7 28 #define OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 0x9 29 #define OPTEE_MSG_ATTR_TYPE_TMEM_OUTPUT 0xa 30 #define OPTEE_MSG_ATTR_TYPE_TMEM_INOUT 0xb 31 32 #define OPTEE_MSG_ATTR_TYPE_MASK GENMASK_32(7, 0) 33 34 /* 35 * Meta parameter to be absorbed by the Secure OS and not passed 36 * to the Trusted Application. 37 * 38 * Currently only used with OPTEE_MSG_CMD_OPEN_SESSION. 39 */ 40 #define OPTEE_MSG_ATTR_META BIT(8) 41 42 /* 43 * Pointer to a list of pages used to register user-defined SHM buffer. 44 * Used with OPTEE_MSG_ATTR_TYPE_TMEM_*. 45 * buf_ptr should point to the beginning of the buffer. Buffer will contain 46 * list of page addresses. OP-TEE core can reconstruct contiguous buffer from 47 * that page addresses list. Page addresses are stored as 64 bit values. 48 * Last entry on a page should point to the next page of buffer. 49 * Every entry in buffer should point to a 4k page beginning (12 least 50 * significant bits must be equal to zero). 51 * 52 * 12 least significant of optee_msg_param.u.tmem.buf_ptr should hold page 53 * offset of user buffer. 54 * 55 * So, entries should be placed like members of this structure: 56 * 57 * struct page_data { 58 * uint64_t pages_array[OPTEE_MSG_NONCONTIG_PAGE_SIZE/sizeof(uint64_t) - 1]; 59 * uint64_t next_page_data; 60 * }; 61 * 62 * Structure is designed to exactly fit into the page size 63 * OPTEE_MSG_NONCONTIG_PAGE_SIZE which is a standard 4KB page. 64 * 65 * The size of 4KB is chosen because this is the smallest page size for ARM 66 * architectures. If REE uses larger pages, it should divide them to 4KB ones. 67 */ 68 #define OPTEE_MSG_ATTR_NONCONTIG BIT(9) 69 70 /* 71 * Memory attributes for caching passed with temp memrefs. The actual value 72 * used is defined outside the message protocol with the exception of 73 * OPTEE_MSG_ATTR_CACHE_PREDEFINED which means the attributes already 74 * defined for the memory range should be used. If optee_smc.h is used as 75 * bearer of this protocol OPTEE_SMC_SHM_* is used for values. 76 */ 77 #define OPTEE_MSG_ATTR_CACHE_SHIFT 16 78 #define OPTEE_MSG_ATTR_CACHE_MASK GENMASK_32(2, 0) 79 #define OPTEE_MSG_ATTR_CACHE_PREDEFINED 0 80 81 /* 82 * Same values as TEE_LOGIN_* from TEE Internal API 83 */ 84 #define OPTEE_MSG_LOGIN_PUBLIC 0x00000000 85 #define OPTEE_MSG_LOGIN_USER 0x00000001 86 #define OPTEE_MSG_LOGIN_GROUP 0x00000002 87 #define OPTEE_MSG_LOGIN_APPLICATION 0x00000004 88 #define OPTEE_MSG_LOGIN_APPLICATION_USER 0x00000005 89 #define OPTEE_MSG_LOGIN_APPLICATION_GROUP 0x00000006 90 91 /* 92 * Page size used in non-contiguous buffer entries 93 */ 94 #define OPTEE_MSG_NONCONTIG_PAGE_SIZE 4096 95 96 #ifndef ASM 97 /** 98 * struct optee_msg_param_tmem - temporary memory reference parameter 99 * @buf_ptr: Address of the buffer 100 * @size: Size of the buffer 101 * @shm_ref: Temporary shared memory reference, pointer to a struct tee_shm 102 * 103 * Secure and normal world communicates pointers as physical address 104 * instead of the virtual address. This is because secure and normal world 105 * have completely independent memory mapping. Normal world can even have a 106 * hypervisor which need to translate the guest physical address (AKA IPA 107 * in ARM documentation) to a real physical address before passing the 108 * structure to secure world. 109 */ 110 struct optee_msg_param_tmem { 111 uint64_t buf_ptr; 112 uint64_t size; 113 uint64_t shm_ref; 114 }; 115 116 /** 117 * struct optee_msg_param_rmem - registered memory reference parameter 118 * @offs: Offset into shared memory reference 119 * @size: Size of the buffer 120 * @shm_ref: Shared memory reference, pointer to a struct tee_shm 121 */ 122 struct optee_msg_param_rmem { 123 uint64_t offs; 124 uint64_t size; 125 uint64_t shm_ref; 126 }; 127 128 /** 129 * struct optee_msg_param_value - values 130 * @a: first value 131 * @b: second value 132 * @c: third value 133 */ 134 struct optee_msg_param_value { 135 uint64_t a; 136 uint64_t b; 137 uint64_t c; 138 }; 139 140 /** 141 * struct optee_msg_param - parameter 142 * @attr: attributes 143 * @memref: a memory reference 144 * @value: a value 145 * 146 * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in 147 * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value, 148 * OPTEE_MSG_ATTR_TYPE_TMEM_* indicates tmem and 149 * OPTEE_MSG_ATTR_TYPE_RMEM_* indicates rmem. 150 * OPTEE_MSG_ATTR_TYPE_NONE indicates that none of the members are used. 151 */ 152 struct optee_msg_param { 153 uint64_t attr; 154 union { 155 struct optee_msg_param_tmem tmem; 156 struct optee_msg_param_rmem rmem; 157 struct optee_msg_param_value value; 158 } u; 159 }; 160 161 /** 162 * struct optee_msg_arg - call argument 163 * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_* 164 * @func: Trusted Application function, specific to the Trusted Application, 165 * used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND 166 * @session: In parameter for all OPTEE_MSG_CMD_* except 167 * OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead 168 * @cancel_id: Cancellation id, a unique value to identify this request 169 * @ret: return value 170 * @ret_origin: origin of the return value 171 * @num_params: number of parameters supplied to the OS Command 172 * @params: the parameters supplied to the OS Command 173 * 174 * All normal calls to Trusted OS uses this struct. If cmd requires further 175 * information than what these fields hold it can be passed as a parameter 176 * tagged as meta (setting the OPTEE_MSG_ATTR_META bit in corresponding 177 * attrs field). All parameters tagged as meta have to come first. 178 */ 179 struct optee_msg_arg { 180 uint32_t cmd; 181 uint32_t func; 182 uint32_t session; 183 uint32_t cancel_id; 184 uint32_t pad; 185 uint32_t ret; 186 uint32_t ret_origin; 187 uint32_t num_params; 188 189 /* num_params tells the actual number of element in params */ 190 struct optee_msg_param params[]; 191 }; 192 193 /** 194 * OPTEE_MSG_GET_ARG_SIZE - return size of struct optee_msg_arg 195 * 196 * @num_params: Number of parameters embedded in the struct optee_msg_arg 197 * 198 * Returns the size of the struct optee_msg_arg together with the number 199 * of embedded parameters. 200 */ 201 #define OPTEE_MSG_GET_ARG_SIZE(num_params) \ 202 (sizeof(struct optee_msg_arg) + \ 203 sizeof(struct optee_msg_param) * (num_params)) 204 #endif /*ASM*/ 205 206 /***************************************************************************** 207 * Part 2 - requests from normal world 208 *****************************************************************************/ 209 210 /* 211 * Return the following UID if using API specified in this file without 212 * further extensions: 213 * 384fb3e0-e7f8-11e3-af63-0002a5d5c51b. 214 * Represented in 4 32-bit words in OPTEE_MSG_UID_0, OPTEE_MSG_UID_1, 215 * OPTEE_MSG_UID_2, OPTEE_MSG_UID_3. 216 */ 217 #define OPTEE_MSG_UID_0 0x384fb3e0 218 #define OPTEE_MSG_UID_1 0xe7f811e3 219 #define OPTEE_MSG_UID_2 0xaf630002 220 #define OPTEE_MSG_UID_3 0xa5d5c51b 221 #define OPTEE_MSG_FUNCID_CALLS_UID 0xFF01 222 223 /* 224 * Returns 2.0 if using API specified in this file without further 225 * extensions. Represented in 2 32-bit words in OPTEE_MSG_REVISION_MAJOR 226 * and OPTEE_MSG_REVISION_MINOR 227 */ 228 #define OPTEE_MSG_REVISION_MAJOR 2 229 #define OPTEE_MSG_REVISION_MINOR 0 230 #define OPTEE_MSG_FUNCID_CALLS_REVISION 0xFF03 231 232 /* 233 * Get UUID of Trusted OS. 234 * 235 * Used by non-secure world to figure out which Trusted OS is installed. 236 * Note that returned UUID is the UUID of the Trusted OS, not of the API. 237 * 238 * Returns UUID in 4 32-bit words in the same way as 239 * OPTEE_MSG_FUNCID_CALLS_UID described above. 240 */ 241 #define OPTEE_MSG_OS_OPTEE_UUID_0 0x486178e0 242 #define OPTEE_MSG_OS_OPTEE_UUID_1 0xe7f811e3 243 #define OPTEE_MSG_OS_OPTEE_UUID_2 0xbc5e0002 244 #define OPTEE_MSG_OS_OPTEE_UUID_3 0xa5d5c51b 245 #define OPTEE_MSG_FUNCID_GET_OS_UUID 0x0000 246 247 /* 248 * Get revision of Trusted OS. 249 * 250 * Used by non-secure world to figure out which version of the Trusted OS 251 * is installed. Note that the returned revision is the revision of the 252 * Trusted OS, not of the API. 253 * 254 * Returns revision in 2 32-bit words in the same way as 255 * OPTEE_MSG_CALLS_REVISION described above. 256 */ 257 #define OPTEE_MSG_FUNCID_GET_OS_REVISION 0x0001 258 259 /* 260 * Do a secure call with struct optee_msg_arg as argument 261 * The OPTEE_MSG_CMD_* below defines what goes in struct optee_msg_arg::cmd 262 * 263 * OPTEE_MSG_CMD_OPEN_SESSION opens a session to a Trusted Application. 264 * The first two parameters are tagged as meta, holding two value 265 * parameters to pass the following information: 266 * param[0].u.value.a-b uuid of Trusted Application 267 * param[1].u.value.a-b uuid of Client 268 * param[1].u.value.c Login class of client OPTEE_MSG_LOGIN_* 269 * 270 * OPTEE_MSG_CMD_INVOKE_COMMAND invokes a command a previously opened 271 * session to a Trusted Application. struct optee_msg_arg::func is Trusted 272 * Application function, specific to the Trusted Application. 273 * 274 * OPTEE_MSG_CMD_CLOSE_SESSION closes a previously opened session to 275 * Trusted Application. 276 * 277 * OPTEE_MSG_CMD_CANCEL cancels a currently invoked command. 278 * 279 * OPTEE_MSG_CMD_REGISTER_SHM registers a shared memory reference. The 280 * information is passed as: 281 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 282 * [| OPTEE_MSG_ATTR_NONCONTIG] 283 * [in] param[0].u.tmem.buf_ptr physical address (of first fragment) 284 * [in] param[0].u.tmem.size size (of first fragment) 285 * [in] param[0].u.tmem.shm_ref holds shared memory reference 286 * 287 * OPTEE_MSG_CMD_UNREGISTER_SHM unregisteres a previously registered shared 288 * memory reference. The information is passed as: 289 * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 290 * [in] param[0].u.rmem.shm_ref holds shared memory reference 291 * [in] param[0].u.rmem.offs 0 292 * [in] param[0].u.rmem.size 0 293 */ 294 #define OPTEE_MSG_CMD_OPEN_SESSION 0 295 #define OPTEE_MSG_CMD_INVOKE_COMMAND 1 296 #define OPTEE_MSG_CMD_CLOSE_SESSION 2 297 #define OPTEE_MSG_CMD_CANCEL 3 298 #define OPTEE_MSG_CMD_REGISTER_SHM 4 299 #define OPTEE_MSG_CMD_UNREGISTER_SHM 5 300 #define OPTEE_MSG_FUNCID_CALL_WITH_ARG 0x0004 301 302 #endif /* _OPTEE_MSG_H */ 303