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