CMSIS-RTOS: Mail Queue Management

| CMSIS-RTOS Version 1.02 CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.

- CMSIS
- CORE
- DSP
- RTOS API
- SVD

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Mail Queue Management
CMSIS-RTOS API

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.

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.