mailbox_controller.h 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  1. /* SPDX-License-Identifier: GPL-2.0-only */
  2. #ifndef __MAILBOX_CONTROLLER_H
  3. #define __MAILBOX_CONTROLLER_H
  4. #include <linux/of.h>
  5. #include <linux/types.h>
  6. #include <linux/hrtimer.h>
  7. #include <linux/device.h>
  8. #include <linux/completion.h>
  9. struct mbox_chan;
  10. /**
  11. * struct mbox_chan_ops - methods to control mailbox channels
  12. * @send_data: The API asks the MBOX controller driver, in atomic
  13. * context try to transmit a message on the bus. Returns 0 if
  14. * data is accepted for transmission, -EBUSY while rejecting
  15. * if the remote hasn't yet read the last data sent. Actual
  16. * transmission of data is reported by the controller via
  17. * mbox_chan_txdone (if it has some TX ACK irq). It must not
  18. * sleep.
  19. * @flush: Called when a client requests transmissions to be blocking but
  20. * the context doesn't allow sleeping. Typically the controller
  21. * will implement a busy loop waiting for the data to flush out.
  22. * @startup: Called when a client requests the chan. The controller
  23. * could ask clients for additional parameters of communication
  24. * to be provided via client's chan_data. This call may
  25. * block. After this call the Controller must forward any
  26. * data received on the chan by calling mbox_chan_received_data.
  27. * The controller may do stuff that need to sleep.
  28. * @shutdown: Called when a client relinquishes control of a chan.
  29. * This call may block too. The controller must not forward
  30. * any received data anymore.
  31. * The controller may do stuff that need to sleep.
  32. * @last_tx_done: If the controller sets 'txdone_poll', the API calls
  33. * this to poll status of last TX. The controller must
  34. * give priority to IRQ method over polling and never
  35. * set both txdone_poll and txdone_irq. Only in polling
  36. * mode 'send_data' is expected to return -EBUSY.
  37. * The controller may do stuff that need to sleep/block.
  38. * Used only if txdone_poll:=true && txdone_irq:=false
  39. * @peek_data: Atomic check for any received data. Return true if controller
  40. * has some data to push to the client. False otherwise.
  41. */
  42. struct mbox_chan_ops {
  43. int (*send_data)(struct mbox_chan *chan, void *data);
  44. int (*flush)(struct mbox_chan *chan, unsigned long timeout);
  45. int (*startup)(struct mbox_chan *chan);
  46. void (*shutdown)(struct mbox_chan *chan);
  47. bool (*last_tx_done)(struct mbox_chan *chan);
  48. bool (*peek_data)(struct mbox_chan *chan);
  49. };
  50. /**
  51. * struct mbox_controller - Controller of a class of communication channels
  52. * @dev: Device backing this controller
  53. * @ops: Operators that work on each communication chan
  54. * @chans: Array of channels
  55. * @num_chans: Number of channels in the 'chans' array.
  56. * @txdone_irq: Indicates if the controller can report to API when
  57. * the last transmitted data was read by the remote.
  58. * Eg, if it has some TX ACK irq.
  59. * @txdone_poll: If the controller can read but not report the TX
  60. * done. Ex, some register shows the TX status but
  61. * no interrupt rises. Ignored if 'txdone_irq' is set.
  62. * @txpoll_period: If 'txdone_poll' is in effect, the API polls for
  63. * last TX's status after these many millisecs
  64. * @of_xlate: Controller driver specific mapping of channel via DT
  65. * @poll_hrt: API private. hrtimer used to poll for TXDONE on all
  66. * channels.
  67. * @node: API private. To hook into list of controllers.
  68. */
  69. struct mbox_controller {
  70. struct device *dev;
  71. const struct mbox_chan_ops *ops;
  72. struct mbox_chan *chans;
  73. int num_chans;
  74. bool txdone_irq;
  75. bool txdone_poll;
  76. unsigned txpoll_period;
  77. struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
  78. const struct of_phandle_args *sp);
  79. /* Internal to API */
  80. struct hrtimer poll_hrt;
  81. struct list_head node;
  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 transfer 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. * REVISIT: 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 - s/w representation of a communication chan
  99. * @mbox: Pointer to the parent/provider of this channel
  100. * @txdone_method: Way to detect TXDone chosen by the API
  101. * @cl: Pointer to the current owner of this channel
  102. * @tx_complete: Transmission completion
  103. * @active_req: Currently active request hook
  104. * @msg_count: No. of mssg currently queued
  105. * @msg_free: Index of next available mssg slot
  106. * @msg_data: Hook for data packet
  107. * @lock: Serialise access to the channel
  108. * @con_priv: Hook for controller driver to attach private data
  109. */
  110. struct mbox_chan {
  111. struct mbox_controller *mbox;
  112. unsigned txdone_method;
  113. struct mbox_client *cl;
  114. struct completion tx_complete;
  115. void *active_req;
  116. unsigned msg_count, msg_free;
  117. void *msg_data[MBOX_TX_QUEUE_LEN];
  118. spinlock_t lock; /* Serialise access to the channel */
  119. void *con_priv;
  120. };
  121. int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
  122. void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
  123. void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
  124. void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
  125. int devm_mbox_controller_register(struct device *dev,
  126. struct mbox_controller *mbox);
  127. void devm_mbox_controller_unregister(struct device *dev,
  128. struct mbox_controller *mbox);
  129. #endif /* __MAILBOX_CONTROLLER_H */