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