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:

        STRUCT_SECTION_ITERABLE(k_mbox, name) = \
                Z_MBOX_INITIALIZER(name) \

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

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

mbox	Address of the mailbox.
tx_msg	Address of the transmit message descriptor.
sem	Address 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_msg	Address of the receive message descriptor.
buffer	Address 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

mbox	Address of the mailbox.
rx_msg	Address of the receive message descriptor.
buffer	Address of the buffer to receive data, or NULL to defer data retrieval and message disposal until later.
timeout	Waiting period for a message to be received, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Message received.
-ENOMSG	Returned without waiting.
-EAGAIN	Waiting 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

mbox	Address 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

mbox	Address of the mailbox.
tx_msg	Address of the transmit message descriptor.
timeout	Waiting 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

0	Message sent.
-ENOMSG	Returned without waiting.
-EAGAIN	Waiting period timed out.