CMSIS-RTOS2  Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Message Queue

Exchange messages between threads in a FIFO-like operation. More...

Data Structures

struct  osMessageQueueAttr_t
 Attributes structure for message queue. More...
 

Functions

osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
 Create and Initialize a Message Queue object. More...
 
const char * osMessageQueueGetName (osMessageQueueId_t mq_id)
 Get name of a Message Queue object. More...
 
osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)
 Put a Message into a Queue or timeout if Queue is full. More...
 
osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
 Get a Message from a Queue or timeout if Queue is empty. More...
 
uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
 Get maximum number of messages in a Message Queue. More...
 
uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
 Get maximum message size in a Memory Pool. More...
 
uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)
 Get number of queued messages in a Message Queue. More...
 
uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)
 Get number of available slots for messages in a Message Queue. More...
 
osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)
 Reset a Message Queue to initial empty state. More...
 
osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)
 Delete a Message Queue object. More...
 

Description

Message passing is another basic communication model between threads. In the message passing model, one thread sends data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to information to be shared. In CMSIS-RTOS, this mechanism is called s message queue. The data is passed from one thread to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The data to be passed can be of integer or pointer type:

MessageQueue.png
CMSIS-RTOS Message Queue

Compared to a Memory Pool, message queues are less efficient in general, but solve a broader range of problems. Sometimes, threads do not have a common address space or the use of shared memory raises problems, such as mutual exclusion.

Note
Refer to Message Queue Configuration for RTX5 configuration options.

Working with Message Queues

Follow these steps to create and use a message queue:

  1. Setup the message queue:
    osMessageQueueId_t MsgQ_Id; // Define a message queue ID
  2. Then, create the message queue in a thread:
    MsgQId_Isr = osMessageQueueNew (16, sizeof(uint32_t), NULL); // Instance a message queue for 16 elements of uint32_t
  3. Fill the message queue with data:
    uint32_t data = 512;
    osMessageQueuePut(MsgQ_Id, data, 0, 0);
  4. From the receiving thread access the data using:
    uint32_t msg;
    osMessageQueueGet(MsgQ_Id, &msg, NULL, 0);

Data Structure Documentation

struct osMessageQueueAttr_t

Attributes structure for message queue.

Data Fields
const char * name name of the message queue
uint32_t attr_bits attribute bits
void * cb_mem memory for control block
uint32_t cb_size size of provided memory for control block
void * mq_mem memory for data storage
uint32_t mq_size size of provided memory for data storage

Function Documentation

osMessageQueueId_t osMessageQueueNew ( uint32_t  msg_count,
uint32_t  msg_size,
const osMessageQueueAttr_t attr 
)
Parameters
[in]msg_countmaximum number of messages in queue.
[in]msg_sizemaximum message size in bytes.
[in]attrmessage queue attributes; NULL: default values.
Returns
message queue ID for reference by other functions or NULL in case of error.
const char * osMessageQueueGetName ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
name as NULL terminated string.
*osStatus_t osMessageQueuePut ( osMessageQueueId_t  mq_id,
const void *  msg_ptr,
uint8_t  msg_prio,
uint32_t  timeout 
)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
[in]msg_ptrpointer to buffer with message to put into a queue.
[in]msg_priomessage priority.
[in]timeoutTimeout Value or 0 in case of no time-out.
Returns
status code that indicates the execution status of the function.

Code Example:

#include "cmsis_os2.h" // CMSIS RTOS header file
/*----------------------------------------------------------------------------
* Message Queue creation & usage
*---------------------------------------------------------------------------*/
void Thread_MsgQueue1 (void *argument); // thread function 1
void Thread_MsgQueue2 (void *argument); // thread function 2
osThreadId_t tid_Thread_MsgQueue1; // thread id 1
osThreadId_t tid_Thread_MsgQueue2; // thread id 2
#define MSGQUEUE_OBJECTS 16 // number of Message Queue Objects
typedef struct { // object data type
uint8_t Buf[32];
uint8_t Idx;
} MSGQUEUE_OBJ_t;
osMemoryPoolId_t mpid_MemPool2; // memory pool id
osMessageQueueId_t mid_MsgQueue; // message queue id
int Init_MsgQueue (void) {
mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);
if (!mid_MsgQueue) {
; // Message Queue object not created, handle failure
}
tid_Thread_MsgQueue1 = osThreadNew (Thread_MsgQueue1, NULL, NULL);
if (!tid_Thread_MsgQueue1) return(-1);
tid_Thread_MsgQueue2 = osThreadNew (Thread_MsgQueue2, NULL, NULL);
if (!tid_Thread_MsgQueue2) return(-1);
return(0);
}
void Thread_MsgQueue1 (void *argument) {
MSGQUEUE_OBJ_t pMsg = 0;
while (1) {
; // Insert thread code here...
pMsg->Buf[0] = 0x55; // do some work...
pMsg->Idx = 0;
osMessageQueuePut (mid_MsgQueue, &pMsg, NULL, NULL);
osThreadYield (); // suspend thread
}
}
void Thread_MsgQueue2 (void *argument) {
MSGQUEUE_OBJ_t pMsg = 0;
while (1) {
; // Insert thread code here...
status = osMessageQueueGet (mid_MsgQueue, &pMsg, NULL, NULL); // wait for message
if (status == osOK) {
; // process data
}
}
}
osStatus_t osMessageQueueGet ( osMessageQueueId_t  mq_id,
void *  msg_ptr,
uint8_t *  msg_prio,
uint32_t  timeout 
)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
[out]msg_ptrpointer to buffer for message to get from a queue.
[out]msg_priopointer to buffer for message priority or NULL.
[in]timeoutTimeout Value or 0 in case of no time-out.
Returns
status code that indicates the execution status of the function.
uint32_t osMessageQueueGetCapacity ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
maximum number of messages.
uint32_t osMessageQueueGetMsgSize ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
maximum message size in bytes.
uint32_t osMessageQueueGetCount ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
number of queued messages.
uint32_t osMessageQueueGetSpace ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
number of available slots for messages.
osStatus_t osMessageQueueReset ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
status code that indicates the execution status of the function.
osStatus_t osMessageQueueDelete ( osMessageQueueId_t  mq_id)
Parameters
[in]mq_idmessage queue ID obtained by osMessageQueueNew.
Returns
status code that indicates the execution status of the function.