drivers/raw/dpaa2_qdma/rte_pmd_dpaa2_qdma.h

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