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/hrtimer.h>
13#include <linux/device.h>
14#include <linux/completion.h>
15
16struct 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 * @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.
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 */
50struct mbox_chan_ops {
51 int (*send_data)(struct mbox_chan *chan, void *data);
52 int (*flush)(struct mbox_chan *chan, unsigned long timeout);
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
74 * @poll_hrt: API private. hrtimer used to poll for TXDONE on all
75 * channels.
76 * @node: API private. To hook into list of controllers.
77 */
78struct mbox_controller {
79 struct device *dev;
80 const struct mbox_chan_ops *ops;
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 */
89 struct hrtimer poll_hrt;
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 */
121struct 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
133int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
134void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
135void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
136void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
137
138int devm_mbox_controller_register(struct device *dev,
139 struct mbox_controller *mbox);
140void devm_mbox_controller_unregister(struct device *dev,
141 struct mbox_controller *mbox);
142
143#endif /* __MAILBOX_CONTROLLER_H */
144