Secure Request Framework

General Description

The Secure Request Framework (SRF) exists to provide a reusable infastructure for implementing multiple secure operations via a single non-secure-callable entry point.

This framework is designed to be generic with no dependency on or knowledge of any particular hardware operation. It can be used directly by user code.

Through the SRF, the secure world exposes one or more operations, which are roughly equivalent to a function. These operations can be combined into a module - a unit of integration between different entities which wish to expose their operations. For example, the Peripheral Driver Library (PDL) would be one module.

The non-secure world invokes an operation by submitting a secure request via the mtb_srf_request_submit API. This request is then passed to the secure world, where its memory addresses are validated, as are the permissions required to perform the operation. A default validation strategy is performed through mtb_srf_memory_validate, and further operation specific validation should be done inside the operation itself. The default mtb_srf_memory_validate API checks that all memory passed in is accessible to the NS side, ensured the minimum number of inVec and outVec are present, and that a legal number of ioVec (input-output vectors) have been provided (discussed further below). This API is defined weakly to enable overriding with a custom implementation.

The mtb_srf_request_submit API accepts inVec and outVec arrays. The max total number of vectors cannot exceed MTB_SRF_MAX_IOVEC. That is, should the max ioVec be 4, legal combinations could be one inVec and three outVec, two of each, or three inVec and one outVec. Unused vectors should be set to NULL.

Note

It is possible to completely disable the SRF by adding a define for CY_SRF_DISABLE in the cases where the SRF library is included as a default dependency but not used.

Prerequisites

This framework requires the user manage a mtb_srf_config.h file that contains macros for the various modules that use the SRF. The file comes with the default macros for user and PDL module IDs. Should a library be added to the project that uses SRF, that library should generate a relevant error message requesting that its module ID is added to the mtb_srf_config.h file. The exact values of the module IDs do not matter, as long as they are unique and unsigned integers. The number of SRF modules should be defined as MTB_SRF_MODULE_COUNT. The SRF uses this macro internally to determine how many module IDs exist in a given project.

Code Snippets

Register module operation

 
cy_stc_smif_context_t SMIFContext;
cy_stc_smif_mem_config_t memConfig;
 
/* These macros would be declared in mtb_srf_config.h, a file owned by the user */
// Our modules - for brevity just including a User module
#define MTB_SRF_MODULE_USER_DEMO        (0U)
 
// A couple submodule IDs
typedef enum
{
    APP_SRF_USER_SUBMODULE_SMIF,
    APP_SRF_USER_SUBMODULE_SYSCLK,
    APP_SRF_USER_SUBMODULE_MAX = APP_SRF_USER_SUBMODULE_SYSCLK
} CY_PDL_SRF_SUBMODULE;
 
// And operations IDs for one of our submodules
#define APP_SRF_SMIF_OP_WRITE           (0U)
#define APP_SRF_SMIF_OP_READ            (1U)
 
 
// Implementation for the SMIF_WRITE operation
cy_rslt_t app_srf_submod_smif_write_fn(mtb_srf_input_ns_t* inputs_ns,
                                       mtb_srf_output_ns_t* outputs_ns,
                                       mtb_srf_invec_ns_t* inputs_ptr_ns,
                                       uint8_t inputs_ptr_ns_cnt,
                                       mtb_srf_outvec_ns_t* outputs_ptr_ns,
                                       uint8_t outputs_ptr_cnt_ns)
{
    // Depending on the application needs, this function might validate the target address before
    // performing the write
    cy_rslt_t result = (cy_rslt_t)Cy_SMIF_MemWrite(inputs_ns->request.base,
                                                   &memConfig, inputs_ns->input_values[0],
                                                   (const uint8_t*)inputs_ptr_ns[0].base,
                                                   inputs_ptr_ns[0].len, &SMIFContext);
    CY_UNUSED_PARAMETER(outputs_ns);
    CY_UNUSED_PARAMETER(outputs_ptr_ns);
    CY_UNUSED_PARAMETER(inputs_ptr_ns_cnt);
    CY_UNUSED_PARAMETER(outputs_ptr_cnt_ns);
    return result;
}
 
 
// Define what resources the operation may act on and if they're read-only or if writing is allowed
mtb_srf_permission_s_t app_srf_smif_permission[] =
{
    {
        .base = (void*)SMIF0_BASE,
        .sub_block = 0,
        .write_allowed = true,
    },
};
 
// Bundle these into an operation structure.
mtb_srf_op_s_t app_srf_smif_operations[] =
{
    {
        .module_id = MTB_SRF_MODULE_USER_DEMO,
        .submodule_id = APP_SRF_USER_SUBMODULE_SMIF,
        .op_id = APP_SRF_SMIF_OP_WRITE,
        .write_required = true,
        .impl = app_srf_submod_smif_write_fn,
        .input_values_len = 1U * sizeof(uint32_t), /* Value up to application - our
                                                      app_srf_submod_smif_write_fn only
                                                      needs one uint32_t (address)*/
        .output_values_len = 0UL,
        .input_len ={ 0UL, 0UL,   0UL   },
        .needs_copy ={ false, false, false },
        .output_len ={ 0UL, 0UL,   0UL   },
        .allowed_rsc = &app_srf_smif_permission[0],
        .num_allowed = sizeof(app_srf_smif_permission) / sizeof(app_srf_smif_permission[0]),
    },
};
 
/* Left empty for brevity */
mtb_srf_op_s_t app_srf_sysclk_operations[] = { 0 };
 
mtb_srf_op_s_t* app_srf_operations[APP_SRF_USER_SUBMODULE_MAX + 1] =
{
    app_srf_smif_operations,
    app_srf_sysclk_operations,
};
 
size_t app_srf_num_operations[APP_SRF_USER_SUBMODULE_MAX + 1] =
{
    sizeof(app_srf_smif_operations) / sizeof(app_srf_smif_operations[0]),
    sizeof(app_srf_sysclk_operations) / sizeof(app_srf_sysclk_operations[0]),
};
 
mtb_srf_module_s_t app_srf_service =
{
    .module_id          = MTB_SRF_MODULE_USER_DEMO,
    .op_by_submod       = app_srf_operations,
    .num_op_by_submod   = app_srf_num_operations,
    .num_submod         = sizeof(app_srf_num_operations) / sizeof(app_srf_num_operations[0]),
};
 
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_register_module_api
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_register_module_api(void)
{
    cy_rslt_t result = CY_RSLT_SUCCESS;
    // Pre-existing init logic
 
    result = mtb_srf_init(&cybsp_srf_context);
    if (result != CY_RSLT_SUCCESS)
    {
        result = mtb_srf_module_register(&cybsp_srf_context, &app_srf_service);
    }
 
    (void)result;
    return result;
}
 
 
#endif /* defined(COMPONENT_SECURE_DEVICE) */
 

Submit request operation

 
/* These macros would be declared in mtb_srf_config.h, a file owned by the user */
#define MTB_SRF_MODULE_PDL_DEMO             (0U)
 
// A couple submodule IDs
typedef enum
{
    CY_PDL_SRF_SUBMODULE_SYSCLK,
    CY_PDL_SRF_SUBMODULE_SYSPM,
    CY_PDL_SRF_SUBMODULE_MAX = CY_PDL_SRF_SUBMODULE_SYSPM
} CY_PDL_SRF_SUBMODULE;
 
// CY_PDL_SRF_SUBMODULE_SYSCLK
#define CY_SYSCLK_SRF_OP_HF_GET_FREQUENCY   (0U)
#define CY_SYSCLK_SRF_OP_HF_GET_ENABLED     (1U)
// CY_PDL_SRF_SUBMODULE_SYSPM
#define CY_SYSPM_SRF_OP_ENTER_SLEEP         (0U)
#define CY_SYSPM_SRF_OP_ENTER_DEEPSLEEP     (1U)
 
 
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_submit_request_api
//--------------------------------------------------------------------------------------------------
cy_rslt_t mtb_srf_request_submit_api(mtb_srf_invec_ns_t* inVec_ns, uint8_t inVec_cnt_ns,
                                     mtb_srf_outvec_ns_t* outVec_ns, uint8_t outVec_cnt_ns)
{
    // Example of overriding the default WEAK mtb_srf_request_submit
    cy_rslt_t result = CY_RSLT_SUCCESS;
 
    // Some logic added here
 
    // A custom mtb_srf_request_submit must ultimately call mtb_srf_request_execute
    result = mtb_srf_request_execute(&cybsp_srf_context, inVec_ns, inVec_cnt_ns, outVec_ns,
                                     outVec_cnt_ns);
 
    return result;
}
 
 
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_submit_request_api
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_submit_request_api(void)
{
    cy_rslt_t result = CY_RSLT_SUCCESS;
 
    // Assuming an already initialized request pool
 
    mtb_srf_invec_ns_t* inVec = NULL;
    mtb_srf_outvec_ns_t* outVec = NULL;
 
    result = mtb_srf_pool_allocate(&cy_pdl_srf_default_pool, &inVec, &outVec, 1000);
    if (result != CY_RSLT_SUCCESS)
    {
        return result;
    }
 
    /* Our first inVec is always a mtb_srf_input_ns_t */
    mtb_srf_input_ns_t* input = (mtb_srf_input_ns_t*)(inVec[0].base);
    mtb_srf_output_ns_t* output = (mtb_srf_output_ns_t*)(outVec[0].base);
 
    input->request.module_id = MTB_SRF_MODULE_PDL_DEMO;
    input->request.submodule_id = CY_PDL_SRF_SUBMODULE_SYSCLK;
    input->request.op_id = CY_SYSCLK_SRF_OP_HF_GET_FREQUENCY;
 
    input->request.base = NULL; /* Base address not required for this function */
    input->request.sub_block = 0UL; /* sub block is hfclk instance */
 
    input->len = 0UL;
    output->len = 1UL * sizeof(uint32_t); /* Store HF Clk Frequency */
 
    uint8_t inVec_cnt = 1;
    uint8_t outVec_cnt = 1;
    result = mtb_srf_request_submit(inVec, inVec_cnt, outVec, outVec_cnt);
 
    return result;
}
 
 

Data Structures
struct	mtb_srf_permission_s_t
	Permission structure. More...
struct	mtb_srf_op_s_t
	Operation description structure. More...
struct	mtb_srf_module_s_t
	Module structure. More...
struct	mtb_srf_context_s_t
	Context structure. More...
struct	mtb_srf_protection_range_s_t
	Structure to define if a range of memory is secure. More...
struct	mtb_srf_memory_protection_s_t
	Structure to contain all different memories security regions. More...

Macros
#define	MTB_SRF_ERR_BAD_PARAM    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 0)
	An invalid parameter value is passed in.
#define	MTB_SRF_ERR_UNKNOWN_OPERATION    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 1)
	Unknown operation requested.
#define	MTB_SRF_ERR_UNKNOWN_MODULE    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 2)
	Unknown module requested.
#define	MTB_SRF_ERR_SECURITY_POLICY_VIOLATION    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 3)
	Request violates resource security permissions.
#define	MTB_SRF_ERR_MODULE_ID_INVALID    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 4)
	Module index provided at registration is invalid.
#define	MTB_SRF_ERR_ALLOCATE_FREE    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 5)
	Failed to allocate/free secure request.
#define	MTB_SRF_ERR_RINGBUF_EMPTY    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 6)
	Ringbuffer is empty.
#define	MTB_SRF_ERR_RINGBUF_FULL    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 7)
	Ringbuffer is full.
#define	MTB_SRF_ERR_ARGBUFF_FULL    CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_SRF, 8)
	No space left in secure argument buffer.
#define	_MTB_SRF_DATA_ALIGN
	This define can be used for aligning address of the data structures with enabled Data Cache.
#define	MTB_SRF_NEVER_TIMEOUT   (0xFFFFFFFFU)
	Indicates that an operation should wait indefinitely.

Typedefs
typedef cy_rslt_t(*	mtb_srf_op_fn_t) (mtb_srf_input_ns_t *inputs_ns, mtb_srf_output_ns_t *outputs_ns, mtb_srf_invec_ns_t *inputs_ptr_ns, uint8_t inputs_ptr_cnt_ns, mtb_srf_outvec_ns_t *outputs_ptr_ns, uint8_t outputs_ptr_cnt_ns)
	Function pointer to the operation. More...

Functions
cy_rslt_t	mtb_srf_init (mtb_srf_context_s_t *context_s)
	Initialize the SRF. More...
cy_rslt_t	mtb_srf_module_register (mtb_srf_context_s_t *context_s, mtb_srf_module_s_t *module_s)
	Register a module for use. More...
cy_rslt_t	mtb_srf_memory_validate (volatile mtb_srf_invec_ns_t *inVec_ns, uint8_t inVec_cnt_ns, volatile mtb_srf_outvec_ns_t *outVec_ns, uint8_t outVec_cnt_ns, mtb_srf_invec_ns_t *inVec, mtb_srf_outvec_ns_t *outVec)
	Validate invec/outvec memory address on non-secure's permission. More...
cy_rslt_t	mtb_srf_request_execute (mtb_srf_context_s_t *context_s, mtb_srf_invec_ns_t *inVec_ns, uint8_t inVec_cnt_ns, mtb_srf_outvec_ns_t *outVec_ns, uint8_t outVec_cnt_ns)
	Execute a request. More...
bool	mtb_srf_is_memory_ns_accessible (uint32_t addr, size_t size)
	Check if an address is non secure accessible. More...
cy_rslt_t	mtb_srf_copy_input_value (void *input, size_t size, mtb_srf_input_ns_t *inputs_ns)
	Copy the operation defined structure value to input_values and validate the structure size If size, which is defined in secure-side, is not eqaul to size of the input_values array, it returns MTB_SRF_ERR_BAD_PARAM. More...
cy_rslt_t	mtb_srf_copy_output_value (mtb_srf_output_ns_t *outputs_ns, void *output, size_t size)
	Copy the operation defined structure value to input_values and validate the structure size If size, which is defined in secure-side, is not eqaul to size of the output_values array, it returns MTB_SRF_ERR_BAD_PARAM. More...
cy_rslt_t	mtb_srf_request_submit (mtb_srf_invec_ns_t *inVec_ns, uint8_t inVec_cnt_ns, mtb_srf_outvec_ns_t *outVec_ns, uint8_t outVec_cnt_ns)
	Submit a request from the non-secure side to the secure. More...

---

Data Structure Documentation

mtb_srf_permission_s_t

struct mtb_srf_permission_s_t

Data Fields
void *	base	Register base address for the hardware resource. If not applicable, set to NULL.
uint16_t	sub_block	Sub-block index, if applicable. E.g. TCPWM counter index. If not applicable, set to 0.
bool	write_allowed	If true, operations that modify the hardware state are allowed.

mtb_srf_op_s_t

struct mtb_srf_op_s_t

Data Fields
uint8_t	module_id	Module ID for this operation. Must be unique within this operation.
uint8_t	submodule_id	Submodule ID for this operation.
uint8_t	op_id	ID for this operation.
bool	write_required	If this operation requires modifying the hardware state.
mtb_srf_op_fn_t	impl	Function pointer to the operation. May perform custom validation, if any, before executing request.
size_t	input_values_len	Required size of input_values.
size_t	output_values_len	Required size of output_values.
size_t	input_len[MTB_SRF_MAX_IOVEC - 1]	Minimum length of inVec pointer arguments needed (From First element)
bool	needs_copy[MTB_SRF_MAX_IOVEC - 1]	Whether an input should be copied into secure memory before processing. This should be set to true if validation decisions are made based on data in this argument. inVec[0] is always copied.
size_t	output_len[MTB_SRF_MAX_IOVEC - 1]	Minimum length of outVec pointer arguments needed (From First element)
mtb_srf_permission_s_t *	allowed_rsc	List of hardware resources on which non-secure is permitted to perform this operation. Permission validation will be bypassed if this is null.
size_t	num_allowed	Length of the allowed_rsc array.

mtb_srf_module_s_t

struct mtb_srf_module_s_t

Data Fields
uint8_t	module_id	ID for this module. Must be globally unique.
mtb_srf_op_s_t **	op_by_submod	Array of operations in this module/submodule.
size_t *	num_op_by_submod	Length of each entry of the op_by_submod array.
size_t	num_submod	Length of the num_op_by_submod array.

mtb_srf_context_s_t

struct mtb_srf_context_s_t

Data Fields
mtb_srf_module_s_t *	modules[MTB_SRF_MODULE_COUNT]

mtb_srf_protection_range_s_t

struct mtb_srf_protection_range_s_t

Data Fields
void *	start	Start of the memory range.
size_t	length	Length of the memory range.
bool	is_secure	If the range is Secure or Non-Secure accessible.

mtb_srf_memory_protection_s_t

struct mtb_srf_memory_protection_s_t

Data Fields
const mtb_srf_protection_range_s_t *	ranges	Pointer to the settings array.
uint8_t	size	Array size.

Typedef Documentation

mtb_srf_op_fn_t

typedef cy_rslt_t(* mtb_srf_op_fn_t) (mtb_srf_input_ns_t *inputs_ns, mtb_srf_output_ns_t *outputs_ns, mtb_srf_invec_ns_t *inputs_ptr_ns, uint8_t inputs_ptr_cnt_ns, mtb_srf_outvec_ns_t *outputs_ptr_ns, uint8_t outputs_ptr_cnt_ns)

Function pointer to the operation.

May perform custom validation, if any, before executing request

Parameters

[in]	inputs_ns	Struct describing the operation and containing non-pointer input arguments
[in,out]	outputs_ns	Struct containing the non-pointer output arguments
[in,out]	inputs_ptr_ns	Array of InVec arguments. InVec[0] is passed as input_ns, so this array starts at inVec[1].
[in]	inputs_ptr_cnt_ns	Number of entries in inputs_ptr_ns
[in,out]	outputs_ptr_ns	Array of outVec arguments. OutVec[0] is passed as output_ns, so this array starts at outVec[1].
[in]	outputs_ptr_cnt_ns	Number of entries in outputs_ptr_ns

Returns

Result of validation check

Function Documentation

mtb_srf_init()

cy_rslt_t mtb_srf_init

(

mtb_srf_context_s_t *

context_s

)

Initialize the SRF.

Parameters

[in,out]

context_s

The context object for this asset

Returns

the status of initialization

mtb_srf_module_register()

cy_rslt_t mtb_srf_module_register	(	mtb_srf_context_s_t *	context_s,
		mtb_srf_module_s_t *	module_s
	)

Register a module for use.

Parameters

[in,out]	context_s	The context object for this asset
[in]	module_s	The module to be registered

Returns

the status of registration

mtb_srf_memory_validate()

cy_rslt_t mtb_srf_memory_validate	(	volatile mtb_srf_invec_ns_t *	inVec_ns,
		uint8_t	inVec_cnt_ns,
		volatile mtb_srf_outvec_ns_t *	outVec_ns,
		uint8_t	outVec_cnt_ns,
		mtb_srf_invec_ns_t *	inVec,
		mtb_srf_outvec_ns_t *	outVec
	)

Validate invec/outvec memory address on non-secure's permission.

This is a weak function with a default implementation so that TFM (where used) can override these checks via its own infrastructure

Parameters

[in]	inVec_ns	Vector for all operation and SRF input
[in]	inVec_cnt_ns	Number of inVecs passed in to validate
[in]	outVec_ns	Vector for all operation and SRF output
[in]	outVec_cnt_ns	Number of outVecs passed in to validate
[out]	inVec	Vector to store local copied inVec_ns
[out]	outVec	Vector to store local copied inVec_ns

Returns

the status of validation

mtb_srf_request_execute()

cy_rslt_t mtb_srf_request_execute	(	mtb_srf_context_s_t *	context_s,
		mtb_srf_invec_ns_t *	inVec_ns,
		uint8_t	inVec_cnt_ns,
		mtb_srf_outvec_ns_t *	outVec_ns,
		uint8_t	outVec_cnt_ns
	)

Execute a request.

Parameters

[in]	context_s	The context object for this asset
[in,out]	inVec_ns	Vector for all operation and SRF input
[in]	inVec_cnt_ns	Number of input vectors in inVec_ns array
[in,out]	outVec_ns	Vector for all operation and SRF output
[in]	outVec_cnt_ns	Number of output vectors in outVec_ns array

Returns

the status of execution

mtb_srf_is_memory_ns_accessible()

bool mtb_srf_is_memory_ns_accessible	(	uint32_t	addr,
		size_t	size
	)

Check if an address is non secure accessible.

Parameters

[in]	addr	The start address to check address for
[in]	size	The size of the area to check

Returns

true if it is ns acccsible, false otherwise

mtb_srf_copy_input_value()

cy_rslt_t mtb_srf_copy_input_value	(	void *	input,
		size_t	size,
		mtb_srf_input_ns_t *	inputs_ns
	)

Copy the operation defined structure value to input_values and validate the structure size If size, which is defined in secure-side, is not eqaul to size of the input_values array, it returns MTB_SRF_ERR_BAD_PARAM.

Parameters

[out]	input	Point to operation defined structure
[in]	size	The size of input to be copied and checked
[in]	inputs_ns	Struct describing the operation and containing non-pointer input arguments

Returns

the status of execution

mtb_srf_copy_output_value()

cy_rslt_t mtb_srf_copy_output_value	(	mtb_srf_output_ns_t *	outputs_ns,
		void *	output,
		size_t	size
	)

Copy the operation defined structure value to input_values and validate the structure size If size, which is defined in secure-side, is not eqaul to size of the output_values array, it returns MTB_SRF_ERR_BAD_PARAM.

Parameters

[out]	outputs_ns	Struct containing the non-pointer output arguments
[in]	output	Point to operation defined structure
[in]	size	The size of output to be copied and checked

Returns

the status of execution

mtb_srf_request_submit()

cy_rslt_t mtb_srf_request_submit	(	mtb_srf_invec_ns_t *	inVec_ns,
		uint8_t	inVec_cnt_ns,
		mtb_srf_outvec_ns_t *	outVec_ns,
		uint8_t	outVec_cnt_ns
	)

Submit a request from the non-secure side to the secure.

This is a function with a default implementation within the BSP. The user may define MTB_SRF_CUSTOM_REQUEST_SUBMIT and override this with their own implementation should they need further action taken. However custom implementations must ultimately call mtb_srf_request_execute.

When the IPC library is present, this function may be called from other cores without TrustZone. The request will be passed to the non-secure side of the TrustZone enabled core, which will then submit it to the secure side.

On Cores which support DCache, it is the user's responsibility that all data pointed to by the inVec[1-3] and outVec[1-3] base pointers is DCache aligned. The input and output structures (inVec[0] and outVec[0], respectively) as well as the ioVec structures themselves are already DCache aligned when allocated from a pool.

Parameters

[in,out]	inVec_ns	Vector for all operation and SRF input
[in]	inVec_cnt_ns	Number of input vectors in inVec_ns array
[in,out]	outVec_ns	Vector for all operation and SRF output
[in]	outVec_cnt_ns	Number of output vectors in outVec_ns array

Returns

the status of submission