CMSIS-RTOS RTX: Message Queue Management

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

- 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 (RTX)

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

## Macros
#define | osFeature_MessageQ 1
| Message Queues 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

CMSIS-RTOS RTX supports message queues.

#define osMessageQ | ( |  | name | ) | &os_messageQ_def_##name

Access to the message queue definition for the function osMessageCreate.

Parameters

  name | name of the queue

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

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

Create and initialize a message queue.

Note
  Cannot be called from Interrupt Service Routines.

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 | Timout Value or 0 in case of no time-out.

Returns
  event information that includes status code.

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.

Note
  Interrupt Service Routines can call this function.

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 | Timout Value or 0 in case of no time-out.

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

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.

Note
  Interrupt Service Routines can call this function.