k3-navss-ringacc.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * TI K3 AM65x NAVSS Ring accelerator Manager (RA) subsystem driver
  4. *
  5. * Copyright (C) 2018 Texas Instruments Incorporated - http://www.ti.com
  6. */
  7. #ifndef __SOC_TI_K3_NAVSS_RINGACC_API_H_
  8. #define __SOC_TI_K3_NAVSS_RINGACC_API_H_
  9. #include <dm/ofnode.h>
  10. #include <linux/bitops.h>
  11. /**
  12. * enum k3_nav_ring_mode - &struct k3_nav_ring_cfg mode
  13. *
  14. * RA ring operational modes
  15. *
  16. * @K3_NAV_RINGACC_RING_MODE_RING: Exposed Ring mode for SW direct access
  17. * @K3_NAV_RINGACC_RING_MODE_MESSAGE: Messaging mode. Messaging mode requires
  18. * that all accesses to the queue must go through this IP so that all
  19. * accesses to the memory are controlled and ordered. This IP then
  20. * controls the entire state of the queue, and SW has no directly control,
  21. * such as through doorbells and cannot access the storage memory directly.
  22. * This is particularly useful when more than one SW or HW entity can be
  23. * the producer and/or consumer at the same time
  24. * @K3_NAV_RINGACC_RING_MODE_CREDENTIALS: Credentials mode is message mode plus
  25. * stores credentials with each message, requiring the element size to be
  26. * doubled to fit the credentials. Any exposed memory should be protected
  27. * by a firewall from unwanted access
  28. * @K3_NAV_RINGACC_RING_MODE_QM: Queue manager mode. This takes the credentials
  29. * mode and adds packet length per element, along with additional read only
  30. * fields for element count and accumulated queue length. The QM mode only
  31. * operates with an 8 byte element size (any other element size is
  32. * illegal), and like in credentials mode each operation uses 2 element
  33. * slots to store the credentials and length fields
  34. */
  35. enum k3_nav_ring_mode {
  36. K3_NAV_RINGACC_RING_MODE_RING = 0,
  37. K3_NAV_RINGACC_RING_MODE_MESSAGE,
  38. K3_NAV_RINGACC_RING_MODE_CREDENTIALS,
  39. K3_NAV_RINGACC_RING_MODE_QM,
  40. k3_NAV_RINGACC_RING_MODE_INVALID
  41. };
  42. /**
  43. * enum k3_nav_ring_size - &struct k3_nav_ring_cfg elm_size
  44. *
  45. * RA ring element's sizes in bytes.
  46. */
  47. enum k3_nav_ring_size {
  48. K3_NAV_RINGACC_RING_ELSIZE_4 = 0,
  49. K3_NAV_RINGACC_RING_ELSIZE_8,
  50. K3_NAV_RINGACC_RING_ELSIZE_16,
  51. K3_NAV_RINGACC_RING_ELSIZE_32,
  52. K3_NAV_RINGACC_RING_ELSIZE_64,
  53. K3_NAV_RINGACC_RING_ELSIZE_128,
  54. K3_NAV_RINGACC_RING_ELSIZE_256,
  55. K3_NAV_RINGACC_RING_ELSIZE_INVALID
  56. };
  57. struct k3_nav_ringacc;
  58. struct k3_nav_ring;
  59. /**
  60. * enum k3_nav_ring_cfg - RA ring configuration structure
  61. *
  62. * @size: Ring size, number of elements
  63. * @elm_size: Ring element size
  64. * @mode: Ring operational mode
  65. * @flags: Ring configuration flags. Possible values:
  66. * @K3_NAV_RINGACC_RING_SHARED: when set allows to request the same ring
  67. * few times. It's usable when the same ring is used as Free Host PD ring
  68. * for different flows, for example.
  69. * Note: Locking should be done by consumer if required
  70. */
  71. struct k3_nav_ring_cfg {
  72. u32 size;
  73. enum k3_nav_ring_size elm_size;
  74. enum k3_nav_ring_mode mode;
  75. #define K3_NAV_RINGACC_RING_SHARED BIT(1)
  76. u32 flags;
  77. };
  78. #define K3_NAV_RINGACC_RING_ID_ANY (-1)
  79. #define K3_NAV_RINGACC_RING_USE_PROXY BIT(1)
  80. /**
  81. * k3_nav_ringacc_request_ring - request ring from ringacc
  82. * @ringacc: pointer on ringacc
  83. * @id: ring id or K3_NAV_RINGACC_RING_ID_ANY for any general purpose ring
  84. * @flags:
  85. * @K3_NAV_RINGACC_RING_USE_PROXY: if set - proxy will be allocated and
  86. * used to access ring memory. Sopported only for rings in
  87. * Message/Credentials/Queue mode.
  88. *
  89. * Returns pointer on the Ring - struct k3_nav_ring
  90. * or NULL in case of failure.
  91. */
  92. struct k3_nav_ring *k3_nav_ringacc_request_ring(struct k3_nav_ringacc *ringacc,
  93. int id, u32 flags);
  94. int k3_nav_ringacc_request_rings_pair(struct k3_nav_ringacc *ringacc,
  95. int fwd_id, int compl_id,
  96. struct k3_nav_ring **fwd_ring,
  97. struct k3_nav_ring **compl_ring);
  98. /**
  99. * k3_nav_ringacc_get_dev - get pointer on RA device
  100. * @ringacc: pointer on RA
  101. *
  102. * Returns device pointer
  103. */
  104. struct udevice *k3_nav_ringacc_get_dev(struct k3_nav_ringacc *ringacc);
  105. /**
  106. * k3_nav_ringacc_ring_reset - ring reset
  107. * @ring: pointer on Ring
  108. *
  109. * Resets ring internal state ((hw)occ, (hw)idx).
  110. * TODO_GS: ? Ring can be reused without reconfiguration
  111. */
  112. void k3_nav_ringacc_ring_reset(struct k3_nav_ring *ring);
  113. /**
  114. * k3_nav_ringacc_ring_reset - ring reset for DMA rings
  115. * @ring: pointer on Ring
  116. *
  117. * Resets ring internal state ((hw)occ, (hw)idx). Should be used for rings
  118. * which are read by K3 UDMA, like TX or Free Host PD rings.
  119. */
  120. void k3_nav_ringacc_ring_reset_dma(struct k3_nav_ring *ring, u32 occ);
  121. /**
  122. * k3_nav_ringacc_ring_free - ring free
  123. * @ring: pointer on Ring
  124. *
  125. * Resets ring and free all alocated resources.
  126. */
  127. int k3_nav_ringacc_ring_free(struct k3_nav_ring *ring);
  128. /**
  129. * k3_nav_ringacc_get_ring_id - Get the Ring ID
  130. * @ring: pointer on ring
  131. *
  132. * Returns the Ring ID
  133. */
  134. u32 k3_nav_ringacc_get_ring_id(struct k3_nav_ring *ring);
  135. /**
  136. * k3_nav_ringacc_ring_cfg - ring configure
  137. * @ring: pointer on ring
  138. * @cfg: Ring configuration parameters (see &struct k3_nav_ring_cfg)
  139. *
  140. * Configures ring, including ring memory allocation.
  141. * Returns 0 on success, errno otherwise.
  142. */
  143. int k3_nav_ringacc_ring_cfg(struct k3_nav_ring *ring,
  144. struct k3_nav_ring_cfg *cfg);
  145. /**
  146. * k3_nav_ringacc_ring_get_size - get ring size
  147. * @ring: pointer on ring
  148. *
  149. * Returns ring size in number of elements.
  150. */
  151. u32 k3_nav_ringacc_ring_get_size(struct k3_nav_ring *ring);
  152. /**
  153. * k3_nav_ringacc_ring_get_free - get free elements
  154. * @ring: pointer on ring
  155. *
  156. * Returns number of free elements in the ring.
  157. */
  158. u32 k3_nav_ringacc_ring_get_free(struct k3_nav_ring *ring);
  159. /**
  160. * k3_nav_ringacc_ring_get_occ - get ring occupancy
  161. * @ring: pointer on ring
  162. *
  163. * Returns total number of valid entries on the ring
  164. */
  165. u32 k3_nav_ringacc_ring_get_occ(struct k3_nav_ring *ring);
  166. /**
  167. * k3_nav_ringacc_ring_is_full - checks if ring is full
  168. * @ring: pointer on ring
  169. *
  170. * Returns true if the ring is full
  171. */
  172. u32 k3_nav_ringacc_ring_is_full(struct k3_nav_ring *ring);
  173. /**
  174. * k3_nav_ringacc_ring_push - push element to the ring tail
  175. * @ring: pointer on ring
  176. * @elem: pointer on ring element buffer
  177. *
  178. * Push one ring element to the ring tail. Size of the ring element is
  179. * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
  180. *
  181. * Returns 0 on success, errno otherwise.
  182. */
  183. int k3_nav_ringacc_ring_push(struct k3_nav_ring *ring, void *elem);
  184. /**
  185. * k3_nav_ringacc_ring_pop - pop element from the ring head
  186. * @ring: pointer on ring
  187. * @elem: pointer on ring element buffer
  188. *
  189. * Push one ring element from the ring head. Size of the ring element is
  190. * determined by ring configuration &struct k3_nav_ring_cfg elm_size..
  191. *
  192. * Returns 0 on success, errno otherwise.
  193. */
  194. int k3_nav_ringacc_ring_pop(struct k3_nav_ring *ring, void *elem);
  195. /**
  196. * k3_nav_ringacc_ring_push_head - push element to the ring head
  197. * @ring: pointer on ring
  198. * @elem: pointer on ring element buffer
  199. *
  200. * Push one ring element to the ring head. Size of the ring element is
  201. * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
  202. *
  203. * Returns 0 on success, errno otherwise.
  204. * Not Supported by ring modes: K3_NAV_RINGACC_RING_MODE_RING
  205. */
  206. int k3_nav_ringacc_ring_push_head(struct k3_nav_ring *ring, void *elem);
  207. /**
  208. * k3_nav_ringacc_ring_pop_tail - pop element from the ring tail
  209. * @ring: pointer on ring
  210. * @elem: pointer on ring element buffer
  211. *
  212. * Push one ring element from the ring tail. Size of the ring element is
  213. * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
  214. *
  215. * Returns 0 on success, errno otherwise.
  216. * Not Supported by ring modes: K3_NAV_RINGACC_RING_MODE_RING
  217. */
  218. int k3_nav_ringacc_ring_pop_tail(struct k3_nav_ring *ring, void *elem);
  219. #endif /* __SOC_TI_K3_NAVSS_RINGACC_API_H_ */