1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * Copyright (c) 2015-2016, Linaro Limited 4 */ 5 6 #ifndef __TEE_DRV_H 7 #define __TEE_DRV_H 8 9 #include <linux/device.h> 10 #include <linux/idr.h> 11 #include <linux/kref.h> 12 #include <linux/list.h> 13 #include <linux/mod_devicetable.h> 14 #include <linux/tee.h> 15 #include <linux/types.h> 16 #include <linux/uuid.h> 17 18 /* 19 * The file describes the API provided by the generic TEE driver to the 20 * specific TEE driver. 21 */ 22 23 #define TEE_SHM_MAPPED BIT(0) /* Memory mapped by the kernel */ 24 #define TEE_SHM_DMA_BUF BIT(1) /* Memory with dma-buf handle */ 25 #define TEE_SHM_EXT_DMA_BUF BIT(2) /* Memory with dma-buf handle */ 26 #define TEE_SHM_REGISTER BIT(3) /* Memory registered in secure world */ 27 #define TEE_SHM_USER_MAPPED BIT(4) /* Memory mapped in user space */ 28 #define TEE_SHM_POOL BIT(5) /* Memory allocated from pool */ 29 30 struct device; 31 struct tee_device; 32 struct tee_shm; 33 struct tee_shm_pool; 34 35 /** 36 * struct tee_context - driver specific context on file pointer data 37 * @teedev: pointer to this drivers struct tee_device 38 * @list_shm: List of shared memory object owned by this context 39 * @data: driver specific context data, managed by the driver 40 * @refcount: reference counter for this structure 41 * @releasing: flag that indicates if context is being released right now. 42 * It is needed to break circular dependency on context during 43 * shared memory release. 44 * @supp_nowait: flag that indicates that requests in this context should not 45 * wait for tee-supplicant daemon to be started if not present 46 * and just return with an error code. It is needed for requests 47 * that arises from TEE based kernel drivers that should be 48 * non-blocking in nature. 49 */ 50 struct tee_context { 51 struct tee_device *teedev; 52 void *data; 53 struct kref refcount; 54 bool releasing; 55 bool supp_nowait; 56 }; 57 58 struct tee_param_memref { 59 size_t shm_offs; 60 size_t size; 61 struct tee_shm *shm; 62 }; 63 64 struct tee_param_value { 65 u64 a; 66 u64 b; 67 u64 c; 68 }; 69 70 struct tee_param { 71 u64 attr; 72 union { 73 struct tee_param_memref memref; 74 struct tee_param_value value; 75 } u; 76 }; 77 78 /** 79 * struct tee_driver_ops - driver operations vtable 80 * @get_version: returns version of driver 81 * @open: called when the device file is opened 82 * @release: release this open file 83 * @open_session: open a new session 84 * @close_session: close a session 85 * @invoke_func: invoke a trusted function 86 * @cancel_req: request cancel of an ongoing invoke or open 87 * @supp_revc: called for supplicant to get a command 88 * @supp_send: called for supplicant to send a response 89 * @shm_register: register shared memory buffer in TEE 90 * @shm_unregister: unregister shared memory buffer in TEE 91 */ 92 struct tee_driver_ops { 93 void (*get_version)(struct tee_device *teedev, 94 struct tee_ioctl_version_data *vers); 95 int (*open)(struct tee_context *ctx); 96 void (*release)(struct tee_context *ctx); 97 int (*open_session)(struct tee_context *ctx, 98 struct tee_ioctl_open_session_arg *arg, 99 struct tee_param *param); 100 int (*close_session)(struct tee_context *ctx, u32 session); 101 int (*invoke_func)(struct tee_context *ctx, 102 struct tee_ioctl_invoke_arg *arg, 103 struct tee_param *param); 104 int (*cancel_req)(struct tee_context *ctx, u32 cancel_id, u32 session); 105 int (*supp_recv)(struct tee_context *ctx, u32 *func, u32 *num_params, 106 struct tee_param *param); 107 int (*supp_send)(struct tee_context *ctx, u32 ret, u32 num_params, 108 struct tee_param *param); 109 int (*shm_register)(struct tee_context *ctx, struct tee_shm *shm, 110 struct page **pages, size_t num_pages, 111 unsigned long start); 112 int (*shm_unregister)(struct tee_context *ctx, struct tee_shm *shm); 113 }; 114 115 /** 116 * struct tee_desc - Describes the TEE driver to the subsystem 117 * @name: name of driver 118 * @ops: driver operations vtable 119 * @owner: module providing the driver 120 * @flags: Extra properties of driver, defined by TEE_DESC_* below 121 */ 122 #define TEE_DESC_PRIVILEGED 0x1 123 struct tee_desc { 124 const char *name; 125 const struct tee_driver_ops *ops; 126 struct module *owner; 127 u32 flags; 128 }; 129 130 /** 131 * tee_device_alloc() - Allocate a new struct tee_device instance 132 * @teedesc: Descriptor for this driver 133 * @dev: Parent device for this device 134 * @pool: Shared memory pool, NULL if not used 135 * @driver_data: Private driver data for this device 136 * 137 * Allocates a new struct tee_device instance. The device is 138 * removed by tee_device_unregister(). 139 * 140 * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure 141 */ 142 struct tee_device *tee_device_alloc(const struct tee_desc *teedesc, 143 struct device *dev, 144 struct tee_shm_pool *pool, 145 void *driver_data); 146 147 /** 148 * tee_device_register() - Registers a TEE device 149 * @teedev: Device to register 150 * 151 * tee_device_unregister() need to be called to remove the @teedev if 152 * this function fails. 153 * 154 * @returns < 0 on failure 155 */ 156 int tee_device_register(struct tee_device *teedev); 157 158 /** 159 * tee_device_unregister() - Removes a TEE device 160 * @teedev: Device to unregister 161 * 162 * This function should be called to remove the @teedev even if 163 * tee_device_register() hasn't been called yet. Does nothing if 164 * @teedev is NULL. 165 */ 166 void tee_device_unregister(struct tee_device *teedev); 167 168 /** 169 * struct tee_shm - shared memory object 170 * @teedev: device used to allocate the object 171 * @ctx: context using the object, if NULL the context is gone 172 * @paddr: physical address of the shared memory 173 * @kaddr: virtual address of the shared memory 174 * @size: size of shared memory 175 * @offset: offset of buffer in user space 176 * @pages: locked pages from userspace 177 * @num_pages: number of locked pages 178 * @dmabuf: dmabuf used to for exporting to user space 179 * @flags: defined by TEE_SHM_* in tee_drv.h 180 * @id: unique id of a shared memory object on this device 181 * 182 * This pool is only supposed to be accessed directly from the TEE 183 * subsystem and from drivers that implements their own shm pool manager. 184 */ 185 struct tee_shm { 186 struct tee_device *teedev; 187 struct tee_context *ctx; 188 phys_addr_t paddr; 189 void *kaddr; 190 size_t size; 191 unsigned int offset; 192 struct page **pages; 193 size_t num_pages; 194 struct dma_buf *dmabuf; 195 u32 flags; 196 int id; 197 }; 198 199 /** 200 * struct tee_shm_pool_mgr - shared memory manager 201 * @ops: operations 202 * @private_data: private data for the shared memory manager 203 */ 204 struct tee_shm_pool_mgr { 205 const struct tee_shm_pool_mgr_ops *ops; 206 void *private_data; 207 }; 208 209 /** 210 * struct tee_shm_pool_mgr_ops - shared memory pool manager operations 211 * @alloc: called when allocating shared memory 212 * @free: called when freeing shared memory 213 * @destroy_poolmgr: called when destroying the pool manager 214 */ 215 struct tee_shm_pool_mgr_ops { 216 int (*alloc)(struct tee_shm_pool_mgr *poolmgr, struct tee_shm *shm, 217 size_t size); 218 void (*free)(struct tee_shm_pool_mgr *poolmgr, struct tee_shm *shm); 219 void (*destroy_poolmgr)(struct tee_shm_pool_mgr *poolmgr); 220 }; 221 222 /** 223 * tee_shm_pool_alloc() - Create a shared memory pool from shm managers 224 * @priv_mgr: manager for driver private shared memory allocations 225 * @dmabuf_mgr: manager for dma-buf shared memory allocations 226 * 227 * Allocation with the flag TEE_SHM_DMA_BUF set will use the range supplied 228 * in @dmabuf, others will use the range provided by @priv. 229 * 230 * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure. 231 */ 232 struct tee_shm_pool *tee_shm_pool_alloc(struct tee_shm_pool_mgr *priv_mgr, 233 struct tee_shm_pool_mgr *dmabuf_mgr); 234 235 /* 236 * tee_shm_pool_mgr_alloc_res_mem() - Create a shm manager for reserved 237 * memory 238 * @vaddr: Virtual address of start of pool 239 * @paddr: Physical address of start of pool 240 * @size: Size in bytes of the pool 241 * 242 * @returns pointer to a 'struct tee_shm_pool_mgr' or an ERR_PTR on failure. 243 */ 244 struct tee_shm_pool_mgr *tee_shm_pool_mgr_alloc_res_mem(unsigned long vaddr, 245 phys_addr_t paddr, 246 size_t size, 247 int min_alloc_order); 248 249 /** 250 * tee_shm_pool_mgr_destroy() - Free a shared memory manager 251 */ 252 static inline void tee_shm_pool_mgr_destroy(struct tee_shm_pool_mgr *poolm) 253 { 254 poolm->ops->destroy_poolmgr(poolm); 255 } 256 257 /** 258 * struct tee_shm_pool_mem_info - holds information needed to create a shared 259 * memory pool 260 * @vaddr: Virtual address of start of pool 261 * @paddr: Physical address of start of pool 262 * @size: Size in bytes of the pool 263 */ 264 struct tee_shm_pool_mem_info { 265 unsigned long vaddr; 266 phys_addr_t paddr; 267 size_t size; 268 }; 269 270 /** 271 * tee_shm_pool_alloc_res_mem() - Create a shared memory pool from reserved 272 * memory range 273 * @priv_info: Information for driver private shared memory pool 274 * @dmabuf_info: Information for dma-buf shared memory pool 275 * 276 * Start and end of pools will must be page aligned. 277 * 278 * Allocation with the flag TEE_SHM_DMA_BUF set will use the range supplied 279 * in @dmabuf, others will use the range provided by @priv. 280 * 281 * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure. 282 */ 283 struct tee_shm_pool * 284 tee_shm_pool_alloc_res_mem(struct tee_shm_pool_mem_info *priv_info, 285 struct tee_shm_pool_mem_info *dmabuf_info); 286 287 /** 288 * tee_shm_pool_free() - Free a shared memory pool 289 * @pool: The shared memory pool to free 290 * 291 * The must be no remaining shared memory allocated from this pool when 292 * this function is called. 293 */ 294 void tee_shm_pool_free(struct tee_shm_pool *pool); 295 296 /** 297 * tee_get_drvdata() - Return driver_data pointer 298 * @returns the driver_data pointer supplied to tee_register(). 299 */ 300 void *tee_get_drvdata(struct tee_device *teedev); 301 302 /** 303 * tee_shm_alloc() - Allocate shared memory 304 * @ctx: Context that allocates the shared memory 305 * @size: Requested size of shared memory 306 * @flags: Flags setting properties for the requested shared memory. 307 * 308 * Memory allocated as global shared memory is automatically freed when the 309 * TEE file pointer is closed. The @flags field uses the bits defined by 310 * TEE_SHM_* above. TEE_SHM_MAPPED must currently always be set. If 311 * TEE_SHM_DMA_BUF global shared memory will be allocated and associated 312 * with a dma-buf handle, else driver private memory. 313 * 314 * @returns a pointer to 'struct tee_shm' 315 */ 316 struct tee_shm *tee_shm_alloc(struct tee_context *ctx, size_t size, u32 flags); 317 318 /** 319 * tee_shm_priv_alloc() - Allocate shared memory privately 320 * @dev: Device that allocates the shared memory 321 * @size: Requested size of shared memory 322 * 323 * Allocates shared memory buffer that is not associated with any client 324 * context. Such buffers are owned by TEE driver and used for internal calls. 325 * 326 * @returns a pointer to 'struct tee_shm' 327 */ 328 struct tee_shm *tee_shm_priv_alloc(struct tee_device *teedev, size_t size); 329 330 /** 331 * tee_shm_register() - Register shared memory buffer 332 * @ctx: Context that registers the shared memory 333 * @addr: Address is userspace of the shared buffer 334 * @length: Length of the shared buffer 335 * @flags: Flags setting properties for the requested shared memory. 336 * 337 * @returns a pointer to 'struct tee_shm' 338 */ 339 struct tee_shm *tee_shm_register(struct tee_context *ctx, unsigned long addr, 340 size_t length, u32 flags); 341 342 /** 343 * tee_shm_is_registered() - Check if shared memory object in registered in TEE 344 * @shm: Shared memory handle 345 * @returns true if object is registered in TEE 346 */ 347 static inline bool tee_shm_is_registered(struct tee_shm *shm) 348 { 349 return shm && (shm->flags & TEE_SHM_REGISTER); 350 } 351 352 /** 353 * tee_shm_free() - Free shared memory 354 * @shm: Handle to shared memory to free 355 */ 356 void tee_shm_free(struct tee_shm *shm); 357 358 /** 359 * tee_shm_put() - Decrease reference count on a shared memory handle 360 * @shm: Shared memory handle 361 */ 362 void tee_shm_put(struct tee_shm *shm); 363 364 /** 365 * tee_shm_va2pa() - Get physical address of a virtual address 366 * @shm: Shared memory handle 367 * @va: Virtual address to tranlsate 368 * @pa: Returned physical address 369 * @returns 0 on success and < 0 on failure 370 */ 371 int tee_shm_va2pa(struct tee_shm *shm, void *va, phys_addr_t *pa); 372 373 /** 374 * tee_shm_pa2va() - Get virtual address of a physical address 375 * @shm: Shared memory handle 376 * @pa: Physical address to tranlsate 377 * @va: Returned virtual address 378 * @returns 0 on success and < 0 on failure 379 */ 380 int tee_shm_pa2va(struct tee_shm *shm, phys_addr_t pa, void **va); 381 382 /** 383 * tee_shm_get_va() - Get virtual address of a shared memory plus an offset 384 * @shm: Shared memory handle 385 * @offs: Offset from start of this shared memory 386 * @returns virtual address of the shared memory + offs if offs is within 387 * the bounds of this shared memory, else an ERR_PTR 388 */ 389 void *tee_shm_get_va(struct tee_shm *shm, size_t offs); 390 391 /** 392 * tee_shm_get_pa() - Get physical address of a shared memory plus an offset 393 * @shm: Shared memory handle 394 * @offs: Offset from start of this shared memory 395 * @pa: Physical address to return 396 * @returns 0 if offs is within the bounds of this shared memory, else an 397 * error code. 398 */ 399 int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa); 400 401 /** 402 * tee_shm_get_size() - Get size of shared memory buffer 403 * @shm: Shared memory handle 404 * @returns size of shared memory 405 */ 406 static inline size_t tee_shm_get_size(struct tee_shm *shm) 407 { 408 return shm->size; 409 } 410 411 /** 412 * tee_shm_get_pages() - Get list of pages that hold shared buffer 413 * @shm: Shared memory handle 414 * @num_pages: Number of pages will be stored there 415 * @returns pointer to pages array 416 */ 417 static inline struct page **tee_shm_get_pages(struct tee_shm *shm, 418 size_t *num_pages) 419 { 420 *num_pages = shm->num_pages; 421 return shm->pages; 422 } 423 424 /** 425 * tee_shm_get_page_offset() - Get shared buffer offset from page start 426 * @shm: Shared memory handle 427 * @returns page offset of shared buffer 428 */ 429 static inline size_t tee_shm_get_page_offset(struct tee_shm *shm) 430 { 431 return shm->offset; 432 } 433 434 /** 435 * tee_shm_get_id() - Get id of a shared memory object 436 * @shm: Shared memory handle 437 * @returns id 438 */ 439 static inline int tee_shm_get_id(struct tee_shm *shm) 440 { 441 return shm->id; 442 } 443 444 /** 445 * tee_shm_get_from_id() - Find shared memory object and increase reference 446 * count 447 * @ctx: Context owning the shared memory 448 * @id: Id of shared memory object 449 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure 450 */ 451 struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id); 452 453 /** 454 * tee_client_open_context() - Open a TEE context 455 * @start: if not NULL, continue search after this context 456 * @match: function to check TEE device 457 * @data: data for match function 458 * @vers: if not NULL, version data of TEE device of the context returned 459 * 460 * This function does an operation similar to open("/dev/teeX") in user space. 461 * A returned context must be released with tee_client_close_context(). 462 * 463 * Returns a TEE context of the first TEE device matched by the match() 464 * callback or an ERR_PTR. 465 */ 466 struct tee_context * 467 tee_client_open_context(struct tee_context *start, 468 int (*match)(struct tee_ioctl_version_data *, 469 const void *), 470 const void *data, struct tee_ioctl_version_data *vers); 471 472 /** 473 * tee_client_close_context() - Close a TEE context 474 * @ctx: TEE context to close 475 * 476 * Note that all sessions previously opened with this context will be 477 * closed when this function is called. 478 */ 479 void tee_client_close_context(struct tee_context *ctx); 480 481 /** 482 * tee_client_get_version() - Query version of TEE 483 * @ctx: TEE context to TEE to query 484 * @vers: Pointer to version data 485 */ 486 void tee_client_get_version(struct tee_context *ctx, 487 struct tee_ioctl_version_data *vers); 488 489 /** 490 * tee_client_open_session() - Open a session to a Trusted Application 491 * @ctx: TEE context 492 * @arg: Open session arguments, see description of 493 * struct tee_ioctl_open_session_arg 494 * @param: Parameters passed to the Trusted Application 495 * 496 * Returns < 0 on error else see @arg->ret for result. If @arg->ret 497 * is TEEC_SUCCESS the session identifier is available in @arg->session. 498 */ 499 int tee_client_open_session(struct tee_context *ctx, 500 struct tee_ioctl_open_session_arg *arg, 501 struct tee_param *param); 502 503 /** 504 * tee_client_close_session() - Close a session to a Trusted Application 505 * @ctx: TEE Context 506 * @session: Session id 507 * 508 * Return < 0 on error else 0, regardless the session will not be 509 * valid after this function has returned. 510 */ 511 int tee_client_close_session(struct tee_context *ctx, u32 session); 512 513 /** 514 * tee_client_invoke_func() - Invoke a function in a Trusted Application 515 * @ctx: TEE Context 516 * @arg: Invoke arguments, see description of 517 * struct tee_ioctl_invoke_arg 518 * @param: Parameters passed to the Trusted Application 519 * 520 * Returns < 0 on error else see @arg->ret for result. 521 */ 522 int tee_client_invoke_func(struct tee_context *ctx, 523 struct tee_ioctl_invoke_arg *arg, 524 struct tee_param *param); 525 526 /** 527 * tee_client_cancel_req() - Request cancellation of the previous open-session 528 * or invoke-command operations in a Trusted Application 529 * @ctx: TEE Context 530 * @arg: Cancellation arguments, see description of 531 * struct tee_ioctl_cancel_arg 532 * 533 * Returns < 0 on error else 0 if the cancellation was successfully requested. 534 */ 535 int tee_client_cancel_req(struct tee_context *ctx, 536 struct tee_ioctl_cancel_arg *arg); 537 538 static inline bool tee_param_is_memref(struct tee_param *param) 539 { 540 switch (param->attr & TEE_IOCTL_PARAM_ATTR_TYPE_MASK) { 541 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT: 542 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT: 543 case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT: 544 return true; 545 default: 546 return false; 547 } 548 } 549 550 extern struct bus_type tee_bus_type; 551 552 /** 553 * struct tee_client_device - tee based device 554 * @id: device identifier 555 * @dev: device structure 556 */ 557 struct tee_client_device { 558 struct tee_client_device_id id; 559 struct device dev; 560 }; 561 562 #define to_tee_client_device(d) container_of(d, struct tee_client_device, dev) 563 564 /** 565 * struct tee_client_driver - tee client driver 566 * @id_table: device id table supported by this driver 567 * @driver: driver structure 568 */ 569 struct tee_client_driver { 570 const struct tee_client_device_id *id_table; 571 struct device_driver driver; 572 }; 573 574 #define to_tee_client_driver(d) \ 575 container_of(d, struct tee_client_driver, driver) 576 577 #endif /*__TEE_DRV_H*/ 578