LXR uboot/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
  13struct udevice;
  14
  15/**
  16 * struct mbox_ops - The functions that a mailbox driver must implement.
  17 */
  18struct 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
  83