CMSIS-RTOS RTX  Version 4.51
CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Mail Queue Management

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.
 
os_InRegs 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.
 

Description

The Mail Queue Management function group allows to control, send, receive, or wait for mail. A mail is a memory block that is send to a thread or interrupt service routine.

MailQueue.png
CMSIS-RTOS Mail Queue

Macro Definition Documentation

#define osFeature_MailQ   1

A CMSIS-RTOS implementation may support mail queues. When the value osFeature_MailQ is 1 mail queues are supported. When the value osFeature_MailQ is 0 no mail queues are supported.

#define osMailQ (   name)    &os_mailQ_def_##name

Access to the mail queue definition for the function osMailCreate.

Parameters
namename of the queue
Note
CAN BE CHANGED: The parameter to osMailQ shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
#define osMailQDef (   name,
  queue_sz,
  type 
)

Define the attributes of a mail queue that can by the function osMailCreate using osMailQ.

Parameters
namename of the queue
queue_szmaximum number of messages in queue
typedata type of a single message element
Note
CAN BE CHANGED: The parameter to osMailQDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

Function Documentation

void * osMailAlloc ( osMailQId  queue_id,
uint32_t  millisec 
)
Parameters
[in]queue_idmail queue ID obtained with osMailCreate.
[in]millisectimeout value or 0 in case of no time-out
Returns
pointer to memory block that can be filled with mail or NULL in case of error.
Note
MUST REMAIN UNCHANGED: osMailAlloc shall be consistent in every CMSIS-RTOS.

Allocate a memory block from the mail queue that is filled with the mail information. When no memory block slot is available, the tread is put into the state WAITING for the time specified with millisec. When millisec is set to osWaitForever the function will wait for an infinite time until a mail queue slot becomes available.

A NULL pointer is returned when no memory slot can be obtained or queue specifies an illegal parameter.

Note
The parameter millisec must be 0 for using this function in an ISR.
void * osMailCAlloc ( osMailQId  queue_id,
uint32_t  millisec 
)
Parameters
[in]queue_idmail queue ID obtained with osMailCreate.
[in]millisectimeout value or 0 in case of no time-out
Returns
pointer to memory block that can be filled with mail or NULL in case of error.
Note
MUST REMAIN UNCHANGED: osMailCAlloc shall be consistent in every CMSIS-RTOS.

Allocate a memory block from the mail queue that is filled with the mail information. The memory block returned is cleared. When no memory block is available, the tread is put into the state WAITING for the time specified with millisec. When millisec is set to osWaitForever the function will wait for an infinite time until a mail queue slot becomes available.

A NULL pointer is returned when no memory block can be obtained or queue specifies an illegal parameter.

Note
The parameter millisec must be 0 for using this function in an ISR.
osMailQId osMailCreate ( const osMailQDef_t queue_def,
osThreadId  thread_id 
)
Parameters
[in]queue_defreference to the mail queue definition obtain with osMailQ
[in]thread_idthread ID (obtained by osThreadCreate or osThreadGetId) or NULL.
Returns
mail queue ID for reference by other functions or NULL in case of error.
Note
MUST REMAIN UNCHANGED: osMailCreate shall be consistent in every CMSIS-RTOS.

Initialize and create a mail queue.

Example:

#include "cmsis_os.h"
osThreadId tid_thread1; // ID for thread 1
osThreadId tid_thread2; // ID for thread 2
typedef struct { // Mail object structure
float voltage; // AD result of measured voltage
float current; // AD result of measured current
int counter; // A counter value
} T_MEAS;
osMailQDef(mail, 16, T_MEAS); // Define mail queue
osMailQId mail;
void send_thread (void const *argument); // forward reference
void recv_thread (void const *argument);
osThreadDef(send_thread, osPriorityNormal, 1, 0); // thread definitions
osThreadDef(recv_thread, osPriorityNormal, 1, 2000);
/*
Thread 1: Send thread
*/
void send_thread (void const *argument) {
T_MEAS *mptr;
mptr = osMailAlloc(mail, osWaitForever); // Allocate memory
mptr->voltage = 223.72; // Set the mail content
mptr->current = 17.54;
mptr->counter = 120786;
osMailPut(mail, mptr); // Send Mail
osDelay(100);
mptr = osMailAlloc(mail, osWaitForever); // Allocate memory
mptr->voltage = 227.23; // Prepare 2nd mail
mptr->current = 12.41;
mptr->counter = 170823;
osMailPut(mail, mptr); // Send Mail
osThreadYield(); // Cooperative multitasking
// We are done here, exit this thread
}
/*
Thread 2: Receive thread
*/
void recv_thread (void const *argument) {
T_MEAS *rptr;
osEvent evt;
for (;;) {
evt = osMailGet(mail, osWaitForever); // wait for mail
if (evt.status == osEventMail) {
rptr = evt.value.p;
printf ("\nVoltage: %.2f V\n", rptr->voltage);
printf ("Current: %.2f A\n", rptr->current);
printf ("Number of cycles: %d\n", rptr->counter);
osMailFree(mail, rptr); // free memory allocated for mail
}
}
}
void StartApplication (void) {
mail = osMailCreate(osMailQ(mail), NULL); // create mail queue
tid_thread1 = osThreadCreate(osThread(send_thread), NULL);
tid_thread2 = osThreadCreate(osThread(recv_thread), NULL);
:
}
osStatus osMailFree ( osMailQId  queue_id,
void *  mail 
)
Parameters
[in]queue_idmail queue ID obtained with osMailCreate.
[in]mailpointer to the memory block that was obtained with osMailGet.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMailFree shall be consistent in every CMSIS-RTOS.

Free the memory block specified by mail and return it to the mail queue.

Status and Error Codes

  • osOK: the mail block is released.
  • osErrorValue: mail block does not belong to the mail queue pool.
  • osErrorParameter: the value to the parameter queue_id is incorrect.
osEvent osMailGet ( osMailQId  queue_id,
uint32_t  millisec 
)
Parameters
[in]queue_idmail queue ID obtained with osMailCreate.
[in]millisectimeout value or 0 in case of no time-out
Returns
event that contains mail information or error code.
Note
MUST REMAIN UNCHANGED: osMailGet shall be consistent in every CMSIS-RTOS.

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. When millisec is 0, the function returns instantly with status osOK. Otherwise the thread is put into the state WAITING. When millisec is set to osWaitForever the function will wait for an infinite time until a mail arrives.

Note
The parameter millisec must be 0 for using this function in an ISR.

Status and Error Codes

  • osOK: no mail is available in the queue and no timeout was specified
  • osEventTimeout: no mail has arrived during the given timeout period.
  • osEventMail: mail received, value.p contains the pointer to mail content.
  • osErrorParameter: a parameter is invalid or outside of a permitted range.
osStatus osMailPut ( osMailQId  queue_id,
void *  mail 
)
Parameters
[in]queue_idmail queue ID obtained with osMailCreate.
[in]mailmemory block previously allocated with osMailAlloc or osMailCAlloc.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osMailPut shall be consistent in every CMSIS-RTOS.

Put the memory block specified with mail into the mail queue specified by queue.

Status and Error Codes

  • osOK: the message is put into the queue.
  • osErrorValue: mail was previously not allocated as memory slot.
  • osErrorParameter: a parameter is invalid or outside of a permitted range.