include/mailbox-uclass.h

   1 /*
   2  * Copyright (c) 2016, NVIDIA CORPORATION.
   3  *
   4  * SPDX-License-Identifier: GPL-2.0
   5  */
   6
   7 #ifndef _MAILBOX_UCLASS_H
   8 #define _MAILBOX_UCLASS_H
   9
  10 /* See mailbox.h for background documentation. */
  11
  12 #include <mailbox.h>
  13
  14 struct udevice;
  15
  16 /**
  17  * struct mbox_ops - The functions that a mailbox driver must implement.
  18  */
  19 struct mbox_ops {
  20         /**
  21          * of_xlate - Translate a client's device-tree (OF) mailbox specifier.
  22          *
  23          * The mailbox core calls this function as the first step in
  24          * implementing a client's mbox_get_by_*() call.
  25          *
  26          * If this function pointer is set to NULL, the mailbox core will use
  27          * a default implementation, which assumes #mbox-cells = <1>, and that
  28          * the DT cell contains a simple integer channel ID.
  29          *
  30          * At present, the mailbox API solely supports device-tree. If this
  31          * changes, other xxx_xlate() functions may be added to support those
  32          * other mechanisms.
  33          *
  34          * @chan:       The channel to hold the translation result.
  35          * @args:       The mailbox specifier values from device tree.
  36          * @return 0 if OK, or a negative error code.
  37          */
  38         int (*of_xlate)(struct mbox_chan *chan,
  39                         struct fdtdec_phandle_args *args);
  40         /**
  41          * request - Request a translated channel.
  42          *
  43          * The mailbox core calls this function as the second step in
  44          * implementing a client's mbox_get_by_*() call, following a successful
  45          * xxx_xlate() call.
  46          *
  47          * @chan:       The channel to request; this has been filled in by a
  48          *              previoux xxx_xlate() function call.
  49          * @return 0 if OK, or a negative error code.
  50          */
  51         int (*request)(struct mbox_chan *chan);
  52         /**
  53          * free - Free a previously requested channel.
  54          *
  55          * This is the implementation of the client mbox_free() API.
  56          *
  57          * @chan:       The channel to free.
  58          * @return 0 if OK, or a negative error code.
  59          */
  60         int (*free)(struct mbox_chan *chan);
  61         /**
  62         * send - Send a message over a mailbox channel
  63         *
  64         * @chan:        The channel to send to the message to.
  65         * @data:        A pointer to the message to send.
  66         * @return 0 if OK, or a negative error code.
  67         */
  68         int (*send)(struct mbox_chan *chan, const void *data);
  69         /**
  70         * recv - Receive any available message from the channel.
  71         *
  72         * This function does not block. If not message is immediately
  73         * available, the function should return an error.
  74         *
  75         * @chan:        The channel to receive to the message from.
  76         * @data:        A pointer to the buffer to hold the received message.
  77         * @return 0 if OK, -ENODATA if no message was available, or a negative
  78         * error code.
  79         */
  80         int (*recv)(struct mbox_chan *chan, void *data);
  81 };
  82
  83 #endif