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.
7 #ifndef __MAILBOX_CONTROLLER_H
8 #define __MAILBOX_CONTROLLER_H
15 * struct mbox_chan_ops - s/w representation of a communication chan
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
23 * @startup: Called when a client requests the chan. The controller
24 * could ask clients for additional parameters of communication
25 * to be provided via client's chan_data. This call may
26 * block. After this call the Controller must forward any
27 * data received on the chan by calling mbox_chan_received_data.
28 * @shutdown: Called when a client relinquishes control of a chan.
29 * This call may block too. The controller must not forwared
30 * any received data anymore.
31 * @last_tx_done: If the controller sets 'txdone_poll', the API calls
32 * this to poll status of last TX. The controller must
33 * give priority to IRQ method over polling and never
34 * set both txdone_poll and txdone_irq. Only in polling
35 * mode 'send_data' is expected to return -EBUSY.
36 * Used only if txdone_poll:=true && txdone_irq:=false
37 * @peek_data: Atomic check for any received data. Return true if controller
38 * has some data to push to the client. False otherwise.
40 struct mbox_chan_ops {
41 int (*send_data)(struct mbox_chan *chan, void *data);
42 int (*startup)(struct mbox_chan *chan);
43 void (*shutdown)(struct mbox_chan *chan);
44 bool (*last_tx_done)(struct mbox_chan *chan);
45 bool (*peek_data)(struct mbox_chan *chan);
49 * struct mbox_controller - Controller of a class of communication chans
50 * @dev: Device backing this controller
51 * @controller_name: Literal name of the controller.
52 * @ops: Operators that work on each communication chan
53 * @chans: Null terminated array of chans.
54 * @txdone_irq: Indicates if the controller can report to API when
55 * the last transmitted data was read by the remote.
56 * Eg, if it has some TX ACK irq.
57 * @txdone_poll: If the controller can read but not report the TX
58 * done. Ex, some register shows the TX status but
59 * no interrupt rises. Ignored if 'txdone_irq' is set.
60 * @txpoll_period: If 'txdone_poll' is in effect, the API polls for
61 * last TX's status after these many millisecs
63 struct mbox_controller {
65 struct mbox_chan_ops *ops;
66 struct mbox_chan *chans;
70 unsigned txpoll_period;
71 struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
72 const struct of_phandle_args *sp);
74 * If the controller supports only TXDONE_BY_POLL,
75 * this timer polls all the links for txdone.
77 struct timer_list poll;
79 /* Hook to add to the global controller list */
80 struct list_head node;
84 * The length of circular buffer for queuing messages from a client.
85 * 'msg_count' tracks the number of buffered messages while 'msg_free'
86 * is the index where the next message would be buffered.
87 * We shouldn't need it too big because every transferr is interrupt
88 * triggered and if we have lots of data to transfer, the interrupt
89 * latencies are going to be the bottleneck, not the buffer length.
90 * Besides, mbox_send_message could be called from atomic context and
91 * the client could also queue another message from the notifier 'tx_done'
92 * of the last transfer done.
93 * REVIST: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
94 * print, it needs to be taken from config option or somesuch.
96 #define MBOX_TX_QUEUE_LEN 20
99 struct mbox_controller *mbox; /* Parent Controller */
100 unsigned txdone_method;
103 struct mbox_client *cl;
104 struct completion tx_complete;
107 unsigned msg_count, msg_free;
108 void *msg_data[MBOX_TX_QUEUE_LEN];
109 /* Access to the channel */
112 /* Private data for controller */
116 int mbox_controller_register(struct mbox_controller *mbox);
117 void mbox_chan_received_data(struct mbox_chan *chan, void *data);
118 void mbox_chan_txdone(struct mbox_chan *chan, int r);
119 void mbox_controller_unregister(struct mbox_controller *mbox);
121 #endif /* __MAILBOX_CONTROLLER_H */