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