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  * About MT-safe, all the functions of the dmadev API implemented by a PMD are
  69  * lock-free functions which assume to not be invoked in parallel on different
  70  * logical cores to work on the same target dmadev object.
  71  * @note Different virtual DMA channels on the same dmadev *DO NOT* support
  72  * parallel invocation because these virtual DMA channels share the same
  73  * HW-DMA-channel.
  74  */
  75
  76 #include <stdint.h>
  77
  78 #include <rte_bitops.h>
  79 #include <rte_common.h>
  80 #include <rte_compat.h>
  81 #include <rte_dev.h>
  82
  83 #ifdef __cplusplus
  84 extern "C" {
  85 #endif
  86
  87 /** Maximum number of devices if rte_dma_dev_max() is not called. */
  88 #define RTE_DMADEV_DEFAULT_MAX 64
  89
  90 /**
  91  * @warning
  92  * @b EXPERIMENTAL: this API may change without prior notice.
  93  *
  94  * Configure the maximum number of dmadevs.
  95  * @note This function can be invoked before the primary process rte_eal_init()
  96  * to change the maximum number of dmadevs. If not invoked, the maximum number
  97  * of dmadevs is @see RTE_DMADEV_DEFAULT_MAX
  98  *
  99  * @param dev_max
 100  *   maximum number of dmadevs.
 101  *
 102  * @return
 103  *   0 on success. Otherwise negative value is returned.
 104  */
 105 __rte_experimental
 106 int rte_dma_dev_max(size_t dev_max);
 107
 108 /**
 109  * @warning
 110  * @b EXPERIMENTAL: this API may change without prior notice.
 111  *
 112  * Get the device identifier for the named DMA device.
 113  *
 114  * @param name
 115  *   DMA device name.
 116  *
 117  * @return
 118  *   Returns DMA device identifier on success.
 119  *   - <0: Failure to find named DMA device.
 120  */
 121 __rte_experimental
 122 int rte_dma_get_dev_id_by_name(const char *name);
 123
 124 /**
 125  * @warning
 126  * @b EXPERIMENTAL: this API may change without prior notice.
 127  *
 128  * Check whether the dev_id is valid.
 129  *
 130  * @param dev_id
 131  *   DMA device index.
 132  *
 133  * @return
 134  *   - If the device index is valid (true) or not (false).
 135  */
 136 __rte_experimental
 137 bool rte_dma_is_valid(int16_t dev_id);
 138
 139 /**
 140  * @warning
 141  * @b EXPERIMENTAL: this API may change without prior notice.
 142  *
 143  * Get the total number of DMA devices that have been successfully
 144  * initialised.
 145  *
 146  * @return
 147  *   The total number of usable DMA devices.
 148  */
 149 __rte_experimental
 150 uint16_t rte_dma_count_avail(void);
 151
 152 /**@{@name DMA capability
 153  * @see struct rte_dma_info::dev_capa
 154  */
 155 /** Support memory-to-memory transfer */
 156 #define RTE_DMA_CAPA_MEM_TO_MEM         RTE_BIT64(0)
 157 /** Support memory-to-device transfer. */
 158 #define RTE_DMA_CAPA_MEM_TO_DEV         RTE_BIT64(1)
 159 /** Support device-to-memory transfer. */
 160 #define RTE_DMA_CAPA_DEV_TO_MEM         RTE_BIT64(2)
 161 /** Support device-to-device transfer. */
 162 #define RTE_DMA_CAPA_DEV_TO_DEV         RTE_BIT64(3)
 163 /** Support SVA which could use VA as DMA address.
 164  * If device support SVA then application could pass any VA address like memory
 165  * from rte_malloc(), rte_memzone(), malloc, stack memory.
 166  * If device don't support SVA, then application should pass IOVA address which
 167  * from rte_malloc(), rte_memzone().
 168  */
 169 #define RTE_DMA_CAPA_SVA                RTE_BIT64(4)
 170 /** Support work in silent mode.
 171  * In this mode, application don't required to invoke rte_dma_completed*()
 172  * API.
 173  * @see struct rte_dma_conf::silent_mode
 174  */
 175 #define RTE_DMA_CAPA_SILENT             RTE_BIT64(5)
 176 /** Support copy operation.
 177  * This capability start with index of 32, so that it could leave gap between
 178  * normal capability and ops capability.
 179  */
 180 #define RTE_DMA_CAPA_OPS_COPY           RTE_BIT64(32)
 181 /** Support scatter-gather list copy operation. */
 182 #define RTE_DMA_CAPA_OPS_COPY_SG        RTE_BIT64(33)
 183 /** Support fill operation. */
 184 #define RTE_DMA_CAPA_OPS_FILL           RTE_BIT64(34)
 185 /**@}*/
 186
 187 /**
 188  * A structure used to retrieve the information of a DMA device.
 189  *
 190  * @see rte_dma_info_get
 191  */
 192 struct rte_dma_info {
 193         const char *dev_name; /**< Unique device name. */
 194         /** Device capabilities (RTE_DMA_CAPA_*). */
 195         uint64_t dev_capa;
 196         /** Maximum number of virtual DMA channels supported. */
 197         uint16_t max_vchans;
 198         /** Maximum allowed number of virtual DMA channel descriptors. */
 199         uint16_t max_desc;
 200         /** Minimum allowed number of virtual DMA channel descriptors. */
 201         uint16_t min_desc;
 202         /** Maximum number of source or destination scatter-gather entry
 203          * supported.
 204          * If the device does not support COPY_SG capability, this value can be
 205          * zero.
 206          * If the device supports COPY_SG capability, then rte_dma_copy_sg()
 207          * parameter nb_src/nb_dst should not exceed this value.
 208          */
 209         uint16_t max_sges;
 210         /** NUMA node connection, -1 if unknown. */
 211         int16_t numa_node;
 212         /** Number of virtual DMA channel configured. */
 213         uint16_t nb_vchans;
 214 };
 215
 216 /**
 217  * @warning
 218  * @b EXPERIMENTAL: this API may change without prior notice.
 219  *
 220  * Retrieve information of a DMA device.
 221  *
 222  * @param dev_id
 223  *   The identifier of the device.
 224  * @param[out] dev_info
 225  *   A pointer to a structure of type *rte_dma_info* to be filled with the
 226  *   information of the device.
 227  *
 228  * @return
 229  *   0 on success. Otherwise negative value is returned.
 230  */
 231 __rte_experimental
 232 int rte_dma_info_get(int16_t dev_id, struct rte_dma_info *dev_info);
 233
 234 /**
 235  * A structure used to configure a DMA device.
 236  *
 237  * @see rte_dma_configure
 238  */
 239 struct rte_dma_conf {
 240         /** The number of virtual DMA channels to set up for the DMA device.
 241          * This value cannot be greater than the field 'max_vchans' of struct
 242          * rte_dma_info which get from rte_dma_info_get().
 243          */
 244         uint16_t nb_vchans;
 245         /** Indicates whether to enable silent mode.
 246          * false-default mode, true-silent mode.
 247          * This value can be set to true only when the SILENT capability is
 248          * supported.
 249          *
 250          * @see RTE_DMA_CAPA_SILENT
 251          */
 252         bool enable_silent;
 253 };
 254
 255 /**
 256  * @warning
 257  * @b EXPERIMENTAL: this API may change without prior notice.
 258  *
 259  * Configure a DMA device.
 260  *
 261  * This function must be invoked first before any other function in the
 262  * API. This function can also be re-invoked when a device is in the
 263  * stopped state.
 264  *
 265  * @param dev_id
 266  *   The identifier of the device to configure.
 267  * @param dev_conf
 268  *   The DMA device configuration structure encapsulated into rte_dma_conf
 269  *   object.
 270  *
 271  * @return
 272  *   0 on success. Otherwise negative value is returned.
 273  */
 274 __rte_experimental
 275 int rte_dma_configure(int16_t dev_id, const struct rte_dma_conf *dev_conf);
 276
 277 /**
 278  * @warning
 279  * @b EXPERIMENTAL: this API may change without prior notice.
 280  *
 281  * Start a DMA device.
 282  *
 283  * The device start step is the last one and consists of setting the DMA
 284  * to start accepting jobs.
 285  *
 286  * @param dev_id
 287  *   The identifier of the device.
 288  *
 289  * @return
 290  *   0 on success. Otherwise negative value is returned.
 291  */
 292 __rte_experimental
 293 int rte_dma_start(int16_t dev_id);
 294
 295 /**
 296  * @warning
 297  * @b EXPERIMENTAL: this API may change without prior notice.
 298  *
 299  * Stop a DMA device.
 300  *
 301  * The device can be restarted with a call to rte_dma_start().
 302  *
 303  * @param dev_id
 304  *   The identifier of the device.
 305  *
 306  * @return
 307  *   0 on success. Otherwise negative value is returned.
 308  */
 309 __rte_experimental
 310 int rte_dma_stop(int16_t dev_id);
 311
 312 /**
 313  * @warning
 314  * @b EXPERIMENTAL: this API may change without prior notice.
 315  *
 316  * Close a DMA device.
 317  *
 318  * The device cannot be restarted after this call.
 319  *
 320  * @param dev_id
 321  *   The identifier of the device.
 322  *
 323  * @return
 324  *   0 on success. Otherwise negative value is returned.
 325  */
 326 __rte_experimental
 327 int rte_dma_close(int16_t dev_id);
 328
 329 /**
 330  * DMA transfer direction defines.
 331  *
 332  * @see struct rte_dma_vchan_conf::direction
 333  */
 334 enum rte_dma_direction {
 335         /** DMA transfer direction - from memory to memory.
 336          *
 337          * @see struct rte_dma_vchan_conf::direction
 338          */
 339         RTE_DMA_DIR_MEM_TO_MEM,
 340         /** DMA transfer direction - from memory to device.
 341          * In a typical scenario, the SoCs are installed on host servers as
 342          * iNICs through the PCIe interface. In this case, the SoCs works in
 343          * EP(endpoint) mode, it could initiate a DMA move request from memory
 344          * (which is SoCs memory) to device (which is host memory).
 345          *
 346          * @see struct rte_dma_vchan_conf::direction
 347          */
 348         RTE_DMA_DIR_MEM_TO_DEV,
 349         /** DMA transfer direction - from device to memory.
 350          * In a typical scenario, the SoCs are installed on host servers as
 351          * iNICs through the PCIe interface. In this case, the SoCs works in
 352          * EP(endpoint) mode, it could initiate a DMA move request from device
 353          * (which is host memory) to memory (which is SoCs memory).
 354          *
 355          * @see struct rte_dma_vchan_conf::direction
 356          */
 357         RTE_DMA_DIR_DEV_TO_MEM,
 358         /** DMA transfer direction - from device to device.
 359          * In a typical scenario, the SoCs are installed on host servers as
 360          * iNICs through the PCIe interface. In this case, the SoCs works in
 361          * EP(endpoint) mode, it could initiate a DMA move request from device
 362          * (which is host memory) to the device (which is another host memory).
 363          *
 364          * @see struct rte_dma_vchan_conf::direction
 365          */
 366         RTE_DMA_DIR_DEV_TO_DEV,
 367 };
 368
 369 /**
 370  * DMA access port type defines.
 371  *
 372  * @see struct rte_dma_port_param::port_type
 373  */
 374 enum rte_dma_port_type {
 375         RTE_DMA_PORT_NONE,
 376         RTE_DMA_PORT_PCIE, /**< The DMA access port is PCIe. */
 377 };
 378
 379 /**
 380  * A structure used to descript DMA access port parameters.
 381  *
 382  * @see struct rte_dma_vchan_conf::src_port
 383  * @see struct rte_dma_vchan_conf::dst_port
 384  */
 385 struct rte_dma_port_param {
 386         /** The device access port type.
 387          *
 388          * @see enum rte_dma_port_type
 389          */
 390         enum rte_dma_port_type port_type;
 391         RTE_STD_C11
 392         union {
 393                 /** PCIe access port parameters.
 394                  *
 395                  * The following model shows SoC's PCIe module connects to
 396                  * multiple PCIe hosts and multiple endpoints. The PCIe module
 397                  * has an integrated DMA controller.
 398                  *
 399                  * If the DMA wants to access the memory of host A, it can be
 400                  * initiated by PF1 in core0, or by VF0 of PF0 in core0.
 401                  *
 402                  * \code{.unparsed}
 403                  * System Bus
 404                  *    |     ----------PCIe module----------
 405                  *    |     Bus
 406                  *    |     Interface
 407                  *    |     -----        ------------------
 408                  *    |     |   |        | PCIe Core0     |
 409                  *    |     |   |        |                |        -----------
 410                  *    |     |   |        |   PF-0 -- VF-0 |        | Host A  |
 411                  *    |     |   |--------|        |- VF-1 |--------| Root    |
 412                  *    |     |   |        |   PF-1         |        | Complex |
 413                  *    |     |   |        |   PF-2         |        -----------
 414                  *    |     |   |        ------------------
 415                  *    |     |   |
 416                  *    |     |   |        ------------------
 417                  *    |     |   |        | PCIe Core1     |
 418                  *    |     |   |        |                |        -----------
 419                  *    |     |   |        |   PF-0 -- VF-0 |        | Host B  |
 420                  *    |-----|   |--------|   PF-1 -- VF-0 |--------| Root    |
 421                  *    |     |   |        |        |- VF-1 |        | Complex |
 422                  *    |     |   |        |   PF-2         |        -----------
 423                  *    |     |   |        ------------------
 424                  *    |     |   |
 425                  *    |     |   |        ------------------
 426                  *    |     |DMA|        |                |        ------
 427                  *    |     |   |        |                |--------| EP |
 428                  *    |     |   |--------| PCIe Core2     |        ------
 429                  *    |     |   |        |                |        ------
 430                  *    |     |   |        |                |--------| EP |
 431                  *    |     |   |        |                |        ------
 432                  *    |     -----        ------------------
 433                  *
 434                  * \endcode
 435                  *
 436                  * @note If some fields can not be supported by the
 437                  * hardware/driver, then the driver ignores those fields.
 438                  * Please check driver-specific documentation for limitations
 439                  * and capablites.
 440                  */
 441                 __extension__
 442                 struct {
 443                         uint64_t coreid : 4; /**< PCIe core id used. */
 444                         uint64_t pfid : 8; /**< PF id used. */
 445                         uint64_t vfen : 1; /**< VF enable bit. */
 446                         uint64_t vfid : 16; /**< VF id used. */
 447                         /** The pasid filed in TLP packet. */
 448                         uint64_t pasid : 20;
 449                         /** The attributes filed in TLP packet. */
 450                         uint64_t attr : 3;
 451                         /** The processing hint filed in TLP packet. */
 452                         uint64_t ph : 2;
 453                         /** The steering tag filed in TLP packet. */
 454                         uint64_t st : 16;
 455                 } pcie;
 456         };
 457         uint64_t reserved[2]; /**< Reserved for future fields. */
 458 };
 459
 460 /**
 461  * A structure used to configure a virtual DMA channel.
 462  *
 463  * @see rte_dma_vchan_setup
 464  */
 465 struct rte_dma_vchan_conf {
 466         /** Transfer direction
 467          *
 468          * @see enum rte_dma_direction
 469          */
 470         enum rte_dma_direction direction;
 471         /** Number of descriptor for the virtual DMA channel */
 472         uint16_t nb_desc;
 473         /** 1) Used to describes the device access port parameter in the
 474          * device-to-memory transfer scenario.
 475          * 2) Used to describes the source device access port parameter in the
 476          * device-to-device transfer scenario.
 477          *
 478          * @see struct rte_dma_port_param
 479          */
 480         struct rte_dma_port_param src_port;
 481         /** 1) Used to describes the device access port parameter in the
 482          * memory-to-device transfer scenario.
 483          * 2) Used to describes the destination device access port parameter in
 484          * the device-to-device transfer scenario.
 485          *
 486          * @see struct rte_dma_port_param
 487          */
 488         struct rte_dma_port_param dst_port;
 489 };
 490
 491 /**
 492  * @warning
 493  * @b EXPERIMENTAL: this API may change without prior notice.
 494  *
 495  * Allocate and set up a virtual DMA channel.
 496  *
 497  * @param dev_id
 498  *   The identifier of the device.
 499  * @param vchan
 500  *   The identifier of virtual DMA channel. The value must be in the range
 501  *   [0, nb_vchans - 1] previously supplied to rte_dma_configure().
 502  * @param conf
 503  *   The virtual DMA channel configuration structure encapsulated into
 504  *   rte_dma_vchan_conf object.
 505  *
 506  * @return
 507  *   0 on success. Otherwise negative value is returned.
 508  */
 509 __rte_experimental
 510 int rte_dma_vchan_setup(int16_t dev_id, uint16_t vchan,
 511                         const struct rte_dma_vchan_conf *conf);
 512
 513 /**
 514  * A structure used to retrieve statistics.
 515  *
 516  * @see rte_dma_stats_get
 517  */
 518 struct rte_dma_stats {
 519         /** Count of operations which were submitted to hardware. */
 520         uint64_t submitted;
 521         /** Count of operations which were completed, including successful and
 522          * failed completions.
 523          */
 524         uint64_t completed;
 525         /** Count of operations which failed to complete. */
 526         uint64_t errors;
 527 };
 528
 529 /**
 530  * Special ID, which is used to represent all virtual DMA channels.
 531  *
 532  * @see rte_dma_stats_get
 533  * @see rte_dma_stats_reset
 534  */
 535 #define RTE_DMA_ALL_VCHAN       0xFFFFu
 536
 537 /**
 538  * @warning
 539  * @b EXPERIMENTAL: this API may change without prior notice.
 540  *
 541  * Retrieve basic statistics of a or all virtual DMA channel(s).
 542  *
 543  * @param dev_id
 544  *   The identifier of the device.
 545  * @param vchan
 546  *   The identifier of virtual DMA channel.
 547  *   If equal RTE_DMA_ALL_VCHAN means all channels.
 548  * @param[out] stats
 549  *   The basic statistics structure encapsulated into rte_dma_stats
 550  *   object.
 551  *
 552  * @return
 553  *   0 on success. Otherwise negative value is returned.
 554  */
 555 __rte_experimental
 556 int rte_dma_stats_get(int16_t dev_id, uint16_t vchan,
 557                       struct rte_dma_stats *stats);
 558
 559 /**
 560  * @warning
 561  * @b EXPERIMENTAL: this API may change without prior notice.
 562  *
 563  * Reset basic statistics of a or all virtual DMA channel(s).
 564  *
 565  * @param dev_id
 566  *   The identifier of the device.
 567  * @param vchan
 568  *   The identifier of virtual DMA channel.
 569  *   If equal RTE_DMA_ALL_VCHAN means all channels.
 570  *
 571  * @return
 572  *   0 on success. Otherwise negative value is returned.
 573  */
 574 __rte_experimental
 575 int rte_dma_stats_reset(int16_t dev_id, uint16_t vchan);
 576
 577 /**
 578  * @warning
 579  * @b EXPERIMENTAL: this API may change without prior notice.
 580  *
 581  * Dump DMA device info.
 582  *
 583  * @param dev_id
 584  *   The identifier of the device.
 585  * @param f
 586  *   The file to write the output to.
 587  *
 588  * @return
 589  *   0 on success. Otherwise negative value is returned.
 590  */
 591 __rte_experimental
 592 int rte_dma_dump(int16_t dev_id, FILE *f);
 593
 594 #ifdef __cplusplus
 595 }
 596 #endif
 597
 598 #endif /* RTE_DMADEV_H */