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