Control, send, receive, or wait for messages. More...

Macros
#define	osFeature_MessageQ 1
	Message Queues: 1=available, 0=not available. More...

#define	osMessageQDef(name, queue_sz, type)
	Create a Message Queue Definition. More...

#define	osMessageQ(name) &os_messageQ_def_##name
	Access a Message Queue Definition. More...

Functions
osMessageQId	osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)
	Create and Initialize a Message Queue. More...

osStatus	osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec)
	Put a Message to a Queue. More...

osEvent	osMessageGet (osMessageQId queue_id, uint32_t millisec)
	Get a Message or Wait for a Message from a Queue. More...

Description

Message Queue Management functions allow to control, send, receive, or wait for messages. A message can be an integer or pointer value that is send to a thread or interrupt service routine.

CMSIS-RTOS Message Queue

Macro Definition Documentation

#define osFeature_MessageQ 1

A CMSIS-RTOS implementation may support message queues.

When osFeature_MailQ is 1 message queues are supported.
When osFeature_MailQ is 0 no message queues are supported.

#define osMessageQ ( name ) &os_messageQ_def_##name

Access to the message queue definition for the function osMessageCreate.

Parameters

name	name of the queue

Note: CAN BE CHANGED: The parameter to osMessageQ shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

#define osMessageQDef	(	name,
		queue_sz,
		type
	)

Define the attributes of a message queue created by the function osMessageCreate using osMessageQ.

Note: The parameter thread registers the receiving thread for a message and is needed for the general osWait function to deliver the message.

Parameters

name	name of the queue.
queue_sz	maximum number of messages in the queue.
type	data type of a single message element (for debugger).

Note: CAN BE CHANGED: The parameter to osMessageQDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

Function Documentation

osMessageQId osMessageCreate	(	const osMessageQDef_t *	queue_def,
		osThreadId	thread_id
	)

Parameters

[in]	queue_def	queue definition referenced with osMessageQ.
[in]	thread_id	thread ID (obtained by osThreadCreate or osThreadGetId) or NULL.

Returns: message queue ID for reference by other functions or NULL in case of error.

Note: MUST REMAIN UNCHANGED: osMessageCreate shall be consistent in every CMSIS-RTOS.

Create and initialize a message queue.

Example

#include "cmsis_os.h"
 
osThreadId tid_thread1;                          // ID for thread 1
osThreadId tid_thread2;                          // for thread 2
 
typedef struct {                                 // Message object structure
  float    voltage;                              // AD result of measured voltage
  float    current;                              // AD result of measured current
  int      counter;                              // A counter value
} T_MEAS;
 
osPoolDef(mpool, 16, T_MEAS);                    // Define memory pool
osPoolId  mpool;
osMessageQDef(MsgBox, 16, T_MEAS);               // Define message queue
osMessageQId  MsgBox;
 
void send_thread (void const *argument);         // forward reference
void recv_thread (void const *argument);         // forward reference
                                                 // Thread definitions
osThreadDef(send_thread, osPriorityNormal, 1, 0);
osThreadDef(recv_thread, osPriorityNormal, 1, 2000);
 
/*
    Thread 1: Send thread
 */
void send_thread (void const *argument) {
  T_MEAS    *mptr;
 
  mptr = osPoolAlloc(mpool);                     // Allocate memory for the message
  mptr->voltage = 223.72;                        // Set the message content
  mptr->current = 17.54;
  mptr->counter = 120786;
  osMessagePut(MsgBox, (uint32_t)mptr, osWaitForever);  // Send Message
  osDelay(100);
 
  mptr = osPoolAlloc(mpool);                     // Allocate memory for the message
  mptr->voltage = 227.23;                        // Prepare a 2nd message
  mptr->current = 12.41;
  mptr->counter = 170823;
  osMessagePut(MsgBox, (uint32_t)mptr, osWaitForever);  // Send Message
  osThreadYield();                               // Cooperative multitasking
                                                 // We are done here, exit this thread
}
 
/*
    Thread 2: Receive thread
 */
void recv_thread (void const *argument) {
  T_MEAS  *rptr;
  osEvent  evt;
   
  for (;;) {
    evt = osMessageGet(MsgBox, osWaitForever);  // wait for message
    if (evt.status == osEventMessage) {
      rptr = evt.value.p;
      printf ("\nVoltage: %.2f V\n", rptr->voltage);
      printf ("Current: %.2f A\n", rptr->current);
      printf ("Number of cycles: %d\n", rptr->counter);
      osPoolFree(mpool, rptr);                  // free memory allocated for message
    }
  }
}
 
void StartApplication (void) {
  mpool = osPoolCreate(osPool(mpool));                 // create memory pool
  MsgBox = osMessageCreate(osMessageQ(MsgBox), NULL);  // create msg queue
   
  tid_thread1 = osThreadCreate(osThread(send_thread), NULL);
  tid_thread2 = osThreadCreate(osThread(recv_thread), NULL);
  :
}

osEvent osMessageGet	(	osMessageQId	queue_id,
		uint32_t	millisec
	)

Parameters

[in]	queue_id	message queue ID obtained with osMessageCreate.
[in]	millisec	timeout value or 0 in case of no time-out.

Returns: event information that includes status code.

Note: MUST REMAIN UNCHANGED: osMessageGet shall be consistent in every CMSIS-RTOS.

Suspend the execution of the current RUNNING thread until a message arrives. When a message is already in the queue, the function returns instantly with the message information.

The argument millisec specifies how long the system waits for a message to become available. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout value can have the following values:

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a message arrives.
all other values specify a time in millisecond for a timeout.

Note: The parameter millisec must be 0 for using this function in an ISR.

Status and Error Codes

osOK: no message is available in the queue and no timeout was specified.
osEventTimeout: no message has arrived during the given timeout period.
osEventMessage: message received, value.p contains the pointer to message.
osErrorParameter: a parameter is invalid or outside of a permitted range.

osStatus osMessagePut	(	osMessageQId	queue_id,
		uint32_t	info,
		uint32_t	millisec
	)

Parameters

[in]	queue_id	message queue ID obtained with osMessageCreate.
[in]	info	message information.
[in]	millisec	timeout value or 0 in case of no time-out.

Returns: status code that indicates the execution status of the function.

Note: MUST REMAIN UNCHANGED: osMessagePut shall be consistent in every CMSIS-RTOS.

Put the message info in a message queue specified by queue_id.

When the message queue is full, the system retries for a specified time with millisec. While the system retries the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values:

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a message queue slot becomes available.
all other values specify a time in millisecond for a timeout.

Note: The parameter millisec must be 0 for using this function in an ISR.

Status and Error Codes

osOK: the message is put into the queue.
osErrorResource: no memory in the queue was available.
osErrorTimeoutResource: no memory in the queue was available during the given time limit.
osErrorParameter: a parameter is invalid or outside of a permitted range.

Macros

Functions

Description

Macro Definition Documentation

Function Documentation