CMSIS-RTOS2: Message Queue

| CMSIS-RTOS2 Version 2.1.1 Real-Time Operating System: API and RTX Reference Implementation

- Main Page
- Usage and Description
- Reference

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

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:

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
  The functions osMessageQueuePut, osMessageQueueGet, osMessageQueueGetCapacity, osMessageQueueGetMsgSize, osMessageQueueGetCount, osMessageQueueGetSpace can be called from Interrupt Service Routines.
  Refer to Message Queue Configuration for RTX5 configuration options.

## Data Structure Documentation

struct osMessageQueueAttr_t

Attributes structure for message queue.

Data Fields
const char * | name | name of the message queue Pointer to a string with a human readable name of the message queue object. Default: NULL.
uint32_t | attr_bits | attribute bits Reserved for future use (set to '0'). Default: 0.
void * | cb_mem | memory for control block Pointer to a memory location for the message queue control block object. This can optionally be used for custom memory management systems. Default: NULL (uses kernel memory management).
uint32_t | cb_size | size of provided memory for control block The size of the memory block passed with cb_mem. Must be the size of a message queue control block object or larger.
void * | mq_mem | memory for data storage Pointer to a memory location for the data of the message queue object. Default: NULL.
uint32_t | mq_size | size of provided memory for data storage The size of the memory passed with mq_mem.

## Function Documentation

osMessageQueueId_t osMessageQueueNew | ( | uint32_t | msg_count,
|  | uint32_t | msg_size,
|  | const osMessageQueueAttr_t * | attr
| ) |  |

Parameters

  [in] | msg_count | maximum number of messages in queue.
  [in] | msg_size | maximum message size in bytes.
  [in] | attr | message queue attributes; NULL: default values.

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

The function osMessageQueueNew creates and initializes a message queue object and returns the pointer to the message queue object identifier or NULL in case of an error. It can be safely called before the RTOS is started (call to osKernelStart), but not before it is initialized (call to osKernelInitialize).

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

Refer to osMessageQueuePut

const char * osMessageQueueGetName | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

Returns
  name as NULL terminated string.

The function osMessageQueueGetName returns the pointer to the name string of the message queue identified by parameter mq_id or NULL in case of an error.

Note
  This function cannot be called from Interrupt Service Routines.

*osStatus_t osMessageQueuePut | ( | osMessageQueueId_t | mq_id,
|  | const void * | msg_ptr,
|  | uint8_t | msg_prio,
|  | uint32_t | timeout
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer with message to put into a queue.
  [in] | msg_prio | message priority.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

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

The blocking function osMessageQueuePut puts the message pointed to by msg_ptr into the the message queue specified by parameter mq_id. The parameter msg_prio is used to sort message according their priority (higher numbers indicate a higher priority) on insertion.

The parameter timeout specifies how long the system waits to put the message into the queue. While the system waits, the thread that is calling this function is put into the BLOCKED state. The parameter timeout can have the following values:

- when timeout is 0, the function returns instantly (i.e. try semantics).
- when timeout is set to osWaitForever the function will wait for an infinite time until the message is delivered (i.e. wait semantics).
- all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).

Possible osStatus_t return values:

- osOK: the message has been put into the queue.
- osErrorTimeout: the message could not be put into the queue in the given time (wait-timed semantics).
- osErrorResource: not enough space in the queue (try semantics).
- osErrorParameter: the parameter mq_id is incorrect, non-zero timeout specified in an ISR.

Note
  May be called from Interrupt Service Routines if the parameter timeout is set to 0.

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;
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 msg;
while (1) {
; // Insert thread code here...
msg.Buf[0] = 0x55; // do some work...
msg.Idx = 0;
osMessageQueuePut (mid_MsgQueue, &msg, 0, NULL);
osThreadYield (); // suspend thread
}
}
void Thread_MsgQueue2 (void *argument) {
MSGQUEUE_OBJ_t msg;
osStatus_t status;
while (1) {
; // Insert thread code here...
status = osMessageQueueGet (mid_MsgQueue, &msg, 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_id | message queue ID obtained by osMessageQueueNew.
  [out] | msg_ptr | pointer to buffer for message to get from a queue.
  [out] | msg_prio | pointer to buffer for message priority or NULL.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

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

The function osMessageQueueGet retrieves a message from the message queue specified by the parameter mq_id and saves it to the buffer pointed to by the parameter msg_ptr. The message priority is stored to parameter msg_prio if not token{NULL}.

The parameter timeout specifies how long the system waits to retrieve the message from the queue. While the system waits, the thread that is calling this function is put into the BLOCKED state. The parameter timeout can have the following values:

- when timeout is 0, the function returns instantly (i.e. try semantics).
- when timeout is set to osWaitForever the function will wait for an infinite time until the message is retrieved (i.e. wait semantics).
- all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).

Possible osStatus_t return values:

- osOK: the message has been retrieved from the queue.
- osErrorTimeout: the message could not be retrieved from the queue in the given time (timed-wait semantics).
- osErrorResource: nothing to get from the queue (try semantics).
- osErrorParameter: the parameter mq_id is incorrect, non-zero timeout specified in an ISR.

Note
  May be called from Interrupt Service Routines if the parameter timeout is set to 0.

Code Example

Refer to osMessageQueuePut

uint32_t osMessageQueueGetCapacity | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

Returns
  maximum number of messages.

The function osMessageQueueGetCapacity returns the maximum number of messages in the message queue object specified by parameter mq_id or 0 in case of an error.

Note
  This function may be called from Interrupt Service Routines.

uint32_t osMessageQueueGetMsgSize | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

Returns
  maximum message size in bytes.

The function osMessageQueueGetMsgSize returns the maximum message size in bytes for the message queue object specified by parameter mq_id or 0 in case of an error.

Note
  This function may be called from Interrupt Service Routines.

uint32_t osMessageQueueGetCount | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

Returns
  number of queued messages.

The function osMessageQueueGetCount returns the number of queued messages in the message queue object specified by parameter mq_id or 0 in case of an error.

Note
  This function may be called from Interrupt Service Routines.

uint32_t osMessageQueueGetSpace | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

Returns
  number of available slots for messages.

The function osMessageQueueGetSpace returns the number available slots for messages in the message queue object specified by parameter mq_id or 0 in case of an error.

Note
  This function may be called from Interrupt Service Routines.

osStatus_t osMessageQueueReset | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

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

The function osMessageQueueReset resets the message queue specified by the parameter mq_id.

Possible osStatus_t return values:

- osOK: the message queue has been rest.
- osErrorParameter: parameter mq_id is NULL or invalid.
- osErrorResource: the message queue specified by parameter mq_id is in an invalid message queue state.
- osErrorISR: osMessageQueueReset cannot be called from interrupt service routines.

Note
  This function cannot be called from Interrupt Service Routines.

osStatus_t osMessageQueueDelete | ( | osMessageQueueId_t | mq_id | ) |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.

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

The function osMessageQueueDelete deletes a message queue object specified by parameter mq_id. It releases internal memory obtained for message queue handling. After this call, the mq_id is no longer valid and cannot be used. The message queue may be created again using the function osMessageQueueNew.

Possible osStatus_t return values:

- osOK: the message queue object has been deleted.
- osErrorParameter: parameter mq_id is NULL or invalid.
- osErrorResource: the message queue specified by parameter mq_id is in an invalid message queue state.
- osErrorISR: osMessageQueueDelete cannot be called from interrupt service routines.

Note
  This function cannot be called from Interrupt Service Routines.