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