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 ... ]
#include <ti/sdo/ipc/Ipc.h>
Functions |
Void | |
Void | |
Functions common to all target modules |
|
|
Typedefs |
typedef struct | |
typedef enum | |
typedef struct | |
Constants |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
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 |
|
Various configuration options for procSync
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
only after processor #1 has called:
struct Ipc_Entry |
|
Struct used for configuration via setEntryMeta
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 |
|
struct for attach/detach plugs
typedef struct Ipc_UserFxn {
Int (*attach)(UArg,UInt16);
Int (*detach)(UArg,UInt16);
} Ipc_UserFxn;
config Ipc_A_addrNotCacheAligned // module-wide |
|
Assert raised when an address is not cache-aligned
extern const Assert_Id Ipc_A_addrNotCacheAligned;
config Ipc_A_addrNotInSharedRegion // module-wide |
|
Assert raised when an address lies outside all known shared regions
extern const Assert_Id Ipc_A_addrNotInSharedRegion;
config Ipc_A_internal // module-wide |
|
Assert raised when an internal error is encountered
config Ipc_A_invArgument // module-wide |
|
Assert raised when an argument is invalid
config Ipc_A_invParam // module-wide |
|
Assert raised when a parameter is invalid
config Ipc_A_nullArgument // module-wide |
|
Assert raised when a required argument is null
config Ipc_A_nullPointer // module-wide |
|
Assert raised when a pointer is null
config Ipc_E_internal // module-wide |
|
Error raised when an internal error occured
config Ipc_E_nameFailed // module-wide |
|
Error raised when a name failed to be added to the 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.
config Ipc_E_versionMismatch // module-wide |
|
Error raised when a version mismatch occurs
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 |
|
Affects how Ipc_start and Ipc_attach behave
DETAILS
Refer to the documentation for the
ProcSync enum for
information about the various ProcSync options.
Ipc_getEntry() // module-wide |
|
Gets the properties for attaching to a remote processor
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 |
|
Sets the properties for attaching to a remote processor
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 |
|
// Get this module's unique id
Bool Ipc_Module_startupDone();
// Test if this module has completed startup
// 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
var Ipc = xdc.useModule('ti.sdo.ipc.Ipc');
module-wide constants & types
obj.
attach =
Int(*)(UArg,UInt16) ...
obj.
detach =
Int(*)(UArg,UInt16) ...
module-wide config parameters
msg: "A_addrNotCacheAligned: Address is not cache aligned"
};
msg: "A_addrNotInSharedRegion: Address not in any shared region"
};
msg: "A_internal: An internal error has occurred"
};
msg: "A_invArgument: Invalid argument supplied"
};
msg: "A_invParam: Invalid configuration parameter supplied"
};
msg: "A_nullArgument: Required argument is null"
};
msg: "A_nullPointer: Pointer is null"
};
msg: "E_internal: An internal error occurred"
};
msg: "E_nameFailed: '%s' name failed to be added to NameServer"
};
msg: "E_versionMismatch: IPC Module version mismatch: creator: %d, opener: %d"
};
module-wide functions
enum Ipc.ProcSync |
|
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
only after processor #1 has called:
C SYNOPSIS
struct Ipc.Entry |
|
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
struct Ipc.UserFxn |
|
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
config Ipc.A_addrNotCacheAligned // module-wide |
|
Assert raised when an address is not cache-aligned
XDCscript usage |
meta-domain |
msg: "A_addrNotCacheAligned: Address is not cache aligned"
};
C SYNOPSIS
config Ipc.A_addrNotInSharedRegion // module-wide |
|
Assert raised when an address lies outside all known shared regions
XDCscript usage |
meta-domain |
msg: "A_addrNotInSharedRegion: Address not in any shared region"
};
C SYNOPSIS
config Ipc.A_internal // module-wide |
|
Assert raised when an internal error is encountered
XDCscript usage |
meta-domain |
msg: "A_internal: An internal error has occurred"
};
C SYNOPSIS
config Ipc.A_invArgument // module-wide |
|
Assert raised when an argument is invalid
XDCscript usage |
meta-domain |
msg: "A_invArgument: Invalid argument supplied"
};
C SYNOPSIS
config Ipc.A_invParam // module-wide |
|
Assert raised when a parameter is invalid
XDCscript usage |
meta-domain |
msg: "A_invParam: Invalid configuration parameter supplied"
};
C SYNOPSIS
config Ipc.A_nullArgument // module-wide |
|
Assert raised when a required argument is null
XDCscript usage |
meta-domain |
msg: "A_nullArgument: Required argument is null"
};
C SYNOPSIS
config Ipc.A_nullPointer // module-wide |
|
Assert raised when a pointer is null
XDCscript usage |
meta-domain |
msg: "A_nullPointer: Pointer is null"
};
C SYNOPSIS
config Ipc.E_internal // module-wide |
|
Error raised when an internal error occured
XDCscript usage |
meta-domain |
msg: "E_internal: An internal error occurred"
};
C SYNOPSIS
config Ipc.E_nameFailed // module-wide |
|
Error raised when a name failed to be added to the NameServer
XDCscript usage |
meta-domain |
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
config Ipc.E_versionMismatch // module-wide |
|
Error raised when a version mismatch occurs
XDCscript usage |
meta-domain |
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
config Ipc.procSync // module-wide |
|
Affects how Ipc_start and Ipc_attach behave
XDCscript usage |
meta-domain |
DETAILS
Refer to the documentation for the
ProcSync enum for
information about the various ProcSync options.
C SYNOPSIS
metaonly config Ipc.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
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 |
|
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 |
|
Add a function that gets called during Ipc_attach/detach
XDCscript usage |
meta-domain |
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 |
|
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 Tue, 22 May 2012 23:45:03 GMT