include/tee.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (c) 2018 Linaro Limited
   4  */
   5
   6 #ifndef __TEE_H
   7 #define __TEE_H
   8
   9 #include <linux/bitops.h>
  10 #include <linux/list.h>
  11
  12 #define TEE_UUID_LEN            16
  13
  14 #define TEE_GEN_CAP_GP          BIT(0)  /* GlobalPlatform compliant TEE */
  15 #define TEE_GEN_CAP_REG_MEM     BIT(1)  /* Supports registering shared memory */
  16
  17 #define TEE_SHM_REGISTER        BIT(0)  /* In list of shared memory */
  18 #define TEE_SHM_SEC_REGISTER    BIT(1)  /* TEE notified of this memory */
  19 #define TEE_SHM_ALLOC           BIT(2)  /* The memory is malloced() and must */
  20                                         /* be freed() */
  21
  22 #define TEE_PARAM_ATTR_TYPE_NONE                0       /* parameter not used */
  23 #define TEE_PARAM_ATTR_TYPE_VALUE_INPUT         1
  24 #define TEE_PARAM_ATTR_TYPE_VALUE_OUTPUT        2
  25 #define TEE_PARAM_ATTR_TYPE_VALUE_INOUT         3       /* input and output */
  26 #define TEE_PARAM_ATTR_TYPE_MEMREF_INPUT        5
  27 #define TEE_PARAM_ATTR_TYPE_MEMREF_OUTPUT       6
  28 #define TEE_PARAM_ATTR_TYPE_MEMREF_INOUT        7       /* input and output */
  29 #define TEE_PARAM_ATTR_TYPE_MASK                0xff
  30 #define TEE_PARAM_ATTR_META                     0x100
  31 #define TEE_PARAM_ATTR_MASK                     (TEE_PARAM_ATTR_TYPE_MASK | \
  32                                                  TEE_PARAM_ATTR_META)
  33
  34 /*
  35  * Global Platform login identifiers for tee_open_session_arg::clnt_login
  36  */
  37 #define TEE_LOGIN_PUBLIC                  0x00000000
  38 #define TEE_LOGIN_USER                    0x00000001
  39 #define TEE_LOGIN_GROUP                   0x00000002
  40 #define TEE_LOGIN_APPLICATION             0x00000004
  41 #define TEE_LOGIN_APPLICATION_USER        0x00000005
  42 #define TEE_LOGIN_APPLICATION_GROUP       0x00000006
  43 /*
  44  * Reserve use of GP implementation specific login method range
  45  * (0x80000000 - 0xBFFFFFFF). This range is rather being used
  46  * for REE kernel clients or TEE implementation.
  47  */
  48 #define TEE_LOGIN_REE_KERNEL_MIN          0x80000000
  49 #define TEE_LOGIN_REE_KERNEL_MAX          0xBFFFFFFF
  50 /* Private login method for REE kernel/privileged clients */
  51 #define TEE_LOGIN_REE_KERNEL              0x80000000
  52
  53 /*
  54  * Some Global Platform error codes which has a meaning if the
  55  * TEE_GEN_CAP_GP bit is returned by the driver in
  56  * struct tee_version_data::gen_caps
  57  */
  58 #define TEE_SUCCESS                     0x00000000
  59 #define TEE_ERROR_STORAGE_NOT_AVAILABLE 0xf0100003
  60 #define TEE_ERROR_GENERIC               0xffff0000
  61 #define TEE_ERROR_EXCESS_DATA           0xffff0004
  62 #define TEE_ERROR_BAD_PARAMETERS        0xffff0006
  63 #define TEE_ERROR_ITEM_NOT_FOUND        0xffff0008
  64 #define TEE_ERROR_NOT_IMPLEMENTED       0xffff0009
  65 #define TEE_ERROR_NOT_SUPPORTED         0xffff000a
  66 #define TEE_ERROR_COMMUNICATION         0xffff000e
  67 #define TEE_ERROR_SECURITY              0xffff000f
  68 #define TEE_ERROR_SHORT_BUFFER          0xffff0010
  69 #define TEE_ERROR_OUT_OF_MEMORY         0xffff000c
  70 #define TEE_ERROR_OVERFLOW              0xffff300f
  71 #define TEE_ERROR_TARGET_DEAD           0xffff3024
  72 #define TEE_ERROR_STORAGE_NO_SPACE      0xffff3041
  73
  74 #define TEE_ORIGIN_COMMS                0x00000002
  75 #define TEE_ORIGIN_TEE                  0x00000003
  76 #define TEE_ORIGIN_TRUSTED_APP          0x00000004
  77
  78 struct udevice;
  79
  80 /**
  81  * struct tee_optee_ta_uuid - OP-TEE Trusted Application (TA) UUID format
  82  *
  83  * Used to identify an OP-TEE TA and define suitable to initialize structs
  84  * of this format is distributed with the interface of the TA. The
  85  * individual fields of this struct doesn't have any special meaning in
  86  * OP-TEE. See RFC4122 for details on the format.
  87  */
  88 struct tee_optee_ta_uuid {
  89         u32 time_low;
  90         u16 time_mid;
  91         u16 time_hi_and_version;
  92         u8 clock_seq_and_node[8];
  93 };
  94
  95 /**
  96  * struct tee_shm - memory shared with the TEE
  97  * @dev:        The TEE device
  98  * @link:       List node in the list in struct struct tee_uclass_priv
  99  * @addr:       Pointer to the shared memory
 100  * @size:       Size of the the shared memory
 101  * @flags:      TEE_SHM_* above
 102  */
 103 struct tee_shm {
 104         struct udevice *dev;
 105         struct list_head link;
 106         void *addr;
 107         ulong size;
 108         u32 flags;
 109 };
 110
 111 /**
 112  * struct tee_param_memref - memory reference for a Trusted Application
 113  * @shm_offs:   Offset in bytes into the shared memory object @shm
 114  * @size:       Size in bytes of the memory reference
 115  * @shm:        Pointer to a shared memory object for the buffer
 116  *
 117  * Used as a part of struct tee_param, see that for more information.
 118  */
 119 struct tee_param_memref {
 120         ulong shm_offs;
 121         ulong size;
 122         struct tee_shm *shm;
 123 };
 124
 125 /**
 126  * struct tee_param_value - value parameter for a Trusted Application
 127  * @a, @b, @c:  Parameters passed by value
 128  *
 129  * Used as a part of struct tee_param, see that for more information.
 130  */
 131 struct tee_param_value {
 132         u64 a;
 133         u64 b;
 134         u64 c;
 135 };
 136
 137 /**
 138  * struct tee_param - invoke parameter for a Trusted Application
 139  * @attr:       Attributes
 140  * @u.memref:   Memref parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of
 141  *              TEE_PARAM_ATTR_TYPE_MEMREF_* above
 142  * @u.value:    Value parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of
 143  *              TEE_PARAM_ATTR_TYPE_VALUE_* above
 144  *
 145  * Parameters to TA are passed using an array of this struct, for
 146  * flexibility both value parameters and memory refereces can be used.
 147  */
 148 struct tee_param {
 149         u64 attr;
 150         union {
 151                 struct tee_param_memref memref;
 152                 struct tee_param_value value;
 153         } u;
 154 };
 155
 156 /**
 157  * struct tee_open_session_arg - extra arguments for tee_open_session()
 158  * @uuid:       [in] UUID of the Trusted Application
 159  * @clnt_uuid:  [in] UUID of client, zeroes for PUBLIC/REE_KERNEL
 160  * @clnt_login: [in] Class of client TEE_LOGIN_*
 161  * @session:    [out] Session id
 162  * @ret:        [out] return value
 163  * @ret_origin: [out] origin of the return value
 164  */
 165 struct tee_open_session_arg {
 166         u8 uuid[TEE_UUID_LEN];
 167         u8 clnt_uuid[TEE_UUID_LEN];
 168         u32 clnt_login;
 169         u32 session;
 170         u32 ret;
 171         u32 ret_origin;
 172 };
 173
 174 /**
 175  * struct tee_invoke_arg - extra arguments for tee_invoke_func()
 176  * @func:       [in] Trusted Application function, specific to the TA
 177  * @session:    [in] Session id, from open session
 178  * @ret:        [out] return value
 179  * @ret_origin: [out] origin of the return value
 180  */
 181 struct tee_invoke_arg {
 182         u32 func;
 183         u32 session;
 184         u32 ret;
 185         u32 ret_origin;
 186 };
 187
 188 /**
 189  * struct tee_version_data - description of TEE
 190  * @gen_caps:   Generic capabilities, TEE_GEN_CAP_* above
 191  */
 192 struct tee_version_data {
 193         u32 gen_caps;
 194 };
 195
 196 /**
 197  * struct tee_driver_ops - TEE driver operations
 198  * @get_version:        Query capabilities of TEE device,
 199  * @open_session:       Opens a session to a Trusted Application in the TEE,
 200  * @close_session:      Closes a session to Trusted Application,
 201  * @invoke_func:        Invokes a function in a Trusted Application,
 202  * @shm_register:       Registers memory shared with the TEE
 203  * @shm_unregister:     Unregisters memory shared with the TEE
 204  */
 205 struct tee_driver_ops {
 206         /**
 207          * get_version() - Query capabilities of TEE device
 208          * @dev:        The TEE device
 209          * @vers:       Pointer to version data
 210          */
 211         void (*get_version)(struct udevice *dev, struct tee_version_data *vers);
 212         /**
 213          * open_session() - Open a session to a Trusted Application
 214          * @dev:        The TEE device
 215          * @arg:        Open session arguments
 216          * @num_param:  Number of elements in @param
 217          * @param:      Parameters for Trusted Application
 218          *
 219          * Returns < 0 on error else see @arg->ret for result. If @arg->ret is
 220          * TEE_SUCCESS the session identifier is available in @arg->session.
 221          */
 222         int (*open_session)(struct udevice *dev,
 223                             struct tee_open_session_arg *arg, uint num_param,
 224                             struct tee_param *param);
 225         /**
 226          * close_session() - Close a session to a Trusted Application
 227          * @dev:        The TEE device
 228          * @session:    Session id
 229          *
 230          * Return < 0 on error else 0, regardless the session will not be valid
 231          * after this function has returned.
 232          */
 233         int (*close_session)(struct udevice *dev, u32 session);
 234         /**
 235          * tee_invoke_func() - Invoke a function in a Trusted Application
 236          * @dev:        The TEE device
 237          * @arg:        Invoke arguments
 238          * @num_param:  Number of elements in @param
 239          * @param:      Parameters for Trusted Application
 240          *
 241          * Returns < 0 on error else see @arg->ret for result.
 242          */
 243         int (*invoke_func)(struct udevice *dev, struct tee_invoke_arg *arg,
 244                            uint num_param, struct tee_param *param);
 245         /**
 246          * shm_register() - Registers memory shared with the TEE
 247          * @dev:        The TEE device
 248          * @shm:        Pointer to a shared memory object
 249          * Returns 0 on success or < 0 on failure.
 250          */
 251         int (*shm_register)(struct udevice *dev, struct tee_shm *shm);
 252         /**
 253          * shm_unregister() - Unregisters memory shared with the TEE
 254          * @dev:        The TEE device
 255          * @shm:        Pointer to a shared memory object
 256          * Returns 0 on success or < 0 on failure.
 257          */
 258         int (*shm_unregister)(struct udevice *dev, struct tee_shm *shm);
 259 };
 260
 261 /**
 262  * __tee_shm_add() - Internal helper function to register shared memory
 263  * @dev:        The TEE device
 264  * @align:      Required alignment of allocated memory block if
 265  *              (@flags & TEE_SHM_ALLOC)
 266  * @addr:       Address of memory block, ignored if (@flags & TEE_SHM_ALLOC)
 267  * @size:       Size of memory block
 268  * @flags:      TEE_SHM_* above
 269  * @shmp:       If the function return 0, this holds the allocated
 270  *              struct tee_shm
 271  *
 272  * returns 0 on success or < 0 on failure.
 273  */
 274 int __tee_shm_add(struct udevice *dev, ulong align, void *addr, ulong size,
 275                   u32 flags, struct tee_shm **shmp);
 276
 277 /**
 278  * tee_shm_alloc() - Allocate shared memory
 279  * @dev:        The TEE device
 280  * @size:       Size of memory block
 281  * @flags:      TEE_SHM_* above
 282  * @shmp:       If the function return 0, this holds the allocated
 283  *              struct tee_shm
 284  *
 285  * returns 0 on success or < 0 on failure.
 286  */
 287 int tee_shm_alloc(struct udevice *dev, ulong size, u32 flags,
 288                   struct tee_shm **shmp);
 289
 290 /**
 291  * tee_shm_register() - Registers shared memory
 292  * @dev:        The TEE device
 293  * @addr:       Address of memory block
 294  * @size:       Size of memory block
 295  * @flags:      TEE_SHM_* above
 296  * @shmp:       If the function return 0, this holds the allocated
 297  *              struct tee_shm
 298  *
 299  * returns 0 on success or < 0 on failure.
 300  */
 301 int tee_shm_register(struct udevice *dev, void *addr, ulong size, u32 flags,
 302                      struct tee_shm **shmp);
 303
 304 /**
 305  * tee_shm_free() - Frees shared memory
 306  * @shm:        Shared memory object
 307  */
 308 void tee_shm_free(struct tee_shm *shm);
 309
 310 /**
 311  * tee_shm_is_registered() - Check register status of shared memory object
 312  * @shm:        Pointer to shared memory object
 313  * @dev:        The TEE device
 314  *
 315  * Returns true if the shared memory object is registered for the supplied
 316  * TEE device
 317  */
 318 bool tee_shm_is_registered(struct tee_shm *shm, struct udevice *dev);
 319
 320 /**
 321  * tee_find_device() - Look up a TEE device
 322  * @start:      if not NULL, continue search after this device
 323  * @match:      function to check TEE device, returns != 0 if the device
 324  *              matches
 325  * @data:       data for match function
 326  * @vers:       if not NULL, version data of TEE device of the device returned
 327  *
 328  * Returns a probed TEE device of the first TEE device matched by the
 329  * match() callback or NULL.
 330  */
 331 #if CONFIG_IS_ENABLED(TEE)
 332 struct udevice *tee_find_device(struct udevice *start,
 333                                 int (*match)(struct tee_version_data *vers,
 334                                              const void *data),
 335                                 const void *data,
 336                                 struct tee_version_data *vers);
 337 #else
 338 static inline struct udevice *tee_find_device(struct udevice *start,
 339                                               int (*match)(struct tee_version_data *vers,
 340                                                            const void *data),
 341                                               const void *data,
 342                                               struct tee_version_data *vers)
 343 {
 344         return NULL;
 345 }
 346 #endif
 347
 348 /**
 349  * tee_get_version() - Query capabilities of TEE device
 350  * @dev:        The TEE device
 351  * @vers:       Pointer to version data
 352  */
 353 void tee_get_version(struct udevice *dev, struct tee_version_data *vers);
 354
 355 /**
 356  * tee_open_session() - Open a session to a Trusted Application
 357  * @dev:        The TEE device
 358  * @arg:        Open session arguments
 359  * @num_param:  Number of elements in @param
 360  * @param:      Parameters for Trusted Application
 361  *
 362  * Returns < 0 on error else see @arg->ret for result. If @arg->ret is
 363  * TEE_SUCCESS the session identifier is available in @arg->session.
 364  */
 365 int tee_open_session(struct udevice *dev, struct tee_open_session_arg *arg,
 366                      uint num_param, struct tee_param *param);
 367
 368 /**
 369  * tee_close_session() - Close a session to a Trusted Application
 370  * @dev:        The TEE device
 371  * @session:    Session id
 372  *
 373  * Return < 0 on error else 0, regardless the session will not be valid
 374  * after this function has returned.
 375  */
 376 int tee_close_session(struct udevice *dev, u32 session);
 377
 378 /**
 379  * tee_invoke_func() - Invoke a function in a Trusted Application
 380  * @dev:        The TEE device
 381  * @arg:        Invoke arguments
 382  * @num_param:  Number of elements in @param
 383  * @param:      Parameters for Trusted Application
 384  *
 385  * Returns < 0 on error else see @arg->ret for result.
 386  */
 387 int tee_invoke_func(struct udevice *dev, struct tee_invoke_arg *arg,
 388                     uint num_param, struct tee_param *param);
 389
 390 /**
 391  * tee_optee_ta_uuid_from_octets() - Converts to struct tee_optee_ta_uuid
 392  * @d:  Destination struct
 393  * @s:  Source UUID octets
 394  *
 395  * Conversion to a struct tee_optee_ta_uuid represantion from binary octet
 396  * representation.
 397  */
 398 void tee_optee_ta_uuid_from_octets(struct tee_optee_ta_uuid *d,
 399                                    const u8 s[TEE_UUID_LEN]);
 400
 401 /**
 402  * tee_optee_ta_uuid_to_octets() - Converts from struct tee_optee_ta_uuid
 403  * @d:  Destination UUID octets
 404  * @s:  Source struct
 405  *
 406  * Conversion from a struct tee_optee_ta_uuid represantion to binary octet
 407  * representation.
 408  */
 409 void tee_optee_ta_uuid_to_octets(u8 d[TEE_UUID_LEN],
 410                                  const struct tee_optee_ta_uuid *s);
 411
 412 /**
 413  * tee_flush_all_shm_dcache() - Flush data cache for all shared memories
 414  * @dev:        The TEE device
 415  */
 416 void tee_flush_all_shm_dcache(struct udevice *dev);
 417
 418 #endif /* __TEE_H */