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
21 struct 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 */
39 struct 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 */
65 struct 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
79 struct tee_param_memref {
80 size_t shm_offs;
81 size_t size;
82 struct tee_shm *shm;
83 };
84
85 struct tee_param_ubuf {
86 void __user *uaddr;
87 size_t size;
88 };
89
90 struct tee_param_objref {
91 u64 id;
92 u64 flags;
93 };
94
95 struct tee_param_value {
96 u64 a;
97 u64 b;
98 u64 c;
99 };
100
101 struct 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 */
118 struct 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 */
128 struct 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 */
139 struct 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 */
145 void 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 */
154 void *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 */
164 int 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 */
tee_shm_get_size(struct tee_shm * shm)171 static 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 */
tee_shm_get_pages(struct tee_shm * shm,size_t * num_pages)182 static 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 */
tee_shm_get_page_offset(struct tee_shm * shm)194 static 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 */
212 struct tee_context *
213 tee_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 */
225 void 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 */
232 void 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 */
245 int 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 */
257 int 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 */
271 int 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 */
282 int 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 */
295 int tee_client_cancel_req(struct tee_context *ctx,
296 struct tee_ioctl_cancel_arg *arg);
297
298 extern 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 */
305 struct 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 */
317 struct tee_client_driver {
318 int (*probe)(struct tee_client_device *);
319 void (*remove)(struct tee_client_device *);
320 void (*shutdown)(struct tee_client_device *);
321 const struct tee_client_device_id *id_table;
322 struct device_driver driver;
323 };
324
325 #define to_tee_client_driver(d) \
326 container_of_const(d, struct tee_client_driver, driver)
327
328 #define tee_client_driver_register(drv) \
329 __tee_client_driver_register(drv, THIS_MODULE)
330 int __tee_client_driver_register(struct tee_client_driver *, struct module *);
331 void tee_client_driver_unregister(struct tee_client_driver *);
332
333 #define module_tee_client_driver(__tee_client_driver) \
334 module_driver(__tee_client_driver, tee_client_driver_register, \
335 tee_client_driver_unregister)
336
337 #endif /*__TEE_DRV_H*/
338