LXR uboot/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
  35struct 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 */
  58struct 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 */
  81int 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 */
  99int 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 */
 109int 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 */
 125int 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 */
 145int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us);
 146
 147#endif
 148