Secure Request Pool Init ibrary

General Description

Secure Request Pool Init Library provides an implementation of secure request pool mtb_srf_pool_t, which is composed of multiple secure request objects mtb_srf_request_ns_t.

Secure request objects need to be accessible by both the secure and non-secure world. In practice, this means that they should be allocated out of the "shared memory" region rather than e.g. off the stack. This, in turn, means that any RAM which is allocated for secure request pool description struct mtb_srf_pool_t is statically allocated for the lifetime of the program. Therefore, it would be inefficient for every secure request client to allocate its own secure request object. There needs to be a means for sharing. This need is satisfied by a secure request pool, which allows multiple secure request clients to share a small number of pre-allocated secure request pool description struct. A secure request pool is specific to a particular non-secure processing environment. I.e. in a system where both the CM33_NS and the CM55 are making secure requests, there would be two secure request pools, one for the CM33_NS and one for the CM55. Usage of this mechanism is optional. If needed to satisfy some special case, a secure request client can allocate their own custom secure request object and use that instead.

Refer to Secure Request Pool Library for more information.

API Reference
	Data Structures

Macros
#define	MTB_SRF_POOL_ENTRY_SIZE(input_values_length, output_values_length)
	A tool to calculate how much memory to provide for a pool. More...

Functions
cy_rslt_t	mtb_srf_pool_init (mtb_srf_pool_t *pool, uint32_t *allocated_mem, size_t num_entries, size_t input_len_per_entry, size_t output_len_per_entry)
	Initializes an secure request pool instance. More...

Macro Definition Documentation

MTB_SRF_POOL_ENTRY_SIZE

#define MTB_SRF_POOL_ENTRY_SIZE	(		input_values_length,
			output_values_length
	)

Value:

        (MTB_SRF_ROUND_UP(sizeof(mtb_srf_input_ns_t) + input_values_length, MTB_SRF_POOL_ALIGNMENT) + \
        MTB_SRF_ROUND_UP(sizeof(mtb_srf_output_ns_t) + output_values_length, MTB_SRF_POOL_ALIGNMENT) + \
        MTB_SRF_ROUND_UP((sizeof(mtb_srf_invec_ns_t) * MTB_SRF_MAX_IOVEC), MTB_SRF_POOL_ALIGNMENT) + \
        MTB_SRF_ROUND_UP((sizeof(mtb_srf_outvec_ns_t) * MTB_SRF_MAX_IOVEC), MTB_SRF_POOL_ALIGNMENT))

A tool to calculate how much memory to provide for a pool.

Function Documentation

mtb_srf_pool_init()

cy_rslt_t mtb_srf_pool_init	(	mtb_srf_pool_t *	pool,
		uint32_t *	allocated_mem,
		size_t	num_entries,
		size_t	input_len_per_entry,
		size_t	output_len_per_entry
	)

Initializes an secure request pool instance.

Parameters

[in,out]	pool	Stores state that secure request pool needs to track between calls. The caller must allocate shared memory for this struct but should not depend on its contents.
[in]	allocated_mem	Pointer to a section of memory allocated by the caller for the pool to use. Recommend using (MTB_SRF_POOL_ENTRY_SIZE num_entries) to calculate for custom pools
[in]	num_entries	The number of secure request objects that should fit into the pool
[in]	input_len_per_entry	The length of input argument array. The default value is MTB_SRF_MAX_ARG_IN_SIZE
[in]	output_len_per_entry	The length of output argument array. The default value is MTB_SRF_MAX_ARG_OUT_SIZE

Returns

the status of the initialization

Initializes an secure request pool instance.