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/idr.h>
12 #include <linux/kref.h>
13 #include <linux/list.h>
14 #include <linux/tee.h>
15 #include <linux/tee_drv.h>
16 #include <linux/types.h>
17 #include <linux/uuid.h>
18
19 /*
20 * The file describes the API provided by the generic TEE driver to the
21 * specific TEE driver.
22 */
23
24 #define TEE_SHM_DYNAMIC BIT(0) /* Dynamic shared memory registered */
25 /* in secure world */
26 #define TEE_SHM_USER_MAPPED BIT(1) /* Memory mapped in user space */
27 #define TEE_SHM_POOL BIT(2) /* Memory allocated from pool */
28 #define TEE_SHM_PRIV BIT(3) /* Memory private to TEE driver */
29
30 #define TEE_DEVICE_FLAG_REGISTERED 0x1
31 #define TEE_MAX_DEV_NAME_LEN 32
32
33 /**
34 * struct tee_device - TEE Device representation
35 * @name: name of device
36 * @desc: description of device
37 * @id: unique id of device
38 * @flags: represented by TEE_DEVICE_FLAG_REGISTERED above
39 * @dev: embedded basic device structure
40 * @cdev: embedded cdev
41 * @num_users: number of active users of this device
42 * @c_no_user: completion used when unregistering the device
43 * @mutex: mutex protecting @num_users and @idr
44 * @idr: register of user space shared memory objects allocated or
45 * registered on this device
46 * @pool: shared memory pool
47 */
48 struct tee_device {
49 char name[TEE_MAX_DEV_NAME_LEN];
50 const struct tee_desc *desc;
51 int id;
52 unsigned int flags;
53
54 struct device dev;
55 struct cdev cdev;
56
57 size_t num_users;
58 struct completion c_no_users;
59 struct mutex mutex; /* protects num_users and idr */
60
61 struct idr idr;
62 struct tee_shm_pool *pool;
63 };
64
65 /**
66 * struct tee_driver_ops - driver operations vtable
67 * @get_version: returns version of driver
68 * @open: called when the device file is opened
69 * @release: release this open file
70 * @open_session: open a new session
71 * @close_session: close a session
72 * @system_session: declare session as a system session
73 * @invoke_func: invoke a trusted function
74 * @cancel_req: request cancel of an ongoing invoke or open
75 * @supp_recv: called for supplicant to get a command
76 * @supp_send: called for supplicant to send a response
77 * @shm_register: register shared memory buffer in TEE
78 * @shm_unregister: unregister shared memory buffer in TEE
79 */
80 struct tee_driver_ops {
81 void (*get_version)(struct tee_device *teedev,
82 struct tee_ioctl_version_data *vers);
83 int (*open)(struct tee_context *ctx);
84 void (*release)(struct tee_context *ctx);
85 int (*open_session)(struct tee_context *ctx,
86 struct tee_ioctl_open_session_arg *arg,
87 struct tee_param *param);
88 int (*close_session)(struct tee_context *ctx, u32 session);
89 int (*system_session)(struct tee_context *ctx, u32 session);
90 int (*invoke_func)(struct tee_context *ctx,
91 struct tee_ioctl_invoke_arg *arg,
92 struct tee_param *param);
93 int (*cancel_req)(struct tee_context *ctx, u32 cancel_id, u32 session);
94 int (*supp_recv)(struct tee_context *ctx, u32 *func, u32 *num_params,
95 struct tee_param *param);
96 int (*supp_send)(struct tee_context *ctx, u32 ret, u32 num_params,
97 struct tee_param *param);
98 int (*shm_register)(struct tee_context *ctx, struct tee_shm *shm,
99 struct page **pages, size_t num_pages,
100 unsigned long start);
101 int (*shm_unregister)(struct tee_context *ctx, struct tee_shm *shm);
102 };
103
104 /**
105 * struct tee_desc - Describes the TEE driver to the subsystem
106 * @name: name of driver
107 * @ops: driver operations vtable
108 * @owner: module providing the driver
109 * @flags: Extra properties of driver, defined by TEE_DESC_* below
110 */
111 #define TEE_DESC_PRIVILEGED 0x1
112 struct tee_desc {
113 const char *name;
114 const struct tee_driver_ops *ops;
115 struct module *owner;
116 u32 flags;
117 };
118
119 /**
120 * tee_device_alloc() - Allocate a new struct tee_device instance
121 * @teedesc: Descriptor for this driver
122 * @dev: Parent device for this device
123 * @pool: Shared memory pool, NULL if not used
124 * @driver_data: Private driver data for this device
125 *
126 * Allocates a new struct tee_device instance. The device is
127 * removed by tee_device_unregister().
128 *
129 * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure
130 */
131 struct tee_device *tee_device_alloc(const struct tee_desc *teedesc,
132 struct device *dev,
133 struct tee_shm_pool *pool,
134 void *driver_data);
135
136 /**
137 * tee_device_register() - Registers a TEE device
138 * @teedev: Device to register
139 *
140 * tee_device_unregister() need to be called to remove the @teedev if
141 * this function fails.
142 *
143 * @returns < 0 on failure
144 */
145 int tee_device_register(struct tee_device *teedev);
146
147 /**
148 * tee_device_unregister() - Removes a TEE device
149 * @teedev: Device to unregister
150 *
151 * This function should be called to remove the @teedev even if
152 * tee_device_register() hasn't been called yet. Does nothing if
153 * @teedev is NULL.
154 */
155 void tee_device_unregister(struct tee_device *teedev);
156
157 /**
158 * tee_device_set_dev_groups() - Set device attribute groups
159 * @teedev: Device to register
160 * @dev_groups: Attribute groups
161 *
162 * Assigns the provided @dev_groups to the @teedev to be registered later
163 * with tee_device_register(). Calling this function is optional, but if
164 * it's called it must be called before tee_device_register().
165 */
166 void tee_device_set_dev_groups(struct tee_device *teedev,
167 const struct attribute_group **dev_groups);
168
169 /**
170 * tee_session_calc_client_uuid() - Calculates client UUID for session
171 * @uuid: Resulting UUID
172 * @connection_method: Connection method for session (TEE_IOCTL_LOGIN_*)
173 * @connectuon_data: Connection data for opening session
174 *
175 * Based on connection method calculates UUIDv5 based client UUID.
176 *
177 * For group based logins verifies that calling process has specified
178 * credentials.
179 *
180 * @return < 0 on failure
181 */
182 int tee_session_calc_client_uuid(uuid_t *uuid, u32 connection_method,
183 const u8 connection_data[TEE_IOCTL_UUID_LEN]);
184
185 /**
186 * struct tee_shm_pool - shared memory pool
187 * @ops: operations
188 * @private_data: private data for the shared memory manager
189 */
190 struct tee_shm_pool {
191 const struct tee_shm_pool_ops *ops;
192 void *private_data;
193 };
194
195 /**
196 * struct tee_shm_pool_ops - shared memory pool operations
197 * @alloc: called when allocating shared memory
198 * @free: called when freeing shared memory
199 * @destroy_pool: called when destroying the pool
200 */
201 struct tee_shm_pool_ops {
202 int (*alloc)(struct tee_shm_pool *pool, struct tee_shm *shm,
203 size_t size, size_t align);
204 void (*free)(struct tee_shm_pool *pool, struct tee_shm *shm);
205 void (*destroy_pool)(struct tee_shm_pool *pool);
206 };
207
208 /*
209 * tee_shm_pool_alloc_res_mem() - Create a shm manager for reserved memory
210 * @vaddr: Virtual address of start of pool
211 * @paddr: Physical address of start of pool
212 * @size: Size in bytes of the pool
213 *
214 * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
215 */
216 struct tee_shm_pool *tee_shm_pool_alloc_res_mem(unsigned long vaddr,
217 phys_addr_t paddr, size_t size,
218 int min_alloc_order);
219
220 /**
221 * tee_shm_pool_free() - Free a shared memory pool
222 * @pool: The shared memory pool to free
223 *
224 * The must be no remaining shared memory allocated from this pool when
225 * this function is called.
226 */
tee_shm_pool_free(struct tee_shm_pool * pool)227 static inline void tee_shm_pool_free(struct tee_shm_pool *pool)
228 {
229 pool->ops->destroy_pool(pool);
230 }
231
232 /**
233 * tee_get_drvdata() - Return driver_data pointer
234 * @returns the driver_data pointer supplied to tee_register().
235 */
236 void *tee_get_drvdata(struct tee_device *teedev);
237
238 /**
239 * tee_shm_alloc_priv_buf() - Allocate shared memory for private use by specific
240 * TEE driver
241 * @ctx: The TEE context for shared memory allocation
242 * @size: Shared memory allocation size
243 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
244 */
245 struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size);
246
247 int tee_dyn_shm_alloc_helper(struct tee_shm *shm, size_t size, size_t align,
248 int (*shm_register)(struct tee_context *ctx,
249 struct tee_shm *shm,
250 struct page **pages,
251 size_t num_pages,
252 unsigned long start));
253 void tee_dyn_shm_free_helper(struct tee_shm *shm,
254 int (*shm_unregister)(struct tee_context *ctx,
255 struct tee_shm *shm));
256
257 /**
258 * tee_shm_is_dynamic() - Check if shared memory object is of the dynamic kind
259 * @shm: Shared memory handle
260 * @returns true if object is dynamic shared memory
261 */
tee_shm_is_dynamic(struct tee_shm * shm)262 static inline bool tee_shm_is_dynamic(struct tee_shm *shm)
263 {
264 return shm && (shm->flags & TEE_SHM_DYNAMIC);
265 }
266
267 /**
268 * tee_shm_put() - Decrease reference count on a shared memory handle
269 * @shm: Shared memory handle
270 */
271 void tee_shm_put(struct tee_shm *shm);
272
273 /**
274 * tee_shm_get_id() - Get id of a shared memory object
275 * @shm: Shared memory handle
276 * @returns id
277 */
tee_shm_get_id(struct tee_shm * shm)278 static inline int tee_shm_get_id(struct tee_shm *shm)
279 {
280 return shm->id;
281 }
282
283 /**
284 * tee_shm_get_from_id() - Find shared memory object and increase reference
285 * count
286 * @ctx: Context owning the shared memory
287 * @id: Id of shared memory object
288 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
289 */
290 struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id);
291
tee_param_is_memref(struct tee_param * param)292 static inline bool tee_param_is_memref(struct tee_param *param)
293 {
294 switch (param->attr & TEE_IOCTL_PARAM_ATTR_TYPE_MASK) {
295 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT:
296 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT:
297 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT:
298 return true;
299 default:
300 return false;
301 }
302 }
303
304 /**
305 * teedev_open() - Open a struct tee_device
306 * @teedev: Device to open
307 *
308 * @return a pointer to struct tee_context on success or an ERR_PTR on failure.
309 */
310 struct tee_context *teedev_open(struct tee_device *teedev);
311
312 /**
313 * teedev_close_context() - closes a struct tee_context
314 * @ctx: The struct tee_context to close
315 */
316 void teedev_close_context(struct tee_context *ctx);
317
318 #endif /*__TEE_CORE_H*/
319