#include <sw_list.h>
#include <otz_tee_api.h>

Classes
struct	TEEC_Session
	The TEEC_Session structure is used to contain control information related to a session between a client and a service. More...

struct	TEEC_Context
	The TEEC_Context structure is used to contain control information related to the TEE. More...

struct	TEEC_SharedMemory
	The TEEC_SharedMemory structure is used to contain control information related to a block of shared memory that is mapped between the client and the service. More...

struct	TEEC_Value
	Small raw data value type. More...

struct	TEEC_TempMemoryReference
	Temporary shared memory reference. More...

struct	TEEC_RegisteredMemoryReference
	Registered memory reference. More...

union	TEEC_Parameter
	Parameter of a TEEC_Operation. More...

struct	TEEC_Operation
	The TEEC_Operation structure is used to contain control information related to an operation that is to be invoked with the security environment. More...

Macros
#define	MAX_SESSIONS_PER_DEVICE 16

#define	MAX_OPERATIONS_PER_SESSION 16

#define	MAX_MEMBLOCKS_PER_SESSION 16

#define	MAX_MEMBLOCKS_PER_OPERATION 4

#define	TEEC_PARAM_TYPES(param0Type, param1Type, param2Type, param3Type) (param3Type << 12 \| param2Type << 8 \| param1Type << 4 \| param0Type)

#define	TEEC_VALUE_UNDEF 0xffffffff

Typedefs
typedef struct TEEC_Operation	TEEC_Operation

typedef struct TEEC_Session	TEEC_Session

typedef struct TEEC_Context	TEEC_Context

typedef struct TEEC_SharedMemory	TEEC_SharedMemory

typedef struct TEEC_TempMemoryReference	TEEC_TempMemoryReference

typedef struct TEEC_RegisteredMemoryReference	TEEC_RegisteredMemoryReference

typedef struct TEEC_Value	TEEC_Value

typedef uint32_t	TEEC_UUID

Enumerations
enum	TEEC_return_code_origin { TEEC_ORIGIN_API = 0x1, TEEC_ORIGIN_COMMS = 0x2, TEEC_ORIGIN_TEE = 0x3, TEEC_ORIGIN_TRUSTED_APP = 0x4 }
	Return code origin. More...

enum	TEEC_login_flags { TEEC_LOGIN_PUBLIC = 0x0, TEEC_LOGIN_USER, TEEC_LOGIN_GROUP, TEEC_LOGIN_APPLICATION = 0x4, TEEC_LOGIN_USER_APPLICATION = 0x5, TEEC_LOGIN_GROUP_APPLICATION = 0x6 }
	Login flag constants. More...

enum	TEEC_shared_mem_flags { TEEC_MEM_INPUT = 0x1, TEEC_MEM_OUTPUT = 0x2 }
	Shared memory flag constants. More...

enum	TEEC_param_type { TEEC_NONE = 0x1, TEEC_VALUE_INPUT, TEEC_VALUE_OUTPUT, TEEC_VALUE_INOUT, TEEC_MEMREF_TEMP_INPUT, TEEC_MEMREF_TEMP_OUTPUT, TEEC_MEMREF_TEMP_INOUT, TEEC_MEMREF_WHOLE = 0xc, TEEC_MEMREF_PARTIAL_INPUT = 0xd, TEEC_MEMREF_PARTIAL_OUTPUT = 0xe, TEEC_MEMREF_PARTIAL_INOUT = 0xf }
	Param type constants. More...

enum	otz_shared_mem_flags { OTZ_MEM_SERVICE_RO = 0x0, OTZ_MEM_SERVICE_WO, OTZ_MEM_SERVICE_RW, OTZ_MEM_SERVICE_UNDEFINED, OTZ_MEM_SERVICE_RO = 0x0, OTZ_MEM_SERVICE_WO, OTZ_MEM_SERVICE_RW, OTZ_MEM_SERVICE_UNDEFINED }
	Shared memory flag constants. More...

Functions
TEEC_Result	TEEC_InitializeContext (const char name, TEEC_Context context)
	Initialize Context. More...

void	TEEC_FinalizeContext (TEEC_Context *context)
	Finalizes an initialized TEE context. More...

TEEC_Result	TEEC_RegisterSharedMemory (TEEC_Context context, TEEC_SharedMemory sharedMem)
	Register a allocated shared memory block. More...

TEEC_Result	TEEC_AllocateSharedMemory (TEEC_Context context, TEEC_SharedMemory sharedMem)
	Allocate a shared memory block. More...

void	TEEC_ReleaseSharedMemory (TEEC_SharedMemory *sharedMem)
	Release a shared memory block. More...

TEEC_Result	TEEC_OpenSession (TEEC_Context context, TEEC_Session session, const TEEC_UUID destination, uint32_t connectionMethod, const void connectionData, TEEC_Operation operation, uint32_t returnOrigin)
	Opens a new session between client and trusted application. More...

void	TEEC_CloseSession (TEEC_Session *session)
	Close a opened session between client and trusted application. More...

TEEC_Result	TEEC_InvokeCommand (TEEC_Session session, uint32_t commandID, TEEC_Operation operation, uint32_t *returnOrigin)
	Invokes a command within the session. More...

void	TEEC_RequestCancellation (TEEC_Operation *operation)
	Request cancellation of pending open session or command invocation. More...

char *	TEEC_GetError (int error, int returnOrigin)
	Returns error string. More...

Macro Definition Documentation

#define MAX_MEMBLOCKS_PER_OPERATION 4

#define MAX_MEMBLOCKS_PER_SESSION 16

#define MAX_OPERATIONS_PER_SESSION 16

#define MAX_SESSIONS_PER_DEVICE 16

#define TEEC_PARAM_TYPES	(	param0Type,
		param1Type,
		param2Type,
		param3Type
	)	(param3Type << 12 \| param2Type << 8 \| param1Type << 4 \| param0Type)

#define TEEC_VALUE_UNDEF 0xffffffff

Typedef Documentation

typedef struct TEEC_Context TEEC_Context

typedef struct TEEC_Operation TEEC_Operation

typedef struct TEEC_RegisteredMemoryReference TEEC_RegisteredMemoryReference

typedef struct TEEC_Session TEEC_Session

typedef struct TEEC_SharedMemory TEEC_SharedMemory

typedef struct TEEC_TempMemoryReference TEEC_TempMemoryReference

typedef uint32_t TEEC_UUID

typedef struct TEEC_Value TEEC_Value

Enumeration Type Documentation

enum otz_shared_mem_flags

Shared memory flag constants.

Enumerator
OTZ_MEM_SERVICE_RO	Service can only read from the memory block.
OTZ_MEM_SERVICE_WO	Service can only write from the memory block.
OTZ_MEM_SERVICE_RW	Service can read and write from the memory block.
OTZ_MEM_SERVICE_UNDEFINED	Invalid flag
OTZ_MEM_SERVICE_RO	Service can only read from the memory block.
OTZ_MEM_SERVICE_WO	Service can only write from the memory block.
OTZ_MEM_SERVICE_RW	Service can read and write from the memory block.
OTZ_MEM_SERVICE_UNDEFINED	Invalid flag

enum TEEC_login_flags

Login flag constants.

Enumerator
TEEC_LOGIN_PUBLIC	No login is to be used.
TEEC_LOGIN_USER	The user executing the application is provided.
TEEC_LOGIN_GROUP	The user group executing the application is provided.
TEEC_LOGIN_APPLICATION	Login data about the running Client Application itself is provided.
TEEC_LOGIN_USER_APPLICATION	Login data about the user running the Client Application and about the Client Application itself is provided.
TEEC_LOGIN_GROUP_APPLICATION	Login data about the group running the Client Application and about the Client Application itself is provided.

enum TEEC_param_type

Param type constants.

Enumerator
TEEC_NONE	The Parameter is not used.
TEEC_VALUE_INPUT	The Parameter is a TEEC_Value tagged as input.
TEEC_VALUE_OUTPUT	The Parameter is a TEEC_Value tagged as output.
TEEC_VALUE_INOUT	The Parameter is a TEEC_Value tagged as both as input and output, i.e., for which both the behaviors of TEEC_VALUE_INPUT and TEEC_VALUE_OUTPUT apply.
TEEC_MEMREF_TEMP_INPUT	The Parameter is a TEEC_TempMemoryReference describing a region of memory which needs to be temporarily registered for the duration of the Operation and is tagged as input.
TEEC_MEMREF_TEMP_OUTPUT	Same as TEEC_MEMREF_TEMP_INPUT, but the Memory Reference is tagged as output. The Implementation may update the size field to reflect the required output size in some use cases.
TEEC_MEMREF_TEMP_INOUT	A Temporary Memory Reference tagged as both input and output, i.e., for which both the behaviors of TEEC_MEMREF_TEMP_INPUT and TEEC_MEMREF_TEMP_OUTPUT apply.
TEEC_MEMREF_WHOLE	The Parameter is a Registered Memory Reference that refers to the entirety of its parent Shared Memory block. The parameter structure is a TEEC_MemoryReference. In this structure, the Implementation MUST read only the parent field and MAY update the size field when the operation completes.
TEEC_MEMREF_PARTIAL_INPUT	A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as input.
TEEC_MEMREF_PARTIAL_OUTPUT	A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as output.
TEEC_MEMREF_PARTIAL_INOUT	A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as both input and output.

enum TEEC_return_code_origin

Return code origin.

Enumerator
TEEC_ORIGIN_API	The return code is an error that originated within the TEE Client API implementation.
TEEC_ORIGIN_COMMS	The return code is an error that originated within the underlying communications stack linking the rich OS with the TEE.
TEEC_ORIGIN_TEE	The return code is an error that originated within the common TEE code.
TEEC_ORIGIN_TRUSTED_APP	The return code is an error that originated within the Trusted application code. This includes the case where the return code is a success.

enum TEEC_shared_mem_flags

Shared memory flag constants.

Enumerator
TEEC_MEM_INPUT	The Shared Memory can carry data from the Client Application to the Trusted Application.
TEEC_MEM_OUTPUT	The Shared Memory can carry data from the Trusted Application to the Client Application.

Function Documentation

TEEC_Result TEEC_AllocateSharedMemory	(	TEEC_Context *	context,
		TEEC_SharedMemory *	sharedMem
	)

Allocate a shared memory block.

This function allocates a new block of memory as a block of Shared Memory within the scope of the specified TEE Context, in accordance with the parameters which have been set by the Client Application inside the sharedMem structure.

The parameter context MUST point to an initialized TEE Context.

The sharedMem parameter MUST point to the Shared Memory structure defining the region to allocate. Client Application MUST have populated the following fields of the Shared Memory structure:
The size field MUST contain the desired size of the buffer, in bytes. The size is allowed to be zero. In this case memory is allocated and the pointer written in to the buffer field on return MUST not be NULL but MUST never be de-referenced by the Client Application. In this case however, the Shared Memory block can be used in Registered Memory References.
The flags field indicates the allowed directions of data flow between the Client Application and the TEE.
The Implementation MUST assume that all other fields in the Shared Memory structure have undefined content.

An Implementation MAY put a hard limit on the size of a single Shared Memory block, defined by the constant TEEC_CONFIG_SHAREDMEM_MAX_SIZE. However note that this function may fail to allocate a block smaller than this limit due to a low resource condition encountered at run-time.

If this function returns any code other than TEEC_SUCCESS the Implementation MUST have set the buffer field of sharedMem to NULL.

Programmer Error
The following usage of the API is a programmer error:
Calling with a context which is not initialized.
Calling with a sharedMem which has not be correctly populated in accordance with the specification.
Attempting to initialize the same Shared Memory structure concurrently from multiple threads.Multi-threaded Client Applications must use platform-provided locking mechanisms to ensure that this case does not occur.

Implementor's Notes
Once successfully allocated the Shared Memory block can be used for efficient data transfers between the Client Application and the Trusted Application. The TEE Client API and the underlying communications infrastructure should attempt to transfer data in to the TEE without using copies, if this is possible on the underlying implementation, but may have to fall back on data copies if zero-copy cannot be achieved. The memory buffer allocated by this function must have sufficient alignment to store any fundamental C data type at a natural alignment. For most platforms this will require the memory buffer to have 8-byte alignment, but refer to the Application Binary Interface (ABI) of the target platform for details.

Parameters

context	A pointer to an initialized TEE Context
sharedMem	A pointer to a Shared Memory structure to allocate: Before calling this function, the Client Application MUST have set the size, and flags fields. On return, for a successful allocation the Implementation MUST have set the pointer buffer to the address of the allocated block, otherwise it MUST set buffer to NULL.

Returns: TEEC_Result: TEEC_SUCCESS: The allocation was successful.
TEEC_ERROR_*: An implementation-defined error code for any other error.

Parameters

context	Pointer to the context
sharedMem	Pointer to the shared memory

Returns: TEEC_Result: TEEC_SUCCESS: The allocation was successful.
TEEC_ERROR_*: An implementation-defined error code for any other error.

void TEEC_CloseSession ( TEEC_Session * session )

Close a opened session between client and trusted application.

This function closes a Session which has been opened with a Trusted Application.

All Commands within the Session MUST have completed before calling this function.

The Implementation MUST do nothing if the session parameter is NULL.

The implementation of this function MUST NOT be able to fail: after this function returns the Client Application must be able to consider that the Session has been closed.

Programmer Error
The following usage of the API is a programmer error:
Calling with a session which still has commands running.
Attempting to close the same Session concurrently from multiple threads.
Attempting to close the same Session more than once.

Parameters

session Session to close

Close a opened session between client and trusted application.

Parameters

session Pointer to the session structure

void TEEC_FinalizeContext ( TEEC_Context * context )

Finalizes an initialized TEE context.

This function finalizes an initialized TEE Context, closing the connection between the Client Application and the TEE. The Client Application MUST only call this function when all Sessions inside this TEE Context have been closed and all Shared Memory blocks have been released.
The implementation of this function MUST NOT be able to fail: after this function returns the Client Application must be able to consider that the Context has been closed.
The function implementation MUST do nothing if context is NULL.

Programmer Error
The following usage of the API is a programmer error:
Calling with a context which still has sessions opened.
Calling with a context which contains unreleased Shared Memory blocks.
Attempting to finalize the same TEE Context structure concurrently from multiple threads.
Attempting to finalize the same TEE Context structure more than once, without an intervening call to TEEC_InitalizeContext.

Parameters

context	An initialized TEEC_Context structure which is to be finalized.
context	An initialized TEEC_Context structure which is to be finalized.

char* TEEC_GetError	(	int	error,
		int	returnOrigin
	)

Returns error string.

This function returns the error string value based on error number and return origin.

Parameters

error	Error number.
returnOrigin	Origin of the return.

Returns: char*: Error string value.

TEEC_Result TEEC_InitializeContext	(	const char *	name,
		TEEC_Context *	context
	)

Initialize Context.

This function initializes a new TEE Context, forming a connection between this Client Application and the TEE identified by the string identifier name.
The Client Application MAY pass a NULL name, which means that the Implementation MUST select a default TEE to connect to. The supported name strings, the mapping of these names to a specific TEE, and the nature of the default TEE are implementation-defined.
The caller MUST pass a pointer to a valid TEEC Context in context. The Implementation MUST assume that all fields of the TEEC_Context structure are in an undefined state.
Programmer Error
The following usage of the API is a programmer error:
Attempting to initialize the same TEE Context structure concurrently from multiple threads. Multi-threaded Client Applications must use platform-provided locking mechanisms to ensure that this case does not occur.

Implementers’ Notes
It is valid Client Application behavior to concurrently initialize different TEE Contexts, so the Implementation MUST support this.

Parameters

name	A zero-terminated string that describes the TEE to connect to. If this parameter is set to NULL the Implementation MUST select a default TEE.
context	A TEEC_Context structure that MUST be initialized by the Implementation.

Returns: TEEC_Result: TEEC_SUCCESS: The initialization was successful.
TEEC_ERROR_*: An implementation-defined error code for any other error.

Parameters

name	A zero-terminated string that describes the TEE to connect to. If this parameter is set to NULL the Implementation MUST select a default TEE.
context	A TEEC_Context structure that MUST be initialized by the Implementation.

Returns: TEEC_Result: TEEC_SUCCESS: The initialization was successful.
TEEC_ERROR_*: An implementation-defined error code for any other error.

TEEC_Result TEEC_InvokeCommand	(	TEEC_Session *	session,
		uint32_t	commandID,
		TEEC_Operation *	operation,
		uint32_t *	returnOrigin
	)

Invokes a command within the session.

This function invokes a Command within the specified Session.

The parameter session MUST point to a valid open Session.

The parameter commandID is an identifier that is used to indicate which of the exposed Trusted Application functions should be invoked. The supported command identifiers are defined by the Trusted Application‟s protocol.

Operation Handling
A Command MAY optionally carry an Operation Payload. When the payload is present the parameter operation MUST point to a TEEC_Operation structure populated by the Client Application. If operation is NULL then no parameters are exchanged with the Trusted Application, and only the Command ID is exchanged.

The operation structure is also used to manage cancellation of the Command. If cancellation is required then the operation pointer MUST be non-NULL and the Client Application MUST have zeroed the started field of the operation structure before calling this function. The operation structure MAY contain no Parameters if no data payload is to be exchanged.

The Operation Payload is handled as described by the following steps, which are executed sequentially:

Each Parameter in the Operation Payload is examined. If the parameter is a Temporary Memory Reference, then it is registered for the duration of the Operation in accordance with the fields set in the TEEC_TempMemoryReference structure and the data flow direction specified in the parameter type. Refer to the TEEC_RegisterSharedMemory function for error conditions which can be triggered during temporary registration of a memory region.
The contents of all the Memory Regions which are exchanged with the TEE are synchronized
The fields of all Value Parameters tagged as input are read by the Implementation. This applies to Parameters of type TEEC_VALUE_INPUT or TEEC_VALUE_INOUT.
The Operation is issued to the Trusted Application. During the execution of the Command, the Trusted Application may read the data held within the memory referred to by input Memory References. It may also write data in to the memory referred to by output Memory References, but these modifications are not guaranteed to be observable by the Client Application until the command completes.
After the Command has completed, the Implementation MUST update the size field of the Memory Reference structures flagged as output:
a. For Memory References that are non-null and marked as output, the updated size field MAY be less than or equal to original size field. In this case this indicates the number of bytes actually written by the Trusted Application, and the Implementation MUST synchronize this region with the Client Application memory space.
b. For all Memory References marked as output, the updated size field MAY be larger than the original size field. For null Memory References, a required buffer size MAY be specified by the Trusted Application. In these cases the passed output buffer was too small or absent, and the returned size indicates the size of the output buffer which is necessary for the operation to succeed. In these cases the Implementation SHOULD NOT synchronize any shared data with the Client Application.
When the Command completes, the Implementation MUST update the fields of all Value Parameters tagged as output, i.e., of type TEEC_VALUE_OUTPUT or TEEC_VALUE_INOUT.
All memory regions that were temporarily registered at the beginning of the function are deregistered as if the function TEEC_ReleaseSharedMemory was called on each of them.
Control is passed back to the calling Client Application code.
Programmer Error
.

The result of this function is returned both in the function TEEC_Result return code and the return origin, stored in the variable pointed to by returnOrigin:
If the return origin is different from TEEC_ORIGIN_TRUSTED_APP, then the return code MUST be one of the error codes. If the return code is TEEC_ERROR_CANCEL then it means that the operation was cancelled before it reached the Trusted Application.
If the return origin is TEEC_ORIGIN_TRUSTED_APP, then the meaning of the return code is determined by the protocol exposed by the Trusted Application. It is recommended that the Trusted Application developer chooses TEEC_SUCCESS (0) to indicate success in their protocol, as this means that it is possible for the Client Application developer to determine success or failure without looking at the return origin.

Programmer
Error
The following usage of the API is a programmer error:
Calling with a session which is not an open session.
Calling with invalid content in the paramTypes field of the operation structure. This invalid behavior includes types which are Reserved for future use or which conflict with the flags of the parent Shared Memory block.
Encoding Registered Memory References which refer to Shared Memory blocks allocated or registered within the scope of a different TEE Context.
Using the same operation structure concurrently for multiple operations, whether open Session operations or Command invocations.

Parameters

session	The open Session in which the command will be invoked.
commandID	The identifier of the Command within the Trusted Application to invoke. The meaning of each Command Identifier must be defined in the protocol exposed by the Trusted Application
operation	A pointer to a Client Application initialized TEEC_Operation structure, or NULL if there is no payload to send or if the Command does not need to support cancellation.
returnOrigin	A pointer to a variable which will contain the return origin. This field may be NULL if the return origin is not needed.

Returns: TEEC_Result: TEEC_SUCCESS: The command was successfully invoked.
TEEC_ERROR_*: An implementation-defined error code for any other error.

Invokes a command within the session.

Parameters

session	Pointer to session
commandID	Command ID
operation	Pointer to operation structure
returnOrigin	Pointer to the return origin

Returns: TEEC_Result: TEEC_SUCCESS: The command was successfully invoked.
TEEC_ERROR_*: An implementation-defined error code for any other error.

TEEC_Result TEEC_OpenSession	(	TEEC_Context *	context,
		TEEC_Session *	session,
		const TEEC_UUID *	destination,
		uint32_t	connectionMethod,
		const void *	connectionData,
		TEEC_Operation *	operation,
		uint32_t *	returnOrigin
	)

Opens a new session between client and trusted application.

This function opens a new Session between the Client Application and the specified Trusted Application.

The Implementation MUST assume that all fields of this session structure are in an undefined state. When this function returns TEEC_SUCCESS the Implementation MUST have populated this structure with any information necessary for subsequent operations within the Session.

The target Trusted Application is identified by a UUID passed in the parameter destination.

The Session MAY be opened using a specific connection method that can carry additional connection data, such as data about the user or user-group running the Client Application, or about the Client Application itself. This allows the Trusted Application to implement access control methods which separate functionality or data accesses for different actors in the rich environment outside of the TEE. The additional data associated with each connection method is passed in via the pointer connectionData. For the core login types the following connection data is required:

TEEC_LOGIN_PUBLIC - connectionData SHOULD be NULL.
TEEC_LOGIN_USER - connectionData SHOULD be NULL.
TEEC_LOGIN_GROUP - connectionData MUST point to a uint32_t which contains the group which this Client Application wants to connect as. The Implementation is responsible for securely ensuring that the Client Application instance is actually a member of this group.
TEEC_LOGIN_APPLICATION - connectionData SHOULD be NULL.
TEEC_LOGIN_USER_APPLICATION - connectionData SHOULD be NULL.
TEEC_LOGIN_GROUP_APPLICATION - connectionData MUST point to a uint32_t which contains the group which this Client Application wants to connect as. The Implementation is responsible for securely ensuring that the Client Application instance is actually a member of this group.
An open-session operation MAY optionally carry an Operation Payload, and MAY also be cancellable. When the payload is present the parameter operation MUST point to a TEEC_Operation structure populated by the Client Application. If operation is NULL then no data buffers are exchanged with the Trusted Application, and the operation cannot be cancelled by the Client Application.

The result of this function is returned both in the function TEEC_Result return code and the return origin, stored in the variable pointed to by returnOrigin:
If the return origin is different from TEEC_ORIGIN_TRUSTED_APP, then the return code MUST be one of the defined error codes . If the return code is TEEC_ERROR_CANCEL then it means that the operation was cancelled before it reached the Trusted Application.
If the return origin is TEEC_ORIGIN_TRUSTED_APP, the meaning of the return code depends on the protocol between the Client Application and the Trusted Application. However, if TEEC_SUCCESS is returned, it always means that the session was successfully opened and if the function returns a code different from TEEC_SUCCESS, it means that the session opening failed.

Programmer Error
The following usage of the API is a programmer error:
Calling with a context which is not yet initialized.
Calling with a connectionData set to NULL if connection data is required by the specified connection method.
Calling with an operation containing an invalid paramTypes field, i.e., containing a reserved parameter type or where a parameter type that conflicts with the parent Shared Memory.
Encoding Registered Memory References which refer to Shared Memory blocks allocated within the scope of a different TEE Context.
Attempting to open a Session using the same Session structure concurrently from multiple threads. Multi-threaded Client Applications must use platform-provided locking mechanisms, to ensure that this case does not occur.
Using the same Operation structure for multiple concurrent operations.

Parameters

context	A pointer to an initialized TEE Context.
session	A pointer to a Session structure to open.
destination	A pointer to a structure containing the UUID of the destination Trusted Application
connectionMethod	The method of connection to use
connectionData	Any necessary data required to support the connection method chosen.
operation	A pointer to an Operation containing a set of Parameters to exchange with the Trusted Application, or NULL if no Parameters are to be exchanged or if the operation cannot be cancelled
returnOrigin	A pointer to a variable which will contain the return origin. This field may be NULL if the return origin is not needed.

Returns: TEEC_Result: TEEC_SUCCESS: The session was successfully opened.
TEEC_ERROR_*: An implementation-defined error code for any other error.

Opens a new session between client and trusted application.

Parameters

context	Pointer to the context
session	Pointer to the session
destination	Service UUID
connectionMethod	Connection method
connectionData	Connection data used for authentication
operation	Pointer to optional operation structure
returnOrigin	Pointer to the return origin

Returns: TEEC_Result: TEEC_SUCCESS: The session was successfully opened.
TEEC_ERROR_*: An implementation-defined error code for any other error.

TEEC_Result TEEC_RegisterSharedMemory	(	TEEC_Context *	context,
		TEEC_SharedMemory *	sharedMem
	)

Register a allocated shared memory block.

This function registers a block of existing Client Application memory as a block of Shared Memory within the scope of the specified TEE Context, in accordance with the parameters which have been set by the Client Application inside the sharedMem structure.

The parameter context MUST point to an initialized TEE Context.

The parameter sharedMem MUST point to the Shared Memory structure defining the memory region to register. The Client Application MUST have populated the following fields of the Shared Memory structure before calling this function:
The buffer field MUST point to the memory region to be shared, and MUST not be NULL.
The size field MUST contain the size of the buffer, in bytes. Zero is a valid length for a buffer.
The flags field indicates the intended directions of data flow between the Client Application and the TEE.
The Implementation MUST assume that all other fields in the Shared Memory structure have undefined content.

An Implementation MAY put a hard limit on the size of a single Shared Memory block, defined by the constant TEEC_CONFIG_SHAREDMEM_MAX_SIZE. However note that this function may fail to register a block smaller than this limit due to a low resource condition encountered at run-time.

Programmer Error
The following usage of the API is a programmer error:
Calling with a context which is not initialized.
Calling with a sharedMem which has not be correctly populated in accordance with the specification.
Attempting to initialize the same Shared Memory structure concurrently from multiple threads.Multi-threaded Client Applications must use platform-provided locking mechanisms to ensure that this case does not occur.

Implementor's Notes
This design allows a non-NULL buffer with a size of 0 bytes to allow trivial integration with any implementations of the C library malloc, in which is valid to allocate a zero byte buffer and receive a non- NULL pointer which may not be de-referenced in return. Once successfully registered, the Shared Memory block can be used for efficient data transfers between the Client Application and the Trusted Application. The TEE Client API implementation and the underlying communications infrastructure SHOULD attempt to transfer data in to the TEE without using copies, if this is possible on the underlying implementation, but MUST fall back on data copies if zero-copy cannot be achieved. Client Application developers should be aware that, if the Implementation requires data copies, then Shared Memory registration may allocate a block of memory of the same size as the block being registered.

Parameters

context	A pointer to an initialized TEE Context
sharedMem	A pointer to a Shared Memory structure to register: the buffer, size, and flags fields of the sharedMem structure MUST be set in accordance with the specification described above

Returns: TEEC_Result: TEEC_SUCCESS: The device was successfully opened.
TEEC_ERROR_*: An implementation-defined error code for any other error.

Parameters

context	Pointer to the context
sharedMem	Pointer to the shared memory

Returns: TEEC_Result: TEEC_SUCCESS: The device was successfully opened.
TEEC_ERROR_*: An implementation-defined error code for any other error.

void TEEC_ReleaseSharedMemory ( TEEC_SharedMemory * sharedMem )

Release a shared memory block.

This function deregisters or deallocates a previously initialized block of Shared Memory. For a memory buffer allocated using TEEC_AllocateSharedMemory the Implementation MUST free the underlying memory and the Client Application MUST NOT access this region after this function has been called. In this case the Implementation MUST set the buffer and size fields of the sharedMem structure to NULL and 0 respectively before returning.

For memory registered using TEEC_RegisterSharedMemory the Implementation MUST deregister the underlying memory from the TEE, but the memory region will stay available to the Client Application for other purposes as the memory is owned by it.

The Implementation MUST do nothing if the sharedMem parameter is NULL.

Programmer Error
The following usage of the API is a programmer error:
Attempting to release Shared Memory which is used by a pending operation.
Attempting to release the same Shared Memory structure concurrently from multiple threads. Multi-threaded Client Applications must use platform-provided locking mechanisms to ensure that this case does not occur.

Parameters

sharedMem	A pointer to a valid Shared Memory structure
sharedMem	Pointer to the shared memory

void TEEC_RequestCancellation ( TEEC_Operation * operation )

Request cancellation of pending open session or command invocation.

This function requests the cancellation of a pending open Session operation or a Command invocation operation. As this is a synchronous API, this function must be called from a thread other than the one executing the TEEC_OpenSession or TEEC_InvokeCommand function.

This function just sends a cancellation signal to the TEE and returns immediately; the operation is not guaranteed to have been cancelled when this function returns. In addition, the cancellation request is just a hint; the TEE or the Trusted Application MAY ignore the cancellation request.

It is valid to call this function using a TEEC_Operation structure any time after the Client Application has set the started field of an Operation structure to zero. In particular, an operation can be cancelled before it is actually invoked, during invocation, and after invocation. Note that the Client Application MUST reset the started field to zero each time an Operation structure is used or re-used to open a Session or invoke a Command if the new operation is to be cancellable.

Client Applications MUST NOT reuse the Operation structure for another Operation until the cancelled command has actually returned in the thread executing the TEEC_OpenSession or TEEC_InvokeCommand function.

Detecting cancellation
In many use cases it will be necessary for the Client Application to detect whether the operation was actually cancelled, or whether it completed normally.
In some implementations it MAY be possible for part of the infrastructure to cancel the operation before it reaches the Trusted Application. In these cases the return origin returned by TEEC_OpenSession or TEEC_InvokeCommand MUST be either or TEEC_ORIGIN_API, TEEC_ORIGIN_COMMS, TEEC_ORIGIN_TEE, and the return code MUST be TEEC_ERROR_CANCEL.
If the cancellation request is handled by the Trusted Application itself then the return origin returned by TEEC_OpenSession or TEEC_InvokeCommand MUST be TEE_ORIGIN_TRUSTED_APP, and the return code is defined by the Trusted Application‟s protocol. If possible, Trusted Applications SHOULD use TEEC_ERROR_CANCEL for their return code, but it is accepted that this is not always possible due to conflicts with existing return code definitions in other standards.

Parameters

operation A pointer to a Client Application instantiated Operation structure.

Request cancellation of pending open session or command invocation.

Parameters

operation Pointer to TEEC operation structure

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation