Commit | Line | Data |
---|---|---|
d2912cb1 | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2b6d83e2 JB |
2 | |
3 | #ifndef __MAILBOX_CONTROLLER_H | |
4 | #define __MAILBOX_CONTROLLER_H | |
5 | ||
6 | #include <linux/of.h> | |
7 | #include <linux/types.h> | |
0cc67945 | 8 | #include <linux/hrtimer.h> |
2b6d83e2 JB |
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. | |
a8803d74 TR |
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. | |
2b6d83e2 JB |
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); | |
a8803d74 | 48 | int (*flush)(struct mbox_chan *chan, unsigned long timeout); |
2b6d83e2 JB |
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 | |
0cc67945 SH |
70 | * @poll_hrt: API private. hrtimer used to poll for TXDONE on all |
71 | * channels. | |
2b6d83e2 JB |
72 | * @node: API private. To hook into list of controllers. |
73 | */ | |
74 | struct mbox_controller { | |
75 | struct device *dev; | |
05ae7975 | 76 | const struct mbox_chan_ops *ops; |
2b6d83e2 JB |
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 */ | |
0cc67945 | 85 | struct hrtimer poll_hrt; |
bca1a100 | 86 | spinlock_t poll_hrt_lock; |
2b6d83e2 JB |
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 | ||
e898d9cd TR |
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 | ||
2b6d83e2 | 140 | #endif /* __MAILBOX_CONTROLLER_H */ |