module ti.sdo.ipc.Ipc
index URL

IPC Master Manager

This module has a common header that can be found in the ti.ipc package. Application code should include the common header file (not the RTSC-generated one): 
#include <ti/ipc/Ipc.h>
The RTSC module must be used in the application's RTSC configuration file (.cfg): 
Ipc = xdc.useModule('ti.sdo.ipc.Ipc');
Documentation for all runtime APIs, instance configuration parameters, error codes macros and type definitions available to the application integrator can be found in the Doxygen documenation for the IPC product. However, the documentation presented on this page should be referred to for information specific to the RTSC module, such as module configuration, Errors, and Asserts. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ipc/Ipc.xdc
#include <ti/sdo/ipc/Ipc.h>
Functions
Void 
Ipc_getEntry// Gets the properties for attaching to a remote processor(Ipc_Entry *entry);
Void 
Ipc_setEntry// Sets the properties for attaching to a remote processor(Ipc_Entry *entry);
Functions common to all target modules
Ipc_Module_getMask// Returns the diagnostics mask for this module, Ipc_Module_hasMask// Test whether this module has a diagnostics mask, Ipc_Module_heap// The heap from which this module allocates memory, Ipc_Module_id// Get this module's unique id, Ipc_Module_setMask// Set the diagnostics mask for this module, Ipc_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct
Ipc_Entry// Struct used for configuration via setEntryMeta ...
typedef enum
Ipc_ProcSync// Various configuration options for procSync ...
typedef struct
Ipc_UserFxn// struct for attach/detach plugs ...
Constants
extern const Assert_Id 
Ipc_A_addrNotCacheAligned// Assert raised when an address is not cache-aligned;
extern const Assert_Id 
Ipc_A_addrNotInSharedRegion// Assert raised when an address lies outside all known shared regions;
extern const Assert_Id 
Ipc_A_internal// Assert raised when an internal error is encountered;
extern const Assert_Id 
Ipc_A_invArgument// Assert raised when an argument is invalid;
extern const Assert_Id 
Ipc_A_invParam// Assert raised when a parameter is invalid;
extern const Assert_Id 
Ipc_A_nullArgument// Assert raised when a required argument is null;
extern const Assert_Id 
Ipc_A_nullPointer// Assert raised when a pointer is null;
extern const Error_Id 
Ipc_E_internal// Error raised when an internal error occured;
extern const Error_Id 
Ipc_E_nameFailed// Error raised when a name failed to be added to the NameServer;
extern const Error_Id 
Ipc_E_versionMismatch// Error raised when a version mismatch occurs;
extern const Ipc_ProcSync 
Ipc_procSync// Affects how Ipc_start and Ipc_attach behave;
 
DETAILS
This module has a common header that can be found in the ti.ipc package. Application code should include the common header file (not the RTSC-generated one): 
#include <ti/ipc/Ipc.h>
The RTSC module must be used in the application's RTSC configuration file (.cfg): 
Ipc = xdc.useModule('ti.sdo.ipc.Ipc');
Documentation for all runtime APIs, instance configuration parameters, error codes macros and type definitions available to the application integrator can be found in the Doxygen documenation for the IPC product. However, the documentation presented on this page should be referred to for information specific to the RTSC module, such as module configuration, Errors, and Asserts.
The most common static configuration that is required of the Ipc module is the procSync configuration that affects the behavior of the Ipc_start and Ipc_attach runtime APIs.
Additionally, certain subsystems of IPC (such as Notify and MessageQ) can be disabled to save resources on a per-connection basis by configuring Ipc using setEntryMeta.
 
enum Ipc_ProcSync
index URL

Various configuration options for procSync

C synopsis target-domain
typedef enum Ipc_ProcSync {
    Ipc_ProcSync_NONE,
    // ProcSync_PAIR with no synchronization
    Ipc_ProcSync_PAIR,
    // Ipc_start does not Ipc_attach
    Ipc_ProcSync_ALL
    // Ipc_start attach to all remote procs
} Ipc_ProcSync;
 
DETAILS
The values in this enum affect the behavior of the Ipc_start and Ipc_attach runtime APIs.
ProcSync_ALL: Calling Ipc_start will also internally Ipc_attach to each remote processor. The application should never call Ipc_attach. This type of startup and synchronization should be used if all IPC processors on a device start up at the same time and connections should be established between every possible pair of processors.
ProcSync_PAIR (default): Calling Ipc_start will perform system-wide IPC initialization required on all processor, but connections to remote processors will not be established (i.e. Ipc_attach will never be called). This configuration should be chosen if synchronization is required and some/all these conditions are true:
  • It is necessary 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 all remote processors are unnecessary and connections should selectively be made to save memory
NOTE: A connection should be made to the owner of region 0 (usually the processor with id = 0) before any connection to any other remote processor can be made. For example, if there are three processors configured with MultiProc, #1 should attach to #0 before it can attach to #2.
ProcSync_NONE: This should be selected with caution. Ipc_start will work exactly as it does with ProcSync_PAIR. However, Ipc_attach will not synchronize with the remote processor. Callers of Ipc_attach are bound by the same restrictions imposed by using ProcSync_PAIR. Additionally, an Ipc_attach to a remote processor whose id is less than our own has to occur *after* the corresponding remote processor has called attach to the original processor. For example, processor #2 can call
  Ipc_attach(1);
only after processor #1 has called:
  Ipc_attach(2);
 
struct Ipc_Entry
index URL

Struct used for configuration via setEntryMeta

C synopsis target-domain
typedef struct Ipc_Entry {
    UInt16 remoteProcId;
    // Remote processor id
    Bool setupNotify;
    // Whether to setup Notify
    Bool setupMessageQ;
    // Whether to setup MessageQ
} Ipc_Entry;
 
DETAILS
This structure defines the fields that are to be configured between the executing processor and a remote processor.
 
struct Ipc_UserFxn
index URL

struct for attach/detach plugs

C synopsis target-domain
typedef struct Ipc_UserFxn {
    Int (*attach)(UArg,UInt16);
    Int (*detach)(UArg,UInt16);
} Ipc_UserFxn;
 
 
config Ipc_A_addrNotCacheAligned  // module-wide
index URL

Assert raised when an address is not cache-aligned

C synopsis target-domain
extern const Assert_Id Ipc_A_addrNotCacheAligned;
 
 
config Ipc_A_addrNotInSharedRegion  // module-wide
index URL

Assert raised when an address lies outside all known shared regions

C synopsis target-domain
extern const Assert_Id Ipc_A_addrNotInSharedRegion;
 
 
config Ipc_A_internal  // module-wide
index URL

Assert raised when an internal error is encountered

C synopsis target-domain
extern const Assert_Id Ipc_A_internal;
 
 
config Ipc_A_invArgument  // module-wide
index URL

Assert raised when an argument is invalid

C synopsis target-domain
extern const Assert_Id Ipc_A_invArgument;
 
 
config Ipc_A_invParam  // module-wide
index URL

Assert raised when a parameter is invalid

C synopsis target-domain
extern const Assert_Id Ipc_A_invParam;
 
 
config Ipc_A_nullArgument  // module-wide
index URL

Assert raised when a required argument is null

C synopsis target-domain
extern const Assert_Id Ipc_A_nullArgument;
 
 
config Ipc_A_nullPointer  // module-wide
index URL

Assert raised when a pointer is null

C synopsis target-domain
extern const Assert_Id Ipc_A_nullPointer;
 
 
config Ipc_E_internal  // module-wide
index URL

Error raised when an internal error occured

C synopsis target-domain
extern const Error_Id Ipc_E_internal;
 
 
config Ipc_E_nameFailed  // module-wide
index URL

Error raised when a name failed to be added to the NameServer

C synopsis target-domain
extern const Error_Id Ipc_E_nameFailed;
 
DETAILS
Error raised in a create call when a name fails to be added to the NameServer table. This can be because the name already exists, the table has reached its max length, or out of memory.
 
config Ipc_E_versionMismatch  // module-wide
index URL

Error raised when a version mismatch occurs

C synopsis target-domain
extern const Error_Id Ipc_E_versionMismatch;
 
DETAILS
Error raised in an open call because there is a version mismatch between the opener and the creator
 
config Ipc_procSync  // module-wide
index URL

Affects how Ipc_start and Ipc_attach behave

C synopsis target-domain
extern const Ipc_ProcSync Ipc_procSync;
 
DETAILS
Refer to the documentation for the ProcSync enum for information about the various ProcSync options.
 
Ipc_getEntry()  // module-wide
index URL

Gets the properties for attaching to a remote processor

C synopsis target-domain
Void Ipc_getEntry(Ipc_Entry *entry);
 
ARGUMENTS
entry — Properties between a pair of processors.
DETAILS
This function must be called before Ipc_attach(). The parameter entry->remoteProcId field must be set prior to calling the function.
 
Ipc_setEntry()  // module-wide
index URL

Sets the properties for attaching to a remote processor

C synopsis target-domain
Void Ipc_setEntry(Ipc_Entry *entry);
 
ARGUMENTS
entry — Properties between a pair of processors.
DETAILS
This function must be called before Ipc_attach(). It allows the user to configure whether Notify and/or MessageQ is setup during Ipc_attach(). If 'setupNotify' is set to 'FALSE', neither the Notify or NameServerRemoteNotify instances are created. If 'setupMessageQ' is set to 'FALSE', the MessageQ transport instances are not created. By default, both flags are set to 'TRUE'.
Note: For any pair of processors, the flags must be the same
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Ipc_Module_id();
// Get this module's unique id
 
Bool Ipc_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Ipc_Module_heap();
// The heap from which this module allocates memory
 
Bool Ipc_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Ipc_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Ipc_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/sdo/ipc/Ipc.xdc
var Ipc = xdc.useModule('ti.sdo.ipc.Ipc');
module-wide constants & types
    values of type Ipc.ProcSync// Various configuration options for procSync
        const Ipc.ProcSync_NONE// ProcSync_PAIR with no synchronization;
        const Ipc.ProcSync_PAIR// Ipc_start does not Ipc_attach;
        const Ipc.ProcSync_ALL// Ipc_start attach to all remote procs;
 
    var obj = new Ipc.Entry// Struct used for configuration via setEntryMeta;
        obj.remoteProcId// Remote processor id = UInt16  ...
        obj.setupNotify// Whether to setup Notify = Bool  ...
        obj.setupMessageQ// Whether to setup MessageQ = Bool  ...
 
    var obj = new Ipc.UserFxn// struct for attach/detach plugs;
        obj.attach = Int(*)(UArg,UInt16)  ...
        obj.detach = Int(*)(UArg,UInt16)  ...
module-wide config parameters
    Ipc.A_addrNotCacheAligned// Assert raised when an address is not cache-aligned = Assert.Desc {
        msg: "A_addrNotCacheAligned: Address is not cache aligned"
    };
    Ipc.A_addrNotInSharedRegion// Assert raised when an address lies outside all known shared regions = Assert.Desc {
        msg: "A_addrNotInSharedRegion: Address not in any shared region"
    };
    Ipc.A_internal// Assert raised when an internal error is encountered = Assert.Desc {
        msg: "A_internal: An internal error has occurred"
    };
    Ipc.A_invArgument// Assert raised when an argument is invalid = Assert.Desc {
        msg: "A_invArgument: Invalid argument supplied"
    };
    Ipc.A_invParam// Assert raised when a parameter is invalid = Assert.Desc {
        msg: "A_invParam: Invalid configuration parameter supplied"
    };
    Ipc.A_nullArgument// Assert raised when a required argument is null = Assert.Desc {
        msg: "A_nullArgument: Required argument is null"
    };
    Ipc.A_nullPointer// Assert raised when a pointer is null = Assert.Desc {
        msg: "A_nullPointer: Pointer is null"
    };
    Ipc.E_internal// Error raised when an internal error occured = Error.Desc {
        msg: "E_internal: An internal error occurred"
    };
    Ipc.E_nameFailed// Error raised when a name failed to be added to the NameServer = Error.Desc {
        msg: "E_nameFailed: '%s' name failed to be added to NameServer"
    };
    Ipc.E_versionMismatch// Error raised when a version mismatch occurs = Error.Desc {
        msg: "E_versionMismatch: IPC Module version mismatch: creator: %d, opener: %d"
    };
    Ipc.procSync// Affects how Ipc_start and Ipc_attach behave = Ipc.ProcSync Ipc.ProcSync_PAIR;
 
    Ipc.common$// Common module configuration parameters = Types.Common$ undefined;
    Ipc.sr0MemorySetup// Whether Shared Region 0 memory is accessible = Bool undefined;
module-wide functions
    Ipc.addUserFxn// Add a function that gets called during Ipc_attach/detach(Ipc.UserFxn fxn, UArg arg) returns Void
    Ipc.setEntryMeta// Statically sets the properties for attaching to a remote processor(Ipc.Entry entry) returns Void
 
 
enum Ipc.ProcSync
index URL

Various configuration options for procSync

XDCscript usage meta-domain
values of type Ipc.ProcSync
    const Ipc.ProcSync_NONE;
    // ProcSync_PAIR with no synchronization
    const Ipc.ProcSync_PAIR;
    // Ipc_start does not Ipc_attach
    const Ipc.ProcSync_ALL;
    // Ipc_start attach to all remote procs
 
DETAILS
The values in this enum affect the behavior of the Ipc_start and Ipc_attach runtime APIs.
ProcSync_ALL: Calling Ipc_start will also internally Ipc_attach to each remote processor. The application should never call Ipc_attach. This type of startup and synchronization should be used if all IPC processors on a device start up at the same time and connections should be established between every possible pair of processors.
ProcSync_PAIR (default): Calling Ipc_start will perform system-wide IPC initialization required on all processor, but connections to remote processors will not be established (i.e. Ipc_attach will never be called). This configuration should be chosen if synchronization is required and some/all these conditions are true:
  • It is necessary 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 all remote processors are unnecessary and connections should selectively be made to save memory
NOTE: A connection should be made to the owner of region 0 (usually the processor with id = 0) before any connection to any other remote processor can be made. For example, if there are three processors configured with MultiProc, #1 should attach to #0 before it can attach to #2.
ProcSync_NONE: This should be selected with caution. Ipc_start will work exactly as it does with ProcSync_PAIR. However, Ipc_attach will not synchronize with the remote processor. Callers of Ipc_attach are bound by the same restrictions imposed by using ProcSync_PAIR. Additionally, an Ipc_attach to a remote processor whose id is less than our own has to occur *after* the corresponding remote processor has called attach to the original processor. For example, processor #2 can call
  Ipc_attach(1);
only after processor #1 has called:
  Ipc_attach(2);
C SYNOPSIS
Ipc_ProcSync
 
struct Ipc.Entry
index URL

Struct used for configuration via setEntryMeta

XDCscript usage meta-domain
var obj = new Ipc.Entry;
 
    obj.remoteProcId = UInt16  ...
    // Remote processor id
    obj.setupNotify = Bool  ...
    // Whether to setup Notify
    obj.setupMessageQ = Bool  ...
    // Whether to setup MessageQ
 
DETAILS
This structure defines the fields that are to be configured between the executing processor and a remote processor.
C SYNOPSIS
Ipc_Entry
 
struct Ipc.UserFxn
index URL

struct for attach/detach plugs

XDCscript usage meta-domain
var obj = new Ipc.UserFxn;
 
    obj.attach = Int(*)(UArg,UInt16)  ...
    obj.detach = Int(*)(UArg,UInt16)  ...
 
C SYNOPSIS
Ipc_UserFxn
 
config Ipc.A_addrNotCacheAligned  // module-wide
index URL

Assert raised when an address is not cache-aligned

XDCscript usage meta-domain
Ipc.A_addrNotCacheAligned = Assert.Desc {
    msg: "A_addrNotCacheAligned: Address is not cache aligned"
};
 
C SYNOPSIS
Ipc_A_addrNotCacheAligned
 
config Ipc.A_addrNotInSharedRegion  // module-wide
index URL

Assert raised when an address lies outside all known shared regions

XDCscript usage meta-domain
Ipc.A_addrNotInSharedRegion = Assert.Desc {
    msg: "A_addrNotInSharedRegion: Address not in any shared region"
};
 
C SYNOPSIS
Ipc_A_addrNotInSharedRegion
 
config Ipc.A_internal  // module-wide
index URL

Assert raised when an internal error is encountered

XDCscript usage meta-domain
Ipc.A_internal = Assert.Desc {
    msg: "A_internal: An internal error has occurred"
};
 
C SYNOPSIS
Ipc_A_internal
 
config Ipc.A_invArgument  // module-wide
index URL

Assert raised when an argument is invalid

XDCscript usage meta-domain
Ipc.A_invArgument = Assert.Desc {
    msg: "A_invArgument: Invalid argument supplied"
};
 
C SYNOPSIS
Ipc_A_invArgument
 
config Ipc.A_invParam  // module-wide
index URL

Assert raised when a parameter is invalid

XDCscript usage meta-domain
Ipc.A_invParam = Assert.Desc {
    msg: "A_invParam: Invalid configuration parameter supplied"
};
 
C SYNOPSIS
Ipc_A_invParam
 
config Ipc.A_nullArgument  // module-wide
index URL

Assert raised when a required argument is null

XDCscript usage meta-domain
Ipc.A_nullArgument = Assert.Desc {
    msg: "A_nullArgument: Required argument is null"
};
 
C SYNOPSIS
Ipc_A_nullArgument
 
config Ipc.A_nullPointer  // module-wide
index URL

Assert raised when a pointer is null

XDCscript usage meta-domain
Ipc.A_nullPointer = Assert.Desc {
    msg: "A_nullPointer: Pointer is null"
};
 
C SYNOPSIS
Ipc_A_nullPointer
 
config Ipc.E_internal  // module-wide
index URL

Error raised when an internal error occured

XDCscript usage meta-domain
Ipc.E_internal = Error.Desc {
    msg: "E_internal: An internal error occurred"
};
 
C SYNOPSIS
Ipc_E_internal
 
config Ipc.E_nameFailed  // module-wide
index URL

Error raised when a name failed to be added to the NameServer

XDCscript usage meta-domain
Ipc.E_nameFailed = Error.Desc {
    msg: "E_nameFailed: '%s' name failed to be added to NameServer"
};
 
DETAILS
Error raised in a create call when a name fails to be added to the NameServer table. This can be because the name already exists, the table has reached its max length, or out of memory.
C SYNOPSIS
Ipc_E_nameFailed
 
config Ipc.E_versionMismatch  // module-wide
index URL

Error raised when a version mismatch occurs

XDCscript usage meta-domain
Ipc.E_versionMismatch = Error.Desc {
    msg: "E_versionMismatch: IPC Module version mismatch: creator: %d, opener: %d"
};
 
DETAILS
Error raised in an open call because there is a version mismatch between the opener and the creator
C SYNOPSIS
Ipc_E_versionMismatch
 
config Ipc.procSync  // module-wide
index URL

Affects how Ipc_start and Ipc_attach behave

XDCscript usage meta-domain
Ipc.procSync = Ipc.ProcSync Ipc.ProcSync_PAIR;
 
DETAILS
Refer to the documentation for the ProcSync enum for information about the various ProcSync options.
C SYNOPSIS
Ipc_procSync
 
metaonly config Ipc.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Ipc.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
 
metaonly config Ipc.sr0MemorySetup  // module-wide
index URL

Whether Shared Region 0 memory is accessible

XDCscript usage meta-domain
Ipc.sr0MemorySetup = Bool undefined;
 
DETAILS
Certain devices have a slave MMU that needs to be configured by the host core before the slave core can access shared region 0. If the host core is also running BIOS, it is necessary to set this configuration to 'true', otherwise start will always fail.
This configuration should not be used for devices that don't have a slave MMU and don't run Linux.
 
metaonly Ipc.addUserFxn()  // module-wide
index URL

Add a function that gets called during Ipc_attach/detach

XDCscript usage meta-domain
Ipc.addUserFxn(Ipc.UserFxn fxn, UArg arg) returns Void
 
ARGUMENTS
fxn — The user function to call during attach/detach.
arg — The argument to the function.
DETAILS
The user added functions must be non-blocking and must run to completion. The functions need to check to make sure it is not called multiple times when more than one thread calls Ipc_attach() for the same processor. It is safe to use IPC APIs in a user function as long as the IPC APIs satisfy these requirements.
      var Ipc = xdc.useModule('ti.sdo.ipc.Ipc');
      var fxn = new Ipc.UserFxn;
      fxn.attach = '&userAttachFxn';
      fxn.detach = '&userDetachFxn';
      Ipc.addUserFxn(fxn, arg);
 
metaonly Ipc.setEntryMeta()  // module-wide
index URL

Statically sets the properties for attaching to a remote processor

XDCscript usage meta-domain
Ipc.setEntryMeta(Ipc.Entry entry) returns Void
 
ARGUMENTS
entry — Properties between a pair of processors.
DETAILS
This function allows the user to configure whether Notify and/or MessageQ is setup during Ipc_attach(). If 'setupNotify' is set to 'false', neither the Notify or NameServerRemoteNotify instances are created. If 'setupMessageQ' is set to 'false', the MessageQ transport instances are not created. By default, both flags are set to 'true'.
Note: For any pair of processors, the flags must be the same
generated on Sat, 11 Feb 2012 00:38:09 GMT