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 38 enum 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 */ 59 struct 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 */ 98 struct 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 134 struct 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 */ 148 struct 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 */ 161 struct 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 */ 183 struct 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 */ 197 int 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 */ 207 void tee_device_unregister(struct tee_device *teedev); 208 209 int tee_device_register_dma_heap(struct tee_device *teedev, 210 enum tee_dma_heap_id id, 211 struct tee_protmem_pool *pool); 212 void 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 */ 224 bool 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 */ 230 void 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 */ 241 void 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 */ 257 int 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 */ 265 struct 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 */ 276 struct 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 */ 291 struct 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 */ 302 static 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 */ 314 struct 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 */ 321 void *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 */ 330 struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size); 331 332 struct tee_shm *tee_shm_alloc_dma_mem(struct tee_context *ctx, 333 size_t page_count); 334 335 int 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)); 341 void 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 */ 350 static 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 */ 359 void 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 */ 366 static 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 */ 378 struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id); 379 380 static 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 */ 398 struct 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 */ 404 void 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 */ 419 void 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 */ 425 void teedev_ctx_put(struct tee_context *ctx); 426 427 #endif /*__TEE_CORE_H*/ 428