# IPC Module

The IPC (Inter-Processor Communication) Driver for Texas Instruments&reg;&nbsp; F28P65x 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_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_CPU2_L_CPU1_R`

      CPU2 - Local core, CPU1 - Remote core.

    enumerator `IPC_TOTAL_NUM`
  enum `IPC_FlashSemOwner`

    Values that can be passed to IPC_claimFlashSemaphore() in order to claim the flash semaphore.

    Values:

    enumerator `IPC_FLASHSEM_OWNER_CPU1` = 0x1
    enumerator `IPC_FLASHSEM_OWNER_CPU2` = 0x2

  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.

    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

    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 only.

    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

    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_claimFlashSemaphore`(IPC_FlashSemOwner semOwner)

    Claim the flash pump semaphore.

    Return

      None.

    Parameters

      - `semOwner`: is the cpu claiming the flash semaphore.

  void `IPC_releaseFlashSemaphore`(void)

    Release the flash pump semaphore.

    Return

      None.

    Parameters

      - `pumpSemBase`: is the base address of the flash pump semaphore.

  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.