CMSIS-RTOS2
Version 2.1.3
Real-Time Operating System: API and RTX Reference Implementation
|
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 Message Queue. 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... | |
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:
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.
struct osMessageQueueAttr_t |
Specifies the following attributes for the osMessageQueueNew function.
Data Fields | ||
---|---|---|
const char * | name |
name of the message queue Pointer to a constant string with a human readable name (displayed during debugging) of the message queue object. Default: NULL no name specified. |
uint32_t | attr_bits |
attribute bits Reserved for future use (must be set to '0' for future compatibility). |
void * | cb_mem |
memory for control block Pointer to a memory for the message queue control block object. Refer to Static Object Memory for more information. Default: NULL to use Automatic Dynamic Allocation for the message queue control block. |
uint32_t | cb_size |
size of provided memory for control block The size (in bytes) of memory block passed with cb_mem. For RTX, the minimum value is defined with osRtxMessageQueueCbSize (higher values are permitted). Default: 0 as the default is no memory provided with cb_mem. |
void * | mq_mem |
memory for data storage Pointer to a memory for the message queue data. Refer to Static Object Memory for more information. Default: NULL to use Automatic Dynamic Allocation for the memory pool data. |
uint32_t | mq_size |
size of provided memory for data storage The size (in bytes) of memory block passed with mq_mem. The minimum memory block size is Default: 0 as the default is no memory provided with mq_mem. |
osMessageQueueId_t osMessageQueueNew | ( | uint32_t | msg_count, |
uint32_t | msg_size, | ||
const osMessageQueueAttr_t * | attr | ||
) |
[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 function osMessageQueueNew creates and initializes a message queue object. The function returns a message queue object identifier or NULL in case of an error.
The function can be called after kernel initialization with osKernelInitialize. It is possible to create message queue objects before the RTOS kernel is started with osKernelStart.
The total amount of memory required for the message queue data is at least msg_count * msg_size
. The msg_size is rounded up to a double even number to ensure 32-bit alignment of the memory blocks.
The memory blocks allocated from the message queue have a fixed size defined with the parameter msg_size
.
Code Example
Refer to osMessageQueuePut
const char * osMessageQueueGetName | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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.
osStatus_t osMessageQueuePut | ( | osMessageQueueId_t | mq_id, |
const void * | msg_ptr, | ||
uint8_t | msg_prio, | ||
uint32_t | timeout | ||
) |
[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 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:
Possible osStatus_t return values:
Code Example:
osStatus_t osMessageQueueGet | ( | osMessageQueueId_t | mq_id, |
void * | msg_ptr, | ||
uint8_t * | msg_prio, | ||
uint32_t | timeout | ||
) |
[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. |
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:
Possible osStatus_t return values:
Code Example
Refer to osMessageQueuePut
uint32_t osMessageQueueGetCapacity | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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.
uint32_t osMessageQueueGetMsgSize | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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.
uint32_t osMessageQueueGetCount | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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.
uint32_t osMessageQueueGetSpace | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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.
osStatus_t osMessageQueueReset | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
The function osMessageQueueReset resets the message queue specified by the parameter mq_id.
Possible osStatus_t return values:
osStatus_t osMessageQueueDelete | ( | osMessageQueueId_t | mq_id | ) |
[in] | mq_id | message queue ID obtained by osMessageQueueNew. |
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: