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 * @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 */ 50 struct 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 */ 78 struct 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 */ 121 struct 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 133 int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */ 134 void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */ 135 void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */ 136 void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */ 137 138 int devm_mbox_controller_register(struct device *dev, 139 struct mbox_controller *mbox); 140 void devm_mbox_controller_unregister(struct device *dev, 141 struct mbox_controller *mbox); 142 143 #endif /* __MAILBOX_CONTROLLER_H */ 144