IPC Notify

Table of Contents

• Features Supported
• SysConfig Features
• Important Usage Guidelines
• Example Usage
• API

This module define's APIs for low latency IPC between different core's on a CPU. These low latency IPC APIs are constrained in features but offer extermely fast transfer of message values between two cores.

Underlying implementation will use HW mechanisms to interrupt the receiving cores, it will also use HW FIFOs (when available) or shared memory based SW FIFOs in fast internal RAM's to transport the message values.

AM64X uses HW mailbox based HW FIFOs to transport the message and interrupt the receiving core.

Features Supported

• Low latency message send and receive between any to any CPUs running no-RTOS or RTOS
• Low latency is achieved by
  • Accessing the HW in very few steps (due to this most error checking is left to the user)
  • Combining the message and client ID into a single 32b value that is send via HW/SW FIFO's (due to this there are constraints on max client ID and max message value)
  • Handling the message received within ISR itself and calling user callback within few steps of receiving the interrupt.
• Client ID field allows to send messages to different SW clients on the receving side
  • Typically each SW client will be indepedant SW entity, so client ID allows to do basic demultiplexing of messages and thus keep the SW entities indepedant of each other even when IPC is involved.
• Ability to register different user handlers for different client ID's
• Callback based mechnism to recieve messages
• Ability to block on message send for ever OR return with error, if the underlying IPC HW/SW FIFO is full.

SysConfig Features

Note

It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

IPC Examples should be build as System Projects. Single core build will fail since IPC code generation dependends on all core contexts in the application.

• Enable/Disable IPC Notify between different CPUs
• Enable/Disable SafeIPC. If Enabled, the Shared memory is organized in a way that allows Firewalling. Only Sender and Receiver core will have access to the Queue. Firewall configuration is not part of IPC SysCfg module. It has to be done separately. The SysCfg generated code has comments on the Start and End addresses and the involved cores. This can be used during the firewall configuration. Data Integrity Check has to be handled in application. CRC can be sent as a part of Payload and decoded in the receiver end.
• Enable/Disable CRC. If Enabled, Data Integrity Check is enabled for IPC Notify Data. The calculated CRC is sent as a part of Payload (ClientID + CRC + Data) and decoded in the receiver end. Application has to define a hook function which will be used by driver for CRC calculation. 8 Bit CRC is used by IPC Notify.

Important Usage Guidelines

• To balance low latency performance vs flexiblility to end user, below contraints are introduced in the API
  • The maximum number of clients supported is constrained to IPC_NOTIFY_CLIENT_ID_MAX.
  • The maximum message value that is exchanged is contrained to IPC_NOTIFY_MSG_VALUE_MAX
• IPC_NOTIFY_MSG_VALUE_MAX is < 32b, and hence one cannot pass pointers as messages.
  • However, passing pointers as messages is not a recommended SW design and instead one should pass offset from some known base address as values instead.
  • Offsets can easily fit within IPC_NOTIFY_MSG_VALUE_MAX limit.
• Internally the implementation will combine client ID and message value as one 32b integer.

Note

In case of applications involving Linux OS, Client ID 15 is reserved for remoteproc messages, this client ID should not be utilized by other users. For more details refer to example at examples/drivers/ipc/ipc_rpmsg_echo_linux/

Example Usage

Include the below files to access the APIs

#include <stdio.h>
#include <drivers/ipc_notify.h>
#include <kernel/dpl/DebugP.h>

Initialize IPC Notify

    int32_t status;
    IpcNotify_Params notifyParams;
 
    /* initialize parameters to default */
    IpcNotify_Params_init(&notifyParams);
 
    /* specify the core on which this API is called */
    notifyParams.selfCoreId = CSL_CORE_ID_R5FSS0_0;
 
    /* list the cores that will do IPC Notify with this core
     * Make sure to NOT list `self` core in the list below
     */
    notifyParams.numCores = 1;
    notifyParams.coreIdList[0] = CSL_CORE_ID_R5FSS0_1;
 
    status = IpcNotify_init(&notifyParams);
    DebugP_assert(status==SystemP_SUCCESS);

Register handler to receive messages

    int32_t status;
    /* client ID to register against, make sure messages are sent to this client ID */
    uint16_t clientId = 4;
 
    /* create a local queue to hold the emssage */
    MyQueue_create(&gMyLocalQ);
 
    /* register a handler to receive messages */
    status = IpcNotify_registerClient(clientId, MyMsg_handler, &gMyLocalQ);
    DebugP_assert(status==SystemP_SUCCESS);

Send message

    /* send `msgValue` to `clientId` of core CSL_CORE_ID_R5FSS0_1 */
    int32_t status;
    /* client ID for which this message is intended,
     * make sure a handler is registered for this client ID
     */
    uint16_t clientId = 4;
    /* message value to send, amke sure the
     * registered handler handles this message
     */
    uint32_t msgValue = 0x08765432;
 
    /* no error checks done inside IpcNotify_sendMsg(), so doing here just to show the constraints */
    DebugP_assert(msgValue < IPC_NOTIFY_MSG_VALUE_MAX);
    DebugP_assert(clientId < IPC_NOTIFY_CLIENT_ID_MAX);
 
    /* wait until msg is put into internal HW/SW FIFO */
    status = IpcNotify_sendMsg(CSL_CORE_ID_R5FSS0_0, clientId, msgValue, 1);
    DebugP_assert(status==SystemP_SUCCESS);

Receive message and handle it in a task

 
/* NOTE: local queue implementation not shown, this is a standard FIFO like SW queue,
 *       which is thread and interrupt safe and can block until there is a element to dequeue
 */
 
/* local Q to hold received messages */
MyQueue_Obj gMyLocalQ;
 
void MyMsg_handler(uint32_t remoteCoreId, uint16_t localClientId, uint32_t msgValue, int32_t crcStatus, void *args)
{
    MyQueue_Obj *myLocalQ = (MyQueue_Obj*)args;
 
    /* message received from remote core `remoteCoreId`, for client ID `localClientId` on this core */
 
    /* instead of handling the messages in callback which is called within ISR, queue this into a larger SW queue.
     * Handle to the SW queue is passed via args in this example.
     * SW queue could be one per remote core, one per client ID or a common Q for all remote cores and so on.
     * Passing queue handle as argument allows the handler to remain
     * common across multiple remote cores and client ID's
     */
    MyQueue_put(myLocalQ, msgValue);
 
    /* NOTE: THis is a sample handler, actually application can have different design based on its
     *       specific requirements
     */
}
 
/* Message handler task */
void MyTask_main(void *args)
{
    while(1)
    {
        uint32_t msgValue;
 
        /* block until there is a element to dequeue from this Q */
        MyQueue_wait(&gMyLocalQ, &msgValue);
 
        if(msgValue == 0x08765432)
        {
            /* handle message value.
             * typically message value will be a command to execute
             * OR
             * it will point (offset or index within a known shared memory base address or array)
             * to command and parameters to execute
             */
        }
    }
}

API

APIs for IPC Notify