include/linux/mailbox_controller.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002
0003 #ifndef __MAILBOX_CONTROLLER_H
0004 #define __MAILBOX_CONTROLLER_H
0005
0006 #include <linux/of.h>
0007 #include <linux/types.h>
0008 #include <linux/hrtimer.h>
0009 #include <linux/device.h>
0010 #include <linux/completion.h>
0011
0012 struct mbox_chan;
0013
0014 /**
0015  * struct mbox_chan_ops - methods to control mailbox channels
0016  * @send_data:  The API asks the MBOX controller driver, in atomic
0017  *      context try to transmit a message on the bus. Returns 0 if
0018  *      data is accepted for transmission, -EBUSY while rejecting
0019  *      if the remote hasn't yet read the last data sent. Actual
0020  *      transmission of data is reported by the controller via
0021  *      mbox_chan_txdone (if it has some TX ACK irq). It must not
0022  *      sleep.
0023  * @flush:  Called when a client requests transmissions to be blocking but
0024  *      the context doesn't allow sleeping. Typically the controller
0025  *      will implement a busy loop waiting for the data to flush out.
0026  * @startup:    Called when a client requests the chan. The controller
0027  *      could ask clients for additional parameters of communication
0028  *      to be provided via client's chan_data. This call may
0029  *      block. After this call the Controller must forward any
0030  *      data received on the chan by calling mbox_chan_received_data.
0031  *      The controller may do stuff that need to sleep.
0032  * @shutdown:   Called when a client relinquishes control of a chan.
0033  *      This call may block too. The controller must not forward
0034  *      any received data anymore.
0035  *      The controller may do stuff that need to sleep.
0036  * @last_tx_done: If the controller sets 'txdone_poll', the API calls
0037  *        this to poll status of last TX. The controller must
0038  *        give priority to IRQ method over polling and never
0039  *        set both txdone_poll and txdone_irq. Only in polling
0040  *        mode 'send_data' is expected to return -EBUSY.
0041  *        The controller may do stuff that need to sleep/block.
0042  *        Used only if txdone_poll:=true && txdone_irq:=false
0043  * @peek_data: Atomic check for any received data. Return true if controller
0044  *        has some data to push to the client. False otherwise.
0045  */
0046 struct mbox_chan_ops {
0047     int (*send_data)(struct mbox_chan *chan, void *data);
0048     int (*flush)(struct mbox_chan *chan, unsigned long timeout);
0049     int (*startup)(struct mbox_chan *chan);
0050     void (*shutdown)(struct mbox_chan *chan);
0051     bool (*last_tx_done)(struct mbox_chan *chan);
0052     bool (*peek_data)(struct mbox_chan *chan);
0053 };
0054
0055 /**
0056  * struct mbox_controller - Controller of a class of communication channels
0057  * @dev:        Device backing this controller
0058  * @ops:        Operators that work on each communication chan
0059  * @chans:      Array of channels
0060  * @num_chans:      Number of channels in the 'chans' array.
0061  * @txdone_irq:     Indicates if the controller can report to API when
0062  *          the last transmitted data was read by the remote.
0063  *          Eg, if it has some TX ACK irq.
0064  * @txdone_poll:    If the controller can read but not report the TX
0065  *          done. Ex, some register shows the TX status but
0066  *          no interrupt rises. Ignored if 'txdone_irq' is set.
0067  * @txpoll_period:  If 'txdone_poll' is in effect, the API polls for
0068  *          last TX's status after these many millisecs
0069  * @of_xlate:       Controller driver specific mapping of channel via DT
0070  * @poll_hrt:       API private. hrtimer used to poll for TXDONE on all
0071  *          channels.
0072  * @node:       API private. To hook into list of controllers.
0073  */
0074 struct mbox_controller {
0075     struct device *dev;
0076     const struct mbox_chan_ops *ops;
0077     struct mbox_chan *chans;
0078     int num_chans;
0079     bool txdone_irq;
0080     bool txdone_poll;
0081     unsigned txpoll_period;
0082     struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
0083                       const struct of_phandle_args *sp);
0084     /* Internal to API */
0085     struct hrtimer poll_hrt;
0086     spinlock_t poll_hrt_lock;
0087     struct list_head node;
0088 };
0089
0090 /*
0091  * The length of circular buffer for queuing messages from a client.
0092  * 'msg_count' tracks the number of buffered messages while 'msg_free'
0093  * is the index where the next message would be buffered.
0094  * We shouldn't need it too big because every transfer is interrupt
0095  * triggered and if we have lots of data to transfer, the interrupt
0096  * latencies are going to be the bottleneck, not the buffer length.
0097  * Besides, mbox_send_message could be called from atomic context and
0098  * the client could also queue another message from the notifier 'tx_done'
0099  * of the last transfer done.
0100  * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
0101  * print, it needs to be taken from config option or somesuch.
0102  */
0103 #define MBOX_TX_QUEUE_LEN   20
0104
0105 /**
0106  * struct mbox_chan - s/w representation of a communication chan
0107  * @mbox:       Pointer to the parent/provider of this channel
0108  * @txdone_method:  Way to detect TXDone chosen by the API
0109  * @cl:         Pointer to the current owner of this channel
0110  * @tx_complete:    Transmission completion
0111  * @active_req:     Currently active request hook
0112  * @msg_count:      No. of mssg currently queued
0113  * @msg_free:       Index of next available mssg slot
0114  * @msg_data:       Hook for data packet
0115  * @lock:       Serialise access to the channel
0116  * @con_priv:       Hook for controller driver to attach private data
0117  */
0118 struct mbox_chan {
0119     struct mbox_controller *mbox;
0120     unsigned txdone_method;
0121     struct mbox_client *cl;
0122     struct completion tx_complete;
0123     void *active_req;
0124     unsigned msg_count, msg_free;
0125     void *msg_data[MBOX_TX_QUEUE_LEN];
0126     spinlock_t lock; /* Serialise access to the channel */
0127     void *con_priv;
0128 };
0129
0130 int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
0131 void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
0132 void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
0133 void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
0134
0135 int devm_mbox_controller_register(struct device *dev,
0136                   struct mbox_controller *mbox);
0137 void devm_mbox_controller_unregister(struct device *dev,
0138                      struct mbox_controller *mbox);
0139
0140 #endif /* __MAILBOX_CONTROLLER_H */