drivers/raw/dpaa2_qdma/rte_pmd_dpaa2_qdma.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2018 NXP
   3  */
   4
   5 #ifndef __RTE_PMD_DPAA2_QDMA_H__
   6 #define __RTE_PMD_DPAA2_QDMA_H__
   7
   8 /**
   9  * @file
  10  *
  11  * NXP dpaa2 QDMA specific structures.
  12  *
  13  */
  14
  15 /** Determines the mode of operation */
  16 enum {
  17         /**
  18          * Allocate a H/W queue per VQ i.e. Exclusive hardware queue for a VQ.
  19          * This mode will have best performance.
  20          */
  21         RTE_QDMA_MODE_HW,
  22         /**
  23          * A VQ shall not have an exclusive associated H/W queue.
  24          * Rather a H/W Queue will be shared by multiple Virtual Queues.
  25          * This mode will have intermediate data structures to support
  26          * multi VQ to PQ mappings thus having some performance implications.
  27          * Note: Even in this mode there is an option to allocate a H/W
  28          * queue for a VQ. Please see 'RTE_QDMA_VQ_EXCLUSIVE_PQ' flag.
  29          */
  30         RTE_QDMA_MODE_VIRTUAL
  31 };
  32
  33 /**
  34  * If user has configued a Virtual Queue mode, but for some particular VQ
  35  * user needs an exclusive H/W queue associated (for better performance
  36  * on that particular VQ), then user can pass this flag while creating the
  37  * Virtual Queue. A H/W queue will be allocated corresponding to
  38  * VQ which uses this flag.
  39  */
  40 #define RTE_QDMA_VQ_EXCLUSIVE_PQ        (1ULL)
  41
  42 /** States if the source addresses is physical. */
  43 #define RTE_QDMA_JOB_SRC_PHY            (1ULL)
  44
  45 /** States if the destination addresses is physical. */
  46 #define RTE_QDMA_JOB_DEST_PHY           (1ULL << 1)
  47
  48 /** Provides QDMA device attributes */
  49 struct rte_qdma_attr {
  50         /** total number of hw QDMA queues present */
  51         uint16_t num_hw_queues;
  52 };
  53
  54 /** QDMA device configuration structure */
  55 struct rte_qdma_config {
  56         /** Number of maximum hw queues to allocate per core. */
  57         uint16_t max_hw_queues_per_core;
  58         /** Maximum number of VQ's to be used. */
  59         uint16_t max_vqs;
  60         /** mode of operation - physical(h/w) or virtual */
  61         uint8_t mode;
  62         /**
  63          * User provides this as input to the driver as a size of the FLE pool.
  64          * FLE's (and corresponding source/destination descriptors) are
  65          * allocated by the driver at enqueue time to store src/dest and
  66          * other data and are freed at the dequeue time. This determines the
  67          * maximum number of inflight jobs on the QDMA device. This should
  68          * be power of 2.
  69          */
  70         int fle_pool_count;
  71 };
  72
  73 /** Provides QDMA device statistics */
  74 struct rte_qdma_vq_stats {
  75         /** States if this vq has exclusively associated hw queue */
  76         uint8_t exclusive_hw_queue;
  77         /** Associated lcore id */
  78         uint32_t lcore_id;
  79         /* Total number of enqueues on this VQ */
  80         uint64_t num_enqueues;
  81         /* Total number of dequeues from this VQ */
  82         uint64_t num_dequeues;
  83         /* total number of pending jobs in this VQ */
  84         uint64_t num_pending_jobs;
  85 };
  86
  87 /** Determines a QDMA job */
  88 struct rte_qdma_job {
  89         /** Source Address from where DMA is (to be) performed */
  90         uint64_t src;
  91         /** Destination Address where DMA is (to be) done */
  92         uint64_t dest;
  93         /** Length of the DMA operation in bytes. */
  94         uint32_t len;
  95         /** See RTE_QDMA_JOB_ flags */
  96         uint32_t flags;
  97         /**
  98          * User can specify a context which will be maintained
  99          * on the dequeue operation.
 100          */
 101         uint64_t cnxt;
 102         /**
 103          * Status of the transaction.
 104          * This is filled in the dequeue operation by the driver.
 105          */
 106         uint8_t status;
 107 };
 108
 109 /**
 110  * Initialize the QDMA device.
 111  *
 112  * @returns
 113  *   - 0: Success.
 114  *   - <0: Error code.
 115  */
 116 int __rte_experimental
 117 rte_qdma_init(void);
 118
 119 /**
 120  * Get the QDMA attributes.
 121  *
 122  * @param qdma_attr
 123  *   QDMA attributes providing total number of hw queues etc.
 124  */
 125 void __rte_experimental
 126 rte_qdma_attr_get(struct rte_qdma_attr *qdma_attr);
 127
 128 /**
 129  * Reset the QDMA device. This API will completely reset the QDMA
 130  * device, bringing it to original state as if only rte_qdma_init() API
 131  * has been called.
 132  *
 133  * @returns
 134  *   - 0: Success.
 135  *   - <0: Error code.
 136  */
 137 int __rte_experimental
 138 rte_qdma_reset(void);
 139
 140 /**
 141  * Configure the QDMA device.
 142  *
 143  * @returns
 144  *   - 0: Success.
 145  *   - <0: Error code.
 146  */
 147 int __rte_experimental
 148 rte_qdma_configure(struct rte_qdma_config *qdma_config);
 149
 150 /**
 151  * Start the QDMA device.
 152  *
 153  * @returns
 154  *   - 0: Success.
 155  *   - <0: Error code.
 156  */
 157 int __rte_experimental
 158 rte_qdma_start(void);
 159
 160 /**
 161  * Create a Virtual Queue on a particular lcore id.
 162  * This API can be called from any thread/core. User can create/destroy
 163  * VQ's at runtime.
 164  *
 165  * @param lcore_id
 166  *   LCORE ID on which this particular queue would be associated with.
 167  * @param flags
 168  *  RTE_QDMA_VQ_ flags. See macro definitions.
 169  *
 170  * @returns
 171  *   - >= 0: Virtual queue ID.
 172  *   - <0: Error code.
 173  */
 174 int __rte_experimental
 175 rte_qdma_vq_create(uint32_t lcore_id, uint32_t flags);
 176
 177 /**
 178  * Enqueue multiple jobs to a Virtual Queue.
 179  * If the enqueue is successful, the H/W will perform DMA operations
 180  * on the basis of the QDMA jobs provided.
 181  *
 182  * @param vq_id
 183  *   Virtual Queue ID.
 184  * @param job
 185  *   List of QDMA Jobs containing relevant information related to DMA.
 186  * @param nb_jobs
 187  *   Number of QDMA jobs provided by the user.
 188  *
 189  * @returns
 190  *   - >=0: Number of jobs successfully submitted
 191  *   - <0: Error code.
 192  */
 193 int __rte_experimental
 194 rte_qdma_vq_enqueue_multi(uint16_t vq_id,
 195                           struct rte_qdma_job **job,
 196                           uint16_t nb_jobs);
 197
 198 /**
 199  * Enqueue a single job to a Virtual Queue.
 200  * If the enqueue is successful, the H/W will perform DMA operations
 201  * on the basis of the QDMA job provided.
 202  *
 203  * @param vq_id
 204  *   Virtual Queue ID.
 205  * @param job
 206  *   A QDMA Job containing relevant information related to DMA.
 207  *
 208  * @returns
 209  *   - >=0: Number of jobs successfully submitted
 210  *   - <0: Error code.
 211  */
 212 int __rte_experimental
 213 rte_qdma_vq_enqueue(uint16_t vq_id,
 214                     struct rte_qdma_job *job);
 215
 216 /**
 217  * Dequeue multiple completed jobs from a Virtual Queue.
 218  * Provides the list of completed jobs capped by nb_jobs.
 219  *
 220  * @param vq_id
 221  *   Virtual Queue ID.
 222  * @param job
 223  *   List of QDMA Jobs returned from the API.
 224  * @param nb_jobs
 225  *   Number of QDMA jobs requested for dequeue by the user.
 226  *
 227  * @returns
 228  *   Number of jobs actually dequeued.
 229  */
 230 int __rte_experimental
 231 rte_qdma_vq_dequeue_multi(uint16_t vq_id,
 232                           struct rte_qdma_job **job,
 233                           uint16_t nb_jobs);
 234
 235 /**
 236  * Dequeue a single completed jobs from a Virtual Queue.
 237  *
 238  * @param vq_id
 239  *   Virtual Queue ID.
 240  *
 241  * @returns
 242  *   - A completed job or NULL if no job is there.
 243  */
 244 struct rte_qdma_job * __rte_experimental
 245 rte_qdma_vq_dequeue(uint16_t vq_id);
 246
 247 /**
 248  * Get a Virtual Queue statistics.
 249  *
 250  * @param vq_id
 251  *   Virtual Queue ID.
 252  * @param vq_stats
 253  *   VQ statistics structure which will be filled in by the driver.
 254  */
 255 void __rte_experimental
 256 rte_qdma_vq_stats(uint16_t vq_id,
 257                   struct rte_qdma_vq_stats *vq_stats);
 258
 259 /**
 260  * Destroy the Virtual Queue specified by vq_id.
 261  * This API can be called from any thread/core. User can create/destroy
 262  * VQ's at runtime.
 263  *
 264  * @param vq_id
 265  *   Virtual Queue ID which needs to be deinialized.
 266  *
 267  * @returns
 268  *   - 0: Success.
 269  *   - <0: Error code.
 270  */
 271 int __rte_experimental
 272 rte_qdma_vq_destroy(uint16_t vq_id);
 273
 274 /**
 275  * Stop QDMA device.
 276  */
 277 void __rte_experimental
 278 rte_qdma_stop(void);
 279
 280 /**
 281  * Destroy the QDMA device.
 282  */
 283 void __rte_experimental
 284 rte_qdma_destroy(void);
 285
 286 #endif /* __RTE_PMD_DPAA2_QDMA_H__*/