1 /* SPDX-License-Identifier: GPL-2.0-only */
2 
3 #ifndef __MAILBOX_CONTROLLER_H
4 #define __MAILBOX_CONTROLLER_H
5 
6 #include <linux/of.h>
7 #include <linux/types.h>
8 #include <linux/hrtimer.h>
9 #include <linux/device.h>
10 #include <linux/completion.h>
11 
12 struct mbox_chan;
13 
14 /**
15  * struct mbox_chan_ops - methods to control mailbox channels
16  * @send_data:	The API asks the MBOX controller driver, in atomic
17  *		context try to transmit a message on the bus. Returns 0 if
18  *		data is accepted for transmission, -EBUSY while rejecting
19  *		if the remote hasn't yet read the last data sent. Actual
20  *		transmission of data is reported by the controller via
21  *		mbox_chan_txdone (if it has some TX ACK irq). It must not
22  *		sleep.
23  * @flush:	Called when a client requests transmissions to be blocking but
24  *		the context doesn't allow sleeping. Typically the controller
25  *		will implement a busy loop waiting for the data to flush out.
26  * @startup:	Called when a client requests the chan. The controller
27  *		could ask clients for additional parameters of communication
28  *		to be provided via client's chan_data. This call may
29  *		block. After this call the Controller must forward any
30  *		data received on the chan by calling mbox_chan_received_data.
31  *		The controller may do stuff that need to sleep.
32  * @shutdown:	Called when a client relinquishes control of a chan.
33  *		This call may block too. The controller must not forward
34  *		any received data anymore.
35  *		The controller may do stuff that need to sleep.
36  * @last_tx_done: If the controller sets 'txdone_poll', the API calls
37  *		  this to poll status of last TX. The controller must
38  *		  give priority to IRQ method over polling and never
39  *		  set both txdone_poll and txdone_irq. Only in polling
40  *		  mode 'send_data' is expected to return -EBUSY.
41  *		  The controller may do stuff that need to sleep/block.
42  *		  Used only if txdone_poll:=true && txdone_irq:=false
43  * @peek_data: Atomic check for any received data. Return true if controller
44  *		  has some data to push to the client. False otherwise.
45  */
46 struct mbox_chan_ops {
47 	int (*send_data)(struct mbox_chan *chan, void *data);
48 	int (*flush)(struct mbox_chan *chan, unsigned long timeout);
49 	int (*startup)(struct mbox_chan *chan);
50 	void (*shutdown)(struct mbox_chan *chan);
51 	bool (*last_tx_done)(struct mbox_chan *chan);
52 	bool (*peek_data)(struct mbox_chan *chan);
53 };
54 
55 /**
56  * struct mbox_controller - Controller of a class of communication channels
57  * @dev:		Device backing this controller
58  * @ops:		Operators that work on each communication chan
59  * @chans:		Array of channels
60  * @num_chans:		Number of channels in the 'chans' array.
61  * @txdone_irq:		Indicates if the controller can report to API when
62  *			the last transmitted data was read by the remote.
63  *			Eg, if it has some TX ACK irq.
64  * @txdone_poll:	If the controller can read but not report the TX
65  *			done. Ex, some register shows the TX status but
66  *			no interrupt rises. Ignored if 'txdone_irq' is set.
67  * @txpoll_period:	If 'txdone_poll' is in effect, the API polls for
68  *			last TX's status after these many millisecs
69  * @of_xlate:		Controller driver specific mapping of channel via DT
70  * @poll_hrt:		API private. hrtimer used to poll for TXDONE on all
71  *			channels.
72  * @node:		API private. To hook into list of controllers.
73  */
74 struct mbox_controller {
75 	struct device *dev;
76 	const struct mbox_chan_ops *ops;
77 	struct mbox_chan *chans;
78 	int num_chans;
79 	bool txdone_irq;
80 	bool txdone_poll;
81 	unsigned txpoll_period;
82 	struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
83 				      const struct of_phandle_args *sp);
84 	/* Internal to API */
85 	struct hrtimer poll_hrt;
86 	spinlock_t poll_hrt_lock;
87 	struct list_head node;
88 };
89 
90 /*
91  * The length of circular buffer for queuing messages from a client.
92  * 'msg_count' tracks the number of buffered messages while 'msg_free'
93  * is the index where the next message would be buffered.
94  * We shouldn't need it too big because every transfer is interrupt
95  * triggered and if we have lots of data to transfer, the interrupt
96  * latencies are going to be the bottleneck, not the buffer length.
97  * Besides, mbox_send_message could be called from atomic context and
98  * the client could also queue another message from the notifier 'tx_done'
99  * of the last transfer done.
100  * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
101  * print, it needs to be taken from config option or somesuch.
102  */
103 #define MBOX_TX_QUEUE_LEN	20
104 
105 /**
106  * struct mbox_chan - s/w representation of a communication chan
107  * @mbox:		Pointer to the parent/provider of this channel
108  * @txdone_method:	Way to detect TXDone chosen by the API
109  * @cl:			Pointer to the current owner of this channel
110  * @tx_complete:	Transmission completion
111  * @active_req:		Currently active request hook
112  * @msg_count:		No. of mssg currently queued
113  * @msg_free:		Index of next available mssg slot
114  * @msg_data:		Hook for data packet
115  * @lock:		Serialise access to the channel
116  * @con_priv:		Hook for controller driver to attach private data
117  */
118 struct mbox_chan {
119 	struct mbox_controller *mbox;
120 	unsigned txdone_method;
121 	struct mbox_client *cl;
122 	struct completion tx_complete;
123 	void *active_req;
124 	unsigned msg_count, msg_free;
125 	void *msg_data[MBOX_TX_QUEUE_LEN];
126 	spinlock_t lock; /* Serialise access to the channel */
127 	void *con_priv;
128 };
129 
130 int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
131 void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
132 void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
133 void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
134 
135 int devm_mbox_controller_register(struct device *dev,
136 				  struct mbox_controller *mbox);
137 void devm_mbox_controller_unregister(struct device *dev,
138 				     struct mbox_controller *mbox);
139 
140 #endif /* __MAILBOX_CONTROLLER_H */
141