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> | |
12 | #include <linux/timer.h> | |
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. | |
27 | * @startup: Called when a client requests the chan. The controller | |
28 | * could ask clients for additional parameters of communication | |
29 | * to be provided via client's chan_data. This call may | |
30 | * block. After this call the Controller must forward any | |
31 | * data received on the chan by calling mbox_chan_received_data. | |
32 | * The controller may do stuff that need to sleep. | |
33 | * @shutdown: Called when a client relinquishes control of a chan. | |
34 | * This call may block too. The controller must not forward | |
35 | * any received data anymore. | |
36 | * The controller may do stuff that need to sleep. | |
37 | * @last_tx_done: If the controller sets 'txdone_poll', the API calls | |
38 | * this to poll status of last TX. The controller must | |
39 | * give priority to IRQ method over polling and never | |
40 | * set both txdone_poll and txdone_irq. Only in polling | |
41 | * mode 'send_data' is expected to return -EBUSY. | |
42 | * The controller may do stuff that need to sleep/block. | |
43 | * Used only if txdone_poll:=true && txdone_irq:=false | |
44 | * @peek_data: Atomic check for any received data. Return true if controller | |
45 | * has some data to push to the client. False otherwise. | |
46 | */ | |
47 | struct mbox_chan_ops { | |
48 | int (*send_data)(struct mbox_chan *chan, void *data); | |
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: API private. Used to poll for TXDONE on all channels. | |
71 | * @node: API private. To hook into list of controllers. | |
72 | */ | |
73 | struct mbox_controller { | |
74 | struct device *dev; | |
75 | struct mbox_chan_ops *ops; | |
76 | struct mbox_chan *chans; | |
77 | int num_chans; | |
78 | bool txdone_irq; | |
79 | bool txdone_poll; | |
80 | unsigned txpoll_period; | |
81 | struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox, | |
82 | const struct of_phandle_args *sp); | |
83 | /* Internal to API */ | |
84 | struct timer_list poll; | |
85 | struct list_head node; | |
86 | }; | |
87 | ||
88 | /* | |
89 | * The length of circular buffer for queuing messages from a client. | |
90 | * 'msg_count' tracks the number of buffered messages while 'msg_free' | |
91 | * is the index where the next message would be buffered. | |
92 | * We shouldn't need it too big because every transfer is interrupt | |
93 | * triggered and if we have lots of data to transfer, the interrupt | |
94 | * latencies are going to be the bottleneck, not the buffer length. | |
95 | * Besides, mbox_send_message could be called from atomic context and | |
96 | * the client could also queue another message from the notifier 'tx_done' | |
97 | * of the last transfer done. | |
98 | * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN" | |
99 | * print, it needs to be taken from config option or somesuch. | |
100 | */ | |
101 | #define MBOX_TX_QUEUE_LEN 20 | |
102 | ||
103 | /** | |
104 | * struct mbox_chan - s/w representation of a communication chan | |
105 | * @mbox: Pointer to the parent/provider of this channel | |
106 | * @txdone_method: Way to detect TXDone chosen by the API | |
107 | * @cl: Pointer to the current owner of this channel | |
108 | * @tx_complete: Transmission completion | |
109 | * @active_req: Currently active request hook | |
110 | * @msg_count: No. of mssg currently queued | |
111 | * @msg_free: Index of next available mssg slot | |
112 | * @msg_data: Hook for data packet | |
113 | * @lock: Serialise access to the channel | |
114 | * @con_priv: Hook for controller driver to attach private data | |
115 | */ | |
116 | struct mbox_chan { | |
117 | struct mbox_controller *mbox; | |
118 | unsigned txdone_method; | |
119 | struct mbox_client *cl; | |
120 | struct completion tx_complete; | |
121 | void *active_req; | |
122 | unsigned msg_count, msg_free; | |
123 | void *msg_data[MBOX_TX_QUEUE_LEN]; | |
124 | spinlock_t lock; /* Serialise access to the channel */ | |
125 | void *con_priv; | |
126 | }; | |
127 | ||
128 | int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */ | |
129 | void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */ | |
130 | void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */ | |
131 | void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */ | |
132 | ||
133 | #endif /* __MAILBOX_CONTROLLER_H */ |