include/linux/mailbox_controller.h

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