git.sur5r.net Git - u-boot/blob - include/mailbox.h

   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  *
  48  * Currently, the mailbox API assumes that a single integer ID is enough to
  49  * identify and configure any mailbox channel for any mailbox provider. If this
  50  * assumption becomes invalid in the future, the struct could be expanded to
  51  * either (a) add more fields to allow mailbox providers to store additional
  52  * information, or (b) replace the id field with an opaque pointer, which the
  53  * provider would dynamically allocated during its .of_xlate op, and process
  54  * during is .request op. This may require the addition of an extra op to clean
  55  * up the allocation.
  56  */
  57 struct mbox_chan {
  58         struct udevice *dev;
  59         /*
  60          * Written by of_xlate. We assume a single id is enough for now. In the
  61          * future, we might add more fields here.
  62          */
  63         unsigned long id;
  64 };
  65
  66 /**
  67  * mbox_get_by_index - Get/request a mailbox by integer index
  68  *
  69  * This looks up and requests a mailbox channel. The index is relative to the
  70  * client device; each device is assumed to have n mailbox channels associated
  71  * with it somehow, and this function finds and requests one of them. The
  72  * mapping of client device channel indices to provider channels may be via
  73  * device-tree properties, board-provided mapping tables, or some other
  74  * mechanism.
  75  *
  76  * @dev:        The client device.
  77  * @index:      The index of the mailbox channel to request, within the
  78  *              client's list of channels.
  79  * @chan        A pointer to a channel object to initialize.
  80  * @return 0 if OK, or a negative error code.
  81  */
  82 int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan);
  83
  84 /**
  85  * mbox_get_by_name - Get/request a mailbox by name
  86  *
  87  * This looks up and requests a mailbox channel. The name is relative to the
  88  * client device; each device is assumed to have n mailbox channels associated
  89  * with it somehow, and this function finds and requests one of them. The
  90  * mapping of client device channel names to provider channels may be via
  91  * device-tree properties, board-provided mapping tables, or some other
  92  * mechanism.
  93  *
  94  * @dev:        The client device.
  95  * @name:       The name of the mailbox channel to request, within the client's
  96  *              list of channels.
  97  * @chan        A pointer to a channel object to initialize.
  98  * @return 0 if OK, or a negative error code.
  99  */
 100 int mbox_get_by_name(struct udevice *dev, const char *name,
 101                      struct mbox_chan *chan);
 102
 103 /**
 104  * mbox_free - Free a previously requested mailbox channel.
 105  *
 106  * @chan:       A channel object that was previously successfully requested by
 107  *              calling mbox_get_by_*().
 108  * @return 0 if OK, or a negative error code.
 109  */
 110 int mbox_free(struct mbox_chan *chan);
 111
 112 /**
 113  * mbox_send - Send a message over a mailbox channel
 114  *
 115  * This function will send a message to the remote entity. It may return before
 116  * the remote entity has received and/or processed the message.
 117  *
 118  * @chan:       A channel object that was previously successfully requested by
 119  *              calling mbox_get_by_*().
 120  * @data:       A pointer to the message to transfer. The format and size of
 121  *              the memory region pointed at by @data is determined by the
 122  *              mailbox provider. Providers that solely transfer notifications
 123  *              will ignore this parameter.
 124  * @return 0 if OK, or a negative error code.
 125  */
 126 int mbox_send(struct mbox_chan *chan, const void *data);
 127
 128 /**
 129  * mbox_recv - Receive any available message from a mailbox channel
 130  *
 131  * This function will wait (up to the specified @timeout_us) for a message to
 132  * be sent by the remote entity, and write the content of any such message
 133  * into a caller-provided buffer.
 134  *
 135  * @chan:       A channel object that was previously successfully requested by
 136  *              calling mbox_get_by_*().
 137  * @data:       A pointer to the buffer to receive the message. The format and
 138  *              size of the memory region pointed at by @data is determined by
 139  *              the mailbox provider. Providers that solely transfer
 140  *              notifications will ignore this parameter.
 141  * @timeout_us: The maximum time to wait for a message to be available, in
 142  *              micro-seconds. A value of 0 does not wait at all.
 143  * @return 0 if OK, -ENODATA if no message was available, or a negative error
 144  * code.
 145  */
 146 int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us);
 147
 148 #endif