| CMSIS-RTOS RTX Version 4.51 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- RTX

- 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.
os_InRegs 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 the value osFeature_MailQ is 1 message queues are supported. When the value 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.

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. When millisec is 0, the function returns instantly with status osOK. Otherwise the thread is put into the state WAITING. When millisec is set to osWaitForever the function will wait for an infinite time until a message arrives.

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. In this case, the tread is put into the state WAITING. When millisec is set to osWaitForever, the function will wait for an infinite time until a message queue slot becomes available.

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.