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_value {
86 u64 a;
87 u64 b;
88 u64 c;
89 };
90
91 struct tee_param {
92 u64 attr;
93 union {
94 struct tee_param_memref memref;
95 struct tee_param_value value;
96 } u;
97 };
98
99 /**
100 * tee_shm_alloc_kernel_buf() - Allocate kernel shared memory for a
101 * particular TEE client driver
102 * @ctx: The TEE context for shared memory allocation
103 * @size: Shared memory allocation size
104 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
105 */
106 struct tee_shm *tee_shm_alloc_kernel_buf(struct tee_context *ctx, size_t size);
107
108 /**
109 * tee_shm_register_kernel_buf() - Register kernel shared memory for a
110 * particular TEE client driver
111 * @ctx: The TEE context for shared memory registration
112 * @addr: Kernel buffer address
113 * @length: Kernel buffer length
114 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
115 */
116 struct tee_shm *tee_shm_register_kernel_buf(struct tee_context *ctx,
117 void *addr, size_t length);
118
119 /**
120 * tee_shm_free() - Free shared memory
121 * @shm: Handle to shared memory to free
122 */
123 void tee_shm_free(struct tee_shm *shm);
124
125 /**
126 * tee_shm_get_va() - Get virtual address of a shared memory plus an offset
127 * @shm: Shared memory handle
128 * @offs: Offset from start of this shared memory
129 * @returns virtual address of the shared memory + offs if offs is within
130 * the bounds of this shared memory, else an ERR_PTR
131 */
132 void *tee_shm_get_va(struct tee_shm *shm, size_t offs);
133
134 /**
135 * tee_shm_get_pa() - Get physical address of a shared memory plus an offset
136 * @shm: Shared memory handle
137 * @offs: Offset from start of this shared memory
138 * @pa: Physical address to return
139 * @returns 0 if offs is within the bounds of this shared memory, else an
140 * error code.
141 */
142 int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa);
143
144 /**
145 * tee_shm_get_size() - Get size of shared memory buffer
146 * @shm: Shared memory handle
147 * @returns size of shared memory
148 */
tee_shm_get_size(struct tee_shm * shm)149 static inline size_t tee_shm_get_size(struct tee_shm *shm)
150 {
151 return shm->size;
152 }
153
154 /**
155 * tee_shm_get_pages() - Get list of pages that hold shared buffer
156 * @shm: Shared memory handle
157 * @num_pages: Number of pages will be stored there
158 * @returns pointer to pages array
159 */
tee_shm_get_pages(struct tee_shm * shm,size_t * num_pages)160 static inline struct page **tee_shm_get_pages(struct tee_shm *shm,
161 size_t *num_pages)
162 {
163 *num_pages = shm->num_pages;
164 return shm->pages;
165 }
166
167 /**
168 * tee_shm_get_page_offset() - Get shared buffer offset from page start
169 * @shm: Shared memory handle
170 * @returns page offset of shared buffer
171 */
tee_shm_get_page_offset(struct tee_shm * shm)172 static inline size_t tee_shm_get_page_offset(struct tee_shm *shm)
173 {
174 return shm->offset;
175 }
176
177 /**
178 * tee_client_open_context() - Open a TEE context
179 * @start: if not NULL, continue search after this context
180 * @match: function to check TEE device
181 * @data: data for match function
182 * @vers: if not NULL, version data of TEE device of the context returned
183 *
184 * This function does an operation similar to open("/dev/teeX") in user space.
185 * A returned context must be released with tee_client_close_context().
186 *
187 * Returns a TEE context of the first TEE device matched by the match()
188 * callback or an ERR_PTR.
189 */
190 struct tee_context *
191 tee_client_open_context(struct tee_context *start,
192 int (*match)(struct tee_ioctl_version_data *,
193 const void *),
194 const void *data, struct tee_ioctl_version_data *vers);
195
196 /**
197 * tee_client_close_context() - Close a TEE context
198 * @ctx: TEE context to close
199 *
200 * Note that all sessions previously opened with this context will be
201 * closed when this function is called.
202 */
203 void tee_client_close_context(struct tee_context *ctx);
204
205 /**
206 * tee_client_get_version() - Query version of TEE
207 * @ctx: TEE context to TEE to query
208 * @vers: Pointer to version data
209 */
210 void tee_client_get_version(struct tee_context *ctx,
211 struct tee_ioctl_version_data *vers);
212
213 /**
214 * tee_client_open_session() - Open a session to a Trusted Application
215 * @ctx: TEE context
216 * @arg: Open session arguments, see description of
217 * struct tee_ioctl_open_session_arg
218 * @param: Parameters passed to the Trusted Application
219 *
220 * Returns < 0 on error else see @arg->ret for result. If @arg->ret
221 * is TEEC_SUCCESS the session identifier is available in @arg->session.
222 */
223 int tee_client_open_session(struct tee_context *ctx,
224 struct tee_ioctl_open_session_arg *arg,
225 struct tee_param *param);
226
227 /**
228 * tee_client_close_session() - Close a session to a Trusted Application
229 * @ctx: TEE Context
230 * @session: Session id
231 *
232 * Return < 0 on error else 0, regardless the session will not be
233 * valid after this function has returned.
234 */
235 int tee_client_close_session(struct tee_context *ctx, u32 session);
236
237 /**
238 * tee_client_system_session() - Declare session as a system session
239 * @ctx: TEE Context
240 * @session: Session id
241 *
242 * This function requests TEE to provision an entry context ready to use for
243 * that session only. The provisioned entry context is used for command
244 * invocation and session closure, not for command cancelling requests.
245 * TEE releases the provisioned context upon session closure.
246 *
247 * Return < 0 on error else 0 if an entry context has been provisioned.
248 */
249 int tee_client_system_session(struct tee_context *ctx, u32 session);
250
251 /**
252 * tee_client_invoke_func() - Invoke a function in a Trusted Application
253 * @ctx: TEE Context
254 * @arg: Invoke arguments, see description of
255 * struct tee_ioctl_invoke_arg
256 * @param: Parameters passed to the Trusted Application
257 *
258 * Returns < 0 on error else see @arg->ret for result.
259 */
260 int tee_client_invoke_func(struct tee_context *ctx,
261 struct tee_ioctl_invoke_arg *arg,
262 struct tee_param *param);
263
264 /**
265 * tee_client_cancel_req() - Request cancellation of the previous open-session
266 * or invoke-command operations in a Trusted Application
267 * @ctx: TEE Context
268 * @arg: Cancellation arguments, see description of
269 * struct tee_ioctl_cancel_arg
270 *
271 * Returns < 0 on error else 0 if the cancellation was successfully requested.
272 */
273 int tee_client_cancel_req(struct tee_context *ctx,
274 struct tee_ioctl_cancel_arg *arg);
275
276 extern const struct bus_type tee_bus_type;
277
278 /**
279 * struct tee_client_device - tee based device
280 * @id: device identifier
281 * @dev: device structure
282 */
283 struct tee_client_device {
284 struct tee_client_device_id id;
285 struct device dev;
286 };
287
288 #define to_tee_client_device(d) container_of(d, struct tee_client_device, dev)
289
290 /**
291 * struct tee_client_driver - tee client driver
292 * @id_table: device id table supported by this driver
293 * @driver: driver structure
294 */
295 struct tee_client_driver {
296 const struct tee_client_device_id *id_table;
297 struct device_driver driver;
298 };
299
300 #define to_tee_client_driver(d) \
301 container_of_const(d, struct tee_client_driver, driver)
302
303 #endif /*__TEE_DRV_H*/
304