4.4.4.2.1. BIOS Application Configuration Files¶

The cores running BIOS in general has a config file which brings in all the modules needed to complete the application running on the specific core. This section explains the details of the entries in the config file. Note: The details here are just representative of a typical configuration. In general the configuration is customized based on the particular example.

var BIOS        = xdc.useModule('ti.sysbios.BIOS');
/*  This adds ipc Startup to be done part of BIOS  startup before main*/
BIOS.addUserStartupFunction('&IpcMgr_ipcStartup');

/* The following configures Debug libtype with Debug build */
if (Program.build.profile == "debug") {
     BIOS.libType = BIOS.LibType_Debug;
} else {
    BIOS.libType = BIOS.LibType_Custom;
}

var Sem = xdc.useModule('ti.sysbios.knl.Semaphore');
var instSem0_Params = new Sem.Params();
instSem0_Params.mode = Sem.Mode_BINARY;
Program.global.runOmpSem = Sem.create(0, instSem0_Params);
Program.global.runOmpSem_complete = Sem.create(0, instSem0_Params);

var Task = xdc.useModule('ti.sysbios.knl.Task');
Task.common$.namedInstance = true;

/* default memory heap */
var Memory = xdc.useModule('xdc.runtime.Memory');
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
var heapMemParams = new HeapMem.Params();
heapMemParams.size = 0x8000;
Memory.defaultHeapInstance = HeapMem.create(heapMemParams);

/* create a heap for MessageQ messages */
var HeapBuf = xdc.useModule('ti.sysbios.heaps.HeapBuf');
var params = new HeapBuf.Params;
params.align = 8;
params.blockSize = 512;
params.numBlocks = 20;

/* application uses the following modules and packages */
xdc.useModule('xdc.runtime.Assert');
xdc.useModule('xdc.runtime.Diags');
xdc.useModule('xdc.runtime.Error');
xdc.useModule('xdc.runtime.Log');
xdc.useModule('xdc.runtime.Registry');

xdc.useModule('ti.sysbios.knl.Semaphore');
xdc.useModule('ti.sysbios.knl.Task');

xdc.useModule('ti.sdo.ipc.Ipc');
xdc.useModule('ti.ipc.ipcmgr.IpcMgr');
var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
/* The following configures the PROC List */
MultiProc.setConfig("CORE0", ["HOST", "CORE0"]);

var msgHeap = HeapBuf.create(params);

var MessageQ  = xdc.useModule('ti.sdo.ipc.MessageQ');
/* Register msgHeap with messageQ */
MessageQ.registerHeapMeta(msgHeap, 0);

/* Enable Memory Translation module that operates on the Resource Table */
var Resource = xdc.useModule('ti.ipc.remoteproc.Resource');
Resource.loadSegment = Program.platform.dataMemory;

/* Setup MessageQ transport */
var VirtioSetup = xdc.useModule('ti.ipc.transports.TransportRpmsgSetup');
MessageQ.SetupTransportProxy = VirtioSetup;

/* Setup NameServer remote proxy */
var NameServer = xdc.useModule("ti.sdo.utils.NameServer");
var NsRemote = xdc.useModule("ti.ipc.namesrv.NameServerRemoteRpmsg");
NameServer.SetupProxy = NsRemote;

  /* system logger */
var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
var LoggerSysParams = new LoggerSys.Params();
var Defaults = xdc.useModule('xdc.runtime.Defaults');
Defaults.common$.logger = LoggerSys.create(LoggerSysParams);

/* enable runtime Diags_setMask() for non-XDC spec'd modules */
var Diags = xdc.useModule('xdc.runtime.Diags');
Diags.setMaskEnabled = true;

/* override diags mask for selected modules */
xdc.useModule('xdc.runtime.Main');
Diags.setMaskMeta("xdc.runtime.Main",
    Diags.ENTRY | Diags.EXIT | Diags.INFO, Diags.RUNTIME_ON);

var Registry = xdc.useModule('xdc.runtime.Registry');
Registry.common$.diags_ENTRY = Diags.RUNTIME_OFF;
Registry.common$.diags_EXIT  = Diags.RUNTIME_OFF;
Registry.common$.diags_INFO  = Diags.RUNTIME_OFF;
Registry.common$.diags_USER1 = Diags.RUNTIME_OFF;
Registry.common$.diags_LIFECYCLE = Diags.RUNTIME_OFF;
Registry.common$.diags_STATUS = Diags.RUNTIME_OFF;

var Main = xdc.useModule('xdc.runtime.Main');
Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;

var Idle = xdc.useModule('ti.sysbios.knl.Idle');
var Deh = xdc.useModule('ti.deh.Deh');

/* Must be placed before pwr mgmt */
Idle.addFunc('&ti_deh_Deh_idleBegin');

4.4.4.3.1. Generating Examples¶

The IPC product will come with the generated examples directory. The IPC product is what is typically delivered with SDKs such as Processor SDK. However, some SDKs point directly to the IPC git tree for the IPC source. In this case, the IPC Examples can be generated separately.

4.4.4.3.2. Tools¶

The following tools need to be installed:

• XDC tools (check the IPC release notes for compatible version)

4.4.4.3.3. Source Code¶

mkdir ipc
cd ipc
git clone git://git.ti.com/ipc/ipc-metadata.git
git clone git://git.ti.com/ipc/ipc-examples.git

Then checkout the IPC release tag that is associated with the IPC version being used. Do this for both repos. For example:

git checkout 3.42.01.03

4.4.4.3.4. Build¶

cd ipc-examples/src
make .examples XDC_INSTALL_DIR=<path_to_xdc_tools> IPCTOOLS=<path_to_ipc-metadata>/src/etc

For example:

make .examples XDC_INSTALL_DIR=/opt/ti/xdctools_3_32_00_06_core IPCTOOLS=/home/user/ipc/ipc-metadata/src/etc

The “examples” director will be generated in the path “ipc-examples/src/”:

ipc-examples/src/examples

4.4.6.1.1. Including Header Files¶

BIOS applications that use modules in the ti.sdo.ipc or ti.sdo.utils package should include the common header files provided in <ipc_install_dir>/packages/ti/ipc/. These header files offer a common API for both SYS/BIOS and HLOS users of IPC.

The following example C code includes header files applications may need to use. Depending on the APIs used in your application code, you may need to include different XDC, IPC, and SYS/BIOS header files.

#include <xdc/std.h>
#include <string.h>

/* ---- XDC.RUNTIME module Headers   */
#include <xdc/runtime/Memory.h>
#include <xdc/runtime/System.h>
#include <xdc/runtime/IHeap.h>

/* ----- IPC module Headers          */
#include <ti/ipc/GateMP.h>
#include <ti/ipc/Ipc.h>
#include <ti/ipc/MessageQ.h>
#include <ti/ipc/HeapBufMP.h>
#include <ti/ipc/MultiProc.h>

/* ---- BIOS6 module Headers         */
#include <ti/sysbios/BIOS.h>
#include <ti/sysbios/knl/Task.h>

/* ---- Get globals from .cfg Header */
#include <xdc/cfg/global.h>

Note that the appropriate include file location has changed from previous versions of IPC. The XDCtools-generated header files are still available in <ipc_install_dir>/packages/ti/sdo/ipc/, but these should not directly be included in runtime .c code. You should search your applications for “ti/sdo/ipc” and “ti/sdo/utils” and change the header file references found as needed. Additional changes to API calls will be needed.

Documentation for all common-header APIs is provided in Doxygen format in your IPC installation at <ipc_install_dir>/docs/doxygen/html/index.html. The latest version of that documentation is available online.

4.4.6.1.2. Standard IPC Function Call Sequence¶

For instance-based modules in IPC, the standard IPC methodology when creating object dynamically (that is, in C code) is to have the creator thread first initialize a MODULE_Params structure to its default values via a MODULE_Params_init() function. The creator thread can then set individual parameter fields in this structure as needed. After setting up the MODULE_Params structure, the creator thread calls the MODULE_create() function to creates the instance and initializes any shared memory used by the instance. If the instance is to be opened remotely, a unique name must be supplied in the parameters.

Other threads can access this instance via the MODULE_open() function, which returns a handle with access to the instance. The name that was used for instance creation must be used in the MODULE_open() function.

In most cases, MODULE_open() functions must be called in the context of a Task. This is because the thread running the MODULE_open() function needs to be able to block (to pend on a Semaphore in this case) while waiting for the remote processor to respond. The response from the remote processor triggers a hardware interrupt, which then posts a Semaphore to allow to Task to resume execution. The exception to this rule is that MODULE_open() functions do not need to be able to block when opening an instance on the local processor.

When the threads have finished using an instance, all threads that called MODULE_open() must call MODULE_close(). Then, the thread that called MODULE_create() can call MODULE_delete() to free the memory used by the instance.

Note that all threads that opened an instance must close that instance before the thread that created it can delete it. Also, a thread that calls MODULE_create() cannot call MODULE_close(). Likewise, a thread that calls MODULE_open() cannot call MODULE_delete().

4.4.6.1.3. Error Handling in IPC¶

Many of the APIs provided by IPC return an integer as a status code. Your application can test the status value returned against any of the provided status constants. For example:

MessageQ_Msg     msg;
MessageQ_Handle  messageQ;
Int              status;

...
status = MessageQ_get(messageQ, &msg, MessageQ_FOREVER);
    if (status < 0) {
        System_abort("Should not happen\n");
    }

Status constants have the following format: MODULE_[S|E]_CONDITION. For example, Ipc_S_SUCCESS, MessageQ_E_FAIL, and SharedRegion_E_MEMORY are status codes that may be returned by functions in the corresponding modules. Success codes always have values greater or equal to zero. For example, Ipc_S_SUCCESS=0 and Ipc_S_ALREADYSETUP=1; both are success codes. Failure codes always have values less than zero. Therefore, the presence of an error can be detected by simply checking whether the return value is negative.

Other APIs provided by IPC return a handle to a created object. If the handle is NULL, an error occurred when creating the object. For example:

messageQ = MessageQ_create(DSP_MESSAGEQNAME, NULL);
if (messageQ == NULL) {
    System_abort("MessageQ_create failed\n");
}

Refer to the Doxygen documentation for status codes returned by IPC functions.

4.4.6.2.1. Ipc Module Configuration (BIOS-side only)¶

In an XDCtools configuration file, you configure the Ipc module for use as follows:

Ipc = xdc.useModule('ti.sdo.ipc.Ipc');

You can configure what the Ipc_start() API will do–which modules it will start and which objects it will create–by using the Ipc.setEntryMeta method in the configuration file to set the following properties:

• setupNotify. If set to false, the Notify module is not set up. The default is true.
• setupMessageQ. If set to false, the MessageQ transport instances to remote processors are not set up and the MessageQ module does not attach to remote processors. The default is true.

For example, the following statements from the notify example configuration turn off the setup of the MessageQ transports and connections to remote processors:

/* To avoid wasting shared memory for MessageQ transports */
for (var i = 0; i < MultiProc.numProcessors; i++) {
    Ipc.setEntryMeta({
        remoteProcId: i,
        setupMessageQ: false,
    });
}

You can configure how the IPC module synchronizes processors by configuring the Ipc.procSync property. For example:

Ipc.procSync = Ipc.ProcSync_ALL;

The options are:

• Ipc.ProcSync_ALL. If you use this option, the Ipc_start() API automatically attaches to and synchronizes all remote processors. If you use this option, your application should never call Ipc_attach(). Use this option if all IPC processors on a device start up at the same time and connections should be established between every possible pair of processors.

• Ipc.ProcSync_PAIR. (Default) If you use this option, you must explicitly call Ipc_attach() to attach to a specific remote processor.

  If you use this option, Ipc_start() performs system-wide IPC initialization, but does not make connections to remote processors. Use this option if any or all of the following are true: - You need to control when synchronization with each remote processor occurs. - Useful work can be done while trying to synchronize with a remote processor by yielding a thread after each attempt to Ipc_attach() to the processor. - Connections to some remote processors are unnecessary and should be made selectively to save memory. - Ipc.ProcSync_NONE. If you use this option, Ipc_start() doesn’t synchronize any processors before setting up the objects needed by other modules.

  Use this option with caution. It is intended for use in cases where the application performs its own synchronization and you want to avoid a potential deadlock situation with the IPC synchronization.

  If you use the ProcSync_NONE option, Ipc_start() works exactly as it does with ProcSync_PAIR. : However, in this case, Ipc_attach() does not synchronize with the remote processor. As with other ProcSync options, Ipc_attach() still sets up access to GateMP, SharedRegion, Notify, NameServer, and MessageQ transports, so your application must still call Ipc_attach() for each remote processor that will be accessed. Note that an Ipc_attach() call for a remote processor whose ID is less than the local processor’s ID must occur after the corresponding remote processor has called Ipc_attach() to the local processor. For example, processor #2 can call Ipc_attach(1) only after processor #1 has called Ipc_attach(2).:

You can configure a function to perform custom actions in addition to the default actions performed when attaching to or detaching from a remote processor. These functions run near the end of Ipc_attach() and near the beginning of Ipc_detach(), respectively. Such functions must be non-blocking and must run to completion. The following example configures two attach functions and two detach functions. Each set of functions will be passed a different argument:

var Ipc = xdc.useModule('ti.sdo.ipc.Ipc');

var fxn = new Ipc.UserFxn;
fxn.attach = '&userAttachFxn1';
fxn.detach = '&userDetachFxn1';
Ipc.addUserFxn(fxn, 0x1);

fxn.attach = '&userAttachFxn2';
fxn.detach = '&userDetachFxn2';
Ipc.addUserFxn(fxn, 0x2);

The latest version of the IPC module configuration documentation is available here

4.4.6.2.2. Ipc Module APIs¶

In addition to the Ipc_start() API, which all applications that use IPC modules are required to call, the Ipc module also provides the following APIs for processor synchronization:

• Ipc_attach() Creates a connection to the specified remote processor.
• Ipc_detach() Deletes the connection to the specified remote processor.

You must call Ipc_start() on a processor before calling Ipc_attach().

Use these functions unless you are using the Ipc.ProcSync_ALL configuration setting. With that option, Ipc_start() automatically attaches to and synchronizes all remote processors, and your application should never call Ipc_attach().

The Ipc.ProcSync_PAIR configuration option expects that your application will call Ipc_attach() for each remote processor with which it should be able to communicate.

Processor synchronization means that one processor waits until the other processor signals that a particular module is ready for use. Within Ipc_attach(), this is done for the GateMP, SharedRegion (region 0), and Notify modules and the MessageQ transports.

You can call the Ipc_detach() API to delete internal instances created by Ipc_attach() and to free the memory used by these instances.

The latest version of the IPC module run-time API documentation is available online

4.4.6.3.1. Configuring the MessageQ Module (BIOS only)¶

On BIOS-based systems, you can configure a number of module-wide properties for MessageQ in your XDCtools configuration file.

A snapshot of the MessageQ module configuration documentation is available online.

To configure the MessageQ module, you must enable the module as follows:

var MessageQ = xdc.useModule('ti.sdo.ipc.MessageQ');

Some example Module-wide configuration properties you can set follow; refer to the IPC documentation for details.

// Maximum length of MessageQ names
MessageQ.maxNameLen = 32;

// Max number of MessageQs that can be dynamically created
MessageQ.maxRuntimeEntries = 10;

4.4.6.3.2. Creating a MessageQ Object¶

You can create message queues dynamically. Static creation is not supported. A MessageQ object is not a shared resource. That is, it resides on the processor, within the process, that creates it.

The reader thread creates a message queue. To create a MessageQ object dynamically, use the MessageQ_create() C API, which has the following syntax:

MessageQ_Handle MessageQ_create(String name, MessageQ_Params *params);

When you create a queue, you specify a name string. This name will be needed by the MessageQ_open() function, which is called by threads on the same or remote processors that want to send messages to the created message queue. While the name is not required (that is, it can be NULL), an unnamed queue cannot be opened.

An ISync handle is associated with the message queue via the synchronizer parameter.

If the call is successful, the MessageQ_Handle is returned. If the call fails, NULL is returned.

You initialize the params struct by using the MessageQ_Params_init() function, which initializes the params structure with the default values. A NULL value for params can be passed into the create call, which results in the defaults being used. The default synchronizer is SyncSem.

The following code creates a MessageQ object using SyncSem as the synchronizer.

MessageQ_Handle   messageQ;
MessageQ_Params   messageQParams;
SyncSem_Handle    syncSemHandle;

...

syncSemHandle = SyncSem_create(NULL, NULL);
MessageQ_Params_init(&messageQParams);
messageQParams.synchronizer = SyncSem_Handle_upCast(syncSemHandle);
messageQ = MessageQ_create(CORE0_MESSAGEQNAME, &messageQParams);

In this example, the CORE0_MESSAGEQNAME constant may be defined in header shared by multiple cores.

A snapshot of the MessageQ module run-time API documentation is available online.

4.4.6.3.3. Opening a Message Queue¶

Writer threads open a created message queue to get access to them. In order to obtain a handle to a message queue that has been created, a writer thread must call MessageQ_open(), which has the following syntax.

Int MessageQ_open(String name, MessageQ_QueueId *queueId);

This function expects a name, which must match with the name of the created object. Internally MessageQ calls NameServer_get() to find the 32-bit queueId associated with the created message queue. NameServer looks both locally and remotely.

If no matching name is found on any processor, MessageQ_open() returns MessageQ_E_NOTFOUND. If the open is successful, the Queue ID is filled in and MessageQ_S_SUCCESS is returned.

The following code opens the MessageQ object created by the processor.

MessageQ_QueueId   remoteQueueId;
Int                status;

...

/* Open the remote message queue. Spin until it is ready. */
do {
   status = MessageQ_open(CORE0_MESSAGEQNAME, &remoteQueueId);
}
while (status < 0);

4.4.6.3.4. Allocating a Message¶

MessageQ manages message allocation via the MessageQ_alloc() and MessageQ_free() functions. MessageQ uses Heaps for message allocation. MessageQ_alloc() has the following syntax:

MessageQ_Msg MessageQ_alloc(UInt16        heapId,
                            UInt32        size);

The allocation size in MessageQ_alloc() must include the size of the message header, which is 32 bytes.

The following code allocates a message:

#define MSGSIZE                  256
#define HEAPID                     0
...
MessageQ_Msg     msg;

...

msg = MessageQ_alloc(HEAPID, sizeof(MessageQ_MsgHeader));
if (msg == NULL) {
    System_abort("MessageQ_alloc failed\n");
}

Once a message is allocated, it can be sent on any message queue. Once the reader receives the message, it may either free the message or re-use the message. Messages in a message queue can be of variable length. The only requirement is that the first field in the definition of a message must be a MsgHeader structure. For example:

typedef struct MyMsg {
    MessageQ_MsgHeader header;     // Required
    SomeEnumType       type        // Can be any field
    ...                            // ...
} MyMsg;

The MessageQ APIs use the MessageQ_MsgHeader internally. Your application should not modify or directly access the fields in the MessageQ_MsgHeader structure.

/* Register this heap with MessageQ */
status = MessageQ_registerHeap( HeapBufMP_Handle_upCast(heapHandle), HEAPID);

4.4.6.3.5. Sending a Message¶

Once a message queue is opened and a message is allocated, the message can be sent to the MessageQ via the MessageQ_put() function, which has the following syntax.

Int MessageQ_put(MessageQ_QueueId queueId,
               MessageQ_Msg     msg);

For example:

status = MessageQ_put(remoteQueueId, msg);

Opening a queue is not required. Instead the message queue ID can be “discovered” via the MessageQ_getReplyQueue() function, which returns the 32-bit queueId.

MessageQ_QueueId replyQueue;
MessageQ_Msg     msg;

/* Use the embedded reply destination */
replyMessageQ = MessageQ_getReplyQueue(msg);
if (replyMessageQ == MessageQ_INVALIDMESSAGEQ) {
    System_abort("Invalid reply queue\n");
}

/* Send the response back */
status = MessageQ_put(replyQueue, msg);
    if (status < 0) {
        System_abort("MessageQ_put was not successful\n");
    }

If the destination queue is local, the message is placed on the appropriate priority linked list and the ISync signal function is called. If the destination queue is on a remote processor, the message is given to the proper transport and returns.

If MessageQ_put() succeeds, it returns MessageQ_S_SUCCESS. If MessageQ_E_FAIL is returned, an error occurred and the caller still owns the message.

There can be multiple senders to a single message queue. MessageQ handles the thread safety.

Before you send a message, you can use the MessageQ_setMsgId() function to assign a numeric value to the message that can be checked by the receiving thread.

/* Increment...the remote side will check this */
msgId++;
MessageQ_setMsgId(msg, msgId);

You can use the MessageQ_setMsgPri() function to set the priority of the message.

4.4.6.3.6. Receiving a Message¶

To receive a message, a reader thread calls the MessageQ_get() API.

Int MessageQ_get(MessageQ_Handle handle,
                 MessageQ_Msg    *msg,
                 UInt            timeout)

If a message is present, it returned by this function. In this case the ISync’s wait() function is not called. For example:

/* Get a message */
status = MessageQ_get(messageQ, &msg, MessageQ_FOREVER);
if (status < 0) {
     System_abort("Should not happen; timeout is forever\n");
}

If no message is present and no error occurs, this function blocks while waiting for the timeout period for the message to arrive. If the timeout period expires, MessageQ_E_FAIL is returned. If an error occurs, the msg argument will be unchanged.

After receiving a message, you can use the following APIs to get information about the message from the message header:

• MessageQ_getMsgId() gets the ID value set by MessageQ_setMsgId(). For example:

/* Get the id and increment it to send back */
msgId = MessageQ_getMsgId(msg);
msgId += NUMCLIENTS;
MessageQ_setMsgId(msg, msgId);

• MessageQ_getMsgPri() gets the priority set by MessageQ_setMsgPri().
• MessageQ_getMsgSize() gets the size of the message in bytes.
• MessageQ_getReplyQueue() gets the ID of the queue provided by MessageQ_setReplyQueue().

4.4.6.3.7. Deleting a MessageQ Object¶

MessageQ_delete() frees a MessageQ object stored in local memory. If any messages are still on the internal linked lists, they will be freed. The contents of the handle are nulled out by the function to prevent use after deleting.

Void MessageQ_delete(MessageQ_Handle *handle);

The queue array entry is set to NULL to allow re-use.

Once a message queue is deleted, no messages should be sent to it. A MessageQ_close() is recommended, but not required.

4.4.6.3.8. Message Priorities¶

MessageQ supports three message priorities as follows:

• MessageQ_NORMALPRI = 0
• MessageQ_HIGHPRI = 1
• MessageQ_URGENTPRI = 3

You can set the priority level for a message before sending it by using the MessageQ_setMsgPri() function:

Void MessageQ_setMsgPri(MessageQ_Msg        msg,
                      MessageQ_Priority   priority)

Internally a MessageQ object maintains two linked lists: normal and high-priority. A normal priority message is placed onto the “normal” linked list in FIFO manner. A high priority message is placed onto the “high-priority” linked list in FIFO manner. An urgent message is placed at the beginning of the high linked list.

When getting a message, the reader checks the high priority linked list first. If a message is present on that list, it is returned. If not, the normal priority linked list is checked. If a message is present there, it is returned. Otherwise the synchronizer’s wait function is called.

4.4.6.3.9. Thread Synchronization (BIOS only)¶

MessageQ supports reads and writes of different thread models. It can work with threading models that include SYS/BIOS’s Hwi, Swi, and Task threads.

This flexibility is accomplished by using an implementation of the xdc.runtime.knl.ISync interface. The creator of the message queue must also create an object of the desired ISync implementation and assign that object as the “synchronizer” of the MessageQ. Each message queue has its own synchronizer object.

An ISync object has two main functions: signal() and wait(). Whenever MessageQ_put() is called, the signal() function of the ISync implementation is called. If MessageQ_get() is called when there are no messages on the queue, the wait() function of the ISync implementation is called. The timeout passed into the MessageQ_get() is directly passed to the ISync wait() API.

For example, if the reader is a SYS/BIOS Swi, the instance could be a SyncSwi. When a MessageQ_put() is called, the Swi_post() API would be called. The Swi would run and it must call MessageQ_get() until no messages are returned. If the Swi does not get all the messages, the Swi will not run again, or at least will not run until a new message is placed on the queue.

The calls to ISync functions occurs directly in MessageQ_put() when the call occurs on the same processor where the queue was created. In the remote case, the transport calls MessageQ_put(), which is then a local put, and the signal function is called.

The following are ISync implementations provided by XDCtools and SYS/BIOS:

• xdc.runtime.knl.SyncNull. The signal() and wait() functions do nothing. Basically this implementation allows for polling.
• xdc.runtime.knl.SyncSemThread. An implementation built using the xdc.runtime.knl.Semaphore module, which is a binary semaphore.
• xdc.runtime.knl.SyncGeneric.xdc. This implementation allows you to use custom signal() and wait() functions as needed.
• ti.sysbios.syncs.SyncSem. An implementation built using the ti.sysbios.ipc.Semaphore module. The signal() function runs a Semaphore_post(). The wait() function runs a Semaphore_pend().
• ti.sysbios.syncs.SyncSwi. An implementation built using the ti.sysbios.knl.Swi module. The signal() function runs a Swi_post(). The wait() function does nothing and returns FALSE if the timeout elapses.
• ti.sysbios.syncs.SyncEvent. An implementation built using the ti.sysbios.ipc.Event module. The signal() function runs an Event_post(). The wait() function does nothing and returns FALSE if the timeout elapses. This implementation allows waiting on multiple events.

The following code from the “message” example creates a SyncSem instance and assigns it to the synchronizer field in the MessageQ_Params structure before creating the MessageQ instance:

#include <ti/sysbios/syncs/SyncSem.h>
...

MessageQ_Params   messageQParams;
SyncSem_Handle    syncSemHandle;

/* Create a message queue using SyncSem as synchronizer */
syncSemHandle = SyncSem_create(NULL, NULL);
MessageQ_Params_init(&messageQParams);
messageQParams.synchronizer = SyncSem_Handle_upCast(syncSemHandle);
messageQ = MessageQ_create(CORE1_MESSAGEQNAME, &messageQParams, NULL);

4.4.6.3.10. ReplyQueue¶

For some applications, doing a MessageQ_open() on a queue is not realistic. For example, a server may not want to open all the clients’ queues for sending responses. To support this use case, the message sender can embed a reply queueId in the message using the MessageQ_setReplyQueue() function.

Void MessageQ_setReplyQueue(MessageQ_Handle handle,
                          MessageQ_Msg msg)

This API stores the message queue’s queueId into fields in the MsgHeader.

The MessageQ_getReplyQueue() function does the reverse. For example:

MessageQ_QueueId replyQueue;
MessageQ_Msg     msg;
...

/* Use the embedded reply destination */
replyMessageQ = MessageQ_getReplyQueue(msg);
if (replyMessageQ == MessageQ_INVALIDMESSAGEQ) {
   System_abort("Invalid reply queue\n");
}

The MessageQ_QueueId value returned by this function can then be used in a MessageQ_put() call.

The queue that is embedded in the message does not have to be the sender’s queue.

4.4.6.3.11. Remote Communication via Transports (BIOS only)¶

MessageQ is designed to support multiple processors. To allow this, different transports can be plugged into MessageQ.

In a multi-processor system, MessageQ communicates with other processors via ti.sdo.ipc.interfaces.IMessageQTransport instances. There can be up to two IMessageQTransport instances for each processor to which communication is desired. One can be a normal-priority transport and the other for handling high-priority messages. This is done via the priority parameter in the transport create() function. If there is only one register to a remote processor (either normal or high), all messages go via that transport.

There can be different transports on a processor. For example, there may be a shared memory transport to processor A and an sRIO one to processor B.

When your application calls Ipc_start(), the default transport instance used by MessageQ is created automatically. Internally, transport instances are responsible for registering themselves with MessageQ via the MessageQ_registerTransport() function.

IPC provides an implementation of the IMessageQTransport interface called ti.sdo.ipc.transports.TransportShm (shared memory). You can write other implementations to meet your needs.

When a transport is created via a transport-specific create() call, a remote processor ID (defined via the MultiProc module) is specified. This ID denotes which processor this instance communicates with. Additionally there are configuration properties for the transport–such as the message priority handled–that can be defined in a Params structure. The transport takes these pieces of information and registers itself with MessageQ. MessageQ now knows which transport to call when sending a message to a remote processor.

Trying to send to a processor that has no transport results in an error.

MessageQ_QueueId MessageQ_getDstQueue(MessageQ_Msg msg)

4.4.6.3.12. Sample Runtime Program Flow (Dynamic)¶

The following figure shows the typical sequence of events when using a MessageQ. A message queue is created by a Task. An open on the same processor then occurs. Assume there is one message in the system. The opener allocates the message and sends it to the created message queue, which gets and frees it.

4.4.6.5.1. Configuring a Heap*MP Module¶

In addition to configuring Heap*MP instances, you can set module-wide configuration properties. For example, the maxNameLen property lets you set the maximum length of heap names. The track[Max]Allocs module configuration property enables/disables tracking memory allocation statistics.

A Heap*MP instance uses a NameServer instance to manage name/value pairs.

The Heap*MP modules make the following assumptions:

• The SharedRegion module handles address translation between a virtual shared address space and the local processor’s address space. If the memory address spaces are identical across all processors, or if a single processor is being used, no address translation is required and the SharedRegion module must be appropriately configured.
• Both processors must have the same endianness.

4.4.6.5.2. Creating a Heap*MP Instance¶

Heaps can be created dynamically. You use the Heap*MP_create() functions to dynamically create Heap*MP instances. As with other IPC modules, before creating a Heap*MP instance, you initialize a Heap*MP_Params structure and set fields in the structure to the desired values. When you create a heap, the shared memory is initialized and the Heap*MP object is created in local memory. Only the actual buffers and some shared information reside in shared memory.

The following code example initializes a HeapBufMP_Params structure and sets fields in it. It then creates and registers an instance of the HeapBufMP module.

/* Create the heap that will be used to allocate messages. */
HeapBufMP_Params_init(&heapBufMPParams);
heapBufMPParams.regionId      = 0;        /* use default region */
heapBufMPParams.name          = "myHeap";
heapBufMPParams.align         = 256;
heapBufMPParams.numBlocks     = 40;
heapBufMPParams.blockSize     = 1024;
heapBufMPParams.gate          = NULL;     /* use system gate */
heapHandle = HeapBufMP_create(&heapBufMPParams);
if (heapHandle == NULL) {
    System_abort("HeapBufMP_create failed\n");
}

/* Register this heap with MessageQ */
MessageQ_registerHeap(HeapBufMP_Handle_upCast(heapHandle), HEAPID);

The parameters for the various Heap*MP implementations vary. For example, when you create a HeapBufMP instance, you can configure the following parameters after initializing the HeapBufMP_Params structure:

• regionId. The index corresponding to the shared region from which shared memory will be allocated.
• name. A name of the heap instance for NameServer (optional).
• align. Requested alignment for each block.
• numBlocks. Number of fixed size blocks.
• blockSize. Size of the blocks in this instance.
• gate. A multiprocessor gate for context protection.
• exact. Only allocate a block if the requested size is an exact match. Default is false.

Of these parameters, the ones that are common to all three Heap*MP implementations are gate, name and regionId.

4.4.6.5.3. Opening a Heap*MP Instance¶

Once a Heap*MP instance is created on a processor, the heap can be opened on another processor to obtain a local handle to the same shared instance. In order for a remote processor to obtain a handle to a Heap*MP that has been created, the remote processor needs to open it using Heap*MP_open().

The Heap*MP modules use a NameServer instance to allow a remote processor to address the local Heap*MP instance using a user-configurable string value as an identifier. The Heap*MP name is the sole parameter needed to identify an instance.

The heap must be created before it can be opened. An open call matches the call’s version number with the creator’s version number in order to ensure compatibility. For example:

HeapBufMP_Handle heapHandle; ...

/* Open heap created by other processor. Loop until open. */
do {
    status = HeapBufMP_open("myHeap", &heapHandle);
}
while (status < 0);

/* Register this heap with MessageQ */
MessageQ_registerHeap(HeapBufMP_Handle_upCast(heapHandle), HEAPID);

4.4.6.5.4. Closing a Heap*MP Instance¶

Heap*MP_close() frees an opened Heap*MP instance stored in local memory. Heap*MP_close() may only be used to finalize instances that were opened with Heap*MP_open() by this thread. For example:

HeapBufMP_close(&heapHandle);

Never call Heap*MP_close() if some other thread has already called Heap*MP_delete().

4.4.6.5.5. Deleting a Heap*MP Instance¶

The Heap*MP creator thread can use Heap*MP_delete() to free a Heap*MP object stored in local memory and to flag the shared memory to indicate that the heap is no longer initialized. Heap*MP_delete() may not be used to finalize a heap using a handle acquired using Heap*MP_open()–Heap*MP_close() should be used by such threads instead.

4.4.6.5.6. Allocating Memory from the Heap¶

The HeapBufMP_alloc() function obtains the first buffer off the heap’s freeList.

The HeapMultiBufMP_alloc() function searches through the buckets to find the smallest size that honors the requested size. It obtains the first block on that bucket.

If the “exact” field in the Heap*BufMP_Params structure was true when the heap was created, the alloc only returns the block if the blockSize for a bucket is the exact size requested. If no exact size is found, an allocation error is returned.

The HeapMemMP_alloc() function allocates a block of memory of the requested size from the heap.

For all of these allocation functions, the cache coherency of the message is managed by the SharedRegion module that manages the shared memory region used for the heap.

4.4.6.5.7. Freeing Memory to the Heap¶

The HeapBufMP_free() function returns an allocated buffer to its heap.

The HeapMultiBufMP_free() function searches through the buckets to determine on which bucket the block should be returned. This is determined by the same algorithm as the HeapMultiBufMP_alloc() function, namely the smallest blockSize that the block can fit into.

If the “exact” field in the Heap*BufMP_Params structure was true when the heap was created, and the size of the block to free does not match any bucket’s blockSize, an assert is raised.

The HeapMemMP_free() function returns the allocated block of memory to its heap.

For all of these deallocation functions, cache coherency is managed by the corresponding Heap*MP module.

4.4.6.5.8. Querying Heap Statistics¶

Both heap modules support use of the xdc.runtime.Memory module’s Memory_getStats() and Memory_query() functions on the heap.

In addition, the Heap*MP modules provide the Heap*MP_getStats(), Heap*MP_getExtendedStats(), and Heap*MP_isBlocking() functions to enable you to gather information about a heap.

By default, allocation tracking is often disabled in shared-heap modules for performance reasons. You can set the HeapBufMP.trackAllocs and HeapMultiBufMP.trackMaxAllocs configuration properties to true in order to turn on allocation tracking for their respective modules. Refer to the CDOC documentation for further information.

Sample Runtime Program Flow The following diagram shows the program flow for a two-processor (or two-thread) application. This application creates a Heap*MP instance dynamically.

4.4.6.6.1. Creating a GateMP Instance¶

As with other IPC modules, GateMP instances can only be created dynamically.

Before creating the GateMP instance, you initialize a GateMP_Params structure and set fields in the structure to the desired values. You then use the GateMP_create() function to dynamically create a GateMP instance.

When you create a gate, shared memory is initialized, but the GateMP object is created in local memory. Only the gate information resides in shared memory.

The following code creates a GateMP object:

GateMP_Params gparams;
GateMP_Handle gateHandle;

GateMP_Params_init(&gparams);
gparams.localProtect = GateMP_LocalProtect_THREAD;
gparams.remoteProtect = GateMP_RemoteProtect_SYSTEM;
gparams.name = "myGate";
gparams.regionId = 1;
gateHandle = GateMP_create(&gparams, NULL);

A gate can be configured to implement remote processor protection in various ways. This is done via the params.remoteProtect configuration property. The options for params.remoteProtect are as follows:

• GateMP_RemoteProtect_NONE. Creates only the local gate specified by the localProtect property.
• GateMP_RemoteProtect_SYSTEM. Uses the default device-specific gate protection mechanism for your device. Internally, GateMP automatically uses device-specific implementations of multi-processor mutexes implemented via a variety of hardware mechanisms. Devices typically support a single type of system gate, so this is usually the correct configuration setting for params.remoteProtect.
• GateMP_RemoteProtect_CUSTOM1 and GateMP_RemoteProtect_CUSTOM2 (BIOS-only). Some devices support multiple types of system gates. If you know that GateMP has multiple implementations of gates for your device, you can use one of these options.

Several gate implementations used internally for remote protection are provided in the ti.sdo.ipc.gates package.

A gate can be configured to implement local protection at various levels. This is done via the params.localProtect configuration property (BIOS-only). The options for params.localProtect are as follows:

• GateMP_LocalProtect_NONE. Uses the XDCtools GateNull implementation, which does not offer any local context protection. For example, you might use this option for a single-threaded local application that still needs remote protection.
• GateMP_LocalProtect_INTERRUPT. Uses the SYS/BIOS GateHwi implementation, which disables hardware interrupts.
• GateMP_LocalProtect_TASKLET. Uses the SYS/BIOS GateSwi implementation, which disables software interrupts.
• GateMP_LocalProtect_THREAD. Uses the SYS/BIOS GateMutexPri implementation, which is based on Semaphores. This option may use a different gate than the following option on some operating systems. When using SYS/BIOS, they are equivalent.
• GateMP_LocalProtect_PROCESS. Uses the SYS/BIOS GateMutexPri implementation, which is based on Semaphores.

This property is currently ignored (as of IPC 3.23) on non-BIOS OSes. A thread-level mutex is used for local protection independent of this property setting.

Other fields you are required to set in the GateMP_Params structure are:

• name. The name of the GateMP instance.
• regionId. The ID of the SharedRegion to use for shared memory used by this GateMP instance (BIOS-only).

The latest version of the GateMP module run-time API documentation is available online

4.4.6.6.2. Opening a GateMP Instance¶

Once an instance is created on a processor, the gate can be opened on another processor to obtain a local handle to the same instance.

The GateMP module uses a NameServer instance to allow a remote processor to address the local GateMP instance using a user-configurable string value as an identifier rather than a potentially dynamic address value.

status = GateMP_open("myGate", &gateHandle);
if (status < 0) {
    System_printf("GateMP_open failed\n");
}

4.4.6.6.3. Closing a GateMP Instance¶

GateMP_close() frees a GateMP object stored in local memory.

GateMP_close() should never be called on an instance whose creator has been deleted.

4.4.6.6.4. Deleting a GateMP Instance¶

GateMP_delete() frees a GateMP object stored in local memory and flags the shared memory to indicate that the gate is no longer initialized.

A thread may not use GateMP_delete() if it acquired the handle to the gate using GateMP_open(). Such threads should call GateMP_close() instead.

4.4.6.6.5. Entering a GateMP Instance¶

Either the GateMP creator or opener may call GateMP_enter() to enter a gate. While it is necessary for the opener to wait for a gate to be created to enter a created gate, it isn’t necessary for a creator to wait for a gate to be opened before entering it.

GateMP_enter() enters the caller’s local gate. The local gate (if supplied) blocks if entered on the local processor. If entered by the remote processor, GateMP_enter() spins until the remote processor has left the gate.

No matter what the params.localProtection configuration property is set to, after GateMP_enter() returns, the caller has exclusive access to the data protected by this gate.

A thread may reenter a gate without blocking or failing.

GateMP_enter() returns a “key” that is used by GateMP_leave() to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.

IArg key;

/* Enter the gate */
key = GateMP_enter(gateHandle);

4.4.6.6.6. Leaving a GateMP Instance¶

GateMP_leave() may only called by a thread that has previously entered this gate via GateMP_enter().

After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).

IArg key;

/* Leave the gate */
GateMP_leave(gateHandle, key);

4.4.6.6.7. Querying a GateMP Instance¶

GateMP_query() returns TRUE if a gate has a given quality, and FALSE otherwise, including cases when the gate does not recognize the constant describing the quality. The qualities you can query are:

• GateMP_Q_BLOCKING. If GateMP_Q__BLOCKING is FALSE, the gate never blocks.
• GateMP_Q_PREEMPTING. If GateMP_Q_PREEMPTING is FALSE, the gate does not allow other threads to preempt the thread that has already entered the gate.

4.4.6.6.8. NameServer Interaction¶

The GateMP module uses a ti.sdo.utils.NameServer instance to store instance information when an instance is created and the name parameter is non-NULL. The length of this name is limited to 16 characters (by default) including the null terminator (‘0’). This length can be increased by configuring the GateMP.maxNameLen module configuration property. If a name is supplied, it must be unique for all GateMP instances.

Other modules can use GateMP instances to protect access to their shared memory resources. For example, the NameServer name tables are protected by setting the “gate” property of the ti.sdo.utils.NameServer module.

These examples set the “gate” property for various modules:

heapBufMPParams.gate  = GateMP_getDefaultRemote();
listMPParams.gate     = gateHandle;

4.4.6.6.9. Sample Runtime Program Flow (Dynamic)¶

The following diagram shows the program flow for a two-processor (or two-thread) application. This application creates a Gate dynamically.

4.4.6.7.1. Introduction¶

Starting in IPC 3.42, the GateMP module added support for accessing device memory without using /dev/mem. Instead of accessing /dev/mem, a uio driver for Shared Region 0 access and a misc driver to expose a hwspinlock user interface can be used. These drivers are added in the Android SDK and GLSDK kernels. This feature was added because in some environments, /dev/mem may not be accessible to the LAD.

4.4.6.7.2. Config¶

Enable the uio and misc drivers in the kernel by enabling the following config options:

CONFIG_HWSPINLOCK_USER=y CONFIG_UIO=y CONFIG_UIO_PDRV_GENIRQ=y Update your dts file to define the hwspinlocks being used by the misc driver. Must start from hwspinlock “0” and go up sequentially:

gatemp {
        compatible = "hwspinlock-user";
        hwlocks = <&hwspinlock 0>,
                  <&hwspinlock 1>,
                  <&hwspinlock 2>,
                  <&hwspinlock 3>,
                  <&hwspinlock 4>,
                  <&hwspinlock 5>,
                  <&hwspinlock 6>,
                  <&hwspinlock 7>,
                  <&hwspinlock 8>,
                  <&hwspinlock 9>;
};

The hwspinlock configuration in the dts file MUST match the BIOS-side IPC HWSpinlock configuration. Configuration the BIOS-side IPC module by adding the following to your cfg file (where <N> is equal to the number of spinlocks in the dts listing):

var HWSpinlock = xdc.useModule(‘ti.sdo.ipc.gates.GateHWSpinlock’);
HWSpinlock.numLocks = <N>;

Update your dts file to add the UIO-based node for Shared Region 0 (modify address and size so that it matches the Shared Region 0 definition in the remote core image):

Kernel 3.14-based releases:

sr0 {
        compatible = "generic-uio";
        reg = <0xbfd00000 0x100000>;
};

Kernel 4.4-based releases:

sr0 {
        compatible = "generic-uio";
        reg = <0x0 0xbfb00000 0x0 0x100000>;
};

Append the following to the kernel’s CONFIG_CMDLINE:

uio_pdrv_genirq.of_id=generic-uio

For example:

CONFIG_CMDLINE="root=/dev/mmcblk0p2 rw console=ttyS0,119200 androidboot.console=ttyS0 init=/init rootfstype=ext4 rootwait drm.rnodes=1 snd.slots_reserved=1,1 androidboot.selinux=permissive androidboot.hardware=jacinto6evmboard uio_pdrv_genirq.of_id=generic-uio"

Also, specific owner/group must be set for the following files:

• /dev/uio0
• /dev/hwspinlock
• Android: /data/lad, /data/lad/LAD
• Linux: /tmp/LAD

4.4.6.9.1. Adding Table Entries Statically¶

To create a shared region lookup table in the XDCtools configuration, first determine the shared memory regions you plan to use.

Next, specify the maximum number of entries in the lookup table with the SharedRegion.numEntries property. You can specify a value for the SharedRegion.cacheLineSize configuration property, which is the default cache line size if no size is specified for a region. You can also specify the value of the SharedRegion.translate property, which should only be set to false if all shared memory regions have the same base address on all processors. Setting the translate property to false improves performance because no address translation is performed.

For example:

var SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');
SharedRegion.cacheLineSize = 32;
SharedRegion.numEntries = 4;
SharedRegion.translate = true;

Then, use the SharedRegion.setEntryMeta() method in the configuration file to specify the parameters of the entry.

var SHAREDMEM      = 0x0C000000;
var SHAREDMEMSIZE  = 0x00200000;

SharedRegion.setEntryMeta(0,
    { base: SHAREDMEM,
      len: SHAREDMEMSIZE,
      ownerProcId: 0,
      isValid: true,
      cacheEnable: true,
      cacheLineSize: 128,
      createHeap: true,
      name: "internal_shared_mem"
});

If, during static configuration, you don’t know the base address for every processor, you should set the “isValid” field for an entry for which you don’t yet know the base address to “false”. Storing this information will allow it to be completed at runtime.

The following figure shows the configuration of a SharedRegion table for the system in the following figure. This system has seven processors and two shared memory regions. Region 0 (“ext”) is accessible by all processors. Region 1 (“local”) is accessible only by processors 1 to 6.

If the “createHeap” field is set to true, a HeapMemMP instance is created within the SharedRegion.

The latest version of the SharedRegion module configuration documentation is available online.

4.4.6.9.2. Modifying Table Entries Dynamically¶

In the application’s C code, a shared memory region can be modified in the SharedRegion table by calling SharedRegion_setEntry().

Typically, applications configure SharedRegion table entries statically as described in the previous section, and only modify the table entries dynamically in applications where it is possible for shared memory region availability to change dynamically.

The call to SharedRegion_setEntry() must specify all the fields in the SharedRegion_Entry structure. The index specified must be the same across all processors for the same shared memory region. The index also must be smaller than the maxNumEntries property, otherwise an assert will be triggered.

typedef struct SharedRegion_Entry {
  Ptr base;
  SizeT len;
  UInt16 ownerProcId;
  Bool isValid;
  Bool cacheEnable;
  SizeT cacheLineSize;
  Bool createHeap;
  String name;
} SharedRegion_Entry;

You can use SharedRegion_getEntry() to fill the fields in a SharedRegion_Entry structure. Then, you can modify fields in the structure and call SharedRegion_setEntry() to write the modified fields back to the SharedRegion table.

If you want to reuse an index location in the SharedRegion table, you can call SharedRegion_clear() on all processors to erase the existing entry at that index location.

The latest version of the SharedRegion module run-time API documentation is available online.

4.4.6.9.3. Using Memory in a Shared Region¶

Note that the SharedRegion with an index of 0 (zero) is used by IPC_start() to create resource management tables for internal use by the GateMP, NameServer, and Notify modules. Thus SharedRegion “0” must be accessible by all processors.

This example allocates memory from a SharedRegion:

buf = Memory_alloc(SharedRegion_getHeap(0), sizeof(Tester) * COUNT, 128, NULL);

4.4.6.9.4. Getting Information About a Shared Region¶

The shared region pointer (SRPtr) is a 32-bit portable pointer composed of an ID and offset. The most significant bits of a SRPtr are used for the ID. The ID corresponds to the index of the entry in the lookup table. The offset is the offset from the base of the shared memory region. The maximum number of table entries in the lookup table determines the number of bits to be used for the ID. An increase in the id means the range of the offset would decrease. The ID is limited to 16-bits.

Here is sample code for getting the SRPtr and then getting the real address pointer back.

SharedRegion_SRPtr srptr; UInt16 id;

// Get the id of the address if id is not already known.
id = SharedRegion_getId(addr);

// Get the shared region pointer for the address
srptr = SharedRegion_getSRPtr(addr, id);

// Get the address back from the shared region pointer
addr = SharedRegion_getPtr(srptr);

In addition, you can use the SharedRegion_getIdByName() function to pass the name of a SharedRegion and receive the ID number of the region.

You can use SharedRegion_getHeap() to get a handle to the heap associated with a region using the heap ID.

You can retrieve a specific shared region’s cache configuration from the SharedRegion table by using SharedRegion_isCacheEnabled() and SharedRegion_getCacheLineSize().

4.4.7.1.1. Basic FIFO Operation of a List¶

To add a structure to a List, its first field needs to be of type List_Elem. The following example shows a structure that can be added to a List. A List has a “head”, which is the front of the list. List_put() adds elements to the back of the list, and List_get() removes and returns the element at the head of the list. Together, these functions support a FIFO queue.

Run-time example: The following example demonstrates the basic List operations–List_put() and List_get().

/* This structure can be added to a List because the first
 * field is a List_Elem. Declared globally. */
typedef struct Rec {
    List_Elem elem;
    Int data;
} Rec;

...

List_Handle myList;              /* in main() */
Rec r1, r2;
Rec* rp;

r1.data = 100;
r2.data = 200;

/* No parameters are needed to create a List. */
myList = List_create(NULL, NULL);

/* Add r1 and r2 to the back of myList. */
List_put(myList, &(r1.elem));
List_put(myList, &(r2.elem));

/* get the records and print their data */
while ((rp = List_get(myList)) != NULL) {
    System_printf("rec: %d\n", rp->data);
}

The example prints the following:

rec: 100
rec: 200

4.4.7.1.2. Iterating Over a List¶

The List module also provides several APIs for looping over a List.

List_next() with NULL returns the element at the front of the List (without removing it). List_next() with an elem returns the next elem. NULL is returned when the end of the List is reached.

Similarly, List_prev() with NULL returns the tail. List_prev() with an elem returns the previous elem. NULL is returned when the beginning of the List is reached.

Run-time example: The following example demonstrates one way to iterate over a List once from beginning to end. In this example, “myList” is a List_Handle.

List_Elem   *elem = NULL;
Rec* rp;

...

/* To start the search at the beginning of the List */
rp = NULL;

/* Begin protection against modification of the List */
key = Gate_enterSystem();

while ((elem = List_next(myList, elem)) != NULL) {
     System_printf("rec: %d\n", rp->data);
}
/* End protection against modification of the List */
Gate_leaveSystem(key);

4.4.7.1.3. Inserting and Removing List Elements¶

Elements can also be inserted or removed from anywhere in the middle of a List using List_insert() and List_remove(). List_insert() inserts an element in front of the specified element. Use List_putHead() to place an element at the front of the List and List_put() to place an element at the end of the List.

List_remove() removes the specified element from whatever List it is in.

Note that List does not provide any APIs for inserting or removing elements at a given index in the List.

Run-time example: The following example demonstrates List_insert() and List_remove():

/* Insert r2 in front of r1 in the List. */
List_insert(myList, &(r1.elem), &(r2.elem));

/* Remove r1 from the List. */
List_remove(myList, &(r1.elem));

Run-time example: The following example treats the List as a LIFO stack using List_putHead() and List_get():

List_Elem  elem[NUMELEM];
List_Elem *tmpElem;

// push onto the top (i.e. head)
for (i = 0; i < NUMELEM; i++) {
    List_putHead(listHandle, &(elem[i]));
}

// remove the buffers in FIFO order.
while((tmpElem = List_get(listHandle)) != NULL) {
    // process tmpElem
}

4.4.7.1.4. Atomic List Operations¶

Lists are commonly shared across multiple threads in the system, which might lead to concurrent modifications of the List by different threads, which would corrupt the List. List provides several “atomic” APIs that disable interrupts before operating on the List. These APIs are List_get() List_put(), List_putHead(), and List_empty().

An atomic API completes in core functionality without being interrupted. Therefore, atomic APIs are thread-safe. An example is List_put(). Multiple threads can call this API at the same time. The threads do not have to manage the synchronization.

Other APIs–List_prev(), List_next(), List_insert(), and List_remove()–should be protected by the application.

4.4.7.2.1. Introduction¶

Many IPC modules require the ability to uniquely specify and identify processors in a multi-processor environment. The MultiProc module centralizes processor ID management into one module. Most multi-processor IPC applications require that you configure this module using the MultiProc.setConfig() function in the *.cfg script. The setConfig() function tells the MultiProc module:

• The specific processor for which this application is being built.
• The processors in this cluster. A “cluster” is a set of processors within

a system that share some memory and for which notification between those processors is needed.

Most systems contain a single cluster. For systems with multiple clusters, you also need to configure the numProcessors and baseIdOfCluster properties.

Each processor reference by the MultiProc module can be uniquely identified by either its name string or an integer ranging from 0 to MultiProc.maxProcessors - 1.

The following XDCtools configuration statements set up a MultiProc array. At runtime, the “DSP” processor running this configuration gets assigned an ID value of 2. The other processors in the system are “VIDEO” with a processor ID of 0 and “DSS” with a processor ID of 1.

/* DSP will get assigned processor id 2. */
var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
MultiProc.setConfig("DSP", ["VIDEO", "DSS", "DSP"]);

The ID is a software-only setting. It does not correlate to hardware core IDs or any other type of hardware identification. For devices with more than one core, each core must have its own unique processor ID. The ID is also independent of any OS setting. The processor ID is not always known at configuration time. It might need to be determined at initialization time via a GPIO pin, flash setting, or some other method. You can call the MultiProc_setLocalId() API (with the restriction that it must be called before module startup) to set the processor ID. However, other modules that use MultiProc need to know that the static ID will be changed during initialization. Setting the local name to NULL in the MultiProc.setConfig statement in the configuration indicates that the MultiProc_setLocalId() API will be used at runtime. Other modules that use MultiProc should act accordingly by deferring processing until the actual ID is known.

For example, the following fragment of configuration code requires that the MultiProc_setLocalId() API be run during startup to fill in the NULL processor name.

/* Specify startup function */
var Startup = xdc.useModule('xdc.runtime.Startup');
Startup.firstFxns.$add('&setMyId');

/* Specify MultiProc config; current processor unknown */
var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2"]);

Then, the application code could contain the following setMyID() function to be run at startup:

Void setMyId()
{
    UInt16 procId;
    Int    status;

    //
    // Board specific determination of processor id.
    // Example: GPIO_READ reads register of GPIO pin 5
    //
    if (GPIO_READ(5) == 0) {
          procId = 0;
    }
    else {
       procId = 1;
    }

    MultiProc_setLocalId(procId);
}

Your application can query the MultiProc table using various runtime APIs. At runtime, the MultiProc_getId() call returns the MultiProc ID for any processor name. At config-time, the MultiProc.getIdMeta() call returns the same value. For example:

core1ProcId = MultiProc_getId("CORE1");

MultiProc_self() returns the processor ID of the processor running the API. For example:

System_printf("My MultiProc id = %d\n", MultiProc_self());

MultiProc_getBaseIdOfCluster() returns the MultiProc ID of the base processor in the cluster to which this processor belongs. The MultiProc_getName() API returns that processor name if given the MultiProc ID. For example:

core0Name = MultiProc_getName(0);

MultiProc_getNumProcessors() evaluates to the total number of processors.

System_printf("Number of processors in the system = %d\n",
              MultiProc_getNumProcessors() );

MultiProc_getBaseIdOfCluster() returns the MultiProc ID of the base processor in the cluster to which this processor belongs. The MultiProc_getName() API returns that processor name if given the MultiProc ID. For example:

core0Name = MultiProc_getName(0);

MultiProc_getNumProcessors() evaluates to the total number of processors.

System_printf("Number of processors in the system = %d\n",
              MultiProc_getNumProcessors() );

MultiProc_getNumProcsInCluster() returns the number of processors in the cluster to which this processor belongs.

4.4.7.2.2. Configuring Clusters With the MultiProc Module¶

A “cluster” is a set of processors within a system that share some memory and for which notification between those processors is needed. If your system has multiple clusters, you need to configure the MultiProc module’s numProcessors and baseIdOfCluster properties in addition to calling the MultiProc.setConfig() function.

Notifications are not supported between different clusters.

For example, in a system with two ‘C6678 devices that each use eight homogeneous cores, you could configure the first ‘C6678 device as follows:

var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
MultiProc.baseIdOfCluster = 0;
MultiProc.numProcessors = 16;
MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2",
         "CORE3", "CORE4", "CORE5", "CORE6", "CORE7"]);

You could configure the second ‘C6678 device as follows:

var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
MultiProc.baseIdOfCluster = 8;
MultiProc.numProcessors = 16;
MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2",
         "CORE3", "CORE4", "CORE5", "CORE6", "CORE7"]);

Notice that the MultiProc.numProcessors property specifies the total number of processors in the system, while the length of the array passed to setConfig() specifies the number of processors in the cluster. (If you are not using multiple clusters, the numProcessors property is configured automatically.) The MultiProc.baseIdOfCluster property is set to the MultiProc ID number you want to use for the first processor in the array for this cluster. For example, if there are 8 processors in a cluster, the baseIdOfCluster property should be 0 for the first cluster and 8 for the second cluster.

The latest version of the MultiProc module configuration documentation is available in MultiProc page

4.4.7.2.3. Creating Connections with MultiProc¶

The Ipc_start() and Ipc_attach() APIs can only be used to attach and synchronizes with processors in the same cluster.

To create a connection between cores in different clusters, you must manually create a connection using the MessageQ and ti.sdo.ipc.NameServerMessageQ modules. The NameServerMessageQ module supports NameServer requests between different clusters by using MessageQ, which in turns uses the MessageQ transport to send a NameServer request.

You can control the timeout period for the NameServerMessageQ module by configuring its timeoutInMicroSecs parameter, which defaults to 1 second. If a response is not received within the timeout period, the NameServer request returns a failure status. The NameServerRemoteNotify module also has a timeoutInMicroSecs parameter that you can configure; it defaults to wait forever.

Creating a connection between cores in different clusters allows you to call MessageQ_open() even for a core on a different cluster. Note that these calls must occur after the MessageQ heap has been registered, because they allocate memory from the heap.

Once the connection has been created, MessageQ can be used between different processors on different clusters just as it is used between different processors in the same cluster.

The latest version of the MultiProc module run-time API documentation is available in MultiProc run-time API

4.4.7.2.4. Example¶

The following example function creates a NameServerMessageQ and TransportXXX to communicate remotely with a processor in a different cluster. The “remoteProcId” would be specified to be the MultiProc ID of the processor in the system. “TransportXXX” must be a copy-based transport that does not require any shared memory. You would need to create such a transport, because IPC does not provide one.

Void myRemoteCreateFunction(Uint16 remoteProcId)
{
    NameServerMessageQ_Params  nsParams;
    NameServerMessageQ_Handle  nsHandle;
    TransportXXX_Handle        tranHandle;
    TransportXXX_Params        tranParams;
    Error_Block eb;

    Error_init(&eb);

    /*
     *  Note: You must register a MessageQ heap prior to
     *  calling NameServerMessageQ_create().
     */

    /* init nsParams */
    NameServerMessageQ_Params_init(&nsParams);

    /* create driver to remote processor */
    nsHandle = NameServerMessageQ_create(
        remoteProcId, /* MultiProc ID of proc on 2nd cluster */
        &nsParams,
        &eb);
      if (nsHandle == NULL) {
        SYS_abort("NameServerMessageQ_create() failed");
    }

      /* initialize the transport parameters */
    TransportXXX_Params_init(&tranParams);

    tranHandle = TransportXXX_create(
       remoteProcId, /* MultiProc ID of proc on 2nd cluster */
       &tranParams,
       &eb);
    if (tranHandle == NULL) {
        SYS_abort("TransportXXX_create() failed");
    }
}

4.4.7.3.1. Creating NameServer Instances Statically (BIOS-only)¶

To create a NameServer instance statically, you can add statements similar to the following to your XDCtools configuration script:

var NameServer = xdc.useModule('ti.sdo.utils.NameServer');

var nameServerParams = new NameServer.Params;
nameServerParams.maxRuntimeEntries = 10;
nameServerParams.maxNameLen = 32;
var nameServer0 = NameServer.create("nameServer0", nameServerParams);

If you want to specify the heap to be used by the NameServer module and a NameServer instance, use configuration statements similar to the following:

var NameServer = xdc.useModule('ti.sdo.utils.NameServer');
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');

var heapParams = new HeapMem.Params;
heapParams.size = 1024;
var heapMem = HeapMem.create(heapParams);

var nameServerParams = new NameServer.Params;
nameServerParams.tableHeap = heapMem;
var nameServer = NameServer.create("staticNameServer", nameServerParams);

To create a NameServer instance dynamically, initialize a NameServer_Params structure with NameServer_Params_init() and customize the values as needed. The parameters include the following:

• checkExisting. If true, NameServer check to see if a name already exists in the name/value table before adding it.
• maxNameLen. Specify the maximum length, in characters, of the name field in the table.
• maxRuntimeEntries. Specify the maximum number of name/value pairs this table can hold. If you set this parameter to NameServer_ALLOWGROWTH, then NameServer allows dynamic growth of the table.
• maxValueLen. Specify the maximum length, in MAUs, of the value field in the table.
• tableHeap. The heap to allocate the name/value table from when allocating dynamically. If this parameter is NULL, the heap used for object allocation is also used here.

After setting parameters, use NameServer_create() to create an instance. Each NameServer instance manages its own name/value table.

The latest version of the NameServer module configuration documentation is available online.

4.4.7.3.2. Creating and Removing NameServer Instances Dynamically¶

The following C example creates a NameServer instance dynamically. The instance allows a maximum of 10 runtime entries (instead of using ALLOWGROWTH). This example also specifies where to allocate the memory needed for the tables (instead of using the default).

NameServer_Handle NSHandle;
NameServer_Params params;

NameServer_Params_init(&params);
params.tableHeap = HeapStd_Handle_upCast(myHeap);
params.maxRuntimeEntries = 10;
NSHandle = NameServer_create("myTable", &params);
if (NSHandle == NULL) {
    // manage error
}

This example C code adds and removes entries at run-time:

Ptr key;

key = NameServer_addUInt32(NSHandle, "volume", 5);
if (key == NULL) {
    // manage error
}

NameServer_removeEntry(NSHandle, key);
// or
NameServer_remove(NSHandle, "volume");

The latest version of the NameServer module run-time API documentation is available online.

4.4.7.3.3. Searching NameServer Instances¶

The following example searches the NameServer instance pointed to by “handle” on the specified processor for a name-value pair with the name stored in nameToFind. It returns the value of the pair to valueBuf.

/* Search NameServer */
status = NameServer_get(NSHandle, nameToFind, valueBuf, sizeof(UInt32), procId);

Using different parameters for different table instances allows you to meet requirements like the following:

• Size differences. The maxValueLen parameter specifies the maximum length, in MAUs, of the value field in the table. One table could allow long values (for example, > 32 bits), while another table could be used to store integers. This customization enables better memory usage.
• Performance. Multiple NameServer tables can improve the search time when retrieving a name/value pair.
• Relax name uniqueness. Names in a specific table must be unique, but the same name can be used in different tables.

When you call NameServer_delete(), the memory for the name/values pairs is freed. You do not need to call NameServer_remove() on the entries before deleting a NameServer instance.

4.4.7.3.4. Other NameServer APIs¶

In addition to the functions mentioned above, the NameServer module provides the following APIs:

• NameServer_get() Retrieves the value portion of a local name/value pair from the specified processor.
• NameServer_getLocal() Retrieves the value portion of a local name/value pair.
• NameServer_remove() Removes a name/value pair from the table given a name.
• NameServer_removeEntry() Removes an entry from the table given a pointer to an entry.

NameServer maintains the name/values table in local memory, not in shared memory. However the NameServer module can be used in a multiprocessor system. The module communicates with other processors via NameServer Remote drivers, which are implementations of the INameServerRemote interface. The communication to the other processors is dependent on the Remote drivers implementation. When a remote driver is created, it registers with NameServer via the NameServer_registerRemoteDriver() API.

The NameServer module uses the MultiProc module to identify different processors. Which remote processors to query and the order in which they are queried is determined by the procId array passed to the NameServer_get() function.

4.4.10.2.1. SYS/BIOS DSP TransportSrio¶

The following SRIO socket types are supported:

TransportSrio_srioSockType_TYPE_9: In this mode, the SRIO IPC transport will use Type 9 sockets to communicate with other SRIO IPC transport endpoints.

TransportSrio_srioSockType_TYPE_11: In this mode, the SRIO IPC transport will use Type 11 sockets to communicate with other SRIO IPC transport endpoints.

4.4.10.2.2. ARM Linux TransportSrio¶

The following SRIO socket types are supported:

sock_TYPE_9: In this mode, the ARM Linux SRIO IPC transport will use Type 9 sockets to communicate with other SRIO IPC transport endpoints.

sock_TYPE_11: In this mode, the ARM Linux SRIO IPC transport will use Type 11 sockets to communicate with other SRIO IPC transport endpoints.

4.4.10.2.3. SYS/BIOS DSP TransportQmss¶

The following QMSS receive queue types are supported:

TransportQmss_queueRcvType_ACCUMULATOR: In this mode, the QMSS accumulator logic is used as the reception mechanism for the QMSS Transport.

TransportQmss_queueRcvType_QPEND: In this mode, a QMSS QPEND (direct interrupt) queue is used as the reception mechanism for the QMSS Transport.

4.4.10.2.4. ARM Linux TransportQmss¶

A QMSS QPEND queue will always be used as the reception mechanism for the ARM Linux QMSS Transport.

4.4.10.3.1. SYS/BIOS DSP TransportSrio¶

ti/transport/ipc/c66/srio/example/src/device_srio.c

#include <ti/transport/ipc/c66/srio/TransportSrio.h>

4.4.10.3.2. ARM Linux TransportSrio¶

linux/srio/test/[consumer or producer]_device_srio.c

#include <linux/srio/TransportSrio.h>

4.4.10.3.3. SYS/BIOS DSP TransportQmss¶

#include <ti/transport/ipc/c66/qmss/TransportQmss.h>

4.4.10.3.4. ARM Linux TransportQmss¶

#include <linux/qmss/TransportQmss.h>

4.4.10.4.1. SYS/BIOS DSP TransportSrio¶

The SYS/BIOS DSP TransportSrio source code and examples are delivered within the PROCSDK RTOS PDK component. DSP TransportSrio can be rebuilt using the environment setup scripts provided with the PDK package. DSP TransportSrio example applications are created as part of the pdkProjectCreate scripts. They can be imported and built the same as PDK LLD example and test CCS projects.

4.4.10.4.2. ARM Linux TransportSrio Source Delivery and Recompilation¶

The ARM Linux TransportSrio source code can be downloaded and built two ways. The transport source code is delivered and built as part of Yocto/bitbake. The source code can also be downloaded and built directly from the GIT repository.

4.4.10.4.3. SYS/BIOS DSP TransportQmss Source Delivery and Recompilation¶

The SYS/BIOS DSP TransportQmss source code and examples are delivered within the PROCSDK RTOS PDK component. DSP TransportQmss can be rebuilt using the environment setup scripts provided with the PDK package. DSP TransportQmss example applications are created as part of the pdkProjectCreate scripts. They can be imported and built the same as PDK LLD example and test CCS projects.

4.4.10.4.4. ARM Linux TransportQmss Source Delivery and Recompilation¶

The ARM Linux TransportQmss source code can be downloaded and built two ways. The transport source code is delivered and built as part of Yocto/bitbake. The source code can also be downloaded and built directly from the GIT repository.

4.4.10.5.1. SYS/BIOS DSP TransportSrio¶

4.4.10.5.2. ARM Linux TransportSrio¶

4.4.10.5.3. SYS/BIOS DSP TransportQmss¶

4.4.10.5.4. ARM Linux TransportQmss¶

4.4.11.1.1. Build¶

The example can be built by running the top level make from the processor_sdk_rtos_<platform>_<version> directory.

cd processor_sdk_rtos_<platform>_<version>
make sdk_ipc_examples_all

Host A53: ./demos/ipc-examples/ping_benchmark_example/hosta53/bin/am65xx_evm/release/server_host.xa53fg
R5F-0:    ./demos/ipc-examples/ping_benchmark_example/r5f-0/bin/am65xx_evm/release/server_r5f-0.xer5f
R5F-1:    ./demos/ipc-examples/ping_benchmark_example/r5f-1/bin/am65xx_evm/release/server_r5f-1.xer5f

Host A53: ./demos/ipc-examples/ping_benchmark_example/hosta53/bin/am65xx_evm/app_r5f0_only/release/server_host.xa53fg
R5F-0:    ./demos/ipc-examples/ping_benchmark_example/r5f-0/bin/am65xx_evm/app_r5f0_only/release/server_r5f-0.xer5f
R5F-1:    ./demos/ipc-examples/ping_benchmark_example/r5f-1/bin/am65xx_evm/app_r5f0_only/release/server_r5f-1.xer5f

make sdk_ipc_examples_app
make sdk_ipc_examples_app_r5f0_only

demos/ipc-examples/ping_benchmark_example/output.appimage
demos/ipc-examples/ping_benchmark_example/am65xx_evm/app_r5f0_only/output.appimage

4.4.11.1.2. Run¶

Pre-requisites: Bootable SD card loaded with SBL.

Overhead:34

Payload Size: 176

Proc id 0, Delta count: 3829025

Proc id 0 to Proc Id 0: Average Roundtrip time is: 19 us

Proc id 1, Delta count: 8920087

Proc id 0 to Proc Id 1: Average Roundtrip time is: 44 us

Proc id 2, Delta count: 7091251

Proc id 0 to Proc Id 2: Average Roundtrip time is: 35 us

AppHost_run: Test Passed

MainHost_appTskFxn: Test Passed

Overhead:144

Payload Size: 176

Proc id 0, Delta count: 8460883

Proc id 1 to Proc Id 0: Average Roundtrip time is: 42 us

Proc id 1, Delta count: 1046906

Proc id 1 to Proc Id 1: Average Roundtrip time is: 5 us

Proc id 2, Delta count: 6297313

Proc id 1 to Proc Id 2: Average Roundtrip time is: 31 us

AppR5f_0_run: Test Passed

4.4.11.2.1. Build¶

This section outlines the build process for the MessageQBench application.

$buildhost make -j messageQApp \
                     messageQBench \
                     messageQMulti \
                     nameServerApp \
                     ping_rpmsg \
                     lad_dra7xx \
                     libmmrpc

4.4.11.2.2. Run¶

This section illustrates the steps to run the MessageQBench application.

target# /usr/bin/MessageQBench

Usage: ./bin/MessageQBench [<numLoops>] [<payloadSize>] [<ProcId>]
       Defaults: numLoops: 1000; payloadSize: 8, ProcId: 1

target#  tests/MessageQBench 1000 8 <slave core procId>

Syntax:
  MessageQBench [<numLoops>] [<payloadSize>] [<procId>]

4.4.11.3.1. IPC Average Round Trip Time¶

The average round trip time is measured using MessageQBench which calculates the time for sending 1000 messages from the main processor to slave core and divided by the number of messages sent (1000).

Average Round Trip Time (ARTT) for K2H/E/G and OMAP-L138 EVMs

Table: IPC Average Round Trip Time (ARTT)

4.4.11.3.2. Throughput¶

Throughput benchmark uses a max transmit window of 130 outstanding messages to get the maximum throughput. Beyond the max transit window of 130, there won’t be enough resource to allocate additional messages before the resource is returned by the outstanding messages. In this case, the benchmark application will fail to run. Different payload sizes from 8 bytes to max of 448 bytes are measured for each direction, and the numbers apply to either direction. The throughput are measured with ARM/DSP running at 1 GHz.

Throughput for K2H/E/G and OMAP-L138 EVMs

Table: IPC Throughput

4.4.11.3.3. IPC Throughput CPU Utilization¶

The CPU utilization is measured using max payload size of 448 bytes with transmit window of 130 messages.

Table: IPC Throughput CPU Utilization

4.4.12.2.1. BIOS¶

For BIOS-to-BIOS communication, the same features available in IPC 1.x are available in IPC 3.x.

4.4.12.2.2. Linux¶

On Linux, IPC 3.x is built upon services available (and evolving!) in the mainline Linux kernel (3.4+). These core services include remoteproc and rpmsg.

Above those Linux services, a few key services from the IPC API (e.g. MessageQ) are provided in user mode.

4.4.12.2.3. QNX¶

On QNX, IPC 3.x provides feature parity to Linux. The QNX OS doesn’t inherently provide primitives like Linux’s ‘remoteproc’ and ‘rpmsg’, so IPC 3.x also includes a loader and rpmsg-compatible communication infrastructure. This rpmsg-compatible MessageQ implementation enables the same BIOS-side image to communicate with either Linux or QNX on the HLOS.

4.4.12.4.1. Introduction¶

The IPC 3.x product introduced support for loading slave images which include a Linux-defined resource table. In IPC 3.00.01, IPC added the ability for users to override the default resource table with their own. This article describes the mechanics involved to do that.

4.4.12.4.2. Config¶

To indicate you want to provide your own resource table, you need to set the Resource.customTable config parameter true.

/* Override the default resource table with my own */
var Resource = xdc.useModule('ti.ipc.remoteproc.Resource');
Resource.customTable = true;

When Resource.customtable is set to true, IPC will no longer generate a default table, and the user will be able to supply their own table using a specially-named C struct, ti_ipc_remoteproc_ResourceTable.

4.4.12.4.3. C Code¶

The user-supplied resource table is a C structure named ti_ipc_remoteproc_ResourceTable that needs to be linked into the slave executable. The platform-specific default resource tables are provided in IPC’s packages/ti/ip/remoteproc/rsc_table_*.h, and are the recommended place to start from.

After finding the default resource table for your platform, you can copy the entirety of it into your own C file, compile it, and link it into your executable.

For reference, here is an Vayu compatible resource table derived from packages/ti/ipc/remoteproc/rsc_table_vayu_ipu.h( Disclaimer: This is a reference design only, and it is subject to enhancements, improvements and other changes without notifications).

#include "rsc_types.h"

/* IPU Memory Map */
#define L4_DRA7XX_BASE          0x4A000000

/* L4_CFG & L4_WKUP */
#define L4_PERIPHERAL_L4CFG     (L4_DRA7XX_BASE)
#define IPU_PERIPHERAL_L4CFG    0x6A000000

#define L4_PERIPHERAL_L4PER1    0x48000000
#define IPU_PERIPHERAL_L4PER1   0x68000000

#define L4_PERIPHERAL_L4PER2    0x48400000
#define IPU_PERIPHERAL_L4PER2   0x68400000

#define L4_PERIPHERAL_L4PER3    0x48800000
#define IPU_PERIPHERAL_L4PER3   0x68800000

#define L4_PERIPHERAL_L4EMU     0x54000000
#define IPU_PERIPHERAL_L4EMU    0x74000000

#define L3_PERIPHERAL_PRUSS     0x4B200000
#define IPU_PERIPHERAL_PRUSS    0x6B200000

#define L3_PERIPHERAL_DMM       0x4E000000
#define IPU_PERIPHERAL_DMM      0x6E000000

#define L3_IVAHD_CONFIG         0x5A000000
#define IPU_IVAHD_CONFIG        0x7A000000

#define L3_IVAHD_SL2            0x5B000000
#define IPU_IVAHD_SL2           0x7B000000

#define L3_TILER_MODE_0_1       0x60000000
#define IPU_TILER_MODE_0_1      0xA0000000

#define L3_TILER_MODE_2         0x70000000
#define IPU_TILER_MODE_2        0xB0000000

#define L3_TILER_MODE_3         0x78000000
#define IPU_TILER_MODE_3        0xB8000000

#define L3_OCMC_RAM       0x40300000
#define IPU_OCMC_RAM      0x60300000

#define L3_EMIF_SDRAM     0xA0000000
#define IPU_EMIF_SDRAM        0x10000000

#define IPU_MEM_TEXT            0x0
#define IPU_MEM_DATA            0x80000000

#define IPU_MEM_IOBUFS          0x90000000

#define IPU_MEM_IPC_DATA        0x9F000000
#define IPU_MEM_IPC_VRING       0x60000000
#define IPU_MEM_RPMSG_VRING0    0x60000000
#define IPU_MEM_RPMSG_VRING1    0x60004000
#define IPU_MEM_VRING_BUFS0     0x60040000
#define IPU_MEM_VRING_BUFS1     0x60080000

#define IPU_MEM_IPC_VRING_SIZE  SZ_1M
#define IPU_MEM_IPC_DATA_SIZE   SZ_1M

#if defined(VAYU_IPU_1)
#define IPU_MEM_TEXT_SIZE       (SZ_1M)
#elif defined(VAYU_IPU_2)
#define IPU_MEM_TEXT_SIZE       (SZ_1M * 6)
#endif

#if defined(VAYU_IPU_1)
#define IPU_MEM_DATA_SIZE       (SZ_1M * 5)
#elif defined(VAYU_IPU_2)
#define IPU_MEM_DATA_SIZE       (SZ_1M * 48)
#endif

#define IPU_MEM_IOBUFS_SIZE     (SZ_1M * 90)

/*
 * Assign fixed RAM addresses to facilitate a fixed MMU table.
 * PHYS_MEM_IPC_VRING & PHYS_MEM_IPC_DATA MUST be together.
 */
/* See CMA BASE addresses in Linux side: arch/arm/mach-omap2/remoteproc.c */
#if defined(VAYU_IPU_1)
#define PHYS_MEM_IPC_VRING      0x9D000000
#elif defined (VAYU_IPU_2)
#define PHYS_MEM_IPC_VRING      0x95800000
#endif

#define PHYS_MEM_IOBUFS         0xBA300000

/*
 * Sizes of the virtqueues (expressed in number of buffers supported,
 * and must be power of 2)
 */
#define IPU_RPMSG_VQ0_SIZE      256
#define IPU_RPMSG_VQ1_SIZE      256

/* flip up bits whose indices represent features we support */
#define RPMSG_IPU_C0_FEATURES   1

struct my_resource_table {
    struct resource_table base;

    UInt32 offset[21];  /* Should match 'num' in actual definition */

    /* rpmsg vdev entry */
    struct fw_rsc_vdev rpmsg_vdev;
    struct fw_rsc_vdev_vring rpmsg_vring0;
    struct fw_rsc_vdev_vring rpmsg_vring1;

    /* text carveout entry */
    struct fw_rsc_carveout text_cout;

    /* data carveout entry */
    struct fw_rsc_carveout data_cout;

    /* ipcdata carveout entry */
    struct fw_rsc_carveout ipcdata_cout;

    /* trace entry */
    struct fw_rsc_trace trace;

    /* devmem entry */
    struct fw_rsc_devmem devmem0;

    /* devmem entry */
    struct fw_rsc_devmem devmem1;

    /* devmem entry */
    struct fw_rsc_devmem devmem2;

    /* devmem entry */
    struct fw_rsc_devmem devmem3;

    /* devmem entry */
    struct fw_rsc_devmem devmem4;

    /* devmem entry */
    struct fw_rsc_devmem devmem5;

    /* devmem entry */
    struct fw_rsc_devmem devmem6;

    /* devmem entry */
    struct fw_rsc_devmem devmem7;

    /* devmem entry */
    struct fw_rsc_devmem devmem8;

    /* devmem entry */
    struct fw_rsc_devmem devmem9;

    /* devmem entry */
    struct fw_rsc_devmem devmem10;

    /* devmem entry */
    struct fw_rsc_devmem devmem11;

    /* devmem entry */
    struct fw_rsc_devmem devmem12;

    /* devmem entry */
    struct fw_rsc_devmem devmem13;

    /* devmem entry */
    struct fw_rsc_devmem devmem14;

    /* devmem entry */
    struct fw_rsc_devmem devmem15;
};
extern char ti_trace_SysMin_Module_State_0_outbuf__A;
#define TRACEBUFADDR (UInt32)&ti_trace_SysMin_Module_State_0_outbuf__A

#pragma DATA_SECTION(ti_ipc_remoteproc_ResourceTable, ".resource_table")
#pragma DATA_ALIGN(ti_ipc_remoteproc_ResourceTable, 4096)

struct my_resource_table ti_ipc_remoteproc_ResourceTable = {
    1,      /* we're the first version that implements this */
    21,     /* number of entries in the table */
    0, 0,   /* reserved, must be zero */
    /* offsets to entries */
    {
        offsetof(struct my_resource_table, rpmsg_vdev),
        offsetof(struct my_resource_table, text_cout),
        offsetof(struct my_resource_table, data_cout),
        offsetof(struct my_resource_table, ipcdata_cout),
        offsetof(struct my_resource_table, trace),
        offsetof(struct my_resource_table, devmem0),
        offsetof(struct my_resource_table, devmem1),
        offsetof(struct my_resource_table, devmem2),
        offsetof(struct my_resource_table, devmem3),
        offsetof(struct my_resource_table, devmem4),
        offsetof(struct my_resource_table, devmem5),
        offsetof(struct my_resource_table, devmem6),
        offsetof(struct my_resource_table, devmem7),
        offsetof(struct my_resource_table, devmem8),
        offsetof(struct my_resource_table, devmem9),
        offsetof(struct my_resource_table, devmem10),
        offsetof(struct my_resource_table, devmem11),
        offsetof(struct my_resource_table, devmem12),
        offsetof(struct my_resource_table, devmem13),
        offsetof(struct my_resource_table, devmem14),
        offsetof(struct my_resource_table, devmem15),
    },

    /* rpmsg vdev entry */
    {
        TYPE_VDEV, VIRTIO_ID_RPMSG, 0,
        RPMSG_IPU_C0_FEATURES, 0, 0, 0, 2, { 0, 0 },
        /* no config data */
    },
    /* the two vrings */
    { IPU_MEM_RPMSG_VRING0, 4096, IPU_RPMSG_VQ0_SIZE, 1, 0 },
    { IPU_MEM_RPMSG_VRING1, 4096, IPU_RPMSG_VQ1_SIZE, 2, 0 },

    {
        TYPE_CARVEOUT,
        IPU_MEM_TEXT, 0,
        IPU_MEM_TEXT_SIZE, 0, 0, "IPU_MEM_TEXT",
    },

    {
        TYPE_CARVEOUT,
        IPU_MEM_DATA, 0,
        IPU_MEM_DATA_SIZE, 0, 0, "IPU_MEM_DATA",
    },

    {
        TYPE_CARVEOUT,
        IPU_MEM_IPC_DATA, 0,
        IPU_MEM_IPC_DATA_SIZE, 0, 0, "IPU_MEM_IPC_DATA",
    },

    {
        TYPE_TRACE, TRACEBUFADDR, 0x8000, 0, "trace:sysm3",
    },

    {
        TYPE_DEVMEM,
        IPU_MEM_IPC_VRING, PHYS_MEM_IPC_VRING,
        IPU_MEM_IPC_VRING_SIZE, 0, 0, "IPU_MEM_IPC_VRING",
    },

    {
        TYPE_DEVMEM,
        IPU_MEM_IOBUFS, PHYS_MEM_IOBUFS,
        IPU_MEM_IOBUFS_SIZE, 0, 0, "IPU_MEM_IOBUFS",
    },

    {
        TYPE_DEVMEM,
        IPU_TILER_MODE_0_1, L3_TILER_MODE_0_1,
        SZ_256M, 0, 0, "IPU_TILER_MODE_0_1",
    },

    {
        TYPE_DEVMEM,
        IPU_TILER_MODE_2, L3_TILER_MODE_2,
        SZ_128M, 0, 0, "IPU_TILER_MODE_2",
    },

    {
        TYPE_DEVMEM,
        IPU_TILER_MODE_3, L3_TILER_MODE_3,
        SZ_128M, 0, 0, "IPU_TILER_MODE_3",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_L4CFG, L4_PERIPHERAL_L4CFG,
        SZ_16M, 0, 0, "IPU_PERIPHERAL_L4CFG",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_L4PER1, L4_PERIPHERAL_L4PER1,
        SZ_2M, 0, 0, "IPU_PERIPHERAL_L4PER1",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_L4PER2, L4_PERIPHERAL_L4PER2,
        SZ_4M, 0, 0, "IPU_PERIPHERAL_L4PER2",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_L4PER3, L4_PERIPHERAL_L4PER3,
        SZ_8M, 0, 0, "IPU_PERIPHERAL_L4PER3",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_L4EMU, L4_PERIPHERAL_L4EMU,
        SZ_16M, 0, 0, "IPU_PERIPHERAL_L4EMU",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_PRUSS, L3_PERIPHERAL_PRUSS,
        SZ_1M, 0, 0, "IPU_PERIPHERAL_PRUSS",
    },

    {
        TYPE_DEVMEM,
        IPU_IVAHD_CONFIG, L3_IVAHD_CONFIG,
        SZ_16M, 0, 0, "IPU_IVAHD_CONFIG",
    },

    {
        TYPE_DEVMEM,
        IPU_IVAHD_SL2, L3_IVAHD_SL2,
        SZ_16M, 0, 0, "IPU_IVAHD_SL2",
    },

    {
        TYPE_DEVMEM,
        IPU_PERIPHERAL_DMM, L3_PERIPHERAL_DMM,
        SZ_1M, 0, 0, "IPU_PERIPHERAL_DMM",
    },

    {
        TYPE_DEVMEM,
        IPU_OCMC_RAM, L3_OCMC_RAM,
        SZ_4M, 0, 0, "IPU_OCMC_RAM",
    },

    {
        TYPE_DEVMEM,
        IPU_EMIF_SDRAM, L3_EMIF_SDRAM,
        SZ_256M, 0, 0, "IPU_EMIF_SDRAM",
    },
};

You can find 3 new TYPE_DEVMEM entries added in above resource table.

• L3_PERIPHERAL_PRUSS
• IPU_OCMC_RAM
• IPU_EMIF_SDRAM

All ELF section placements (as well as the VRINGS, which aren’t in an ELF section) are placed in memory allocated from the remoteproc CMA area and are mapped to the virtual address as specified in the TYPE_CARVEOUT entries.

The virtual addresses #defined are:

#define IPU_MEM_TEXT            0x0
#define IPU_MEM_DATA            0x80000000

#define IPU_MEM_IOBUFS          0x90000000

#define IPU_MEM_IPC_DATA        0x9F000000
#define IPU_MEM_IPC_VRING       0x60000000

The followings are fixed physical address to facilitate a fixed MMU table.

#if defined(VAYU_IPU_1)
#define PHYS_MEM_IPC_VRING      0x9D000000
#elif defined (VAYU_IPU_2)
#define PHYS_MEM_IPC_VRING      0x95800000
#endif

These PHYS_MEM values match exactly the physical address specified in the remoteproc CMA area in Linux DTS file:

ipu2_cma_pool: ipu2_cma@95800000 {
        compatible = "shared-dma-pool";
        reg = <0x95800000 0x3800000>;
        reusable;
        status = "okay";
};

ipu1_cma_pool: ipu1_cma@9d000000 {
        compatible = "shared-dma-pool";
        reg = <0x9d000000 0x2000000>;
        reusable;
        status = "okay";
};

The 1st entry in the resource table is:

/* rpmsg vdev entry */
{
    TYPE_VDEV, VIRTIO_ID_RPMSG, 0,
    RPMSG_IPU_C0_FEATURES, 0, 0, 0, 2, { 0, 0 },
    /* no config data */
},
/* the two vrings */
{ IPU_MEM_RPMSG_VRING0, 4096, IPU_RPMSG_VQ0_SIZE, 1, 0 },
{ IPU_MEM_RPMSG_VRING1, 4096, IPU_RPMSG_VQ1_SIZE, 2, 0 },

This tells remoteproc to allocate the vrings and vring buffers, and the remoteproc CMA area is used for this.

The 2nd-4th entries are:

{
    TYPE_CARVEOUT,
    IPU_MEM_TEXT, 0,
    IPU_MEM_TEXT_SIZE, 0, 0, "IPU_MEM_TEXT",
},
{
    TYPE_CARVEOUT,
    IPU_MEM_DATA, 0,
    IPU_MEM_DATA_SIZE, 0, 0, "IPU_MEM_DATA",
},
{
    TYPE_CARVEOUT,
    IPU_MEM_IPC_DATA, 0,
    IPU_MEM_IPC_DATA_SIZE, 0, 0, "IPU_MEM_IPC_DATA",
},

These carveouts tell remoteproc to allocate memory from its CMA area and map the allocated physical address to the virtual address specified in the carveout (the 1st field after TYPE_CARVEOUT), in the IPU’s MMU (“iommu” in Linux kernel parlance). These are for the ELF sections that are placed (mapped) in those virtual address.

The TYPE_TRACE entry tells remoteproc where the remote executable’s trace buffer is, using its C symbol.

The TYPE_DEVMEM entries are virtual <-> physical mappings. remoteproc just creates an IPU MMU mapping for the entry. The 1st TYPE_DEVMEM entry corresponds to the vrings and creates the IPU MMU mapping needed to access them from the IPU core:

{
    TYPE_DEVMEM,
    IPU_MEM_IPC_VRING, PHYS_MEM_IPC_VRING,
    IPU_MEM_IPC_VRING_SIZE, 0, 0, "IPU_MEM_IPC_VRING",
},

4.4.12.4.4. New TYPE_DEVMEM entry¶

To add a new TYPE_DEVMEM entry, for example, to access PRU-ICSS from IPU

• 1. specify the physical address of PRU-ICSS and its virutal address.

#define L3_PERIPHERAL_PRUSS     0x4B200000
#define IPU_PERIPHERAL_PRUSS    0x6B200000

• 2. increase size of offset[X] array in struct my_resource_table.
• 3. add new struct fw_rsc_devmem devmemY entry in struct my_resource_table.
• 4. increase number of entries in ti_ipc_remoteproc_ResourceTable.
• 5. add a offsetof(struct my_resource_table, devmemY) in ti_ipc_remoteproc_ResourceTable.
• 6. add actual entry in ti_ipc_remoteproc_ResourceTable.

{
    TYPE_DEVMEM,
    IPU_PERIPHERAL_PRUSS, L3_PERIPHERAL_PRUSS,
    SZ_1M, 0, 0, "IPU_PERIPHERAL_PRUSS",
},

Note, when MMU is enabled, even though it is a one-to-one mapping, you need to have an entry mapped in the MMU for that, e.g. to access PRU-ICSS from DSP, you must add the following entry in rsc_table_vayu_dsp.h

#define L3_PRU_ICSS             0x4B200000
#define DSP_PRU_ICSS            0x4B200000

The MMU pagetable can be dumped through debugfs - “cat /sys/kernel/debug/omap_iommu/<iommu_name>/pagetable”

4.4.12.5.1. Overview¶

The main aim of this page is to capture details about the different resources used in the IPC drivers.

4.4.12.5.2. Interrupt map usage¶

4.4.14.3.1. BIOS-side Build¶

http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0553a/CHDBIJJE.html

http://git.ti.com/cgit/cgit.cgi/ipc/ipcdev.git/tree/packages/ti/sdo/ipc/family/vayu/InterruptIpu.xs

4.4.14.3.2. Linux Build¶

For details on the Linux build process see the IPC Install Guide for Linux.

# make clean
#
# make

# make distclean
#
# make -f ipc-linux.mak
# make

4.4.14.3.3. QNX Build¶

For details on the QNX build process see the IPC Install Guide for QNX.

startup-dra74x-vayu-evm -r0xBA300000,0x5A00000 -v -n852,668 -W -G

#define SH_MEM_BLOCK1_START 0xBA300000
#define SH_MEM_BLOCK1_SIZE  0x5A00000

4.4.14.3.4. Runtime Troubleshooting¶

target# echo "disabled" > /debug/remoteproc/remoteproc0/recovery

4.4.14.5.1. LAD reports NameServer_setup: connect failed: 22, Invalid argument¶

Internally, LAD tries to connect to sockets created by the rpmsg_proto kernel driver. This connection can fail for several reasons, so this is a common “general” error code. Some examples that generate this error condition are below.

• Failure to load the slave image. If the a slave executable fails to load, the sockets to communicate with it are not created. Make sure the slaves you need to communicate with are already loaded.
• Failure to provide the correct KERNEL_INSTALL_DIR when building the user-side IPC libraries. Some customers reported this error when using Linux 3.9+ kernels (where the AF_MAX value in socket.h has increased). This created a mismatch in what AF_RPMSG was set to in user libs and the kernel, and the connect call failed. The solution was to require users set KERNEL_INSTALL_DIR when building the user-space libraries so IPC can interrogate the kernel version and set AF_RPMSG appropriately.
• Failure to configure the slave image correctly. Internally, the slave-side MessageQ transport (TransportRpmsg) broadcasts its availability to the Linux host. If this broadcast doesn’t occur (e.g., b/c the slave wasn’t configured with TransportRpmsg), the socket connection will fail with error 22.
• General slave-to-host interrupt failure. Some devices (e.g. DRA7XX) have interrupt crossbars that must be configured correctly as part of system boot (e.g. uboot). If these crossbars aren’t initialized correctly, the slave-side broadcast that TransportRpmsg is available won’t be received, the underlying socket connection won’t be available, and the first sign of failure will be LAD trying to connect to the socket.

4.4.14.5.2. LAD reports LAD_connect() failed: 4¶

This is a LAD_IOFAILURE = 4. The HOST OS-side application was unable to communicate with LAD due to an OS_level I/O failure.

This is typically caused by LAD directory permissions.

• In Linux /tmp/LAD
• In Android /data/lad/LAD

The application was attempting to create or read from LAD’s response FIFO but was unable to by the application.

LAD must be started as root(su). IPC user applications communicating with LAD, can be executed in user mode but need to ensure LAD is stared with the correct permission.

• % lad_dra7xx -l log.txt -p 777

You can also run both LAD and user application as root(su), thus not requiring permission to be properly set when starting LAD.

4.4.14.5.3. LAD reports _GateMP_TI_dGate not found¶

When the -g option is thrown, the LAD log may show an error about not finding the symbol _GateMP_TI_dGate:

[22.583839] NameServer_getRemote: value for GateMP:_GateMP_TI_dGate not found.
[22.583852] GateMP_attach: failed to open default gate on procId 4
[22.583862]     status = -5
[22.583871] DONE

This is because LAD is looking for the default GateMP instance, and did not find it. On the DRA7xx, verify

1. SharedRegion 0 is defined on DSP1. GateMP implementation on the host requires use of SharedRegion
2. DSP1 is the owner of SharedRegion 0
3. Ipc_start() is called on DSP1. This ensures the default GateMP instance is created.

4.4.14.6.1. BIOS-side VirtQueue assertions¶

The slave loads ok, but communication fails, and in the slave trace output you find the following assert (line number and timestamp may vary):

[      0.000] [t=0x00d090ce] ti.ipc.family.vayu.VirtQueue: ERROR: "VirtQueue.c", line 296:
[      0.000] ti.ipc.family.vayu.VirtQueue: "VirtQueue.c", line 296:
[      0.000] xdc.runtime.Error.raise: terminating execution

This error often indicates a mismatch in VRING addresses between the HLOS side and the slave. Often this is because a custom resource table was provided and the VRING addresses specified don’t match the HLOS-side addresses.

4.4.14.6.2. QNX IPC driver takes a long time to load the slave executable(s) when ‘-g’ is thrown¶

The ‘-g’ option to the IPC driver is used to enable optional support for GateMP on the host processor. During the setup of GateMP module, it polls the slave processors for the default gate instance, which is created by the owner of SharedRegion 0. If none of the cores loaded has created the default gate, the driver will continue polling and eventually timeout after 2 seconds, which means the loading procedure may be delayed by 2 seconds as a consequence. To better suit a given application, one can adjust the polling interval and the timeout duration in the file <IPC_INSTALL_DIR>/qnx/src/ipc3x_dev/ti/syslink/ipc/hlos/knl/GateMP_daemon.c (this code excerpt may look slightly different depending on the version of IPC you are looking at, but the idea is the same):

// Timeout duration is SETUP_TIMEOUT * polling interval
#define SETUP_TIMEOUT         2

Int GateMP_setup(Int32 * sr0ProcId)
{
...
   UInt              timeout = SETUP_TIMEOUT;
...
   if (status == GateMP_S_SUCCESS) {
       /* The default gate creator is the owner of SR0 */
       while (((status = GateMP_openDefaultGate(&GateMP_module->defaultGate,
           &procId)) == GateMP_E_NOTFOUND) && (timeout > 0)) {
           sleep(1);  // polling interval
           timeout--;
       }
...
}

In the case where the owner of SharedRegion 0 is not being loaded by the IPC driver, reducing the timeout duration (SETUP_TIMEOUT) may be useful to reduce the delay that results when the driver cannot find the default gate.

In the case where the owner of SharedRegion 0 is indeed loaded by the IPC driver, using usleep() instead of sleep() to reduce the polling interval can be beneficial in cases where the initial poll happens before the slave core (owner of SR0) has even got to the point in its initialization to create the default gate. A faster polling rate would ensure that a second or a third poll is performed more quickly thereby giving a chance for the driver to move on. On the other hand, reducing the polling interval too much may cause the driver to swamp the slave cores with gate lookup requests, counterproductively slowing down the loading process. As a rule of thumb, it is recommended to keep the polling interval above 1 ms in modern platforms at the time of writing.

4.4.14.7.1. Linux¶

The runtime suspend feature can be enabled or disabled by writing ‘auto’ or ‘on’ to the device’s ‘control’ power field. The default is enabled. First, find the slave you want to disable (e.g. cat /debug/remoteproc/remoteproc0/name) and then echo “on” to the device’s “control” power field.

For example, if “remoteproc0” is the core you want to disable:

target# echo "on" > /sys/bus/platform/devices/58820000.ipu/power/control

4.4.14.7.2. SYS/BIOS¶

Alternatively, the slave can choose to deny the runtime suspend request, preventing suspend. To prevent the slave from suspending, add the IpcPower_hibernateLock() call to the slave software. When you wish to allow suspend again, call IpcPower_hibernateUnlock(). As long as the lock is held, the slave will deny all suspend requests from the HLOS.

IpcPower_hibernateLock();
...
// Perform tasks
...
IpcPower_hibernateUnlock();

In this case, it is not necessary to also disable auto-suspend from the HLOS.

4.4.14.7.3. QNX¶

Runtime auto-suspend is not supported in QNX.

4.4.14.8.1. Overview¶

This wiki article is a collection of frequently asked questions (FAQ) on IPC on Keystone family of devices , along with some useful collateral and software reference links.

4.4.14.8.2. Guide on building and running the IPC examples of Processor SDK¶

4.4.14.8.3. Keystone IPC Frequently Asked Questions (FAQ)¶

Q: Where do I look for the list of IPC API reference document?

Ans:

Please visit : http://downloads.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/latest/docs/doxygen/html/index.html

The IPC product contains the following APIs:

•GateMP (BIOS, Linux, QNX)
•HeapBufMP (BIOS)
•HeapMemMP (BIOS)
•HeapMultiBufMP (BIOS)
•Ipc (BIOS, Linux, QNX)
•ListMP (BIOS)
•MessageQ (BIOS, Linux, QNX)
•MultiProc (BIOS, Linux, QNX)
•NameServer (BIOS, Linux, QNX)
•Notify (BIOS)
•SharedRegion (BIOS)
•IpcPower (BIOS)

Some environments also provide a “Multimedia RPC” interface. Currently this is limited to OMAP5 and DRA7XX devices running an HLOS.

•MmRpc (Linux, QNX)
•MmServiceMgr (BIOS)

Q: How to re-build the IPC package and its libraries?

Ans:

Actually, the user guide which comes along with the IPC package ( under docs folder) is sufficient to build the IPC package. However, we have extracted below steps from user guide. For building IPC package, you can use either Cygwin/Command-line utility in windows machine or Linux machine. This cannot be built through CCS.

PLATFORM = TCI6638
DESTDIR = /opt/ti/ipc_3_xx_xx_xx/ipc_3_xx_xx_xx_lib

XDC_INSTALL_DIR = /opt/ti/xdctools_3_xx_xx_xx
BIOS_INSTALL_DIR = /opt/ti/bios_6_xx_xx_xx
ti.targets.elf.C66 = /opt/ti/ccsv5/tools/compiler/C6000_7.4.5

Q: Is there any simple example to demonstrate IPC methods like message Q or notify for Keystone-II ?

Ans:

~/ti/ipc_3_3x_xx_xx/examples$ ls
C6472_bios_elf C6A8149_bios_elf DRA7XX_android_elf DRA7XX_linux_elf makefile TCI6638_linux_elf
TI814X_bios_elf C6678_bios_elf dosrc.bat DRA7XX_bios_elf DRA7XX_qnx_elf OMAPL138_linux_elf TDA3XX_bios_elf

Please refer the readme.txt to run and build the example according to the target used. For K2, use the cluster ID as 0 instead of 18.

1. perl patchExec.pl 0 compute_dspN.xe66 compute_dspN_patched.xe66
2. lad_tci6638 -r 8 -n 9 -b 0 -l log.txt

Q: For Keystone II, is there any CCS based examples to demonstrate a simple communication between ARM-DSP?

Ans:

No. We have only Image Processing Demo.

In MCSDK 3.x, the ARM core only runs Linux kernel and User Space applications. There isn’t any Linux application example using CCS and if any, it will be using Linux commands.

Q: In IPC packages, there are lot of test example(sample.c) code given in the path: “~ipc_3_3x_xx_xxpackagestiipctests”. But there is only command line option to build the whole IPC package. No option available to build the test examples individually. This is time consuming to build the whole IPC package. Customers were asking for CCS based environment to build and test as individual example for both DSP and ARM side.

Ans:

The IPC package has been developed to work on multiple platforms like Linux, Android, QNX and TI-RTOS(SYS/BIOS) so the command line build is selected which is common across all these platforms and we do not have CCS based projects for these examples.

Q: For keystone-II devices, where do I find the source code of the image processing demo and how to I re-build them? Using ARM core as a master, DSP cores as slaves.

Ans:

Tested version : “mcsdk_bios_3_00_03_15”. The Image processing demo was tested multiple times with this version and it works fine.

The image processing demo source code can be found in below path.

PATH: C:timcsdk_bios_3_0x_0x_0xdemosimage_processingipc (master, slave and common directories)

Building Slave Code: The project can be imported into CCS and can be rebuilt.

For K2E: “~mcsdk_bios_3_0x_0x_0xdemosimage_processingipcevm66ak2eslave”

For K2K: “~mcsdk_bios_3_0x_0x_0xdemosimage_processingipcevmtci6638k2kslave”

For K2L: “~mcsdk_bios_3_0x_0x_0xdemosimage_processingipcevmtci6630k2lslave”

Building Master Code:

This can be built in the linux environment using the makefile provided at

(~mcsdk_bios_3_0x_0x_0xdemosimage_processingipcevm66ak2xmastermake ) which in turn uses the makefile located at ~mcsdk_bios_3_0x_0x_0xdemosimage_processingipcmastersrc

Q: How to import the slave code of Image processing demo and how do I build it?

Ans:

Refer the screenshot below in which the correct path should be provided to pick up the project and its sources. Note that the option for “Copy projects into work space” should be unchecked.

In the project explorer screen, check whether you are able to see the folders, slave –> src –> *.c files.... Right click on the project and give build.

Q: After building the slave code of the Image processing demo using CCS, where it needs to be replaced in the linux file system?

Ans:

Take the binary file, image_processing_evmtci66xxk2x_slave.out and replace it in the path target Linux filesystem, “/usr/share/matrix-gui-2.0/apps/demo_imageproc/bin/”

Q:  While building the ARM(master) side code of Image processing demo, I see a compilation error message about Std.h as below when I make it with or without BUILD_LOCAL=true.

Update the Makefile located at “mcsdk_bios_3_0x_0x_0xdemosimage_processingipcmastersrcmakefile” as below,

IPC_INSTALL_DIR := /opt/ti/ipc_3_xx_0x_0x
CFLAGS  := -Wall -I$(COMMON_INC) -I$(MASTER_INC) -I$(IPC_INSTALL_DIR)/linux/include -I$(IPC_INSTALL_DIR)/packages -D_GNU_SOURCE

Q: While building the ARM(master) side code of Image processing demo, I see a linker error message like below.

IPC_INSTALL_DIR := /opt/ti/ipc_3_3x_xx_xx

#The location where the libraries are installed after building the IPC package
SIPC_LINUX_DIR := /opt/ti/ipc_3_3x_xx_xx/IPC_Linux_libraries

CROSS_COMPILE ?= arm-linux-gnueabihf-
CC            := $(CROSS_COMPILE)gcc
CFLAGS        := -Wall -I$(COMMON_INC) -I$(MASTER_INC) -I$(IPC_INSTALL_DIR)/linux/include -I$(IPC_INSTALL_DIR)/packages -D_GNU_SOURCE
LFLAGS        := -lpthread -L$(SIPC_LINUX_DIR)/ -ltitransportrpmsg -L$(SIPC_LINUX_DIR)/ -ltiipc -L$(SIPC_LINUX_DIR)/ -ltiipcutils

Q: The Image processing demo does not work on the version of MCSDK, V3.0x.xx.x on both the K2H and K2E EVMs. The earlier version of MCSDK works on both the EVMs. Will it be fixed on next version?

Ans:

u-boot# env default –f –a
u-boot# setenv mem_reserve 1536M
u-boot# saveenv

Q: How to build and run the qmssIpcBenchmark on C6678 EVM?

Ans:

Hardware set up:

Set the boot mode dip switch to no boot/EMIF16 mode, Connect power and emulator to C6678 EVM.

Software setup: 1. After power ON the EVM, create and launch the target configuration file(.ccxml) for CCS debugging.

2. Group Core 0 and Core 1 in CCS.
3. Connect to both cores via the group.

4. Load the evmc66xxl.gel to initialize the DDR. The GEL can be found in the “CCS install dir”ccsv5ccs_base_x.x.x.xxxxxemulationboardsevmc66xxlgel directory. Once loaded execute the default setup script on each core. In the CCS menu go to Scripts->EVMC6678L Init Functions->Global_Default_Setup.

5. Highlighting the Group in the CCS Debug window, load transportipcexamplesqmssIpcBenchmarkDebugqmssIpcBenchmark_c66xx.out on each core

6. Highlighting the Group in CCS Debug window, run the program in CCS on both cores simultaneously, qmssIpcBenchmark_c66xx will send messageQ messages between the cores via the QMSS transport. The messages will be used to measure the transport’s performance. The test will be complete after the throughput (msg/s) has been calculated.

Q: How can I build the qmssIpcbenchmark of pdk_C6678_1_1_2_x pdk_C6678_1_1_2_x with release build configuration ?

Ans:

Q: How to re-build the IPC - QMSS transport library and generate “ti.transport.ipc.qmss.transports.ae66” ?

Ans:

After installing PDK, go to path “~tipdk_C6678_1_1_2_xpackagestitransportipcqmsstransports”

1. [Optional - Required for debug single stepping] Modify the transports config.bld file C66LE/BE.ccOpts.prefix to remove optimization and add symbolic debug

From: "-mo -o3 -q -k -eo.o"
To: "-mo -g -q -k -eo.o"

2. From a command prompt navigate to the pdkpackagestitransportipc(qmss or srio) directory 3 Configure the XDCPATH environment variable with the BIOS and IPC install locations:

set XDCPATH=c:\ti\bios_w_xx_yy_zz\packages\
set XDCPATH=%XDCPATH%;c:\ti\ipc_w_xx_yy_zz\packages\

4 Configure the XDCCGROOT environment variable with the compiler install path (Using CGT 7.2.4 installed as part of CCS as an example)

set XDCCGROOT=c:\ti\ccsv5\tools\compiler\c6000_7.2.4

5 Add the XDC Tools to your system PATH

set PATH=%PATH%;c:\ti\xdctools_w_xx_yy_zz\

6 Clean the transport

>xdc clean -PR .

7 Build the transport

>xdc -PR .

If we try this option, we should be able to build in releasemode. Note: To allow single-step debug of the IPC and BIOS source rebuild the example projects with the following command added to the example’s .cfg file BIOS.libType = BIOS.LibType_Debug; <— here.

4.4.15.1.1. Introduction¶

Inter/Intra Processor Communication (IPC) is a product designed to enable communication between processors in a multi-processor environment. Features of IPC include message passing, multi-processor gates, shared memory primitives, and more.

IPC is designed for use with processors running SYS/BIOS applications. This is typically an ARM or DSP. IPC includes support for High Level Operating Systems (HLOS) like Linux, as well as the SYS/BIOS RTOS. The breadth of IPC features supported in an HLOS environment is reduced in an effort to simplify the product.

4.4.15.1.2. Install¶

IPC is often distributed and installed within a larger SDK. In those cases, no installation is required.

Outside of an SDK, IPC can be downloaded here, and is released as a zip file. To install, simply extract the file.

buildhost$ unzip ipc_<version>.zip

This will extract the IPC product in a directory with its product name and version information (e.g. c:/ti/ipc_<version>)

4.4.15.1.3. Build¶

The IPC product often comes with prebuilt libraries, so rebuilding them isn’t necessary. The IPC product downloads contain prebuilt libraries, and when provided with an SDK, IPC is typically rebuilt to contain only libraries appropriate for the SDK.

However, if you want to rebuild its libraries, IPC provides GNU makefile(s) at the base of the product. This section describes the steps required to rebuild the IPC libraries.

<buildhost> make -f ipc-bios.mak all

4.4.15.1.4. Examples¶

The IPC product contains an examples/archive directory with device-specific examples. Once identifying your device, the examples can be unzipped anywhere on your build host. Typically once unzipped, the user edits the example’s individual products.mak file and simply invokes make.

Each example contains a readme.txt with example-specific details.

4.4.15.1.5. See Also¶

• IPC 3.x
• IPC Users Guide
• IPC 3.x FAQ
• IPC Install Guide Linux
• IPC Install Guide QNX

4.4.15.2.1. Introduction¶

Inter/Intra Processor Communication (IPC) is a product designed to enable communication between processors in a multi-processor environment. Features of IPC include message passing, multi-processor gates, shared memory primitives, and more.

IPC is designed for use with processors running SYS/BIOS applications. This is typically an ARM or DSP. IPC includes support for High Level Operating Systems (HLOS) like Linux, as well as the SYS/BIOS RTOS. The breadth of IPC features supported in an HLOS environment is reduced in an effort to simplify the product.

4.4.15.2.2. Install¶

IPC is often distributed and installed within a larger SDK. In those cases, no installation is required.

Outside of an SDK, IPC can be downloaded here, and is released as a zip file. To install, simply extract the file.

buildhost$ unzip ipc_<version>.zip

This will extract the IPC product in a directory with its product name and version information (e.g. c:/ti/ipc_<version>)

4.4.15.2.3. Build¶

The IPC product often comes with prebuilt SYS/BIOS-side libraries, so rebuilding them isn’t necessary. The Linux-side user libraries may also be provided prebuilt, but customers often want to change the configuration (e.g. static, dynamic).

IPC provides GNU makefile(s) to rebuild all its libraries at the base of the product, details are below.

<buildhost> make -f ipc-linux.mak config

<buildhost> make

<buildhost> make -f ipc-linux.mak config PLATFORM=omapl138
<buildhost> make

<buildhost> make distclean

<buildhost> make -f ipc-bios.mak all

4.4.15.2.4. Run¶

The IPC product provides a way to install (copy) the necessary IPC executables and libraries onto the device’s target file-system to simplify the execution of the applications.

buildhost$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi-  uImage

buildhost$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi-  modules
buildhost$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- INSTALL_MOD_PATH=<target filesystem> modules_install

bootargs console=ttyS2,115200n8 root=/dev/nfs nfsroot=HOST:nfs_root,nolock rw ip=dhcp rproc_mem=16M@0xC3000000

buildhost$ make install prefix=<target filesystem>/usr

buildhost$ sudo make install prefix=<target filesystem>/usr

buildhost$ cp IPC_INSTALL_DIR/packages/ti/ipc/tests/bin/ti_platforms_evmOMAPL138_DSP/ <target filesystem>/lib/firmware/.

target# /usr/bin/lad_<device>

target# /usr/bin/lad_<device> lad.txt

target# /usr/bin/lad_<device> -l lad.txt

target# mkdir /debug

target# depmod -a
target# mount -t debugfs none /debug
target# modprobe remoteproc
target# modprobe da8xx_remoteproc da8xx_fw_name=messageq_single.xe674
target# modprobe virtio_rpmsg_bus
target# modprobe rpmsg_proto

target# umount /debug
target# rmmod rpmsg_proto
target# rmmod virtio_rpmsg_bus
target# rmmod da8xx_remoteproc
target# rmmod remoteproc

target# depmod -a
target# mount -t debugfs none /debug
target# modprobe remoteproc
target# modprobe omap_remoteproc
target# modprobe virtio_rpmsg_bus
target# modprobe rpmsg_proto

target# /usr/bin/MessageQApp_<device>

Using numLoops: 100; procId : 1
Entered MessageQApp_execute
Local MessageQId: 0x1
Remote queueId  [0x10000]
Exchanging 100 messages with remote processor DSP...
MessageQ_get #0 Msg = 0x15328
Exchanged 1 messages with remote processor DSP
MessageQ_get #1 Msg = 0x15328
...
...
Exchanged 99 messages with remote processor DSP
MessageQ_get #99 Msg = 0x15328
Exchanged 100 messages with remote processor DSP
Sample application successfully completed!
Leaving MessageQApp_execute

target# cat /debug/remoteproc/remoteproc0/trace0

3 Resource entries at 0xc3100000
messageq_single.c:main: MultiProc id = 1
registering rpmsg-proto service on 61 with HOST
tsk1Fxn: created MessageQ: SLAVE_DSP; QueueID: 0x10000
Awaiting sync message from host...
[t=0x00000001:67984156] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: no object for endpoint: 53
[t=0x00000001:67f626ed] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: no object for endpoint: 53
Received msg from (procId:remoteQueueId): 0x0:0x1
       payload: 8 bytes; loops: 100 with printing.
Got msg #0 (40 bytes) from procId 0
Sending msg Id #0 to procId 0
Got msg #1 (40 bytes) from procId 0
Sending msg Id #1 to procId 0
...
...
Got msg #98 (40 bytes) from procId 0
Sending msg Id #98 to procId 0
Got msg #99 (40 bytes) from procId 0
Sending msg Id #99 to procId 0
Awaiting sync message from host...
[t=0x00000015:7b46c4c2] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: no object for endpoint: 53
[t=0x00000015:7b6315fb] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: no object for endpoint: 53

4.4.15.2.5. See Also¶

• IPC 3.x
• IPC Users Guide
• IPC 3.x FAQ
• IPC Install Guide QNX
• IPC Install Guide BIOS

4.4.15.3.1. Introduction¶

Inter/Intra Processor Communication (IPC) is a product designed to enable communication between processors in a multi-processor environment. Features of IPC include message passing, multi-processor gates, shared memory primitives, and more.

IPC is designed for use with processors running SYS/BIOS applications. This is typically an ARM or DSP. IPC includes support for High Level Operating Systems (HLOS) like Linux, as well as the SYS/BIOS RTOS. The breadth of IPC features supported in an HLOS environment is reduced in an effort to simplify the product.

4.4.15.3.2. Install¶

IPC is often distributed and installed within a larger SDK. In those cases, no installation is required.

Outside of an SDK, IPC can be downloaded here, and is released as a zip file. To install, simply extract the file.

buildhost$ unzip ipc_<version>.zip

This will extract the IPC product in a directory with its product name and version information (e.g. c:/ti/ipc_<version>)

4.4.15.3.3. Build¶

The IPC product often comes with prebuilt SYS/BIOS-side libraries, so rebuilding them isn’t necessary. The QNX-side libraries/binaries may also be provided prebuilt by SDK programs, but the standalone IPC release does not currently pre-build them.

IPC provides GNU makefile(s) to rebuild all its libraries at the base of the product, details are below.

<buildhost> make -f ipc-qnx.mak all

<buildhost> make -f ipc-bios.mak all

<buildhost> set PATH=C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem
<buildhost> <XDC_INSTALL_DIR>\gmake -f ipc-bios.mak all

4.4.15.3.4. Run¶

The IPC product provides a way to install (copy) the necessary IPC executables and libraries onto the device’s target file-system to simplify the execution of the applications. The details can vary across OS’s, so this description has been separated into OS-specific sections.

startup-omap5432uevm -r 0xBA300000,0x5A00000 -vvvvv -P2 -W

buildhost$ make -f ipc-qnx.mak install

C:/QNX650/host/win32/x86/usr/bin/make -j 1 -Cle.v7 -fMakefile install
      1 [main] ? (5984) C:\QNX650\host\win32\x86\usr\photon\bin\find.exe: *** fa
tal error - system shared memory version mismatch detected - 0x8A88009C/0x2D1E009C.
This problem is probably due to using incompatible versions of the cygwin DLL.
Search for cygwin1.dll using the Windows Start->Find/Search facility
and delete all but the most recent version.  The most recent version *should*
reside in x:\cygwin\bin, where 'x' is the drive on which you have
installed the cygwin distribution.  Rebooting is also suggested if you
are unable to find another cygwin DLL.

buildhost$ copy <IPC_INSTALL_DIR>/packages/ti/ipc/tests/bin/ti_platform_omap54xx_ipu/messageq_single.xem4 <DESTDIR>/armle-v7/bin

target# cd <target directory corresponding to DESTDIR>/armle-v7/bin
target# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<target directory corresponding to DESTDIR>/armle-v7/usr/lib
target# ipc <CORE1> <remote executable 1> <CORE2> <remote executable 2> ...

target# ipc IPU test_omx_ipu_omap5.xem4

target# cd <target directory corresponding to DESTDIR>/armle-v7/bin
target# slay ipc

target# cd <target directory corresponding to DESTDIR>/armle-v7/bin/tests
target# use MessageQApp

target# cd <target directory corresponding to DESTDIR>/armle-v7/bin/tests
target# ./MessageQApp 10

target# cd <target directory corresponding to DESTDIR>/armle-v7/bin
target# shmemallocator
target# cd tests
target# mmrpc_test 1

Using numLoops: 10; procId : 1
Entered MessageQApp_execute
Local MessageQId: 0x1
Remote queueId  [0x10000]
Exchanging 10 messages with remote processor IPU...
MessageQ_get #0 Msg = 0x11c9f0
Exchanged 1 messages with remote processor IPU
MessageQ_get #1 Msg = 0x11c9f0
Exchanged 2 messages with remote processor IPU
MessageQ_get #2 Msg = 0x11c9f0
...
...
Exchanged 9 messages with remote processor IPU
MessageQ_get #9 Msg = 0x11c9f0
Exchanged 10 messages with remote processor IPU
Sample application successfully completed!
Leaving MessageQApp_execute

target# cat /dev/ipc-trace/IPU

[0][      0.000] 16 Resource entries at 0x3000
[0][      0.000] messageq_single.c:main: MultiProc id = 1
[0][      0.000] [t=0x006c565d] ti.ipc.transports.TransportVirtioSetup: TransportVirtio
Setup_attach: remoteProcId: 0
[0][      0.000] registering rpmsg-proto:rpmsg-proto service on 61 with HOST
[0][      0.000] [t=0x0072625b] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_create: endPt c
reated: 61
[0][      0.000] [t=0x0073e8d9] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_toHost kicked
[0][      0.000] [t=0x00753771] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][      0.000] [t=0x0076cb49] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][      0.000]        Received msg: from: 0x5a, to: 0x35, dataLen: 72
[0][      0.000] [t=0x007872e9] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: no object
for endpoint: 53
[0][      0.000] tsk1Fxn: created MessageQ: SLAVE_CORE0; QueueID: 0x10000
[0][      0.000] Awaiting sync message from host...
[0][     51.992] [t=0x0c475268] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     51.992] [t=0x0c48eb28] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     51.993]        Received msg: from: 0x400, to: 0x3d, dataLen: 176
[0][     51.993] [t=0x0c4ad220] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 176, from: 1024
[0][     51.993]
[0][     52.995] [t=0x0c873ded] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     52.996] [t=0x0c88b029] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     52.996]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     52.996] [t=0x0c8a8a87] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     52.996]
[0][     52.996] Received msg from (procId:remoteQueueId): 0x0:0x1
[0][     52.996]        payload: 8 bytes; loops: 10 with printing.
[0][     52.997] [t=0x0c8eab7e] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     52.997] [t=0x0c9031bc] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     52.997]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     52.997] [t=0x0c9208fa] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     52.997]
[0][     52.997] Got msg #0 (40 bytes) from procId 0
[0][     52.997] Sending msg Id #0 to procId 0
[0][     52.998] [t=0x0c959f33] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     52.998] [t=0x0c971df7] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     52.998]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     52.998] [t=0x0c98f3e7] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     52.998]
[0][     52.999] Got msg #1 (40 bytes) from procId 0
[0][     52.999] Sending msg Id #1 to procId 0
[0][     52.999] [t=0x0c9c7a00] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     52.999] [t=0x0c9df7fc] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     52.999]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     52.999] [t=0x0c9fce5a] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     52.999]
[0][     53.000] Got msg #2 (40 bytes) from procId 0
[0][     53.000] Sending msg Id #2 to procId 0
[0][     53.000] [t=0x0ca36e79] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     53.000] [t=0x0ca4ea95] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     53.000]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     53.001] [t=0x0ca6c975] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     53.001]
[0][     53.001] Got msg #3 (40 bytes) from procId 0
[0][     53.001] Sending msg Id #3 to procId 0
...
...
[0][     53.007] Got msg #8 (40 bytes) from procId 0
[0][     53.007] Sending msg Id #8 to procId 0
[0][     53.007] [t=0x0cccd3d7] ti.ipc.rpmsg.MessageQCopy: callback_availBufReady: virt
Queue_fromHost kicked
[0][     53.007] [t=0x0cce50ed] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_swiFxn:
[0][     53.007]        Received msg: from: 0x406, to: 0x3d, dataLen: 40
[0][     53.007] [t=0x0cd027bd] ti.ipc.rpmsg.MessageQCopy: MessageQCopy_send: calling c
allback with data len: 40, from: 1030
[0][     53.007]
[0][     53.008] Got msg #9 (40 bytes) from procId 0
[0][     53.008] Sending msg Id #9 to procId 0
[0][     53.008] Awaiting sync message from host...

buildhost$ unzip ex02_messageq.zip
buildhost$ cd ex02_messageq
buildhost$ make clean
buildhost$ make
buildhost$ make install

buildhost$ cd <IPC_INSTALL_DIR>/examples
buildhost$ make extract
buildhost$ make
buildhost$ make install

target# ipc IPU ex02_messageq/debug/server_ipu.xem4 DSP ex02_messageq/debug/server_dsp.xe64T
target# cd ex02_messageq/debug/
target# app_host IPU

target# echo <slave executable file path> > /dev/ipc-file/<core name>
target# echo 1 > /dev/ipc-state/<core name>

target# echo 0 > /dev/ipc-state/<core name>

target# cat /dev/ipc-state/<core name>

target# IPC_DEBUG=<level> app_host

target# sloginfo -m42

target# IPC_DEBUG_SLOG_LEVEL=<level> ipc DSP1 ex02_messageq/debug/server_dsp1.xe66

target# cat /dev/ipc-trace/<core name>

ipc3x_dev: utils
    @cd src/ipc3x_dev; \
        make IPC_PLATFORM=$(IPC_PLATFORM) SMP=1 QNX_CFLAGS=$(QNX_CFLAGS) IPC_DEBUG=1

target# make -f ipc-qnx.mak clean
target# make -f ipc-qnx.mak all

4.4.15.3.5. See Also¶

• IPC 3.x
• IPC Users Guide
• IPC 3.x FAQ
• IPC Install Guide Linux
• IPC Install Guide BIOS

4.6.3.1.1. Overview¶

Bootloader supports power-on-reset bootstraps for the board. It initializes board, loads application from the memory device to DDR and transfers control to application. Section provides additional details including flashing and booting instructions across different media.

4.6.3.1.2. Source Reference¶

< BASE_DIR = PDK_INSTALL_DIR\packages\ti\starterware>

4.6.3.1.3. Bootloader execution sequence¶

The Processor SDK RTOS boot loader uses a two stage boot process. The different stages of the application boot sequence using Processor SDK RTOS bootloader are shown below:

4.6.3.1.4. Tools and Binary formats¶

TI Boot image

<GCC_TOOLCHAIN_PATH>/bin/arm-none-eabi-objcopy -O binary <application>.out <application>.bin

gcc tiimage.c –o tiimage.out

tiimage.out <Image Load Address> NONE <application>.bin <application>_ti.bin

<GCC_TOOLCHAIN_PATH>/bin/arm-none-eabi-objcopy -O binary <application>.out <application>.bin

tiimage.exe <Image Load Address> NONE <application>.bin <application>_ti.bin

4.6.3.1.5. Boot Modes supported¶

Following are the Boot Modes supported through AM335x/AM437x bootloader for the various EVMs.

4.6.3.1.6. Building the Bootloader¶

Pre-requisite: Setup SDK build environment as described in article

Setup_Environment

Change working directory to the packages/ti/starterware directory

cd <procsdk_install_dir>/pdk_<soc>_<version>/packages/ti/starterware

NOTE: For the starterware build targets below, the parallel make option (-j) is not supported. Please ensure that the below are built without parallel make option.

gmake bootloader BUILDCFG=boot BOOTMODE=<BOOT_MODE> PLATFORM=<EVM> PROFILE=<BUILD_PROFILE> -s KW_BUILD=no

gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=amic110-ddrless PROFILE=debug -s KW_BUILD=no USE_DDR=no
gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=amic110-ddrless PROFILE=release -s KW_BUILD=no USE_DDR=no

gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=am335x-evm PROFILE=debug -s KW_BUILD=no ENABLE_PRU=yes
gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=am335x-evm PROFILE=release -s KW_BUILD=no ENABLE_PRU=yes

gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=am335x-evm PROFILE=debug -s KW_BUILD=no BIN_LOAD=yes
gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=am335x-evm PROFILE=release -s KW_BUILD=no BIN_LOAD=yes

gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=amic110-ddrless PROFILE=debug -s KW_BUILD=no BUILD_ICSS_DDRLESS_BOOT=yes
gmake bootloader BUILDCFG=boot BOOTMODE=mcspi PLATFORM=amic110-ddrless PROFILE=release -s KW_BUILD=no BUILD_ICSS_DDRLESS_BOOT=yes

4.6.3.1.7. Boot Mode settings¶

Boot mode settings for supported AM335x and AM437x boards can be found in the applicable EVM Hardware User’s Guide.

4.6.3.1.8. Boot Modes¶

StarterWare QSPI Flash Writer!!
BOARDInit status [0x0]
SoC                   : [AM43XX]
Core                  : [A9]
Board Detected        : [IDKEVM]
Base Board Revision   : [UNKNOWN]
Daughter Card Revision: [UNKNOWN]
Copying boot to QSPI Flash
Copying app to QSPI Flash
Changing read to quad mode
Read mode has been changed to Quad mode
SUCCESS!!!
Flashing completed

StarterWare Boot Loader
BOARDInit status [0x0]
SoC                   : [AM43XX]
Core                  : [A9]
Board Detected        : [IDKEVM]
Base Board Revision   : [UNKNOWN]
Daughter Card Revision: [UNKNOWN]
Copying Header of the application image
Copying image from flash to DDR
Jumping to StarterWare Application...

NOTE: Boot logs will appear approximately after 25 seconds on reset.

 NOTE:If there is no boot mode selection present on board, boot image will be loaded depending on ROM boot sequence
Example: If QSPI flash and MMCSD has valid bootloaders, on reset MMCSD boot image will be loaded following ROM Boot sequence.

CCCCCCCCCCCCCCCCCCCCCCCCCCCC
StarterWare Boot Loader
BOARDInit status [0x0]
 SoC                   : [AM43XX]
 Core                  : [A9]
 Board Detected        : [IDKEVM]
 Base Board Revision   : [UNKNOWN]
 Daughter Card Revision: [UNKNOWN]
GPIO Instance number: 0
Pin number: 22
Please transfer file:
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC

Starting SPIWriter.
Choose Operation:
Enter 1 ----> To FLASH an Image
Enter 2 ----> To ERASE Flash
Enter 3 ----> To EXIT

Enter the File Name

Enter the Offset in bytes (in HEX)

Erasing flash at byte offset: xx, byte length: xxxx
SF: Successfully erased xxxx bytes @ xxxx
Writing flash at page offset: x, number of pages: xxxx
Flashing is in progress...
Verifying... Success.

Choose your operation
Enter 1 ---> To Flash an Image
Enter 2 ---> To ERASE the whole NAND
Enter 3 ---> To EXIT

Enter image file path

Enter offset (in hex):

Choose the ECC scheme from given options
Enter 1 ---> BCH 8 bit
Enter 2 ---> HAM
Enter 3 ---> T0 EXIT
Please enter ECC scheme type:

Application is successfully flashed
NAND flashing successful!

   StarterWare Boot Loader
BOARDInit status [0x0]
SoC                   : [AM335X]
Core                  : [A8]
Board Detected        : [GPEVM]
Base Board Revision   : [1.5]
Daughter Card Revision: [UNKNOWN]
NAND flash is connected to GPMC on this board
Jumping to StarterWare Application...

4.6.3.1.9. Test Application¶

The section explains steps for building and booting a sample pdk application for am335x or am437x using MMCSD bootloader.

4.6.3.1.10. Usage Notes¶

• Bootloader Memory map

The bootloader code runs from internal OCMC memory and occupies certain amount of OCMC memory that is not available for application to use during booting.

Refer to the map file for the boot loader to check for latest information on the memory utilization in the boot loader.

Location of linker command file:

BASE_DIR\binary\bootloader\bin\<platform>\gcc

After SBL execution is complete, this region can be used as per application requirement.

• Configuring entry point for SBL

The three files that help setup the entry point in the bootloader build are “PDK_INSTALL_PATH/packages/ti/starterware/soc/armv7a/gcc/sbl_init.S” and the linker command file “PDK_INSTALL_PATH/packages/ti/starterware/examples/gcc/<device>_boot.lds”. The global symbol Entry is used to provide the entry point to the bootloader. The Base address of the memory section OCMCRAM (starts at 1K offset in OCMC RAM as defined in TRM) is then used by the tiimage or GPHEader tool to provide RBL the guidance to find the entry point to pass control. After MLO is created check the TI image format file( _ti.bin) to confirm that the entry point matches the location of Entry symbol in the .map file.

• Boot image creation tools generates a large boot image if load sections are fragmented

Please note that when using objcopy the compiler generates a contiguous binary that gets loaded by the bootloader at the location specified in the header appended by TIIMAGE boot utility. IF you have some code sections in OCMC or SRAM and some section in DDR the compiler will generates a binary that spans across full memory range which would be in order of MB or even GB size so it is recommended that you create compact binaries that can be loaded into memory or implement a ELF parser to bootloader memory sections that may be fragmented in the address space. you can also load separate binaries for OCMC sections and DDR memory and load the sections separately

• Removing Heap section from application binary to speed up boot times

A common issue reported with the ARM GCC compiler is that it appends Heap section associated with the binary to the binary image used to boot. The Heap section is usually filled with zeros so can cause significant delay in boot times. Essentially the bootloader will be writing a bunch of zeros in memory so is inefficient. Following work around has been used to circumvent the issue

Option 1: Eliminate the heap by using the compiler option “–remove-section” as described in the E2E post below:

Refer: E2E post to configure Heap in ARM application binary by adding “–remove-section”

Example BIOS configuration:

var heap1 = HeapMem.create();
heap1.size = 256 * 1024 * 1024;
heap1.sectionName = ".stack";
Memory.defaultHeapInstance = heap1;

Compiler Setting : –remove-section=.stack

Option 2 Configure Segment type to be “NO LOAD” in .cfg and use excludeSections

SYSBIOS Memory map configurations allows user to specify the section name, length and type. by configuring the section type to “NOLOAD” and using excludeSection option the heap memory can be eliminated from the final binary.

Example BIOS configuration:

Program.sectMap[".biosheap"] = new Program.SectionSpec();
Program.sectMap[".biosheap"].runSegment = "DDR2"
Program.sectMap[".biosheap"].type = "NOLOAD";

Program.sectionsExclude = ".biosheap"

Alternate approach using linker command file:

.ddr3Heap (NOLOAD):
  {
      *(.ddr3Heap)
  } > HOST_DDR3

4.6.3.1.11. Debugging application boot¶

Steps to debug application boot using Processor SDK RTOS bootloader are discussed in the article `Common steps to debug application boot <index_Foundational_Components.html#common-steps-to-debug-application-boot>`__

4.6.3.2.1. Overview¶

The Secondary Bootloader (SBL) for AM57xx device initializes the execution environment for multi-core application and this can be used to demonstrate an out-of-box experience.The section covers additional details including execution sequence, tools and additional flashing instructions.

4.6.3.2.2. Bootloader Execution Sequence¶

• Power On Reset
• ROM Bootloader (RBL)
  • Software pre-programmed in ROM memory starts executing
  • Checks Sysboot pins and choose booting device
  • If no valid bootloader found on booting device, RBL checks for next booting device.
  • Platform configuration and initialization.
  • Configures DPLL and clock settings for MPU, and boot media like I2C, MMCSD, SD/MMC, SPI, QSPI, Ethernet etc for reliable boot.
  • The sequence depends on RBL execution flow and Sysboot pins.
  • RBL gets image size and load address by checking TI Image Header appended on bootloader binary(.bin). Check binary formats.
  • Loads the binary to internal memory at the Load address fetched from TI Image Header
  • Passes control to Secondary Bootloader(SBL)

• Secondary bootloader(SBL)
  • User level secondary bootloader(SBL) begins execution from internal memory by running basic initialization routines like setting up Stack, BSS and then jumps to main() to begin Board Initialization.
  • Board Initialization is done by a call to Board_init() API.For additional details refer Processor SDK Board Support.
  • It includes setting up PLLs, enabling clocks to all interfaces and modules, performing pinmux and setting up UART console.
  • Once Board Initialization is complete, it enables clocks to the slave cores like C66x/DSP, IPU, etc and brings them out of reset.
  • Parses Multicore Application image located in memory device and copies it to DDR memory based on load address for different sections.
  • Once copy is successful it transfers control to application.
• Application then starts executing from DDR.

4.6.3.2.3. Directory structure¶

Makefiles:

• PDK_INSTALL_PATH/ti/boot/sbl/board/<EVAL_BOARD>/build: Makefile for bootloader that provides list of source files and library and compiler options to create bootloader binary.

Source Files:

• PDK_INSTALL_PATH/ti/boot/sbl/board/<EVAL_BOARD>: Source to SBL main function that consolidates all features
• PDK_INSTALL_PATH/ti/boot/sbl/soc: Source to SOC specific initialization used in the SBL.
• PDK_INSTALL_PATH/ti/boot/sbl/src: Source to boot media specific initialization used in the SBL.

4.6.3.2.4. Tools and Binary Formats¶

This section lists out the various tools and scripts used by SBL for different boot modes and those required to create a bootable application image.

SBL/MLO image format: To generate the MLO, SBL uses tiImageGen tool to prepend the sbl.bin image with the TI header information. The image format has been described in detail in the Image Format Section of theAM57xx Technical Reference manual

Application image format: A bootable application image can be created by using the Am57xImageGen script provided under tools folder as part of sbl. It can be located at <PDK_INSTALL_DIR>/packages/ti/boot/sbl/tools/scripts folder.

The Am57xImageGen script uses out2rprc and multicoreImageGen format conversion tools to create the final application image. Graphical view of the multicore application image is provided below:

The script creates the bootable image in 2 steps

Step 1: Conversion to RPRC format conversion

• Firstly, application executable is converted from ELF/COFF format (.out) to custom TI Rprc binary image using out2rprc tool. This tool strips out the initialized sections from the executable file (i.e. *.out) and places them in a compact format that the SBL can understand. The output (bin) file is typically much smaller than the original executable (out) file.
• The rprc files are intermediate files in a format that is consumed by MulticoreImageGen tool that generates the final binary.

RPRC File Header Format

RPRC Section Header Format

Step 2: Multicore Image file generation

• RPRC files for each cores is combined into a single multicore bootable application image.

Multicore boot image format

Meta Header Start

Meta Header per Core

Core ID and Device ID for specific devices can be located in the file sbl_slave_core_boot.h in the boot/sbl/soc/<SOC_NAME> folder

Refer section App Image Creation for more details on usage of this script and application image creation.

Flashing Tools

SBL provides a CCS based qspi flash writer utility to flash image and multicore AppImage from a SD card to onboard QSPI device. It is located at <PDK_INSTALL_DIR>/packages/ti/boot/sbl/tools/flashWriter/qspi

4.6.3.2.5. Building the SBL¶

Pre-requisites to Building

• Set your environment using pdksetupenv.bat or pdksetupenv.sh. Refer to the Processor SDK RTOS Building page for information on setting up your build environment
• The SBL has following dependencies and will need the following libraries built
  • Board
  • UART
  • I2C
  • SPI
  • CSL
  • OSAL
  • MMCSD
  • PM

Compiling the SBL Components

To build the SBL components:

1. cd <PDK>/packages/ti/board/diag
2. make all BOARD=<BOARD_NAME> SOC=<SOC_NAME> BOOTMODE=<BOOTMEDIA>

• BOARD_NAME : idkAM572x, idkAM571x, evmAM572x, idkAM574x
• SOC_NAME : AM572x, AM571x, AM574x

This will make the SBL for a specific $BOARD and $BOOT_MEDIA. Output files will be located in: <PDK>/packages/ti/boot/sbl/binary/<BOARD>

Boot Modes

This Release of SBL supports MMCSD and QSPI Boot modes. The different boot modes supported for all the boards is tabulated in the table below.

PDK QSPI Flash Writer!!
Copying boot to QSPI Flash
Copying app to QSPI Flash
Changing read to quad mode
Read mode has been changed to Quad mode
SUCCESS!!!
Flashing completed

4.6.3.2.6. Test Application¶

SBL provides a test application to demonstrate booting of multicore application image on A15 and DSP cores.The multicore sample application uses mailbox for inter-processor communication. It is used to validate the multi-core boot-up use case.

Master application sends wake-up message to the DSP slave cores & waits for acknowledgement message from the slave cores in an infinite loop.Each slave DSP core waits for wake-up message from the master core responds back with an acknowledgement message.

Go to cd (TI_PDK_INSTALL_DIR)\packages\ti\boot\sbl

make example BOARD=<BOARD> SOC=<SOC> to build the application
make example_clean BOARD=<BOARD>

make example BOARD=idkAM572x SOC=AM572x

Ex: export BIN_PATH=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary

export APP_MPU_CPU0=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/idkAM572x/example/armv7/bin/sbl_app.out

export APP_DSP1=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/idkAM572x/example/c66/dsp1/bin/sbl_app.xe66

export APP_DSP2=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/idkAM572x/example/c66/dsp2/bin/sbl_app.xe663

export APP_IPU1_CPU0=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/idkAM572x/example/m4/ipu1/bin/sbl_app.xem4

export APP_IPU1_CPU0=$(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/idkAM572x/example/m4/ipu2/bin/sbl_app.xem4

4.6.3.2.6.3. Windows environment¶

Command to build the test application.

Go to cd (TI_PDK_INSTALL_DIR)\packages\ti\boot\sbl

gmake example BOARD=<BOARD> SOC=<SOC> to build the application
gmake example_clean BOARD=<BOARD>

Example:

gmake example BOARD=idkAM572x SOC=AM572x

To create the final bootable application image use the AM57xImageGen script and follow these steps

1. Set the following environment variable in windows command prompt

BIN_PATH: Pointing to the path where the AppImage needs to be generated

Ex:  set BIN_PATH=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary

2. Edit the batch file to point to the application elf files by setting the input application variables.

App_MPU_CPU0: Point to the path where the application .out for A15 MPU is located App_DSP1: Point to the path where the dsp core 1 application is located App_DSP2: Point to the path where the dsp core 2 application is located

set App_MPU_CPU0=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary\idkAM572x\example\armv7\bin\sbl_app.out

set App_DSP1=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary\idkAM572x\example\c66\dsp1\bin\sbl_app.xe66

set App_DSP2=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary\idkAM572x\example\c66\dsp2\bin\sbl_app.xe66

set App_IPU1_CPU0=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary\idkAM572x\example\m4\ipu1\bin\sbl_app.xem4

set App_IPU2_CPU0=%TI_PDK_INSTALL_DIR%\packages\ti\boot\sbl\binary\idkAM572x\example\m4\ipu2\bin\sbl_app.xem4

3. If it is not required to load an application on specific core leave the variable blank.

4. Run the batch file AM57xImageGen found under the path $(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/tools/scripts

5. Follow the steps 4 to 6 listed above for Linux environment. | Setup Requirements “”“”“”“”“”“”“”“”“”“” For information on board specific requirements like power supply, UART console port connections refer the Hardware User guide of the respective boards.

The configurations needed to setup UART console through a serial terminal application on host PC are listed in the next section.

4.6.3.2.6.3.1. UART Console Setup¶

PDK SBL prints messages on the UART Serial Console running on the host. Hence, a serial terminal application (like Tera Term/HyperTerminal/minicom) should be running on the host.

The host serial port must be configured at 115200 baud, no parity, 1 stop bit and no flow control. Please ensure that the local echo setting for the terminal is turned off.

4.6.3.2.6.3.2. Loading the test application¶

Follow these steps to load the test application using a SD card on the target

copy the MLO to your SD card (located at $(TI_PDK_INSTALL_DIR)/packages/ti/boot/sbl/binary/[BOARD]/mmcsd)

1. copy the example app located at path pointed to by BIN_PATH to your SD card
2. insert your SD card into your board and power on your board
3. open teraterm to connect to the board’s UART console
4. press the “Hard Reset” button on your board

On Successful bootup you should see the following logs on the UART console for a AM572x based board.

Note

MPU Core 0 example does a sequential check of mailbox messages sent from the other cores. On rare occasions, the check happens before the message is sent - the “<core> boot-up Successful” message might not be displayed even though the core(s) were booted successfully.

4.6.3.2.7. Application Integration¶

4.6.3.2.7.1. Memory Map¶

Table indicated below provides memory map details for SBL image in OCMC_RAM1.  For more details on pinmux and IO delay requirements refer this link Processor SDK Board Support

We recommend that users should refer to the linker command file and the map file for the boot loader to check for latest information on the memory utilization in the boot loader.

Location of linker command file: <PDK_INSTALL_PATH>/packages/ti/boot/sbl/board/<BOARD>/build

The SBL memory map is shown below

Note

• After the application boots and is running on the SOC, it is free to use the SBL_MEM region.
• The pinmux data from the board library and MMU Table are part of the SBL_MEM region indicated in the figure above. If pinmux data needs to be placed at a specific location then users can update the SBL linker command file to add the BOARD_IO_DELAY_CODE and BOARD_IO_DELAY_DATA as described in Application Integration of board library for AM5x

4.6.3.2.8. SBL Customization¶

SPI_Params_init(&spiParams);
spiParams.bitRate = 24000000U;

4.6.3.2.9. Usage Notes¶

4.6.3.3.1. Overview¶

The Secondary Bootloader (SBL) for AM65xx/J721E device initializes the execution environment for multi-core applications and this can be used to demonstrate a real world product experience. This section covers additional details including execution sequence, tools and additional flashing instructions.

The SBL is essentially a baremetal application, and it uses many components from the Processor SDK

• <PDK>/packages/ti/build : For build infrastructure
• <PDK>/packages/ti/csl : For initialization and SoC addresses
• <PDK>/packages/ti/board : For board and usecase specific initialization
• <PDK>/packages/ti/drv/spi : For reading applications from OSPI flashes
• <PDK>/packages/ti/drv/udma : For reading data from boot media using DMA
• <PDK>/packages/ti/drv/mmcsd : For reading applications from MMC/SD/eMMC
• <PDK>/packages/ti/fs/fatfs : For reading files from MMC/SD/eMMC
• <PDK>/packages/ti/drv/sciclient : For communicating with DMSC sub-system
• <PDK>/packages/ti/drv/uart : For log messages
• <PDK>/packages/ti/osal : Primitives required by ti/drv components

The SBL is in turn used by the board framework to load and start diagnostics

Bootloader Execution Sequence

• Power On Reset
• ROM Bootloader (RBL)
  • Software pre-programmed in AM65xx/J721E ROM memory starts executing
  • The RBL performs platform configuration and initialization.
  • It then checks sysboot pins and chooses booting device
  • The RBL then configures PLL and clock settings for R5, and boot media like eMMC, SD/MMC, OSPI, UART, PCIe, Ethernet etc for reliable boot.
  • If no valid bootloader found on booting device, the RBL checks for next booting device, based on sysboot pins
  • It then gets image size and load address by checking the X.509 certificate that is part of the bootloader image.
  • The RBL then verifies, optionally decrypts and loads the binary to internal memory at the load address specified in the X.509 certificate.
  • Finally it resets the R5 and passes control to Secondary Bootloader(SBL) running on the R5.
• Secondary bootloader(SBL)
  • User level secondary bootloader(SBL) begins execution from internal memory. It enables ATCM, starts PMU timers for profiling, initializes the MCU, and sets up the stack, heap and globals. It then jumps to main().
  • Board Initialization is done by calls to Board_init() API.For additional details refer Processor SDK Board Support.
  • The RAT is setup. Pin MUX and UART console are setup by calling Board_init() API. The system firmware (SYSFW) is then loaded from the boot media into the DMSC subsystem.
  • Once the SYSFW is up and running, the rest of the initialization can be done.
  • This includes optionally using Board_init() to configure PLLs, LPSCs and DDR.
  • The SBL then loads the application from the boot media. If the image is signed, the application will be copied into a user specified reserved memory, and the SBL will attempt to verify the image by calling system firmware APIs. On HS devices, the boot proceeds only if image verification passes.
  • The SBL parses application image(s) for each of the core(s) from boot media and scatter loads it to memory.
  • Once the application is loaded, the SBL communicates with the system firmware to setup the clocks for the core(s) and release it from reset.
  • The core then starts executing from application entry point.

4.6.3.3.2. Block Diagram¶

4.6.3.3.3. Memory Map¶

4.6.3.3.4. Directory structure¶

sbl
│
├── board
│   └── k3
│       └── sbl_main.c                                      <= define main() for SBL, board specific init
│
├── build
│   ├── makefile                                            <= makefile for the SBL component
│   ├── sbl_am65xx.sh                                       <= For legacy, called by Yocto build
│   ├── sbl_boot_test.mk                                    <= Builds SBL single core tests
│   ├── sbl_smp_test.mk                                     <= Builds example app for using SBL lib
│   ├── sbl_mcu0_boot_perf_test.mk                          <= Builds example app for SBL performance tuning
│   ├── sbl_mcu0_boot_xip_entry.mk                          <= Builds example trampoline app to demonstrate transitioning to a XIP app from SBL
│   ├── sbl_mcu0_boot_xip_test.mk                           <= Builds example app to demonstrate XIP execution from XIP capable boot media
│   ├── sbl_img.mk                                          <= builds SBL image that is loaded and executed by ROM code
│   ├── sbl_lib.mk                                          <= Builds sbl library that other apps can link into
│   ├── sbl_multicore_smp.mk                                <= Builds multi-core image from SBL lib eg. test to demonstrate symmetric multiprocessor boot (SMP)
│   └── sbl_multicore_amp.mk                                <= Builds multi-core image from single core tests to demonstrate asymmetric multiprocessor boot (AMP)
│
├── example
│   └── k3MulticoreApp
│       ├── binary
│       │   └── [soc]
│       │       ├── sbl_baremetal_*.appimage                <= SBL loadable board specific sample apps for testing SBL boot flow on GP devices
│       │       ├── sbl_baremetal_*.appimage.signed         <= SBL loadable board specific signed sample apps for testing SBL boot flow on HS devices
│       │       └── sbl_baremetal_*_release.x*.bin          <= Binary image that can be eXecuted In Place on XIP capable boot media
│       ├── mcuAmplinker.lds                                <= Linker comamnd file when TI CGT is used for Asym. Multiproc. boot
│       ├── mpuAmplinker.lds                                <= GCC linker command file (for Cortex Axx cores) for Asym. Multiproc. boot
│       ├── mcuBootPerfLinker.lds                           <= TI CGT Linker comamnd file for SBL performance tuning example.
│       ├── mcuLockStepLinker.lds                           <= Linker comamnd file when TI CGT is used for R5 lock-step boot
│       ├── mpuSmplinker.lds                                <= GCC linker command file (for Cortex Axx cores) for SMP boot
│       ├── mcuXiplinker.lds                                <= Linker command file for XIP trampoline app
│       ├── xip_entry.lds                                   <= Linker comamnd file for XIP test case
│       ├── xip_entry.asm                                   <= Entry point of XIP trampoline app
│       ├── xip_stub.c                                      <= Simple SBL test app that demonstrates transitioning to a XIP app
│       ├── sbl_amp_multicore.c                             <= Simple SBL test that displays UART message
│       ├── sbl_amp_multicore_sections.h                    <= Allows same source to be loaded to different sections for different cores.
│       ├── sbl_mcu_0_boot_perf_benchmark.c                 <= SBL Test to tune boot performance.
│       ├── sbl_multicore_a53.asm                           <= Test case entry point  for Cortex-Axx cores
│       ├── sbl_multicore_r5.asm                            <= Test case entry point for Cortex-R5 cores
│       ├── sbl_multicore_r5_sections.inc                   <= Allows same source to be loaded to different sections for different MCUs.
│       ├── sbl_printf.c                                    <= Lightweight UART printf function for SBL testing
│       ├── sbl_smp_multicore.c                             <= Simple SBL SMP test that uses SBL lib to reset MPUs
│       └── sbl_smp_r5.asm                                  <= Provides dummy override function for __mpu_init for SMP testcase.
│
├── binary                                                  <= ROM bootable SBL images for each board/boot media
│   ├── [board]
│       └── [bootmedia]
│           └── bin
│               └── sbl_[bootmedia]_img_mcu1_0_release.tiimage
│
├── lib                                                     <= SBL lib for each boot media/board supported
│   ├── [bootmedia]
│   │   └── [board]
│   │       └── r5f
│   │           └── release
│   │               └── sbl_lib_[bootmedia].aer5f
│   └── cust
│       └── [board]
│           └── r5f
│               └── release
│                   └── sbl_lib_cust.aer5f
│
├── soc                                                     <= SOC specific SBL code
│   └── k3
│       ├── linker.cmd                                      <= Linker file used for generating ROM loadable SBL image.
│       ├── sbl_err_trap.h                                  <= Error loops for SBL
│       ├── sbl_init.asm                                    <= SBL Entry point
│       ├── sbl_misc.asm                                    <= SBL Assembly utility functions
│       ├── sbl_log.h                                       <= SBL logging framework
│       ├── sbl_sci_client.c                                <= Calls SYSFW on DMSC
│       ├── sbl_sci_client.h
│       ├── sbl_slave_core_boot.c                           <= Code that contains the sequence to release a core from reset
│       ├── sbl_slave_core_boot.h
│       ├── sbl_soc.c                                       <= Cache Ops, PMU init, image verfication, etc & SoC specific code like RAT Init..
│       ├── sbl_soc_cfg.h                                   <= Abstraction layer for hiding SoC level changes from SBL
│       └── sbl_profile.h                                   <= SBL profiling framework
│
├── src                                                     <= Common drivers used across SOCs
│   ├── mmcsd
│   ├── hyperflash
│   ├── ospi
│   ├── qspi
│   ├── uart
│   ├── rprc                                                <= RPRC image parser used by SBL
│   └── spi
│
└── tools
    ├── btoccs
    ├── byteswap
    ├── ccsutil
    ├── flashWriter                                         <= Unused for AM65xx/J721E. AM65xx/J721E uses Uniflash to program flashes.
    ├── multicoreImageGen                                   <= Stitches multiple RPRC images for different cores into a single image
    ├── omapl13x_boot_utils                                 <= Unused for AM65xx/J721E
    ├── omapl13x_sd_card_format                             <= Unused for AM65xx/J721E
    ├── out2rprc                                            <= Converts .out into .rprc files, so that SBL can load non-continuous memory sections
    ├── scripts                                             <= Scripts used by .out  generated by CCS projects into SBL loadable images
    │   ├── K3ImageGen.bat
    │   └── K3ImageGen.sh
    └── tiImageGen                                          <= Unused for AM65xx/J721E. Image generation is handled by PDK build framework (<prsdk_install_path>/pdk_*/packages/ti/build/)

4.6.3.3.5. Image Formats¶

SBL format:

To generate the a bootable image, the SBL build uses the x509CertificateGen script to sign the sbl binary with so that the ROM Boot Loader (RBL) can parse it. The image format expected by the RBL has been described in detail in the Image Format Section of the AM65xx Technical Reference Manual and the J721E Technical Reference Manual

Application image format:

Two utilities - out2rprc and multicoreImageGen are used to convert an application elf image(s) into an image loadable by the SBL. The structure of a multicore application image is provided below:

RPRC File Header Format

RPRC Section Header Format

Multicore boot image format

Meta Header Start

Meta Header per Core

Signed application image format:

To convert the multicore application image into a format that can be verified, the build flow uses the x509CertificateGen script to create a x509 certificate for the app image. Images that have a x509 certificate are called signed images. Signed applications images are mandatory for HS devices, but will work also work on GP devices.

Signed images are automatically detected by the SBL and loaded into a scratch memory area specified during SBL build. The scratch memory area used by default is specified in sbl_lib.mk via the flags SBL_SCRATCH_MEM_START and SBL_SCRATCH_MEM_SIZE. The SBL_SCRATCH_MEM* options can also be specified for custom builds to override the defaults.

The SBL scratch memory is unavailable to applications during app load time, as the SBL is still active. Once the SBL transfers control to the application, this memory is available for app use - in other words SBL_SCRATCH_MEM* is available during app runtime.

For information on the application’s X.509 certificate format, please refer Security X509 Certificate Documentation

4.6.3.3.6. Building the SBL and its components¶

Pre-requisites to Building

• Set your environment using pdksetupenv.bat or pdksetupenv.sh. Refer to Processor SDK RTOS Building for information on setting up your build environment

openssl version

Compiling the SBL

To build all the SBL components:

cd <PDK>/packages/ti/boot/sbl/build
gmake clean all (for windows)
make clean all  (for Linux)

• SBL image files are be located at: <PDK>/packages/ti/boot/sbl/binary/
• SBL examples are located at <PDK>/packages/ti/boot/sbl/examples/k3MulticoreApp/binary
• SBL lib are located at <PDK>/packages/ti/boot/sbl/lib/

Compile time options for the SBL

The SBL supports several compile time options to tweak the SBL to satisfy requirements of ease of use, boot time and size. These can be enabled or disabled by editing sbl/sbl_component.mk

• SBL_LOG_LEVEL : Controls amount of SBL logs (on the MCU UART) and system firmware logs(on WAKEUP UART). Varies from 0(no logs) to 3 (all logs)
• SBL_USE_DMA : Valid values are 0 (use CPU to access boot media) or 1 (use DMA to access boot media).
• SBL_DISPLAY_PROFILE_INFO : At the end of the boot process, displays a log of timestamps at which different SBL profile points are hit. This is useful to see how much time the SBL spends in different functions. SBL_LOG_LEVEL can significantly affect performance numbers.
• SBL_ENABLE_PLL : Dials up all the PLLs calling Board_init(). Makes it easier for applications as they no longer have to initialize the PLLs. However, enabling this significantly increases boot time and power consumption. Requires system firmware to be loaded.
• SBL_ENABLE_CLOCKS : Enables all the module clocks by calling Board_init(). Makes it easier for applications as they no longer have to enable clocks.
• SBL_ENABLE_DDR : Initializes the DDR. At the cost of boot time, this enables applications to run from and use DDR. SBL_ENABLE_CLOCKS and SBL_ENABLE_PLL must also be enabed for this to work. Enabling this option increases the boot time.
• SBL_SKIP_MCU_RESET : Jumps to the MCU0 application entry point without resetting the core. Enables faster boot time. Will not change the MCU’s mode (lock-step/split). Application also inherits the MCU state as the SBL left it in.
• SBL_ENABLE_DEV_GRP_MCU : Will cause the system firmware to only use MCU domain resources during system firmware initialization. This can be dont either to support boot when the main power domain is off, or to save boot time.

The SBL also supports a “custom” build, in addition to standard out-of-box builds. A custom build is a useful way of testing out the effect of different build options - like when optimizing for boot time, or enabling custom usecases like eXecute In Place (XIP) to reduce memory usage.

For an example of how to use such custom builds, please refer to sbl/sbl_component.mk. It shows how to specify a select list of build options while building SBL images and libs.

SBL Startup

The SBL can specify the R5 configuration (lockstep or split) that ROM needs to use when it starts up the SBL. This info is passed to ROM as a field in the X509 certificate. The value in this field can be controlled by editing the build flag R5_STARTUP_MODE in sbl/build/sbl_img.mk

• EFUSE_DEFAULT : SBL will run with the same R5 configuration the boot rom ran in.
• SPLIT_MODE : ROM will switch the R5 to split mode before starting the SBL (default).

Enabling/Disabling JTAG on secure devices

JTAG access is controlled using a field in the X509 certificate.

By default, for an easy out of box experience, the Processor SDK enables debug via JTAG on High Secure devices. Leaving JTAG enabled, while making it easy for software development, creates a major security hole in production devices.

To disable/change the level of JTAG access on HS devices, update the value of the debugType field in the signing scripts build/makerules/x509template.txt (when building from windows) and build/makerules/x509CertificateGen.sh (when building from linux).

Valid values are

• 0 : Disable all JTAG access (most secure and most restrictive)
• 1 : Use device defaults (most secure and most restrictive)
• 2 : Allow debug of non-secure code, when the CPU is running in secure mode, JTAG connectivity will be lost
• 4 : Allow debug of both secure and non-secure code (least secure and least restrictive). This is the default.