Secure IPC Notify driver enables IPC communication between R5F cores and HSM M4 core. This driver cannot be used without encrypted HSMRt binary for HS-FS devices (will be available in 8.4) and TIFS-MCU for HS-SE devices (available on mySecureSW).
Introduction
The secure IPC notify(SIPC Notify) driver enables IPC communication between R5FSSx-x cores and HSM M4 core for HS-SE devices.
SIPC provides a means of secure communication between R5FSSx and HSM M4 for using HSM services. The underlying implementation uses mailbox HW interrupts and HSM MBOX shared memory(refer Mailbox mechanism for SIPC) to pass messages from R5FSSx-x to HSM M4 and vice versa.
The trusted R5FSSx-x which can post a request for services from HSM are termed as secure hosts. A non-secure host cannot communicate with HSM, moreover, the shared memory used in SIPC communication is not accessible to non-secure hosts. The cores that are going to be secure hosts are defined via sysconfig and this will be a static configuration at compile time. At a time there can only be atmost two secure hosts which can talk to HSM via SIPC, thus the name secure IPC.
Note
Sysconfig initialization has to be handled by HSM client. For Secure IPC, Sysconfig is not supported in this release. It will be available with upcoming SDK releases along with HSM client
Secure IPC design description
SIPC supports RTOS-based implementation on the R5F side. The concept of CLIENT IDs is borrowed from IPC Notify, where in the RTOS scenario each task has a callback registered of type SIPC_FxnCallback. This function will be called when a message is received for a respective CLIENT ID. Refer to Understanding inter-processor communication (IPC) to know more about CLIENT IDs.
HSM client is a wrapper on top of SIPC which asks for specific services from TIFS-MCU. User can install TIFS package from MySecureSw portal.
SIPC communication model
The maximum number of client Ids available on R5F is SIPC_CLIENT_ID_MAX = 5. On the HSM M4 side the SIPC_CLIENT_ID_MAX = 2 as it doesn't run RTOS applications.
Mailbox mechanism for SIPC
SIPC uses HSM_MBOX (2KB) memory for secure communication with HSM. It uses MBOX_READ_DONE_ACK interrupt to notify target core to read from the dedicated message queue residing in HSM_MBOX memory. IPC Notify uses MSS_MBOX(16KB) memory for R5<-->R5 communication.
SIPC shared memory configuration
The swQx is a struct holding pointer to actual queue location in HSM MBOX. There can be atmost 2 secure hosts at a time, so the total number of queues will be 4. If R5F wants to send a message to HSM then R5F writes into R5F -> HSM queue and sends an interrupt to HSM M4, once acknowledged HSM will read the message from the same queue. Similarly, If HSM wants to send a message then HSM will write into HSM --> R5 queues and sends an interrupt to R5F.
Note
The entire HSM MBOX memory must be read and write protected for non-secure hosts. setting up this firewall configuration is the responsibility of the HSM server running on M4.
SIPC initialization
Following parameters are user-configurable.
Queue Depth. -: Number of elements per queue.
Number of secure hosts -: Could be 1 or 2.
Secure hosts core Ids -: which R5F cores will be secure hosts.
These parameters will be initialized via sysconfig.
/* Sysconfig generated parameter QUEUE LENGTH */
#define SIPC_QUEUE_LENGTH (32u)
/* Sysconfig generated parameter TOTAL R5 CORES [1,2] */
#define SIPC_NUM_R5_CORES (2u)
/* Memory assigned for each R5x <-> HSM channel */
sysconfig will also generate code to allocate memory for the queues in HSM MBOX based on Queue depth and number of secure hosts. The pointer to this queue will be passed to SIPC_init at init time. For the initialization on R5F side, the SIPC_Params::tx_SipcQueues will point to gQueue_R5ToHsm where R5F will write to HSM. Similarly, SIPC_Params::rx_SipcQueues will point to gQueueHsmToR5 from where R5F will read the message sent by HSM M4.
As the size of HSM MBOX is 2KB the max Queue Depth is limited.
if SIPC_NUM_R5_CORES is 2 then the total number of queues will be 4 and the max queue depth will be 492/ SIPC_MSG_SIZE .
if SIPC_NUM_R5_CORES is 1 then the total number of queues will be 1 and the max queue depth will be 984/ SIPC_MSG_SIZE .
SIPC Initialization from R5F secure host
/* Following SIPC init will be done by HSM client running on R5*/
In order to inherit the HSM services, the application must comply the uses of IPC via shared memory i.e. a memory region should be designated to both the CPUs. Make sure to mark this section as non-cached in the R5F MPU. However if the cache is enabled, for the shared region its application responsibility to bypass cache or invalidate the cache.
Message format.
Unlike IPC Notify the message size of SIPC can be in the range of 3 to 100 bytes.
The minimum message size is 3 bytes i.e [ Dest ClientId ][ Src ClientId ][data]. Users can change SIPC_MSG_SIZE based on a protocol that is implemented on top of SIPC.
Following is an example of a message structure used by HSM client to communicate with HSM via SIPC. The size of a message is 13 bytes refer to HSM_CLIENT.
message format used by HSM client
Note
It is recommended to use 13 bytes message format as mentioned above for optimal latency.
Example usage.
Consider a use case where R5F sends a message to HSM and HSM echoes back the same message.
/* sipc initialization which will be done via sysconfig. */
SIPC_R5F_secure_host_config();
sipc_sec_host_start();
}
Refer Secure IPC example for more info.
Note
The secure IPC example project is a part of TIFS package for HS-SE devices. To use this example user needs to sign an NDA(non disclosure agreement). TIFS package can installed via mysecure software.
1.8.20