CMSIS-RTOS
Version 1.03
Real-Time Operating System: API and RTX Reference Implementation.
|
Exchange data between threads using a queue of memory blocks. More...
Macros | |
#define | osFeature_MailQ 1 |
Mail Queues: 1=available, 0=not available. More... | |
#define | osMailQDef(name, queue_sz, type) |
Create a Mail Queue Definition. More... | |
#define | osMailQ(name) &os_mailQ_def_##name |
Access a Mail Queue Definition. More... | |
Functions | |
osMailQId | osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id) |
Create and Initialize mail queue. More... | |
void * | osMailAlloc (osMailQId queue_id, uint32_t millisec) |
Allocate a memory block from a mail. More... | |
void * | osMailCAlloc (osMailQId queue_id, uint32_t millisec) |
Allocate a memory block from a mail and set memory block to zero. More... | |
osStatus | osMailPut (osMailQId queue_id, void *mail) |
Put a mail to a queue. More... | |
osEvent | osMailGet (osMailQId queue_id, uint32_t millisec) |
Get a mail from a queue. More... | |
osStatus | osMailFree (osMailQId queue_id, void *mail) |
Free a memory block from a mail. More... | |
A mail queue resembles a Message Queue, but the data that is being transferred consists of memory blocks that need to be allocated (before putting data in) and freed (after taking data out). The mail queue uses a Memory Pool to create formatted memory blocks and passes pointers to these blocks in a message queue. This allows the data to stay in an allocated memory block while only a pointer is moved between the separate threads. This is an advantage over messages that can transfer only a 32-bit value or a pointer. Using the mail queue functions, you can control, send, receive, or wait for mail.
Follow these steps to create and use a mail queue:
#define osFeature_MailQ 1 |
A CMSIS-RTOS implementation may support mail queues.
CMSIS-RTOS RTX Setting: osFeature_MailQ is 1
#define osMailQ | ( | name | ) | &os_mailQ_def_##name |
Access to the mail queue definition for the function osMailCreate.
name | name of the queue |
#define osMailQDef | ( | name, | |
queue_sz, | |||
type | |||
) |
Define the attributes of a mail queue that can by the function osMailCreate using osMailQ.
name | name of the queue |
queue_sz | maximum number of messages in queue |
type | data type of a single message element |
void * osMailAlloc | ( | osMailQId | queue_id, |
uint32_t | millisec | ||
) |
[in] | queue_id | mail queue ID obtained with osMailCreate. |
[in] | millisec | Timout Value or 0 in case of no time-out |
Allocate a memory block from the mail queue that is filled with the mail information.
The argument queue_id specifies a mail queue identifier that is obtain with osMailCreate.
The argument millisec specifies how long the system waits for a mail slot to become available. While the system waits the thread calling this function is put into the state WAITING. The millisec timeout can have the following values:
A NULL pointer is returned when no memory slot can be obtained or queue specifies an illegal parameter.
void * osMailCAlloc | ( | osMailQId | queue_id, |
uint32_t | millisec | ||
) |
[in] | queue_id | mail queue ID obtained with osMailCreate. |
[in] | millisec | Timout Value or 0 in case of no time-out |
Allocate a memory block from the mail queue that is filled with the mail information. The memory block returned is cleared.
The argument queue_id specifies a mail queue identifier that is obtain with osMailCreate.
The argument millisec specifies how long the system waits for a mail slot to become available. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values:
A NULL pointer is returned when no memory block can be obtained or queue specifies an illegal parameter.
osMailQId osMailCreate | ( | const osMailQDef_t * | queue_def, |
osThreadId | thread_id | ||
) |
[in] | queue_def | reference to the mail queue definition obtain with osMailQ |
[in] | thread_id | thread ID (obtained by osThreadCreate or osThreadGetId) or NULL. |
Initialize and create a mail queue.
Code Example
[in] | queue_id | mail queue ID obtained with osMailCreate. |
[in] | pointer to the memory block that was obtained with osMailGet. |
Free the memory block specified by mail and return it to the mail queue.
[in] | queue_id | mail queue ID obtained with osMailCreate. |
[in] | millisec | Timout Value or 0 in case of no time-out |
Suspend the execution of the current RUNNING thread until a mail arrives. When a mail is already in the queue, the function returns instantly with the mail information.
The argument millisec specifies how long the system waits for a mail to arrive. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values:
[in] | queue_id | mail queue ID obtained with osMailCreate. |
[in] | memory block previously allocated with osMailAlloc or osMailCAlloc. |
Put the memory block specified with mail into the mail queue specified by queue.