tee_core.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * Copyright (c) 2024 Linaro Limited
  4 */
  5
  6#ifndef __TEE_CORE_H
  7#define __TEE_CORE_H
  8
  9#include <linux/cdev.h>
 10#include <linux/device.h>
 11#include <linux/dma-buf.h>
 12#include <linux/idr.h>
 13#include <linux/kref.h>
 14#include <linux/list.h>
 15#include <linux/scatterlist.h>
 16#include <linux/tee.h>
 17#include <linux/tee_drv.h>
 18#include <linux/types.h>
 19#include <linux/uuid.h>
 20
 21/*
 22 * The file describes the API provided by the generic TEE driver to the
 23 * specific TEE driver.
 24 */
 25
 26#define TEE_SHM_DYNAMIC		BIT(0)  /* Dynamic shared memory registered */
 27					/* in secure world */
 28#define TEE_SHM_USER_MAPPED	BIT(1)  /* Memory mapped in user space */
 29#define TEE_SHM_POOL		BIT(2)  /* Memory allocated from pool */
 30#define TEE_SHM_PRIV		BIT(3)  /* Memory private to TEE driver */
 31#define TEE_SHM_DMA_BUF		BIT(4)	/* Memory with dma-buf handle */
 32#define TEE_SHM_DMA_MEM		BIT(5)	/* Memory allocated with */
 33					/* dma_alloc_pages() */
 34
 35#define TEE_DEVICE_FLAG_REGISTERED	0x1
 36#define TEE_MAX_DEV_NAME_LEN		32
 37
 38enum tee_dma_heap_id {
 39	TEE_DMA_HEAP_SECURE_VIDEO_PLAY = 1,
 40	TEE_DMA_HEAP_TRUSTED_UI,
 41	TEE_DMA_HEAP_SECURE_VIDEO_RECORD,
 42};
 43
 44/**
 45 * struct tee_device - TEE Device representation
 46 * @name:	name of device
 47 * @desc:	description of device
 48 * @id:		unique id of device
 49 * @flags:	represented by TEE_DEVICE_FLAG_REGISTERED above
 50 * @dev:	embedded basic device structure
 51 * @cdev:	embedded cdev
 52 * @num_users:	number of active users of this device
 53 * @c_no_user:	completion used when unregistering the device
 54 * @mutex:	mutex protecting @num_users and @idr
 55 * @idr:	register of user space shared memory objects allocated or
 56 *		registered on this device
 57 * @pool:	shared memory pool
 58 */
 59struct tee_device {
 60	char name[TEE_MAX_DEV_NAME_LEN];
 61	const struct tee_desc *desc;
 62	int id;
 63	unsigned int flags;
 64
 65	struct device dev;
 66	struct cdev cdev;
 67
 68	size_t num_users;
 69	struct completion c_no_users;
 70	struct mutex mutex;	/* protects num_users and idr */
 71
 72	struct idr idr;
 73	struct tee_shm_pool *pool;
 74};
 75
 76/**
 77 * struct tee_driver_ops - driver operations vtable
 78 * @get_version:	returns version of driver
 79 * @open:		called for a context when the device file is opened
 80 * @close_context:	called when the device file is closed
 81 * @release:		called to release the context
 82 * @open_session:	open a new session
 83 * @close_session:	close a session
 84 * @system_session:	declare session as a system session
 85 * @invoke_func:	invoke a trusted function
 86 * @object_invoke_func:	invoke a TEE object
 87 * @cancel_req:		request cancel of an ongoing invoke or open
 88 * @supp_recv:		called for supplicant to get a command
 89 * @supp_send:		called for supplicant to send a response
 90 * @shm_register:	register shared memory buffer in TEE
 91 * @shm_unregister:	unregister shared memory buffer in TEE
 92 *
 93 * The context given to @open might last longer than the device file if it is
 94 * tied to other resources in the TEE driver. @close_context is called when the
 95 * client closes the device file, even if there are existing references to the
 96 * context. The TEE driver can use @close_context to start cleaning up.
 97 */
 98struct tee_driver_ops {
 99	void (*get_version)(struct tee_device *teedev,
100			    struct tee_ioctl_version_data *vers);
101	int (*open)(struct tee_context *ctx);
102	void (*close_context)(struct tee_context *ctx);
103	void (*release)(struct tee_context *ctx);
104	int (*open_session)(struct tee_context *ctx,
105			    struct tee_ioctl_open_session_arg *arg,
106			    struct tee_param *param);
107	int (*close_session)(struct tee_context *ctx, u32 session);
108	int (*system_session)(struct tee_context *ctx, u32 session);
109	int (*invoke_func)(struct tee_context *ctx,
110			   struct tee_ioctl_invoke_arg *arg,
111			   struct tee_param *param);
112	int (*object_invoke_func)(struct tee_context *ctx,
113				  struct tee_ioctl_object_invoke_arg *arg,
114				  struct tee_param *param);
115	int (*cancel_req)(struct tee_context *ctx, u32 cancel_id, u32 session);
116	int (*supp_recv)(struct tee_context *ctx, u32 *func, u32 *num_params,
117			 struct tee_param *param);
118	int (*supp_send)(struct tee_context *ctx, u32 ret, u32 num_params,
119			 struct tee_param *param);
120	int (*shm_register)(struct tee_context *ctx, struct tee_shm *shm,
121			    struct page **pages, size_t num_pages,
122			    unsigned long start);
123	int (*shm_unregister)(struct tee_context *ctx, struct tee_shm *shm);
124};
125
126/**
127 * struct tee_desc - Describes the TEE driver to the subsystem
128 * @name:	name of driver
129 * @ops:	driver operations vtable
130 * @owner:	module providing the driver
131 * @flags:	Extra properties of driver, defined by TEE_DESC_* below
132 */
133#define TEE_DESC_PRIVILEGED	0x1
134struct tee_desc {
135	const char *name;
136	const struct tee_driver_ops *ops;
137	struct module *owner;
138	u32 flags;
139};
140
141/**
142 * struct tee_protmem_pool - protected memory pool
143 * @ops:		operations
144 *
145 * This is an abstract interface where this struct is expected to be
146 * embedded in another struct specific to the implementation.
147 */
148struct tee_protmem_pool {
149	const struct tee_protmem_pool_ops *ops;
150};
151
152/**
153 * struct tee_protmem_pool_ops - protected memory pool operations
154 * @alloc:		called when allocating protected memory
155 * @free:		called when freeing protected memory
156 * @update_shm:		called when registering a dma-buf to update the @shm
157 *			with physical address of the buffer or to return the
158 *			@parent_shm of the memory pool
159 * @destroy_pool:	called when destroying the pool
160 */
161struct tee_protmem_pool_ops {
162	int (*alloc)(struct tee_protmem_pool *pool, struct sg_table *sgt,
163		     size_t size, size_t *offs);
164	void (*free)(struct tee_protmem_pool *pool, struct sg_table *sgt);
165	int (*update_shm)(struct tee_protmem_pool *pool, struct sg_table *sgt,
166			  size_t offs, struct tee_shm *shm,
167			  struct tee_shm **parent_shm);
168	void (*destroy_pool)(struct tee_protmem_pool *pool);
169};
170
171/**
172 * tee_device_alloc() - Allocate a new struct tee_device instance
173 * @teedesc:	Descriptor for this driver
174 * @dev:	Parent device for this device
175 * @pool:	Shared memory pool, NULL if not used
176 * @driver_data: Private driver data for this device
177 *
178 * Allocates a new struct tee_device instance. The device is
179 * removed by tee_device_unregister().
180 *
181 * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure
182 */
183struct tee_device *tee_device_alloc(const struct tee_desc *teedesc,
184				    struct device *dev,
185				    struct tee_shm_pool *pool,
186				    void *driver_data);
187
188/**
189 * tee_device_register() - Registers a TEE device
190 * @teedev:	Device to register
191 *
192 * tee_device_unregister() need to be called to remove the @teedev if
193 * this function fails.
194 *
195 * @returns < 0 on failure
196 */
197int tee_device_register(struct tee_device *teedev);
198
199/**
200 * tee_device_unregister() - Removes a TEE device
201 * @teedev:	Device to unregister
202 *
203 * This function should be called to remove the @teedev even if
204 * tee_device_register() hasn't been called yet. Does nothing if
205 * @teedev is NULL.
206 */
207void tee_device_unregister(struct tee_device *teedev);
208
209int tee_device_register_dma_heap(struct tee_device *teedev,
210				 enum tee_dma_heap_id id,
211				 struct tee_protmem_pool *pool);
212void tee_device_put_all_dma_heaps(struct tee_device *teedev);
213
214/**
215 * tee_device_get() - Increment the user count for a tee_device
216 * @teedev: Pointer to the tee_device
217 *
218 * If tee_device_unregister() has been called and the final user of @teedev
219 * has already released the device, this function will fail to prevent new users
220 * from accessing the device during the unregistration process.
221 *
222 * Returns: true if @teedev remains valid, otherwise false
223 */
224bool tee_device_get(struct tee_device *teedev);
225
226/**
227 * tee_device_put() - Decrease the user count for a tee_device
228 * @teedev: pointer to the tee_device
229 */
230void tee_device_put(struct tee_device *teedev);
231
232/**
233 * tee_device_set_dev_groups() - Set device attribute groups
234 * @teedev:	Device to register
235 * @dev_groups: Attribute groups
236 *
237 * Assigns the provided @dev_groups to the @teedev to be registered later
238 * with tee_device_register(). Calling this function is optional, but if
239 * it's called it must be called before tee_device_register().
240 */
241void tee_device_set_dev_groups(struct tee_device *teedev,
242			       const struct attribute_group **dev_groups);
243
244/**
245 * tee_session_calc_client_uuid() - Calculates client UUID for session
246 * @uuid:		Resulting UUID
247 * @connection_method:	Connection method for session (TEE_IOCTL_LOGIN_*)
248 * @connectuon_data:	Connection data for opening session
249 *
250 * Based on connection method calculates UUIDv5 based client UUID.
251 *
252 * For group based logins verifies that calling process has specified
253 * credentials.
254 *
255 * @return < 0 on failure
256 */
257int tee_session_calc_client_uuid(uuid_t *uuid, u32 connection_method,
258				 const u8 connection_data[TEE_IOCTL_UUID_LEN]);
259
260/**
261 * struct tee_shm_pool - shared memory pool
262 * @ops:		operations
263 * @private_data:	private data for the shared memory manager
264 */
265struct tee_shm_pool {
266	const struct tee_shm_pool_ops *ops;
267	void *private_data;
268};
269
270/**
271 * struct tee_shm_pool_ops - shared memory pool operations
272 * @alloc:		called when allocating shared memory
273 * @free:		called when freeing shared memory
274 * @destroy_pool:	called when destroying the pool
275 */
276struct tee_shm_pool_ops {
277	int (*alloc)(struct tee_shm_pool *pool, struct tee_shm *shm,
278		     size_t size, size_t align);
279	void (*free)(struct tee_shm_pool *pool, struct tee_shm *shm);
280	void (*destroy_pool)(struct tee_shm_pool *pool);
281};
282
283/*
284 * tee_shm_pool_alloc_res_mem() - Create a shm manager for reserved memory
285 * @vaddr:	Virtual address of start of pool
286 * @paddr:	Physical address of start of pool
287 * @size:	Size in bytes of the pool
288 *
289 * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
290 */
291struct tee_shm_pool *tee_shm_pool_alloc_res_mem(unsigned long vaddr,
292						phys_addr_t paddr, size_t size,
293						int min_alloc_order);
294
295/**
296 * tee_shm_pool_free() - Free a shared memory pool
297 * @pool:	The shared memory pool to free
298 *
299 * The must be no remaining shared memory allocated from this pool when
300 * this function is called.
301 */
302static inline void tee_shm_pool_free(struct tee_shm_pool *pool)
303{
304	pool->ops->destroy_pool(pool);
305}
306
307/**
308 * tee_protmem_static_pool_alloc() - Create a protected memory manager
309 * @paddr:	Physical address of start of pool
310 * @size:	Size in bytes of the pool
311 *
312 * @returns pointer to a 'struct tee_protmem_pool' or an ERR_PTR on failure.
313 */
314struct tee_protmem_pool *tee_protmem_static_pool_alloc(phys_addr_t paddr,
315						       size_t size);
316
317/**
318 * tee_get_drvdata() - Return driver_data pointer
319 * @returns the driver_data pointer supplied to tee_register().
320 */
321void *tee_get_drvdata(struct tee_device *teedev);
322
323/**
324 * tee_shm_alloc_priv_buf() - Allocate shared memory for private use by specific
325 *                            TEE driver
326 * @ctx:	The TEE context for shared memory allocation
327 * @size:	Shared memory allocation size
328 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
329 */
330struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size);
331
332struct tee_shm *tee_shm_alloc_dma_mem(struct tee_context *ctx,
333				      size_t page_count);
334
335int tee_dyn_shm_alloc_helper(struct tee_shm *shm, size_t size, size_t align,
336			     int (*shm_register)(struct tee_context *ctx,
337						 struct tee_shm *shm,
338						 struct page **pages,
339						 size_t num_pages,
340						 unsigned long start));
341void tee_dyn_shm_free_helper(struct tee_shm *shm,
342			     int (*shm_unregister)(struct tee_context *ctx,
343						   struct tee_shm *shm));
344
345/**
346 * tee_shm_is_dynamic() - Check if shared memory object is of the dynamic kind
347 * @shm:	Shared memory handle
348 * @returns true if object is dynamic shared memory
349 */
350static inline bool tee_shm_is_dynamic(struct tee_shm *shm)
351{
352	return shm && (shm->flags & TEE_SHM_DYNAMIC);
353}
354
355/**
356 * tee_shm_put() - Decrease reference count on a shared memory handle
357 * @shm:	Shared memory handle
358 */
359void tee_shm_put(struct tee_shm *shm);
360
361/**
362 * tee_shm_get_id() - Get id of a shared memory object
363 * @shm:	Shared memory handle
364 * @returns id
365 */
366static inline int tee_shm_get_id(struct tee_shm *shm)
367{
368	return shm->id;
369}
370
371/**
372 * tee_shm_get_from_id() - Find shared memory object and increase reference
373 * count
374 * @ctx:	Context owning the shared memory
375 * @id:		Id of shared memory object
376 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
377 */
378struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id);
379
380static inline bool tee_param_is_memref(struct tee_param *param)
381{
382	switch (param->attr & TEE_IOCTL_PARAM_ATTR_TYPE_MASK) {
383	case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT:
384	case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT:
385	case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT:
386		return true;
387	default:
388		return false;
389	}
390}
391
392/**
393 * teedev_open() - Open a struct tee_device
394 * @teedev:	Device to open
395 *
396 * @return a pointer to struct tee_context on success or an ERR_PTR on failure.
397 */
398struct tee_context *teedev_open(struct tee_device *teedev);
399
400/**
401 * teedev_close_context() - closes a struct tee_context
402 * @ctx:	The struct tee_context to close
403 */
404void teedev_close_context(struct tee_context *ctx);
405
406/**
407 * teedev_ctx_get() - Increment the reference count of a context
408 * @ctx: Pointer to the context
409 *
410 * This function increases the refcount of the context, which is tied to
411 * resources shared by the same tee_device. During the unregistration process,
412 * the context may remain valid even after tee_device_unregister() has returned.
413 *
414 * Users should ensure that the context's refcount is properly decreased before
415 * calling tee_device_put(), typically within the context's release() function.
416 * Alternatively, users can call tee_device_get() and teedev_ctx_get() together
417 * and release them simultaneously (see shm_alloc_helper()).
418 */
419void teedev_ctx_get(struct tee_context *ctx);
420
421/**
422 * teedev_ctx_put() - Decrease reference count on a context
423 * @ctx: pointer to the context
424 */
425void teedev_ctx_put(struct tee_context *ctx);
426
427#endif /*__TEE_CORE_H*/