ivc.h 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Copyright (c) 2016, NVIDIA CORPORATION.
  4. */
  5. #ifndef _ASM_ARCH_TEGRA_IVC_H
  6. #define _ASM_ARCH_TEGRA_IVC_H
  7. /*
  8. * Tegra IVC is a communication protocol that transfers fixed-size frames
  9. * bi-directionally and in-order between the local CPU and some remote entity.
  10. * Communication is via a statically sized and allocated buffer in shared
  11. * memory and a notification mechanism.
  12. *
  13. * This API handles all aspects of the shared memory buffer's metadata, and
  14. * leaves all aspects of the frame content to the calling code; frames
  15. * typically contain some higher-level protocol. The notification mechanism is
  16. * also handled externally to this API, since it can vary from instance to
  17. * instance.
  18. *
  19. * The client model is to first find some free (for TX) or filled (for RX)
  20. * frame, process that frame's memory buffer (fill or read it), and then
  21. * inform the protocol that the frame has been filled/read, i.e. advance the
  22. * write/read pointer. If the channel is full, there may be no available frames
  23. * to fill/read. In this case, client code may either poll for an available
  24. * frame, or wait for the remote entity to send a notification to the local
  25. * CPU.
  26. */
  27. /**
  28. * struct tegra_ivc - In-memory shared memory layout.
  29. *
  30. * This is described in detail in ivc.c.
  31. */
  32. struct tegra_ivc_channel_header;
  33. /**
  34. * struct tegra_ivc - Software state of an IVC channel.
  35. *
  36. * This state is internal to the IVC code and should not be accessed directly
  37. * by clients. It is public solely so clients can allocate storage for the
  38. * structure.
  39. */
  40. struct tegra_ivc {
  41. /**
  42. * rx_channel - Pointer to the shared memory region used to receive
  43. * messages from the remote entity.
  44. */
  45. struct tegra_ivc_channel_header *rx_channel;
  46. /**
  47. * tx_channel - Pointer to the shared memory region used to send
  48. * messages to the remote entity.
  49. */
  50. struct tegra_ivc_channel_header *tx_channel;
  51. /**
  52. * r_pos - The position in list of frames in rx_channel that we are
  53. * reading from.
  54. */
  55. uint32_t r_pos;
  56. /**
  57. * w_pos - The position in list of frames in tx_channel that we are
  58. * writing to.
  59. */
  60. uint32_t w_pos;
  61. /**
  62. * nframes - The number of frames allocated (in each direction) in
  63. * shared memory.
  64. */
  65. uint32_t nframes;
  66. /**
  67. * frame_size - The size of each frame in shared memory.
  68. */
  69. uint32_t frame_size;
  70. /**
  71. * notify - Function to call to notify the remote processor of a
  72. * change in channel state.
  73. */
  74. void (*notify)(struct tegra_ivc *);
  75. };
  76. /**
  77. * tegra_ivc_read_get_next_frame - Locate the next frame to receive.
  78. *
  79. * Locate the next frame to be received/processed, return the address of the
  80. * frame, and do not remove it from the queue. Repeated calls to this function
  81. * will return the same address until tegra_ivc_read_advance() is called.
  82. *
  83. * @ivc The IVC channel.
  84. * @frame Pointer to be filled with the address of the frame to receive.
  85. *
  86. * Return: 0 if a frame is available, else a negative error code.
  87. */
  88. int tegra_ivc_read_get_next_frame(struct tegra_ivc *ivc, void **frame);
  89. /**
  90. * tegra_ivc_read_advance - Advance the read queue.
  91. *
  92. * Inform the protocol and remote entity that the frame returned by
  93. * tegra_ivc_read_get_next_frame() has been processed. The remote end may then
  94. * re-use it to transmit further data. Subsequent to this function returning,
  95. * tegra_ivc_read_get_next_frame() will return a different frame.
  96. *
  97. * @ivc The IVC channel.
  98. *
  99. * Return: 0 if OK, else a negative error code.
  100. */
  101. int tegra_ivc_read_advance(struct tegra_ivc *ivc);
  102. /**
  103. * tegra_ivc_write_get_next_frame - Locate the next frame to fill for transmit.
  104. *
  105. * Locate the next frame to be filled for transmit, return the address of the
  106. * frame, and do not add it to the queue. Repeated calls to this function
  107. * will return the same address until tegra_ivc_read_advance() is called.
  108. *
  109. * @ivc The IVC channel.
  110. * @frame Pointer to be filled with the address of the frame to fill.
  111. *
  112. * Return: 0 if a frame is available, else a negative error code.
  113. */
  114. int tegra_ivc_write_get_next_frame(struct tegra_ivc *ivc, void **frame);
  115. /**
  116. * tegra_ivc_write_advance - Advance the write queue.
  117. *
  118. * Inform the protocol and remote entity that the frame returned by
  119. * tegra_ivc_write_get_next_frame() has been filled and should be transmitted.
  120. * The remote end may then read data from it. Subsequent to this function
  121. * returning, tegra_ivc_write_get_next_frame() will return a different frame.
  122. *
  123. * @ivc The IVC channel.
  124. *
  125. * Return: 0 if OK, else a negative error code.
  126. */
  127. int tegra_ivc_write_advance(struct tegra_ivc *ivc);
  128. /**
  129. * tegra_ivc_channel_notified - handle internal messages
  130. *
  131. * This function must be called following every notification.
  132. *
  133. * @ivc The IVC channel.
  134. *
  135. * Return: 0 if the channel is ready for communication, or -EAGAIN if a
  136. * channel reset is in progress.
  137. */
  138. int tegra_ivc_channel_notified(struct tegra_ivc *ivc);
  139. /**
  140. * tegra_ivc_channel_reset - initiates a reset of the shared memory state
  141. *
  142. * This function must be called after a channel is initialized but before it
  143. * is used for communication. The channel will be ready for use when a
  144. * subsequent call to notify the remote of the channel reset indicates the
  145. * reset operation is complete.
  146. *
  147. * @ivc The IVC channel.
  148. */
  149. void tegra_ivc_channel_reset(struct tegra_ivc *ivc);
  150. /**
  151. * tegra_ivc_init - Initialize a channel's software state.
  152. *
  153. * @ivc The IVC channel.
  154. * @rx_base Address of the the RX shared memory buffer.
  155. * @tx_base Address of the the TX shared memory buffer.
  156. * @nframes Number of frames in each shared memory buffer.
  157. * @frame_size Size of each frame.
  158. *
  159. * Return: 0 if OK, else a negative error code.
  160. */
  161. int tegra_ivc_init(struct tegra_ivc *ivc, ulong rx_base, ulong tx_base,
  162. uint32_t nframes, uint32_t frame_size,
  163. void (*notify)(struct tegra_ivc *));
  164. #endif