include/mailbox-uclass.h

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