IPC Module¶

The IPC (Inter-Processor Communication) Driver for Texas Instruments®  F2838x device provides a set of API functions for using the IPC module to communicate between the 3 cores (C28x1, C28x2 and CM)on the microcontroller. C28x1 and C28x2 are also referred to as CPU1 and CPU2 in this document and in the driver. Each core contains two different instances of IPC - one for each remote core.

group ipc_api

This module is used for inter-processor communications.

Defines

IPC_MSGQ_SUPPORT 1U¶

IPC_BUFFER_SIZE 4U¶

IPC_NUM_OF_INTERRUPTS 4U¶

IPC_FLAGS_DEFINED¶

IPC_NO_FLAG 0x00000000U¶: NO FLAG.

IPC_FLAG0 0x00000001U¶: IPC FLAG 0.

IPC_FLAG1 0x00000002U¶: IPC FLAG 1.

IPC_FLAG2 0x00000004U¶: IPC FLAG 2.

IPC_FLAG3 0x00000008U¶: IPC FLAG 3.

IPC_FLAG4 0x00000010U¶: IPC FLAG 4.

IPC_FLAG5 0x00000020U¶: IPC FLAG 5.

IPC_FLAG6 0x00000040U¶: IPC FLAG 6.

IPC_FLAG7 0x00000080U¶: IPC FLAG 7.

IPC_FLAG8 0x00000100U¶: IPC FLAG 8.

IPC_FLAG9 0x00000200U¶: IPC FLAG 9.

IPC_FLAG10 0x00000400U¶: IPC FLAG 10.

IPC_FLAG11 0x00000800U¶: IPC FLAG 11.

IPC_FLAG12 0x00001000U¶: IPC FLAG 12.

IPC_FLAG13 0x00002000U¶: IPC FLAG 13.

IPC_FLAG14 0x00004000U¶: IPC FLAG 14.

IPC_FLAG15 0x00008000U¶: IPC FLAG 15.

IPC_FLAG16 0x00010000U¶: IPC FLAG 16.

IPC_FLAG17 0x00020000U¶: IPC FLAG 17.

IPC_FLAG18 0x00040000U¶: IPC FLAG 18.

IPC_FLAG19 0x00080000U¶: IPC FLAG 19.

IPC_FLAG20 0x00100000U¶: IPC FLAG 20.

IPC_FLAG21 0x00200000U¶: IPC FLAG 21.

IPC_FLAG22 0x00400000U¶: IPC FLAG 22.

IPC_FLAG23 0x00800000U¶: IPC FLAG 23.

IPC_FLAG24 0x01000000U¶: IPC FLAG 24.

IPC_FLAG25 0x02000000U¶: IPC FLAG 25.

IPC_FLAG26 0x04000000U¶: IPC FLAG 26.

IPC_FLAG27 0x08000000U¶: IPC FLAG 27.

IPC_FLAG28 0x10000000U¶: IPC FLAG 28.

IPC_FLAG29 0x20000000U¶: IPC FLAG 29.

IPC_FLAG30 0x40000000U¶: IPC FLAG 30.

IPC_FLAG31 0x80000000U¶: IPC FLAG 31.

IPC_FLAG_ALL 0xFFFFFFFFU¶: All IPC flags.

IPC_INT0 0x0U¶: IPC Interrupt 0.

IPC_INT1 0x1U¶: IPC Interrupt 1.

IPC_INT2 0x2U¶: IPC Interrupt 2.

IPC_INT3 0x3U¶: IPC Interrupt 3.

IPC_INT4 0x4U¶: IPC Interrupt 4.

IPC_INT5 0x5U¶: IPC Interrupt 5.

IPC_INT6 0x6U¶: IPC Interrupt 6.

IPC_INT7 0x7U¶: IPC Interrupt 7.

IPC_ADDR_CORRECTION_ENABLE true¶

IPC_ADDR_CORRECTION_DISABLE false¶

IPC_BLOCKING_CALL true¶

IPC_NONBLOCKING_CALL false¶

IPC_PUMPREQUEST_REG IPC_Instance[IPC_CPU1_L_CPU2_R].IPC_Boot_Pump_Reg->IPC_PUMPREQUEST¶

IPC_MAX_BUFFER_INDEX (IPC_BUFFER_SIZE - 1U)¶

Enums

enum IPC_Type_t¶

Values that can be passed as parameter ipcType in all the driver functions

Values:

enumerator IPC_CPU1_L_CPU2_R¶: CPU1 - Local core, CPU2 - Remote core.

enumerator IPC_CPU1_L_CM_R¶: CPU1 - Local core, CM - Remote core.

enumerator IPC_CPU2_L_CPU1_R¶: CPU2 - Local core, CPU1 - Remote core.

enumerator IPC_CPU2_L_CM_R¶: CPU2 - Local core, CM - Remote core.

enumerator IPC_TOTAL_NUM¶

Functions

void IPC_setFlagLtoR(IPC_Type_t ipcType, uint32_t flags)¶

Local core sets Local to Remote IPC Flag

This function will allow the Local core system to set the designated IPC flags to send to the Remote core system. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the IPC flag mask for the flags being set

Return: None.

void IPC_clearFlagLtoR(IPC_Type_t ipcType, uint32_t flags)¶

Local core clears Local to Remote IPC Flag

This function will allow the Local core system to clear the designated IPC flags sent to the Remote core system. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the IPC flag mask for the flags being cleared

Return: None.

void IPC_ackFlagRtoL(IPC_Type_t ipcType, uint32_t flags)¶

Local core acknowledges Remote to Local IPC Flag.

This function will allow the Local core system to acknowledge/clear the IPC flag set by the Remote core system. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the IPC flag mask for the flags being acknowledged.

Return: None.

bool IPC_isFlagBusyLtoR(IPC_Type_t ipcType, uint32_t flags)¶

Determines whether the given IPC flags are busy or not.

Allows the caller to determine whether the designated Local to Remote IPC flags are pending. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the Local to Remote IPC flag masks to check the status of

Return: Returns true if the any of the designated IPC flags are busy or false if all the designated IPC flags are free.

bool IPC_isFlagBusyRtoL(IPC_Type_t ipcType, uint32_t flags)¶

Determines whether the given Remote to Local IPC flags are busy or not.

Allows the caller to determine whether the designated Remote to Local IPC flags are pending. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the Remote to Local IPC Flag masks to check the status of

Return: Returns true if the any of the designated IPC flags are busy or false if all the designated IPC flags are free.

void IPC_waitForFlag(IPC_Type_t ipcType, uint32_t flag)¶

Wait for the remote core to send a flag

Allows the caller to wait for the Remote to Local flag to be send by the remote core. The

flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flag: is the Remote to Local IPC flag mask to wait for

Return: None

void IPC_waitForAck(IPC_Type_t ipcType, uint32_t flag)¶

Wait for the IPC flag to be acknowledged

Allows the caller to wait for the IPC flag to be acknowledged by the remote core. The

flagsparameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flag: is the IPC flag mask for which ack is pending

Return: None

void IPC_sync(IPC_Type_t ipcType, uint32_t flag)¶

Synchronises the two cores

Allows the local and remote cores to synchronise. Neither core will return from this function call before the other core enters it.

Parameters

ipcType: is the enum corresponding to the IPC instance used
flag: is the IPC flag mask with which synchronisation is done

Note: Must be called with same flag mask on both the cores
Return: None

void IPC_init(IPC_Type_t ipcType)¶

Initialize IPC

Return

None

Parameters

ipcType: is the enum corresponding to the IPC instance used This function initializes IPC by clearing all the flags

bool IPC_sendCommand(IPC_Type_t ipcType, uint32_t flags, bool addrCorrEnable, uint32_t command, uint32_t addr, uint32_t data)¶

Sends a command to the Remote core

Allows the caller to send a command to the remote core. A command consists of a unique command value, a 32-bit address and a 32-bit data. The function also sends the designated flags to the remote core. There may be differences in the address spaces of Local and Remote core. For example in case of F2838X device, the address spaces of C28x core and CM core are different. In case the

addr refers to an address in the IPC MSG RAM, addrCorrEnable param may be used to correct the address mismatch

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the IPC flag mask for the flags to be set
addrCorrEnable: is the flag used to determine whether or not to convert the addr parameter to remote core’s address space
command: is the 32-bit command value
addr: is the 32-bit address to be sent as part of command
data: is the 32-bit data to be sent as part of command

The flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31. The addrCorrEnable parameter can take values IPC_ADDR_CORRECTION_ENABLE (converts the address to remote core’s address space) or IPC_ADDR_CORRECTION_DISABLE(does not modify the addr parmeter)

The application shall use the function IPC_getResponse to read the response sent by the remote core.

Note: The application is expected to wait until the the response is received before sending another command.
Note: addrCorrEnable parameter must be kept same on the sending and receiving cores
Return: Returns true if the command is sent properly and false if the designated flags were busy and hence command was not sent.

bool IPC_readCommand(IPC_Type_t ipcType, uint32_t flags, bool addrCorrEnable, uint32_t *command, uint32_t *addr, uint32_t *data)¶

Reads a command sent by the Remote core

Allows the caller to read a command sent by the remote core. A command consists of a unique command value, a 32-bit address and a 32-bit data. There may be differences in the address spaces of Local and Remote core. For example in case of F2838X device, the address spaces of C28x core and CM core are different. In case the

addr refers to an address in the IPC MSG RAM, addrCorrEnable param may be used to correct the address mismatch

Parameters

ipcType: is the enum corresponding to the IPC instance used
flags: is the IPC flag mask for the flags sent by the remote core
addrCorrEnable: is the flag used to determine whether or not to convert the addr parameter to remote core’s address space
command: is the 32-bit pointer at which the command value is read to
addr: is the 32-bit pointer at which address value is read to
data: is the 32-bit pointer at which the data is read to

The flags parameter can be any of the IPC flag values: IPC_FLAG0 - IPC_FLAG31. The addrCorrEnable parameter can take values IPC_ADDR_CORRECTION_ENABLE (converts the address to remote core’s address space) or IPC_ADDR_CORRECTION_DISABLE(does not modify the addr parmeter)

Note: The application is expected to acknowledge the flag and send a response (if needed) after reading the command
Note: addrCorrEnable parameter must be kept same on the sending and receiving cores
Return: Returns true if the command is read properly and false if the designated flags were empty and hence command was not read.

void IPC_sendResponse(IPC_Type_t ipcType, uint32_t data)¶

Sends the response to the command sent by remote core.

Allows the caller to send a response to the command previously sent by the remote core

Parameters

ipcType: is the enum corresponding to the IPC instance used
data: is the 32-bit value of the response to be sent

Return: None.

uint32_t IPC_getResponse(IPC_Type_t ipcType)¶

Reads the response from the remote core.

Allows the caller to read the response sent by the remote core to the command previously sent by the local core

Parameters

ipcType: is the enum corresponding to the IPC instance used

Return: the 32-bit value of the response.

void IPC_setBootMode(IPC_Type_t ipcType, uint32_t mode)¶

Sets the BOOTMODE register.

Allows the caller to set the BOOTMODE register.

Parameters

ipcType: is the enum corresponding to the IPC instance used
mode: is the 32-bit value to be set

Note: This function shall be called by CPU1 only.
Note: Boot registers are not available in CPU2<->CM IPC instance
Return: None

uint32_t IPC_getBootMode(IPC_Type_t ipcType)¶

Reads the BOOTMODE register.

Allows the caller to read the BOOTMODE register.

Parameters

ipcType: is the enum corresponding to the IPC instance used

Note: Boot registers are not available in CPU2<->CM IPC instance
Return: 32-bit value of the BOOOTMODE register

void IPC_setBootStatus(IPC_Type_t ipcType, uint32_t status)¶

Sets the BOOTSTS register.

Allows the caller to set the BOOTSTS register.

Parameters

ipcType: is the enum corresponding to the IPC instance used
status: is the 32-bit value to be set

Note: This function shall be called by CPU2 and CM only
Note: This function shall be called by CPU2 and CM only. Boot registers are not available in CPU2<->CM IPC instance
Return: None.

uint32_t IPC_getBootStatus(IPC_Type_t ipcType)¶

Reads the BOOTSTS register.

Allows the caller to set the BOOTMODE register.

Parameters

ipcType: is the enum corresponding to the IPC instance used

Note: Boot registers are not available in CPU2<->CM IPC instance
Return: 32-bit value of the BOOOTSTS register

uint64_t IPC_getCounter(IPC_Type_t ipcType)¶

Reads the timestamp counter value.

Allows the caller to read the IPC timestamp counter value.

Parameters

ipcType: is the enum corresponding to the IPC instance used

Return: 64-bit counter value.

void IPC_registerInterrupt(IPC_Type_t ipcType, uint32_t ipcInt, void (*pfnHandler)(void))¶

Registers an interrupt handler for IPC

This function registers the handler to be called when an IPC interrupt occurs. This function enables the global interrupt in the interrupt controller. The

ipcInt parameter can be any of the IPC flag values:IPC_INT0 - IPC_INT7. IPC_INT0 corresponds to IPC Flag 0 interrupt and so on.

Parameters

ipcType: is the enum corresponding to the IPC instance used
ipcInt: is the Flag number for which interrupt is being registered
pfnHandler: is the pointer to ISR function

void IPC_unregisterInterrupt(IPC_Type_t ipcType, uint32_t ipcInt)¶

Unregisters an interrupt handler for IPC

This function clears the handler to be called when an IPC interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called. The

ipcInt parameter can be any of the IPC flag values:IPC_INT0 - IPC_INT7. IPC_INT0 corresponds to IPC Flag 0 interrupt and so on.

Parameters

ipcType: is the enum corresponding to the IPC instance used
ipcInt: is the Flag number for which interrupt is being unregistered

void IPC_initMessageQueue(IPC_Type_t ipcType, volatile IPC_MessageQueue_t *msgQueue, uint32_t ipcInt_L, uint32_t ipcInt_R)¶

Initializes the IPC message queue

This function initializes the IPC message queue with circular buffer and index addresses for an IPC interrupt pair. The

ipcInt_L and ipcInt_R parameters can be one of the following values: IPC_INT0, IPC_INT1, IPC_INT2, IPC_INT3.

Parameters

ipcType: is the enum corresponding to the IPC instance used
msgQueue: specifies the address of a IPC_MessageQueue_t instance
ipcInt_L: specifies the interrupt number on the local core used by the message queue .
ipcInt_R: specifies the interrupt number on the remote core used by the message queue.

Note: If an interrupt is currently in use by an IPC_MessageQueue_t instance, that particular interrupt should not be tied to a second IPC_MessageQueue_t instance.
Note: For a particular ipcInt_L - ipcInt_R pair, there must be an instance of IPC_MessageQueue_t defined and initialized on both the locakl and remote systems.
Return: None.

bool IPC_sendMessageToQueue(IPC_Type_t ipcType, volatile IPC_MessageQueue_t *msgQueue, bool addrCorrEnable, IPC_Message_t *msg, bool block)¶

Sends a message into the messageQueue.

This function checks if there is a free slot in the message queue. If so, it puts the message pointed to by

msg into the free and sets the appropriate IPC interrupt flag

Parameters

ipcType: is the enum corresponding to the IPC instance used
msgQueue: specifies the address of a IPC_MessageQueue_t instance
addrCorrEnable: is the flag used to determine whether or not to convert the addr parameter to remote core’s address space
msg: specifies the address of the IPC_Message_t instance to be sent to message queue.
block: specifies whether to allow function to block until the buffer has a free slot

The addrCorrEnable parameter can take values IPC_ADDR_CORRECTION_ENABLE (converts the address to remote core’s address space) or IPC_ADDR_CORRECTION_DISABLE(does not modify the addr parmeter) The block parameter can be one of the following values: IPC_BLOCKING_CALL or IPC_NONBLOCKING_CALL.

Return: false if the queue is full. true if the message is successfully sent.

bool IPC_readMessageFromQueue(IPC_Type_t ipcType, volatile IPC_MessageQueue_t *msgQueue, bool addrCorrEnable, IPC_Message_t *msg, bool block)¶

Reads a message from the messageQueue.

This function checks if there is a message in the message queue. If so, it reads the message and writes to the address pointed to by

msg into.

Parameters

ipcType: is the enum corresponding to the IPC instance used
msgQueue: specifies the address of a IPC_MessageQueue_t instance
addrCorrEnable: is the flag used to determine whether or not to convert the addr parameter to remote core’s address space
msg: specifies the address of the IPC_Message_t instance to which the message needs to be read
block: specifies whether to allow function to block until a message is available in the message queue

The addrCorrEnable parameter can take values IPC_ADDR_CORRECTION_ENABLE (converts the address to remote core’s address space) or IPC_ADDR_CORRECTION_DISABLE(does not modify the addr parmeter) The block parameter can be one of the following values: IPC_BLOCKING_CALL or IPC_NONBLOCKING_CALL.

Return: false if the queue is empty. true if the message successfully read.

Variables

const IPC_Instance_t IPC_Instance[IPC_TOTAL_NUM]¶

struct IPC_Flag_Ctr_Reg_t¶: #include <ipc.h>

struct IPC_SendCmd_Reg_t¶: #include <ipc.h>

struct IPC_RecvCmd_Reg_t¶: #include <ipc.h>

struct IPC_Boot_Pump_Reg_t¶: #include <ipc.h>

struct IPC_Message_t¶: #include <ipc.h>

struct IPC_PutBuffer_t¶: #include <ipc.h>

struct IPC_GetBuffer_t¶: #include <ipc.h>

struct IPC_Instance_t¶: #include <ipc.h>

struct IPC_MessageQueue_t¶: #include <ipc.h>

There are two versions of IPC drivers in this device - one used by the C28x cores (present in the driverlib folder), the other used by the CM core (present in the driverlib_cm folder). With very few exceptions, the same IPC APIs are used by all the 3 processors. As a result all the APIs require a parameter indicating the IPC type that defines the local and remote cores. For example, IPC_CPU1_L_CPU2_R enum defines CPU1 as the local core and CPU2 as the remote core. This enum shall be used by the CPU1 core to communncate to CPU2 core.

The IPC driver can be configured to include or exclude the message queue support using the macro IPC_MSGQ_SUPPORT. The macro is set to 1 by default and includes message queue support. This feature creates some data structures in the IPC MSG RAM. If the application do not want the IPC message RAM to used by the driver, this macro can be set to 0. Make sure the macro value is the same on C28x and CM side IPC drivers.