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