fsl_qbman_portal.h 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (C) 2014 Freescale Semiconductor
  4. */
  5. #ifndef _FSL_QBMAN_PORTAL_H
  6. #define _FSL_QBMAN_PORTAL_H
  7. #include <fsl-mc/fsl_qbman_base.h>
  8. /* Create and destroy a functional object representing the given QBMan portal
  9. * descriptor. */
  10. struct qbman_swp *qbman_swp_init(const struct qbman_swp_desc *);
  11. /************/
  12. /* Dequeues */
  13. /************/
  14. /* See the QBMan driver API documentation for details on the enqueue
  15. * mechanisms. NB: the use of a 'ldpaa_' prefix for this type is because it is
  16. * primarily used by the "DPIO" layer that sits above (and hides) the QBMan
  17. * driver. The structure is defined in the DPIO interface, but to avoid circular
  18. * dependencies we just pre/re-declare it here opaquely. */
  19. struct ldpaa_dq;
  20. /* ------------------- */
  21. /* Pull-mode dequeuing */
  22. /* ------------------- */
  23. struct qbman_pull_desc {
  24. uint32_t dont_manipulate_directly[6];
  25. };
  26. /* Clear the contents of a descriptor to default/starting state. */
  27. void qbman_pull_desc_clear(struct qbman_pull_desc *);
  28. /* If not called, or if called with 'storage' as NULL, the result pull dequeues
  29. * will produce results to DQRR. If 'storage' is non-NULL, then results are
  30. * produced to the given memory location (using the physical/DMA address which
  31. * the caller provides in 'storage_phys'), and 'stash' controls whether or not
  32. * those writes to main-memory express a cache-warming attribute. */
  33. void qbman_pull_desc_set_storage(struct qbman_pull_desc *,
  34. struct ldpaa_dq *storage,
  35. dma_addr_t storage_phys,
  36. int stash);
  37. /* numframes must be between 1 and 16, inclusive */
  38. void qbman_pull_desc_set_numframes(struct qbman_pull_desc *, uint8_t numframes);
  39. /* token is the value that shows up in the dequeue results that can be used to
  40. * detect when the results have been published, and is not really used when
  41. * dequeue results go to DQRR. The easiest technique is to zero result "storage"
  42. * before issuing a pull dequeue, and use any non-zero 'token' value. */
  43. void qbman_pull_desc_set_token(struct qbman_pull_desc *, uint8_t token);
  44. /* Exactly one of the following descriptor "actions" should be set. (Calling any
  45. * one of these will replace the effect of any prior call to one of these.)
  46. * - pull dequeue from the given frame queue (FQ)
  47. * - pull dequeue from any FQ in the given work queue (WQ)
  48. * - pull dequeue from any FQ in any WQ in the given channel
  49. */
  50. void qbman_pull_desc_set_fq(struct qbman_pull_desc *, uint32_t fqid);
  51. /* Issue the pull dequeue command */
  52. int qbman_swp_pull(struct qbman_swp *, struct qbman_pull_desc *);
  53. /* -------------------------------- */
  54. /* Polling DQRR for dequeue results */
  55. /* -------------------------------- */
  56. /* NULL return if there are no unconsumed DQRR entries. Returns a DQRR entry
  57. * only once, so repeated calls can return a sequence of DQRR entries, without
  58. * requiring they be consumed immediately or in any particular order. */
  59. const struct ldpaa_dq *qbman_swp_dqrr_next(struct qbman_swp *);
  60. /* Consume DQRR entries previously returned from qbman_swp_dqrr_next(). */
  61. void qbman_swp_dqrr_consume(struct qbman_swp *, const struct ldpaa_dq *);
  62. /* ------------------------------------------------- */
  63. /* Polling user-provided storage for dequeue results */
  64. /* ------------------------------------------------- */
  65. /* Only used for user-provided storage of dequeue results, not DQRR. Prior to
  66. * being used, the storage must set "oldtoken", so that the driver notices when
  67. * hardware has filled it in with results using a "newtoken". NB, for efficiency
  68. * purposes, the driver will perform any required endianness conversion to
  69. * ensure that the user's dequeue result storage is in host-endian format
  70. * (whether or not that is the same as the little-endian format that hardware
  71. * DMA'd to the user's storage). As such, once the user has called
  72. * qbman_dq_entry_has_newtoken() and been returned a valid dequeue result, they
  73. * should not call it again on the same memory location (except of course if
  74. * another dequeue command has been executed to produce a new result to that
  75. * location).
  76. */
  77. void qbman_dq_entry_set_oldtoken(struct ldpaa_dq *,
  78. unsigned int num_entries,
  79. uint8_t oldtoken);
  80. int qbman_dq_entry_has_newtoken(struct qbman_swp *,
  81. const struct ldpaa_dq *,
  82. uint8_t newtoken);
  83. /* -------------------------------------------------------- */
  84. /* Parsing dequeue entries (DQRR and user-provided storage) */
  85. /* -------------------------------------------------------- */
  86. /* DQRR entries may contain non-dequeue results, ie. notifications */
  87. int qbman_dq_entry_is_DQ(const struct ldpaa_dq *);
  88. /************/
  89. /* Enqueues */
  90. /************/
  91. struct qbman_eq_desc {
  92. uint32_t dont_manipulate_directly[8];
  93. };
  94. /* Clear the contents of a descriptor to default/starting state. */
  95. void qbman_eq_desc_clear(struct qbman_eq_desc *);
  96. /* Exactly one of the following descriptor "actions" should be set. (Calling
  97. * any one of these will replace the effect of any prior call to one of these.)
  98. * - enqueue without order-restoration
  99. * - enqueue with order-restoration
  100. * - fill a hole in the order-restoration sequence, without any enqueue
  101. * - advance NESN (Next Expected Sequence Number), without any enqueue
  102. * 'respond_success' indicates whether an enqueue response should be DMA'd
  103. * after success (otherwise a response is DMA'd only after failure).
  104. * 'incomplete' indicates that other fragments of the same 'seqnum' are yet to
  105. * be enqueued.
  106. */
  107. void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *, int respond_success);
  108. void qbman_eq_desc_set_response(struct qbman_eq_desc *,
  109. dma_addr_t storage_phys,
  110. int stash);
  111. /* token is the value that shows up in an enqueue response that can be used to
  112. * detect when the results have been published. The easiest technique is to zero
  113. * result "storage" before issuing an enqueue, and use any non-zero 'token'
  114. * value. */
  115. void qbman_eq_desc_set_token(struct qbman_eq_desc *, uint8_t token);
  116. /* Exactly one of the following descriptor "targets" should be set. (Calling any
  117. * one of these will replace the effect of any prior call to one of these.)
  118. * - enqueue to a frame queue
  119. * - enqueue to a queuing destination
  120. * Note, that none of these will have any affect if the "action" type has been
  121. * set to "orp_hole" or "orp_nesn".
  122. */
  123. void qbman_eq_desc_set_fq(struct qbman_eq_desc *, uint32_t fqid);
  124. void qbman_eq_desc_set_qd(struct qbman_eq_desc *, uint32_t qdid,
  125. uint32_t qd_bin, uint32_t qd_prio);
  126. /* Issue an enqueue command. ('fd' should only be NULL if the "action" of the
  127. * descriptor is "orp_hole" or "orp_nesn".) */
  128. int qbman_swp_enqueue(struct qbman_swp *, const struct qbman_eq_desc *,
  129. const struct qbman_fd *fd);
  130. /*******************/
  131. /* Buffer releases */
  132. /*******************/
  133. struct qbman_release_desc {
  134. uint32_t dont_manipulate_directly[1];
  135. };
  136. /* Clear the contents of a descriptor to default/starting state. */
  137. void qbman_release_desc_clear(struct qbman_release_desc *);
  138. /* Set the ID of the buffer pool to release to */
  139. void qbman_release_desc_set_bpid(struct qbman_release_desc *, uint32_t bpid);
  140. /* Issue a release command. 'num_buffers' must be less than 8. */
  141. int qbman_swp_release(struct qbman_swp *, const struct qbman_release_desc *,
  142. const uint64_t *buffers, unsigned int num_buffers);
  143. /*******************/
  144. /* Buffer acquires */
  145. /*******************/
  146. int qbman_swp_acquire(struct qbman_swp *, uint32_t bpid, uint64_t *buffers,
  147. unsigned int num_buffers);
  148. #endif /* !_FSL_QBMAN_PORTAL_H */