CMSIS-RTOS RTX: Mail Queue Management

| CMSIS-RTOS RTX Version 4.80 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- 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 (RTX)

Control, send, receive, or wait for mail. More...

## Macros
#define | osFeature_MailQ 1
| Mail Queues 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 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.

CMSIS-RTOS Mail Queue

## Macro Definition Documentation

#define osFeature_MailQ 1

CMSIS-RTOS RTX supports mail queues.

#define osMailQ | ( |  | name | ) | &os_mailQ_def_##name

Access to the mail queue definition for the function osMailCreate.

Parameters

  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.

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

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

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.

Note
  Interrupt Service Routines can call this function.

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.

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.

Note
  Interrupt Service Routines can call this function.

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.

Initialize and create a mail queue.

Note
  Cannot be called from Interrupt Service Routines.

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.

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.

Note
  Interrupt Service Routines can call this function.

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.

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.

Note
  Interrupt Service Routines can call this function.

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.

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.

Note
  Interrupt Service Routines can call this function.