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