tee_drv.h

  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*/