1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 3 #ifndef __MAILBOX_CONTROLLER_H 4 #define __MAILBOX_CONTROLLER_H 5 6 #include <linux/bits.h> 7 #include <linux/completion.h> 8 #include <linux/device.h> 9 #include <linux/hrtimer.h> 10 #include <linux/of.h> 11 #include <linux/types.h> 12 13 struct mbox_chan; 14 15 /* Sentinel value distinguishing "no active request" from "NULL message data" */ 16 #define MBOX_NO_MSG ((void *)-1) 17 18 #define MBOX_TXDONE_BY_IRQ BIT(0) /* controller has remote RTR irq */ 19 #define MBOX_TXDONE_BY_POLL BIT(1) /* controller can read status of last TX */ 20 #define MBOX_TXDONE_BY_ACK BIT(2) /* S/W ACK received by Client ticks the TX */ 21 22 /** 23 * struct mbox_chan_ops - methods to control mailbox channels 24 * @send_data: The API asks the MBOX controller driver, in atomic 25 * context try to transmit a message on the bus. Returns 0 if 26 * data is accepted for transmission, -EBUSY while rejecting 27 * if the remote hasn't yet read the last data sent. Actual 28 * transmission of data is reported by the controller via 29 * mbox_chan_txdone (if it has some TX ACK irq). It must not 30 * sleep. 31 * @flush: Called when a client requests transmissions to be blocking but 32 * the context doesn't allow sleeping. Typically the controller 33 * will implement a busy loop waiting for the data to flush out. 34 * @startup: Called when a client requests the chan. The controller 35 * could ask clients for additional parameters of communication 36 * to be provided via client's chan_data. This call may 37 * block. After this call the Controller must forward any 38 * data received on the chan by calling mbox_chan_received_data. 39 * The controller may do stuff that need to sleep. 40 * @shutdown: Called when a client relinquishes control of a chan. 41 * This call may block too. The controller must not forward 42 * any received data anymore. 43 * The controller may do stuff that need to sleep. 44 * @last_tx_done: If the controller sets 'txdone_poll', the API calls 45 * this to poll status of last TX. The controller must 46 * give priority to IRQ method over polling and never 47 * set both txdone_poll and txdone_irq. Only in polling 48 * mode 'send_data' is expected to return -EBUSY. 49 * The controller may do stuff that need to sleep/block. 50 * Used only if txdone_poll:=true && txdone_irq:=false 51 * @peek_data: Atomic check for any received data. Return true if controller 52 * has some data to push to the client. False otherwise. 53 */ 54 struct mbox_chan_ops { 55 int (*send_data)(struct mbox_chan *chan, void *data); 56 int (*flush)(struct mbox_chan *chan, unsigned long timeout); 57 int (*startup)(struct mbox_chan *chan); 58 void (*shutdown)(struct mbox_chan *chan); 59 bool (*last_tx_done)(struct mbox_chan *chan); 60 bool (*peek_data)(struct mbox_chan *chan); 61 }; 62 63 /** 64 * struct mbox_controller - Controller of a class of communication channels 65 * @dev: Device backing this controller. Required. 66 * @ops: Operators that work on each communication chan. Required. 67 * @chans: Array of channels. Required. 68 * @num_chans: Number of channels in the 'chans' array. Required. 69 * @txdone_irq: Indicates if the controller can report to API when 70 * the last transmitted data was read by the remote. 71 * Eg, if it has some TX ACK irq. 72 * @txdone_poll: If the controller can read but not report the TX 73 * done. Ex, some register shows the TX status but 74 * no interrupt rises. Ignored if 'txdone_irq' is set. 75 * @txpoll_period: If 'txdone_poll' is in effect, the API polls for 76 * last TX's status after these many millisecs 77 * @fw_xlate: Controller driver specific mapping of channel via fwnode 78 * @of_xlate: Controller driver specific mapping of channel via DT 79 * @poll_hrt: API private. hrtimer used to poll for TXDONE on all 80 * channels. 81 * @poll_hrt_lock: API private. Lock protecting access to poll_hrt. 82 * @node: API private. To hook into list of controllers. 83 */ 84 struct mbox_controller { 85 struct device *dev; 86 const struct mbox_chan_ops *ops; 87 struct mbox_chan *chans; 88 int num_chans; 89 bool txdone_irq; 90 bool txdone_poll; 91 unsigned txpoll_period; 92 struct mbox_chan *(*fw_xlate)(struct mbox_controller *mbox, 93 const struct fwnode_reference_args *sp); 94 struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox, 95 const struct of_phandle_args *sp); 96 /* Internal to API */ 97 struct hrtimer poll_hrt; 98 spinlock_t poll_hrt_lock; 99 struct list_head node; 100 }; 101 102 /* 103 * The length of circular buffer for queuing messages from a client. 104 * 'msg_count' tracks the number of buffered messages while 'msg_free' 105 * is the index where the next message would be buffered. 106 * We shouldn't need it too big because every transfer is interrupt 107 * triggered and if we have lots of data to transfer, the interrupt 108 * latencies are going to be the bottleneck, not the buffer length. 109 * Besides, mbox_send_message could be called from atomic context and 110 * the client could also queue another message from the notifier 'tx_done' 111 * of the last transfer done. 112 * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN" 113 * print, it needs to be taken from config option or somesuch. 114 */ 115 #define MBOX_TX_QUEUE_LEN 20 116 117 /** 118 * struct mbox_chan - s/w representation of a communication chan 119 * @mbox: Pointer to the parent/provider of this channel 120 * @txdone_method: Way to detect TXDone chosen by the API 121 * @cl: Pointer to the current owner of this channel 122 * @tx_complete: Transmission completion 123 * @active_req: Currently active request hook 124 * @msg_count: No. of mssg currently queued 125 * @msg_free: Index of next available mssg slot 126 * @msg_data: Hook for data packet 127 * @lock: Serialise access to the channel 128 * @con_priv: Hook for controller driver to attach private data 129 */ 130 struct mbox_chan { 131 struct mbox_controller *mbox; 132 unsigned txdone_method; 133 struct mbox_client *cl; 134 struct completion tx_complete; 135 void *active_req; 136 unsigned msg_count, msg_free; 137 void *msg_data[MBOX_TX_QUEUE_LEN]; 138 spinlock_t lock; /* Serialise access to the channel */ 139 void *con_priv; 140 }; 141 142 int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */ 143 void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */ 144 void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */ 145 void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */ 146 147 int devm_mbox_controller_register(struct device *dev, 148 struct mbox_controller *mbox); 149 #endif /* __MAILBOX_CONTROLLER_H */ 150