CMSIS-RTOS2: Message Queue Functions

| CMSIS-RTOS2 Version 2.1.3 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
Functions
Message Queue Functions
Event functions

Events generated by message queue functions. More...

## Functions
void | EvrRtxMessageQueueError (osMessageQueueId_t mq_id, int32_t status)
| Event on message queue error (Error) More...
void | EvrRtxMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
| Event on message queue create and initialization (API) More...
void | EvrRtxMessageQueueCreated (osMessageQueueId_t mq_id, const char *name)
| Event on successful message queue create (Op) More...
void | EvrRtxMessageQueueGetName (osMessageQueueId_t mq_id, const char *name)
| Event on message queue name retrieve(API) More...
void | EvrRtxMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)
| Event on message put (API) More...
void | EvrRtxMessageQueuePutPending (osMessageQueueId_t mq_id, const void *msg_ptr, uint32_t timeout)
| Event on pending message put (Op) More...
void | EvrRtxMessageQueuePutTimeout (osMessageQueueId_t mq_id)
| Event on message put timeout (Op) More...
void | EvrRtxMessageQueueInsertPending (osMessageQueueId_t mq_id, const void *msg_ptr)
| Event on pending message insert (Op) More...
void | EvrRtxMessageQueueInserted (osMessageQueueId_t mq_id, const void *msg_ptr)
| Event on successful message insert (Op) More...
void | EvrRtxMessageQueueNotInserted (osMessageQueueId_t mq_id, const void *msg_ptr)
| Event on unsuccessful message insert (Op) More...
void | EvrRtxMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
| Event on message get (API) More...
void | EvrRtxMessageQueueGetPending (osMessageQueueId_t mq_id, void *msg_ptr, uint32_t timeout)
| Event on pending message get (Op) More...
void | EvrRtxMessageQueueGetTimeout (osMessageQueueId_t mq_id)
| Event on message get timeout (Op) More...
void | EvrRtxMessageQueueRetrieved (osMessageQueueId_t mq_id, void *msg_ptr)
| Event on successful message get (Op) More...
void | EvrRtxMessageQueueNotRetrieved (osMessageQueueId_t mq_id, void *msg_ptr)
| Event on unsuccessful message get (Op) More...
void | EvrRtxMessageQueueGetCapacity (osMessageQueueId_t mq_id, uint32_t capacity)
| Event on message queue capacity retrieve (API) More...
void | EvrRtxMessageQueueGetMsgSize (osMessageQueueId_t mq_id, uint32_t msg_size)
| Event on message queue message size retrieve (API) More...
void | EvrRtxMessageQueueGetCount (osMessageQueueId_t mq_id, uint32_t count)
| Event on message queue message count retrieve (API) More...
void | EvrRtxMessageQueueGetSpace (osMessageQueueId_t mq_id, uint32_t space)
| Event on message queue message slots retrieve (API) More...
void | EvrRtxMessageQueueReset (osMessageQueueId_t mq_id)
| Event on message queue reset (API) More...
void | EvrRtxMessageQueueResetDone (osMessageQueueId_t mq_id)
| Event on successful message queue reset (Op) More...
void | EvrRtxMessageQueueDelete (osMessageQueueId_t mq_id)
| Event on message queue delete (API) More...
void | EvrRtxMessageQueueDestroyed (osMessageQueueId_t mq_id)
| Event on successful message queue delete (Op) More...

## Description

## Function Documentation

void EvrRtxMessageQueueError | ( | osMessageQueueId_t | mq_id,
|  | int32_t | status
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew or NULL when ID is unknown.
  [in] | status | extended execution status.

The event MessageQueueError is generated when Message Queue routines complete their execution due to an error.

The status parameter indicates the execution status and can be one of the osStatus_t codes or one of the extended execution status codes which are summarized in the table below.

Extended Status Code | Description
--- | ---
osRtxErrorKernelNotReady | Kernel scheduler is not in Ready state.
osRtxErrorKernelNotRunning | Kernel scheduler is not executing - there is no running thread.
osRtxErrorInvalidControlBlock | Object control block with invalid alignment or size was specified.
osRtxErrorInvalidDataMemory | Object data memory with invalid alignment or size was specified.
osRtxErrorInvalidThreadStack | Thread stack memory with invalid alignment or size was specified.
osRtxErrorInvalidPriority | Invalid thread priority was specified.
osRtxErrorThreadNotJoinable | Specified thread is not joinable.
osRtxErrorMutexNotOwned | Specified mutex is not owned by the current running thread.
osRtxErrorMutexNotLocked | Specified mutex is not locked.
osRtxErrorMutexLockLimit | Maximum number of recursive mutex locks reached.
osRtxErrorSemaphoreCountLimit | Semaphore count limit reached.
osRtxErrorTZ_InitContext_S | Secure context memory system initialization failed.
osRtxErrorTZ_AllocContext_S | Secure context memory allocation failed.
osRtxErrorTZ_FreeContext_S | Secure context memory deallocation failed.
osRtxErrorTZ_LoadContext_S | Secure context load failed.
osRtxErrorTZ_SaveContext_S | Secure context save failed.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- status : execution status code.

void EvrRtxMessageQueueNew | ( | 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.

The event MessageQueueNew is generated when the function osMessageQueueNew is called.

Value in the Event Recorder shows:

- msg_count : maximum number of messages in queue.
- msg_size : maximum message size in bytes.
- attr : memory address of Message Queue attributes or 0 when they are not specified.

In case when message queue attributes are provided in the API call they are also detailed in the Event Recorder.

void EvrRtxMessageQueueCreated | ( | osMessageQueueId_t | mq_id,
|  | const char * | name
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | name | pointer to message queue object name.

The event MessageQueueCreated is generated when the function osMessageQueueNew successfully creates a message queue object.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueGetName | ( | osMessageQueueId_t | mq_id,
|  | const char * | name
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | name | pointer to message queue object name.

The event MessageQueueGetName is generated when the function osMessageQueueGetName is called and its execution result is known.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- name : retrieved memory address of name string (0 in case of a failure).

void EvrRtxMessageQueuePut | ( | 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.

The event MessageQueuePut is generated when the function osMessageQueuePut is called.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of message buffer.
- msg_prio : message priority.
- timeout : Timeout Value.

void EvrRtxMessageQueuePutPending | ( | osMessageQueueId_t | mq_id,
|  | const void * | msg_ptr,
|  | 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] | timeout | Timeout Value or 0 in case of no time-out.

The event MessageQueuePutPending is generated when the function osMessageQueuePut starts waiting to put message into the queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of message buffer.
- timeout : Timeout Value.

void EvrRtxMessageQueuePutTimeout | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueuePutTimeout is generated when the function osMessageQueuePut fails to insert a message into the queue until timeout expires.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueInsertPending | ( | osMessageQueueId_t | mq_id,
|  | const void * | msg_ptr
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer with message to put into a queue.

The event MessageQueueInsertPending is generated when the function osMessageQueuePut is called from ISR and message is registered to be put into the queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of message buffer.

void EvrRtxMessageQueueInserted | ( | osMessageQueueId_t | mq_id,
|  | const void * | msg_ptr
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer with message to put into a queue.

The event MessageQueueInserted is generated when a message is successfully inserted into the queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of message buffer.

void EvrRtxMessageQueueNotInserted | ( | osMessageQueueId_t | mq_id,
|  | const void * | msg_ptr
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer with message to put into a queue.

The event MessageQueueNotInserted is generated when the function osMessageQueuePut fails to insert a message into the queue. Usually this happens when queue is out of memory.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of message buffer.

void EvrRtxMessageQueueGet | ( | osMessageQueueId_t | mq_id,
|  | 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 for message to get from a queue.
  [in] | msg_prio | message priority.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

The event MessageQueueGet is generated when the function osMessageQueueGet is called.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of buffer for message.
- msg_prio : memory address of buffer for message priority.
- timeout : Timeout Value.

void EvrRtxMessageQueueGetPending | ( | osMessageQueueId_t | mq_id,
|  | void * | msg_ptr,
|  | uint32_t | timeout
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer for message to get from a queue.
  [in] | timeout | Timeout Value or 0 in case of no time-out.

The event MessageQueueGetPending is generated when the function osMessageQueueGet starts waiting for message to be retrieved from the queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of buffer for message.
- timeout : Timeout Value.

void EvrRtxMessageQueueGetTimeout | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueueGetTimeout is generated when the function osMessageQueueGet is called and there is no message available in queue until timeout expires.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueRetrieved | ( | osMessageQueueId_t | mq_id,
|  | void * | msg_ptr
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer for message to get from a queue.

The event MessageQueueRetrieved is generated when message is retrieved from the message queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of buffer for message.

void EvrRtxMessageQueueNotRetrieved | ( | osMessageQueueId_t | mq_id,
|  | void * | msg_ptr
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_ptr | pointer to buffer for message to get from a queue.

The event MessageQueueNotRetrieved is generated when the function osMessageQueueGet is called without the wait timeout and there is no message available in queue.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_ptr : memory address of buffer for message.

void EvrRtxMessageQueueGetCapacity | ( | osMessageQueueId_t | mq_id,
|  | uint32_t | capacity
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | capacity | maximum number of messages.

The event MessageQueueGetCapacity is generated when the function osMessageQueueGetCapacity is called and its execution result is known.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- capacity : retrieved maximum number of messages (0 in case of a failure).

void EvrRtxMessageQueueGetMsgSize | ( | osMessageQueueId_t | mq_id,
|  | uint32_t | msg_size
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | msg_size | maximum message size in bytes.

The event MessageQueueGetMsgSize is generated when the function osMessageQueueGetMsgSize is called and its execution result is known.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- msg_size : retrieved maximum message size in bytes (0 in case of a failure).

void EvrRtxMessageQueueGetCount | ( | osMessageQueueId_t | mq_id,
|  | uint32_t | count
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | count | number of queued messages.

The event MessageQueueGetCount is generated when the function osMessageQueueGetCount is called and its execution result is known.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- count : retrieved number of queued messages (0 in case of a failure).

void EvrRtxMessageQueueGetSpace | ( | osMessageQueueId_t | mq_id,
|  | uint32_t | space
| ) |  |

Parameters

  [in] | mq_id | message queue ID obtained by osMessageQueueNew.
  [in] | space | number of available slots for messages.

The event MessageQueueGetSpace is generated when the function osMessageQueueGetSpace is called and its execution result is known.

Value in the Event Recorder shows:

- mq_id : message queue ID.
- space : retrieved number of available slots for messages (0 in case of a failure).

void EvrRtxMessageQueueReset | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueueReset is generated when the function osMessageQueueReset is called.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueResetDone | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueueResetDone is generated when the function osMessageQueueReset successfully completes message queue reset.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueDelete | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueueDelete is generated when the function osMessageQueueDelete is called.

Value in the Event Recorder shows:

- mq_id : message queue ID.

void EvrRtxMessageQueueDestroyed | ( | osMessageQueueId_t | mq_id | ) |

Parameters

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

The event MessageQueueDestroyed is generated when the function osMessageQueueDelete successfully deletes the message queue object.

Value in the Event Recorder shows:

- mq_id : message queue ID.