Message Queues

---

Detailed Description

Message Queues can be used to send arbitrary messages between tasks.

Messages are sent in the form of generic pointers to memory. TiROS handles these message pointers in an opaque manner and does not care what they point to. It is important to note that the maximum size of the message queue has to be known when the message queue is intialized. It cannot be resized on the fly. A message server can wait on a message queue or poll it (with the O_NONBLOCKING option). A message client can send a message on the queue which will unblock any waiting server. If multiple tasks are waiting on the same message queue, the one with the highest priority will be unblocked first.

NOTE: A custom type mqind_t is used for the queue length. This is of type unsigned integer. By default, it is an 8-bit integer (max val of 255). This can be overridden (see tr_types.h).

NOTE: Always initialize before use.

 #define TST_QSZ 4
 osword_t tst_Q[msgQ_MEMSZ(TST_QSZ)];   // Previously initialized
 void task1(void *dummy)
 {
   int8_t rc;
   osptr_t rx_val;
   while(1) {
       rc = msgQ_recv( (msgQ_t*)tst_Q, 0, 0, &rx_val);
       if (rc == SUCCESS) {
          do_something(rx_val);
       }
   }
 }
 void task2(void *dummy)
 {
   int8_t rc;
   while(1) {
       rc = msgQ_send( (msgQ_t*)tst_Q, 7); // Send 7 to task1
   }
 }

Defines
#define	msgQ_MEMSZ(qlen)
Functions
void	msgQ_init (msgQ_t *m, mqind_t qlen)
mqind_t	msgQ_count (msgQ_t *m)
int8_t	msgQ_send (msgQ_t *m, osptr_t tx_value)
int8_t	msgQ_recv (msgQ_t *m, const trtime_t *timeout, uint8_t options, osptr_t *rx_value)

---

Define Documentation

#define msgQ_MEMSZ

(

qlen

)

Value:

((sizeof(struct msgQ) +  \
                (mqind_t)qlen * sizeof(osptr_t) + \
                sizeof(osword_t)-1) /   sizeof(osword_t))

Get the memory size for a message queue This macro makes sure that the memory is word aligned.

Parameters:

qlen

Length of the message queue

Returns:

Memory occupied (in words)

Definition at line 1002 of file tiros.h.

---

Function Documentation

void msgQ_init	(	msgQ_t *	m,
		mqind_t	qlen
	)

Initialize a message queue.

Calling Context:

1. Before os_start().
2. From within a task.
3. From an ISR.

Parameters:

	m	Pointer to message queue
	qlen	Length of the queue. NOTE: The queue memory is contained in the msgQ structure. It is EXTREMELY IMPORTANT that the qlen argument to this call be less than or equal to the length of the message queue that was used as an argument for msgQ_MEMSZ( ). Failing to follow this rule will result in buffer overflows.

Eg.:

   msgQ_t *m;
   qlen = 10;

   osword_t dummy[ msgQ_MEMSZ(qlen)];
   m = (msgQ_t *) dummy;
   msgQ_init(m, qlen);

The memory should not be transient. It should be global, or allocated on the heap.

mqind_t msgQ_count

(

msgQ_t *

m

)

The number of messages in the queue.

Calling Context:

1. Before os_start().
2. From within a task.
3. From an ISR.

Note: The message queue must be initialized before this call, else the return value is meaningless

Parameters:

m

Pointer to the message queue

Returns:

Number of messages in the queue

int8_t msgQ_send	(	msgQ_t *	m,
		osptr_t	tx_value
	)

Post a message to the queue.

Calling Context:

1. From within a task.
2. From an ISR.

In the current implementation, if the queue is full, an error is returned. The task is not allowed to block here. This may be changed in the future.

Parameters:

	m	Pointer to message queue
	tx_value	The value to be added to the queue.

Returns:

{SUCCESS, ERR_FULL}

int8_t msgQ_recv	(	msgQ_t *	m,
		const trtime_t *	timeout,
		uint8_t	options,
		osptr_t *	rx_value
	)

Wait for message.

Calling Context:

1. From within a task.
2. From an ISR (error if blocking needed).

Parameters:

	m	Pointer to message queue
	timeout	Timeout. This can be 0 for infinite timeout.
	options	[O_NONBLOCKING | O_RELATIVE_TIME ].
[out]	rx_value	Pointer to memory where the message should be stored.

Returns:

{SUCCESS, ERR_WOULDBLOCK_ISR, ERR_WOULDBLOCK_MUTEX, ERR_TIMEOUT, ERR_RESUMED}.

---