183d290c5STom Rini /* SPDX-License-Identifier: GPL-2.0 */ 2769d52efSStephen Warren /* 3769d52efSStephen Warren * Copyright (c) 2016, NVIDIA CORPORATION. 4769d52efSStephen Warren */ 5769d52efSStephen Warren 6769d52efSStephen Warren #ifndef _MAILBOX_H 7769d52efSStephen Warren #define _MAILBOX_H 8769d52efSStephen Warren 9769d52efSStephen Warren /** 10769d52efSStephen Warren * A mailbox is a hardware mechanism for transferring small fixed-size messages 11769d52efSStephen Warren * and/or notifications between the CPU on which U-Boot runs and some other 12769d52efSStephen Warren * device such as an auxiliary CPU running firmware or a hardware module. 13769d52efSStephen Warren * 14769d52efSStephen Warren * Data transfer is optional; a mailbox may consist solely of a notification 15769d52efSStephen Warren * mechanism. When data transfer is implemented, it is via HW registers or 16769d52efSStephen Warren * FIFOs, rather than via RAM-based buffers. The mailbox API generally 17769d52efSStephen Warren * implements any communication protocol enforced solely by hardware, and 18769d52efSStephen Warren * leaves any higher-level protocols to other layers. 19769d52efSStephen Warren * 20769d52efSStephen Warren * A mailbox channel is a bi-directional mechanism that can send a message or 21769d52efSStephen Warren * notification to a single specific remote entity, and receive messages or 22769d52efSStephen Warren * notifications from that entity. The size, content, and format of such 23769d52efSStephen Warren * messages is defined by the mailbox implementation, or the remote entity with 24769d52efSStephen Warren * which it communicates; there is no general standard at this API level. 25769d52efSStephen Warren * 26769d52efSStephen Warren * A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider 27769d52efSStephen Warren * will often implement multiple separate mailbox channels, since the hardware 28769d52efSStephen Warren * it manages often has this capability. mailbox-uclass.h describes the 29769d52efSStephen Warren * interface which mailbox providers must implement. 30769d52efSStephen Warren * 31769d52efSStephen Warren * Mailbox consumers/clients generate and send, or receive and process, 32769d52efSStephen Warren * messages. This header file describes the API used by clients. 33769d52efSStephen Warren */ 34769d52efSStephen Warren 35769d52efSStephen Warren struct udevice; 36769d52efSStephen Warren 37769d52efSStephen Warren /** 38769d52efSStephen Warren * struct mbox_chan - A handle to a single mailbox channel. 39769d52efSStephen Warren * 40769d52efSStephen Warren * Clients provide storage for channels. The content of the channel structure 41769d52efSStephen Warren * is managed solely by the mailbox API and mailbox drivers. A mailbox channel 42769d52efSStephen Warren * is initialized by "get"ing the mailbox. The channel struct is passed to all 43769d52efSStephen Warren * other mailbox APIs to identify which mailbox to operate upon. 44769d52efSStephen Warren * 45769d52efSStephen Warren * @dev: The device which implements the mailbox. 46769d52efSStephen Warren * @id: The mailbox channel ID within the provider. 47*600e46b0SLokesh Vutla * @con_priv: Hook for controller driver to attach private data 48769d52efSStephen Warren * 49769d52efSStephen Warren * Currently, the mailbox API assumes that a single integer ID is enough to 50769d52efSStephen Warren * identify and configure any mailbox channel for any mailbox provider. If this 51769d52efSStephen Warren * assumption becomes invalid in the future, the struct could be expanded to 52769d52efSStephen Warren * either (a) add more fields to allow mailbox providers to store additional 53769d52efSStephen Warren * information, or (b) replace the id field with an opaque pointer, which the 54769d52efSStephen Warren * provider would dynamically allocated during its .of_xlate op, and process 55769d52efSStephen Warren * during is .request op. This may require the addition of an extra op to clean 56769d52efSStephen Warren * up the allocation. 57769d52efSStephen Warren */ 58769d52efSStephen Warren struct mbox_chan { 59769d52efSStephen Warren struct udevice *dev; 60*600e46b0SLokesh Vutla /* Written by of_xlate.*/ 61769d52efSStephen Warren unsigned long id; 62*600e46b0SLokesh Vutla void *con_priv; 63769d52efSStephen Warren }; 64769d52efSStephen Warren 65769d52efSStephen Warren /** 66769d52efSStephen Warren * mbox_get_by_index - Get/request a mailbox by integer index 67769d52efSStephen Warren * 68769d52efSStephen Warren * This looks up and requests a mailbox channel. The index is relative to the 69769d52efSStephen Warren * client device; each device is assumed to have n mailbox channels associated 70769d52efSStephen Warren * with it somehow, and this function finds and requests one of them. The 71769d52efSStephen Warren * mapping of client device channel indices to provider channels may be via 72769d52efSStephen Warren * device-tree properties, board-provided mapping tables, or some other 73769d52efSStephen Warren * mechanism. 74769d52efSStephen Warren * 75769d52efSStephen Warren * @dev: The client device. 76769d52efSStephen Warren * @index: The index of the mailbox channel to request, within the 77769d52efSStephen Warren * client's list of channels. 78769d52efSStephen Warren * @chan A pointer to a channel object to initialize. 79769d52efSStephen Warren * @return 0 if OK, or a negative error code. 80769d52efSStephen Warren */ 81769d52efSStephen Warren int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan); 82769d52efSStephen Warren 83769d52efSStephen Warren /** 84769d52efSStephen Warren * mbox_get_by_name - Get/request a mailbox by name 85769d52efSStephen Warren * 86769d52efSStephen Warren * This looks up and requests a mailbox channel. The name is relative to the 87769d52efSStephen Warren * client device; each device is assumed to have n mailbox channels associated 88769d52efSStephen Warren * with it somehow, and this function finds and requests one of them. The 89769d52efSStephen Warren * mapping of client device channel names to provider channels may be via 90769d52efSStephen Warren * device-tree properties, board-provided mapping tables, or some other 91769d52efSStephen Warren * mechanism. 92769d52efSStephen Warren * 93769d52efSStephen Warren * @dev: The client device. 94769d52efSStephen Warren * @name: The name of the mailbox channel to request, within the client's 95769d52efSStephen Warren * list of channels. 96769d52efSStephen Warren * @chan A pointer to a channel object to initialize. 97769d52efSStephen Warren * @return 0 if OK, or a negative error code. 98769d52efSStephen Warren */ 99769d52efSStephen Warren int mbox_get_by_name(struct udevice *dev, const char *name, 100769d52efSStephen Warren struct mbox_chan *chan); 101769d52efSStephen Warren 102769d52efSStephen Warren /** 103769d52efSStephen Warren * mbox_free - Free a previously requested mailbox channel. 104769d52efSStephen Warren * 105769d52efSStephen Warren * @chan: A channel object that was previously successfully requested by 106769d52efSStephen Warren * calling mbox_get_by_*(). 107769d52efSStephen Warren * @return 0 if OK, or a negative error code. 108769d52efSStephen Warren */ 109769d52efSStephen Warren int mbox_free(struct mbox_chan *chan); 110769d52efSStephen Warren 111769d52efSStephen Warren /** 112769d52efSStephen Warren * mbox_send - Send a message over a mailbox channel 113769d52efSStephen Warren * 114769d52efSStephen Warren * This function will send a message to the remote entity. It may return before 115769d52efSStephen Warren * the remote entity has received and/or processed the message. 116769d52efSStephen Warren * 117769d52efSStephen Warren * @chan: A channel object that was previously successfully requested by 118769d52efSStephen Warren * calling mbox_get_by_*(). 119769d52efSStephen Warren * @data: A pointer to the message to transfer. The format and size of 120769d52efSStephen Warren * the memory region pointed at by @data is determined by the 121769d52efSStephen Warren * mailbox provider. Providers that solely transfer notifications 122769d52efSStephen Warren * will ignore this parameter. 123769d52efSStephen Warren * @return 0 if OK, or a negative error code. 124769d52efSStephen Warren */ 125769d52efSStephen Warren int mbox_send(struct mbox_chan *chan, const void *data); 126769d52efSStephen Warren 127769d52efSStephen Warren /** 128769d52efSStephen Warren * mbox_recv - Receive any available message from a mailbox channel 129769d52efSStephen Warren * 130769d52efSStephen Warren * This function will wait (up to the specified @timeout_us) for a message to 131769d52efSStephen Warren * be sent by the remote entity, and write the content of any such message 132769d52efSStephen Warren * into a caller-provided buffer. 133769d52efSStephen Warren * 134769d52efSStephen Warren * @chan: A channel object that was previously successfully requested by 135769d52efSStephen Warren * calling mbox_get_by_*(). 136769d52efSStephen Warren * @data: A pointer to the buffer to receive the message. The format and 137769d52efSStephen Warren * size of the memory region pointed at by @data is determined by 138769d52efSStephen Warren * the mailbox provider. Providers that solely transfer 139769d52efSStephen Warren * notifications will ignore this parameter. 140769d52efSStephen Warren * @timeout_us: The maximum time to wait for a message to be available, in 141769d52efSStephen Warren * micro-seconds. A value of 0 does not wait at all. 142769d52efSStephen Warren * @return 0 if OK, -ENODATA if no message was available, or a negative error 143769d52efSStephen Warren * code. 144769d52efSStephen Warren */ 145769d52efSStephen Warren int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us); 146769d52efSStephen Warren 147769d52efSStephen Warren #endif 148