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 #define TEE_UUID_LEN            16
  10
  11 #define TEE_GEN_CAP_GP          BIT(0)  /* GlobalPlatform compliant TEE */
  12 #define TEE_GEN_CAP_REG_MEM     BIT(1)  /* Supports registering shared memory */
  13
  14 #define TEE_SHM_REGISTER        BIT(0)  /* In list of shared memory */
  15 #define TEE_SHM_SEC_REGISTER    BIT(1)  /* TEE notified of this memory */
  16 #define TEE_SHM_ALLOC           BIT(2)  /* The memory is malloced() and must */
  17                                         /* be freed() */
  18
  19 #define TEE_PARAM_ATTR_TYPE_NONE                0       /* parameter not used */
  20 #define TEE_PARAM_ATTR_TYPE_VALUE_INPUT         1
  21 #define TEE_PARAM_ATTR_TYPE_VALUE_OUTPUT        2
  22 #define TEE_PARAM_ATTR_TYPE_VALUE_INOUT         3       /* input and output */
  23 #define TEE_PARAM_ATTR_TYPE_MEMREF_INPUT        5
  24 #define TEE_PARAM_ATTR_TYPE_MEMREF_OUTPUT       6
  25 #define TEE_PARAM_ATTR_TYPE_MEMREF_INOUT        7       /* input and output */
  26 #define TEE_PARAM_ATTR_TYPE_MASK                0xff
  27 #define TEE_PARAM_ATTR_META                     0x100
  28 #define TEE_PARAM_ATTR_MASK                     (TEE_PARAM_ATTR_TYPE_MASK | \
  29                                                  TEE_PARAM_ATTR_META)
  30
  31 /*
  32  * Some Global Platform error codes which has a meaning if the
  33  * TEE_GEN_CAP_GP bit is returned by the driver in
  34  * struct tee_version_data::gen_caps
  35  */
  36 #define TEE_SUCCESS                     0x00000000
  37 #define TEE_ERROR_GENERIC               0xffff0000
  38 #define TEE_ERROR_BAD_PARAMETERS        0xffff0006
  39 #define TEE_ERROR_ITEM_NOT_FOUND        0xffff0008
  40 #define TEE_ERROR_NOT_IMPLEMENTED       0xffff0009
  41 #define TEE_ERROR_NOT_SUPPORTED         0xffff000a
  42 #define TEE_ERROR_COMMUNICATION         0xffff000e
  43 #define TEE_ERROR_SECURITY              0xffff000f
  44 #define TEE_ERROR_OUT_OF_MEMORY         0xffff000c
  45 #define TEE_ERROR_TARGET_DEAD           0xffff3024
  46
  47 #define TEE_ORIGIN_COMMS                0x00000002
  48 #define TEE_ORIGIN_TEE                  0x00000003
  49 #define TEE_ORIGIN_TRUSTED_APP          0x00000004
  50
  51 struct udevice;
  52 /**
  53  * struct tee_shm - memory shared with the TEE
  54  * @dev:        The TEE device
  55  * @link:       List node in the list in struct struct tee_uclass_priv
  56  * @addr:       Pointer to the shared memory
  57  * @size:       Size of the the shared memory
  58  * @flags:      TEE_SHM_* above
  59  */
  60 struct tee_shm {
  61         struct udevice *dev;
  62         struct list_head link;
  63         void *addr;
  64         ulong size;
  65         u32 flags;
  66 };
  67
  68 /**
  69  * struct tee_param_memref - memory reference for a Trusted Application
  70  * @shm_offs:   Offset in bytes into the shared memory object @shm
  71  * @size:       Size in bytes of the memory reference
  72  * @shm:        Pointer to a shared memory object for the buffer
  73  *
  74  * Used as a part of struct tee_param, see that for more information.
  75  */
  76 struct tee_param_memref {
  77         ulong shm_offs;
  78         ulong size;
  79         struct tee_shm *shm;
  80 };
  81
  82 /**
  83  * struct tee_param_value - value parameter for a Trusted Application
  84  * @a, @b, @c:  Parameters passed by value
  85  *
  86  * Used as a part of struct tee_param, see that for more information.
  87  */
  88 struct tee_param_value {
  89         u64 a;
  90         u64 b;
  91         u64 c;
  92 };
  93
  94 /**
  95  * struct tee_param - invoke parameter for a Trusted Application
  96  * @attr:       Attributes
  97  * @u.memref:   Memref parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of
  98  *              TEE_PARAM_ATTR_TYPE_MEMREF_* above
  99  * @u.value:    Value parameter if (@attr & TEE_PARAM_ATTR_MASK) is one of
 100  *              TEE_PARAM_ATTR_TYPE_VALUE_* above
 101  *
 102  * Parameters to TA are passed using an array of this struct, for
 103  * flexibility both value parameters and memory refereces can be used.
 104  */
 105 struct tee_param {
 106         u64 attr;
 107         union {
 108                 struct tee_param_memref memref;
 109                 struct tee_param_value value;
 110         } u;
 111 };
 112
 113 /**
 114  * struct tee_open_session_arg - extra arguments for tee_open_session()
 115  * @uuid:       [in] UUID of the Trusted Application
 116  * @clnt_uuid:  [in] Normally zeroes
 117  * @clnt_login: [in] Normally 0
 118  * @session:    [out] Session id
 119  * @ret:        [out] return value
 120  * @ret_origin: [out] origin of the return value
 121  */
 122 struct tee_open_session_arg {
 123         u8 uuid[TEE_UUID_LEN];
 124         u8 clnt_uuid[TEE_UUID_LEN];
 125         u32 clnt_login;
 126         u32 session;
 127         u32 ret;
 128         u32 ret_origin;
 129 };
 130
 131 /**
 132  * struct tee_invoke_arg - extra arguments for tee_invoke_func()
 133  * @func:       [in] Trusted Application function, specific to the TA
 134  * @session:    [in] Session id, from open session
 135  * @ret:        [out] return value
 136  * @ret_origin: [out] origin of the return value
 137  */
 138 struct tee_invoke_arg {
 139         u32 func;
 140         u32 session;
 141         u32 ret;
 142         u32 ret_origin;
 143 };
 144
 145 /**
 146  * struct tee_version_data - description of TEE
 147  * @gen_caps:   Generic capabilities, TEE_GEN_CAP_* above
 148  */
 149 struct tee_version_data {
 150         u32 gen_caps;
 151 };
 152
 153 /**
 154  * struct tee_driver_ops - TEE driver operations
 155  * @get_version:        Query capabilities of TEE device,
 156  * @open_session:       Opens a session to a Trusted Application in the TEE,
 157  * @close_session:      Closes a session to Trusted Application,
 158  * @invoke_func:        Invokes a function in a Trusted Application,
 159  * @shm_register:       Registers memory shared with the TEE
 160  * @shm_unregister:     Unregisters memory shared with the TEE
 161  */
 162 struct tee_driver_ops {
 163         /**
 164          * get_version() - Query capabilities of TEE device
 165          * @dev:        The TEE device
 166          * @vers:       Pointer to version data
 167          */
 168         void (*get_version)(struct udevice *dev, struct tee_version_data *vers);
 169         /**
 170          * open_session() - Open a session to a Trusted Application
 171          * @dev:        The TEE device
 172          * @arg:        Open session arguments
 173          * @num_param:  Number of elements in @param
 174          * @param:      Parameters for Trusted Application
 175          *
 176          * Returns < 0 on error else see @arg->ret for result. If @arg->ret is
 177          * TEE_SUCCESS the session identifier is available in @arg->session.
 178          */
 179         int (*open_session)(struct udevice *dev,
 180                             struct tee_open_session_arg *arg, uint num_param,
 181                             struct tee_param *param);
 182         /**
 183          * close_session() - Close a session to a Trusted Application
 184          * @dev:        The TEE device
 185          * @session:    Session id
 186          *
 187          * Return < 0 on error else 0, regardless the session will not be valid
 188          * after this function has returned.
 189          */
 190         int (*close_session)(struct udevice *dev, u32 session);
 191         /**
 192          * tee_invoke_func() - Invoke a function in a Trusted Application
 193          * @dev:        The TEE device
 194          * @arg:        Invoke arguments
 195          * @num_param:  Number of elements in @param
 196          * @param:      Parameters for Trusted Application
 197          *
 198          * Returns < 0 on error else see @arg->ret for result.
 199          */
 200         int (*invoke_func)(struct udevice *dev, struct tee_invoke_arg *arg,
 201                            uint num_param, struct tee_param *param);
 202         /**
 203          * shm_register() - Registers memory shared with the TEE
 204          * @dev:        The TEE device
 205          * @shm:        Pointer to a shared memory object
 206          * Returns 0 on success or < 0 on failure.
 207          */
 208         int (*shm_register)(struct udevice *dev, struct tee_shm *shm);
 209         /**
 210          * shm_unregister() - Unregisters memory shared with the TEE
 211          * @dev:        The TEE device
 212          * @shm:        Pointer to a shared memory object
 213          * Returns 0 on success or < 0 on failure.
 214          */
 215         int (*shm_unregister)(struct udevice *dev, struct tee_shm *shm);
 216 };
 217
 218 /**
 219  * __tee_shm_add() - Internal helper function to register shared memory
 220  * @dev:        The TEE device
 221  * @align:      Required alignment of allocated memory block if
 222  *              (@flags & TEE_SHM_ALLOC)
 223  * @addr:       Address of memory block, ignored if (@flags & TEE_SHM_ALLOC)
 224  * @size:       Size of memory block
 225  * @flags:      TEE_SHM_* above
 226  * @shmp:       If the function return 0, this holds the allocated
 227  *              struct tee_shm
 228  *
 229  * returns 0 on success or < 0 on failure.
 230  */
 231 int __tee_shm_add(struct udevice *dev, ulong align, void *addr, ulong size,
 232                   u32 flags, struct tee_shm **shmp);
 233
 234 /**
 235  * tee_shm_alloc() - Allocate shared memory
 236  * @dev:        The TEE device
 237  * @size:       Size of memory block
 238  * @flags:      TEE_SHM_* above
 239  * @shmp:       If the function return 0, this holds the allocated
 240  *              struct tee_shm
 241  *
 242  * returns 0 on success or < 0 on failure.
 243  */
 244 int tee_shm_alloc(struct udevice *dev, ulong size, u32 flags,
 245                   struct tee_shm **shmp);
 246
 247 /**
 248  * tee_shm_register() - Registers shared memory
 249  * @dev:        The TEE device
 250  * @addr:       Address of memory block
 251  * @size:       Size of memory block
 252  * @flags:      TEE_SHM_* above
 253  * @shmp:       If the function return 0, this holds the allocated
 254  *              struct tee_shm
 255  *
 256  * returns 0 on success or < 0 on failure.
 257  */
 258 int tee_shm_register(struct udevice *dev, void *addr, ulong size, u32 flags,
 259                      struct tee_shm **shmp);
 260
 261 /**
 262  * tee_shm_free() - Frees shared memory
 263  * @shm:        Shared memory object
 264  */
 265 void tee_shm_free(struct tee_shm *shm);
 266
 267 /**
 268  * tee_shm_is_registered() - Check register status of shared memory object
 269  * @shm:        Pointer to shared memory object
 270  * @dev:        The TEE device
 271  *
 272  * Returns true if the shared memory object is registered for the supplied
 273  * TEE device
 274  */
 275 bool tee_shm_is_registered(struct tee_shm *shm, struct udevice *dev);
 276
 277 /**
 278  * tee_find_device() - Look up a TEE device
 279  * @start:      if not NULL, continue search after this device
 280  * @match:      function to check TEE device, returns != 0 if the device
 281  *              matches
 282  * @data:       data for match function
 283  * @vers:       if not NULL, version data of TEE device of the device returned
 284  *
 285  * Returns a probed TEE device of the first TEE device matched by the
 286  * match() callback or NULL.
 287  */
 288 struct udevice *tee_find_device(struct udevice *start,
 289                                 int (*match)(struct tee_version_data *vers,
 290                                              const void *data),
 291                                 const void *data,
 292                                 struct tee_version_data *vers);
 293
 294 /**
 295  * tee_get_version() - Query capabilities of TEE device
 296  * @dev:        The TEE device
 297  * @vers:       Pointer to version data
 298  */
 299 void tee_get_version(struct udevice *dev, struct tee_version_data *vers);
 300
 301 /**
 302  * tee_open_session() - Open a session to a Trusted Application
 303  * @dev:        The TEE device
 304  * @arg:        Open session arguments
 305  * @num_param:  Number of elements in @param
 306  * @param:      Parameters for Trusted Application
 307  *
 308  * Returns < 0 on error else see @arg->ret for result. If @arg->ret is
 309  * TEE_SUCCESS the session identifier is available in @arg->session.
 310  */
 311 int tee_open_session(struct udevice *dev, struct tee_open_session_arg *arg,
 312                      uint num_param, struct tee_param *param);
 313
 314 /**
 315  * tee_close_session() - Close a session to a Trusted Application
 316  * @dev:        The TEE device
 317  * @session:    Session id
 318  *
 319  * Return < 0 on error else 0, regardless the session will not be valid
 320  * after this function has returned.
 321  */
 322 int tee_close_session(struct udevice *dev, u32 session);
 323
 324 /**
 325  * tee_invoke_func() - Invoke a function in a Trusted Application
 326  * @dev:        The TEE device
 327  * @arg:        Invoke arguments
 328  * @num_param:  Number of elements in @param
 329  * @param:      Parameters for Trusted Application
 330  *
 331  * Returns < 0 on error else see @arg->ret for result.
 332  */
 333 int tee_invoke_func(struct udevice *dev, struct tee_invoke_arg *arg,
 334                     uint num_param, struct tee_param *param);
 335
 336 #endif /* __TEE_H */