AM261x MCU+ SDK: APIs for IPC RPMessage

| AM261x MCU+ SDK 26.00.00 |

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

## Introduction

See IPC RPMessage for more details.

## Data Structures
struct | RPMessage_Object
struct | RPMessage_CreateParams
| Parameters passed to RPMessage_construct. More...
struct | RPMessage_Params
| Parameters passed to RPMessage_init, these are generated via SysCfg. More...

## Functions
void | RPMessage_Params_init (RPMessage_Params *params)
| Set default values to RPMessage_Params. More...
void | RPMessage_CreateParams_init (RPMessage_CreateParams *params)
| Set default values to RPMessage_CreateParams. More...
int32_t | RPMessage_init (const RPMessage_Params *params)
| Initialize RPMessage module. More...
void | RPMessage_deInit (void)
| De-Initialize RPMessage module. More...
int32_t | RPMessage_waitForLinuxReady (uint32_t timeout)
| Wait for linux side RPMessage to be ready. More...
void | RPMessage_controlEndPtCallback (RPMessage_ControlEndPtCallback controlEndPtCallback, void *controlEndPtCallbackArgs)
| Callback to call when a control message is received on a control end point. More...
int32_t | RPMessage_construct (RPMessage_Object *obj, const RPMessage_CreateParams *createParams)
| Create a RPMessage object to receive messages at a specified end-point. More...
void | RPMessage_destruct (RPMessage_Object *obj)
| Delete a previously created RPMessage object. More...
void | RPMessage_unblock (RPMessage_Object *obj)
| Unblocks RPMessage_recv, for the input object, if it is blocked waiting on messages and users want to exit that task. More...
uint16_t | RPMessage_getLocalEndPt (const RPMessage_Object *obj)
| Return local end point of a RPMessage_Object. More...
int32_t | RPMessage_announce (uint16_t remoteProcId, uint16_t localEndPt, const char *name)
| Announce a local end point at which a `service` is created to a remote core. More...
int32_t | RPMessage_send (void *data, uint16_t dataLen, uint16_t remoteCoreId, uint16_t remoteEndPt, uint16_t localEndPt, uint32_t timeout)
| Send a message to a remote core at a specified remote end point. More...
int32_t | RPMessage_recv (RPMessage_Object *obj, void *data, uint16_t *dataLen, uint16_t *remoteCoreId, uint16_t *remoteEndPt, uint32_t timeout)
| Blocking API to wait till a message is received from any CPU at the specified local end point. More...

## Typedefs
typedef void(* | RPMessage_RecvCallback) (struct RPMessage_Object_s *obj, void *arg, void *data, uint16_t dataLen, int32_t crcStatus, uint16_t remoteCoreId, uint16_t remoteEndPt)
| Callback that is invoked when a message is received from any CPU at the specified local end point. More...
typedef void(* | RPMessage_RecvNotifyCallback) (struct RPMessage_Object_s *obj, void *arg)
| Callback that is invoked when a message is received from any CPU at the specified local end point. More...
typedef void(* | RPMessage_ControlEndPtCallback) (void *arg, uint16_t remoteCoreId, uint16_t remoteEndPt, const char *remoteServiceName)
| Callback that is invoked when a annoucement message is received on the control end point. More...
typedef int32_t(* | RPMessage_CrcHookFxn) (uint8_t *data, uint16_t dataLen, uint8_t crcSize, void *crc)
| This is the CRC Hook function to be defined in application for CRC Calculation. More...

## Macros
#define | RPMESSAGE_MAX_LOCAL_ENDPT (64U)
| Users can create RPMessage_Object with local end value in the range of 0 .. RPMESSAGE_MAX_LOCAL_ENDPT - 1. More...
#define | RPMESSAGE_VRING_ADDR_INVALID (0xFFFFFFFFU)
| Value to indicate if vring ID is valid or NOT. More...
#define | RPMESSAGE_VRING_SIZE(numBuf, bufSize) (((numBuf)*(uint16_t)((bufSize)+32U))+32U)
| Returns the size needed for each VRING. More...
#define | RPMESSAGE_OBJECT_SIZE_MAX (192U)
| Size of RPMessage_Object. More...
#define | RPMESSAGE_CRC_SIZE (2U)
| CRC size in bytes for IPC RPMsg. More...

## Macro Definition Documentation

## ◆ RPMESSAGE_MAX_LOCAL_ENDPT

#define RPMESSAGE_MAX_LOCAL_ENDPT (64U)

Users can create RPMessage_Object with local end value in the range of 0 .. RPMESSAGE_MAX_LOCAL_ENDPT - 1.

This limit is put to allow fast indexing of end point object to recevied messages and the value is kept small to save memory space

## ◆ RPMESSAGE_VRING_ADDR_INVALID

#define RPMESSAGE_VRING_ADDR_INVALID (0xFFFFFFFFU)

Value to indicate if vring ID is valid or NOT.

When a core does not participate in IPC RPMessage set the vring ID in RPMessage_Params to this value

## ◆ RPMESSAGE_VRING_SIZE

#define RPMESSAGE_VRING_SIZE | ( |  | numBuf,
|  |  | bufSize
| ) |  | (((numBuf)*(uint16_t)((bufSize)+32U))+32U)

Returns the size needed for each VRING.

This is approximate size that is >= to actual required size. Approximate size is returned to allow compile time macro for size calculation. Actual required size is calculated in the internal run-time function `RPMessage_vringGetSize`. However this can be ignored by end users. During initialization, a assert is used to check if user provided size is >= actual required size.

Parameters

  numBuf | [in] Number of buffer in the VRING
  bufSize | [in] Size of each buffer, in units of bytes

Returns
  VRING size in bytes

## ◆ RPMESSAGE_OBJECT_SIZE_MAX

#define RPMESSAGE_OBJECT_SIZE_MAX (192U)

Size of RPMessage_Object.

## ◆ RPMESSAGE_CRC_SIZE

#define RPMESSAGE_CRC_SIZE (2U)

CRC size in bytes for IPC RPMsg.

## Typedef Documentation

## ◆ RPMessage_RecvCallback

typedef void(* RPMessage_RecvCallback) (struct RPMessage_Object_s *obj, void *arg, void *data, uint16_t dataLen, int32_t crcStatus, uint16_t remoteCoreId, uint16_t remoteEndPt)

Callback that is invoked when a message is received from any CPU at the specified local end point.

The callback can be optionally registered during RPMessage_construct

Note
  All message contents MUST be consumed in the callback. When callback returns the message buffer is released back to the sender. If the message contents are needed for deferred processing then take a copy of the message contents

Warning
  Do not call blocking apis such as 'RPMessage_send()' from this callback which runs in isr context

Parameters

  obj | [in] RPMessage end point object created with RPMessage_construct
  arg | [in] Arguments specified by user during RPMessage_construct
  data | [in] Pointer to message
  dataLen | [in] Length of message
  crcStatus | [in] CRC Check status. SystemP_SUCCESS on success, else SystemP_FAILURE.
  remoteCoreId | [in] Core ID of sender
  remoteEndPt | [in] End point of sender

## ◆ RPMessage_RecvNotifyCallback

typedef void(* RPMessage_RecvNotifyCallback) (struct RPMessage_Object_s *obj, void *arg)

Callback that is invoked when a message is received from any CPU at the specified local end point.

The callback can be optionally registered during RPMessage_construct

Note
  Unlike RPMessage_RecvCallback, this callback only notifies that there is one or more messages to be read, but the message itself is not read by the driver unless RPMessage_recv is called in this callback or later within a task.
  If RPMessage_RecvCallback is set, then RPMessage_RecvNotifyCallback callback is not used.

Parameters

  obj | [in] RPMessage end point object created with RPMessage_construct
  arg | [in] Arguments specified by user during RPMessage_construct

## ◆ RPMessage_ControlEndPtCallback

typedef void(* RPMessage_ControlEndPtCallback) (void *arg, uint16_t remoteCoreId, uint16_t remoteEndPt, const char *remoteServiceName)

Callback that is invoked when a annoucement message is received on the control end point.

The callback can be optionally registered during RPMessage_init

Note
  All message contents MUST be consumed in the callback. When callback returns the message buffer is released back to the sender. If the message contents are needed for deferred processing then take a copy of the message contents

Parameters

  arg | [in] Arguments specified by user during RPMessage_init
  remoteCoreId | [in] Core ID of sender
  remoteEndPt | [in] End point of sender that has annoucned the service over the control end point
  remoteServiceName | [in] Name of the remote service that is annoucned

## ◆ RPMessage_CrcHookFxn

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

This is the CRC Hook function to be defined in application for CRC Calculation.

Note
  IPC Notify uses 16 Bit CRC and driver invokes this API with crcSize = 2 and passes a 16 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

## ◆ RPMessage_Params_init()

void RPMessage_Params_init | ( | RPMessage_Params * | params | ) |

Set default values to RPMessage_Params.

Parameters

  params | [out] default intialized structure

## ◆ RPMessage_CreateParams_init()

void RPMessage_CreateParams_init | ( | RPMessage_CreateParams * | params | ) |

Set default values to RPMessage_CreateParams.

Parameters

  params | [out] default intialized structure

## ◆ RPMessage_init()

int32_t RPMessage_init | ( | const RPMessage_Params * | params | ) |

Initialize RPMessage module.

Parameters

  params | [in] Initialization parameters

## ◆ RPMessage_deInit()

void RPMessage_deInit | ( | void |  | ) |

De-Initialize RPMessage module.

## ◆ RPMessage_waitForLinuxReady()

int32_t RPMessage_waitForLinuxReady | ( | uint32_t | timeout | ) |

Wait for linux side RPMessage to be ready.

Messages should not be sent to Linux, if enabled, until this function return success.

Note
  When using RPMessage between RTOS/no-RTOS cores then this API needed not be called.

Parameters

  timeout | [in] Timeout in units of system ticks

Returns
  SystemP_SUCCESS, linux has initialized its side of RPMessage

## ◆ RPMessage_controlEndPtCallback()

void RPMessage_controlEndPtCallback | ( | RPMessage_ControlEndPtCallback | controlEndPtCallback,
|  | void * | controlEndPtCallbackArgs
| ) |  |

Callback to call when a control message is received on a control end point.

Parameters

  controlEndPtCallback | [in] User callback to invoke
  controlEndPtCallbackArgs | [in] Arguments pass to the user control end point callback

## ◆ RPMessage_construct()

int32_t RPMessage_construct | ( | RPMessage_Object * | obj,
|  | const RPMessage_CreateParams * | createParams
| ) |  |

Create a RPMessage object to receive messages at a specified end-point.

Note
  Each new object that is created MUST have a unique local end point.
  Local end point MUST be < RPMESSAGE_MAX_LOCAL_ENDPT
  User MUST choose a value and `ANY` is not supported
  When callback is registered in RPMessage_CreateParams, RPMessage_recv MUST not be used.

Parameters

  obj | [out] Created object
  createParams | [in] parameters

Returns
  SystemP_SUCCESS on success, else failure.

## ◆ RPMessage_destruct()

void RPMessage_destruct | ( | RPMessage_Object * | obj | ) |

Delete a previously created RPMessage object.

Parameters

  obj | [in] object

## ◆ RPMessage_unblock()

void RPMessage_unblock | ( | RPMessage_Object * | obj | ) |

Unblocks RPMessage_recv, for the input object, if it is blocked waiting on messages and users want to exit that task.

Parameters

  obj | [in] object

## ◆ RPMessage_getLocalEndPt()

uint16_t RPMessage_getLocalEndPt | ( | const RPMessage_Object * | obj | ) |

Return local end point of a RPMessage_Object.

The value will be same as that was used to create the object earlier.

Parameters

  obj | [in] object

Returns
  local end point of input object

## ◆ RPMessage_announce()

int32_t RPMessage_announce | ( | uint16_t | remoteProcId,
|  | uint16_t | localEndPt,
|  | const char * | name
| ) |  |

Announce a local end point at which a `service` is created to a remote core.

Note
  Announcing end points is optional and is not used internally by IPC RPmessage in any way.
  User MUST announce one by one to all remote core's of interest. There is no announce to `ALL` option
  To handle announcement messages, make sure user handler is registered during RPMessage_init via RPMessage_Params
  It is upto the end user to use the callback to signal or wait until a remote service is announced.

Parameters

  remoteProcId | [in] The remote core to annouce to.
  localEndPt | [in] Local end point of the service that is being announced
  name | [in] Name of the service that is being announced

Returns
  SystemP_SUCCESS, when the annouce message was sent, else failure

## ◆ RPMessage_send()

int32_t RPMessage_send | ( | void * | data,
|  | uint16_t | dataLen,
|  | uint16_t | remoteCoreId,
|  | uint16_t | remoteEndPt,
|  | uint16_t | localEndPt,
|  | uint32_t | timeout
| ) |  |

Send a message to a remote core at a specified remote end point.

Note
  `dataLen` MUST be <= RPMessage_Params::vringMsgSize - 16 bytes for internal header
  In order for a remote core to receive the message, a end point should be created on the remote core at the same value as `remoteEndPt`
  localEndPt, is strictly not needed, however this is available to the user on the remote core and can be used as a reply end point. Use RPMessage_getLocalEndPt to set to the RPMessage object at which to listen for replies
  When timeout is 0, then if a free buffer is not available to transmit, it will return will immediately SystemP_TIMEOUT. Else it will wait for specified `timeout` ticks for a free buffer to be available.

Parameters

  data | [in] Pointer to message data to send
  dataLen | [in] size of message data to send
  remoteCoreId | [in] Remote core ID to whom the message is being sent
  remoteEndPt | [in] Remote core end point ID to which the message is being sent
  localEndPt | [in] Local end point that is sending the message
  timeout | [in] Amount of time to wait, in units of system ticks

Returns
  SystemP_SUCCESS, when the send message was successful
  SystemP_TIMEOUT, message not sent since free transmit buffer not available and timeout happened.

## ◆ RPMessage_recv()

int32_t RPMessage_recv | ( | RPMessage_Object * | obj,
|  | void * | data,
|  | uint16_t * | dataLen,
|  | uint16_t * | remoteCoreId,
|  | uint16_t * | remoteEndPt,
|  | uint32_t | timeout
| ) |  |

Blocking API to wait till a message is received from any CPU at the specified local end point.

Note
  Local end point is specified during RPMessage_construct
  When callback is registered this API should not be used.
  `dataLen` when passed by user contains the user message buffer size, i.e size of buffer pointer to by 'data`. If received message size exceeds *dataLen then it is truncated. If received message size is <= *dataLen then all received bytes are copied to `data` and *dataLen indicates the size of valid bytes in `data`

Parameters

  obj | [in] RPMessage end point object created with RPMessage_construct
  data | [in] Pointer to received message contents
  dataLen | [in] Length of user message buffer, in bytes [out] Size of received message, in bytes
  remoteCoreId | [out] Core ID of sender
  remoteEndPt | [out] End point of sender
  timeout | [in] Time in system ticks to block for a message receive

Returns
  SystemP_SUCCESS, new message received, all output parameters are valid
  SystemP_TIMEOUT, API unblocked due to timeout and output parameters should not be used.