The MessageQ module supports the structured sending and receiving of
variable length messages. This module can be used for homogeneous
(DSP to DSP) or heterogeneous (Arm to DSP) multi-processor messaging.
MessageQ provides more sophisticated messaging than other modules. It is
typically used for complex situations such as multi-processor messaging.
Messages are sent and received by being placed on and removed from a
message queue. A reader is a thread that gets (reads) messages from a
message queue. A writer is a thread that puts (writes) a message to a
message queue. Each message queue has one reader and can have many writers.
A thread may read from or write to multiple message queues.
Conceptually, the reader thread owns a message queue. The reader thread
creates a message queue. The writer threads open a created message queue
to get access to them.
Messages must be allocated from the MessageQ module. Once a message is
allocated, it can be sent to any message queue. Once a message is sent, the
writer loses ownership of the message and should not attempt to modify the
message. Once the reader receives the message, it owns the message. It
may either free the message or re-use the message.
The MessageQ API uses the MessageQ_MsgHeader internally. Your application
should not modify or directly access the fields in the MessageQ_MsgHeader.
An application can use multiple heaps. The purpose of having multiple
heaps is to allow an application to regulate its message usage. For
example, an application can allocate critical messages from one heap of fast
on-chip memory and non-critical messages from another heap of slower
external memory.
const MessageQ_ANY |
|
Denotes any queueId is acceptable
#define MessageQ_ANY (Bits16)~(0)
DETAILS
This constant is the default for the
queueId parameter.
This value must match ti/ipc/MessageQ.h but is needed to initialize
queueId.
const MessageQ_HIGHPRI |
|
#define MessageQ_HIGHPRI (UInt)1
const MessageQ_NORMALPRI |
|
Message priority values. These must match the values defined in
ti/ipc/MessageQ.h but are needed here for ROV
#define MessageQ_NORMALPRI (UInt)0
const MessageQ_RESERVEDPRI |
|
#define MessageQ_RESERVEDPRI (UInt)2
const MessageQ_URGENTPRI |
|
#define MessageQ_URGENTPRI (UInt)3
typedef MessageQ_FreeHookFxn |
|
Function prototype for the MessageQ_free callback
typedef Void (*MessageQ_FreeHookFxn)(Bits16,Bits16);
VALUES
Bits16
heapId of message that was freed
msgId of message that was freed
typedef MessageQ_PutHookFxn |
|
Function prototype for the MessageQ_put callback
typedef Void (*MessageQ_PutHookFxn)(Bits32,Ptr);
VALUES
Bits32
queueId of the destination message queue
Ptr
pointer to a message header structure
typedef MessageQ_QueueId |
|
MessageQ ID
typedef UInt32 MessageQ_QueueId;
config MessageQ_A_cannotFreeStaticMsg // module-wide |
|
Assert raised when attempting to free a static message
extern const Assert_Id MessageQ_A_cannotFreeStaticMsg;
config MessageQ_A_heapIdInvalid // module-wide |
|
Assert raised when using an invalid heapId
extern const Assert_Id MessageQ_A_heapIdInvalid;
config MessageQ_A_invalidContext // module-wide |
|
Assert raised when calling API with wrong handle
extern const Assert_Id MessageQ_A_invalidContext;
DETAILS
Some APIs can only be called with an opened handle (e.g.
close. Some can only be called with a created handle
(e.g.
get).
config MessageQ_A_invalidMsg // module-wide |
|
Assert raised when an invalid message is supplied
extern const Assert_Id MessageQ_A_invalidMsg;
config MessageQ_A_invalidObj // module-wide |
|
Assert raised for an invalid MessageQ object
extern const Assert_Id MessageQ_A_invalidObj;
config MessageQ_A_invalidParam // module-wide |
|
Assert raised for an invalid parameter
extern const Assert_Id MessageQ_A_invalidParam;
config MessageQ_A_invalidQueueId // module-wide |
|
Assert raised when an invalid queueId is supplied
extern const Assert_Id MessageQ_A_invalidQueueId;
config MessageQ_A_invalidUnblock // module-wide |
|
Assert raised when attempting to unblock a remote MessageQ or one that
has been configured with a non-blocking synchronizer
extern const Assert_Id MessageQ_A_invalidUnblock;
config MessageQ_A_procIdInvalid // module-wide |
|
Assert raised when using an invalid procId
extern const Assert_Id MessageQ_A_procIdInvalid;
config MessageQ_A_unregisteredTransport // module-wide |
|
Assert raised when attempting to send a message to a core
where a transport has not been registered
extern const Assert_Id MessageQ_A_unregisteredTransport;
config MessageQ_E_indexNotAvailable // module-wide |
|
Error raised if the requested queueIndex is not available
extern const Error_Id MessageQ_E_indexNotAvailable;
config MessageQ_E_maxReached // module-wide |
|
Error raised if all the message queue objects are taken
extern const Error_Id MessageQ_E_maxReached;
config MessageQ_E_nameFailed // module-wide |
|
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
extern const Error_Id MessageQ_E_nameFailed;
config MessageQ_E_unregisterHeapId // module-wide |
|
Error raised when heapId has not been registered
extern const Error_Id MessageQ_E_unregisterHeapId;
config MessageQ_LM_alloc // module-wide |
|
Logged when allocating a message
DETAILS
When the
traceFlag is true, all message allocations
are logged.
config MessageQ_LM_free // module-wide |
|
Logged when freeing a message
DETAILS
When the
traceFlag is true, all freeing of messages
are logged. If an individual message's tracing was enabled
via
setMsgTrace, the MessageQ_free is also logged.
config MessageQ_LM_get // module-wide |
|
Logged when a message is received off the queue
DETAILS
When the
traceFlag is true, all getting of messages
are logged. If an individual message's tracing
was enabled via
setMsgTrace, the MessageQ_get is
also logged.
config MessageQ_LM_putLocal // module-wide |
|
Logged when a message is placed onto a local queue
DETAILS
When the
traceFlag is true, all putting of messages
are logged. If an individual message's tracing was enabled
via
setMsgTrace, the MessageQ_put is also logged.
config MessageQ_LM_putRemote // module-wide |
|
Logged when a message is given to a transport
extern const Log_Event MessageQ_LM_putRemote;
DETAILS
When the
traceFlag is true, all putting of messages
to a transport are logged. If an individual message's tracing
was enabled via
setMsgTrace, the MessageQ_put is
also logged.
config MessageQ_LM_rcvByTransport // module-wide |
|
Logged when a transport receives an incoming message
extern const Log_Event MessageQ_LM_rcvByTransport;
DETAILS
When the
traceFlag is true, all incoming messages
are logged. If an individual message's tracing
was enabled via
setMsgTrace, the receiving of a message is
also logged.
config MessageQ_LM_setTrace // module-wide |
|
Logged when setting the trace flag on a message
DETAILS
This is logged when tracing on a message is set via
setMsgTrace.
config MessageQ_LM_staticMsgInit // module-wide |
|
Logged when statically initializing a message
extern const Log_Event MessageQ_LM_staticMsgInit;
DETAILS
When the
traceFlag is true, all messages that
are statically initialized via
staticMsgInit are logged.
config MessageQ_freeHookFxn // module-wide |
|
Free function in MessageQ_free after message was freed back to the heap
config MessageQ_maxNameLen // module-wide |
|
Maximum length for Message queue names
extern const UInt MessageQ_maxNameLen;
config MessageQ_maxRuntimeEntries // module-wide |
|
Maximum number of MessageQs that can be dynamically created
extern const UInt MessageQ_maxRuntimeEntries;
config MessageQ_nameTableGate // module-wide |
|
Gate used to make the name table thread safe
DETAILS
This gate is used when accessing the name table during
a
create,
delete, and
open.
This gate is also used to protect MessageQ when growing
internal tables in the
create.
The table is in local memory, not shared memory. So a
single processor gate will work.
The default will be
xdc.runtime.knl.GateThread
instance.
config MessageQ_numHeaps // module-wide |
|
Number of heapIds in the system
extern const UInt16 MessageQ_numHeaps;
DETAILS
This allows MessageQ to pre-allocate the heaps table.
The heaps table is used when registering heaps.
There is no default heap, so unless the system is only using
staticMsgInit, the application must register a heap.
config MessageQ_numReservedEntries // module-wide |
|
Number of reserved MessageQ indexes
extern const UInt MessageQ_numReservedEntries;
DETAILS
An application can request the first N message queue indexes be
reserved to be used by MessageQ_create2. MessageQ_create will
not use these slots. The application can use any index less than
the value of numReservedEntries for the queueIndex field in the
MessageQ_Params2 structure.
numReservedEntries must be equal or less than
maxRuntimeEntries.
config MessageQ_putHookFxn // module-wide |
|
Put function hook
config MessageQ_traceFlag // module-wide |
|
Trace setting
extern const Bool MessageQ_traceFlag;
DETAILS
This flag allows the configuration of the default module trace
settings.
MessageQ_registerTransport() // module-wide |
|
Register a transport with MessageQ
ARGUMENTS
transport
transport to register
procId
MultiProc id that transport communicates with
priority
priority of transport
RETURNS
Whether the register was successful.
DETAILS
This API is called by the transport when it is created.
MessageQ_unregisterTransport() // module-wide |
|
Unregister a transport with MessageQ
Void MessageQ_unregisterTransport(UInt16 procId, UInt priority);
ARGUMENTS
procId
unregister transport that communicates with
this remote processor
priority
priority of transport
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool MessageQ_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool MessageQ_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 MessageQ_Module_getMask();
// Returns the diagnostics mask for this module
Void MessageQ_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct MessageQ_Object MessageQ_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct MessageQ_Struct MessageQ_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct MessageQ_Params {
// Instance config-params structure
// Common per-instance configs
UInt16 queueIndex;
// Requested MessageQ_QueueIndex
// ISync handle used to signal IO completion
} MessageQ_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config MessageQ_Params.queueIndex // instance |
|
Requested MessageQ_QueueIndex
DETAILS
This parameter allows an application to specify the queueIndex to
be used for a message queue. To use this functionality, the
MessageQ.numReservedEntries static configuration parameter must be
set to a specific value.
The default is
ANY. This means do that you are not asking for
an explicit index. MessageQ will find the first available one which is
equal or greater than MessageQ.numReservedEntries.
config MessageQ_Params.synchronizer // instance |
|
ISync handle used to signal IO completion
DETAILS
The ISync instance is used in the
get and
put.
The
xdc.runtime.knl.ISync.signal is called as part
of the
put call. The
xdc.runtime.knl.ISync.wait is
called in the
get if there are no messages present.
Instance Built-Ins |
|
Int MessageQ_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
proxy MessageQ.SetupTransportProxy |
|
MessageQ transport setup proxy
// explicit access to the currently bound delegate module
const MessageQ.ANY |
|
Denotes any queueId is acceptable
const MessageQ.ANY = ~(0);
DETAILS
This constant is the default for the
queueId parameter.
This value must match ti/ipc/MessageQ.h but is needed to initialize
queueId.
C SYNOPSIS
const MessageQ.HIGHPRI |
|
const MessageQ.HIGHPRI = 1;
C SYNOPSIS
const MessageQ.NORMALPRI |
|
Message priority values. These must match the values defined in
ti/ipc/MessageQ.h but are needed here for ROV
const MessageQ.NORMALPRI = 0;
C SYNOPSIS
const MessageQ.RESERVEDPRI |
|
const MessageQ.RESERVEDPRI = 2;
C SYNOPSIS
const MessageQ.URGENTPRI |
|
const MessageQ.URGENTPRI = 3;
C SYNOPSIS
config MessageQ.A_cannotFreeStaticMsg // module-wide |
|
Assert raised when attempting to free a static message
msg: "A_cannotFreeStaticMsg: Cannot call MessageQ_free with static msg"
};
C SYNOPSIS
config MessageQ.A_heapIdInvalid // module-wide |
|
Assert raised when using an invalid heapId
msg: "A_heapIdInvalid: heapId is invalid"
};
C SYNOPSIS
config MessageQ.A_invalidContext // module-wide |
|
Assert raised when calling API with wrong handle
msg: "A_invalidContext: Cannot call with an open/create handle"
};
DETAILS
Some APIs can only be called with an opened handle (e.g.
close. Some can only be called with a created handle
(e.g.
get).
C SYNOPSIS
config MessageQ.A_invalidMsg // module-wide |
|
Assert raised when an invalid message is supplied
msg: "A_invalidMsg: Invalid message"
};
C SYNOPSIS
config MessageQ.A_invalidObj // module-wide |
|
Assert raised for an invalid MessageQ object
msg: "A_invalidObj: an invalid obj is used"
};
C SYNOPSIS
config MessageQ.A_invalidParam // module-wide |
|
Assert raised for an invalid parameter
msg: "A_invalidParam: an invalid parameter was passed in"
};
C SYNOPSIS
config MessageQ.A_invalidQueueId // module-wide |
|
Assert raised when an invalid queueId is supplied
msg: "A_invalidQueueId: Invalid queueId is used"
};
C SYNOPSIS
config MessageQ.A_invalidUnblock // module-wide |
|
Assert raised when attempting to unblock a remote MessageQ or one that
has been configured with a non-blocking synchronizer
msg: "A_invalidUnblock: Trying to unblock a remote MessageQ or a queue with non-blocking synchronizer"
};
C SYNOPSIS
config MessageQ.A_procIdInvalid // module-wide |
|
Assert raised when using an invalid procId
msg: "A_procIdInvalid: procId is invalid"
};
C SYNOPSIS
config MessageQ.A_unregisteredTransport // module-wide |
|
Assert raised when attempting to send a message to a core
where a transport has not been registered
msg: "A_unregisteredTransport: transport is not registered"
};
C SYNOPSIS
config MessageQ.E_indexNotAvailable // module-wide |
|
Error raised if the requested queueIndex is not available
msg: "E_indexNotAvailable: queueIndex %d not available"
};
C SYNOPSIS
config MessageQ.E_maxReached // module-wide |
|
Error raised if all the message queue objects are taken
msg: "E_maxReached: All objects in use. MessageQ.maxRuntimeEntries is %d"
};
C SYNOPSIS
config MessageQ.E_nameFailed // module-wide |
|
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
msg: "E_nameFailed: '%s' name failed to be added to NameServer"
};
C SYNOPSIS
config MessageQ.E_unregisterHeapId // module-wide |
|
Error raised when heapId has not been registered
msg: "E_unregisterHeapId: Heap id %d not registered"
};
C SYNOPSIS
config MessageQ.LM_alloc // module-wide |
|
Logged when allocating a message
msg: "LM_alloc: Message 0x%x (seqNum = %d, srcProc = %d) was allocated"
};
DETAILS
When the
traceFlag is true, all message allocations
are logged.
C SYNOPSIS
config MessageQ.LM_free // module-wide |
|
Logged when freeing a message
msg: "LM_free: Message 0x%x (seqNum = %d, srcProc = %d) was freed"
};
DETAILS
When the
traceFlag is true, all freeing of messages
are logged. If an individual message's tracing was enabled
via
setMsgTrace, the MessageQ_free is also logged.
C SYNOPSIS
config MessageQ.LM_get // module-wide |
|
Logged when a message is received off the queue
msg: "LM_get: Message 0x%x (seqNum = %d, srcProc = %d) was received by queue 0x%x"
};
DETAILS
When the
traceFlag is true, all getting of messages
are logged. If an individual message's tracing
was enabled via
setMsgTrace, the MessageQ_get is
also logged.
C SYNOPSIS
config MessageQ.LM_putLocal // module-wide |
|
Logged when a message is placed onto a local queue
msg: "LM_putLocal: Message 0x%x (seqNum = %d, srcProc = %d) was placed onto queue 0x%x"
};
DETAILS
When the
traceFlag is true, all putting of messages
are logged. If an individual message's tracing was enabled
via
setMsgTrace, the MessageQ_put is also logged.
C SYNOPSIS
config MessageQ.LM_putRemote // module-wide |
|
Logged when a message is given to a transport
msg: "LM_putRemote: Message 0x%x (seqNum = %d, srcProc = %d) was given to processor %d transport"
};
DETAILS
When the
traceFlag is true, all putting of messages
to a transport are logged. If an individual message's tracing
was enabled via
setMsgTrace, the MessageQ_put is
also logged.
C SYNOPSIS
config MessageQ.LM_rcvByTransport // module-wide |
|
Logged when a transport receives an incoming message
msg: "LM_rcvByTransport: Message 0x%x (seqNum = %d, srcProc = %d) was received"
};
DETAILS
When the
traceFlag is true, all incoming messages
are logged. If an individual message's tracing
was enabled via
setMsgTrace, the receiving of a message is
also logged.
C SYNOPSIS
config MessageQ.LM_setTrace // module-wide |
|
Logged when setting the trace flag on a message
msg: "LM_setTrace: Message 0x%x (seqNum = %d, srcProc = %d) traceFlag = %d"
};
DETAILS
This is logged when tracing on a message is set via
setMsgTrace.
C SYNOPSIS
config MessageQ.LM_staticMsgInit // module-wide |
|
Logged when statically initializing a message
msg: "LM_staticMsgInit: Message 0x%x (seqNum = %d, srcProc = %d) was set in MessageQ_staticMsgInit"
};
DETAILS
When the
traceFlag is true, all messages that
are statically initialized via
staticMsgInit are logged.
C SYNOPSIS
config MessageQ.freeHookFxn // module-wide |
|
Free function in MessageQ_free after message was freed back to the heap
MessageQ.freeHookFxn = Void(*)(Bits16,Bits16) null;
C SYNOPSIS
config MessageQ.maxNameLen // module-wide |
|
Maximum length for Message queue names
MessageQ.maxNameLen = UInt 32;
C SYNOPSIS
config MessageQ.maxRuntimeEntries // module-wide |
|
Maximum number of MessageQs that can be dynamically created
C SYNOPSIS
config MessageQ.nameTableGate // module-wide |
|
Gate used to make the name table thread safe
DETAILS
This gate is used when accessing the name table during
a
create,
delete, and
open.
This gate is also used to protect MessageQ when growing
internal tables in the
create.
The table is in local memory, not shared memory. So a
single processor gate will work.
The default will be
xdc.runtime.knl.GateThread
instance.
C SYNOPSIS
config MessageQ.numHeaps // module-wide |
|
Number of heapIds in the system
MessageQ.numHeaps = UInt16 8;
DETAILS
This allows MessageQ to pre-allocate the heaps table.
The heaps table is used when registering heaps.
There is no default heap, so unless the system is only using
staticMsgInit, the application must register a heap.
C SYNOPSIS
config MessageQ.numReservedEntries // module-wide |
|
Number of reserved MessageQ indexes
MessageQ.numReservedEntries = UInt 0;
DETAILS
An application can request the first N message queue indexes be
reserved to be used by MessageQ_create2. MessageQ_create will
not use these slots. The application can use any index less than
the value of numReservedEntries for the queueIndex field in the
MessageQ_Params2 structure.
numReservedEntries must be equal or less than
maxRuntimeEntries.
C SYNOPSIS
config MessageQ.putHookFxn // module-wide |
|
Put function hook
MessageQ.putHookFxn = Void(*)(Bits32,Ptr) null;
C SYNOPSIS
config MessageQ.traceFlag // module-wide |
|
Trace setting
MessageQ.traceFlag = Bool false;
DETAILS
This flag allows the configuration of the default module trace
settings.
C SYNOPSIS
metaonly config MessageQ.common$ // module-wide |
|
Common module configuration parameters
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 MessageQ.tableSection // module-wide |
|
Section name is used to place the names table
MessageQ.tableSection = String null;
metaonly MessageQ.registerHeapMeta() // module-wide |
|
Statically register a heap with MessageQ
MessageQ.
registerHeapMeta(
IHeap.Handle heap,
UInt16 heapId)
returns Void
ARGUMENTS
heap
Heap to register
heapId
heapId associated with the heap
DETAILS
Build error if heapId is in use.
metaonly MessageQ.registerTransportMeta() // module-wide |
|
Statically register a transport with MessageQ
ARGUMENTS
transport
transport to register
procId
procId that transport communicaties with
priority
priority of transport
DETAILS
Build error if remote processor already has a transport
registered.
Instance Config Parameters |
|
var params = new MessageQ.Params;
// Instance config-params object
// Requested MessageQ_QueueIndex
// ISync handle used to signal IO completion
config MessageQ.Params.queueIndex // instance |
|
Requested MessageQ_QueueIndex
var params = new MessageQ.Params;
...
DETAILS
This parameter allows an application to specify the queueIndex to
be used for a message queue. To use this functionality, the
MessageQ.numReservedEntries static configuration parameter must be
set to a specific value.
The default is
ANY. This means do that you are not asking for
an explicit index. MessageQ will find the first available one which is
equal or greater than MessageQ.numReservedEntries.
C SYNOPSIS
config MessageQ.Params.synchronizer // instance |
|
ISync handle used to signal IO completion
var params = new MessageQ.Params;
...
DETAILS
The ISync instance is used in the
get and
put.
The
xdc.runtime.knl.ISync.signal is called as part
of the
put call. The
xdc.runtime.knl.ISync.wait is
called in the
get if there are no messages present.
C SYNOPSIS