| 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 |
|
| 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_hrt: API private. hrtimer used to poll for TXDONE on all
|
| 71 | * channels.
|
| 72 | * @node: API private. To hook into list of controllers.
|
| 73 |
|
| 74 | struct mbox_controller {
|
| 75 | struct device *dev;
|
| 76 | const struct mbox_chan_ops *ops;
|
| 77 | struct mbox_chan *chans;
|
| 78 | int num_chans;
|
| 79 | bool txdone_irq;
|
| 80 | bool txdone_poll;
|
| 81 | unsigned txpoll_period;
|
| 82 | struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
|
| 83 | const struct of_phandle_args *sp);
|
| 84 |
|
| 85 | struct hrtimer poll_hrt;
|
| 86 | struct list_head node;
|
| 87 | };
|
| 88 |
|
| 89 | |
| 90 | * The length of circular buffer for queuing messages from a client.
|
| 91 | * 'msg_count' tracks the number of buffered messages while 'msg_free'
|
| 92 | * is the index where the next message would be buffered.
|
| 93 | * We shouldn't need it too big because every transfer is interrupt
|
| 94 | * triggered and if we have lots of data to transfer, the interrupt
|
| 95 | * latencies are going to be the bottleneck, not the buffer length.
|
| 96 | * Besides, mbox_send_message could be called from atomic context and
|
| 97 | * the client could also queue another message from the notifier 'tx_done'
|
| 98 | * of the last transfer done.
|
| 99 | * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
|
| 100 | * print, it needs to be taken from config option or somesuch.
|
| 101 |
|
| 102 | #define MBOX_TX_QUEUE_LEN 20
|
| 103 |
|
| 104 | |
| 105 | * struct mbox_chan - s/w representation of a communication chan
|
| 106 | * @mbox: Pointer to the parent/provider of this channel
|
| 107 | * @txdone_method: Way to detect TXDone chosen by the API
|
| 108 | * @cl: Pointer to the current owner of this channel
|
| 109 | * @tx_complete: Transmission completion
|
| 110 | * @active_req: Currently active request hook
|
| 111 | * @msg_count: No. of mssg currently queued
|
| 112 | * @msg_free: Index of next available mssg slot
|
| 113 | * @msg_data: Hook for data packet
|
| 114 | * @lock: Serialise access to the channel
|
| 115 | * @con_priv: Hook for controller driver to attach private data
|
| 116 |
|
| 117 | struct mbox_chan {
|
| 118 | struct mbox_controller *mbox;
|
| 119 | unsigned txdone_method;
|
| 120 | struct mbox_client *cl;
|
| 121 | struct completion tx_complete;
|
| 122 | void *active_req;
|
| 123 | unsigned msg_count, msg_free;
|
| 124 | void *msg_data[MBOX_TX_QUEUE_LEN];
|
| 125 | spinlock_t lock;
|
| 126 | void *con_priv;
|
| 127 | };
|
| 128 |
|
| 129 | int mbox_controller_register(struct mbox_controller *mbox);
|
| 130 | void mbox_controller_unregister(struct mbox_controller *mbox);
|
| 131 | void mbox_chan_received_data(struct mbox_chan *chan, void *data);
|
| 132 | void mbox_chan_txdone(struct mbox_chan *chan, int r);
|
| 133 |
|
| 134 | #endif
|