CMSIS-RTOS: Message Queue Management

| CMSIS-RTOS Version 1.02 CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.

- CMSIS
- CORE
- Driver
- DSP
- RTOS API
- Pack
- SVD

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Message Queue Management
CMSIS-RTOS API

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

## Macros

#define | osFeature_MessageQ 1
| Message Queues: 1=available, 0=not available.
#define | osMessageQDef(name, queue_sz, type)
| Create a Message Queue Definition.
#define | osMessageQ(name) &os_messageQ_def_##name
| Access a Message Queue Definition.

## Functions

osMessageQId | osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)
| Create and Initialize a Message Queue.
osStatus | osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec)
| Put a Message to a Queue.
osEvent | osMessageGet (osMessageQId queue_id, uint32_t millisec)
| Get a Message or Wait for a Message from a Queue.

## 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.