mailbox_controller.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2
  3#ifndef __MAILBOX_CONTROLLER_H
  4#define __MAILBOX_CONTROLLER_H
  5
  6#include <linux/completion.h>
  7#include <linux/device.h>
  8#include <linux/hrtimer.h>
  9#include <linux/of.h>
 10#include <linux/types.h>
 11
 12struct mbox_chan;
 13
 14/**
 15 * struct mbox_chan_ops - methods to control mailbox channels
 16 * @send_data:	The API asks the MBOX controller driver, in atomic
 17 *		context try to transmit a message on the bus. Returns 0 if
 18 *		data is accepted for transmission, -EBUSY while rejecting
 19 *		if the remote hasn't yet read the last data sent. Actual
 20 *		transmission of data is reported by the controller via
 21 *		mbox_chan_txdone (if it has some TX ACK irq). It must not
 22 *		sleep.
 23 * @flush:	Called when a client requests transmissions to be blocking but
 24 *		the context doesn't allow sleeping. Typically the controller
 25 *		will implement a busy loop waiting for the data to flush out.
 26 * @startup:	Called when a client requests the chan. The controller
 27 *		could ask clients for additional parameters of communication
 28 *		to be provided via client's chan_data. This call may
 29 *		block. After this call the Controller must forward any
 30 *		data received on the chan by calling mbox_chan_received_data.
 31 *		The controller may do stuff that need to sleep.
 32 * @shutdown:	Called when a client relinquishes control of a chan.
 33 *		This call may block too. The controller must not forward
 34 *		any received data anymore.
 35 *		The controller may do stuff that need to sleep.
 36 * @last_tx_done: If the controller sets 'txdone_poll', the API calls
 37 *		  this to poll status of last TX. The controller must
 38 *		  give priority to IRQ method over polling and never
 39 *		  set both txdone_poll and txdone_irq. Only in polling
 40 *		  mode 'send_data' is expected to return -EBUSY.
 41 *		  The controller may do stuff that need to sleep/block.
 42 *		  Used only if txdone_poll:=true && txdone_irq:=false
 43 * @peek_data: Atomic check for any received data. Return true if controller
 44 *		  has some data to push to the client. False otherwise.
 45 */
 46struct mbox_chan_ops {
 47	int (*send_data)(struct mbox_chan *chan, void *data);
 48	int (*flush)(struct mbox_chan *chan, unsigned long timeout);
 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 * @fw_xlate:		Controller driver specific mapping of channel via fwnode
 70 * @of_xlate:		Controller driver specific mapping of channel via DT
 71 * @poll_hrt:		API private. hrtimer used to poll for TXDONE on all
 72 *			channels.
 73 * @node:		API private. To hook into list of controllers.
 74 */
 75struct mbox_controller {
 76	struct device *dev;
 77	const struct mbox_chan_ops *ops;
 78	struct mbox_chan *chans;
 79	int num_chans;
 80	bool txdone_irq;
 81	bool txdone_poll;
 82	unsigned txpoll_period;
 83	struct mbox_chan *(*fw_xlate)(struct mbox_controller *mbox,
 84				      const struct fwnode_reference_args *sp);
 85	struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
 86				      const struct of_phandle_args *sp);
 87	/* Internal to API */
 88	struct hrtimer poll_hrt;
 89	spinlock_t poll_hrt_lock;
 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);
140#endif /* __MAILBOX_CONTROLLER_H */