Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Mailbox APIs

Data Structures

struct  k_mbox_msg
 Mailbox Message Structure. More...
 
struct  k_mbox
 Mailbox Structure. More...
 

Macros

#define K_MBOX_DEFINE(name)
 Statically define and initialize a mailbox. More...
 

Functions

void k_mbox_init (struct k_mbox *mbox)
 Initialize a mailbox. More...
 
int k_mbox_put (struct k_mbox *mbox, struct k_mbox_msg *tx_msg, k_timeout_t timeout)
 Send a mailbox message in a synchronous manner. More...
 
void k_mbox_async_put (struct k_mbox *mbox, struct k_mbox_msg *tx_msg, struct k_sem *sem)
 Send a mailbox message in an asynchronous manner. More...
 
int k_mbox_get (struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer, k_timeout_t timeout)
 Receive a mailbox message. More...
 
void k_mbox_data_get (struct k_mbox_msg *rx_msg, void *buffer)
 Retrieve mailbox message data into a buffer. More...
 

Detailed Description

Macro Definition Documentation

◆ K_MBOX_DEFINE

#define K_MBOX_DEFINE (   name)

#include <include/kernel.h>

Value:
Z_MBOX_INITIALIZER(name) \
#define STRUCT_SECTION_ITERABLE(struct_type, name)
Defines a new iterable section.
Definition: common.h:199
Mailbox Structure.
Definition: kernel.h:4596

Statically define and initialize a mailbox.

The mailbox is to be accessed outside the module where it is defined using:

extern struct k_mbox <name>;
Parameters
nameName of the mailbox.

Function Documentation

◆ k_mbox_async_put()

void k_mbox_async_put ( struct k_mbox mbox,
struct k_mbox_msg tx_msg,
struct k_sem *  sem 
)

#include <include/kernel.h>

Send a mailbox message in an asynchronous manner.

This routine sends a message to mbox without waiting for a receiver to process it. The message data may be in a buffer, in a memory pool block, or non-existent (i.e. an empty message). Optionally, the semaphore sem will be given when the message has been both received and completely processed by the receiver.

Parameters
mboxAddress of the mailbox.
tx_msgAddress of the transmit message descriptor.
semAddress of a semaphore, or NULL if none is needed.
Returns
N/A

◆ k_mbox_data_get()

void k_mbox_data_get ( struct k_mbox_msg rx_msg,
void buffer 
)

#include <include/kernel.h>

Retrieve mailbox message data into a buffer.

This routine completes the processing of a received message by retrieving its data into a buffer, then disposing of the message.

Alternatively, this routine can be used to dispose of a received message without retrieving its data.

Parameters
rx_msgAddress of the receive message descriptor.
bufferAddress of the buffer to receive data, or NULL to discard the data.
Returns
N/A

◆ k_mbox_get()

int k_mbox_get ( struct k_mbox mbox,
struct k_mbox_msg rx_msg,
void buffer,
k_timeout_t  timeout 
)

#include <include/kernel.h>

Receive a mailbox message.

This routine receives a message from mbox, then optionally retrieves its data and disposes of the message.

Parameters
mboxAddress of the mailbox.
rx_msgAddress of the receive message descriptor.
bufferAddress of the buffer to receive data, or NULL to defer data retrieval and message disposal until later.
timeoutWaiting period for a message to be received, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0Message received.
-ENOMSGReturned without waiting.
-EAGAINWaiting period timed out.

◆ k_mbox_init()

void k_mbox_init ( struct k_mbox mbox)

#include <include/kernel.h>

Initialize a mailbox.

This routine initializes a mailbox object, prior to its first use.

Parameters
mboxAddress of the mailbox.
Returns
N/A

◆ k_mbox_put()

int k_mbox_put ( struct k_mbox mbox,
struct k_mbox_msg tx_msg,
k_timeout_t  timeout 
)

#include <include/kernel.h>

Send a mailbox message in a synchronous manner.

This routine sends a message to mbox and waits for a receiver to both receive and process it. The message data may be in a buffer, in a memory pool block, or non-existent (i.e. an empty message).

Parameters
mboxAddress of the mailbox.
tx_msgAddress of the transmit message descriptor.
timeoutWaiting period for the message to be received, or one of the special values K_NO_WAIT and K_FOREVER. Once the message has been received, this routine waits as long as necessary for the message to be completely processed.
Return values
0Message sent.
-ENOMSGReturned without waiting.
-EAGAINWaiting period timed out.