AM261x MCU+ SDK: APIs for IPC Notify

| AM261x MCU+ SDK 26.00.00 |

Data Structures | Functions | Typedefs | Macros
APIs for IPC Notify
APIs for SOC Specific Device Drivers

## Introduction

See IPC Notify for more details.

## Data Structures
struct | IpcNotify_Params
| Parameters used by IpcNotify_init. More...

## Functions
void | IpcNotify_Params_init (IpcNotify_Params *params)
| Set default value to IpcNotify_Params. More...
int32_t | IpcNotify_init (const IpcNotify_Params *params)
| Initialize IPC Notify module. More...
void | IpcNotify_deInit (void)
| De-initialize IPC Notify module. More...
int32_t | IpcNotify_sendMsg (uint32_t remoteCoreId, uint16_t remoteClientId, uint32_t msgValue, uint32_t waitForFifoNotFull)
| Send message to a specific remote core and specific client ID on that remote core. More...
int32_t | IpcNotify_registerClient (uint16_t localClientId, IpcNotify_FxnCallback msgCallback, void *args)
| Register a callback to handle messages received from a specific remote core and for a specific local client ID. More...
int32_t | IpcNotify_unregisterClient (uint16_t localClientId)
| Un-register a previously registered callback. More...
uint32_t | IpcNotify_getSelfCoreId (void)
| Return current core ID. More...
uint32_t | IpcNotify_isCoreEnabled (uint32_t coreId)
| Check if a core is enabled for IPC. More...
int32_t | IpcNotify_sendSync (uint32_t remoteCoreId)
| Send a sync message to specific core. More...
int32_t | IpcNotify_waitSync (uint32_t remoteCoreId, uint32_t timeout)
| Wait for a sync message to be received from the specified core. More...
int32_t | IpcNotify_syncAll (uint32_t timeout)
| Send a message to all enabled cores and wait for sync message from all enabled cores. More...
void | IpcNotify_registerNonNotifyCallback (IpcNotify_NonNotifyCallback callback)
| This is a driver library internal API and is used in certain SOCs by the separate mailbox driver. More...

## Typedefs
typedef void(* | IpcNotify_FxnCallback) (uint32_t remoteCoreId, uint16_t localClientId, uint32_t msgValue, int32_t crcStatus, void *args)
| User callback that is invoked when a message is received from a reote core for a given client ID. More...
typedef void(* | IpcNotify_NonNotifyCallback) (uint32_t remoteCoreId)
| This is a driver library internal API and is used in certain SOCs by the separate mailbox driver. More...
typedef int32_t(* | IpcNotify_CrcHookFxn) (uint8_t *data, uint16_t dataLen, uint8_t crcSize, void *crc)
| This is the API defined in application for CRC Calculation. More...

## Macros
#define | IPC_NOTIFY_CLIENT_ID_MAX (16U)
| Maximum number of clients possible for receiving messages. More...
#define | IPC_NOTIFY_CLIENT_ID_RPMSG (0U)
| Client ID used by rpmessage, this client ID should not be used by other users. More...
#define | IPC_NOTIFY_CLIENT_ID_SYNC (1U)
| Client ID used for sync messages, this client ID should not be used by other users. More...
#define | IPC_NOTIFY_DEFAULT_INTR_PRIORITY (4U)
| Default Interrupt priority for IPC Notify. More...
#define | IPC_NOTIFY_MSG_VALUE_MAX (0x10000000U)
| Maximum value of message that can be sent and received. More...
#define | IPC_NOTIFY_CRC_MSG_VALUE_MAX (0x100000U)
| Maximum value of message that can be sent and received when CRC is enabled. More...
#define | IPC_NOTIFY_CRC_MAX (0x100U)
| Maximum value of CRC that can be sent and received. More...
#define | IPC_NOTIFY_CRC_SIZE (1U)
| CRC size in bytes for IPC Notify. More...
#define | IPC_NOTIFY_CRC_DATASIZE (4U)
| Data size in bytes for IPC Notify. More...
#define | IPC_INTR_ROUTER_ENABLE (0x01U)
| Interrupt router enable for IPC. More...
#define | IPC_INTR_ROUTER_DISABLE (0x00U)
| Interrupt router disable for IPC. More...

## Macro Definition Documentation

## ◆ IPC_NOTIFY_CLIENT_ID_MAX

#define IPC_NOTIFY_CLIENT_ID_MAX (16U)

Maximum number of clients possible for receiving messages.

## ◆ IPC_NOTIFY_CLIENT_ID_RPMSG

#define IPC_NOTIFY_CLIENT_ID_RPMSG (0U)

Client ID used by rpmessage, this client ID should not be used by other users.

## ◆ IPC_NOTIFY_CLIENT_ID_SYNC

#define IPC_NOTIFY_CLIENT_ID_SYNC (1U)

Client ID used for sync messages, this client ID should not be used by other users.

## ◆ IPC_NOTIFY_DEFAULT_INTR_PRIORITY

#define IPC_NOTIFY_DEFAULT_INTR_PRIORITY (4U)

Default Interrupt priority for IPC Notify.

## ◆ IPC_NOTIFY_MSG_VALUE_MAX

#define IPC_NOTIFY_MSG_VALUE_MAX (0x10000000U)

Maximum value of message that can be sent and received.

## ◆ IPC_NOTIFY_CRC_MSG_VALUE_MAX

#define IPC_NOTIFY_CRC_MSG_VALUE_MAX (0x100000U)

Maximum value of message that can be sent and received when CRC is enabled.

## ◆ IPC_NOTIFY_CRC_MAX

#define IPC_NOTIFY_CRC_MAX (0x100U)

Maximum value of CRC that can be sent and received.

## ◆ IPC_NOTIFY_CRC_SIZE

#define IPC_NOTIFY_CRC_SIZE (1U)

CRC size in bytes for IPC Notify.

## ◆ IPC_NOTIFY_CRC_DATASIZE

#define IPC_NOTIFY_CRC_DATASIZE (4U)

Data size in bytes for IPC Notify.

## ◆ IPC_INTR_ROUTER_ENABLE

#define IPC_INTR_ROUTER_ENABLE (0x01U)

Interrupt router enable for IPC.

## ◆ IPC_INTR_ROUTER_DISABLE

#define IPC_INTR_ROUTER_DISABLE (0x00U)

Interrupt router disable for IPC.

## Typedef Documentation

## ◆ IpcNotify_FxnCallback

typedef void(* IpcNotify_FxnCallback) (uint32_t remoteCoreId, uint16_t localClientId, uint32_t msgValue, int32_t crcStatus, void *args)

User callback that is invoked when a message is received from a reote core for a given client ID.

Before invoking the API, the IPC module would have 'popped` the message from the HW or SW FIFO already. This callback is called frm ISR context, so all constraints of ISR should be applied by the callback, e.g. no blocking wait, quickly handle message and exit ISR.

For most applications, it is recommended to put the message value into a local SW queue and defer the message handling itself to a application task.

Parameters

  remoteCoreId | [in] Remote core that has sent the message
  localClientId | [in] Local client ID to which the message is sent
  msgValue | [in] Message value that is sent
  crcStatus | [in] CRC Check status. SystemP_SUCCESS on success, else SystemP_FAILURE.
  args | [in] Argument pointer passed by user when IpcNotify_registerClient is called

## ◆ IpcNotify_NonNotifyCallback

typedef void(* IpcNotify_NonNotifyCallback) (uint32_t remoteCoreId)

This is a driver library internal API and is used in certain SOCs by the separate mailbox driver.

Attention
  This API should not be used by end users.

Parameters

  remoteCoreId | [in] remote core ID that generated the interrupt

## ◆ IpcNotify_CrcHookFxn

typedef int32_t(* IpcNotify_CrcHookFxn) (uint8_t *data, uint16_t dataLen, uint8_t crcSize, void *crc)

This is the API defined in application for CRC Calculation.

Note
  IPC Notify uses 8 Bit CRC and driver invokes this API with crcSize = 1 and passes an 8 bit variable as crc pointer.

Parameters

  data | [in] Pointer to data.
  dataLen | [in] Length of message in bytes.
  crcSize | [in] Size of CRC to be calculated in bytes.
  crc | [out] Pointer to the calculated CRC value.

## Function Documentation

## ◆ IpcNotify_Params_init()

void IpcNotify_Params_init | ( | IpcNotify_Params * | params | ) |

Set default value to IpcNotify_Params.

Parameters

  params | [out] Default initialized structure

## ◆ IpcNotify_init()

int32_t IpcNotify_init | ( | const IpcNotify_Params * | params | ) |

Initialize IPC Notify module.

This API will initialize the HW used for IPC including registering interrupts for receiving messages.

Parameters

  params | [in] Initializaion parameters

## ◆ IpcNotify_deInit()

void IpcNotify_deInit | ( | void |  | ) |

De-initialize IPC Notify module.

This API will de-initialize the HW used for IPC including un-registering interrupts for receiving messages.

## ◆ IpcNotify_sendMsg()

int32_t IpcNotify_sendMsg | ( | uint32_t | remoteCoreId,
|  | uint16_t | remoteClientId,
|  | uint32_t | msgValue,
|  | uint32_t | waitForFifoNotFull
| ) |  |

Send message to a specific remote core and specific client ID on that remote core.

Note
  To reduce latency, error checks are avoided in this API. Users need to make sure the client ID value is < IPC_NOTIFY_CLIENT_ID_MAX and message value is < IPC_NOTIFY_MSG_VALUE_MAX
  This API can be called from within ISRs and is also thread-safe. Internally this API disables interrupts for a short while to make the API ISR and thread safe.
  One cannot send messages to self, i.e remoteCoreId, cannot be same as core ID of the CPU that called this API.

Parameters

  remoteCoreId | [in] Remote core to sent message to, see CSL_CoreID for valid values.
  remoteClientId | [in] Remote core client ID to send message to, MUST be < IPC_NOTIFY_CLIENT_ID_MAX
  msgValue | [in] Message value to send, MUST be < IPC_NOTIFY_MSG_VALUE_MAX
  waitForFifoNotFull | [in] 1: wait for message to be inserted into HW or SW FIFO, 0: if FIFO is full, dont send message and return with error.

Returns
  SystemP_SUCCESS, message sent successfully
  SystemP_FAILURE, message could not be sent since HW or SW FIFO for holding the message is full.

## ◆ IpcNotify_registerClient()

int32_t IpcNotify_registerClient | ( | uint16_t | localClientId,
|  | IpcNotify_FxnCallback | msgCallback,
|  | void * | args
| ) |  |

Register a callback to handle messages received from a specific remote core and for a specific local client ID.

Parameters

  localClientId | [in] Client ID to which the message has been sent
  msgCallback | [in] Callback to invoke, if callback is already registered, error will be returned.
  args | [in] User arguments, that are passed back to user when the callback is invoked

Returns
  SystemP_SUCCESS, callback registered sucessfully
  SystemP_FAILURE, callback registration failed, either remoteCoreId or localClientId is invalid or callback already registered.

## ◆ IpcNotify_unregisterClient()

int32_t IpcNotify_unregisterClient | ( | uint16_t | localClientId | ) |

Un-register a previously registered callback.

Parameters

  localClientId | [in] Client ID to which the message has been sent

Returns
  SystemP_SUCCESS, callback un-registered sucessfully
  SystemP_FAILURE, callback un-registration failed, either remoteCoreId or localClientId is invalid

## ◆ IpcNotify_getSelfCoreId()

uint32_t IpcNotify_getSelfCoreId | ( | void |  | ) |

Return current core ID.

Returns
  Core ID, see CSL_CoreID for valid values.

## ◆ IpcNotify_isCoreEnabled()

uint32_t IpcNotify_isCoreEnabled | ( | uint32_t | coreId | ) |

Check if a core is enabled for IPC.

Parameters

  coreId | [in] Core ID, see CSL_CoreID for valid values.

Returns
  1: core is enabled for IPC, 0: core is not enabled for IPC

## ◆ IpcNotify_sendSync()

int32_t IpcNotify_sendSync | ( | uint32_t | remoteCoreId | ) |

Send a sync message to specific core.

This API can be used to send sync message's to very specific core's For most users recommend to use the more simpler IpcNotify_syncAll() API.

Parameters

  remoteCoreId | [in] Core ID, see CSL_CoreID for valid values.

Returns
  SystemP_SUCCESS, sync message was sent successfully, else failure

## ◆ IpcNotify_waitSync()

int32_t IpcNotify_waitSync | ( | uint32_t | remoteCoreId,
|  | uint32_t | timeout
| ) |  |

Wait for a sync message to be received from the specified core.

This API can be used to recevice sync message from very specific core's For most users recommend to use the more simpler IpcNotify_syncAll() API.

Parameters

  remoteCoreId | [in] Core ID, see CSL_CoreID for valid values.
  timeout | [in] Amount of time in units of ticks to wait

Returns
  SystemP_SUCCESS, sync message was recevied successfully
  SystemP_TIMEOUT, sync message was NOT recevied after `timeout` ticks
  SystemP_FAILURE, invalid arguments

## ◆ IpcNotify_syncAll()

int32_t IpcNotify_syncAll | ( | uint32_t | timeout | ) |

Send a message to all enabled cores and wait for sync message from all enabled cores.

This API when called on all CPUs, make sure all CPUs execute upto a certain and then proceed only when all other CPUs have also executed to the same point.

This is useful esp during system init to make sure message exchange can be started only after all CPUs have finished their system initialization.

Parameters

  timeout | [in] Amount of time in units of ticks to wait for the sync

Returns
  SystemP_SUCCESS, all sync messages recevied successfully
  SystemP_TIMEOUT, some sync messages was NOT recevied after `timeout` ticks
  SystemP_FAILURE, invalid arguments

## ◆ IpcNotify_registerNonNotifyCallback()

void IpcNotify_registerNonNotifyCallback | ( | IpcNotify_NonNotifyCallback | callback | ) |

This is a driver library internal API and is used in certain SOCs by the separate mailbox driver.

Attention
  This API should not be used by end users.

Parameters

  callback | [in] Callback to call when a interrupt is received from a CPU which is not part of IPC Notify core list