1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * Copyright (c) 2015-2022 Linaro Limited |
4 | */ |
5 | |
6 | #ifndef __TEE_DRV_H |
7 | #define __TEE_DRV_H |
8 | |
9 | #include <linux/device.h> |
10 | #include <linux/idr.h> |
11 | #include <linux/kref.h> |
12 | #include <linux/list.h> |
13 | #include <linux/mod_devicetable.h> |
14 | #include <linux/tee.h> |
15 | #include <linux/types.h> |
16 | #include <linux/uuid.h> |
17 | |
18 | /* |
19 | * The file describes the API provided by the generic TEE driver to the |
20 | * specific TEE driver. |
21 | */ |
22 | |
23 | #define TEE_SHM_DYNAMIC BIT(0) /* Dynamic shared memory registered */ |
24 | /* in secure world */ |
25 | #define TEE_SHM_USER_MAPPED BIT(1) /* Memory mapped in user space */ |
26 | #define TEE_SHM_POOL BIT(2) /* Memory allocated from pool */ |
27 | #define TEE_SHM_PRIV BIT(3) /* Memory private to TEE driver */ |
28 | |
29 | struct device; |
30 | struct tee_device; |
31 | struct tee_shm; |
32 | struct tee_shm_pool; |
33 | |
34 | /** |
35 | * struct tee_context - driver specific context on file pointer data |
36 | * @teedev: pointer to this drivers struct tee_device |
37 | * @list_shm: List of shared memory object owned by this context |
38 | * @data: driver specific context data, managed by the driver |
39 | * @refcount: reference counter for this structure |
40 | * @releasing: flag that indicates if context is being released right now. |
41 | * It is needed to break circular dependency on context during |
42 | * shared memory release. |
43 | * @supp_nowait: flag that indicates that requests in this context should not |
44 | * wait for tee-supplicant daemon to be started if not present |
45 | * and just return with an error code. It is needed for requests |
46 | * that arises from TEE based kernel drivers that should be |
47 | * non-blocking in nature. |
48 | * @cap_memref_null: flag indicating if the TEE Client support shared |
49 | * memory buffer with a NULL pointer. |
50 | */ |
51 | struct tee_context { |
52 | struct tee_device *teedev; |
53 | void *data; |
54 | struct kref refcount; |
55 | bool releasing; |
56 | bool supp_nowait; |
57 | bool cap_memref_null; |
58 | }; |
59 | |
60 | struct tee_param_memref { |
61 | size_t shm_offs; |
62 | size_t size; |
63 | struct tee_shm *shm; |
64 | }; |
65 | |
66 | struct tee_param_value { |
67 | u64 a; |
68 | u64 b; |
69 | u64 c; |
70 | }; |
71 | |
72 | struct tee_param { |
73 | u64 attr; |
74 | union { |
75 | struct tee_param_memref memref; |
76 | struct tee_param_value value; |
77 | } u; |
78 | }; |
79 | |
80 | /** |
81 | * struct tee_driver_ops - driver operations vtable |
82 | * @get_version: returns version of driver |
83 | * @open: called when the device file is opened |
84 | * @release: release this open file |
85 | * @open_session: open a new session |
86 | * @close_session: close a session |
87 | * @invoke_func: invoke a trusted function |
88 | * @cancel_req: request cancel of an ongoing invoke or open |
89 | * @supp_recv: called for supplicant to get a command |
90 | * @supp_send: called for supplicant to send a response |
91 | * @shm_register: register shared memory buffer in TEE |
92 | * @shm_unregister: unregister shared memory buffer in TEE |
93 | */ |
94 | struct tee_driver_ops { |
95 | void (*get_version)(struct tee_device *teedev, |
96 | struct tee_ioctl_version_data *vers); |
97 | int (*open)(struct tee_context *ctx); |
98 | void (*release)(struct tee_context *ctx); |
99 | int (*open_session)(struct tee_context *ctx, |
100 | struct tee_ioctl_open_session_arg *arg, |
101 | struct tee_param *param); |
102 | int (*close_session)(struct tee_context *ctx, u32 session); |
103 | int (*invoke_func)(struct tee_context *ctx, |
104 | struct tee_ioctl_invoke_arg *arg, |
105 | struct tee_param *param); |
106 | int (*cancel_req)(struct tee_context *ctx, u32 cancel_id, u32 session); |
107 | int (*supp_recv)(struct tee_context *ctx, u32 *func, u32 *num_params, |
108 | struct tee_param *param); |
109 | int (*supp_send)(struct tee_context *ctx, u32 ret, u32 num_params, |
110 | struct tee_param *param); |
111 | int (*shm_register)(struct tee_context *ctx, struct tee_shm *shm, |
112 | struct page **pages, size_t num_pages, |
113 | unsigned long start); |
114 | int (*shm_unregister)(struct tee_context *ctx, struct tee_shm *shm); |
115 | }; |
116 | |
117 | /** |
118 | * struct tee_desc - Describes the TEE driver to the subsystem |
119 | * @name: name of driver |
120 | * @ops: driver operations vtable |
121 | * @owner: module providing the driver |
122 | * @flags: Extra properties of driver, defined by TEE_DESC_* below |
123 | */ |
124 | #define TEE_DESC_PRIVILEGED 0x1 |
125 | struct tee_desc { |
126 | const char *name; |
127 | const struct tee_driver_ops *ops; |
128 | struct module *owner; |
129 | u32 flags; |
130 | }; |
131 | |
132 | /** |
133 | * tee_device_alloc() - Allocate a new struct tee_device instance |
134 | * @teedesc: Descriptor for this driver |
135 | * @dev: Parent device for this device |
136 | * @pool: Shared memory pool, NULL if not used |
137 | * @driver_data: Private driver data for this device |
138 | * |
139 | * Allocates a new struct tee_device instance. The device is |
140 | * removed by tee_device_unregister(). |
141 | * |
142 | * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure |
143 | */ |
144 | struct tee_device *tee_device_alloc(const struct tee_desc *teedesc, |
145 | struct device *dev, |
146 | struct tee_shm_pool *pool, |
147 | void *driver_data); |
148 | |
149 | /** |
150 | * tee_device_register() - Registers a TEE device |
151 | * @teedev: Device to register |
152 | * |
153 | * tee_device_unregister() need to be called to remove the @teedev if |
154 | * this function fails. |
155 | * |
156 | * @returns < 0 on failure |
157 | */ |
158 | int tee_device_register(struct tee_device *teedev); |
159 | |
160 | /** |
161 | * tee_device_unregister() - Removes a TEE device |
162 | * @teedev: Device to unregister |
163 | * |
164 | * This function should be called to remove the @teedev even if |
165 | * tee_device_register() hasn't been called yet. Does nothing if |
166 | * @teedev is NULL. |
167 | */ |
168 | void tee_device_unregister(struct tee_device *teedev); |
169 | |
170 | /** |
171 | * tee_session_calc_client_uuid() - Calculates client UUID for session |
172 | * @uuid: Resulting UUID |
173 | * @connection_method: Connection method for session (TEE_IOCTL_LOGIN_*) |
174 | * @connectuon_data: Connection data for opening session |
175 | * |
176 | * Based on connection method calculates UUIDv5 based client UUID. |
177 | * |
178 | * For group based logins verifies that calling process has specified |
179 | * credentials. |
180 | * |
181 | * @return < 0 on failure |
182 | */ |
183 | int tee_session_calc_client_uuid(uuid_t *uuid, u32 connection_method, |
184 | const u8 connection_data[TEE_IOCTL_UUID_LEN]); |
185 | |
186 | /** |
187 | * struct tee_shm - shared memory object |
188 | * @ctx: context using the object |
189 | * @paddr: physical address of the shared memory |
190 | * @kaddr: virtual address of the shared memory |
191 | * @size: size of shared memory |
192 | * @offset: offset of buffer in user space |
193 | * @pages: locked pages from userspace |
194 | * @num_pages: number of locked pages |
195 | * @refcount: reference counter |
196 | * @flags: defined by TEE_SHM_* in tee_drv.h |
197 | * @id: unique id of a shared memory object on this device, shared |
198 | * with user space |
199 | * @sec_world_id: |
200 | * secure world assigned id of this shared memory object, not |
201 | * used by all drivers |
202 | * |
203 | * This pool is only supposed to be accessed directly from the TEE |
204 | * subsystem and from drivers that implements their own shm pool manager. |
205 | */ |
206 | struct tee_shm { |
207 | struct tee_context *ctx; |
208 | phys_addr_t paddr; |
209 | void *kaddr; |
210 | size_t size; |
211 | unsigned int offset; |
212 | struct page **pages; |
213 | size_t num_pages; |
214 | refcount_t refcount; |
215 | u32 flags; |
216 | int id; |
217 | u64 sec_world_id; |
218 | }; |
219 | |
220 | /** |
221 | * struct tee_shm_pool - shared memory pool |
222 | * @ops: operations |
223 | * @private_data: private data for the shared memory manager |
224 | */ |
225 | struct tee_shm_pool { |
226 | const struct tee_shm_pool_ops *ops; |
227 | void *private_data; |
228 | }; |
229 | |
230 | /** |
231 | * struct tee_shm_pool_ops - shared memory pool operations |
232 | * @alloc: called when allocating shared memory |
233 | * @free: called when freeing shared memory |
234 | * @destroy_pool: called when destroying the pool |
235 | */ |
236 | struct tee_shm_pool_ops { |
237 | int (*alloc)(struct tee_shm_pool *pool, struct tee_shm *shm, |
238 | size_t size, size_t align); |
239 | void (*free)(struct tee_shm_pool *pool, struct tee_shm *shm); |
240 | void (*destroy_pool)(struct tee_shm_pool *pool); |
241 | }; |
242 | |
243 | /* |
244 | * tee_shm_pool_alloc_res_mem() - Create a shm manager for reserved memory |
245 | * @vaddr: Virtual address of start of pool |
246 | * @paddr: Physical address of start of pool |
247 | * @size: Size in bytes of the pool |
248 | * |
249 | * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure. |
250 | */ |
251 | struct tee_shm_pool *tee_shm_pool_alloc_res_mem(unsigned long vaddr, |
252 | phys_addr_t paddr, size_t size, |
253 | int min_alloc_order); |
254 | |
255 | /** |
256 | * tee_shm_pool_free() - Free a shared memory pool |
257 | * @pool: The shared memory pool to free |
258 | * |
259 | * The must be no remaining shared memory allocated from this pool when |
260 | * this function is called. |
261 | */ |
262 | static inline void tee_shm_pool_free(struct tee_shm_pool *pool) |
263 | { |
264 | pool->ops->destroy_pool(pool); |
265 | } |
266 | |
267 | /** |
268 | * tee_get_drvdata() - Return driver_data pointer |
269 | * @returns the driver_data pointer supplied to tee_register(). |
270 | */ |
271 | void *tee_get_drvdata(struct tee_device *teedev); |
272 | |
273 | struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size); |
274 | struct tee_shm *tee_shm_alloc_kernel_buf(struct tee_context *ctx, size_t size); |
275 | |
276 | struct tee_shm *tee_shm_register_kernel_buf(struct tee_context *ctx, |
277 | void *addr, size_t length); |
278 | |
279 | /** |
280 | * tee_shm_is_dynamic() - Check if shared memory object is of the dynamic kind |
281 | * @shm: Shared memory handle |
282 | * @returns true if object is dynamic shared memory |
283 | */ |
284 | static inline bool tee_shm_is_dynamic(struct tee_shm *shm) |
285 | { |
286 | return shm && (shm->flags & TEE_SHM_DYNAMIC); |
287 | } |
288 | |
289 | /** |
290 | * tee_shm_free() - Free shared memory |
291 | * @shm: Handle to shared memory to free |
292 | */ |
293 | void tee_shm_free(struct tee_shm *shm); |
294 | |
295 | /** |
296 | * tee_shm_put() - Decrease reference count on a shared memory handle |
297 | * @shm: Shared memory handle |
298 | */ |
299 | void tee_shm_put(struct tee_shm *shm); |
300 | |
301 | /** |
302 | * tee_shm_get_va() - Get virtual address of a shared memory plus an offset |
303 | * @shm: Shared memory handle |
304 | * @offs: Offset from start of this shared memory |
305 | * @returns virtual address of the shared memory + offs if offs is within |
306 | * the bounds of this shared memory, else an ERR_PTR |
307 | */ |
308 | void *tee_shm_get_va(struct tee_shm *shm, size_t offs); |
309 | |
310 | /** |
311 | * tee_shm_get_pa() - Get physical address of a shared memory plus an offset |
312 | * @shm: Shared memory handle |
313 | * @offs: Offset from start of this shared memory |
314 | * @pa: Physical address to return |
315 | * @returns 0 if offs is within the bounds of this shared memory, else an |
316 | * error code. |
317 | */ |
318 | int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa); |
319 | |
320 | /** |
321 | * tee_shm_get_size() - Get size of shared memory buffer |
322 | * @shm: Shared memory handle |
323 | * @returns size of shared memory |
324 | */ |
325 | static inline size_t tee_shm_get_size(struct tee_shm *shm) |
326 | { |
327 | return shm->size; |
328 | } |
329 | |
330 | /** |
331 | * tee_shm_get_pages() - Get list of pages that hold shared buffer |
332 | * @shm: Shared memory handle |
333 | * @num_pages: Number of pages will be stored there |
334 | * @returns pointer to pages array |
335 | */ |
336 | static inline struct page **tee_shm_get_pages(struct tee_shm *shm, |
337 | size_t *num_pages) |
338 | { |
339 | *num_pages = shm->num_pages; |
340 | return shm->pages; |
341 | } |
342 | |
343 | /** |
344 | * tee_shm_get_page_offset() - Get shared buffer offset from page start |
345 | * @shm: Shared memory handle |
346 | * @returns page offset of shared buffer |
347 | */ |
348 | static inline size_t tee_shm_get_page_offset(struct tee_shm *shm) |
349 | { |
350 | return shm->offset; |
351 | } |
352 | |
353 | /** |
354 | * tee_shm_get_id() - Get id of a shared memory object |
355 | * @shm: Shared memory handle |
356 | * @returns id |
357 | */ |
358 | static inline int tee_shm_get_id(struct tee_shm *shm) |
359 | { |
360 | return shm->id; |
361 | } |
362 | |
363 | /** |
364 | * tee_shm_get_from_id() - Find shared memory object and increase reference |
365 | * count |
366 | * @ctx: Context owning the shared memory |
367 | * @id: Id of shared memory object |
368 | * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure |
369 | */ |
370 | struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id); |
371 | |
372 | /** |
373 | * tee_client_open_context() - Open a TEE context |
374 | * @start: if not NULL, continue search after this context |
375 | * @match: function to check TEE device |
376 | * @data: data for match function |
377 | * @vers: if not NULL, version data of TEE device of the context returned |
378 | * |
379 | * This function does an operation similar to open("/dev/teeX") in user space. |
380 | * A returned context must be released with tee_client_close_context(). |
381 | * |
382 | * Returns a TEE context of the first TEE device matched by the match() |
383 | * callback or an ERR_PTR. |
384 | */ |
385 | struct tee_context * |
386 | tee_client_open_context(struct tee_context *start, |
387 | int (*match)(struct tee_ioctl_version_data *, |
388 | const void *), |
389 | const void *data, struct tee_ioctl_version_data *vers); |
390 | |
391 | /** |
392 | * tee_client_close_context() - Close a TEE context |
393 | * @ctx: TEE context to close |
394 | * |
395 | * Note that all sessions previously opened with this context will be |
396 | * closed when this function is called. |
397 | */ |
398 | void tee_client_close_context(struct tee_context *ctx); |
399 | |
400 | /** |
401 | * tee_client_get_version() - Query version of TEE |
402 | * @ctx: TEE context to TEE to query |
403 | * @vers: Pointer to version data |
404 | */ |
405 | void tee_client_get_version(struct tee_context *ctx, |
406 | struct tee_ioctl_version_data *vers); |
407 | |
408 | /** |
409 | * tee_client_open_session() - Open a session to a Trusted Application |
410 | * @ctx: TEE context |
411 | * @arg: Open session arguments, see description of |
412 | * struct tee_ioctl_open_session_arg |
413 | * @param: Parameters passed to the Trusted Application |
414 | * |
415 | * Returns < 0 on error else see @arg->ret for result. If @arg->ret |
416 | * is TEEC_SUCCESS the session identifier is available in @arg->session. |
417 | */ |
418 | int tee_client_open_session(struct tee_context *ctx, |
419 | struct tee_ioctl_open_session_arg *arg, |
420 | struct tee_param *param); |
421 | |
422 | /** |
423 | * tee_client_close_session() - Close a session to a Trusted Application |
424 | * @ctx: TEE Context |
425 | * @session: Session id |
426 | * |
427 | * Return < 0 on error else 0, regardless the session will not be |
428 | * valid after this function has returned. |
429 | */ |
430 | int tee_client_close_session(struct tee_context *ctx, u32 session); |
431 | |
432 | /** |
433 | * tee_client_invoke_func() - Invoke a function in a Trusted Application |
434 | * @ctx: TEE Context |
435 | * @arg: Invoke arguments, see description of |
436 | * struct tee_ioctl_invoke_arg |
437 | * @param: Parameters passed to the Trusted Application |
438 | * |
439 | * Returns < 0 on error else see @arg->ret for result. |
440 | */ |
441 | int tee_client_invoke_func(struct tee_context *ctx, |
442 | struct tee_ioctl_invoke_arg *arg, |
443 | struct tee_param *param); |
444 | |
445 | /** |
446 | * tee_client_cancel_req() - Request cancellation of the previous open-session |
447 | * or invoke-command operations in a Trusted Application |
448 | * @ctx: TEE Context |
449 | * @arg: Cancellation arguments, see description of |
450 | * struct tee_ioctl_cancel_arg |
451 | * |
452 | * Returns < 0 on error else 0 if the cancellation was successfully requested. |
453 | */ |
454 | int tee_client_cancel_req(struct tee_context *ctx, |
455 | struct tee_ioctl_cancel_arg *arg); |
456 | |
457 | static inline bool tee_param_is_memref(struct tee_param *param) |
458 | { |
459 | switch (param->attr & TEE_IOCTL_PARAM_ATTR_TYPE_MASK) { |
460 | case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT: |
461 | case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT: |
462 | case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT: |
463 | return true; |
464 | default: |
465 | return false; |
466 | } |
467 | } |
468 | |
469 | extern struct bus_type tee_bus_type; |
470 | |
471 | /** |
472 | * struct tee_client_device - tee based device |
473 | * @id: device identifier |
474 | * @dev: device structure |
475 | */ |
476 | struct tee_client_device { |
477 | struct tee_client_device_id id; |
478 | struct device dev; |
479 | }; |
480 | |
481 | #define to_tee_client_device(d) container_of(d, struct tee_client_device, dev) |
482 | |
483 | /** |
484 | * struct tee_client_driver - tee client driver |
485 | * @id_table: device id table supported by this driver |
486 | * @driver: driver structure |
487 | */ |
488 | struct tee_client_driver { |
489 | const struct tee_client_device_id *id_table; |
490 | struct device_driver driver; |
491 | }; |
492 | |
493 | #define to_tee_client_driver(d) \ |
494 | container_of(d, struct tee_client_driver, driver) |
495 | |
496 | /** |
497 | * teedev_open() - Open a struct tee_device |
498 | * @teedev: Device to open |
499 | * |
500 | * @return a pointer to struct tee_context on success or an ERR_PTR on failure. |
501 | */ |
502 | struct tee_context *teedev_open(struct tee_device *teedev); |
503 | |
504 | /** |
505 | * teedev_close_context() - closes a struct tee_context |
506 | * @ctx: The struct tee_context to close |
507 | */ |
508 | void teedev_close_context(struct tee_context *ctx); |
509 | |
510 | #endif /*__TEE_DRV_H*/ |
511 | |