AM64x MCU+ SDK  08.02.00
IPC and Mailbox Migration Guide

This section describes the differences between IPC APIs of MCU+ SDK and Processor SDK RTOS (PDK). This can be used as migration aid when moving from Processor SDK RTOS (PDK) to MCU+ SDK.

In MCU+ SDK, the IPC APIs are simplified and consolidated into below two APIs

  • IPC Notify to provide exterme low latency IPC API
    • This can be considered as new API that can be used when sub-micro second IPC latency is needed in some hard real-time applications
  • IPC RPMessage to provide higher level message passing IPC API

API changes

There are changes in functions names, structure names and macro names. The changes in function names are listed below.

PDK MCU+ SDK Change Description / Remarks
IPC LLD
IpcInitPrms_init RPMessage_Params_init, IpcNotify_Params_init In MCU+ SDK, both IPC notify and IPC rpmsg need to be initialized. SysConfig can be used to simplify the IPC module init.
Ipc_init, RPMessage_init RPMessage_init, IpcNotify_init In MCU+ SDK, both IPC notify and IPC rpmsg need to be initialized. SysConfig can be used to simplify the IPC module init.
Ipc_deinit, RPMessage_deInit RPMessage_deInit, IpcNotify_deInit In MCU+ SDK, both IPC notify and IPC rpmsg need to be de-initialized. SysConfig can be used to simplify the IPC module init.
RPMessage_lateInit RPMessage_waitForLinuxReady API rename
RPMessageParams_init RPMessage_CreateParams_init API rename
RPMessage_create RPMessage_construct Static alloc friendly API, simplified API
RPMessage_setCallback NONE Set callback as part of RPMessage_construct parameters
RPMessage_recv, RPMessage_recvNb RPMessage_recv Unified API for blocking as well as non-blocking mode.
RPMessage_send RPMessage_send API signature to match RPMessage_recv parameters and also supports timeout
RPMessage_delete RPMessage_destruct Static alloc friendly API
RPMessage_unblock RPMessage_unblock NO CHANGE
RPMessage_getRemoteEndPt, RPMessage_getRemoteEndPtToken RPMessage_controlEndPtCallback Callback based mechanism to listen to announce messages from remote CPUs, to enable NORTOS implementation.
RPMessage_announce RPMessage_announce NO CHANGE, except that "ALL" cannot be used to send annoucement to all CPUs, specific CPU ID MUST be used.
RPMessage_getMessageBufferSize, RPMessage_getObjMemRequired, RPMessage_unblockGetRemoteEndPt, Ipc_newMessageIsr, Ipc_mailboxEnableNewMsgInt, Ipc_mailboxDisableNewMsgInt NONE NOT needed in MCU+ SDK.
NONE RPMessage_getLocalEndPt New APIs to complete the functionality
Mailbox LLD
Mailbox_initParams_init RPMessage_Params_init, IpcNotify_Params_init In MCU+ SDK, both IPC notify and IPC rpmsg need to be initialized. SysConfig can be used to simplify the IPC module init.
Mailbox_init RPMessage_init, IpcNotify_init In MCU+ SDK, both IPC notify and IPC rpmsg need to be initialized. SysConfig can be used to simplify the IPC module init.
Mailbox_deinit RPMessage_deInit, IpcNotify_deInit In MCU+ SDK, both IPC notify and IPC rpmsg need to be de-initialized. SysConfig can be used to simplify the IPC module init.
Mailbox_openParams_init RPMessage_CreateParams_init In MCU+ SDK, create a local end point to receive messages from any remote CPU at local CPU
Mailbox_open RPMessage_construct In MCU+ SDK, create a local end point to receive messages from any remote CPU at local CPU
Mailbox_write RPMessage_send In MCU+ SDK, use this API to send a message to a specific remote CPU and specific end point on that CPU
Mailbox_read RPMessage_recv In MCU+ SDK, use this API to receive messages from remote CPUs to the create local end point. The remote CPU and remote CPU end point is returned when the API returns.
Mailbox_readFlush RPMessage_recv In MCU+ SDK, explicit flush is not needed and is taken care of in RPMessage_recv.
Mailbox_close RPMessage_destruct In MCU+ SDK, use this to close a previously created local end point.
Mailbox_GetMessageCount, Mailbox_getStats, Mailbox_enableInterrupts, Mailbox_disableInterrupts NONE NOT needed in MCU+ SDK.
NONE RPMessage_waitForLinuxReady, RPMessage_controlEndPtCallback, RPMessage_announce, This APIs can be ignored when migrating from mailbox LLD.
NONE RPMessage_unblock, RPMessage_getLocalEndPt These APIs can be useful when writing applications using IPC rpmsg API.

Important Notes

Migration from IPC LLD API

  • In MCU+ SDK use the IPC RPMessage to get equivalent features of IPC LLD.
  • MCU+ SDK implements the same rpmsg protocol as IPC LLD. Only the APIs are lot more simplified and enable low memory footprint applications vs PDK.

Migration from Mailbox LLD API

  • To get equivalent features of mailbox LLD, create one rpmsg end point (equivalent to channel in mailbox LLD) and then use rpmsg APIs to send and receive message packets.
  • Unlike mailbox LLD, when using IPC RPMessage, one can send a new message even if previous message is not yet read. This is possible when number of message buffers is configured as > 1. In order to not allow sending of new message until previous message is read, set the number of message buffers to 1 during module initialization

See Also

IPC Notify, IPC RPMessage, Understanding inter-processor communication (IPC)