u-boot/include/mailbox.h

1 /* SPDX-License-Identifier: GPL-2.0 */
10  * A mailbox is a hardware mechanism for transferring small fixed-size messages
11  * and/or notifications between the CPU on which U-Boot runs and some other
16  * FIFOs, rather than via RAM-based buffers. The mailbox API generally
18  * leaves any higher-level protocols to other layers.
20  * A mailbox channel is a bi-directional mechanism that can send a message or
21  * notification to a single specific remote entity, and receive messages or
28  * it manages often has this capability. mailbox-uclass.h describes the
38  * struct mbox_chan - A handle to a single mailbox channel.
40  * Clients provide storage for channels. The content of the channel structure
41  * is managed solely by the mailbox API and mailbox drivers. A mailbox channel
42  * is initialized by "get"ing the mailbox. The channel struct is passed to all
46  * @id: The mailbox channel ID within the provider.
49  * Currently, the mailbox API assumes that a single integer ID is enough to
50  * identify and configure any mailbox channel for any mailbox provider. If this
66  * mbox_get_by_index - Get/request a mailbox by integer index
68  * This looks up and requests a mailbox channel. The index is relative to the
71  * mapping of client device channel indices to provider channels may be via
72  * device-tree properties, board-provided mapping tables, or some other
76  * @index:	The index of the mailbox channel to request, within the
78  * @chan	A pointer to a channel object to initialize.
84  * mbox_get_by_name - Get/request a mailbox by name
86  * This looks up and requests a mailbox channel. The name is relative to the
89  * mapping of client device channel names to provider channels may be via
90  * device-tree properties, board-provided mapping tables, or some other
94  * @name:	The name of the mailbox channel to request, within the client's
96  * @chan	A pointer to a channel object to initialize.
103  * mbox_free - Free a previously requested mailbox channel.
105  * @chan:	A channel object that was previously successfully requested by
112  * mbox_send - Send a message over a mailbox channel
117  * @chan:	A channel object that was previously successfully requested by
128  * mbox_recv - Receive any available message from a mailbox channel
132  * into a caller-provided buffer.
134  * @chan:	A channel object that was previously successfully requested by
141  *		micro-seconds. A value of 0 does not wait at all.
142  * @return 0 if OK, -ENODATA if no message was available, or a negative error