module ti.sdo.ipc.MessageQ

Message-passing with queuing

C synopsis
Individual elements
XDCscript usage
Individual elements

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. [ more ... ]

C synopsis target-domain sourced in ti/sdo/ipc/MessageQ.xdc

#include <ti/sdo/ipc/MessageQ.h>

Functions
Void	MessageQ_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(MessageQ_Params *params);
Bool	MessageQ_registerTransport// Register a transport with MessageQ(IMessageQTransport_Handle transport, UInt16 procId, UInt priority);
Void	MessageQ_unregisterTransport// Unregister a transport with MessageQ(UInt16 procId, UInt priority);
Functions common to all target instances
	MessageQ_handle// Convert this instance structure pointer into an instance handle, MessageQ_Handle_label// The label associated with this instance object, MessageQ_Handle_name// The name of this instance object, MessageQ_Object_count// The number of statically-created instance objects, MessageQ_Object_first// The handle of the first dynamically-created instance object, or NULL, MessageQ_Object_get// The handle of the i-th statically-created instance object (array == NULL), MessageQ_Object_heap// The heap used to allocate dynamically-created instance objects, MessageQ_Object_next// The handle of the next dynamically-created instance object, or NULL, MessageQ_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	MessageQ_Module_getMask// Returns the diagnostics mask for this module, MessageQ_Module_hasMask// Test whether this module has a diagnostics mask, MessageQ_Module_heap// The heap from which this module allocates memory, MessageQ_Module_id// Get this module's unique id, MessageQ_Module_setMask// Set the diagnostics mask for this module, MessageQ_Module_startupDone// Test if this module has completed startup
Defines
#define	MessageQ_HIGHPRI// (UInt)1
#define	MessageQ_NORMALPRI// Message priority values. These must match the values defined in ti/ipc/MessageQ.h but are needed here for ROV (UInt)0
#define	MessageQ_RESERVEDPRI// (UInt)2
#define	MessageQ_URGENTPRI// (UInt)3
Typedefs
typedef MessageQ_Object *	MessageQ_Handle// Client reference to an instance object;
typedef struct	MessageQ_Object// Opaque internal representation of an instance object MessageQ_Object;
typedef struct	MessageQ_Params// Instance config-params structure ...
typedef UInt32	MessageQ_QueueId// MessageQ ID;
typedef struct	MessageQ_Struct// Opaque client structure large enough to hold an instance object MessageQ_Struct;
Constants
extern const Assert_Id	MessageQ_A_cannotFreeStaticMsg// Assert raised when attempting to free a static message;
extern const Assert_Id	MessageQ_A_heapIdInvalid// Assert raised when using an invalid heapId;
extern const Assert_Id	MessageQ_A_invalidContext// Assert raised when calling API with wrong handle;
extern const Assert_Id	MessageQ_A_invalidMsg// Assert raised when an invalid message is supplied;
extern const Assert_Id	MessageQ_A_invalidObj// Assert raised for an invalid MessageQ object;
extern const Assert_Id	MessageQ_A_invalidParam// Assert raised for an invalid parameter;
extern const Assert_Id	MessageQ_A_invalidQueueId// Assert raised when an invalid queueId is supplied;
extern const Assert_Id	MessageQ_A_invalidUnblock// 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_procIdInvalid// Assert raised when using an invalid procId;
extern const Assert_Id	MessageQ_A_unregisteredTransport// Assert raised when attempting to send a message to a core where a transport has not been registered;
extern const Error_Id	MessageQ_E_maxReached// Error raised if all the message queue objects are taken;
extern const Error_Id	MessageQ_E_nameFailed// 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_unregisterHeapId// Error raised when heapId has not been registered;
extern const Log_Event	MessageQ_LM_alloc// Logged when allocating a message;
extern const Log_Event	MessageQ_LM_free// Logged when freeing a message;
extern const Log_Event	MessageQ_LM_get// Logged when a message is received off the queue;
extern const Log_Event	MessageQ_LM_putLocal// Logged when a message is placed onto a local queue;
extern const Log_Event	MessageQ_LM_putRemote// Logged when a message is given to a transport;
extern const Log_Event	MessageQ_LM_rcvByTransport// Logged when a transport receives an incoming message;
extern const Log_Event	MessageQ_LM_setTrace// Logged when setting the trace flag on a message;
extern const Log_Event	MessageQ_LM_staticMsgInit// Logged when statically initializing a message;
extern const UInt	MessageQ_maxNameLen// Maximum length for Message queue names;
extern const UInt	MessageQ_maxRuntimeEntries// Maximum number of MessageQs that can be dynamically created;
extern const IGateProvider_Handle	MessageQ_nameTableGate// Gate used to make the name table thread safe;
extern const UInt16	MessageQ_numHeaps// Number of heapIds in the system;
extern const Bool	MessageQ_traceFlag// Trace setting;

DETAILS

MessageQ provides more sophisticated messaging than other modules. It is typically used for complex situations such as multi-processor messaging.

The following are key features of the MessageQ module:

Writers and readers can be relocated to another processor with no runtime code changes.
Timeouts are allowed when receiving messages.
Readers can determine the writer and reply back.
Receiving a message is deterministic when the timeout is zero.
Messages can reside on any message queue.
Supports zero-copy transfers.
Can send and receive from any type of thread.
Notification mechanism is specified by application.
Allows QoS (quality of service) on message buffer pools. For example, using specific buffer pools for specific message queues.

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.

Message queues are identified by a system-wide unique name. Internally, MessageQ uses the ti.sdo.utils.NameServer module for managing these names. The names are used for opening a message queue.

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.

Messages in a message queue can be of variable length. The only requirement is that the first field in the definition of a message must be a MsgHeader structure. For example:

  typedef struct MyMsg {
      MessageQ_MsgHeader header;
      ...
  } MyMsg;

The MessageQ API uses the MessageQ_MsgHeader internally. Your application should not modify or directly access the fields in the MessageQ_MsgHeader.

All messages sent via the MessageQ module must be allocated from a xdc.runtime.IHeap implementation. The heap can also be used for other memory allocation not related to MessageQ.

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.

The registerHeap and registerHeapMeta are APIs used to assign a MessageQ heapId to a heap. When allocating a message, the heapId is used, not the heap handle. This heapId is actually placed into the message (part of the MsgHeader). Care must be taken when assigning heapIds. Refer to the registerHeap and registerHeapMeta descriptions for more details.

MessageQ also supports the usage of messages that are not allocated via the alloc function. Please refer to the staticMsgInit function description for more details.

MessageQ supports reads/writes of different thread models. This is accomplished by having the creator of the message queue specify a xdc.runtime.knl.ISync.Object via the synchronizer configuration parameter. The xdc.runtime.knl.ISync.signal portion of the ISync instance is called whenever the put is called. The xdc.runtime.knl.ISync.wait portion is called in the get if and only if there are no messages.

Since ISyncs are binary, the reader must drain the message queue of all messages before waiting for another signal. For example, if the reader was a SYSBIOS Swi, the xdc.runtime.knl.ISync instance could be a SyncSwi. If a put was called, the Swi_post() would be called. The Swi would run and it must call get until no messages are returned.

In a multiple processor system, MessageQ communicates to other processors via ti.sdo.ipc.interfaces.IMessageQTransport instances. MessageQ supports a high priority and a normal priority transport between any two processors. The IMessageQTransport instances are created via the SetupTransportProxy. The instances are responsible for registering themselves with MessageQ. This is accomplished via the registerTransport function.

const MessageQ_HIGHPRI