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  */
  52
  53 #include <stdint.h>
  54
  55 #include <rte_bitops.h>
  56 #include <rte_common.h>
  57 #include <rte_compat.h>
  58 #include <rte_dev.h>
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif
  63
  64 /** Maximum number of devices if rte_dma_dev_max() is not called. */
  65 #define RTE_DMADEV_DEFAULT_MAX 64
  66
  67 /**
  68  * @warning
  69  * @b EXPERIMENTAL: this API may change without prior notice.
  70  *
  71  * Configure the maximum number of dmadevs.
  72  * @note This function can be invoked before the primary process rte_eal_init()
  73  * to change the maximum number of dmadevs. If not invoked, the maximum number
  74  * of dmadevs is @see RTE_DMADEV_DEFAULT_MAX
  75  *
  76  * @param dev_max
  77  *   maximum number of dmadevs.
  78  *
  79  * @return
  80  *   0 on success. Otherwise negative value is returned.
  81  */
  82 __rte_experimental
  83 int rte_dma_dev_max(size_t dev_max);
  84
  85 /**
  86  * @warning
  87  * @b EXPERIMENTAL: this API may change without prior notice.
  88  *
  89  * Get the device identifier for the named DMA device.
  90  *
  91  * @param name
  92  *   DMA device name.
  93  *
  94  * @return
  95  *   Returns DMA device identifier on success.
  96  *   - <0: Failure to find named DMA device.
  97  */
  98 __rte_experimental
  99 int rte_dma_get_dev_id_by_name(const char *name);
 100
 101 /**
 102  * @warning
 103  * @b EXPERIMENTAL: this API may change without prior notice.
 104  *
 105  * Check whether the dev_id is valid.
 106  *
 107  * @param dev_id
 108  *   DMA device index.
 109  *
 110  * @return
 111  *   - If the device index is valid (true) or not (false).
 112  */
 113 __rte_experimental
 114 bool rte_dma_is_valid(int16_t dev_id);
 115
 116 /**
 117  * @warning
 118  * @b EXPERIMENTAL: this API may change without prior notice.
 119  *
 120  * Get the total number of DMA devices that have been successfully
 121  * initialised.
 122  *
 123  * @return
 124  *   The total number of usable DMA devices.
 125  */
 126 __rte_experimental
 127 uint16_t rte_dma_count_avail(void);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif
 132
 133 #endif /* RTE_DMADEV_H */