405 lines · c
1/*2 * Copyright (c) 2015-2016, Linaro Limited3 * All rights reserved.4 *5 * Redistribution and use in source and binary forms, with or without6 * 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 documentation13 * 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, THE17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE18 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE19 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR20 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF21 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS22 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN23 * 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 THE25 * POSSIBILITY OF SUCH DAMAGE.26 */27 28#ifndef __TEE_H29#define __TEE_H30 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 the38 * data passed back and forth using TEE_IOC_CMD.39 */40 41/* Helpers to make the ioctl defines */42#define TEE_IOC_MAGIC 0xa443#define TEE_IOC_BASE 044 45#define TEE_MAX_ARG_SIZE 102446 47#define TEE_GEN_CAP_GP (1 << 0)/* GlobalPlatform compliant TEE */48#define TEE_GEN_CAP_PRIVILEGED (1 << 1)/* Privileged device (for supplicant) */49#define TEE_GEN_CAP_REG_MEM (1 << 2)/* Supports registering shared memory */50#define TEE_GEN_CAP_MEMREF_NULL (1 << 3)/* NULL MemRef support */51 52#define TEE_MEMREF_NULL (__u64)(-1) /* NULL MemRef Buffer */53 54/*55 * TEE Implementation ID56 */57#define TEE_IMPL_ID_OPTEE 158#define TEE_IMPL_ID_AMDTEE 259#define TEE_IMPL_ID_TSTEE 360 61/*62 * OP-TEE specific capabilities63 */64#define TEE_OPTEE_CAP_TZ (1 << 0)65 66/**67 * struct tee_ioctl_version_data - TEE version68 * @impl_id: [out] TEE implementation id69 * @impl_caps: [out] Implementation specific capabilities70 * @gen_caps: [out] Generic capabilities, defined by TEE_GEN_CAPS_* above71 *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 */76struct 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 TEE84 *85 * Takes a tee_ioctl_version_data struct and returns with the TEE version86 * 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 argument93 * @size: [in/out] Size of shared memory to allocate94 * @flags: [in/out] Flags to/from allocation.95 * @id: [out] Identifier of the shared memory96 *97 * The flags field should currently be zero as input. Updated by the call98 * with actual flags as defined by TEE_IOCTL_SHM_* above.99 * This structure is used as argument for TEE_IOC_SHM_ALLOC below.100 */101struct tee_ioctl_shm_alloc_data {102 __u64 size;103 __u32 flags;104 __s32 id;105};106 107/**108 * TEE_IOC_SHM_ALLOC - allocate shared memory109 *110 * Allocates shared memory between the user space process and secure OS.111 *112 * Returns a file descriptor on success or < 0 on failure113 *114 * The returned file descriptor is used to map the shared memory into user115 * space. The shared memory is freed when the descriptor is closed and the116 * 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 buffer123 * @buf_ptr: [in] A __user pointer to a buffer124 * @buf_len: [in] Length of the buffer above125 *126 * Used as argument for TEE_IOC_OPEN_SESSION, TEE_IOC_INVOKE,127 * TEE_IOC_SUPPL_RECV, and TEE_IOC_SUPPL_SEND below.128 */129struct 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 union136 */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 1143#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_OUTPUT 2144#define TEE_IOCTL_PARAM_ATTR_TYPE_VALUE_INOUT 3 /* input and output */145 146/*147 * These defines shared memory reference parameters (struct148 * tee_ioctl_param_memref)149 */150#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT 5151#define TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT 6152#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 types156 */157#define TEE_IOCTL_PARAM_ATTR_TYPE_MASK 0xff158 159/* Meta parameter carrying extra information about the message. */160#define TEE_IOCTL_PARAM_ATTR_META 0x100161 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 API168 * Are only defined for GP compliant TEEs169 */170#define TEE_IOCTL_LOGIN_PUBLIC 0171#define TEE_IOCTL_LOGIN_USER 1172#define TEE_IOCTL_LOGIN_GROUP 2173#define TEE_IOCTL_LOGIN_APPLICATION 4174#define TEE_IOCTL_LOGIN_USER_APPLICATION 5175#define TEE_IOCTL_LOGIN_GROUP_APPLICATION 6176/*177 * Disallow user-space to use GP implementation specific login178 * method range (0x80000000 - 0xBFFFFFFF). This range is rather179 * being reserved for REE kernel clients or TEE implementation.180 */181#define TEE_IOCTL_LOGIN_REE_KERNEL_MIN 0x80000000182#define TEE_IOCTL_LOGIN_REE_KERNEL_MAX 0xBFFFFFFF183/* Private login method for REE kernel clients */184#define TEE_IOCTL_LOGIN_REE_KERNEL 0x80000000185 186/**187 * struct tee_ioctl_param - parameter188 * @attr: attributes189 * @a: if a memref, offset into the shared memory object, else a value parameter190 * @b: if a memref, size of the buffer, else a value parameter191 * @c: if a memref, shared memory identifier, else a value parameter192 *193 * @attr & TEE_PARAM_ATTR_TYPE_MASK indicates if memref or value is used in194 * the union. TEE_PARAM_ATTR_TYPE_VALUE_* indicates value and195 * TEE_PARAM_ATTR_TYPE_MEMREF_* indicates memref. TEE_PARAM_ATTR_TYPE_NONE196 * indicates that none of the members are used.197 *198 * Shared memory is allocated with TEE_IOC_SHM_ALLOC which returns an199 * identifier representing the shared memory object. A memref can reference200 * a part of a shared memory by specifying an offset (@a) and size (@b) of201 * the object. To supply the entire shared memory object set the offset202 * (@a) to 0 and size (@b) to the previously returned size of the object.203 *204 * A client may need to present a NULL pointer in the argument205 * passed to a trusted application in the TEE.206 * This is also a requirement in GlobalPlatform Client API v1.0c207 * (section 3.2.5 memory references), which can be found at208 * http://www.globalplatform.org/specificationsdevice.asp209 *210 * If a NULL pointer is passed to a TA in the TEE, the (@c)211 * IOCTL parameters value must be set to TEE_MEMREF_NULL indicating a NULL212 * memory reference.213 */214struct tee_ioctl_param {215 __u64 attr;216 __u64 a;217 __u64 b;218 __u64 c;219};220 221#define TEE_IOCTL_UUID_LEN 16222 223/**224 * struct tee_ioctl_open_session_arg - Open session argument225 * @uuid: [in] UUID of the Trusted Application226 * @clnt_uuid: [in] UUID of client227 * @clnt_login: [in] Login class of client, TEE_IOCTL_LOGIN_* above228 * @cancel_id: [in] Cancellation id, a unique value to identify this request229 * @session: [out] Session id230 * @ret: [out] return value231 * @ret_origin [out] origin of the return value232 * @num_params [in] number of parameters following this struct233 */234struct tee_ioctl_open_session_arg {235 __u8 uuid[TEE_IOCTL_UUID_LEN];236 __u8 clnt_uuid[TEE_IOCTL_UUID_LEN];237 __u32 clnt_login;238 __u32 cancel_id;239 __u32 session;240 __u32 ret;241 __u32 ret_origin;242 __u32 num_params;243 /* num_params tells the actual number of element in params */244 struct tee_ioctl_param params[];245};246 247/**248 * TEE_IOC_OPEN_SESSION - opens a session to a Trusted Application249 *250 * Takes a struct tee_ioctl_buf_data which contains a struct251 * tee_ioctl_open_session_arg followed by any array of struct252 * tee_ioctl_param253 */254#define TEE_IOC_OPEN_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \255 struct tee_ioctl_buf_data)256 257/**258 * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted259 * Application260 * @func: [in] Trusted Application function, specific to the TA261 * @session: [in] Session id262 * @cancel_id: [in] Cancellation id, a unique value to identify this request263 * @ret: [out] return value264 * @ret_origin [out] origin of the return value265 * @num_params [in] number of parameters following this struct266 */267struct tee_ioctl_invoke_arg {268 __u32 func;269 __u32 session;270 __u32 cancel_id;271 __u32 ret;272 __u32 ret_origin;273 __u32 num_params;274 /* num_params tells the actual number of element in params */275 struct tee_ioctl_param params[];276};277 278/**279 * TEE_IOC_INVOKE - Invokes a function in a Trusted Application280 *281 * Takes a struct tee_ioctl_buf_data which contains a struct282 * tee_invoke_func_arg followed by any array of struct tee_param283 */284#define TEE_IOC_INVOKE _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 3, \285 struct tee_ioctl_buf_data)286 287/**288 * struct tee_ioctl_cancel_arg - Cancels an open session or invoke ioctl289 * @cancel_id: [in] Cancellation id, a unique value to identify this request290 * @session: [in] Session id, if the session is opened, else set to 0291 */292struct tee_ioctl_cancel_arg {293 __u32 cancel_id;294 __u32 session;295};296 297/**298 * TEE_IOC_CANCEL - Cancels an open session or invoke299 */300#define TEE_IOC_CANCEL _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 4, \301 struct tee_ioctl_cancel_arg)302 303/**304 * struct tee_ioctl_close_session_arg - Closes an open session305 * @session: [in] Session id306 */307struct tee_ioctl_close_session_arg {308 __u32 session;309};310 311/**312 * TEE_IOC_CLOSE_SESSION - Closes a session313 */314#define TEE_IOC_CLOSE_SESSION _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 5, \315 struct tee_ioctl_close_session_arg)316 317/**318 * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function319 * @func: [in] supplicant function320 * @num_params [in/out] number of parameters following this struct321 *322 * @num_params is the number of params that tee-supplicant has room to323 * receive when input, @num_params is the number of actual params324 * tee-supplicant receives when output.325 */326struct tee_iocl_supp_recv_arg {327 __u32 func;328 __u32 num_params;329 /* num_params tells the actual number of element in params */330 struct tee_ioctl_param params[];331};332 333/**334 * TEE_IOC_SUPPL_RECV - Receive a request for a supplicant function335 *336 * Takes a struct tee_ioctl_buf_data which contains a struct337 * tee_iocl_supp_recv_arg followed by any array of struct tee_param338 */339#define TEE_IOC_SUPPL_RECV _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 6, \340 struct tee_ioctl_buf_data)341 342/**343 * struct tee_iocl_supp_send_arg - Send a response to a received request344 * @ret: [out] return value345 * @num_params [in] number of parameters following this struct346 */347struct tee_iocl_supp_send_arg {348 __u32 ret;349 __u32 num_params;350 /* num_params tells the actual number of element in params */351 struct tee_ioctl_param params[];352};353 354/**355 * TEE_IOC_SUPPL_SEND - Send a response to a received request356 *357 * Takes a struct tee_ioctl_buf_data which contains a struct358 * tee_iocl_supp_send_arg followed by any array of struct tee_param359 */360#define TEE_IOC_SUPPL_SEND _IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 7, \361 struct tee_ioctl_buf_data)362 363/**364 * struct tee_ioctl_shm_register_data - Shared memory register argument365 * @addr: [in] Start address of shared memory to register366 * @length: [in/out] Length of shared memory to register367 * @flags: [in/out] Flags to/from registration.368 * @id: [out] Identifier of the shared memory369 *370 * The flags field should currently be zero as input. Updated by the call371 * with actual flags as defined by TEE_IOCTL_SHM_* above.372 * This structure is used as argument for TEE_IOC_SHM_REGISTER below.373 */374struct tee_ioctl_shm_register_data {375 __u64 addr;376 __u64 length;377 __u32 flags;378 __s32 id;379};380 381/**382 * TEE_IOC_SHM_REGISTER - Register shared memory argument383 *384 * Registers shared memory between the user space process and secure OS.385 *386 * Returns a file descriptor on success or < 0 on failure387 *388 * The shared memory is unregisterred when the descriptor is closed.389 */390#define TEE_IOC_SHM_REGISTER _IOWR(TEE_IOC_MAGIC, TEE_IOC_BASE + 9, \391 struct tee_ioctl_shm_register_data)392/*393 * Five syscalls are used when communicating with the TEE driver.394 * open(): opens the device associated with the driver395 * ioctl(): as described above operating on the file descriptor from open()396 * close(): two cases397 * - closes the device file descriptor398 * - closes a file descriptor connected to allocated shared memory399 * mmap(): maps shared memory into user space using information from struct400 * tee_ioctl_shm_alloc_data401 * munmap(): unmaps previously shared memory402 */403 404#endif /*__TEE_H*/405