1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Copyright (c) 2018 Linaro Limited 4 */ 5 6 #ifndef __TEE_H 7 #define __TEE_H 8 9 #define TEE_UUID_LEN 16 10 11 #define TEE_GEN_CAP_GP BIT(0) /* GlobalPlatform compliant TEE */ 12 #define TEE_GEN_CAP_REG_MEM BIT(1) /* Supports registering shared memory */ 13 14 #define TEE_SHM_REGISTER BIT(0) /* In list of shared memory */ 15 #define TEE_SHM_SEC_REGISTER BIT(1) /* TEE notified of this memory */ 16 #define TEE_SHM_ALLOC BIT(2) /* The memory is malloced() and must */ 17 /* be freed() */ 18 19 #define TEE_PARAM_ATTR_TYPE_NONE 0 /* parameter not used */ 20 #define TEE_PARAM_ATTR_TYPE_VALUE_INPUT 1 21 #define TEE_PARAM_ATTR_TYPE_VALUE_OUTPUT 2 22 #define TEE_PARAM_ATTR_TYPE_VALUE_INOUT 3 /* input and output */ 23 #define TEE_PARAM_ATTR_TYPE_MEMREF_INPUT 5 24 #define TEE_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6 25 #define TEE_PARAM_ATTR_TYPE_MEMREF_INOUT 7 /* input and output */ 26 #define TEE_PARAM_ATTR_TYPE_MASK 0xff 27 #define TEE_PARAM_ATTR_META 0x100 28 #define TEE_PARAM_ATTR_MASK (TEE_PARAM_ATTR_TYPE_MASK | \ 29 TEE_PARAM_ATTR_META) 30 31 /* 32 * Some Global Platform error codes which has a meaning if the 33 * TEE_GEN_CAP_GP bit is returned by the driver in 34 * struct tee_version_data::gen_caps 35 */ 36 #define TEE_SUCCESS 0x00000000 37 #define TEE_ERROR_GENERIC 0xffff0000 38 #define TEE_ERROR_BAD_PARAMETERS 0xffff0006 39 #define TEE_ERROR_ITEM_NOT_FOUND 0xffff0008 40 #define TEE_ERROR_NOT_IMPLEMENTED 0xffff0009 41 #define TEE_ERROR_NOT_SUPPORTED 0xffff000a 42 #define TEE_ERROR_COMMUNICATION 0xffff000e 43 #define TEE_ERROR_SECURITY 0xffff000f 44 #define TEE_ERROR_OUT_OF_MEMORY 0xffff000c 45 #define TEE_ERROR_TARGET_DEAD 0xffff3024 46 47 #define TEE_ORIGIN_COMMS 0x00000002 48 #define TEE_ORIGIN_TEE 0x00000003 49 #define TEE_ORIGIN_TRUSTED_APP 0x00000004 50 51 struct udevice; 52 53 /** 54 * struct tee_optee_ta_uuid - OP-TEE Trusted Application (TA) UUID format 55 * 56 * Used to identify an OP-TEE TA and define suitable to initialize structs 57 * of this format is distributed with the interface of the TA. The 58 * individual fields of this struct doesn't have any special meaning in 59 * OP-TEE. See RFC4122 for details on the format. 60 */ 61 struct tee_optee_ta_uuid { 62 u32 time_low; 63 u16 time_mid; 64 u16 time_hi_and_version; 65 u8 clock_seq_and_node[8]; 66 }; 67 68 /** 69 * struct tee_shm - memory shared with the TEE 70 * @dev: The TEE device 71 * @link: List node in the list in struct struct tee_uclass_priv 72 * @addr: Pointer to the shared memory 73 * @size: Size of the the shared memory 74 * @flags: TEE_SHM_* above 75 */ 76 struct tee_shm { 77 struct udevice *dev; 78 struct list_head link; 79 void *addr; 80 ulong size; 81 u32 flags; 82 }; 83 84 /** 85 * struct tee_param_memref - memory reference for a Trusted Application 86 * @shm_offs: Offset in bytes into the shared memory object @shm 87 * @size: Size in bytes of the memory reference 88 * @shm: Pointer to a shared memory object for the buffer 89 * 90 * Used as a part of struct tee_param, see that for more information. 91 */ 92 struct tee_param_memref { 93 ulong shm_offs; 94 ulong size; 95 struct tee_shm *shm; 96 }; 97 98 /** 99 * struct tee_param_value - value parameter for a Trusted Application 100 * @a, @b, @c: Parameters passed by value 101 * 102 * Used as a part of struct tee_param, see that for more information. 103 */ 104 struct tee_param_value { 105 u64 a; 106 u64 b; 107 u64 c; 108 }; 109 110 /** 111 * struct tee_param - invoke parameter for a Trusted Application 112 * @attr: Attributes 113 * @u.memref: Memref parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of 114 * TEE_PARAM_ATTR_TYPE_MEMREF_* above 115 * @u.value: Value parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of 116 * TEE_PARAM_ATTR_TYPE_VALUE_* above 117 * 118 * Parameters to TA are passed using an array of this struct, for 119 * flexibility both value parameters and memory refereces can be used. 120 */ 121 struct tee_param { 122 u64 attr; 123 union { 124 struct tee_param_memref memref; 125 struct tee_param_value value; 126 } u; 127 }; 128 129 /** 130 * struct tee_open_session_arg - extra arguments for tee_open_session() 131 * @uuid: [in] UUID of the Trusted Application 132 * @clnt_uuid: [in] Normally zeroes 133 * @clnt_login: [in] Normally 0 134 * @session: [out] Session id 135 * @ret: [out] return value 136 * @ret_origin: [out] origin of the return value 137 */ 138 struct tee_open_session_arg { 139 u8 uuid[TEE_UUID_LEN]; 140 u8 clnt_uuid[TEE_UUID_LEN]; 141 u32 clnt_login; 142 u32 session; 143 u32 ret; 144 u32 ret_origin; 145 }; 146 147 /** 148 * struct tee_invoke_arg - extra arguments for tee_invoke_func() 149 * @func: [in] Trusted Application function, specific to the TA 150 * @session: [in] Session id, from open session 151 * @ret: [out] return value 152 * @ret_origin: [out] origin of the return value 153 */ 154 struct tee_invoke_arg { 155 u32 func; 156 u32 session; 157 u32 ret; 158 u32 ret_origin; 159 }; 160 161 /** 162 * struct tee_version_data - description of TEE 163 * @gen_caps: Generic capabilities, TEE_GEN_CAP_* above 164 */ 165 struct tee_version_data { 166 u32 gen_caps; 167 }; 168 169 /** 170 * struct tee_driver_ops - TEE driver operations 171 * @get_version: Query capabilities of TEE device, 172 * @open_session: Opens a session to a Trusted Application in the TEE, 173 * @close_session: Closes a session to Trusted Application, 174 * @invoke_func: Invokes a function in a Trusted Application, 175 * @shm_register: Registers memory shared with the TEE 176 * @shm_unregister: Unregisters memory shared with the TEE 177 */ 178 struct tee_driver_ops { 179 /** 180 * get_version() - Query capabilities of TEE device 181 * @dev: The TEE device 182 * @vers: Pointer to version data 183 */ 184 void (*get_version)(struct udevice *dev, struct tee_version_data *vers); 185 /** 186 * open_session() - Open a session to a Trusted Application 187 * @dev: The TEE device 188 * @arg: Open session arguments 189 * @num_param: Number of elements in @param 190 * @param: Parameters for Trusted Application 191 * 192 * Returns < 0 on error else see @arg->ret for result. If @arg->ret is 193 * TEE_SUCCESS the session identifier is available in @arg->session. 194 */ 195 int (*open_session)(struct udevice *dev, 196 struct tee_open_session_arg *arg, uint num_param, 197 struct tee_param *param); 198 /** 199 * close_session() - Close a session to a Trusted Application 200 * @dev: The TEE device 201 * @session: Session id 202 * 203 * Return < 0 on error else 0, regardless the session will not be valid 204 * after this function has returned. 205 */ 206 int (*close_session)(struct udevice *dev, u32 session); 207 /** 208 * tee_invoke_func() - Invoke a function in a Trusted Application 209 * @dev: The TEE device 210 * @arg: Invoke arguments 211 * @num_param: Number of elements in @param 212 * @param: Parameters for Trusted Application 213 * 214 * Returns < 0 on error else see @arg->ret for result. 215 */ 216 int (*invoke_func)(struct udevice *dev, struct tee_invoke_arg *arg, 217 uint num_param, struct tee_param *param); 218 /** 219 * shm_register() - Registers memory shared with the TEE 220 * @dev: The TEE device 221 * @shm: Pointer to a shared memory object 222 * Returns 0 on success or < 0 on failure. 223 */ 224 int (*shm_register)(struct udevice *dev, struct tee_shm *shm); 225 /** 226 * shm_unregister() - Unregisters memory shared with the TEE 227 * @dev: The TEE device 228 * @shm: Pointer to a shared memory object 229 * Returns 0 on success or < 0 on failure. 230 */ 231 int (*shm_unregister)(struct udevice *dev, struct tee_shm *shm); 232 }; 233 234 /** 235 * __tee_shm_add() - Internal helper function to register shared memory 236 * @dev: The TEE device 237 * @align: Required alignment of allocated memory block if 238 * (@flags & TEE_SHM_ALLOC) 239 * @addr: Address of memory block, ignored if (@flags & TEE_SHM_ALLOC) 240 * @size: Size of memory block 241 * @flags: TEE_SHM_* above 242 * @shmp: If the function return 0, this holds the allocated 243 * struct tee_shm 244 * 245 * returns 0 on success or < 0 on failure. 246 */ 247 int __tee_shm_add(struct udevice *dev, ulong align, void *addr, ulong size, 248 u32 flags, struct tee_shm **shmp); 249 250 /** 251 * tee_shm_alloc() - Allocate shared memory 252 * @dev: The TEE device 253 * @size: Size of memory block 254 * @flags: TEE_SHM_* above 255 * @shmp: If the function return 0, this holds the allocated 256 * struct tee_shm 257 * 258 * returns 0 on success or < 0 on failure. 259 */ 260 int tee_shm_alloc(struct udevice *dev, ulong size, u32 flags, 261 struct tee_shm **shmp); 262 263 /** 264 * tee_shm_register() - Registers shared memory 265 * @dev: The TEE device 266 * @addr: Address of memory block 267 * @size: Size of memory block 268 * @flags: TEE_SHM_* above 269 * @shmp: If the function return 0, this holds the allocated 270 * struct tee_shm 271 * 272 * returns 0 on success or < 0 on failure. 273 */ 274 int tee_shm_register(struct udevice *dev, void *addr, ulong size, u32 flags, 275 struct tee_shm **shmp); 276 277 /** 278 * tee_shm_free() - Frees shared memory 279 * @shm: Shared memory object 280 */ 281 void tee_shm_free(struct tee_shm *shm); 282 283 /** 284 * tee_shm_is_registered() - Check register status of shared memory object 285 * @shm: Pointer to shared memory object 286 * @dev: The TEE device 287 * 288 * Returns true if the shared memory object is registered for the supplied 289 * TEE device 290 */ 291 bool tee_shm_is_registered(struct tee_shm *shm, struct udevice *dev); 292 293 /** 294 * tee_find_device() - Look up a TEE device 295 * @start: if not NULL, continue search after this device 296 * @match: function to check TEE device, returns != 0 if the device 297 * matches 298 * @data: data for match function 299 * @vers: if not NULL, version data of TEE device of the device returned 300 * 301 * Returns a probed TEE device of the first TEE device matched by the 302 * match() callback or NULL. 303 */ 304 struct udevice *tee_find_device(struct udevice *start, 305 int (*match)(struct tee_version_data *vers, 306 const void *data), 307 const void *data, 308 struct tee_version_data *vers); 309 310 /** 311 * tee_get_version() - Query capabilities of TEE device 312 * @dev: The TEE device 313 * @vers: Pointer to version data 314 */ 315 void tee_get_version(struct udevice *dev, struct tee_version_data *vers); 316 317 /** 318 * tee_open_session() - Open a session to a Trusted Application 319 * @dev: The TEE device 320 * @arg: Open session arguments 321 * @num_param: Number of elements in @param 322 * @param: Parameters for Trusted Application 323 * 324 * Returns < 0 on error else see @arg->ret for result. If @arg->ret is 325 * TEE_SUCCESS the session identifier is available in @arg->session. 326 */ 327 int tee_open_session(struct udevice *dev, struct tee_open_session_arg *arg, 328 uint num_param, struct tee_param *param); 329 330 /** 331 * tee_close_session() - Close a session to a Trusted Application 332 * @dev: The TEE device 333 * @session: Session id 334 * 335 * Return < 0 on error else 0, regardless the session will not be valid 336 * after this function has returned. 337 */ 338 int tee_close_session(struct udevice *dev, u32 session); 339 340 /** 341 * tee_invoke_func() - Invoke a function in a Trusted Application 342 * @dev: The TEE device 343 * @arg: Invoke arguments 344 * @num_param: Number of elements in @param 345 * @param: Parameters for Trusted Application 346 * 347 * Returns < 0 on error else see @arg->ret for result. 348 */ 349 int tee_invoke_func(struct udevice *dev, struct tee_invoke_arg *arg, 350 uint num_param, struct tee_param *param); 351 352 /** 353 * tee_optee_ta_uuid_from_octets() - Converts to struct tee_optee_ta_uuid 354 * @d: Destination struct 355 * @s: Source UUID octets 356 * 357 * Conversion to a struct tee_optee_ta_uuid represantion from binary octet 358 * representation. 359 */ 360 void tee_optee_ta_uuid_from_octets(struct tee_optee_ta_uuid *d, 361 const u8 s[TEE_UUID_LEN]); 362 363 /** 364 * tee_optee_ta_uuid_to_octets() - Converts from struct tee_optee_ta_uuid 365 * @d: Destination UUID octets 366 * @s: Source struct 367 * 368 * Conversion from a struct tee_optee_ta_uuid represantion to binary octet 369 * representation. 370 */ 371 void tee_optee_ta_uuid_to_octets(u8 d[TEE_UUID_LEN], 372 const struct tee_optee_ta_uuid *s); 373 374 #endif /* __TEE_H */ 375