include/linux/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/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  */
 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  */
 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  */
 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
 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*/