1/* SPDX-License-Identifier: GPL-2.0-only */
2/*
3 * Copyright (c) 2015-2024 Linaro Limited
4 */
5
6#ifndef __TEE_DRV_H
7#define __TEE_DRV_H
8
9#include <linux/device.h>
10#include <linux/kref.h>
11#include <linux/list.h>
12#include <linux/mod_devicetable.h>
13#include <linux/tee.h>
14#include <linux/types.h>
15
16/*
17 * The file describes the API provided by the TEE subsystem to the
18 * TEE client drivers.
19 */
20
21struct tee_device;
22
23/**
24 * struct tee_context - driver specific context on file pointer data
25 * @teedev: pointer to this drivers struct tee_device
26 * @data: driver specific context data, managed by the driver
27 * @refcount: reference counter for this structure
28 * @releasing: flag that indicates if context is being released right now.
29 * It is needed to break circular dependency on context during
30 * shared memory release.
31 * @supp_nowait: flag that indicates that requests in this context should not
32 * wait for tee-supplicant daemon to be started if not present
33 * and just return with an error code. It is needed for requests
34 * that arises from TEE based kernel drivers that should be
35 * non-blocking in nature.
36 * @cap_memref_null: flag indicating if the TEE Client support shared
37 * memory buffer with a NULL pointer.
38 */
39struct tee_context {
40 struct tee_device *teedev;
41 void *data;
42 struct kref refcount;
43 bool releasing;
44 bool supp_nowait;
45 bool cap_memref_null;
46};
47
48/**
49 * struct tee_shm - shared memory object
50 * @ctx: context using the object
51 * @paddr: physical address of the shared memory
52 * @kaddr: virtual address of the shared memory
53 * @size: size of shared memory
54 * @offset: offset of buffer in user space
55 * @pages: locked pages from userspace
56 * @num_pages: number of locked pages
57 * @refcount: reference counter
58 * @flags: defined by TEE_SHM_* in tee_core.h
59 * @id: unique id of a shared memory object on this device, shared
60 * with user space
61 * @sec_world_id:
62 * secure world assigned id of this shared memory object, not
63 * used by all drivers
64 */
65struct tee_shm {
66 struct tee_context *ctx;
67 phys_addr_t paddr;
68 void *kaddr;
69 size_t size;
70 unsigned int offset;
71 struct page **pages;
72 size_t num_pages;
73 refcount_t refcount;
74 u32 flags;
75 int id;
76 u64 sec_world_id;
77};
78
79struct tee_param_memref {
80 size_t shm_offs;
81 size_t size;
82 struct tee_shm *shm;
83};
84
85struct tee_param_ubuf {
86 void __user *uaddr;
87 size_t size;
88};
89
90struct tee_param_objref {
91 u64 id;
92 u64 flags;
93};
94
95struct tee_param_value {
96 u64 a;
97 u64 b;
98 u64 c;
99};
100
101struct tee_param {
102 u64 attr;
103 union {
104 struct tee_param_memref memref;
105 struct tee_param_objref objref;
106 struct tee_param_ubuf ubuf;
107 struct tee_param_value value;
108 } u;
109};
110
111/**
112 * tee_shm_alloc_kernel_buf() - Allocate kernel shared memory for a
113 * particular TEE client driver
114 * @ctx: The TEE context for shared memory allocation
115 * @size: Shared memory allocation size
116 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
117 */
118struct tee_shm *tee_shm_alloc_kernel_buf(struct tee_context *ctx, size_t size);
119
120/**
121 * tee_shm_register_kernel_buf() - Register kernel shared memory for a
122 * particular TEE client driver
123 * @ctx: The TEE context for shared memory registration
124 * @addr: Kernel buffer address
125 * @length: Kernel buffer length
126 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
127 */
128struct tee_shm *tee_shm_register_kernel_buf(struct tee_context *ctx,
129 void *addr, size_t length);
130
131/**
132 * tee_shm_register_fd() - Register shared memory from file descriptor
133 *
134 * @ctx: Context that allocates the shared memory
135 * @fd: Shared memory file descriptor reference
136 *
137 * @returns a pointer to 'struct tee_shm' on success, and ERR_PTR on failure
138 */
139struct tee_shm *tee_shm_register_fd(struct tee_context *ctx, int fd);
140
141/**
142 * tee_shm_free() - Free shared memory
143 * @shm: Handle to shared memory to free
144 */
145void tee_shm_free(struct tee_shm *shm);
146
147/**
148 * tee_shm_get_va() - Get virtual address of a shared memory plus an offset
149 * @shm: Shared memory handle
150 * @offs: Offset from start of this shared memory
151 * @returns virtual address of the shared memory + offs if offs is within
152 * the bounds of this shared memory, else an ERR_PTR
153 */
154void *tee_shm_get_va(struct tee_shm *shm, size_t offs);
155
156/**
157 * tee_shm_get_pa() - Get physical address of a shared memory plus an offset
158 * @shm: Shared memory handle
159 * @offs: Offset from start of this shared memory
160 * @pa: Physical address to return
161 * @returns 0 if offs is within the bounds of this shared memory, else an
162 * error code.
163 */
164int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa);
165
166/**
167 * tee_shm_get_size() - Get size of shared memory buffer
168 * @shm: Shared memory handle
169 * @returns size of shared memory
170 */
171static inline size_t tee_shm_get_size(struct tee_shm *shm)
172{
173 return shm->size;
174}
175
176/**
177 * tee_shm_get_pages() - Get list of pages that hold shared buffer
178 * @shm: Shared memory handle
179 * @num_pages: Number of pages will be stored there
180 * @returns pointer to pages array
181 */
182static inline struct page **tee_shm_get_pages(struct tee_shm *shm,
183 size_t *num_pages)
184{
185 *num_pages = shm->num_pages;
186 return shm->pages;
187}
188
189/**
190 * tee_shm_get_page_offset() - Get shared buffer offset from page start
191 * @shm: Shared memory handle
192 * @returns page offset of shared buffer
193 */
194static inline size_t tee_shm_get_page_offset(struct tee_shm *shm)
195{
196 return shm->offset;
197}
198
199/**
200 * tee_client_open_context() - Open a TEE context
201 * @start: if not NULL, continue search after this context
202 * @match: function to check TEE device
203 * @data: data for match function
204 * @vers: if not NULL, version data of TEE device of the context returned
205 *
206 * This function does an operation similar to open("/dev/teeX") in user space.
207 * A returned context must be released with tee_client_close_context().
208 *
209 * Returns a TEE context of the first TEE device matched by the match()
210 * callback or an ERR_PTR.
211 */
212struct tee_context *
213tee_client_open_context(struct tee_context *start,
214 int (*match)(struct tee_ioctl_version_data *,
215 const void *),
216 const void *data, struct tee_ioctl_version_data *vers);
217
218/**
219 * tee_client_close_context() - Close a TEE context
220 * @ctx: TEE context to close
221 *
222 * Note that all sessions previously opened with this context will be
223 * closed when this function is called.
224 */
225void tee_client_close_context(struct tee_context *ctx);
226
227/**
228 * tee_client_get_version() - Query version of TEE
229 * @ctx: TEE context to TEE to query
230 * @vers: Pointer to version data
231 */
232void tee_client_get_version(struct tee_context *ctx,
233 struct tee_ioctl_version_data *vers);
234
235/**
236 * tee_client_open_session() - Open a session to a Trusted Application
237 * @ctx: TEE context
238 * @arg: Open session arguments, see description of
239 * struct tee_ioctl_open_session_arg
240 * @param: Parameters passed to the Trusted Application
241 *
242 * Returns < 0 on error else see @arg->ret for result. If @arg->ret
243 * is TEEC_SUCCESS the session identifier is available in @arg->session.
244 */
245int tee_client_open_session(struct tee_context *ctx,
246 struct tee_ioctl_open_session_arg *arg,
247 struct tee_param *param);
248
249/**
250 * tee_client_close_session() - Close a session to a Trusted Application
251 * @ctx: TEE Context
252 * @session: Session id
253 *
254 * Return < 0 on error else 0, regardless the session will not be
255 * valid after this function has returned.
256 */
257int tee_client_close_session(struct tee_context *ctx, u32 session);
258
259/**
260 * tee_client_system_session() - Declare session as a system session
261 * @ctx: TEE Context
262 * @session: Session id
263 *
264 * This function requests TEE to provision an entry context ready to use for
265 * that session only. The provisioned entry context is used for command
266 * invocation and session closure, not for command cancelling requests.
267 * TEE releases the provisioned context upon session closure.
268 *
269 * Return < 0 on error else 0 if an entry context has been provisioned.
270 */
271int tee_client_system_session(struct tee_context *ctx, u32 session);
272
273/**
274 * tee_client_invoke_func() - Invoke a function in a Trusted Application
275 * @ctx: TEE Context
276 * @arg: Invoke arguments, see description of
277 * struct tee_ioctl_invoke_arg
278 * @param: Parameters passed to the Trusted Application
279 *
280 * Returns < 0 on error else see @arg->ret for result.
281 */
282int tee_client_invoke_func(struct tee_context *ctx,
283 struct tee_ioctl_invoke_arg *arg,
284 struct tee_param *param);
285
286/**
287 * tee_client_cancel_req() - Request cancellation of the previous open-session
288 * or invoke-command operations in a Trusted Application
289 * @ctx: TEE Context
290 * @arg: Cancellation arguments, see description of
291 * struct tee_ioctl_cancel_arg
292 *
293 * Returns < 0 on error else 0 if the cancellation was successfully requested.
294 */
295int tee_client_cancel_req(struct tee_context *ctx,
296 struct tee_ioctl_cancel_arg *arg);
297
298extern const struct bus_type tee_bus_type;
299
300/**
301 * struct tee_client_device - tee based device
302 * @id: device identifier
303 * @dev: device structure
304 */
305struct tee_client_device {
306 struct tee_client_device_id id;
307 struct device dev;
308};
309
310#define to_tee_client_device(d) container_of(d, struct tee_client_device, dev)
311
312/**
313 * struct tee_client_driver - tee client driver
314 * @id_table: device id table supported by this driver
315 * @driver: driver structure
316 */
317struct tee_client_driver {
318 const struct tee_client_device_id *id_table;
319 struct device_driver driver;
320};
321
322#define to_tee_client_driver(d) \
323 container_of_const(d, struct tee_client_driver, driver)
324
325#endif /*__TEE_DRV_H*/
326

source code of linux/include/linux/tee_drv.h