lib/dmadev/rte_dmadev.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2021 HiSilicon Limited
   3  * Copyright(c) 2021 Intel Corporation
   4  * Copyright(c) 2021 Marvell International Ltd
   5  * Copyright(c) 2021 SmartShare Systems
   6  */
   7
   8 #ifndef RTE_DMADEV_H
   9 #define RTE_DMADEV_H
  10
  11 /**
  12  * @file rte_dmadev.h
  13  *
  14  * DMA (Direct Memory Access) device API.
  15  *
  16  * The DMA framework is built on the following model:
  17  *
  18  *     ---------------   ---------------       ---------------
  19  *     | virtual DMA |   | virtual DMA |       | virtual DMA |
  20  *     | channel     |   | channel     |       | channel     |
  21  *     ---------------   ---------------       ---------------
  22  *            |                |                      |
  23  *            ------------------                      |
  24  *                     |                              |
  25  *               ------------                    ------------
  26  *               |  dmadev  |                    |  dmadev  |
  27  *               ------------                    ------------
  28  *                     |                              |
  29  *            ------------------               ------------------
  30  *            | HW DMA channel |               | HW DMA channel |
  31  *            ------------------               ------------------
  32  *                     |                              |
  33  *                     --------------------------------
  34  *                                     |
  35  *                           ---------------------
  36  *                           | HW DMA Controller |
  37  *                           ---------------------
  38  *
  39  * The DMA controller could have multiple HW-DMA-channels (aka. HW-DMA-queues),
  40  * each HW-DMA-channel should be represented by a dmadev.
  41  *
  42  * The dmadev could create multiple virtual DMA channels, each virtual DMA
  43  * channel represents a different transfer context. The DMA operation request
  44  * must be submitted to the virtual DMA channel. e.g. Application could create
  45  * virtual DMA channel 0 for memory-to-memory transfer scenario, and create
  46  * virtual DMA channel 1 for memory-to-device transfer scenario.
  47  *
  48  * This framework uses 'int16_t dev_id' as the device identifier of a dmadev,
  49  * and 'uint16_t vchan' as the virtual DMA channel identifier in one dmadev.
  50  *
  51  * The functions exported by the dmadev API to setup a device designated by its
  52  * device identifier must be invoked in the following order:
  53  *     - rte_dma_configure()
  54  *     - rte_dma_vchan_setup()
  55  *     - rte_dma_start()
  56  *
  57  * Then, the application can invoke dataplane functions to process jobs.
  58  *
  59  * If the application wants to change the configuration (i.e. invoke
  60  * rte_dma_configure() or rte_dma_vchan_setup()), it must invoke
  61  * rte_dma_stop() first to stop the device and then do the reconfiguration
  62  * before invoking rte_dma_start() again. The dataplane functions should not
  63  * be invoked when the device is stopped.
  64  *
  65  * Finally, an application can close a dmadev by invoking the rte_dma_close()
  66  * function.
  67  *
  68  * The dataplane APIs include two parts:
  69  * The first part is the submission of operation requests:
  70  *     - rte_dma_copy()
  71  *     - rte_dma_copy_sg()
  72  *     - rte_dma_fill()
  73  *     - rte_dma_submit()
  74  *
  75  * These APIs could work with different virtual DMA channels which have
  76  * different contexts.
  77  *
  78  * The first three APIs are used to submit the operation request to the virtual
  79  * DMA channel, if the submission is successful, a positive
  80  * ring_idx <= UINT16_MAX is returned, otherwise a negative number is returned.
  81  *
  82  * The last API is used to issue doorbell to hardware, and also there are flags
  83  * (@see RTE_DMA_OP_FLAG_SUBMIT) parameter of the first three APIs could do the
  84  * same work.
  85  * @note When enqueuing a set of jobs to the device, having a separate submit
  86  * outside a loop makes for clearer code than having a check for the last
  87  * iteration inside the loop to set a special submit flag.  However, for cases
  88  * where one item alone is to be submitted or there is a small set of jobs to
  89  * be submitted sequentially, having a submit flag provides a lower-overhead
  90  * way of doing the submission while still keeping the code clean.
  91  *
  92  * The second part is to obtain the result of requests:
  93  *     - rte_dma_completed()
  94  *         - return the number of operation requests completed successfully.
  95  *     - rte_dma_completed_status()
  96  *         - return the number of operation requests completed.
  97  *
  98  * @note If the dmadev works in silent mode (@see RTE_DMA_CAPA_SILENT),
  99  * application does not invoke the above two completed APIs.
 100  *
 101  * About the ring_idx which enqueue APIs (e.g. rte_dma_copy(), rte_dma_fill())
 102  * return, the rules are as follows:
 103  *     - ring_idx for each virtual DMA channel are independent.
 104  *     - For a virtual DMA channel, the ring_idx is monotonically incremented,
 105  *       when it reach UINT16_MAX, it wraps back to zero.
 106  *     - This ring_idx can be used by applications to track per-operation
 107  *       metadata in an application-defined circular ring.
 108  *     - The initial ring_idx of a virtual DMA channel is zero, after the
 109  *       device is stopped, the ring_idx needs to be reset to zero.
 110  *
 111  * One example:
 112  *     - step-1: start one dmadev
 113  *     - step-2: enqueue a copy operation, the ring_idx return is 0
 114  *     - step-3: enqueue a copy operation again, the ring_idx return is 1
 115  *     - ...
 116  *     - step-101: stop the dmadev
 117  *     - step-102: start the dmadev
 118  *     - step-103: enqueue a copy operation, the ring_idx return is 0
 119  *     - ...
 120  *     - step-x+0: enqueue a fill operation, the ring_idx return is 65535
 121  *     - step-x+1: enqueue a copy operation, the ring_idx return is 0
 122  *     - ...
 123  *
 124  * The DMA operation address used in enqueue APIs (i.e. rte_dma_copy(),
 125  * rte_dma_copy_sg(), rte_dma_fill()) is defined as rte_iova_t type.
 126  *
 127  * The dmadev supports two types of address: memory address and device address.
 128  *
 129  * - memory address: the source and destination address of the memory-to-memory
 130  * transfer type, or the source address of the memory-to-device transfer type,
 131  * or the destination address of the device-to-memory transfer type.
 132  * @note If the device support SVA (@see RTE_DMA_CAPA_SVA), the memory address
 133  * can be any VA address, otherwise it must be an IOVA address.
 134  *
 135  * - device address: the source and destination address of the device-to-device
 136  * transfer type, or the source address of the device-to-memory transfer type,
 137  * or the destination address of the memory-to-device transfer type.
 138  *
 139  * About MT-safe, all the functions of the dmadev API implemented by a PMD are
 140  * lock-free functions which assume to not be invoked in parallel on different
 141  * logical cores to work on the same target dmadev object.
 142  * @note Different virtual DMA channels on the same dmadev *DO NOT* support
 143  * parallel invocation because these virtual DMA channels share the same
 144  * HW-DMA-channel.
 145  */
 146
 147 #include <stdint.h>
 148
 149 #include <rte_bitops.h>
 150 #include <rte_common.h>
 151 #include <rte_compat.h>
 152 #include <rte_dev.h>
 153
 154 #ifdef __cplusplus
 155 extern "C" {
 156 #endif
 157
 158 /** Maximum number of devices if rte_dma_dev_max() is not called. */
 159 #define RTE_DMADEV_DEFAULT_MAX 64
 160
 161 /**
 162  * @warning
 163  * @b EXPERIMENTAL: this API may change without prior notice.
 164  *
 165  * Configure the maximum number of dmadevs.
 166  * @note This function can be invoked before the primary process rte_eal_init()
 167  * to change the maximum number of dmadevs. If not invoked, the maximum number
 168  * of dmadevs is @see RTE_DMADEV_DEFAULT_MAX
 169  *
 170  * @param dev_max
 171  *   maximum number of dmadevs.
 172  *
 173  * @return
 174  *   0 on success. Otherwise negative value is returned.
 175  */
 176 __rte_experimental
 177 int rte_dma_dev_max(size_t dev_max);
 178
 179 /**
 180  * @warning
 181  * @b EXPERIMENTAL: this API may change without prior notice.
 182  *
 183  * Get the device identifier for the named DMA device.
 184  *
 185  * @param name
 186  *   DMA device name.
 187  *
 188  * @return
 189  *   Returns DMA device identifier on success.
 190  *   - <0: Failure to find named DMA device.
 191  */
 192 __rte_experimental
 193 int rte_dma_get_dev_id_by_name(const char *name);
 194
 195 /**
 196  * @warning
 197  * @b EXPERIMENTAL: this API may change without prior notice.
 198  *
 199  * Check whether the dev_id is valid.
 200  *
 201  * @param dev_id
 202  *   DMA device index.
 203  *
 204  * @return
 205  *   - If the device index is valid (true) or not (false).
 206  */
 207 __rte_experimental
 208 bool rte_dma_is_valid(int16_t dev_id);
 209
 210 /**
 211  * @warning
 212  * @b EXPERIMENTAL: this API may change without prior notice.
 213  *
 214  * Get the total number of DMA devices that have been successfully
 215  * initialised.
 216  *
 217  * @return
 218  *   The total number of usable DMA devices.
 219  */
 220 __rte_experimental
 221 uint16_t rte_dma_count_avail(void);
 222
 223 /**@{@name DMA capability
 224  * @see struct rte_dma_info::dev_capa
 225  */
 226 /** Support memory-to-memory transfer */
 227 #define RTE_DMA_CAPA_MEM_TO_MEM         RTE_BIT64(0)
 228 /** Support memory-to-device transfer. */
 229 #define RTE_DMA_CAPA_MEM_TO_DEV         RTE_BIT64(1)
 230 /** Support device-to-memory transfer. */
 231 #define RTE_DMA_CAPA_DEV_TO_MEM         RTE_BIT64(2)
 232 /** Support device-to-device transfer. */
 233 #define RTE_DMA_CAPA_DEV_TO_DEV         RTE_BIT64(3)
 234 /** Support SVA which could use VA as DMA address.
 235  * If device support SVA then application could pass any VA address like memory
 236  * from rte_malloc(), rte_memzone(), malloc, stack memory.
 237  * If device don't support SVA, then application should pass IOVA address which
 238  * from rte_malloc(), rte_memzone().
 239  */
 240 #define RTE_DMA_CAPA_SVA                RTE_BIT64(4)
 241 /** Support work in silent mode.
 242  * In this mode, application don't required to invoke rte_dma_completed*()
 243  * API.
 244  * @see struct rte_dma_conf::silent_mode
 245  */
 246 #define RTE_DMA_CAPA_SILENT             RTE_BIT64(5)
 247 /** Support copy operation.
 248  * This capability start with index of 32, so that it could leave gap between
 249  * normal capability and ops capability.
 250  */
 251 #define RTE_DMA_CAPA_OPS_COPY           RTE_BIT64(32)
 252 /** Support scatter-gather list copy operation. */
 253 #define RTE_DMA_CAPA_OPS_COPY_SG        RTE_BIT64(33)
 254 /** Support fill operation. */
 255 #define RTE_DMA_CAPA_OPS_FILL           RTE_BIT64(34)
 256 /**@}*/
 257
 258 /**
 259  * A structure used to retrieve the information of a DMA device.
 260  *
 261  * @see rte_dma_info_get
 262  */
 263 struct rte_dma_info {
 264         const char *dev_name; /**< Unique device name. */
 265         /** Device capabilities (RTE_DMA_CAPA_*). */
 266         uint64_t dev_capa;
 267         /** Maximum number of virtual DMA channels supported. */
 268         uint16_t max_vchans;
 269         /** Maximum allowed number of virtual DMA channel descriptors. */
 270         uint16_t max_desc;
 271         /** Minimum allowed number of virtual DMA channel descriptors. */
 272         uint16_t min_desc;
 273         /** Maximum number of source or destination scatter-gather entry
 274          * supported.
 275          * If the device does not support COPY_SG capability, this value can be
 276          * zero.
 277          * If the device supports COPY_SG capability, then rte_dma_copy_sg()
 278          * parameter nb_src/nb_dst should not exceed this value.
 279          */
 280         uint16_t max_sges;
 281         /** NUMA node connection, -1 if unknown. */
 282         int16_t numa_node;
 283         /** Number of virtual DMA channel configured. */
 284         uint16_t nb_vchans;
 285 };
 286
 287 /**
 288  * @warning
 289  * @b EXPERIMENTAL: this API may change without prior notice.
 290  *
 291  * Retrieve information of a DMA device.
 292  *
 293  * @param dev_id
 294  *   The identifier of the device.
 295  * @param[out] dev_info
 296  *   A pointer to a structure of type *rte_dma_info* to be filled with the
 297  *   information of the device.
 298  *
 299  * @return
 300  *   0 on success. Otherwise negative value is returned.
 301  */
 302 __rte_experimental
 303 int rte_dma_info_get(int16_t dev_id, struct rte_dma_info *dev_info);
 304
 305 /**
 306  * A structure used to configure a DMA device.
 307  *
 308  * @see rte_dma_configure
 309  */
 310 struct rte_dma_conf {
 311         /** The number of virtual DMA channels to set up for the DMA device.
 312          * This value cannot be greater than the field 'max_vchans' of struct
 313          * rte_dma_info which get from rte_dma_info_get().
 314          */
 315         uint16_t nb_vchans;
 316         /** Indicates whether to enable silent mode.
 317          * false-default mode, true-silent mode.
 318          * This value can be set to true only when the SILENT capability is
 319          * supported.
 320          *
 321          * @see RTE_DMA_CAPA_SILENT
 322          */
 323         bool enable_silent;
 324 };
 325
 326 /**
 327  * @warning
 328  * @b EXPERIMENTAL: this API may change without prior notice.
 329  *
 330  * Configure a DMA device.
 331  *
 332  * This function must be invoked first before any other function in the
 333  * API. This function can also be re-invoked when a device is in the
 334  * stopped state.
 335  *
 336  * @param dev_id
 337  *   The identifier of the device to configure.
 338  * @param dev_conf
 339  *   The DMA device configuration structure encapsulated into rte_dma_conf
 340  *   object.
 341  *
 342  * @return
 343  *   0 on success. Otherwise negative value is returned.
 344  */
 345 __rte_experimental
 346 int rte_dma_configure(int16_t dev_id, const struct rte_dma_conf *dev_conf);
 347
 348 /**
 349  * @warning
 350  * @b EXPERIMENTAL: this API may change without prior notice.
 351  *
 352  * Start a DMA device.
 353  *
 354  * The device start step is the last one and consists of setting the DMA
 355  * to start accepting jobs.
 356  *
 357  * @param dev_id
 358  *   The identifier of the device.
 359  *
 360  * @return
 361  *   0 on success. Otherwise negative value is returned.
 362  */
 363 __rte_experimental
 364 int rte_dma_start(int16_t dev_id);
 365
 366 /**
 367  * @warning
 368  * @b EXPERIMENTAL: this API may change without prior notice.
 369  *
 370  * Stop a DMA device.
 371  *
 372  * The device can be restarted with a call to rte_dma_start().
 373  *
 374  * @param dev_id
 375  *   The identifier of the device.
 376  *
 377  * @return
 378  *   0 on success. Otherwise negative value is returned.
 379  */
 380 __rte_experimental
 381 int rte_dma_stop(int16_t dev_id);
 382
 383 /**
 384  * @warning
 385  * @b EXPERIMENTAL: this API may change without prior notice.
 386  *
 387  * Close a DMA device.
 388  *
 389  * The device cannot be restarted after this call.
 390  *
 391  * @param dev_id
 392  *   The identifier of the device.
 393  *
 394  * @return
 395  *   0 on success. Otherwise negative value is returned.
 396  */
 397 __rte_experimental
 398 int rte_dma_close(int16_t dev_id);
 399
 400 /**
 401  * DMA transfer direction defines.
 402  *
 403  * @see struct rte_dma_vchan_conf::direction
 404  */
 405 enum rte_dma_direction {
 406         /** DMA transfer direction - from memory to memory.
 407          *
 408          * @see struct rte_dma_vchan_conf::direction
 409          */
 410         RTE_DMA_DIR_MEM_TO_MEM,
 411         /** DMA transfer direction - from memory to device.
 412          * In a typical scenario, the SoCs are installed on host servers as
 413          * iNICs through the PCIe interface. In this case, the SoCs works in
 414          * EP(endpoint) mode, it could initiate a DMA move request from memory
 415          * (which is SoCs memory) to device (which is host memory).
 416          *
 417          * @see struct rte_dma_vchan_conf::direction
 418          */
 419         RTE_DMA_DIR_MEM_TO_DEV,
 420         /** DMA transfer direction - from device to memory.
 421          * In a typical scenario, the SoCs are installed on host servers as
 422          * iNICs through the PCIe interface. In this case, the SoCs works in
 423          * EP(endpoint) mode, it could initiate a DMA move request from device
 424          * (which is host memory) to memory (which is SoCs memory).
 425          *
 426          * @see struct rte_dma_vchan_conf::direction
 427          */
 428         RTE_DMA_DIR_DEV_TO_MEM,
 429         /** DMA transfer direction - from device to device.
 430          * In a typical scenario, the SoCs are installed on host servers as
 431          * iNICs through the PCIe interface. In this case, the SoCs works in
 432          * EP(endpoint) mode, it could initiate a DMA move request from device
 433          * (which is host memory) to the device (which is another host memory).
 434          *
 435          * @see struct rte_dma_vchan_conf::direction
 436          */
 437         RTE_DMA_DIR_DEV_TO_DEV,
 438 };
 439
 440 /**
 441  * DMA access port type defines.
 442  *
 443  * @see struct rte_dma_port_param::port_type
 444  */
 445 enum rte_dma_port_type {
 446         RTE_DMA_PORT_NONE,
 447         RTE_DMA_PORT_PCIE, /**< The DMA access port is PCIe. */
 448 };
 449
 450 /**
 451  * A structure used to descript DMA access port parameters.
 452  *
 453  * @see struct rte_dma_vchan_conf::src_port
 454  * @see struct rte_dma_vchan_conf::dst_port
 455  */
 456 struct rte_dma_port_param {
 457         /** The device access port type.
 458          *
 459          * @see enum rte_dma_port_type
 460          */
 461         enum rte_dma_port_type port_type;
 462         RTE_STD_C11
 463         union {
 464                 /** PCIe access port parameters.
 465                  *
 466                  * The following model shows SoC's PCIe module connects to
 467                  * multiple PCIe hosts and multiple endpoints. The PCIe module
 468                  * has an integrated DMA controller.
 469                  *
 470                  * If the DMA wants to access the memory of host A, it can be
 471                  * initiated by PF1 in core0, or by VF0 of PF0 in core0.
 472                  *
 473                  * \code{.unparsed}
 474                  * System Bus
 475                  *    |     ----------PCIe module----------
 476                  *    |     Bus
 477                  *    |     Interface
 478                  *    |     -----        ------------------
 479                  *    |     |   |        | PCIe Core0     |
 480                  *    |     |   |        |                |        -----------
 481                  *    |     |   |        |   PF-0 -- VF-0 |        | Host A  |
 482                  *    |     |   |--------|        |- VF-1 |--------| Root    |
 483                  *    |     |   |        |   PF-1         |        | Complex |
 484                  *    |     |   |        |   PF-2         |        -----------
 485                  *    |     |   |        ------------------
 486                  *    |     |   |
 487                  *    |     |   |        ------------------
 488                  *    |     |   |        | PCIe Core1     |
 489                  *    |     |   |        |                |        -----------
 490                  *    |     |   |        |   PF-0 -- VF-0 |        | Host B  |
 491                  *    |-----|   |--------|   PF-1 -- VF-0 |--------| Root    |
 492                  *    |     |   |        |        |- VF-1 |        | Complex |
 493                  *    |     |   |        |   PF-2         |        -----------
 494                  *    |     |   |        ------------------
 495                  *    |     |   |
 496                  *    |     |   |        ------------------
 497                  *    |     |DMA|        |                |        ------
 498                  *    |     |   |        |                |--------| EP |
 499                  *    |     |   |--------| PCIe Core2     |        ------
 500                  *    |     |   |        |                |        ------
 501                  *    |     |   |        |                |--------| EP |
 502                  *    |     |   |        |                |        ------
 503                  *    |     -----        ------------------
 504                  *
 505                  * \endcode
 506                  *
 507                  * @note If some fields can not be supported by the
 508                  * hardware/driver, then the driver ignores those fields.
 509                  * Please check driver-specific documentation for limitations
 510                  * and capablites.
 511                  */
 512                 __extension__
 513                 struct {
 514                         uint64_t coreid : 4; /**< PCIe core id used. */
 515                         uint64_t pfid : 8; /**< PF id used. */
 516                         uint64_t vfen : 1; /**< VF enable bit. */
 517                         uint64_t vfid : 16; /**< VF id used. */
 518                         /** The pasid filed in TLP packet. */
 519                         uint64_t pasid : 20;
 520                         /** The attributes filed in TLP packet. */
 521                         uint64_t attr : 3;
 522                         /** The processing hint filed in TLP packet. */
 523                         uint64_t ph : 2;
 524                         /** The steering tag filed in TLP packet. */
 525                         uint64_t st : 16;
 526                 } pcie;
 527         };
 528         uint64_t reserved[2]; /**< Reserved for future fields. */
 529 };
 530
 531 /**
 532  * A structure used to configure a virtual DMA channel.
 533  *
 534  * @see rte_dma_vchan_setup
 535  */
 536 struct rte_dma_vchan_conf {
 537         /** Transfer direction
 538          *
 539          * @see enum rte_dma_direction
 540          */
 541         enum rte_dma_direction direction;
 542         /** Number of descriptor for the virtual DMA channel */
 543         uint16_t nb_desc;
 544         /** 1) Used to describes the device access port parameter in the
 545          * device-to-memory transfer scenario.
 546          * 2) Used to describes the source device access port parameter in the
 547          * device-to-device transfer scenario.
 548          *
 549          * @see struct rte_dma_port_param
 550          */
 551         struct rte_dma_port_param src_port;
 552         /** 1) Used to describes the device access port parameter in the
 553          * memory-to-device transfer scenario.
 554          * 2) Used to describes the destination device access port parameter in
 555          * the device-to-device transfer scenario.
 556          *
 557          * @see struct rte_dma_port_param
 558          */
 559         struct rte_dma_port_param dst_port;
 560 };
 561
 562 /**
 563  * @warning
 564  * @b EXPERIMENTAL: this API may change without prior notice.
 565  *
 566  * Allocate and set up a virtual DMA channel.
 567  *
 568  * @param dev_id
 569  *   The identifier of the device.
 570  * @param vchan
 571  *   The identifier of virtual DMA channel. The value must be in the range
 572  *   [0, nb_vchans - 1] previously supplied to rte_dma_configure().
 573  * @param conf
 574  *   The virtual DMA channel configuration structure encapsulated into
 575  *   rte_dma_vchan_conf object.
 576  *
 577  * @return
 578  *   0 on success. Otherwise negative value is returned.
 579  */
 580 __rte_experimental
 581 int rte_dma_vchan_setup(int16_t dev_id, uint16_t vchan,
 582                         const struct rte_dma_vchan_conf *conf);
 583
 584 /**
 585  * A structure used to retrieve statistics.
 586  *
 587  * @see rte_dma_stats_get
 588  */
 589 struct rte_dma_stats {
 590         /** Count of operations which were submitted to hardware. */
 591         uint64_t submitted;
 592         /** Count of operations which were completed, including successful and
 593          * failed completions.
 594          */
 595         uint64_t completed;
 596         /** Count of operations which failed to complete. */
 597         uint64_t errors;
 598 };
 599
 600 /**
 601  * Special ID, which is used to represent all virtual DMA channels.
 602  *
 603  * @see rte_dma_stats_get
 604  * @see rte_dma_stats_reset
 605  */
 606 #define RTE_DMA_ALL_VCHAN       0xFFFFu
 607
 608 /**
 609  * @warning
 610  * @b EXPERIMENTAL: this API may change without prior notice.
 611  *
 612  * Retrieve basic statistics of a or all virtual DMA channel(s).
 613  *
 614  * @param dev_id
 615  *   The identifier of the device.
 616  * @param vchan
 617  *   The identifier of virtual DMA channel.
 618  *   If equal RTE_DMA_ALL_VCHAN means all channels.
 619  * @param[out] stats
 620  *   The basic statistics structure encapsulated into rte_dma_stats
 621  *   object.
 622  *
 623  * @return
 624  *   0 on success. Otherwise negative value is returned.
 625  */
 626 __rte_experimental
 627 int rte_dma_stats_get(int16_t dev_id, uint16_t vchan,
 628                       struct rte_dma_stats *stats);
 629
 630 /**
 631  * @warning
 632  * @b EXPERIMENTAL: this API may change without prior notice.
 633  *
 634  * Reset basic statistics of a or all virtual DMA channel(s).
 635  *
 636  * @param dev_id
 637  *   The identifier of the device.
 638  * @param vchan
 639  *   The identifier of virtual DMA channel.
 640  *   If equal RTE_DMA_ALL_VCHAN means all channels.
 641  *
 642  * @return
 643  *   0 on success. Otherwise negative value is returned.
 644  */
 645 __rte_experimental
 646 int rte_dma_stats_reset(int16_t dev_id, uint16_t vchan);
 647
 648 /**
 649  * device vchannel status
 650  *
 651  * Enum with the options for the channel status, either idle, active or halted due to error
 652  * @see rte_dma_vchan_status
 653  */
 654 enum rte_dma_vchan_status {
 655         RTE_DMA_VCHAN_IDLE,          /**< not processing, awaiting ops */
 656         RTE_DMA_VCHAN_ACTIVE,        /**< currently processing jobs */
 657         RTE_DMA_VCHAN_HALTED_ERROR,  /**< not processing due to error, cannot accept new ops */
 658 };
 659
 660 /**
 661  * @warning
 662  * @b EXPERIMENTAL: this API may change without prior notice.
 663  *
 664  * Determine if all jobs have completed on a device channel.
 665  * This function is primarily designed for testing use, as it allows a process to check if
 666  * all jobs are completed, without actually gathering completions from those jobs.
 667  *
 668  * @param dev_id
 669  *   The identifier of the device.
 670  * @param vchan
 671  *   The identifier of virtual DMA channel.
 672  * @param[out] status
 673  *   The vchan status
 674  * @return
 675  *   0 - call completed successfully
 676  *   < 0 - error code indicating there was a problem calling the API
 677  */
 678 __rte_experimental
 679 int
 680 rte_dma_vchan_status(int16_t dev_id, uint16_t vchan, enum rte_dma_vchan_status *status);
 681
 682 /**
 683  * @warning
 684  * @b EXPERIMENTAL: this API may change without prior notice.
 685  *
 686  * Dump DMA device info.
 687  *
 688  * @param dev_id
 689  *   The identifier of the device.
 690  * @param f
 691  *   The file to write the output to.
 692  *
 693  * @return
 694  *   0 on success. Otherwise negative value is returned.
 695  */
 696 __rte_experimental
 697 int rte_dma_dump(int16_t dev_id, FILE *f);
 698
 699 /**
 700  * DMA transfer result status code defines.
 701  *
 702  * @see rte_dma_completed_status
 703  */
 704 enum rte_dma_status_code {
 705         /** The operation completed successfully. */
 706         RTE_DMA_STATUS_SUCCESSFUL,
 707         /** The operation failed to complete due abort by user.
 708          * This is mainly used when processing dev_stop, user could modidy the
 709          * descriptors (e.g. change one bit to tell hardware abort this job),
 710          * it allows outstanding requests to be complete as much as possible,
 711          * so reduce the time to stop the device.
 712          */
 713         RTE_DMA_STATUS_USER_ABORT,
 714         /** The operation failed to complete due to following scenarios:
 715          * The jobs in a particular batch are not attempted because they
 716          * appeared after a fence where a previous job failed. In some HW
 717          * implementation it's possible for jobs from later batches would be
 718          * completed, though, so report the status from the not attempted jobs
 719          * before reporting those newer completed jobs.
 720          */
 721         RTE_DMA_STATUS_NOT_ATTEMPTED,
 722         /** The operation failed to complete due invalid source address. */
 723         RTE_DMA_STATUS_INVALID_SRC_ADDR,
 724         /** The operation failed to complete due invalid destination address. */
 725         RTE_DMA_STATUS_INVALID_DST_ADDR,
 726         /** The operation failed to complete due invalid source or destination
 727          * address, cover the case that only knows the address error, but not
 728          * sure which address error.
 729          */
 730         RTE_DMA_STATUS_INVALID_ADDR,
 731         /** The operation failed to complete due invalid length. */
 732         RTE_DMA_STATUS_INVALID_LENGTH,
 733         /** The operation failed to complete due invalid opcode.
 734          * The DMA descriptor could have multiple format, which are
 735          * distinguished by the opcode field.
 736          */
 737         RTE_DMA_STATUS_INVALID_OPCODE,
 738         /** The operation failed to complete due bus read error. */
 739         RTE_DMA_STATUS_BUS_READ_ERROR,
 740         /** The operation failed to complete due bus write error. */
 741         RTE_DMA_STATUS_BUS_WRITE_ERROR,
 742         /** The operation failed to complete due bus error, cover the case that
 743          * only knows the bus error, but not sure which direction error.
 744          */
 745         RTE_DMA_STATUS_BUS_ERROR,
 746         /** The operation failed to complete due data poison. */
 747         RTE_DMA_STATUS_DATA_POISION,
 748         /** The operation failed to complete due descriptor read error. */
 749         RTE_DMA_STATUS_DESCRIPTOR_READ_ERROR,
 750         /** The operation failed to complete due device link error.
 751          * Used to indicates that the link error in the memory-to-device/
 752          * device-to-memory/device-to-device transfer scenario.
 753          */
 754         RTE_DMA_STATUS_DEV_LINK_ERROR,
 755         /** The operation failed to complete due lookup page fault. */
 756         RTE_DMA_STATUS_PAGE_FAULT,
 757         /** The operation failed to complete due unknown reason.
 758          * The initial value is 256, which reserves space for future errors.
 759          */
 760         RTE_DMA_STATUS_ERROR_UNKNOWN = 0x100,
 761 };
 762
 763 /**
 764  * A structure used to hold scatter-gather DMA operation request entry.
 765  *
 766  * @see rte_dma_copy_sg
 767  */
 768 struct rte_dma_sge {
 769         rte_iova_t addr; /**< The DMA operation address. */
 770         uint32_t length; /**< The DMA operation length. */
 771 };
 772
 773 #include "rte_dmadev_core.h"
 774
 775 /**@{@name DMA operation flag
 776  * @see rte_dma_copy()
 777  * @see rte_dma_copy_sg()
 778  * @see rte_dma_fill()
 779  */
 780 /** Fence flag.
 781  * It means the operation with this flag must be processed only after all
 782  * previous operations are completed.
 783  * If the specify DMA HW works in-order (it means it has default fence between
 784  * operations), this flag could be NOP.
 785  */
 786 #define RTE_DMA_OP_FLAG_FENCE   RTE_BIT64(0)
 787 /** Submit flag.
 788  * It means the operation with this flag must issue doorbell to hardware after
 789  * enqueued jobs.
 790  */
 791 #define RTE_DMA_OP_FLAG_SUBMIT  RTE_BIT64(1)
 792 /** Write data to low level cache hint.
 793  * Used for performance optimization, this is just a hint, and there is no
 794  * capability bit for this, driver should not return error if this flag was set.
 795  */
 796 #define RTE_DMA_OP_FLAG_LLC     RTE_BIT64(2)
 797 /**@}*/
 798
 799 /**
 800  * @warning
 801  * @b EXPERIMENTAL: this API may change without prior notice.
 802  *
 803  * Enqueue a copy operation onto the virtual DMA channel.
 804  *
 805  * This queues up a copy operation to be performed by hardware, if the 'flags'
 806  * parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin
 807  * this operation, otherwise do not trigger doorbell.
 808  *
 809  * @param dev_id
 810  *   The identifier of the device.
 811  * @param vchan
 812  *   The identifier of virtual DMA channel.
 813  * @param src
 814  *   The address of the source buffer.
 815  * @param dst
 816  *   The address of the destination buffer.
 817  * @param length
 818  *   The length of the data to be copied.
 819  * @param flags
 820  *   An flags for this operation.
 821  *   @see RTE_DMA_OP_FLAG_*
 822  *
 823  * @return
 824  *   - 0..UINT16_MAX: index of enqueued job.
 825  *   - -ENOSPC: if no space left to enqueue.
 826  *   - other values < 0 on failure.
 827  */
 828 __rte_experimental
 829 static inline int
 830 rte_dma_copy(int16_t dev_id, uint16_t vchan, rte_iova_t src, rte_iova_t dst,
 831              uint32_t length, uint64_t flags)
 832 {
 833         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
 834
 835 #ifdef RTE_DMADEV_DEBUG
 836         if (!rte_dma_is_valid(dev_id) || length == 0)
 837                 return -EINVAL;
 838         RTE_FUNC_PTR_OR_ERR_RET(*obj->copy, -ENOTSUP);
 839 #endif
 840
 841         return (*obj->copy)(obj->dev_private, vchan, src, dst, length, flags);
 842 }
 843
 844 /**
 845  * @warning
 846  * @b EXPERIMENTAL: this API may change without prior notice.
 847  *
 848  * Enqueue a scatter-gather list copy operation onto the virtual DMA channel.
 849  *
 850  * This queues up a scatter-gather list copy operation to be performed by
 851  * hardware, if the 'flags' parameter contains RTE_DMA_OP_FLAG_SUBMIT then
 852  * trigger doorbell to begin this operation, otherwise do not trigger doorbell.
 853  *
 854  * @param dev_id
 855  *   The identifier of the device.
 856  * @param vchan
 857  *   The identifier of virtual DMA channel.
 858  * @param src
 859  *   The pointer of source scatter-gather entry array.
 860  * @param dst
 861  *   The pointer of destination scatter-gather entry array.
 862  * @param nb_src
 863  *   The number of source scatter-gather entry.
 864  *   @see struct rte_dma_info::max_sges
 865  * @param nb_dst
 866  *   The number of destination scatter-gather entry.
 867  *   @see struct rte_dma_info::max_sges
 868  * @param flags
 869  *   An flags for this operation.
 870  *   @see RTE_DMA_OP_FLAG_*
 871  *
 872  * @return
 873  *   - 0..UINT16_MAX: index of enqueued job.
 874  *   - -ENOSPC: if no space left to enqueue.
 875  *   - other values < 0 on failure.
 876  */
 877 __rte_experimental
 878 static inline int
 879 rte_dma_copy_sg(int16_t dev_id, uint16_t vchan, struct rte_dma_sge *src,
 880                 struct rte_dma_sge *dst, uint16_t nb_src, uint16_t nb_dst,
 881                 uint64_t flags)
 882 {
 883         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
 884
 885 #ifdef RTE_DMADEV_DEBUG
 886         if (!rte_dma_is_valid(dev_id) || src == NULL || dst == NULL ||
 887             nb_src == 0 || nb_dst == 0)
 888                 return -EINVAL;
 889         RTE_FUNC_PTR_OR_ERR_RET(*obj->copy_sg, -ENOTSUP);
 890 #endif
 891
 892         return (*obj->copy_sg)(obj->dev_private, vchan, src, dst, nb_src,
 893                                nb_dst, flags);
 894 }
 895
 896 /**
 897  * @warning
 898  * @b EXPERIMENTAL: this API may change without prior notice.
 899  *
 900  * Enqueue a fill operation onto the virtual DMA channel.
 901  *
 902  * This queues up a fill operation to be performed by hardware, if the 'flags'
 903  * parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin
 904  * this operation, otherwise do not trigger doorbell.
 905  *
 906  * @param dev_id
 907  *   The identifier of the device.
 908  * @param vchan
 909  *   The identifier of virtual DMA channel.
 910  * @param pattern
 911  *   The pattern to populate the destination buffer with.
 912  * @param dst
 913  *   The address of the destination buffer.
 914  * @param length
 915  *   The length of the destination buffer.
 916  * @param flags
 917  *   An flags for this operation.
 918  *   @see RTE_DMA_OP_FLAG_*
 919  *
 920  * @return
 921  *   - 0..UINT16_MAX: index of enqueued job.
 922  *   - -ENOSPC: if no space left to enqueue.
 923  *   - other values < 0 on failure.
 924  */
 925 __rte_experimental
 926 static inline int
 927 rte_dma_fill(int16_t dev_id, uint16_t vchan, uint64_t pattern,
 928              rte_iova_t dst, uint32_t length, uint64_t flags)
 929 {
 930         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
 931
 932 #ifdef RTE_DMADEV_DEBUG
 933         if (!rte_dma_is_valid(dev_id) || length == 0)
 934                 return -EINVAL;
 935         RTE_FUNC_PTR_OR_ERR_RET(*obj->fill, -ENOTSUP);
 936 #endif
 937
 938         return (*obj->fill)(obj->dev_private, vchan, pattern, dst, length,
 939                             flags);
 940 }
 941
 942 /**
 943  * @warning
 944  * @b EXPERIMENTAL: this API may change without prior notice.
 945  *
 946  * Trigger hardware to begin performing enqueued operations.
 947  *
 948  * This API is used to write the "doorbell" to the hardware to trigger it
 949  * to begin the operations previously enqueued by rte_dma_copy/fill().
 950  *
 951  * @param dev_id
 952  *   The identifier of the device.
 953  * @param vchan
 954  *   The identifier of virtual DMA channel.
 955  *
 956  * @return
 957  *   0 on success. Otherwise negative value is returned.
 958  */
 959 __rte_experimental
 960 static inline int
 961 rte_dma_submit(int16_t dev_id, uint16_t vchan)
 962 {
 963         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
 964
 965 #ifdef RTE_DMADEV_DEBUG
 966         if (!rte_dma_is_valid(dev_id))
 967                 return -EINVAL;
 968         RTE_FUNC_PTR_OR_ERR_RET(*obj->submit, -ENOTSUP);
 969 #endif
 970
 971         return (*obj->submit)(obj->dev_private, vchan);
 972 }
 973
 974 /**
 975  * @warning
 976  * @b EXPERIMENTAL: this API may change without prior notice.
 977  *
 978  * Return the number of operations that have been successfully completed.
 979  *
 980  * @param dev_id
 981  *   The identifier of the device.
 982  * @param vchan
 983  *   The identifier of virtual DMA channel.
 984  * @param nb_cpls
 985  *   The maximum number of completed operations that can be processed.
 986  * @param[out] last_idx
 987  *   The last completed operation's ring_idx.
 988  *   If not required, NULL can be passed in.
 989  * @param[out] has_error
 990  *   Indicates if there are transfer error.
 991  *   If not required, NULL can be passed in.
 992  *
 993  * @return
 994  *   The number of operations that successfully completed. This return value
 995  *   must be less than or equal to the value of nb_cpls.
 996  */
 997 __rte_experimental
 998 static inline uint16_t
 999 rte_dma_completed(int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,
1000                   uint16_t *last_idx, bool *has_error)
1001 {
1002         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
1003         uint16_t idx;
1004         bool err;
1005
1006 #ifdef RTE_DMADEV_DEBUG
1007         if (!rte_dma_is_valid(dev_id) || nb_cpls == 0)
1008                 return 0;
1009         RTE_FUNC_PTR_OR_ERR_RET(*obj->completed, 0);
1010 #endif
1011
1012         /* Ensure the pointer values are non-null to simplify drivers.
1013          * In most cases these should be compile time evaluated, since this is
1014          * an inline function.
1015          * - If NULL is explicitly passed as parameter, then compiler knows the
1016          *   value is NULL
1017          * - If address of local variable is passed as parameter, then compiler
1018          *   can know it's non-NULL.
1019          */
1020         if (last_idx == NULL)
1021                 last_idx = &idx;
1022         if (has_error == NULL)
1023                 has_error = &err;
1024
1025         *has_error = false;
1026         return (*obj->completed)(obj->dev_private, vchan, nb_cpls, last_idx,
1027                                  has_error);
1028 }
1029
1030 /**
1031  * @warning
1032  * @b EXPERIMENTAL: this API may change without prior notice.
1033  *
1034  * Return the number of operations that have been completed, and the operations
1035  * result may succeed or fail.
1036  *
1037  * @param dev_id
1038  *   The identifier of the device.
1039  * @param vchan
1040  *   The identifier of virtual DMA channel.
1041  * @param nb_cpls
1042  *   Indicates the size of status array.
1043  * @param[out] last_idx
1044  *   The last completed operation's ring_idx.
1045  *   If not required, NULL can be passed in.
1046  * @param[out] status
1047  *   This is a pointer to an array of length 'nb_cpls' that holds the completion
1048  *   status code of each operation.
1049  *   @see enum rte_dma_status_code
1050  *
1051  * @return
1052  *   The number of operations that completed. This return value must be less
1053  *   than or equal to the value of nb_cpls.
1054  *   If this number is greater than zero (assuming n), then n values in the
1055  *   status array are also set.
1056  */
1057 __rte_experimental
1058 static inline uint16_t
1059 rte_dma_completed_status(int16_t dev_id, uint16_t vchan,
1060                          const uint16_t nb_cpls, uint16_t *last_idx,
1061                          enum rte_dma_status_code *status)
1062 {
1063         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
1064         uint16_t idx;
1065
1066 #ifdef RTE_DMADEV_DEBUG
1067         if (!rte_dma_is_valid(dev_id) || nb_cpls == 0 || status == NULL)
1068                 return 0;
1069         RTE_FUNC_PTR_OR_ERR_RET(*obj->completed_status, 0);
1070 #endif
1071
1072         if (last_idx == NULL)
1073                 last_idx = &idx;
1074
1075         return (*obj->completed_status)(obj->dev_private, vchan, nb_cpls,
1076                                         last_idx, status);
1077 }
1078
1079 /**
1080  * @warning
1081  * @b EXPERIMENTAL: this API may change without prior notice.
1082  *
1083  * Check remaining capacity in descriptor ring for the current burst.
1084  *
1085  * @param dev_id
1086  *   The identifier of the device.
1087  * @param vchan
1088  *   The identifier of virtual DMA channel.
1089  *
1090  * @return
1091  *   - Remaining space in the descriptor ring for the current burst.
1092  *   - 0 on error
1093  */
1094 __rte_experimental
1095 static inline uint16_t
1096 rte_dma_burst_capacity(int16_t dev_id, uint16_t vchan)
1097 {
1098         struct rte_dma_fp_object *obj = &rte_dma_fp_objs[dev_id];
1099
1100 #ifdef RTE_DMADEV_DEBUG
1101         if (!rte_dma_is_valid(dev_id))
1102                 return 0;
1103         RTE_FUNC_PTR_OR_ERR_RET(*obbj->burst_capacity, 0);
1104 #endif
1105         return (*obj->burst_capacity)(obj->dev_private, vchan);
1106 }
1107
1108 #ifdef __cplusplus
1109 }
1110 #endif
1111
1112 #endif /* RTE_DMADEV_H */