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