Control, send, receive, or wait for mail. 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

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

CMSIS-RTOS Mail Queue

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.

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

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

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.

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.

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

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

Macro Definition Documentation

Function Documentation