include/uapi/linux/tee.h

   1 /*
   2  * Copyright (c) 2015-2016, Linaro Limited
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright notice,
   9  * this list of conditions and the following disclaimer.
  10  *
  11  * 2. Redistributions in binary form must reproduce the above copyright notice,
  12  * this list of conditions and the following disclaimer in the documentation
  13  * and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  19  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25  * POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef __TEE_H
  29 #define __TEE_H
  30
  31 #include <linux/ioctl.h>
  32 #include <linux/types.h>
  33
  34 /*
  35  * This file describes the API provided by a TEE driver to user space.
  36  *
  37  * Each TEE driver defines a TEE specific protocol which is used for the
  38  * data passed back and forth using TEE_IOC_CMD.
  39  */
  40
  41 /* Helpers to make the ioctl defines */
  42 #define TEE_IOC_MAGIC   0xa4
  43 #define TEE_IOC_BASE    0
  44
  45 /* Flags relating to shared memory */
  46 #define TEE_IOCTL_SHM_MAPPED    0x1     /* memory mapped in normal world */
  47 #define TEE_IOCTL_SHM_DMA_BUF   0x2     /* dma-buf handle on shared memory */
  48
  49 #define TEE_MAX_ARG_SIZE        1024
  50
  51 #define TEE_GEN_CAP_GP          (1 << 0)/* GlobalPlatform compliant TEE */
  52 #define TEE_GEN_CAP_PRIVILEGED  (1 << 1)/* Privileged device (for supplicant) */
  53 #define TEE_GEN_CAP_REG_MEM     (1 << 2)/* Supports registering shared memory */
  54
  55 /*
  56  * TEE Implementation ID
  57  */
  58 #define TEE_IMPL_ID_OPTEE       1
  59 #define TEE_IMPL_ID_AMDTEE      2
  60
  61 /*
  62  * OP-TEE specific capabilities
  63  */
  64 #define TEE_OPTEE_CAP_TZ        (1 << 0)
  65
  66 /**
  67  * struct tee_ioctl_version_data - TEE version
  68  * @impl_id:    [out] TEE implementation id
  69  * @impl_caps:  [out] Implementation specific capabilities
  70  * @gen_caps:   [out] Generic capabilities, defined by TEE_GEN_CAPS_* above
  71  *
  72  * Identifies the TEE implementation, @impl_id is one of TEE_IMPL_ID_* above.
  73  * @impl_caps is implementation specific, for example TEE_OPTEE_CAP_*
  74  * is valid when @impl_id == TEE_IMPL_ID_OPTEE.
  75  */
  76 struct tee_ioctl_version_data {
  77         __u32 impl_id;
  78         __u32 impl_caps;
  79         __u32 gen_caps;
  80 };
  81
  82 /**
  83  * TEE_IOC_VERSION - query version of TEE
  84  *
  85  * Takes a tee_ioctl_version_data struct and returns with the TEE version
  86  * data filled in.
  87  */
  88 #define TEE_IOC_VERSION         _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 0, \
  89                                      struct tee_ioctl_version_data)
  90
  91 /**
  92  * struct tee_ioctl_shm_alloc_data - Shared memory allocate argument
  93  * @size:       [in/out] Size of shared memory to allocate
  94  * @flags:      [in/out] Flags to/from allocation.
  95  * @id:         [out] Identifier of the shared memory
  96  *
  97  * The flags field should currently be zero as input. Updated by the call
  98  * with actual flags as defined by TEE_IOCTL_SHM_* above.
  99  * This structure is used as argument for TEE_IOC_SHM_ALLOC below.
 100  */
 101 struct tee_ioctl_shm_alloc_data {
 102         __u64 size;
 103         __u32 flags;
 104         __s32 id;
 105 };
 106
 107 /**
 108  * TEE_IOC_SHM_ALLOC - allocate shared memory
 109  *
 110  * Allocates shared memory between the user space process and secure OS.
 111  *
 112  * Returns a file descriptor on success or < 0 on failure
 113  *
 114  * The returned file descriptor is used to map the shared memory into user
 115  * space. The shared memory is freed when the descriptor is closed and the
 116  * memory is unmapped.
 117  */
 118 #define TEE_IOC_SHM_ALLOC       _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 1, \
 119                                      struct tee_ioctl_shm_alloc_data)
 120
 121 /**
 122  * struct tee_ioctl_buf_data - Variable sized buffer
 123  * @buf_ptr:    [in] A __user pointer to a buffer
 124  * @buf_len:    [in] Length of the buffer above
 125  *
 126  * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,
 127  * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.
 128  */
 129 struct tee_ioctl_buf_data {
 130         __u64 buf_ptr;
 131         __u64 buf_len;
 132 };
 133
 134 /*
 135  * Attributes for struct tee_ioctl_param, selects field in the union
 136  */
 137 #define TEE_IOCTL_PARAM_ATTR_TYPE_NONE          0       /* parameter not used */
 138
 139 /*
 140  * These defines value parameters (struct tee_ioctl_param_value)
 141  */
 142 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INPUT   1
 143 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT  2
 144 #define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT   3       /* input and output */
 145
 146 /*
 147  * These defines shared memory reference parameters (struct
 148  * tee_ioctl_param_memref)
 149  */
 150 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT  5
 151 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6
 152 #define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT  7       /* input and output */
 153
 154 /*
 155  * Mask for the type part of the attribute, leaves room for more types
 156  */
 157 #define TEE_IOCTL_PARAM_ATTR_TYPE_MASK          0xff
 158
 159 /* Meta parameter carrying extra information about the message. */
 160 #define TEE_IOCTL_PARAM_ATTR_META               0x100
 161
 162 /* Mask of all known attr bits */
 163 #define TEE_IOCTL_PARAM_ATTR_MASK \
 164         (TEE_IOCTL_PARAM_ATTR_TYPE_MASK | TEE_IOCTL_PARAM_ATTR_META)
 165
 166 /*
 167  * Matches TEEC_LOGIN_* in GP TEE Client API
 168  * Are only defined for GP compliant TEEs
 169  */
 170 #define TEE_IOCTL_LOGIN_PUBLIC                  0
 171 #define TEE_IOCTL_LOGIN_USER                    1
 172 #define TEE_IOCTL_LOGIN_GROUP                   2
 173 #define TEE_IOCTL_LOGIN_APPLICATION             4
 174 #define TEE_IOCTL_LOGIN_USER_APPLICATION        5
 175 #define TEE_IOCTL_LOGIN_GROUP_APPLICATION       6
 176
 177 /**
 178  * struct tee_ioctl_param - parameter
 179  * @attr: attributes
 180  * @a: if a memref, offset into the shared memory object, else a value parameter
 181  * @b: if a memref, size of the buffer, else a value parameter
 182  * @c: if a memref, shared memory identifier, else a value parameter
 183  *
 184  * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref or value is used in
 185  * the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value and
 186  * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref. TEE_PARAM_ATTR_TYPE_NONE
 187  * indicates that none of the members are used.
 188  *
 189  * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an
 190  * identifier representing the shared memory object. A memref can reference
 191  * a part of a shared memory by specifying an offset (@a) and size (@b) of
 192  * the object. To supply the entire shared memory object set the offset
 193  * (@a) to 0 and size (@b) to the previously returned size of the object.
 194  */
 195 struct tee_ioctl_param {
 196         __u64 attr;
 197         __u64 a;
 198         __u64 b;
 199         __u64 c;
 200 };
 201
 202 #define TEE_IOCTL_UUID_LEN              16
 203
 204 /**
 205  * struct tee_ioctl_open_session_arg - Open session argument
 206  * @uuid:       [in] UUID of the Trusted Application
 207  * @clnt_uuid:  [in] UUID of client
 208  * @clnt_login: [in] Login class of client, TEE_IOCTL_LOGIN_* above
 209  * @cancel_id:  [in] Cancellation id, a unique value to identify this request
 210  * @session:    [out] Session id
 211  * @ret:        [out] return value
 212  * @ret_origin  [out] origin of the return value
 213  * @num_params  [in] number of parameters following this struct
 214  */
 215 struct tee_ioctl_open_session_arg {
 216         __u8 uuid[TEE_IOCTL_UUID_LEN];
 217         __u8 clnt_uuid[TEE_IOCTL_UUID_LEN];
 218         __u32 clnt_login;
 219         __u32 cancel_id;
 220         __u32 session;
 221         __u32 ret;
 222         __u32 ret_origin;
 223         __u32 num_params;
 224         /* num_params tells the actual number of element in params */
 225         struct tee_ioctl_param params[];
 226 };
 227
 228 /**
 229  * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application
 230  *
 231  * Takes a struct tee_ioctl_buf_data which contains a struct
 232  * tee_ioctl_open_session_arg followed by any array of struct
 233  * tee_ioctl_param
 234  */
 235 #define TEE_IOC_OPEN_SESSION    _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
 236                                      struct tee_ioctl_buf_data)
 237
 238 /**
 239  * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
 240  * Application
 241  * @func:       [in] Trusted Application function, specific to the TA
 242  * @session:    [in] Session id
 243  * @cancel_id:  [in] Cancellation id, a unique value to identify this request
 244  * @ret:        [out] return value
 245  * @ret_origin  [out] origin of the return value
 246  * @num_params  [in] number of parameters following this struct
 247  */
 248 struct tee_ioctl_invoke_arg {
 249         __u32 func;
 250         __u32 session;
 251         __u32 cancel_id;
 252         __u32 ret;
 253         __u32 ret_origin;
 254         __u32 num_params;
 255         /* num_params tells the actual number of element in params */
 256         struct tee_ioctl_param params[];
 257 };
 258
 259 /**
 260  * TEE_IOC_INVOKE - Invokes a function in a Trusted Application
 261  *
 262  * Takes a struct tee_ioctl_buf_data which contains a struct
 263  * tee_invoke_func_arg followed by any array of struct tee_param
 264  */
 265 #define TEE_IOC_INVOKE          _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \
 266                                      struct tee_ioctl_buf_data)
 267
 268 /**
 269  * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl
 270  * @cancel_id:  [in] Cancellation id, a unique value to identify this request
 271  * @session:    [in] Session id, if the session is opened, else set to 0
 272  */
 273 struct tee_ioctl_cancel_arg {
 274         __u32 cancel_id;
 275         __u32 session;
 276 };
 277
 278 /**
 279  * TEE_IOC_CANCEL - Cancels an open session or invoke
 280  */
 281 #define TEE_IOC_CANCEL          _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 4, \
 282                                      struct tee_ioctl_cancel_arg)
 283
 284 /**
 285  * struct tee_ioctl_close_session_arg - Closes an open session
 286  * @session:    [in] Session id
 287  */
 288 struct tee_ioctl_close_session_arg {
 289         __u32 session;
 290 };
 291
 292 /**
 293  * TEE_IOC_CLOSE_SESSION - Closes a session
 294  */
 295 #define TEE_IOC_CLOSE_SESSION   _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \
 296                                      struct tee_ioctl_close_session_arg)
 297
 298 /**
 299  * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
 300  * @func:       [in] supplicant function
 301  * @num_params  [in/out] number of parameters following this struct
 302  *
 303  * @num_params is the number of params that tee-supplicant has room to
 304  * receive when input, @num_params is the number of actual params
 305  * tee-supplicant receives when output.
 306  */
 307 struct tee_iocl_supp_recv_arg {
 308         __u32 func;
 309         __u32 num_params;
 310         /* num_params tells the actual number of element in params */
 311         struct tee_ioctl_param params[];
 312 };
 313
 314 /**
 315  * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function
 316  *
 317  * Takes a struct tee_ioctl_buf_data which contains a struct
 318  * tee_iocl_supp_recv_arg followed by any array of struct tee_param
 319  */
 320 #define TEE_IOC_SUPPL_RECV      _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \
 321                                      struct tee_ioctl_buf_data)
 322
 323 /**
 324  * struct tee_iocl_supp_send_arg - Send a response to a received request
 325  * @ret:        [out] return value
 326  * @num_params  [in] number of parameters following this struct
 327  */
 328 struct tee_iocl_supp_send_arg {
 329         __u32 ret;
 330         __u32 num_params;
 331         /* num_params tells the actual number of element in params */
 332         struct tee_ioctl_param params[];
 333 };
 334
 335 /**
 336  * TEE_IOC_SUPPL_SEND - Receive a request for a supplicant function
 337  *
 338  * Takes a struct tee_ioctl_buf_data which contains a struct
 339  * tee_iocl_supp_send_arg followed by any array of struct tee_param
 340  */
 341 #define TEE_IOC_SUPPL_SEND      _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \
 342                                      struct tee_ioctl_buf_data)
 343
 344 /**
 345  * struct tee_ioctl_shm_register_data - Shared memory register argument
 346  * @addr:      [in] Start address of shared memory to register
 347  * @length:    [in/out] Length of shared memory to register
 348  * @flags:     [in/out] Flags to/from registration.
 349  * @id:                [out] Identifier of the shared memory
 350  *
 351  * The flags field should currently be zero as input. Updated by the call
 352  * with actual flags as defined by TEE_IOCTL_SHM_* above.
 353  * This structure is used as argument for TEE_IOC_SHM_REGISTER below.
 354  */
 355 struct tee_ioctl_shm_register_data {
 356         __u64 addr;
 357         __u64 length;
 358         __u32 flags;
 359         __s32 id;
 360 };
 361
 362 /**
 363  * TEE_IOC_SHM_REGISTER - Register shared memory argument
 364  *
 365  * Registers shared memory between the user space process and secure OS.
 366  *
 367  * Returns a file descriptor on success or < 0 on failure
 368  *
 369  * The shared memory is unregisterred when the descriptor is closed.
 370  */
 371 #define TEE_IOC_SHM_REGISTER   _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 9, \
 372                                      struct tee_ioctl_shm_register_data)
 373 /*
 374  * Five syscalls are used when communicating with the TEE driver.
 375  * open(): opens the device associated with the driver
 376  * ioctl(): as described above operating on the file descriptor from open()
 377  * close(): two cases
 378  *   - closes the device file descriptor
 379  *   - closes a file descriptor connected to allocated shared memory
 380  * mmap(): maps shared memory into user space using information from struct
 381  *         tee_ioctl_shm_alloc_data
 382  * munmap(): unmaps previously shared memory
 383  */
 384
 385 #endif /*__TEE_H*/