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

Go to the source code of this file.

Data Structures

struct  tfm_msg_body_t
 
struct  partition_static_t
 
struct  partition_t
 
struct  spm_partition_db_t
 
struct  tfm_spm_service_db_t
 
struct  tfm_spm_service_t
 
struct  tfm_conn_handle_t
 

Macros

#define TFM_VERSION_POLICY_RELAXED   0
 
#define TFM_VERSION_POLICY_STRICT   1
 
#define TFM_HANDLE_STATUS_IDLE   0
 
#define TFM_HANDLE_STATUS_ACTIVE   1
 
#define TFM_HANDLE_STATUS_CONNECT_ERROR   2
 
#define PART_REGION_ADDR(partition, region)   (uint32_t)&REGION_NAME(Image$$, partition, region)
 
#define TFM_CONN_HANDLE_MAX_NUM   16
 
#define SPM_INVALID_PARTITION_IDX   (~0U)
 
#define TFM_PARTITION_UNPRIVILEGED_MODE   0
 
#define TFM_PARTITION_PRIVILEGED_MODE   1
 
#define SPM_PART_FLAG_APP_ROT   0x01
 
#define SPM_PART_FLAG_PSA_ROT   0x02
 
#define SPM_PART_FLAG_IPC   0x04
 
#define TFM_PRIORITY_HIGH   THRD_PRIOR_HIGHEST
 
#define TFM_PRIORITY_NORMAL   THRD_PRIOR_MEDIUM
 
#define TFM_PRIORITY_LOW   THRD_PRIOR_LOWEST
 
#define TFM_PRIORITY(LEVEL)   TFM_PRIORITY_##LEVEL
 
#define TFM_MSG_MAGIC   0x15154343
 

Enumerations

enum  spm_err_t {
  SPM_ERR_OK = 0, SPM_ERR_PARTITION_DB_NOT_INIT, SPM_ERR_PARTITION_ALREADY_ACTIVE, SPM_ERR_PARTITION_NOT_AVAILABLE,
  SPM_ERR_INVALID_PARAMETER, SPM_ERR_INVALID_CONFIG, SPM_ERR_OK = 0, SPM_ERR_PARTITION_DB_NOT_INIT,
  SPM_ERR_PARTITION_ALREADY_ACTIVE, SPM_ERR_PARTITION_NOT_AVAILABLE, SPM_ERR_INVALID_PARAMETER, SPM_ERR_INVALID_CONFIG
}
 
enum  tfm_memory_access_e { TFM_MEMORY_ACCESS_RO = 1, TFM_MEMORY_ACCESS_RW = 2 }
 

Functions

enum spm_err_t tfm_spm_db_init (void)
 Initialize partition database. More...
 
uint32_t tfm_spm_partition_get_privileged_mode (uint32_t partition_flags)
 Get the current partition mode. More...
 
void tfm_spm_request_handler (const struct tfm_state_context_t *svc_ctx)
 Handle an SPM request by a secure service. More...
 
uint32_t tfm_spm_partition_get_running_partition_id (void)
 Get the running partition ID. More...
 
struct tfm_conn_handle_ttfm_spm_create_conn_handle (struct tfm_spm_service_t *service, int32_t client_id)
 Create connection handle for client connect. More...
 
int32_t tfm_spm_validate_conn_handle (const struct tfm_conn_handle_t *conn_handle, int32_t client_id)
 Validate connection handle for client connect. More...
 
int32_t tfm_spm_free_conn_handle (struct tfm_spm_service_t *service, struct tfm_conn_handle_t *conn_handle)
 Free connection handle which not used anymore. More...
 
struct tfm_msg_body_ttfm_spm_get_msg_by_signal (struct partition_t *partition, psa_signal_t signal)
 Get the msg context by signal. More...
 
struct partition_ttfm_spm_get_running_partition (void)
 Get current running partition context. More...
 
struct tfm_spm_service_ttfm_spm_get_service_by_sid (uint32_t sid)
 Get the service context by service ID. More...
 
struct tfm_msg_body_ttfm_spm_get_msg_from_handle (psa_handle_t msg_handle)
 Get message context by message handle. More...
 
struct tfm_msg_body_ttfm_spm_get_msg_buffer_from_conn_handle (struct tfm_conn_handle_t *conn_handle)
 Get message context by connect handle. More...
 
void tfm_spm_fill_msg (struct tfm_msg_body_t *msg, struct tfm_spm_service_t *service, psa_handle_t handle, int32_t type, int32_t client_id, psa_invec *invec, size_t in_len, psa_outvec *outvec, size_t out_len, psa_outvec *caller_outvec)
 Fill the message for PSA client call. More...
 
int32_t tfm_spm_send_event (struct tfm_spm_service_t *service, struct tfm_msg_body_t *msg)
 Send message and wake up the SP who is waiting on message queue, block the current thread and scheduler triggered. More...
 
int32_t tfm_spm_check_client_version (struct tfm_spm_service_t *service, uint32_t version)
 Check the client version according to version policy. More...
 
int32_t tfm_spm_check_authorization (uint32_t sid, struct tfm_spm_service_t *service, bool ns_caller)
 Check the client access authorization. More...
 
int32_t tfm_memory_check (const void *buffer, size_t len, bool ns_caller, enum tfm_memory_access_e access, uint32_t privileged)
 Check the memory reference is valid. More...
 
void tfm_pendsv_do_schedule (struct tfm_arch_ctx_t *p_actx)
 
uint32_t tfm_spm_init (void)
 SPM initialization implementation. More...
 
void tfm_spm_enable_irq (uint32_t *args)
 SVC handler of enabling irq_line of the specified irq_signal. More...
 
void tfm_spm_disable_irq (uint32_t *args)
 SVC handler of disabling irq_line of the specified irq_signal. More...
 
void tfm_spm_validate_caller (struct partition_t *p_cur_sp, uint32_t *p_ctx, uint32_t exc_return, bool ns_caller)
 Validate the whether NS caller re-enter. More...
 
psa_handle_t tfm_spm_to_user_handle (struct tfm_conn_handle_t *handle_instance)
 Converts a handle instance into a corresponded user handle. More...
 
struct tfm_conn_handle_ttfm_spm_to_handle_instance (psa_handle_t user_handle)
 Converts a user handle into a corresponded handle instance. More...
 
void tfm_core_handler_mode (void)
 Move to handler mode by a SVC for specific purpose. More...
 
int32_t tfm_spm_set_rhandle (struct tfm_spm_service_t *service, struct tfm_conn_handle_t *conn_handle, void *rhandle)
 Set reverse handle value for connection. More...
 
void update_caller_outvec_len (struct tfm_msg_body_t *msg)
 
void notify_with_signal (int32_t partition_id, psa_signal_t signal)
 notify the partition with the signal. More...
 
int32_t get_irq_line_for_signal (int32_t partition_id, psa_signal_t signal, IRQn_Type *irq_line)
 Return the IRQ line number associated with a signal. More...
 

Macro Definition Documentation

#define PART_REGION_ADDR (   partition,
  region 
)    (uint32_t)&REGION_NAME(Image$$, partition, region)

Definition at line 27 of file spm_ipc.h.

#define SPM_INVALID_PARTITION_IDX   (~0U)

Definition at line 32 of file spm_ipc.h.

#define SPM_PART_FLAG_APP_ROT   0x01

Definition at line 38 of file spm_ipc.h.

#define SPM_PART_FLAG_IPC   0x04

Definition at line 40 of file spm_ipc.h.

#define SPM_PART_FLAG_PSA_ROT   0x02

Definition at line 39 of file spm_ipc.h.

#define TFM_CONN_HANDLE_MAX_NUM   16

Definition at line 30 of file spm_ipc.h.

#define TFM_HANDLE_STATUS_ACTIVE   1

Definition at line 24 of file spm_ipc.h.

#define TFM_HANDLE_STATUS_CONNECT_ERROR   2

Definition at line 25 of file spm_ipc.h.

#define TFM_HANDLE_STATUS_IDLE   0

Definition at line 23 of file spm_ipc.h.

#define TFM_MSG_MAGIC   0x15154343

Definition at line 47 of file spm_ipc.h.

#define TFM_PARTITION_PRIVILEGED_MODE   1

Definition at line 36 of file spm_ipc.h.

#define TFM_PARTITION_UNPRIVILEGED_MODE   0

Definition at line 35 of file spm_ipc.h.

#define TFM_PRIORITY (   LEVEL)    TFM_PRIORITY_##LEVEL

Definition at line 45 of file spm_ipc.h.

#define TFM_PRIORITY_HIGH   THRD_PRIOR_HIGHEST

Definition at line 42 of file spm_ipc.h.

#define TFM_PRIORITY_LOW   THRD_PRIOR_LOWEST

Definition at line 44 of file spm_ipc.h.

#define TFM_PRIORITY_NORMAL   THRD_PRIOR_MEDIUM

Definition at line 43 of file spm_ipc.h.

#define TFM_VERSION_POLICY_RELAXED   0

Definition at line 20 of file spm_ipc.h.

#define TFM_VERSION_POLICY_STRICT   1

Definition at line 21 of file spm_ipc.h.

Enumeration Type Documentation

enum spm_err_t
Enumerator
SPM_ERR_OK 
SPM_ERR_PARTITION_DB_NOT_INIT 
SPM_ERR_PARTITION_ALREADY_ACTIVE 
SPM_ERR_PARTITION_NOT_AVAILABLE 
SPM_ERR_INVALID_PARAMETER 
SPM_ERR_INVALID_CONFIG 
SPM_ERR_OK 
SPM_ERR_PARTITION_DB_NOT_INIT 
SPM_ERR_PARTITION_ALREADY_ACTIVE 
SPM_ERR_PARTITION_NOT_AVAILABLE 
SPM_ERR_INVALID_PARAMETER 
SPM_ERR_INVALID_CONFIG 

Definition at line 49 of file spm_ipc.h.

Enumerator
TFM_MEMORY_ACCESS_RO 
TFM_MEMORY_ACCESS_RW 

Definition at line 168 of file spm_ipc.h.

Function Documentation

int32_t get_irq_line_for_signal ( int32_t  partition_id,
psa_signal_t  signal,
IRQn_Type *  irq_line 
)

Return the IRQ line number associated with a signal.

Parameters
[in]partition_idThe ID of the partition in which we look for the signal.
[in]signalThe signal we do the query for.
[out]irq_lineThe irq line associated with signal
Return values
IPC_SUCCESSExecution successful, irq_line contains a valid value.
IPC_ERROR_GENERICThere was an error finding the IRQ line for the signal. irq_line is unchanged.

Definition at line 881 of file spm_ipc.c.

Here is the caller graph for this function:

void notify_with_signal ( int32_t  partition_id,
psa_signal_t  signal 
)

notify the partition with the signal.

Parameters
[in]partition_idThe ID of the partition to be notified.
[in]signalThe signal that the partition is to be notified with.
Return values
voidSuccess.
Does not returnIf partition_id is invalid.

Definition at line 831 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

void tfm_core_handler_mode ( void  )

Move to handler mode by a SVC for specific purpose.

Definition at line 157 of file tfm_core_svcalls_ipc.c.

Here is the caller graph for this function:

int32_t tfm_memory_check ( const void *  buffer,
size_t  len,
bool  ns_caller,
enum tfm_memory_access_e  access,
uint32_t  privileged 
)

Check the memory reference is valid.

Parameters
[in]bufferPointer of memory reference
[in]lenLength of memory reference in bytes
[in]ns_callerFrom non-secure caller
[in]accessType of access specified by the tfm_memory_access_e
[in]privilegedPrivileged mode or unprivileged mode: TFM_PARTITION_UNPRIVILEGED_MODE TFM_PARTITION_PRIVILEGED_MODE
Return values
IPC_SUCCESSSuccess
IPC_ERROR_BAD_PARAMETERSBad parameters input
IPC_ERROR_MEMORY_CHECKCheck failed

Definition at line 596 of file spm_ipc.c.

Here is the caller graph for this function:

void tfm_pendsv_do_schedule ( struct tfm_arch_ctx_t p_actx)

Definition at line 756 of file spm_ipc.c.

Here is the call graph for this function:

int32_t tfm_spm_check_authorization ( uint32_t  sid,
struct tfm_spm_service_t service,
bool  ns_caller 
)

Check the client access authorization.

Parameters
[in]sidTarget RoT Service identity
[in]serviceTarget service context pointer, which can be get by partition management functions
[in]ns_callerWhether from NS caller
Return values
IPC_SUCCESSSuccess
IPC_ERROR_GENERICAuthorization check failed

Definition at line 416 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

int32_t tfm_spm_check_client_version ( struct tfm_spm_service_t service,
uint32_t  version 
)

Check the client version according to version policy.

Parameters
[in]serviceTarget service context pointer, which can be get by partition management functions
[in]versionClient support version
Return values
IPC_SUCCESSSuccess
IPC_ERROR_BAD_PARAMETERSBad parameters input
IPC_ERROR_VERSIONCheck failed

Definition at line 394 of file spm_ipc.c.

Here is the caller graph for this function:

struct tfm_conn_handle_t* tfm_spm_create_conn_handle ( struct tfm_spm_service_t service,
int32_t  client_id 
)

Create connection handle for client connect.

Parameters
[in]serviceTarget service context pointer
[in]client_idPartition ID of the sender of the message
Return values
NULLCreate failed
Not NULLService handle created

Definition at line 137 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

enum spm_err_t tfm_spm_db_init ( void  )

Initialize partition database.

Returns
Error code spm_err_t

Definition at line 1415 of file spm_func.c.

Here is the call graph for this function:

void tfm_spm_disable_irq ( uint32_t *  args)

SVC handler of disabling irq_line of the specified irq_signal.

Parameters
[in]argsInclude all input arguments: irq_signal.
Return values
voidSuccess.
Does not returnThe call is invalid, one or more of the following are true:
  • irq_signal is not an interrupt signal.
  • irq_signal indicates more than one signal.

Definition at line 925 of file spm_ipc.c.

Here is the call graph for this function:

void tfm_spm_enable_irq ( uint32_t *  args)

SVC handler of enabling irq_line of the specified irq_signal.

Parameters
[in]argsInclude all input arguments: irq_signal.
Return values
voidSuccess.
Does not returnThe call is invalid, one or more of the following are true:
  • irq_signal is not an interrupt signal.
  • irq_signal indicates more than one signal.

Definition at line 897 of file spm_ipc.c.

Here is the call graph for this function:

void tfm_spm_fill_msg ( struct tfm_msg_body_t msg,
struct tfm_spm_service_t service,
psa_handle_t  handle,
int32_t  type,
int32_t  client_id,
psa_invec invec,
size_t  in_len,
psa_outvec outvec,
size_t  out_len,
psa_outvec caller_outvec 
)

Fill the message for PSA client call.

Parameters
[in]msgService Message Queue buffer pointer
[in]serviceTarget service context pointer, which can be obtained by partition management functions
[in]handleConnect handle return by psa_connect().
[in]typeMessage type, PSA_IPC_CONNECT, PSA_IPC_CALL or PSA_IPC_DISCONNECT
[in]client_idPartition ID of the sender of the message
[in]invecArray of input psa_invec structures
[in]in_lenNumber of input psa_invec structures
[in]outvecArray of output psa_outvec structures
[in]out_lenNumber of output psa_outvec structures
[in]caller_outvecArray of caller output psa_outvec structures

Definition at line 498 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

int32_t tfm_spm_free_conn_handle ( struct tfm_spm_service_t service,
struct tfm_conn_handle_t conn_handle 
)

Free connection handle which not used anymore.

Parameters
[in]serviceTarget service context pointer
[in]conn_handleConnection handle created by tfm_spm_create_conn_handle()
Return values
IPC_SUCCESSSuccess
IPC_ERROR_BAD_PARAMETERSBad parameters input
Does not returnPanic for not find service by handle

Definition at line 179 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

struct tfm_msg_body_t* tfm_spm_get_msg_buffer_from_conn_handle ( struct tfm_conn_handle_t conn_handle)

Get message context by connect handle.

Parameters
[in]conn_handleService connect handle.
Returns
The message body context pointer tfm_msg_body_t structures

Definition at line 491 of file spm_ipc.c.

Here is the caller graph for this function:

struct tfm_msg_body_t* tfm_spm_get_msg_by_signal ( struct partition_t partition,
psa_signal_t  signal 
)

Get the msg context by signal.

Parameters
[in]partitionPartition context pointer partition_t structures
[in]signalSignal associated with inputs to the Secure Partition, psa_signal_t
Return values
NULLFailed
Not NULLTarget service context pointer, tfm_msg_body_t structures

Definition at line 233 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

struct tfm_msg_body_t* tfm_spm_get_msg_from_handle ( psa_handle_t  msg_handle)

Get message context by message handle.

Parameters
[in]msg_handleMessage handle which is a reference generated by the SPM to a specific message.
Returns
The message body context pointer tfm_msg_body_t structures

Definition at line 450 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

struct partition_t* tfm_spm_get_running_partition ( void  )

Get current running partition context.

Return values
NULLFailed
Not NULLReturn the parttion context pointer partition_t structures

Definition at line 384 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

struct tfm_spm_service_t* tfm_spm_get_service_by_sid ( uint32_t  sid)

Get the service context by service ID.

Parameters
[in]sidRoT Service identity
Return values
NULLFailed
Not NULLTarget service context pointer, tfm_spm_service_t structures

Definition at line 351 of file spm_ipc.c.

Here is the caller graph for this function:

uint32_t tfm_spm_init ( void  )

SPM initialization implementation.

This function must be called under handler mode.

Return values
Thisfunction returns an EXC_RETURN value. Other faults would panic the execution and never returned.

Definition at line 641 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t tfm_spm_partition_get_privileged_mode ( uint32_t  partition_flags)

Get the current partition mode.

Parameters
[in]partition_flagsFlags of current partition
Return values
TFM_PARTITION_PRIVILEGED_MODEPrivileged mode
TFM_PARTITION_UNPRIVILEGED_MODEUnprivileged mode

Definition at line 713 of file spm_func.c.

Here is the caller graph for this function:

uint32_t tfm_spm_partition_get_running_partition_id ( void  )

Get the running partition ID.

Returns
Returns the partition ID

Definition at line 584 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

void tfm_spm_request_handler ( const struct tfm_state_context_t svc_ctx)

Handle an SPM request by a secure service.

Parameters
[in]svc_ctxThe stacked SVC context

Definition at line 1382 of file spm_func.c.

Here is the call graph for this function:

int32_t tfm_spm_send_event ( struct tfm_spm_service_t service,
struct tfm_msg_body_t msg 
)

Send message and wake up the SP who is waiting on message queue, block the current thread and scheduler triggered.

Parameters
[in]serviceTarget service context pointer, which can be obtained by partition management functions
[in]msgmessage created by tfm_spm_create_msg() tfm_msg_body_t structures
Return values
IPC_SUCCESSSuccess
IPC_ERROR_BAD_PARAMETERSBad parameters input
IPC_ERROR_GENERICFailed to enqueue message to service message queue

Definition at line 556 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

int32_t tfm_spm_set_rhandle ( struct tfm_spm_service_t service,
struct tfm_conn_handle_t conn_handle,
void *  rhandle 
)

Set reverse handle value for connection.

Parameters
[in]serviceTarget service context pointer
[in]conn_handleConnection handle created by tfm_spm_create_conn_handle()
[in]rhandlerhandle need to save
Return values
IPC_SUCCESSSuccess
IPC_ERROR_BAD_PARAMETERSBad parameters input
Does not returnPanic for not find handle node

Definition at line 196 of file spm_ipc.c.

Here is the caller graph for this function:

struct tfm_conn_handle_t* tfm_spm_to_handle_instance ( psa_handle_t  user_handle)

Converts a user handle into a corresponded handle instance.

Definition at line 121 of file spm_ipc.c.

Here is the caller graph for this function:

psa_handle_t tfm_spm_to_user_handle ( struct tfm_conn_handle_t handle_instance)

Converts a handle instance into a corresponded user handle.

Definition at line 93 of file spm_ipc.c.

Here is the caller graph for this function:

void tfm_spm_validate_caller ( struct partition_t p_cur_sp,
uint32_t *  p_ctx,
uint32_t  exc_return,
bool  ns_caller 
)

Validate the whether NS caller re-enter.

Parameters
[in]p_cur_spPointer to current partition.
[in]p_ctxPointer to current stack context.
[in]exc_returnEXC_RETURN value.
[in]ns_callerIf 'true', call from non-secure client. Or from secure client.
Return values
voidSuccess.

Definition at line 953 of file spm_ipc.c.

Here is the call graph for this function:

int32_t tfm_spm_validate_conn_handle ( const struct tfm_conn_handle_t conn_handle,
int32_t  client_id 
)

Validate connection handle for client connect.

Parameters
[in]conn_handleHandle to be validated
[in]client_idPartition ID of the sender of the message
Return values
IPC_SUCCESSSuccess
IPC_ERROR_GENERICInvalid handle

Definition at line 161 of file spm_ipc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

void update_caller_outvec_len ( struct tfm_msg_body_t msg)

Definition at line 807 of file spm_ipc.c.

Here is the caller graph for this function: