]>
Commit | Line | Data |
---|---|---|
83d290c5 | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
6238935d SW |
2 | /* |
3 | * Copyright (c) 2016, NVIDIA CORPORATION. | |
6238935d SW |
4 | */ |
5 | ||
769d52ef SW |
6 | #ifndef _MAILBOX_H |
7 | #define _MAILBOX_H | |
6238935d SW |
8 | |
9 | /** | |
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 | |
12 | * device such as an auxiliary CPU running firmware or a hardware module. | |
13 | * | |
14 | * Data transfer is optional; a mailbox may consist solely of a notification | |
15 | * mechanism. When data transfer is implemented, it is via HW registers or | |
16 | * FIFOs, rather than via RAM-based buffers. The mailbox API generally | |
17 | * implements any communication protocol enforced solely by hardware, and | |
18 | * leaves any higher-level protocols to other layers. | |
19 | * | |
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 | |
22 | * notifications from that entity. The size, content, and format of such | |
23 | * messages is defined by the mailbox implementation, or the remote entity with | |
24 | * which it communicates; there is no general standard at this API level. | |
25 | * | |
26 | * A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider | |
27 | * will often implement multiple separate mailbox channels, since the hardware | |
769d52ef | 28 | * it manages often has this capability. mailbox-uclass.h describes the |
6238935d SW |
29 | * interface which mailbox providers must implement. |
30 | * | |
31 | * Mailbox consumers/clients generate and send, or receive and process, | |
32 | * messages. This header file describes the API used by clients. | |
33 | */ | |
34 | ||
35 | struct udevice; | |
36 | ||
37 | /** | |
38 | * struct mbox_chan - A handle to a single mailbox channel. | |
39 | * | |
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 | |
43 | * other mailbox APIs to identify which mailbox to operate upon. | |
44 | * | |
45 | * @dev: The device which implements the mailbox. | |
46 | * @id: The mailbox channel ID within the provider. | |
600e46b0 | 47 | * @con_priv: Hook for controller driver to attach private data |
6238935d SW |
48 | * |
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 | |
51 | * assumption becomes invalid in the future, the struct could be expanded to | |
52 | * either (a) add more fields to allow mailbox providers to store additional | |
53 | * information, or (b) replace the id field with an opaque pointer, which the | |
54 | * provider would dynamically allocated during its .of_xlate op, and process | |
55 | * during is .request op. This may require the addition of an extra op to clean | |
56 | * up the allocation. | |
57 | */ | |
58 | struct mbox_chan { | |
59 | struct udevice *dev; | |
600e46b0 | 60 | /* Written by of_xlate.*/ |
6238935d | 61 | unsigned long id; |
600e46b0 | 62 | void *con_priv; |
6238935d SW |
63 | }; |
64 | ||
65 | /** | |
66 | * mbox_get_by_index - Get/request a mailbox by integer index | |
67 | * | |
68 | * This looks up and requests a mailbox channel. The index is relative to the | |
69 | * client device; each device is assumed to have n mailbox channels associated | |
70 | * with it somehow, and this function finds and requests one of them. 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 | |
73 | * mechanism. | |
74 | * | |
75 | * @dev: The client device. | |
76 | * @index: The index of the mailbox channel to request, within the | |
77 | * client's list of channels. | |
78 | * @chan A pointer to a channel object to initialize. | |
79 | * @return 0 if OK, or a negative error code. | |
80 | */ | |
81 | int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan); | |
82 | ||
83 | /** | |
84 | * mbox_get_by_name - Get/request a mailbox by name | |
85 | * | |
86 | * This looks up and requests a mailbox channel. The name is relative to the | |
87 | * client device; each device is assumed to have n mailbox channels associated | |
88 | * with it somehow, and this function finds and requests one of them. 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 | |
91 | * mechanism. | |
92 | * | |
93 | * @dev: The client device. | |
94 | * @name: The name of the mailbox channel to request, within the client's | |
95 | * list of channels. | |
96 | * @chan A pointer to a channel object to initialize. | |
97 | * @return 0 if OK, or a negative error code. | |
98 | */ | |
99 | int mbox_get_by_name(struct udevice *dev, const char *name, | |
100 | struct mbox_chan *chan); | |
101 | ||
102 | /** | |
103 | * mbox_free - Free a previously requested mailbox channel. | |
104 | * | |
105 | * @chan: A channel object that was previously successfully requested by | |
106 | * calling mbox_get_by_*(). | |
107 | * @return 0 if OK, or a negative error code. | |
108 | */ | |
109 | int mbox_free(struct mbox_chan *chan); | |
110 | ||
111 | /** | |
112 | * mbox_send - Send a message over a mailbox channel | |
113 | * | |
114 | * This function will send a message to the remote entity. It may return before | |
115 | * the remote entity has received and/or processed the message. | |
116 | * | |
117 | * @chan: A channel object that was previously successfully requested by | |
118 | * calling mbox_get_by_*(). | |
119 | * @data: A pointer to the message to transfer. The format and size of | |
120 | * the memory region pointed at by @data is determined by the | |
121 | * mailbox provider. Providers that solely transfer notifications | |
122 | * will ignore this parameter. | |
123 | * @return 0 if OK, or a negative error code. | |
124 | */ | |
125 | int mbox_send(struct mbox_chan *chan, const void *data); | |
126 | ||
127 | /** | |
128 | * mbox_recv - Receive any available message from a mailbox channel | |
129 | * | |
130 | * This function will wait (up to the specified @timeout_us) for a message to | |
131 | * be sent by the remote entity, and write the content of any such message | |
132 | * into a caller-provided buffer. | |
133 | * | |
134 | * @chan: A channel object that was previously successfully requested by | |
135 | * calling mbox_get_by_*(). | |
136 | * @data: A pointer to the buffer to receive the message. The format and | |
137 | * size of the memory region pointed at by @data is determined by | |
138 | * the mailbox provider. Providers that solely transfer | |
139 | * notifications will ignore this parameter. | |
140 | * @timeout_us: The maximum time to wait for a message to be available, in | |
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 | |
143 | * code. | |
144 | */ | |
145 | int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us); | |
146 | ||
147 | #endif |