xref: /openbmc/u-boot/include/tee.h (revision 2d59ec84829ff339041667c857afe94d5160f4b4)
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