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