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

Description

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.

CMSIS-RTOS Mail Queue

Working with Mail Queues

Follow these steps to create and use a mail queue:

Declare a data structure that combines a number of elements:
typedef struct {

uint32_t length;

uint32_t width;

uint32_t height;

uint32_t weight;

} properties_t;
Declare a mail queue made up of these objects:
osMailQDef (object_pool_q, 10, properties_t); // Declare mail queue

osMailQId (object_pool_q_id); // Mail queue ID
Then, create the mail pool in a thread:
object_pool_q_id = osMailCreate(osMailQ(object_pool_q), NULL);
Allocate the mail queue within a thread and fill it with data:
properties_t *object_data;

object_data = (properties_t *) osMailAlloc(object_pool_q_id, osWaitForever);

object_data->length = 100;

object_data->width = 10;

object_data->height = 23;

object_data->weight = 1000;
Pass the pointer to the mail queue to another thread:
osMailPut(object_pool_q_id, object_data);
Access the data in another thread:
osEvent event = osMailGet(properties_q_id, osWaitForever);

properties_t *received = (properties_t *)event.value.p; // ".p" indicates that the message is a pointer

my_length(received->length);
Once the data has been used, the memory block must be freed so that the memory pool can be reused
osMailFree(object_pool_q_id, received);

Macro Definition Documentation

#define osFeature_MailQ 1

A CMSIS-RTOS implementation may support mail queues.

When osFeature_MailQ is 1 mail queues are supported.
When osFeature_MailQ is 0 no mail queues are supported.

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.

Parameters

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

Note: The parameter thread registers the receiving thread for a mail and is needed for the general osWait function to deliver the mail.

Parameters

name	name of the queue
queue_sz	maximum number of messages in queue
type	data 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_id	mail queue ID obtained with osMailCreate.
[in]	millisec	Timout 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.

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:

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a mail slot can be allocated.
all other values specify a time in millisecond for a timeout.

Note: The parameter millisec must be 0 for using this function in an ISR.; Interrupt Service Routines can call this function.

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
	)

Parameters

[in]	queue_id	mail queue ID obtained with osMailCreate.
[in]	millisec	Timout 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.

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:

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a mail slot can be allocated.
all other values specify a time in millisecond for a timeout.

Note: The parameter millisec must be 0 for using this function in an ISR.; Interrupt Service Routines can call this function.

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
	)

Parameters

[in]	queue_def	reference to the mail queue definition obtain with osMailQ
[in]	thread_id	thread 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.

Note: Cannot be called from Interrupt Service Routines.

Code 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_id	mail queue ID obtained with osMailCreate.
[in]	mail	pointer 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.

Note: Interrupt Service Routines can call this function.

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_id	mail queue ID obtained with osMailCreate.
[in]	millisec	Timout 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.

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:

when millisec is 0, the function returns instantly.
when millisec is set to osWaitForever the function will wait for an infinite time until a mail arrives.
all other values specify a time in millisecond for a timeout.

Note: The parameter millisec must be 0 for using this function in an ISR.; Interrupt Service Routines can call this function.

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_id	mail queue ID obtained with osMailCreate.
[in]	mail	memory 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.

Macros

Functions

Description

Working with Mail Queues

Macro Definition Documentation

Function Documentation