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