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