Mailbox

Mailbox controller class. More...

Modules
	SF32LB52 mailbox
	SiFli SF32LB52 mailbox.

Data Structures
struct	pbl_mbox_chan
	A channel, as used by a consumer. More...
struct	pbl_mbox_client
	Channel client. More...
struct	pbl_mbox_chan_state
	Channel state, kept by the class. More...
struct	pbl_mbox_controller_state
	Controller state, kept by the class. More...
struct	pbl_mbox_controller_ops
	Controller operations, implemented by the providers. More...
struct	pbl_mbox_controller
	Mailbox controller. More...

Macros
#define	PBL_MBOX_MAX_CELLS   2U
	Maximum number of specifier cells.
#define	PBL_MBOX_CHAN(_ctrl, ...)
	Initializer of a struct pbl_mbox_chan.
#define	PBL_MBOX_CONTROLLER_STATE_DEFINE(sym, _num_chans)
	Define the state of a controller, for providers.
#define	PBL_MBOX_CONTROLLER_INIT(sym, _name, _init, _deps, _ops, _txpoll_period_ms)
	Initializer of a struct pbl_mbox_controller, for providers.

Functions
int	pbl_mbox_request (const struct pbl_mbox_chan *chan, const struct pbl_mbox_client *cl)
	Request a channel and enable it.
void	pbl_mbox_free (const struct pbl_mbox_chan *chan)
	Disable a channel and release it, dropping any message in flight.
int	pbl_mbox_send (const struct pbl_mbox_chan *chan, const void *msg)
	Send a message.
void	pbl_mbox_chan_received (const struct pbl_mbox_controller *ctrl, uint8_t idx, const void *msg)
	Report a message from the remote, for providers.
void	pbl_mbox_chan_txdone (const struct pbl_mbox_controller *ctrl, uint8_t idx, int ret)
	Report that the remote took the last message, for providers with a completion interrupt.

Variables
const struct pbl_device_class	pbl_mbox_class
	Class of the mailbox controllers.

Detailed Description

Mailbox controller class.

A mailbox controller passes messages, or just doorbells, between processors over channels. A consumer holds a struct pbl_mbox_chan, what a devicetree mboxes entry describes: the controller and its specifier cells, which the controller translates to one of its channels. It requests the channel with a struct pbl_mbox_client, usually embedded in its own state so the callbacks get back to it with container_of():

static void prv_rx(const struct pbl_mbox_client *cl, const void *msg) {
  const struct foo *foo = container_of(cl, const struct foo, cl);
  // interrupt context
}
 
ret = pbl_mbox_request(&foo->rx_chan, &foo->cl);
ret = pbl_mbox_request(&foo->tx_chan, &foo->cl);
ret = pbl_mbox_send(&foo->tx_chan, nullptr);

Doorbell controllers carry no data: messages are nullptr and the payload lives in shared memory. One message per channel is in flight; sending while one is in flight queues the new message, replacing an already queued one, and the controller sends it once the first is done. The class reports completed messages through the client's tx_done, polling the controller when it has no completion interrupt.

---

Data Structure Documentation

pbl_mbox_chan

struct pbl_mbox_chan

A channel, as used by a consumer.

Data Fields
uint32_t	cells[PBL_MBOX_MAX_CELLS]	Specifier cells, as interpreted by the controller.
const struct pbl_mbox_controller *	ctrl	Controller.

pbl_mbox_chan_state

struct pbl_mbox_chan_state

Channel state, kept by the class.

Data Fields
const struct pbl_mbox_client *	cl	Client, set while the channel is requested.
uint32_t	rx_count	Messages received.
bool	tx_active	Whether tx_msg is in flight.
uint32_t	tx_count	Messages sent.
const void *	tx_msg	Message in flight.
const void *	tx_next	Message queued behind tx_msg.
bool	tx_queued	Whether tx_next is queued.

pbl_mbox_controller_state

struct pbl_mbox_controller_state

Controller state, kept by the class.

Data Fields
const struct pbl_mbox_controller *	ctrl	Controller.
struct pbl_timer	poll	Completion poll timer.

pbl_mbox_controller

struct pbl_mbox_controller

Mailbox controller.

Data Fields
struct pbl_mbox_chan_state *	chans	Channel states, num_chans entries.
struct pbl_device	dev	Device.
uint8_t	num_chans	Number of channels.
const struct pbl_mbox_controller_ops *	ops	Operations.
struct pbl_mbox_controller_state *	state	Controller state.
uint16_t	txpoll_period_ms	Completion poll period in milliseconds; 0 if the provider reports completion itself.

Macro Definition Documentation

PBL_MBOX_CHAN

#define PBL_MBOX_CHAN	(		_ctrl,
			...
	)

Value:

  {                                           \
    .ctrl = (_ctrl), .cells = { __VA_ARGS__ } \
  }

Initializer of a struct pbl_mbox_chan.

Parameters

_ctrl	Controller.
...	Specifier cells.

PBL_MBOX_CONTROLLER_INIT

#define PBL_MBOX_CONTROLLER_INIT	(		sym,
			_name,
			_init,
			_deps,
			_ops,
			_txpoll_period_ms
	)

Value:

  {                                                                                   \
    .dev = PBL_DEVICE_INIT_CLASS(sym, _name, _init, nullptr, _deps, &pbl_mbox_class), \
    .ops = (_ops),                                                                    \
    .state = &sym##_mbox_ctrl_state,                                                  \
    .chans = sym##_mbox_chans,                                                        \
    .num_chans = sizeof(sym##_mbox_chans) / sizeof(sym##_mbox_chans[0]),              \
    .txpoll_period_ms = (_txpoll_period_ms),                                          \
  }

Initializer of a struct pbl_mbox_controller, for providers.

Parameters

sym	Controller symbol, with its PBL_MBOX_CONTROLLER_STATE_DEFINE().
_name	Device name.
_init	Device init function.
_deps	Device dependencies.
_ops	Operations.
_txpoll_period_ms	Completion poll period in milliseconds, 0 for none.

PBL_MBOX_CONTROLLER_STATE_DEFINE

#define PBL_MBOX_CONTROLLER_STATE_DEFINE	(		sym,
			_num_chans
	)

Value:

  PBL_DEVICE_STATE_DEFINE(sym);                                  \
  static struct pbl_mbox_controller_state sym##_mbox_ctrl_state; \
  static struct pbl_mbox_chan_state sym##_mbox_chans[_num_chans]

Define the state of a controller, for providers.

Parameters

sym	Controller symbol.
_num_chans	Number of channels.

PBL_MBOX_MAX_CELLS

#define PBL_MBOX_MAX_CELLS   2U

Maximum number of specifier cells.

Function Documentation

pbl_mbox_chan_received()

void pbl_mbox_chan_received	(	const struct pbl_mbox_controller *	ctrl,
		uint8_t	idx,
		const void *	msg
	)

Report a message from the remote, for providers.

Called from interrupt context.

Parameters

ctrl	Controller.
idx	Channel index.
msg	Message, nullptr for doorbells.

pbl_mbox_chan_txdone()

void pbl_mbox_chan_txdone	(	const struct pbl_mbox_controller *	ctrl,
		uint8_t	idx,
		int	ret
	)

Report that the remote took the last message, for providers with a completion interrupt.

Called from interrupt context.

Parameters

ctrl	Controller.
idx	Channel index.
ret	0, or a negative errno.

pbl_mbox_free()

void pbl_mbox_free

(

const struct pbl_mbox_chan *

chan

)

Disable a channel and release it, dropping any message in flight.

Parameters

chan	Channel, requested.

pbl_mbox_request()

int pbl_mbox_request	(	const struct pbl_mbox_chan *	chan,
		const struct pbl_mbox_client *	cl
	)

Request a channel and enable it.

Parameters

chan	Channel.
cl	Client, must outlive the request.

Returns

0 on success, -ENODEV if the controller is not ready, -EINVAL for a bad specifier, -EBUSY if the channel is already requested, or a negative errno from the provider.

pbl_mbox_send()

int pbl_mbox_send	(	const struct pbl_mbox_chan *	chan,
		const void *	msg
	)

Send a message.

Does not wait: the client's tx_done reports when the remote took it.

Parameters

chan	Channel, requested.
msg	Message, nullptr for doorbells.

Returns

0 on success, -EINVAL if the channel is not requested, or a negative errno from the provider.

Variable Documentation

pbl_mbox_class

const struct pbl_device_class pbl_mbox_class

extern

Class of the mailbox controllers.