xref: /openbmc/u-boot/include/mailbox.h (revision 96c2961ba68e0baf463998301a09eddf76f462e6)
1  /* SPDX-License-Identifier: GPL-2.0 */
2  /*
3   * Copyright (c) 2016, NVIDIA CORPORATION.
4   */
5  
6  #ifndef _MAILBOX_H
7  #define _MAILBOX_H
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
28   * it manages often has this capability. mailbox-uclass.h describes the
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.
47   * @con_priv: Hook for controller driver to attach private data
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;
60  	/* Written by of_xlate.*/
61  	unsigned long id;
62  	void *con_priv;
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
148