IPC API  3.40.00.06
Data Structures | Macros | Functions
Ipc.h File Reference

Detailed Description

Ipc Manager.

This module is primarily used to configure IPC, synchronize processors, and initialize the IPC runtime.

On SYS/BIOS, the memory for SharedRegion zero must be valid before Ipc_start() can be called. Ipc_start() must be called before any other IPC APIs are used.

The Ipc header should be included in an application as follows:

#include <ti/ipc/Ipc.h>

Go to the source code of this file.

Data Structures

struct  Ipc_TransportFactoryFxns
 Factory virtual function table. More...
 

Macros

#define Ipc_S_BUSY   (2)
 The resource is still in use. More...
 
#define Ipc_S_ALREADYSETUP   (1)
 The module has been already setup. More...
 
#define Ipc_S_SUCCESS   (0)
 Operation is successful. More...
 
#define Ipc_E_FAIL   (-1)
 Generic failure. More...
 
#define Ipc_E_INVALIDARG   (-2)
 Argument passed to function is invalid. More...
 
#define Ipc_E_MEMORY   (-3)
 Operation resulted in memory failure. More...
 
#define Ipc_E_ALREADYEXISTS   (-4)
 The specified entity already exists. More...
 
#define Ipc_E_NOTFOUND   (-5)
 Unable to find the specified entity. More...
 
#define Ipc_E_TIMEOUT   (-6)
 Operation timed out. More...
 
#define Ipc_E_INVALIDSTATE   (-7)
 Module is not initialized or in an invalid state. More...
 
#define Ipc_E_OSFAILURE   (-8)
 A failure occurred in an OS-specific call. More...
 
#define Ipc_E_RESOURCE   (-9)
 Specified resource is not available. More...
 
#define Ipc_E_RESTART   (-10)
 Operation was interrupted. Please restart the operation. More...
 
#define Ipc_E_NOTREADY   (-11)
 Operation was not ready. More...
 

Functions

Int Ipc_attach (UInt16 remoteProcId)
 Attach to remote processor. More...
 
Int Ipc_clusterConfig (Void)
 Internal IPC cluster configuration. More...
 
Int Ipc_detach (UInt16 remoteProcId)
 Detach from the remote processor. More...
 
Bool Ipc_isAttached (UInt16 remoteProcId)
 Query whether attached to a remote processor. More...
 
Int Ipc_readConfig (UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size)
 Reads the config entry from the config area. More...
 
Int Ipc_start (Void)
 Reserves memory, creates default GateMP and HeapMemMP. More...
 
Int Ipc_stop (Void)
 Resets the Ipc state. More...
 
Int Ipc_transportConfig (Ipc_TransportFactoryFxns *factory)
 Configure the primary transport factory. More...
 
Int Ipc_writeConfig (UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size)
 Writes the config entry to the config area. More...
 

Macro Definition Documentation

#define Ipc_S_BUSY   (2)

The resource is still in use.

#define Ipc_S_ALREADYSETUP   (1)

The module has been already setup.

#define Ipc_S_SUCCESS   (0)

Operation is successful.

#define Ipc_E_FAIL   (-1)

Generic failure.

#define Ipc_E_INVALIDARG   (-2)

Argument passed to function is invalid.

#define Ipc_E_MEMORY   (-3)

Operation resulted in memory failure.

#define Ipc_E_ALREADYEXISTS   (-4)

The specified entity already exists.

#define Ipc_E_NOTFOUND   (-5)

Unable to find the specified entity.

#define Ipc_E_TIMEOUT   (-6)

Operation timed out.

#define Ipc_E_INVALIDSTATE   (-7)

Module is not initialized or in an invalid state.

#define Ipc_E_OSFAILURE   (-8)

A failure occurred in an OS-specific call.

#define Ipc_E_RESOURCE   (-9)

Specified resource is not available.

#define Ipc_E_RESTART   (-10)

Operation was interrupted. Please restart the operation.

#define Ipc_E_NOTREADY   (-11)

Operation was not ready.

Function Documentation

Int Ipc_attach ( UInt16  remoteProcId)

Attach to remote processor.

Note
This function is currently only supported on SYS/BIOS.

This function synchronizes with the remote processor, typically via shared memory. Both processors must call this function to attach to each other. Ipc_start() must be called before calling Ipc_attach(). A processor must attach to the owner of SharedRegion zero before it can successfully attach to another processor. Attempting to attach to another processor first returns Ipc_E_FAIL.

This function opens the default GateMP and SharedRegion zero heap. The Notify, NameServerRemoteNotify, and MessageQ transport instances are created for communicating with the specified remote processor in SharedRegion zero heap. The user's Ipc attach function is called.

On SYS/BIOS, this function should be called within a 'while' loop within a Task. A Task_sleep() or Task_yield() should be called within the loop to allow other threads in the system to execute. This function needs to be called in a loop because the remote processor may not be in a ready state.

Note
For SYS/BIOS, if the config parameter Ipc.procSync is set to Ipc.ProcSync_ALL, there is no need to call this function as it is internally called by Ipc_start().
1 while (Ipc_attach(remoteProcId) < 0) {
2  Task_sleep(1);
3 }
Parameters
remoteProcIdremote processor's MultiProc id
Returns
Status
See also
Ipc_detach()
Ipc_isAttached()
Int Ipc_clusterConfig ( Void  )

Internal IPC cluster configuration.

Perform run-time configuration of internal data structures related to cluster baseId. This function should be called from a "startup first" hook but after having called MultiProc_setBaseIdOfCluster().

Remarks
This function is only available on SYS/BIOS.
Int Ipc_detach ( UInt16  remoteProcId)

Detach from the remote processor.

Note
This function is currently only supported on SYS/BIOS.

A processor must detach from all other processors before it can successfully detach from the owner of SharedRegion zero. Attempting to detach from the owner of SharedRegion zero first returns Ipc_E_FAIL.

If a processor successfully attached to a remote processor 'N' times, it must call Ipc_detach 'N' times to be completely detached. Ipc_detach returns Ipc_S_BUSY for the first 'N - 1' times its called. Ipc_detach returns Ipc_S_SUCCESS, if successful, on the 'N' time its called. If called on a remote processor that is detached, Ipc_S_SUCCESS is returned.

This function should be called within a loop to make sure the processor successfully detached from the remote processor. If called from the processor with the bigger procId, this function closes the instances created for communicating with the specified remote processor. If called from the processor with the smaller procId, this function returns Ipc_E_NOTREADY while the processor with the bigger procId has not finished detaching. Once the processor with the bigger procId is finished detaching, this function deletes the instances created for communicating with the specified remote processor.

For SYS/BIOS, this function should be called within a 'while' loop in a Task because the slave may have to wait for the master to detach. Furthermore, a Task_sleep() or Task_yield() should be called within the same 'while' loop to allow other threads in the system to execute.

1 while (TRUE) {
2  status = Ipc_detach(remoteProcId);
3  if (status == Ipc_E_NOTREADY) {
4  Task_sleep(1);
5  }
6  else if (status < 0) {
7  System_printf("Ipc_detach failed \n");
8  break;
9  }
10  else {
11  break;
12  }
13 }
Parameters
remoteProcIdremote processor's MultiProc id
Returns
Status
See also
Ipc_attach()
Ipc_isAttached()
Bool Ipc_isAttached ( UInt16  remoteProcId)

Query whether attached to a remote processor.

Note
This function is currently only supported on SYS/BIOS.
Parameters
remoteProcIdremote processor's MultiProc id
Returns
TRUE if attached, FALSE if not attached
Remarks
If remoteProcId == MultiProc_self(), FALSE is always returned.
See also
Ipc_attach()
Ipc_detach()
Int Ipc_readConfig ( UInt16  remoteProcId,
UInt32  tag,
Ptr  cfg,
SizeT  size 
)

Reads the config entry from the config area.

Note
This function is currently only supported on SYS/BIOS.

For more information about this API, refer to the documentation for Ipc_writeConfig()

Parameters
remoteProcIdremote processor's MultiProc id
tagtag to identify a config entry
cfgaddress where the entry will be copied
sizesize of config entry
Returns
Status
See also
Ipc_writeConfig
Int Ipc_start ( Void  )

Reserves memory, creates default GateMP and HeapMemMP.

This function needs to be called before Ipc_attach(). It should only be called once, unless the return value is Ipc_E_NOTREADY. This indicates that either the SharedRegion zero is not valid or has not been setup yet so Ipc_start may be called again. Once successfully started, subsequent calls returns Ipc_S_ALREADYSETUP.

Ipc reserves some shared memory in SharedRegion zero for synchronization. GateMP reserves some shared memory for managing the gates and for the default GateMP. The same amount of memory must be reserved by each processor, but only the owner of SharedRegion zero clears the reserved memory and creates the default GateMP. The default heap for each SharedRegion is created by the owner of each SharedRegion.

Note
For SYS/BIOS, if the config parameter Ipc.procSync is set to Ipc.ProcSync_ALL, this function calls Ipc_attach() internally.
Returns
Status
See also
Ipc_stop()
Int Ipc_stop ( Void  )

Resets the Ipc state.

This function should be called only once and only after detaching from all processors. Once called, Ipc is placed back to the same state as it was before Ipc_start() was called.

Returns
Status
See also
Ipc_start()
Int Ipc_transportConfig ( Ipc_TransportFactoryFxns factory)

Configure the primary transport factory.

Configure IPC with the factory to use for the primary transport The transport factory will be invoked by IPC during the start phase (i.e. Ipc_start()) to create the transport instances. IPC will also use the factory during the stop phase (i.e. Ipc_stop()) to finalize the transport instances.

By configuring the transport factory at run-time, the application is able to pick which transport implementation will be used. It is expected that each transport implementation provides a suitable factory for use by the application.

This function is only available on Linux systems.

Returns
Status
Int Ipc_writeConfig ( UInt16  remoteProcId,
UInt32  tag,
Ptr  cfg,
SizeT  size 
)

Writes the config entry to the config area.

Note
This function is currently only supported on SYS/BIOS.

Ipc_writeConfig() and Ipc_readConfig() are used to pass configuration information from one core to another. This 'information' is passed via a pointer to shared memory with a given size and is identified via a unique tag. A typical use case of this API would be passing configuration information at startup-time. For example, if MessageQ is used, this information might include the queue name, message heap sizes, etc.

For Ipc_writeConfig(), if 'NULL' is passed in for the cfg parameter, it attempts to free the shared memory that is allocated by a previous Ipc_writeConfig() call. The remoteProcId, tag, and size must match the previous Ipc_writeConfig() call.

Ipc_writeConfig() writes into SharedRegion 0 (SR0) and uses tag to uniquely identify the structure (cfg) and size written into SR0 which both sides must agree on.

Parameters
remoteProcIdremote processor's MultiProc id
tagtag to identify a config entry
cfgaddress where the entry will be copied
sizesize of config entry
Returns
Status
See also
Ipc_readConfig()
Copyright 2015, Texas Instruments Incorporated