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
11 #include <linux/types.h>
12 #include <linux/timer.h>
13 #include <linux/device.h>
14 #include <linux/completion.h>
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
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.
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
);
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.
73 struct mbox_controller
{
75 struct mbox_chan_ops
*ops
;
76 struct mbox_chan
*chans
;
80 unsigned txpoll_period
;
81 struct mbox_chan
*(*of_xlate
)(struct mbox_controller
*mbox
,
82 const struct of_phandle_args
*sp
);
84 struct timer_list poll
;
85 struct list_head node
;
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.
101 #define MBOX_TX_QUEUE_LEN 20
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
117 struct mbox_controller
*mbox
;
118 unsigned txdone_method
;
119 struct mbox_client
*cl
;
120 struct completion tx_complete
;
122 unsigned msg_count
, msg_free
;
123 void *msg_data
[MBOX_TX_QUEUE_LEN
];
124 spinlock_t lock
; /* Serialise access to the channel */
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 */
133 #endif /* __MAILBOX_CONTROLLER_H */
This page took 0.032389 seconds and 5 git commands to generate.