1 files changed, 133 insertions, 0 deletions
diff --git a/include/linux/mailbox_controller.h b/include/linux/mailbox_controller.h
new file mode 100644
index 000000000000..d4cf96f07cfc
--- /dev/null
+++ b/include/linux/mailbox_controller.h
@@ -0,0 +1,133 @@
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ */
+#ifndef __MAILBOX_CONTROLLER_H
+#define __MAILBOX_CONTROLLER_H
+#include <linux/of.h>
+#include <linux/types.h>
+#include <linux/timer.h>
+#include <linux/device.h>
+#include <linux/completion.h>
+struct mbox_chan;
+/**
+ * struct mbox_chan_ops - methods to control mailbox channels
+ * @send_data:  The API asks the MBOX controller driver, in atomic
+ *              context try to transmit a message on the bus. Returns 0 if
+ *              data is accepted for transmission, -EBUSY while rejecting
+ *              if the remote hasn't yet read the last data sent. Actual
+ *              transmission of data is reported by the controller via
+ *              mbox_chan_txdone (if it has some TX ACK irq). It must not
+ *              sleep.
+ * @startup:    Called when a client requests the chan. The controller
+ *              could ask clients for additional parameters of communication
+ *              to be provided via client's chan_data. This call may
+ *              block. After this call the Controller must forward any
+ *              data received on the chan by calling mbox_chan_received_data.
+ *              The controller may do stuff that need to sleep.
+ * @shutdown:   Called when a client relinquishes control of a chan.
+ *              This call may block too. The controller must not forward
+ *              any received data anymore.
+ *              The controller may do stuff that need to sleep.
+ * @last_tx_done: If the controller sets 'txdone_poll', the API calls
+ *                this to poll status of last TX. The controller must
+ *                give priority to IRQ method over polling and never
+ *                set both txdone_poll and txdone_irq. Only in polling
+ *                mode 'send_data' is expected to return -EBUSY.
+ *                The controller may do stuff that need to sleep/block.
+ *                Used only if txdone_poll:=true && txdone_irq:=false
+ * @peek_data: Atomic check for any received data. Return true if controller
+ *                has some data to push to the client. False otherwise.
+ */
+struct mbox_chan_ops {
+        int (*send_data)(struct mbox_chan *chan, void *data);
+        int (*startup)(struct mbox_chan *chan);
+        void (*shutdown)(struct mbox_chan *chan);
+        bool (*last_tx_done)(struct mbox_chan *chan);
+        bool (*peek_data)(struct mbox_chan *chan);
+};
+/**
+ * struct mbox_controller - Controller of a class of communication channels
+ * @dev:                Device backing this controller
+ * @ops:                Operators that work on each communication chan
+ * @chans:              Array of channels
+ * @num_chans:          Number of channels in the 'chans' array.
+ * @txdone_irq:         Indicates if the controller can report to API when
+ *                      the last transmitted data was read by the remote.
+ *                      Eg, if it has some TX ACK irq.
+ * @txdone_poll:        If the controller can read but not report the TX
+ *                      done. Ex, some register shows the TX status but
+ *                      no interrupt rises. Ignored if 'txdone_irq' is set.
+ * @txpoll_period:      If 'txdone_poll' is in effect, the API polls for
+ *                      last TX's status after these many millisecs
+ * @of_xlate:           Controller driver specific mapping of channel via DT
+ * @poll:               API private. Used to poll for TXDONE on all channels.
+ * @node:               API private. To hook into list of controllers.
+ */
+struct mbox_controller {
+        struct device *dev;
+        struct mbox_chan_ops *ops;
+        struct mbox_chan *chans;
+        int num_chans;
+        bool txdone_irq;
+        bool txdone_poll;
+        unsigned txpoll_period;
+        struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
+                                      const struct of_phandle_args *sp);
+        /* Internal to API */
+        struct timer_list poll;
+        struct list_head node;
+};
+/*
+ * The length of circular buffer for queuing messages from a client.
+ * 'msg_count' tracks the number of buffered messages while 'msg_free'
+ * is the index where the next message would be buffered.
+ * We shouldn't need it too big because every transfer is interrupt
+ * triggered and if we have lots of data to transfer, the interrupt
+ * latencies are going to be the bottleneck, not the buffer length.
+ * Besides, mbox_send_message could be called from atomic context and
+ * the client could also queue another message from the notifier 'tx_done'
+ * of the last transfer done.
+ * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
+ * print, it needs to be taken from config option or somesuch.
+ */
+#define MBOX_TX_QUEUE_LEN       20
+/**
+ * struct mbox_chan - s/w representation of a communication chan
+ * @mbox:               Pointer to the parent/provider of this channel
+ * @txdone_method:      Way to detect TXDone chosen by the API
+ * @cl:                 Pointer to the current owner of this channel
+ * @tx_complete:        Transmission completion
+ * @active_req:         Currently active request hook
+ * @msg_count:          No. of mssg currently queued
+ * @msg_free:           Index of next available mssg slot
+ * @msg_data:           Hook for data packet
+ * @lock:               Serialise access to the channel
+ * @con_priv:           Hook for controller driver to attach private data
+ */
+struct mbox_chan {
+        struct mbox_controller *mbox;
+        unsigned txdone_method;
+        struct mbox_client *cl;
+        struct completion tx_complete;
+        void *active_req;
+        unsigned msg_count, msg_free;
+        void *msg_data[MBOX_TX_QUEUE_LEN];
+        spinlock_t lock; /* Serialise access to the channel */
+        void *con_priv;
+};
+int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
+void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
+void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
+void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
+#endif /* __MAILBOX_CONTROLLER_H */

diff --git a/include/linux/mailbox_controller.h b/include/linux/mailbox_controller.h new file mode 100644 index 000000000000..d4cf96f07cfc --- /dev/null +++ b/include/linux/mailbox_controller.h
@@ -0,0 +1,133 @@
	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/timer.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: API private. Used to poll for TXDONE on all channels.
	71	* @node: API private. To hook into list of controllers.
	72	*/
	73	struct mbox_controller {
	74	struct device *dev;
	75	struct mbox_chan_ops *ops;
	76	struct mbox_chan *chans;
	77	int num_chans;
	78	bool txdone_irq;
	79	bool txdone_poll;
	80	unsigned txpoll_period;
	81	struct mbox_chan (of_xlate)(struct mbox_controller *mbox,
	82	const struct of_phandle_args *sp);
	83	/* Internal to API */
	84	struct timer_list poll;
	85	struct list_head node;
	86	};
	87
	88	/*
	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.
	100	*/
	101	#define MBOX_TX_QUEUE_LEN 20
	102
	103	/**
	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
	115	*/
	116	struct mbox_chan {
	117	struct mbox_controller *mbox;
	118	unsigned txdone_method;
	119	struct mbox_client *cl;
	120	struct completion tx_complete;
	121	void *active_req;
	122	unsigned msg_count, msg_free;
	123	void *msg_data[MBOX_TX_QUEUE_LEN];
	124	spinlock_t lock; /* Serialise access to the channel */
	125	void *con_priv;
	126	};
	127
	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 */
	132
	133	#endif /* __MAILBOX_CONTROLLER_H */