• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2015-2016, Linaro Limited
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright notice,
9  * this list of conditions and the following disclaimer.
10  *
11  * 2. Redistributions in binary form must reproduce the above copyright notice,
12  * this list of conditions and the following disclaimer in the documentation
13  * and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
19  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25  * POSSIBILITY OF SUCH DAMAGE.
26  */
27 
28 #ifndef __TEE_H
29 #define __TEE_H
30 
31 #include <linux/ioctl.h>
32 #include <linux/types.h>
33 
34 /*
35  * This file describes the API provided by a TEE driver to user space.
36  *
37  * Each TEE driver defines a TEE specific protocol which is used for the
38  * data passed back and forth using TEE_IOC_CMD.
39  */
40 
41 /* Helpers to make the ioctl defines */
42 #define TEE_IOC_MAGIC	0xa4
43 #define TEE_IOC_BASE	0
44 
45 /* Flags relating to shared memory */
46 #define TEE_IOCTL_SHM_MAPPED	0x1	/* memory mapped in normal world */
47 #define TEE_IOCTL_SHM_DMA_BUF	0x2	/* dma-buf handle on shared memory */
48 
49 #define TEE_MAX_ARG_SIZE	1024
50 
51 #define TEE_GEN_CAP_GP		(1 << 0)/* GlobalPlatform compliant TEE */
52 #define TEE_GEN_CAP_PRIVILEGED	(1 << 1)/* Privileged device (for supplicant) */
53 #define TEE_GEN_CAP_REG_MEM	(1 << 2)/* Supports registering shared memory */
54 
55 /*
56  * TEE Implementation ID
57  */
58 #define TEE_IMPL_ID_OPTEE	1
59 
60 /*
61  * OP-TEE specific capabilities
62  */
63 #define TEE_OPTEE_CAP_TZ	(1 << 0)
64 
65 /**
66  * struct tee_ioctl_version_data - TEE version
67  * @impl_id:	[out] TEE implementation id
68  * @impl_caps:	[out] Implementation specific capabilities
69  * @gen_caps:	[out] Generic capabilities, defined by TEE_GEN_CAPS_* above
70  *
71  * Identifies the TEE implementation, @impl_id is one of TEE_IMPL_ID_* above.
72  * @impl_caps is implementation specific, for example TEE_OPTEE_CAP_*
73  * is valid when @impl_id == TEE_IMPL_ID_OPTEE.
74  */
75 struct tee_ioctl_version_data {
76 	__u32 impl_id;
77 	__u32 impl_caps;
78 	__u32 gen_caps;
79 };
80 
81 /**
82  * TEE_IOC_VERSION - query version of TEE
83  *
84  * Takes a tee_ioctl_version_data struct and returns with the TEE version
85  * data filled in.
86  */
87 #define TEE_IOC_VERSION		_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 0, \
88 				     struct tee_ioctl_version_data)
89 
90 /**
91  * struct tee_ioctl_shm_alloc_data - Shared memory allocate argument
92  * @size:	[in/out] Size of shared memory to allocate
93  * @flags:	[in/out] Flags to/from allocation.
94  * @id:		[out] Identifier of the shared memory
95  *
96  * The flags field should currently be zero as input. Updated by the call
97  * with actual flags as defined by TEE_IOCTL_SHM_* above.
98  * This structure is used as argument for TEE_IOC_SHM_ALLOC below.
99  */
100 struct tee_ioctl_shm_alloc_data {
101 	__u64 size;
102 	__u32 flags;
103 	__s32 id;
104 };
105 
106 /**
107  * TEE_IOC_SHM_ALLOC - allocate shared memory
108  *
109  * Allocates shared memory between the user space process and secure OS.
110  *
111  * Returns a file descriptor on success or < 0 on failure
112  *
113  * The returned file descriptor is used to map the shared memory into user
114  * space. The shared memory is freed when the descriptor is closed and the
115  * memory is unmapped.
116  */
117 #define TEE_IOC_SHM_ALLOC	_IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 1, \
118 				     struct tee_ioctl_shm_alloc_data)
119 
120 /**
121  * struct tee_ioctl_buf_data - Variable sized buffer
122  * @buf_ptr:	[in] A __user pointer to a buffer
123  * @buf_len:	[in] Length of the buffer above
124  *
125  * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,
126  * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.
127  */
128 struct tee_ioctl_buf_data {
129 	__u64 buf_ptr;
130 	__u64 buf_len;
131 };
132 
133 /*
134  * Attributes for struct tee_ioctl_param, selects field in the union
135  */
136 #define TEE_IOCTL_PARAM_ATTR_TYPE_NONE		0	/* parameter not used */
137 
138 /*
139  * These defines value parameters (struct tee_ioctl_param_value)
140  */
141 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INPUT	1
142 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT	2
143 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT	3	/* input and output */
144 
145 /*
146  * These defines shared memory reference parameters (struct
147  * tee_ioctl_param_memref)
148  */
149 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT	5
150 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT	6
151 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT	7	/* input and output */
152 
153 /*
154  * Mask for the type part of the attribute, leaves room for more types
155  */
156 #define TEE_IOCTL_PARAM_ATTR_TYPE_MASK		0xff
157 
158 /* Meta parameter carrying extra information about the message. */
159 #define TEE_IOCTL_PARAM_ATTR_META		0x100
160 
161 /* Mask of all known attr bits */
162 #define TEE_IOCTL_PARAM_ATTR_MASK \
163 	(TEE_IOCTL_PARAM_ATTR_TYPE_MASK | TEE_IOCTL_PARAM_ATTR_META)
164 
165 /*
166  * Matches TEEC_LOGIN_* in GP TEE Client API
167  * Are only defined for GP compliant TEEs
168  */
169 #define TEE_IOCTL_LOGIN_PUBLIC			0
170 #define TEE_IOCTL_LOGIN_USER			1
171 #define TEE_IOCTL_LOGIN_GROUP			2
172 #define TEE_IOCTL_LOGIN_APPLICATION		4
173 #define TEE_IOCTL_LOGIN_USER_APPLICATION	5
174 #define TEE_IOCTL_LOGIN_GROUP_APPLICATION	6
175 
176 /**
177  * struct tee_ioctl_param - parameter
178  * @attr: attributes
179  * @a: if a memref, offset into the shared memory object, else a value parameter
180  * @b: if a memref, size of the buffer, else a value parameter
181  * @c: if a memref, shared memory identifier, else a value parameter
182  *
183  * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref or value is used in
184  * the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value and
185  * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref. TEE_PARAM_ATTR_TYPE_NONE
186  * indicates that none of the members are used.
187  *
188  * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an
189  * identifier representing the shared memory object. A memref can reference
190  * a part of a shared memory by specifying an offset (@a) and size (@b) of
191  * the object. To supply the entire shared memory object set the offset
192  * (@a) to 0 and size (@b) to the previously returned size of the object.
193  */
194 struct tee_ioctl_param {
195 	__u64 attr;
196 	__u64 a;
197 	__u64 b;
198 	__u64 c;
199 };
200 
201 #define TEE_IOCTL_UUID_LEN		16
202 
203 /**
204  * struct tee_ioctl_open_session_arg - Open session argument
205  * @uuid:	[in] UUID of the Trusted Application
206  * @clnt_uuid:	[in] UUID of client
207  * @clnt_login:	[in] Login class of client, TEE_IOCTL_LOGIN_* above
208  * @cancel_id:	[in] Cancellation id, a unique value to identify this request
209  * @session:	[out] Session id
210  * @ret:	[out] return value
211  * @ret_origin	[out] origin of the return value
212  * @num_params	[in] number of parameters following this struct
213  */
214 struct tee_ioctl_open_session_arg {
215 	__u8 uuid[TEE_IOCTL_UUID_LEN];
216 	__u8 clnt_uuid[TEE_IOCTL_UUID_LEN];
217 	__u32 clnt_login;
218 	__u32 cancel_id;
219 	__u32 session;
220 	__u32 ret;
221 	__u32 ret_origin;
222 	__u32 num_params;
223 	/* num_params tells the actual number of element in params */
224 	struct tee_ioctl_param params[];
225 };
226 
227 /**
228  * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application
229  *
230  * Takes a struct tee_ioctl_buf_data which contains a struct
231  * tee_ioctl_open_session_arg followed by any array of struct
232  * tee_ioctl_param
233  */
234 #define TEE_IOC_OPEN_SESSION	_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
235 				     struct tee_ioctl_buf_data)
236 
237 /**
238  * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
239  * Application
240  * @func:	[in] Trusted Application function, specific to the TA
241  * @session:	[in] Session id
242  * @cancel_id:	[in] Cancellation id, a unique value to identify this request
243  * @ret:	[out] return value
244  * @ret_origin	[out] origin of the return value
245  * @num_params	[in] number of parameters following this struct
246  */
247 struct tee_ioctl_invoke_arg {
248 	__u32 func;
249 	__u32 session;
250 	__u32 cancel_id;
251 	__u32 ret;
252 	__u32 ret_origin;
253 	__u32 num_params;
254 	/* num_params tells the actual number of element in params */
255 	struct tee_ioctl_param params[];
256 };
257 
258 /**
259  * TEE_IOC_INVOKE - Invokes a function in a Trusted Application
260  *
261  * Takes a struct tee_ioctl_buf_data which contains a struct
262  * tee_invoke_func_arg followed by any array of struct tee_param
263  */
264 #define TEE_IOC_INVOKE		_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \
265 				     struct tee_ioctl_buf_data)
266 
267 /**
268  * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl
269  * @cancel_id:	[in] Cancellation id, a unique value to identify this request
270  * @session:	[in] Session id, if the session is opened, else set to 0
271  */
272 struct tee_ioctl_cancel_arg {
273 	__u32 cancel_id;
274 	__u32 session;
275 };
276 
277 /**
278  * TEE_IOC_CANCEL - Cancels an open session or invoke
279  */
280 #define TEE_IOC_CANCEL		_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 4, \
281 				     struct tee_ioctl_cancel_arg)
282 
283 /**
284  * struct tee_ioctl_close_session_arg - Closes an open session
285  * @session:	[in] Session id
286  */
287 struct tee_ioctl_close_session_arg {
288 	__u32 session;
289 };
290 
291 /**
292  * TEE_IOC_CLOSE_SESSION - Closes a session
293  */
294 #define TEE_IOC_CLOSE_SESSION	_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \
295 				     struct tee_ioctl_close_session_arg)
296 
297 /**
298  * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
299  * @func:	[in] supplicant function
300  * @num_params	[in/out] number of parameters following this struct
301  *
302  * @num_params is the number of params that tee-supplicant has room to
303  * receive when input, @num_params is the number of actual params
304  * tee-supplicant receives when output.
305  */
306 struct tee_iocl_supp_recv_arg {
307 	__u32 func;
308 	__u32 num_params;
309 	/* num_params tells the actual number of element in params */
310 	struct tee_ioctl_param params[];
311 };
312 
313 /**
314  * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function
315  *
316  * Takes a struct tee_ioctl_buf_data which contains a struct
317  * tee_iocl_supp_recv_arg followed by any array of struct tee_param
318  */
319 #define TEE_IOC_SUPPL_RECV	_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \
320 				     struct tee_ioctl_buf_data)
321 
322 /**
323  * struct tee_iocl_supp_send_arg - Send a response to a received request
324  * @ret:	[out] return value
325  * @num_params	[in] number of parameters following this struct
326  */
327 struct tee_iocl_supp_send_arg {
328 	__u32 ret;
329 	__u32 num_params;
330 	/* num_params tells the actual number of element in params */
331 	struct tee_ioctl_param params[];
332 };
333 
334 /**
335  * TEE_IOC_SUPPL_SEND - Receive a request for a supplicant function
336  *
337  * Takes a struct tee_ioctl_buf_data which contains a struct
338  * tee_iocl_supp_send_arg followed by any array of struct tee_param
339  */
340 #define TEE_IOC_SUPPL_SEND	_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \
341 				     struct tee_ioctl_buf_data)
342 
343 /**
344  * struct tee_ioctl_shm_register_data - Shared memory register argument
345  * @addr:      [in] Start address of shared memory to register
346  * @length:    [in/out] Length of shared memory to register
347  * @flags:     [in/out] Flags to/from registration.
348  * @id:                [out] Identifier of the shared memory
349  *
350  * The flags field should currently be zero as input. Updated by the call
351  * with actual flags as defined by TEE_IOCTL_SHM_* above.
352  * This structure is used as argument for TEE_IOC_SHM_REGISTER below.
353  */
354 struct tee_ioctl_shm_register_data {
355 	__u64 addr;
356 	__u64 length;
357 	__u32 flags;
358 	__s32 id;
359 };
360 
361 /**
362  * TEE_IOC_SHM_REGISTER - Register shared memory argument
363  *
364  * Registers shared memory between the user space process and secure OS.
365  *
366  * Returns a file descriptor on success or < 0 on failure
367  *
368  * The shared memory is unregisterred when the descriptor is closed.
369  */
370 #define TEE_IOC_SHM_REGISTER   _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 9, \
371 				     struct tee_ioctl_shm_register_data)
372 /*
373  * Five syscalls are used when communicating with the TEE driver.
374  * open(): opens the device associated with the driver
375  * ioctl(): as described above operating on the file descriptor from open()
376  * close(): two cases
377  *   - closes the device file descriptor
378  *   - closes a file descriptor connected to allocated shared memory
379  * mmap(): maps shared memory into user space using information from struct
380  *	   tee_ioctl_shm_alloc_data
381  * munmap(): unmaps previously shared memory
382  */
383 
384 #endif /*__TEE_H*/
385