Secure Request IPC integration

General Description

This library provides support for sending requests from an alternative core to the core with the secure paritition.

The non-secure partition acts as a relay to unpack the request sent over Infineon's interprocessor communication library (MTB-IPC) and submit it in the same way as other non-secure requests. The library also provides functionality to signal completion so the requesting core can view the results. This is accomplished through two roles: Client and Relay. The Client owns a pool of requests that are tied to IPC semaphores that will signal completion. The relay receives unpacks requests on the core containing the secure region before processing and signalling. This requires each of the contexts to be set up to create the relay relationship and begin submitting requests. Refer to SRF documentation Secure Request Framework for more information on secure requests and request pools. The APIs for submiting a request remain the same on all cores, but a client context must be set up on the core that needs IPC in order for the request to be sent correctly.

Refer to Code Snippets for more information.

Prerequisites

The IPC components of the SRF IPC integration must be set up prior to transfer. Please refer to MTB-IPC documentation on how to setup an IPC instance and a mailbox for request transfer. The MTB SRF IPC will by default consume MTB_SRF_IPC_SEMA_COUNT + 3 semaphores for its own use.

Request pool data memory allocation

Request pool data memory allocation can be done with help of MTB_SRF_IPC_REQUEST_DATA_ALLOC macro, but using it is not mandatory, so user can allocate memory for the shared memory in any convenient for them way. This struct is necessary to store and keep track of all shared objects during operation.

Custom Packet

Many APIs can be overridden with macros to allow custom implementations. To support this, the mtb_srf_ipc_packet_t type can be overriden via the define MTB_SRF_IPC_CUSTOM_PACKET_TYPE. However, the various APIs have minimum requirements on what this type defines.

mtb_srf_ipc_request_submit, overridden via MTB_SRF_CUSTOM_IPC_REQUEST_SUBMIT, requires all the default packet struct members to operate.

mtb_srf_ipc_process_request, overridden via MTB_SRF_CUSTOM_PROCESS_REQUEST, requires the ioVec pointers and counts (inVec_ptr, inVec_cnt_ns, outVec_ptr, outVec_cnt_ns).

mtb_srf_ipc_signal_complete, which cannot be overriden, requires the semaphore_idx member.

All other APIs interact with the packet type as a pointer and aren't affected by the contents.

Code Snippets

Register a Client and transfer request

uint32_t IPC_SEMAPHORE_INDEXES[] = { 1UL, 2UL, 3UL, 4UL, 5UL, 6UL };
#define IPC_NUM_REQ_IN_POOL (6UL)
CY_SECTION_SHAREDMEM mtb_srf_ipc_packet_t ipc_requests[IPC_NUM_REQ_IN_POOL] _MTB_SRF_DATA_ALIGN;
/* NOTE: A default client context, "cybsp_mtb_srf_client_context", is declared in the BSP */
mtb_srf_ipc_client_context_t example_srf_client_context;
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_ipc_client
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_ipc_client(void)
{
    mtb_ipc_mbox_sender_t sender;
    mtb_srf_ipc_pool_t ipc_pool;
    mtb_srf_ipc_pool_cfg_t pool_cfg;
    mtb_ipc_semaphore_t ipc_semaphores[IPC_NUM_REQ_IN_POOL];
 
    // Assume IPC instance, mailbox, and semaphores are already initialized
    // Refer to MTB IPC documentation for more information
 
    pool_cfg.request_pool = (mtb_srf_ipc_packet_t*)ipc_requests;
    pool_cfg.request_semaphores = (mtb_ipc_semaphore_t*)ipc_semaphores;
    pool_cfg.num_semaphores = IPC_NUM_REQ_IN_POOL;
    pool_cfg.num_requests = IPC_NUM_REQ_IN_POOL;
 
    cy_rslt_t result = mtb_srf_ipc_pool_init(&ipc_pool, &pool_cfg);
 
    mtb_srf_ipc_client_context_cfg_t client_cfg;
    client_cfg.mailbox_handle = &sender;
    client_cfg.pool = &ipc_pool;
 
    result = mtb_srf_setup_client_context(&example_srf_client_context, &client_cfg);
 
    // 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;
    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;
}
 
 

Register a Relay

#define IPC_NUM_REQ_IN_POOL (6UL)
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_ipc_relay_setup
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_ipc_relay_setup(void)
{
    mtb_ipc_mbox_receiver_t receiver;
    mtb_srf_ipc_relay_context_t relay;
    mtb_srf_ipc_relay_context_cfg_t cfg;
    mtb_ipc_semaphore_t ipc_semaphores[IPC_NUM_REQ_IN_POOL];
 
    // Assume IPC instance, mailbox, and semaphores are already initialized
    // See MTB IPC documentation for more information
    cfg.mailbox = &receiver;
    cfg.request_semaphores = (mtb_ipc_semaphore_t*)ipc_semaphores;
    cfg.num_semaphores = IPC_NUM_REQ_IN_POOL;
    cfg.num_requests = IPC_NUM_REQ_IN_POOL;
    cy_rslt_t result = mtb_srf_setup_relay_context(&relay, &cfg);
    return result;
}
 
 

Start Relay (Non-RTOS)

mtb_srf_ipc_relay_context_t cb_relay;
//--------------------------------------------------------------------------------------------------
// ipc_callback
//--------------------------------------------------------------------------------------------------
void ipc_callback(void* callback_arg, mtb_ipc_mbox_event_t event)
{
    CY_UNUSED_PARAMETER(callback_arg);
    CY_UNUSED_PARAMETER(event);
    mtb_srf_ipc_receive_request(&cb_relay, 100);
}
 
 
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_ipc_relay_nonrtos
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_ipc_relay_nonrtos(void)
{
    //Assume Relay context is already initialized
    mtb_ipc_mbox_receiver_enable_event(cb_relay.mailbox_handle,
                                       MTB_IPC_MBOX_FULL,
                                       true);
    mtb_ipc_mbox_receiver_register_callback(cb_relay.mailbox_handle, ipc_callback, NULL);

    cy_rslt_t result = mtb_srf_ipc_process_pending_request(&cb_relay);
    return result;
}
 
 

Start Relay (RTOS)

 
#if defined(CY_RTOS_AWARE) || defined(COMPONENT_RTOS_AWARE)
cy_rslt_t snippet_mtb_srf_ipc_relay_rtos(void)
{
    //Assume Relay context is already initialized
 
    mtb_srf_ipc_relay_context_t relay;
    cy_thread_t receive;
    cy_thread_t process;
    uint64_t thread_stack_receive[300];
    uint64_t thread_stack_process[300];
 
    cy_rslt_t result = cy_rtos_thread_create(&receive, &mtb_srf_ipc_receive_thread,
                                             "Receive Thread", &thread_stack_receive,
                                             sizeof(thread_stack_receive),
                                             CY_RTOS_PRIORITY_NORMAL, (cy_thread_arg_t)&relay);
 
 
    result = cy_rtos_thread_create(&process, &mtb_srf_ipc_process_thread,
                                   "Process Thread", &thread_stack_process,
                                   sizeof(thread_stack_process),
                                   CY_RTOS_PRIORITY_NORMAL, (cy_thread_arg_t)&relay);
    return result;
}
 
 

Quick init of Client

CY_SECTION_SHAREDMEM mtb_srf_ipc_packet_t srf_ipc_requests_simple[MTB_SRF_POOL_SIZE]
_MTB_SRF_DATA_ALIGN;
uint32_t IPC_SEMAPHORE_INDEXES_SIMPLE[] = { 1UL, 2UL, 3UL, 4UL, 5UL, 6UL };
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_ipc_client_init
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_ipc_client_init(void)
{
    // Assume IPC instance already initialized
    mtb_ipc_t ipc_inst_simple;
    mtb_ipc_mbox_sender_t ipc_sender_simple;
    mtb_srf_ipc_pool_t srf_ipc_pool_simple;
    mtb_ipc_semaphore_t ipc_semaphores[IPC_NUM_REQ_IN_POOL];
 
    mtb_srf_ipc_client_init_cfg_t client_init_simple =
    {
        .ipc_instance       = &ipc_inst_simple,
        .mailbox_handle     = &ipc_sender_simple,
        .ipc_sem_indexes    = IPC_SEMAPHORE_INDEXES_SIMPLE,
        .srf_ipc_requests   = srf_ipc_requests_simple,
        .srf_ipc_pool       = &srf_ipc_pool_simple,
        .semaphore_handles  = ipc_semaphores,
        .mbox_idx           = 0UL,
        .num_semaphores     = IPC_NUM_REQ_IN_POOL,
        .num_requests       = IPC_NUM_REQ_IN_POOL
    };
 
    cy_rslt_t result = mtb_srf_ipc_client_init(&example_srf_client_context, &client_init_simple);
 
    return result;
}
 
 

Quick init of Relay

CY_SECTION_SHAREDMEM mtb_ipc_mbox_data_t srf_ipc_mbox_data _MTB_IPC_DATA_ALIGN;
CY_SECTION_SHAREDMEM mtb_ipc_semaphore_data_t sem_data_simple[IPC_NUM_REQ_IN_POOL];
uint32_t IPC_SEMAPHORE_INDEXES_SIMPLE[] = { 1UL, 2UL, 3UL, 4UL, 5UL, 6UL };
//--------------------------------------------------------------------------------------------------
// snippet_mtb_srf_ipc_relay_init
//--------------------------------------------------------------------------------------------------
cy_rslt_t snippet_mtb_srf_ipc_relay_init(void)
{
    // Assume IPC instance already initialized
    mtb_ipc_t ipc_inst_simple;
    mtb_ipc_mbox_receiver_t ipc_receiver_simple;
    mtb_srf_ipc_relay_context_t mtb_srf_relay_context;
    mtb_ipc_semaphore_t sem_arr_simple[IPC_NUM_REQ_IN_POOL];
    mtb_srf_ipc_relay_init_cfg_t relay_init_simple =
    {
        .ipc_instance           = &ipc_inst_simple,
        .mailbox_handle         = &ipc_receiver_simple,
        .ipc_sem_indexes        =  IPC_SEMAPHORE_INDEXES_SIMPLE,
        .mailbox_data           = &srf_ipc_mbox_data,
        .semaphore_data         = sem_data_simple,
        .semaphore_handles      = sem_arr_simple,
        .mbox_idx               = 0UL,
        .mbox_read_sema_idx     = 10UL,
        .mbox_write_sema_idx    = 11UL,
        .num_semaphores         = IPC_NUM_REQ_IN_POOL,
        .num_requests           = IPC_NUM_REQ_IN_POOL
    };
 
    #if (defined(CY_RTOS_AWARE) || defined(COMPONENT_RTOS_AWARE))
    cy_queue_t rtos_queue;
    // Queue must be initialzied before passing into relay init
    relay_init_simple.ipc_req_queue = &rtos_queue;
    #endif
 
    cy_rslt_t result = mtb_srf_ipc_relay_init(&mtb_srf_relay_context, &relay_init_simple);
 
    return result;
}
 
 

API Reference
	Data Structures

Functions
cy_rslt_t	mtb_srf_ipc_request_submit (mtb_srf_ipc_client_context_t *client_context, 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 another core to a TrustZone enabled core.
cy_rslt_t	mtb_srf_ipc_pool_semaphore_alloc (mtb_srf_ipc_pool_t *pool, uint16_t *sema_idx, uint32_t timeout_us)
	Allocate IPC semaphore to use in signalling.
cy_rslt_t	mtb_srf_ipc_pool_req_alloc (mtb_srf_ipc_pool_t *pool, mtb_srf_ipc_packet_t **req, uint32_t timeout_us)
	Allocate secure request object within an SRF IPC request pool to act as a packet.
cy_rslt_t	mtb_srf_ipc_pool_semaphore_free (mtb_srf_ipc_pool_t *pool, uint16_t sema_idx)
	Deallocate an IPC semaphore.
cy_rslt_t	mtb_srf_ipc_pool_req_free (mtb_srf_ipc_pool_t *pool, const mtb_srf_ipc_packet_t *req)
	Free secure request object within an SRF IPC request pool.
cy_rslt_t	mtb_srf_ipc_request_send (mtb_srf_ipc_client_context_t *client_context, mtb_srf_ipc_packet_t *request, uint64_t timeout_us)
	Sends a request from the non-secure side to the secure and blocks for a timeout until request is processed.
cy_rslt_t	mtb_srf_ipc_receive_request (mtb_srf_ipc_relay_context_t *relay_context, uint64_t timeout_us)
	Receives an SRF request over IPC and adds to either the queue if using an RTOS or the ringbuffer.
cy_rslt_t	mtb_srf_ipc_process_request (mtb_srf_ipc_packet_t *request)
	Process the SRF request from IPC.
cy_rslt_t	mtb_srf_ipc_process_pending_request (mtb_srf_ipc_relay_context_t *relay_context)
	Process the SRF request pending in either the queue if using an RTOS or the ringbuffer.
cy_rslt_t	mtb_srf_ipc_signal_complete (mtb_srf_ipc_relay_context_t *relay_context, mtb_srf_ipc_packet_t *request)
	Signals to client that secure request has been completed and output can be read.

Function Documentation

mtb_srf_ipc_request_submit()

cy_rslt_t mtb_srf_ipc_request_submit	(	mtb_srf_ipc_client_context_t *	client_context,
		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 another core to a TrustZone enabled core.

Note

Calling this API is handled internally. When the IPC library is present, calling mtb_srf_request_submit from another core will redirect to this API. If the default mtb_srf_request_submit is disabled via the Makefile define MTB_SRF_CUSTOM_REQUEST_SUBMIT, it becomes the user's responsibility to call this on non-Trustzone cores.

Parameters

[in,out]	client_context	Stores state that client process needs to track between calls.
[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

mtb_srf_ipc_pool_semaphore_alloc()

cy_rslt_t mtb_srf_ipc_pool_semaphore_alloc	(	mtb_srf_ipc_pool_t *	pool,
		uint16_t *	sema_idx,
		uint32_t	timeout_us )

Allocate IPC semaphore to use in signalling.

Parameters

[in,out]	pool	The pool object that was populated by mtb_srf_pool_init
[in,out]	sema_idx	Pointer to the semaphore index that will be allocated.
[in]	timeout_us	Timeout to wait in microsecond. Set to 0 to perform no wait.

Returns

the status of allocate request

mtb_srf_ipc_pool_req_alloc()

cy_rslt_t mtb_srf_ipc_pool_req_alloc	(	mtb_srf_ipc_pool_t *	pool,
		mtb_srf_ipc_packet_t **	req,
		uint32_t	timeout_us )

Allocate secure request object within an SRF IPC request pool to act as a packet.

Parameters

[in,out]	pool	The pool object that was populated by mtb_srf_pool_init
[in,out]	req	Pointer to an SRF IPC request object.
[in]	timeout_us	Timeout to wait in microsecond. Set to 0 to perform no wait.

Note

The timeout_us must always be 0 if allocation is invoked from an interrupt context.

Returns

the status of allocate request

mtb_srf_ipc_pool_semaphore_free()

cy_rslt_t mtb_srf_ipc_pool_semaphore_free	(	mtb_srf_ipc_pool_t *	pool,
		uint16_t	sema_idx )

Deallocate an IPC semaphore.

Parameters

[in,out]	pool	The pool object that was populated by mtb_srf_pool_init
[in,out]	sema_idx	Index of semaphore to be deallocated from the pool.

Returns

the status of allocate request

mtb_srf_ipc_pool_req_free()

cy_rslt_t mtb_srf_ipc_pool_req_free	(	mtb_srf_ipc_pool_t *	pool,
		const mtb_srf_ipc_packet_t *	req )

Free secure request object within an SRF IPC request pool.

Parameters

[in,out]	pool	The pool object that was populated by mtb_srf_pool_init
[in]	req	Pointer to an MB SRF request for the pool to free

Returns

the status of free request

mtb_srf_ipc_request_send()

cy_rslt_t mtb_srf_ipc_request_send	(	mtb_srf_ipc_client_context_t *	client_context,
		mtb_srf_ipc_packet_t *	request,
		uint64_t	timeout_us )

Sends a request from the non-secure side to the secure and blocks for a timeout until request is processed.

This is a function that should be added any implementation of mtb_srf_request_submit, either within the BSP or custom.

Parameters

[in,out]	client_context	Stores state that client process needs to track between calls.
[in,out]	request	Pointer to SRF IPC request object that will be sent by mailbox. If this is of a type other than default mtb_srf_ipc_packet_t, then please override mtb_srf_ipc_process_request to handle additional parameters.
[in]	timeout_us	Timeout (in uS) to attempt to send request over IPC and subsequently wait for a response.

Returns

the status of submission

mtb_srf_ipc_receive_request()

cy_rslt_t mtb_srf_ipc_receive_request	(	mtb_srf_ipc_relay_context_t *	relay_context,
		uint64_t	timeout_us )

Receives an SRF request over IPC and adds to either the queue if using an RTOS or the ringbuffer.

Parameters

[in,out]	relay_context	Stores state that client process needs to track between calls.
[in]	timeout_us	Timeout (in uS) to attempt to receive request over IPC.

Returns

the status of the receive.

No RTOS so we add to ring buffer

mtb_srf_ipc_process_request()

cy_rslt_t mtb_srf_ipc_process_request

(

mtb_srf_ipc_packet_t *

request

)

Process the SRF request from IPC.

Parameters

[in,out]

request

Secure request to prepare for processing. If this is of a type other than default mtb_srf_ipc_packet_t, please override this function to handle additional parameters.

Returns

the status of the request submit.

mtb_srf_ipc_process_pending_request()

cy_rslt_t mtb_srf_ipc_process_pending_request

(

mtb_srf_ipc_relay_context_t *

relay_context

)

Process the SRF request pending in either the queue if using an RTOS or the ringbuffer.

Parameters

[in,out]

relay_context

Stores state that client process needs to track between calls.

Returns

the status of the request submit.

mtb_srf_ipc_signal_complete()

cy_rslt_t mtb_srf_ipc_signal_complete	(	mtb_srf_ipc_relay_context_t *	relay_context,
		mtb_srf_ipc_packet_t *	request )

Signals to client that secure request has been completed and output can be read.

Parameters

[in,out]	relay_context	Stores state that client process needs to track between calls.
[in]	request	Secure request to prepare for processing.

Returns

the status of the signalling