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.
proxy MessageQ.SetupTransportProxy |
 |
MessageQ transport setup proxy
XDCscript usage |
meta-domain |
// explicit access to the currently bound delegate module
const MessageQ.HIGHPRI |
 |
XDCscript usage |
meta-domain |
const MessageQ.HIGHPRI = 1;
#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
XDCscript usage |
meta-domain |
const MessageQ.NORMALPRI = 0;
#define MessageQ_NORMALPRI (UInt)0
const MessageQ.RESERVEDPRI |
 |
XDCscript usage |
meta-domain |
const MessageQ.RESERVEDPRI = 2;
#define MessageQ_RESERVEDPRI (UInt)2
const MessageQ.URGENTPRI |
 |
XDCscript usage |
meta-domain |
const MessageQ.URGENTPRI = 3;
#define MessageQ_URGENTPRI (UInt)3
typedef MessageQ.QueueId |
 |
MessageQ ID
typedef UInt32 MessageQ_QueueId;
config MessageQ.A_cannotFreeStaticMsg // module-wide |
 |
Assert raised when attempting to free a static message
XDCscript usage |
meta-domain |
msg: "A_cannotFreeStaticMsg: Cannot call MessageQ_free with static msg"
};
extern const Assert_Id MessageQ_A_cannotFreeStaticMsg;
config MessageQ.A_heapIdInvalid // module-wide |
 |
Assert raised when using an invalid heapId
XDCscript usage |
meta-domain |
msg: "A_heapIdInvalid: heapId is invalid"
};
extern const Assert_Id MessageQ_A_heapIdInvalid;
config MessageQ.A_invalidContext // module-wide |
 |
Assert raised when calling API with wrong handle
XDCscript usage |
meta-domain |
msg: "A_invalidContext: Cannot call with an open/create 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
XDCscript usage |
meta-domain |
msg: "A_invalidMsg: Invalid message"
};
extern const Assert_Id MessageQ_A_invalidMsg;
config MessageQ.A_invalidObj // module-wide |
 |
Assert raised for an invalid MessageQ object
XDCscript usage |
meta-domain |
msg: "A_invalidObj: an invalid obj is used"
};
extern const Assert_Id MessageQ_A_invalidObj;
config MessageQ.A_invalidParam // module-wide |
 |
Assert raised for an invalid parameter
XDCscript usage |
meta-domain |
msg: "A_invalidParam: an invalid parameter was passed in"
};
extern const Assert_Id MessageQ_A_invalidParam;
config MessageQ.A_invalidQueueId // module-wide |
 |
Assert raised when an invalid queueId is supplied
XDCscript usage |
meta-domain |
msg: "A_invalidQueueId: Invalid queueId is used"
};
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
XDCscript usage |
meta-domain |
msg: "A_invalidUnblock: Trying to unblock a remote MessageQ or a queue with non-blocking synchronizer"
};
extern const Assert_Id MessageQ_A_invalidUnblock;
config MessageQ.A_procIdInvalid // module-wide |
 |
Assert raised when using an invalid procId
XDCscript usage |
meta-domain |
msg: "A_procIdInvalid: procId is invalid"
};
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
XDCscript usage |
meta-domain |
msg: "A_unregisteredTransport: transport is not registered"
};
extern const Assert_Id MessageQ_A_unregisteredTransport;
config MessageQ.E_maxReached // module-wide |
 |
Error raised if all the message queue objects are taken
XDCscript usage |
meta-domain |
msg: "E_maxReached: All objects in use. MessageQ.maxRuntimeEntries is %d"
};
extern const Error_Id MessageQ_E_maxReached;
config MessageQ.E_unregisterHeapId // module-wide |
 |
Error raised when heapId has not been registered
XDCscript usage |
meta-domain |
msg: "E_unregisterHeapId: Heap id %d not registered"
};
extern const Error_Id MessageQ_E_unregisterHeapId;
config MessageQ.LM_alloc // module-wide |
 |
Logged when allocating a message
XDCscript usage |
meta-domain |
msg: "LM_alloc: Message 0x%x (seqNum = %d, srcProc = %d) was allocated"
};
DETAILS
When the
traceFlag is true, all message allocations
are logged.
config MessageQ.LM_free // module-wide |
 |
Logged when freeing a message
XDCscript usage |
meta-domain |
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.
config MessageQ.LM_get // module-wide |
 |
Logged when a message is received off the queue
XDCscript usage |
meta-domain |
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.
config MessageQ.LM_putLocal // module-wide |
 |
Logged when a message is placed onto a local queue
XDCscript usage |
meta-domain |
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.
config MessageQ.LM_putRemote // module-wide |
 |
Logged when a message is given to a transport
XDCscript usage |
meta-domain |
msg: "LM_putRemote: Message 0x%x (seqNum = %d, srcProc = %d) was given to processor %d 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
XDCscript usage |
meta-domain |
msg: "LM_rcvByTransport: Message 0x%x (seqNum = %d, srcProc = %d) was received"
};
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
XDCscript usage |
meta-domain |
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.
config MessageQ.LM_staticMsgInit // module-wide |
 |
Logged when statically initializing a message
XDCscript usage |
meta-domain |
msg: "LM_staticMsgInit: Message 0x%x (seqNum = %d, srcProc = %d) was set in MessageQ_staticMsgInit"
};
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.maxNameLen // module-wide |
 |
Maximum length for Message queue names
XDCscript usage |
meta-domain |
MessageQ.maxNameLen = UInt 32;
extern const UInt MessageQ_maxNameLen;
config MessageQ.maxRuntimeEntries // module-wide |
 |
Maximum number of MessageQs that can be dynamically created
XDCscript usage |
meta-domain |
extern const UInt MessageQ_maxRuntimeEntries;
config MessageQ.nameTableGate // module-wide |
 |
Gate used to make the name table thread safe
XDCscript usage |
meta-domain |
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
XDCscript usage |
meta-domain |
MessageQ.numHeaps = UInt16 1;
extern const UInt16 MessageQ_numHeaps;
DETAILS
This allows MessageQ to pre-allocate the heaps table.
The heaps table is used when registering heaps.
The default is 1.
There is no default heap, so unless the system is only using
staticMsgInit, the application must register a heap.
config MessageQ.traceFlag // module-wide |
 |
Trace setting
XDCscript usage |
meta-domain |
MessageQ.traceFlag = Bool false;
extern const Bool MessageQ_traceFlag;
DETAILS
This flag allows the configuration of the default module trace
settings.
metaonly config MessageQ.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 MessageQ.tableSection // module-wide |
 |
Section name is used to place the names table
XDCscript usage |
meta-domain |
MessageQ.tableSection = String null;
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
metaonly MessageQ.registerHeapMeta( ) // module-wide |
 |
Statically register a heap with MessageQ
XDCscript usage |
meta-domain |
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
XDCscript usage |
meta-domain |
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.
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
per-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
per-instance config parameters |
 |
XDCscript usage |
meta-domain |
var params = new MessageQ.Params;
// Instance config-params object
// ISync handle used to signal IO completion
typedef struct MessageQ_Params {
// Instance config-params structure
// Common per-instance configs
// ISync handle used to signal IO completion
} MessageQ_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config MessageQ.synchronizer // per-instance |
 |
ISync handle used to signal IO completion
XDCscript usage |
meta-domain |
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.
per-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