GeMRTOS Message Queue: Producer-Consumer API for Nios V RTOS

GeMRTOS message queue is an inter-task communication resource that lets independent tasks exchange data asynchronously in a GeMRTOS multiprocessor RTOS running on Altera FPGA platforms with Nios V processors. Using a producer-consumer pattern, one or more producer tasks send messages to the queue while subscribed consumer tasks receive them. This page covers the complete message queue API: how to create a queue, subscribe consumers, send formatted or raw messages, and receive data — along with the T_QUEUE_RESOURCE structure reference.

How GeMRTOS Message Queues Work #

The message queue is a resource that enables independent tasks to exchange information. A producer task sends messages to the message queue; each message remains associated with the queue until either (1) all subscribed consumer tasks have read (consumed) it, or (2) a timeout expires. The producer task remains suspended until all consumers have received the message or the timeout fires. Consumer tasks that have already received all pending messages remain suspended waiting for the next one.

Message Queue API Reference #

Creating a Message Queue #

Create a new message queue resource with:

GS_RCB *gu_MessageQueueCreate(void);

The gu_MessageQueueCreate function allocates and initializes a new message queue resource built on the GS_RCB structure, with T_QUEUE_RESOURCE fields appended. The function can be called from main code or from a task, but must be called before any subscribe, send, or receive operation on that queue.

Returns: pointer to the new message queue resource (GS_RCB), or NULL if no queue resource is available.

Subscribing a Consumer Task #

A consumer task must subscribe to a message queue before it can receive messages — and, unlike a generic subscribe call, this is also where its receive buffer is registered:

GS_ECB *gu_MessageQueueSubscribe(GS_TCB *ptcb, GS_RCB *presource,
                                  void *buffer_msg, G_UINT32 buffer_length);

The gu_MessageQueueSubscribe function registers the specified task as a consumer of the given message queue resource, binding the buffer it will receive messages into for the lifetime of the subscription. A task must be subscribed before calling gu_MessageQueueReceive. The queue must have been previously created with gu_MessageQueueCreate.

Returns: pointer to the GS_ECB event associated with this subscription, or NULL on error.

Sending Formatted Messages #

A producer task sends a printf-style formatted message with:

G_UINT32 gu_MessageQueuePrintf(GS_RCB *prcb, const char *format, ...);

The gu_MessageQueuePrintf function sends a formatted message to the specified queue. The calling task remains suspended until the message has been delivered to all subscribed consumers. The format string follows standard printf conventions, supporting embedded format tags replaced by subsequent arguments.

Returns: G_TRUE always — this call reports a fixed success flag, not a delivery count (see gu_MessageQueueSend below for a call that reports how many subscribers actually received the message, including partial-delivery/timeout cases).

Sending Raw Messages #

A producer task sends a raw byte message, with an explicit timeout, using:

int gu_MessageQueueSend(GS_RCB *prcb, const char *pmsg, int msg_length,
                         G_UINT64 timeout);

The gu_MessageQueueSend function sends a message buffer to the queue. The calling task remains suspended until the message has been delivered to all subscribed consumers or the timeout expires.

Returns: the number of subscribers the message was delivered to, as a positive value if delivery to all subscribers completed; a negative value (the negated partial-delivery count) if the timeout expired before every subscriber received it. This is not a G_TRUE/G_FALSE success flag — check the sign and magnitude to know exactly how many receivers were reached.

Receiving Messages #

A subscribed consumer task receives the next pending message with:

int gu_MessageQueueReceive(GS_RCB *prcb);

The gu_MessageQueueReceive function copies the next message from the queue into the buffer registered earlier at gu_MessageQueueSubscribe time — it does not take a buffer argument of its own. The task must have been previously subscribed. If the received message is larger than the buffer length given at subscribe time, it is silently truncated to fit.

Returns: the number of bytes actually received (may be less than the message length if the subscription’s buffer was too small); ERR_RECEIVE_ABORT (0xFFFFFFFF) if the receive was aborted. This is a byte count, not a G_TRUE/G_FALSE boolean — a return value of 0 means an empty message was delivered, not a failure.

Destroying a Message Queue #

G_UINT32 gu_MessageQueueDestroy(GS_RCB *pqueue);

gu_MessageQueueDestroy returns a message queue’s GS_RCB to the free pool. It fails (returns G_FALSE) if the queue still has subscribers or pending sender/receiver events — a queue must be idle before it can be destroyed.

T_QUEUE_RESOURCE Structure #

The T_QUEUE_RESOURCE structure is embedded as the queue field within a GS_RCB resource. Access its fields using: (GS_RCB *)->queue.<field>

Key Takeaways #

• The GeMRTOS message queue implements an asynchronous producer-consumer IPC pattern for Nios V FPGA RTOS, suspending the producer until all subscribers have consumed the message or a timeout fires.
• Consumer tasks must call gu_MessageQueueSubscribe before receiving messages — this same call also binds the receive buffer for the subscription’s whole lifetime.
• gu_MessageQueueReceive takes no buffer argument — it always writes into the buffer given at subscribe time, and truncates messages that exceed that buffer’s length.
• Use gu_MessageQueuePrintf for human-readable formatted messages (always blocks until every subscriber has it, returns a fixed success flag) and gu_MessageQueueSend for raw binary data with an explicit timeout (returns a real delivered-subscriber count, positive on full delivery, negative on partial/timeout).
• The message queue resource is built on GeMRTOS’s GS_RCB and linked-list infrastructure; T_QUEUE_RESOURCE fields (MQ_subscribers, MQ_seq_send) are accessed via (GS_RCB *)->queue.<field>.