Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
MBOX Interface

MBOX Interface . More...

Data Structures

struct  mbox_msg
 Message struct (to hold data and its size). More...
 
struct  mbox_dt_spec
 MBOX specification from DT. More...
 

Macros

#define MBOX_DT_SPEC_GET(node_id, name)
 Structure initializer for struct mbox_dt_spec from devicetree.
 
#define MBOX_DT_SPEC_INST_GET(inst, name)
 Instance version of MBOX_DT_CHANNEL_GET()
 

Typedefs

typedef uint32_t mbox_channel_id_t
 Type for MBOX channel identifiers.
 

Functions

static bool mbox_is_ready_dt (const struct mbox_dt_spec *spec)
 Validate if MBOX device instance from a struct mbox_dt_spec is ready.
 
int mbox_send (const struct device *dev, mbox_channel_id_t channel_id, const struct mbox_msg *msg)
 Try to send a message over the MBOX device.
 
static int mbox_send_dt (const struct mbox_dt_spec *spec, const struct mbox_msg *msg)
 Try to send a message over the MBOX device from a struct mbox_dt_spec.
 
static int mbox_register_callback (const struct device *dev, mbox_channel_id_t channel_id, mbox_callback_t cb, void *user_data)
 Register a callback function on a channel for incoming messages.
 
static int mbox_register_callback_dt (const struct mbox_dt_spec *spec, mbox_callback_t cb, void *user_data)
 Register a callback function on a channel for incoming messages from a struct mbox_dt_spec.
 
int mbox_mtu_get (const struct device *dev)
 Return the maximum number of bytes possible in an outbound message.
 
static int mbox_mtu_get_dt (const struct mbox_dt_spec *spec)
 Return the maximum number of bytes possible in an outbound message from struct mbox_dt_spec.
 
int mbox_set_enabled (const struct device *dev, mbox_channel_id_t channel_id, bool enabled)
 Enable (disable) interrupts and callbacks for inbound channels.
 
static int mbox_set_enabled_dt (const struct mbox_dt_spec *spec, bool enabled)
 Enable (disable) interrupts and callbacks for inbound channels from a struct mbox_dt_spec.
 
uint32_t mbox_max_channels_get (const struct device *dev)
 Return the maximum number of channels.
 
static int mbox_max_channels_get_dt (const struct mbox_dt_spec *spec)
 Return the maximum number of channels from a struct mbox_dt_spec.
 

Detailed Description

MBOX Interface .

Since
1.0
Version
0.1.0
CPU #1 |
+----------+ | +----------+
| +---TX9----+ +--------+--RX8---+ |
| dev A | | | | | CPU #2 |
| <---RX8--+ | | +------+--TX9---> |
+----------+ | | | | | +----------+
+--+-v---v-+--+ |
| | |
| MBOX dev | |
| | |
+--+-^---^--+-+ |
+----------+ | | | | | +----------+
| <---RX2--+ | | +-----+--TX3---> |
| dev B | | | | | CPU #3 |
| +---TX3----+ +--------+--RX2---+ |
+----------+ | +----------+
|

An MBOX device is a peripheral capable of passing signals (and data depending on the peripheral) between CPUs and clusters in the system. Each MBOX instance is providing one or more channels, each one targeting one other CPU cluster (multiple channels can target the same cluster).

For example in the plot the device 'dev A' is using the TX channel 9 to signal (or send data to) the CPU #2 and it's expecting data or signals on the RX channel 8. Thus it can send the message through the channel 9, and it can register a callback on the channel 8 of the MBOX device.

This API supports two modes: signalling mode and data transfer mode.

In signalling mode:

In data transfer mode:

Macro Definition Documentation

◆ MBOX_DT_SPEC_GET

#define MBOX_DT_SPEC_GET ( node_id,
name )

#include <zephyr/drivers/mbox.h>

Value:
{ \
.dev = DEVICE_DT_GET(DT_MBOX_CTLR_BY_NAME(node_id, name)), \
.channel_id = DT_MBOX_CHANNEL_BY_NAME(node_id, name), \
}
#define DEVICE_DT_GET(node_id)
Get a device reference from a devicetree node identifier.
Definition device.h:255
#define DT_MBOX_CHANNEL_BY_NAME(node_id, name)
Get a MBOX channel value by name.
Definition mbox.h:89
#define DT_MBOX_CTLR_BY_NAME(node_id, name)
Get the node identifier for the MBOX controller from a mboxes property by name.
Definition mbox.h:52

Structure initializer for struct mbox_dt_spec from devicetree.

This helper macro expands to a static initializer for a struct mbox_dt_spec by reading the relevant device controller and channel number from the devicetree.

Example devicetree fragment:

n: node {
mboxes = <&mbox1 8>,
<&mbox1 9>;
mbox-names = "tx", "rx";
};

Example usage:

const struct mbox_dt_spec spec = MBOX_DT_SPEC_GET(DT_NODELABEL(n), tx);
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition devicetree.h:200
#define MBOX_DT_SPEC_GET(node_id, name)
Structure initializer for struct mbox_dt_spec from devicetree.
Definition mbox.h:122
MBOX specification from DT.
Definition mbox.h:87
Parameters
node_idDevicetree node identifier for the MBOX device
namelowercase-and-underscores name of the mboxes element
Returns
static initializer for a struct mbox_dt_spec

◆ MBOX_DT_SPEC_INST_GET

#define MBOX_DT_SPEC_INST_GET ( inst,
name )

#include <zephyr/drivers/mbox.h>

Value:
#define DT_DRV_INST(inst)
Node identifier for an instance of a DT_DRV_COMPAT compatible.
Definition devicetree.h:3759

Instance version of MBOX_DT_CHANNEL_GET()

Parameters
instDT_DRV_COMPAT instance number
namelowercase-and-underscores name of the mboxes element
Returns
static initializer for a struct mbox_dt_spec

Typedef Documentation

◆ mbox_channel_id_t

#include <zephyr/drivers/mbox.h>

Type for MBOX channel identifiers.

Function Documentation

◆ mbox_is_ready_dt()

static bool mbox_is_ready_dt ( const struct mbox_dt_spec * spec)
inlinestatic

#include <zephyr/drivers/mbox.h>

Validate if MBOX device instance from a struct mbox_dt_spec is ready.

Parameters
specMBOX specification from devicetree
Returns
See return values for mbox_send()

◆ mbox_max_channels_get()

uint32_t mbox_max_channels_get ( const struct device * dev)

#include <zephyr/drivers/mbox.h>

Return the maximum number of channels.

Return the maximum number of channels supported by the hardware.

Parameters
devMBOX device instance.
Returns
>0 Maximum possible number of supported channels on success
-errno Negative errno on error.

◆ mbox_max_channels_get_dt()

static int mbox_max_channels_get_dt ( const struct mbox_dt_spec * spec)
inlinestatic

#include <zephyr/drivers/mbox.h>

Return the maximum number of channels from a struct mbox_dt_spec.

Parameters
specMBOX specification from devicetree
Returns
See return values for mbox_max_channels_get()

◆ mbox_mtu_get()

int mbox_mtu_get ( const struct device * dev)

#include <zephyr/drivers/mbox.h>

Return the maximum number of bytes possible in an outbound message.

Returns the actual number of bytes that it is possible to send through an outgoing channel.

This number can be 0 when the driver only supports signalling or when on the receiving side the content and size of the message must be retrieved in an indirect way (i.e. probing some other peripheral, reading memory regions, etc...).

If this function returns 0, the msg parameter in mbox_send() is expected to be NULL.

Parameters
devMBOX device instance.
Return values
>0Maximum possible size of a message in bytes
0Indicates signalling
-errnoNegative errno on error.

◆ mbox_mtu_get_dt()

static int mbox_mtu_get_dt ( const struct mbox_dt_spec * spec)
inlinestatic

#include <zephyr/drivers/mbox.h>

Return the maximum number of bytes possible in an outbound message from struct mbox_dt_spec.

Parameters
specMBOX specification from devicetree
Returns
See return values for mbox_register_callback()

◆ mbox_register_callback()

static int mbox_register_callback ( const struct device * dev,
mbox_channel_id_t channel_id,
mbox_callback_t cb,
void * user_data )
inlinestatic

#include <zephyr/drivers/mbox.h>

Register a callback function on a channel for incoming messages.

This function doesn't assume anything concerning the status of the interrupts. Use mbox_set_enabled() to enable or to disable the interrupts if needed.

Parameters
devMBOX device instance
channel_idMBOX channel identifier
cbCallback function to execute on incoming message interrupts.
user_dataApplication-specific data pointer which will be passed to the callback function when executed.
Return values
0On success.
-errnoNegative errno on error.

◆ mbox_register_callback_dt()

static int mbox_register_callback_dt ( const struct mbox_dt_spec * spec,
mbox_callback_t cb,
void * user_data )
inlinestatic

#include <zephyr/drivers/mbox.h>

Register a callback function on a channel for incoming messages from a struct mbox_dt_spec.

Parameters
specMBOX specification from devicetree
cbCallback function to execute on incoming message interrupts.
user_dataApplication-specific data pointer which will be passed to the callback function when executed.
Returns
See return values for mbox_register_callback()

◆ mbox_send()

int mbox_send ( const struct device * dev,
mbox_channel_id_t channel_id,
const struct mbox_msg * msg )

#include <zephyr/drivers/mbox.h>

Try to send a message over the MBOX device.

Send a message over an struct mbox_channel. The msg parameter must be NULL when the driver is used for signalling.

If the msg parameter is not NULL, this data is expected to be delivered on the receiving side using the data parameter of the receiving callback.

Parameters
devMBOX device instance
channel_idMBOX channel identifier
msgMessage
Return values
0On success.
-EBUSYIf the remote hasn't yet read the last data sent.
-EMSGSIZEIf the supplied data size is unsupported by the driver.
-EINVALIf there was a bad parameter, such as: too-large channel descriptor or the device isn't an outbound MBOX channel.

◆ mbox_send_dt()

static int mbox_send_dt ( const struct mbox_dt_spec * spec,
const struct mbox_msg * msg )
inlinestatic

#include <zephyr/drivers/mbox.h>

Try to send a message over the MBOX device from a struct mbox_dt_spec.

Parameters
specMBOX specification from devicetree
msgMessage
Returns
See return values for mbox_send()

◆ mbox_set_enabled()

int mbox_set_enabled ( const struct device * dev,
mbox_channel_id_t channel_id,
bool enabled )

#include <zephyr/drivers/mbox.h>

Enable (disable) interrupts and callbacks for inbound channels.

Enable interrupt for the channel when the parameter 'enable' is set to true. Disable it otherwise.

Immediately after calling this function with 'enable' set to true, the channel is considered enabled and ready to receive signal and messages (even already pending), so the user must take care of installing a proper callback (if needed) using mbox_register_callback() on the channel before enabling it. For this reason it is recommended that all the channels are disabled at probe time.

Enabling a channel for which there is no installed callback is considered undefined behavior (in general the driver must take care of gracefully handling spurious interrupts with no installed callback).

Parameters
devMBOX device instance
channel_idMBOX channel identifier
enabledEnable (true) or disable (false) the channel.
Return values
0On success.
-EINVALIf it isn't an inbound channel.
-EALREADYIf channel is already enabled.

◆ mbox_set_enabled_dt()

static int mbox_set_enabled_dt ( const struct mbox_dt_spec * spec,
bool enabled )
inlinestatic

#include <zephyr/drivers/mbox.h>

Enable (disable) interrupts and callbacks for inbound channels from a struct mbox_dt_spec.

Parameters
specMBOX specification from devicetree
enabledEnable (true) or disable (false) the channel.
Returns
See return values for mbox_set_enabled()