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 | |