TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
client.h File Reference
#include <stddef.h>
#include <stdint.h>
#include "psa/error.h"
Include dependency graph for client.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  psa_invec
 
struct  psa_outvec
 

Macros

#define PSA_FRAMEWORK_VERSION   (0x0100u)
 
#define PSA_VERSION_NONE   (0u)
 
#define PSA_NULL_HANDLE   ((psa_handle_t)0)
 
#define PSA_HANDLE_IS_VALID(handle)   ((psa_handle_t)(handle) > 0)
 
#define PSA_HANDLE_TO_ERROR(handle)   ((psa_status_t)(handle))
 
#define PSA_MAX_IOVEC   (4u)
 
#define PSA_IPC_CALL   (0)
 

Typedefs

typedef int32_t psa_handle_t
 
typedef struct psa_invec psa_invec
 
typedef struct psa_outvec psa_outvec
 

Functions

uint32_t psa_framework_version (void)
 Retrieve the version of the PSA Framework API that is implemented. More...
 
uint32_t psa_version (uint32_t sid)
 Retrieve the version of an RoT Service or indicate that it is not present on this system. More...
 
psa_handle_t psa_connect (uint32_t sid, uint32_t version)
 Connect to an RoT Service by its SID. More...
 
psa_status_t psa_call (psa_handle_t handle, int32_t type, const psa_invec *in_vec, size_t in_len, psa_outvec *out_vec, size_t out_len)
 Call an RoT Service on an established connection. More...
 
void psa_close (psa_handle_t handle)
 Close a connection to an RoT Service. More...
 

Macro Definition Documentation

#define PSA_FRAMEWORK_VERSION   (0x0100u)

The version of the PSA Framework API that is being used to build the calling firmware.

Definition at line 26 of file client.h.

#define PSA_HANDLE_IS_VALID (   handle)    ((psa_handle_t)(handle) > 0)

Tests whether a handle value returned by psa_connect() is valid.

Definition at line 43 of file client.h.

#define PSA_HANDLE_TO_ERROR (   handle)    ((psa_status_t)(handle))

Converts the handle value returned from a failed call psa_connect() into an error code.

Definition at line 49 of file client.h.

#define PSA_IPC_CALL   (0)

An IPC message type that indicates a generic client request.

Definition at line 59 of file client.h.

#define PSA_MAX_IOVEC   (4u)

Maximum number of input and output vectors for a request to psa_call().

Definition at line 54 of file client.h.

#define PSA_NULL_HANDLE   ((psa_handle_t)0)

The zero-value null handle can be assigned to variables used in clients and RoT Services, indicating that there is no current connection or message.

Definition at line 38 of file client.h.

#define PSA_VERSION_NONE   (0u)

Return value from psa_version() if the requested RoT Service is not present in the system.

Definition at line 32 of file client.h.

Typedef Documentation

typedef int32_t psa_handle_t

Definition at line 61 of file client.h.

typedef struct psa_invec psa_invec

A read-only input memory region provided to an RoT Service.

typedef struct psa_outvec psa_outvec

A writable output memory region provided to an RoT Service.

Function Documentation

psa_status_t psa_call ( psa_handle_t  handle,
int32_t  type,
const psa_invec in_vec,
size_t  in_len,
psa_outvec out_vec,
size_t  out_len 
)

Call an RoT Service on an established connection.

Parameters
[in]handleA handle to an established connection.
[in]typeThe request type. Must be zero( PSA_IPC_CALL) or positive.
[in]in_vecArray of input psa_invec structures.
[in]in_lenNumber of input psa_invec structures.
[in,out]out_vecArray of output psa_outvec structures.
[in]out_lenNumber of output psa_outvec structures.
Return values
>=0RoT Service-specific status value.
<0RoT Service-specific error code.
PSA_ERROR_PROGRAMMER_ERRORThe connection has been terminated by the RoT Service. The call is a PROGRAMMER ERROR if one or more of the following are true:
  • An invalid handle was passed.
  • The connection is already handling a request.
  • type < 0.
  • An invalid memory reference was provided.
  • in_len + out_len > PSA_MAX_IOVEC.
  • The message is unrecognized by the RoT Service or incorrectly formatted.

Definition at line 47 of file psa_client.c.

Here is the call graph for this function:

Here is the caller graph for this function:

void psa_close ( psa_handle_t  handle)

Close a connection to an RoT Service.

Parameters
[in]handleA handle to an established connection, or the null handle.
Return values
voidSuccess.
PROGRAMMER ERRORThe call is a PROGRAMMER ERROR if one or more of the following are true:
  • An invalid handle was provided that is not the null handle.
  • The connection is currently handling a request.

Definition at line 63 of file psa_client.c.

Here is the call graph for this function:

Here is the caller graph for this function:

psa_handle_t psa_connect ( uint32_t  sid,
uint32_t  version 
)

Connect to an RoT Service by its SID.

Parameters
[in]sidID of the RoT Service to connect to.
[in]versionRequested version of the RoT Service.
Return values
>0 A handle for the connection.
PSA_ERROR_CONNECTION_REFUSEDThe SPM or RoT Service has refused the connection.
PSA_ERROR_CONNECTION_BUSYThe SPM or RoT Service cannot make the connection at the moment.
PROGRAMMER ERRORThe call is a PROGRAMMER ERROR if one or more of the following are true:
  • The RoT Service ID is not present.
  • The RoT Service version is not supported.
  • The caller is not allowed to access the RoT service.

Definition at line 30 of file psa_client.c.

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t psa_framework_version ( void  )

Retrieve the version of the PSA Framework API that is implemented.

Returns
version The version of the PSA Framework implementation that is providing the runtime services to the caller. The major and minor version are encoded as follows:
  • version[15:8] – major version number.
  • version[7:0] – minor version number.

Definition at line 14 of file psa_client.c.

Here is the call graph for this function:

uint32_t psa_version ( uint32_t  sid)

Retrieve the version of an RoT Service or indicate that it is not present on this system.

Parameters
[in]sidID of the RoT Service to query.
Return values
PSA_VERSION_NONEThe RoT Service is not implemented, or the caller is not permitted to access the service.
>0 The version of the implemented RoT Service.

Definition at line 22 of file psa_client.c.

Here is the call graph for this function: