Merge git://git.denx.de/u-boot-marvell
[platform/kernel/u-boot.git] / 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          * free - 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 (*free)(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