AM261x MCU+ SDK: APIs for Secure IPC Notify

| AM261x MCU+ SDK 26.00.00 |

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

## Introduction

See SIPC Notify for more details.

## Data Structures
struct | SIPC_Params
| Parameters used by SIPC_init. More...
struct | SIPC_SwQueue
| SIPC swQ structure which holds the data pointer to a fifo Queue in HSM MBOX memory. More...

## Functions
void | SIPC_Params_init (SIPC_Params *params)
| Set default value to SIPC_Params. More...
int32_t | SIPC_init (SIPC_Params *params)
| Initialize Secure IPC notify module. More...
void | SIPC_deInit (void)
| De-initialize secure IPC Notify module. More...
int32_t | SIPC_sendMsg (uint8_t remoteSecCoreId, uint8_t remoteClientId, uint8_t localClientId, uint8_t *msgValue, SIPC_fifoFlags waitForFifoNotFull)
| Send message to a specific remote core and specific client ID on that remote core. More...
int32_t | SIPC_registerClient (uint8_t localClientId, SIPC_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 | SIPC_unregisterClient (uint16_t localClientId)
| Un-register a previously registered callback. More...
uint32_t | SIPC_getSelfCoreId (void)
| Return current core ID. More...
uint32_t | SIPC_getSelfSecMasterId (void)
| Return current core sec master ID. More...
uint32_t | SIPC_isCoreEnabled (uint32_t coreId)
| Check if a core is enabled for SIPC. More...

## Typedefs
typedef void(* | SIPC_FxnCallback) (uint8_t remoteSecCoreId, uint8_t localClientId, uint8_t remoteClientId, uint8_t *msgValue, void *args)
| User callback that is invoked when a message is received from a reote core for a given client ID. More...
typedef uint32_t | SIPC_coreId
| Core Ids to identify different cores. More...
typedef uint32_t | SIPC_SecCoreId
| Secure host Id to identify different secure hosts. Max number of secure host on AM263x is 2. More...

## Enumerations
enum | SIPC_fifoFlags { ABORT_ON_FIFO_FULL, WAIT_IF_FIFO_FULL }
| flags to pass with the SIPC_sendMsg Api which indicates the flow of execution when the write FIFO is full More...

## Typedef Documentation

## ◆ SIPC_FxnCallback

typedef void(* SIPC_FxnCallback) (uint8_t remoteSecCoreId, uint8_t localClientId, uint8_t remoteClientId,uint8_t *msgValue, 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.

Note
  This callback will process the *msgValue . Registered function should not be blocking. as this is called from isr context.

Parameters

  remoteSecCoreId | [in] Remote core that has sent the message
  localClientId | [in] Local client ID to which the message is sent
  remoteClientId | [in] remote client Id from which this message has been sent
  msgValue | [in] pointer to the buffer with SIPC_MSG_SIZE elements
  args | [in] Argument pointer passed by user when SIPC_registerClient is called

## ◆ SIPC_coreId

typedef uint32_t SIPC_coreId

Core Ids to identify different cores.

## ◆ SIPC_SecCoreId

typedef uint32_t SIPC_SecCoreId

Secure host Id to identify different secure hosts. Max number of secure host on AM263x is 2.

## Enumeration Type Documentation

## ◆ SIPC_fifoFlags

enum SIPC_fifoFlags

flags to pass with the SIPC_sendMsg Api which indicates the flow of execution when the write FIFO is full

Enumerator
ABORT_ON_FIFO_FULL |
WAIT_IF_FIFO_FULL |

## Function Documentation

## ◆ SIPC_Params_init()

void SIPC_Params_init | ( | SIPC_Params * | params | ) |

Set default value to SIPC_Params.

Parameters

  params | [out] Default initialized structure

## ◆ SIPC_init()

int32_t SIPC_init | ( | SIPC_Params * | params | ) |

Initialize Secure IPC notify module.

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

Parameters

  params | [in] Initializaion parameters

## ◆ SIPC_deInit()

void SIPC_deInit | ( | void |  | ) |

De-initialize secure IPC Notify module.

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

## ◆ SIPC_sendMsg()

int32_t SIPC_sendMsg | ( | uint8_t | remoteSecCoreId,
|  | uint8_t | remoteClientId,
|  | uint8_t | localClientId,
|  | uint8_t * | msgValue,
|  | SIPC_fifoFlags | 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 < SIPC_CLIENT_ID_MAX and message value is < SIPC_CLIENT_ID_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

  remoteSecCoreId | [in] Remote core to sent message to, see
  remoteClientId | [in] Remote core client ID to send message to
  localClientId | [in] self core client ID from which the meessage is being sent
  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 [in] 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.

## ◆ SIPC_registerClient()

int32_t SIPC_registerClient | ( | uint8_t | localClientId,
|  | SIPC_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.

## ◆ SIPC_unregisterClient()

int32_t SIPC_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

## ◆ SIPC_getSelfCoreId()

uint32_t SIPC_getSelfCoreId | ( | void |  | ) |

Return current core ID.

Returns
  Core ID, see SIPC_coreId for valid values.

## ◆ SIPC_getSelfSecMasterId()

uint32_t SIPC_getSelfSecMasterId | ( | void |  | ) |

Return current core sec master ID.

Returns
  Core ID, see SIPC_SecCoreId for valid values.

## ◆ SIPC_isCoreEnabled()

uint32_t SIPC_isCoreEnabled | ( | uint32_t | coreId | ) |

Check if a core is enabled for SIPC.

Parameters

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

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