include/linux/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
  21 struct 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  */
  39 struct 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  */
  65 struct 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
  79 struct tee_param_memref {
  80         size_t shm_offs;
  81         size_t size;
  82         struct tee_shm *shm;
  83 };
  84
  85 struct tee_param_value {
  86         u64 a;
  87         u64 b;
  88         u64 c;
  89 };
  90
  91 struct tee_param {
  92         u64 attr;
  93         union {
  94                 struct tee_param_memref memref;
  95                 struct tee_param_value value;
  96         } u;
  97 };
  98
  99 /**
 100  * tee_shm_alloc_kernel_buf() - Allocate kernel shared memory for a
 101  *                              particular TEE client driver
 102  * @ctx:        The TEE context for shared memory allocation
 103  * @size:       Shared memory allocation size
 104  * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
 105  */
 106 struct tee_shm *tee_shm_alloc_kernel_buf(struct tee_context *ctx, size_t size);
 107
 108 /**
 109  * tee_shm_register_kernel_buf() - Register kernel shared memory for a
 110  *                                 particular TEE client driver
 111  * @ctx:        The TEE context for shared memory registration
 112  * @addr:       Kernel buffer address
 113  * @length:     Kernel buffer length
 114  * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
 115  */
 116 struct tee_shm *tee_shm_register_kernel_buf(struct tee_context *ctx,
 117                                             void *addr, size_t length);
 118
 119 /**
 120  * tee_shm_free() - Free shared memory
 121  * @shm:        Handle to shared memory to free
 122  */
 123 void tee_shm_free(struct tee_shm *shm);
 124
 125 /**
 126  * tee_shm_get_va() - Get virtual address of a shared memory plus an offset
 127  * @shm:        Shared memory handle
 128  * @offs:       Offset from start of this shared memory
 129  * @returns virtual address of the shared memory + offs if offs is within
 130  *      the bounds of this shared memory, else an ERR_PTR
 131  */
 132 void *tee_shm_get_va(struct tee_shm *shm, size_t offs);
 133
 134 /**
 135  * tee_shm_get_pa() - Get physical address of a shared memory plus an offset
 136  * @shm:        Shared memory handle
 137  * @offs:       Offset from start of this shared memory
 138  * @pa:         Physical address to return
 139  * @returns 0 if offs is within the bounds of this shared memory, else an
 140  *      error code.
 141  */
 142 int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa);
 143
 144 /**
 145  * tee_shm_get_size() - Get size of shared memory buffer
 146  * @shm:        Shared memory handle
 147  * @returns size of shared memory
 148  */
 149 static inline size_t tee_shm_get_size(struct tee_shm *shm)
 150 {
 151         return shm->size;
 152 }
 153
 154 /**
 155  * tee_shm_get_pages() - Get list of pages that hold shared buffer
 156  * @shm:        Shared memory handle
 157  * @num_pages:  Number of pages will be stored there
 158  * @returns pointer to pages array
 159  */
 160 static inline struct page **tee_shm_get_pages(struct tee_shm *shm,
 161                                               size_t *num_pages)
 162 {
 163         *num_pages = shm->num_pages;
 164         return shm->pages;
 165 }
 166
 167 /**
 168  * tee_shm_get_page_offset() - Get shared buffer offset from page start
 169  * @shm:        Shared memory handle
 170  * @returns page offset of shared buffer
 171  */
 172 static inline size_t tee_shm_get_page_offset(struct tee_shm *shm)
 173 {
 174         return shm->offset;
 175 }
 176
 177 /**
 178  * tee_client_open_context() - Open a TEE context
 179  * @start:      if not NULL, continue search after this context
 180  * @match:      function to check TEE device
 181  * @data:       data for match function
 182  * @vers:       if not NULL, version data of TEE device of the context returned
 183  *
 184  * This function does an operation similar to open("/dev/teeX") in user space.
 185  * A returned context must be released with tee_client_close_context().
 186  *
 187  * Returns a TEE context of the first TEE device matched by the match()
 188  * callback or an ERR_PTR.
 189  */
 190 struct tee_context *
 191 tee_client_open_context(struct tee_context *start,
 192                         int (*match)(struct tee_ioctl_version_data *,
 193                                      const void *),
 194                         const void *data, struct tee_ioctl_version_data *vers);
 195
 196 /**
 197  * tee_client_close_context() - Close a TEE context
 198  * @ctx:        TEE context to close
 199  *
 200  * Note that all sessions previously opened with this context will be
 201  * closed when this function is called.
 202  */
 203 void tee_client_close_context(struct tee_context *ctx);
 204
 205 /**
 206  * tee_client_get_version() - Query version of TEE
 207  * @ctx:        TEE context to TEE to query
 208  * @vers:       Pointer to version data
 209  */
 210 void tee_client_get_version(struct tee_context *ctx,
 211                             struct tee_ioctl_version_data *vers);
 212
 213 /**
 214  * tee_client_open_session() - Open a session to a Trusted Application
 215  * @ctx:        TEE context
 216  * @arg:        Open session arguments, see description of
 217  *              struct tee_ioctl_open_session_arg
 218  * @param:      Parameters passed to the Trusted Application
 219  *
 220  * Returns < 0 on error else see @arg->ret for result. If @arg->ret
 221  * is TEEC_SUCCESS the session identifier is available in @arg->session.
 222  */
 223 int tee_client_open_session(struct tee_context *ctx,
 224                             struct tee_ioctl_open_session_arg *arg,
 225                             struct tee_param *param);
 226
 227 /**
 228  * tee_client_close_session() - Close a session to a Trusted Application
 229  * @ctx:        TEE Context
 230  * @session:    Session id
 231  *
 232  * Return < 0 on error else 0, regardless the session will not be
 233  * valid after this function has returned.
 234  */
 235 int tee_client_close_session(struct tee_context *ctx, u32 session);
 236
 237 /**
 238  * tee_client_system_session() - Declare session as a system session
 239  * @ctx:        TEE Context
 240  * @session:    Session id
 241  *
 242  * This function requests TEE to provision an entry context ready to use for
 243  * that session only. The provisioned entry context is used for command
 244  * invocation and session closure, not for command cancelling requests.
 245  * TEE releases the provisioned context upon session closure.
 246  *
 247  * Return < 0 on error else 0 if an entry context has been provisioned.
 248  */
 249 int tee_client_system_session(struct tee_context *ctx, u32 session);
 250
 251 /**
 252  * tee_client_invoke_func() - Invoke a function in a Trusted Application
 253  * @ctx:        TEE Context
 254  * @arg:        Invoke arguments, see description of
 255  *              struct tee_ioctl_invoke_arg
 256  * @param:      Parameters passed to the Trusted Application
 257  *
 258  * Returns < 0 on error else see @arg->ret for result.
 259  */
 260 int tee_client_invoke_func(struct tee_context *ctx,
 261                            struct tee_ioctl_invoke_arg *arg,
 262                            struct tee_param *param);
 263
 264 /**
 265  * tee_client_cancel_req() - Request cancellation of the previous open-session
 266  * or invoke-command operations in a Trusted Application
 267  * @ctx:       TEE Context
 268  * @arg:       Cancellation arguments, see description of
 269  *             struct tee_ioctl_cancel_arg
 270  *
 271  * Returns < 0 on error else 0 if the cancellation was successfully requested.
 272  */
 273 int tee_client_cancel_req(struct tee_context *ctx,
 274                           struct tee_ioctl_cancel_arg *arg);
 275
 276 extern const struct bus_type tee_bus_type;
 277
 278 /**
 279  * struct tee_client_device - tee based device
 280  * @id:                 device identifier
 281  * @dev:                device structure
 282  */
 283 struct tee_client_device {
 284         struct tee_client_device_id id;
 285         struct device dev;
 286 };
 287
 288 #define to_tee_client_device(d) container_of(d, struct tee_client_device, dev)
 289
 290 /**
 291  * struct tee_client_driver - tee client driver
 292  * @id_table:           device id table supported by this driver
 293  * @driver:             driver structure
 294  */
 295 struct tee_client_driver {
 296         const struct tee_client_device_id *id_table;
 297         struct device_driver driver;
 298 };
 299
 300 #define to_tee_client_driver(d) \
 301                 container_of(d, struct tee_client_driver, driver)
 302
 303 #endif /*__TEE_DRV_H*/