PDK/PDK IPCLITE User Guide

Introduction

This IPC Lite module is built on top for mailbox driver to abstract functionality of mailboxes and makes it usable in software stack with or without operating system. ipc_lite library supports event multiplexing, which means application writers can register multiple callbacks for one remote core using single mailbox queue. It supports 32bit value to be transferred across from sender core to receiver core. ipc_lite library does not use any dynamic memory allocation or shared memory to transferring messages.

Design description and Interface

• Module: ipclib_interrupt - This module is responsible for implementing ipc_lite library API. This is expected to be platform independent and OS independent. The module holds static configuration of processors participating in IPC, Mailbox and interrupt (cross bar) configuration done by application.
• ipc_lite\src\ipclib_interrupt.c - This file contains the Ipc_lite APIs for inter processor communication using IPC interrupt module.
• ipc_lite\src\<$SOC>\ipclib_interrupt<$SOC>.c - Platform specific implementation of interrupt setup / connection

Ipclib module configuration

Ipclib module configuration is as mentioned below

• ipc_lite\src\<$SOC>\ipclib_interrupt<$SOC>ProcCfg.c - Platform specific implementation of available processors in the system. IpcLib API and utility functions operate on IpcLib_gProcConfig to get information about processor ids and names.
• ipc_lite\src\<$SOC>\ipclib_interrupt<$SOC>MailboxCfg.c - Platform specific implementation of mailbox base addresses and mailbox table that is used for N x N bidirectional communication. Each entry in this table indicates mailbox entry that is used for unidirectional communication from source to destination. Here Source and destinations are indexes to 2D IpcLib_gMailboxConfig. IE entries in the mailbox cfg file denote invalid entries, it means no mailbox is allocated for source to destination
• ipc_lite\src\<$SOC>\ipclib_interrupt<$SOC>XbarCfg.c - Platform specific implementation of local interrupt numbers and their connections. This can change based on platform using IpcLib in application

LE entry in the xbar config denotes last entry in the table

Ipclib message transfer sequence

Receiver's sequence

1. IpcLib_interruptSetDefaultInitPrm() (optional but advised)
2. Change params as required
3. IpcLib_interruptInit() - with valid params
4. IpcLib_interruptRegisterEvent() - with valid callback function   

Sender's sequence

1. IpcLib_interruptSetDefaultInitPrm() (optional but advised)
2. Change params as required
3. IpcLib_interruptInit() - with valid params
4. IpcLib_interruptSendEvent() - with valid payload and event id

Essentially ipc_lite library allows receivers to register multiple callback functions. Number of callbacks is capped by IPCLIB_MAX_EVENTS. The module maintains this callback table and delivers message to right callback upon receiving interrupt. It multiplexes over single interrupt line from sender M to receiver N. This gives applications more flexibility with minimal system resource usage.

Message delivery from sender to receiver

ipc_lite library allows 32 bit value to be sent across. Depending upon value of message it uses one or two mailbox entries. It uses last 5 bits of first message as eventId, if payload value fits into rest 27 bits it sends the single message or else it utilizes another message. ISR in the ipclib ensures messages are delivered correctly. These are implementation details and application writer need not worry about this.

Building the Library for TI RTOS/SYSBIOS

Note: By default ipc_Lite library is build for bare-metal use case and will not work in BIOS environment. This is because of the difference in how interrupts are registered in baremetal and SYSBIOS. To work with SYSBIOS environment user needs to re build with following changes

• Open "<pdk>/packages/ti/drv/ipc_lite/ipclite_component.mk"
• Change INCLUDE_SYSBIOS ?= no to INCLUDE_SYSBIOS ?= yes
• Perform clean and build the library again

Sample Application

ipc_lite_mbx_test_app

ipc_lite_mbx_test_app example uses IpcLib module to achieve inter-processor communication between all cores of supported SOC. The example shows how to configure IpcLib for a particular platform. It registers event for particular remote core. It shows how to send an interrupt to a remote core followed by un-registration of an event.
This application can be used for stress testing as well as debug issues with IpcLib. By default NUM_ITERATIONS macro in the application is set to 10000 this means, every configured core receives 10000 mailbox payloads (32 bit) from every other remote core. NUM_ITERATIONS can be changed to 1 for debugging purpose.
To enable additional debug prints users can enable ENABLE_MULTICORE_PRINTS but this is optional before build. By default all cores print the received payloads (messages) only after receiving all messages; it may take few seconds to see the complete output since it exchanges 10000 messages in NxN fashion if there are N cores in the SOC.

Running the example

• Launch target configuration, then load all the Gel files required.
• Switch settings in board should be set to debug mode.
• Connect and load executable on respective cores manually.
• Run all cores one by one

Note: : This example can be run using SBL also. Please refer to SBL user guide.