![]() |
CMSIS-RTOS
Version 1.02
CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.
|
Control, send, receive, or wait for mail. More...
Macros | |
#define | osFeature_MailQ 1 |
Mail Queues: 1=available, 0=not available. | |
#define | osMailQDef(name, queue_sz, type) |
Create a Mail Queue Definition. | |
#define | osMailQ(name) &os_mailQ_def_##name |
Access a Mail Queue Definition. | |
Functions | |
osMailQId | osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id) |
Create and Initialize mail queue. | |
void * | osMailAlloc (osMailQId queue_id, uint32_t millisec) |
Allocate a memory block from a mail. | |
void * | osMailCAlloc (osMailQId queue_id, uint32_t millisec) |
Allocate a memory block from a mail and set memory block to zero. | |
osStatus | osMailPut (osMailQId queue_id, void *mail) |
Put a mail to a queue. | |
osEvent | osMailGet (osMailQId queue_id, uint32_t millisec) |
Get a mail from a queue. | |
osStatus | osMailFree (osMailQId queue_id, void *mail) |
Free a memory block from a mail. | |
The Mail Queue Management function group allow to control, send, receive, or wait for mail. A mail is a memory block that is sent to a thread or interrupt service routine. The memory block needs to be allocated before putting data in and freed after taking data out. Memory blocks can hold and transfer data structures. This is an advantage over messages that can transfer only a 32-bit value or a pointer.
#define osFeature_MailQ 1 |
A CMSIS-RTOS implementation may support mail queues.
#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 | timeout 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 tread 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 | timeout 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 | timeout 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.