include/linux/mailbox_controller.h

   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
  12 struct mbox_chan;
  13
  14 /**
  15  * struct mbox_chan_ops - s/w representation of a communication chan
  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  *              block.
  23  * @startup:    Called when a client requests the chan. The controller
  24  *              could ask clients for additional parameters of communication
  25  *              to be provided via client's chan_data. This call may
  26  *              block. After this call the Controller must forward any
  27  *              data received on the chan by calling mbox_chan_received_data.
  28  * @shutdown:   Called when a client relinquishes control of a chan.
  29  *              This call may block too. The controller must not forwared
  30  *              any received data anymore.
  31  * @last_tx_done: If the controller sets 'txdone_poll', the API calls
  32  *                this to poll status of last TX. The controller must
  33  *                give priority to IRQ method over polling and never
  34  *                set both txdone_poll and txdone_irq. Only in polling
  35  *                mode 'send_data' is expected to return -EBUSY.
  36  *                Used only if txdone_poll:=true && txdone_irq:=false
  37  * @peek_data: Atomic check for any received data. Return true if controller
  38  *                has some data to push to the client. False otherwise.
  39  */
  40 struct mbox_chan_ops {
  41         int (*send_data)(struct mbox_chan *chan, void *data);
  42         int (*startup)(struct mbox_chan *chan);
  43         void (*shutdown)(struct mbox_chan *chan);
  44         bool (*last_tx_done)(struct mbox_chan *chan);
  45         bool (*peek_data)(struct mbox_chan *chan);
  46 };
  47
  48 /**
  49  * struct mbox_controller - Controller of a class of communication chans
  50  * @dev:                Device backing this controller
  51  * @controller_name:    Literal name of the controller.
  52  * @ops:                Operators that work on each communication chan
  53  * @chans:              Null terminated array of chans.
  54  * @txdone_irq:         Indicates if the controller can report to API when
  55  *                      the last transmitted data was read by the remote.
  56  *                      Eg, if it has some TX ACK irq.
  57  * @txdone_poll:        If the controller can read but not report the TX
  58  *                      done. Ex, some register shows the TX status but
  59  *                      no interrupt rises. Ignored if 'txdone_irq' is set.
  60  * @txpoll_period:      If 'txdone_poll' is in effect, the API polls for
  61  *                      last TX's status after these many millisecs
  62  */
  63 struct mbox_controller {
  64         struct device *dev;
  65         struct mbox_chan_ops *ops;
  66         struct mbox_chan *chans;
  67         int num_chans;
  68         bool txdone_irq;
  69         bool txdone_poll;
  70         unsigned txpoll_period;
  71         struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
  72                                         const struct of_phandle_args *sp);
  73         /*
  74          * If the controller supports only TXDONE_BY_POLL,
  75          * this timer polls all the links for txdone.
  76          */
  77         struct timer_list poll;
  78         unsigned period;
  79         /* Hook to add to the global controller list */
  80         struct list_head node;
  81 };
  82
  83 /*
  84  * The length of circular buffer for queuing messages from a client.
  85  * 'msg_count' tracks the number of buffered messages while 'msg_free'
  86  * is the index where the next message would be buffered.
  87  * We shouldn't need it too big because every transferr is interrupt
  88  * triggered and if we have lots of data to transfer, the interrupt
  89  * latencies are going to be the bottleneck, not the buffer length.
  90  * Besides, mbox_send_message could be called from atomic context and
  91  * the client could also queue another message from the notifier 'tx_done'
  92  * of the last transfer done.
  93  * REVIST: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
  94  * print, it needs to be taken from config option or somesuch.
  95  */
  96 #define MBOX_TX_QUEUE_LEN       20
  97
  98 struct mbox_chan {
  99         struct mbox_controller *mbox; /* Parent Controller */
 100         unsigned txdone_method;
 101
 102         /* client */
 103         struct mbox_client *cl;
 104         struct completion tx_complete;
 105
 106         void *active_req;
 107         unsigned msg_count, msg_free;
 108         void *msg_data[MBOX_TX_QUEUE_LEN];
 109         /* Access to the channel */
 110         spinlock_t lock;
 111
 112         /* Private data for controller */
 113         void *con_priv;
 114 };
 115
 116 int mbox_controller_register(struct mbox_controller *mbox);
 117 void mbox_chan_received_data(struct mbox_chan *chan, void *data);
 118 void mbox_chan_txdone(struct mbox_chan *chan, int r);
 119 void mbox_controller_unregister(struct mbox_controller *mbox);
 120
 121 #endif /* __MAILBOX_CONTROLLER_H */