lib/dmadev/rte_dmadev_pmd.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2021 HiSilicon Limited
   3  */
   4
   5 #ifndef RTE_DMADEV_PMD_H
   6 #define RTE_DMADEV_PMD_H
   7
   8 /**
   9  * @file
  10  *
  11  * DMA Device PMD interface
  12  *
  13  * Driver facing interface for a DMA device. These are not to be called directly
  14  * by any application.
  15  */
  16
  17 #include "rte_dmadev.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 struct rte_dma_dev;
  24
  25 /** @internal Used to get device information of a device. */
  26 typedef int (*rte_dma_info_get_t)(const struct rte_dma_dev *dev,
  27                                   struct rte_dma_info *dev_info,
  28                                   uint32_t info_sz);
  29
  30 /** @internal Used to configure a device. */
  31 typedef int (*rte_dma_configure_t)(struct rte_dma_dev *dev,
  32                                    const struct rte_dma_conf *dev_conf,
  33                                    uint32_t conf_sz);
  34
  35 /** @internal Used to start a configured device. */
  36 typedef int (*rte_dma_start_t)(struct rte_dma_dev *dev);
  37
  38 /** @internal Used to stop a configured device. */
  39 typedef int (*rte_dma_stop_t)(struct rte_dma_dev *dev);
  40
  41 /** @internal Used to close a configured device. */
  42 typedef int (*rte_dma_close_t)(struct rte_dma_dev *dev);
  43
  44 /** @internal Used to allocate and set up a virtual DMA channel. */
  45 typedef int (*rte_dma_vchan_setup_t)(struct rte_dma_dev *dev, uint16_t vchan,
  46                                 const struct rte_dma_vchan_conf *conf,
  47                                 uint32_t conf_sz);
  48
  49 /** @internal Used to retrieve basic statistics. */
  50 typedef int (*rte_dma_stats_get_t)(const struct rte_dma_dev *dev,
  51                         uint16_t vchan, struct rte_dma_stats *stats,
  52                         uint32_t stats_sz);
  53
  54 /** @internal Used to reset basic statistics. */
  55 typedef int (*rte_dma_stats_reset_t)(struct rte_dma_dev *dev, uint16_t vchan);
  56
  57 /** @internal Used to dump internal information. */
  58 typedef int (*rte_dma_dump_t)(const struct rte_dma_dev *dev, FILE *f);
  59
  60 /**
  61  * DMA device operations function pointer table.
  62  *
  63  * @see struct rte_dma_dev:dev_ops
  64  */
  65 struct rte_dma_dev_ops {
  66         rte_dma_info_get_t         dev_info_get;
  67         rte_dma_configure_t        dev_configure;
  68         rte_dma_start_t            dev_start;
  69         rte_dma_stop_t             dev_stop;
  70         rte_dma_close_t            dev_close;
  71
  72         rte_dma_vchan_setup_t      vchan_setup;
  73
  74         rte_dma_stats_get_t        stats_get;
  75         rte_dma_stats_reset_t      stats_reset;
  76
  77         rte_dma_dump_t             dev_dump;
  78 };
  79 /**
  80  * Possible states of a DMA device.
  81  *
  82  * @see struct rte_dma_dev::state
  83  */
  84 enum rte_dma_dev_state {
  85         RTE_DMA_DEV_UNUSED = 0, /**< Device is unused. */
  86         /** Device is registered, but not ready to be used. */
  87         RTE_DMA_DEV_REGISTERED,
  88         /** Device is ready for use. This is set by the PMD. */
  89         RTE_DMA_DEV_READY,
  90 };
  91
  92 /**
  93  * @internal
  94  * The generic data structure associated with each DMA device.
  95  */
  96 struct rte_dma_dev {
  97         char dev_name[RTE_DEV_NAME_MAX_LEN]; /**< Unique identifier name */
  98         int16_t dev_id; /**< Device [external] identifier. */
  99         int16_t numa_node; /**< Local NUMA memory ID. -1 if unknown. */
 100         void *dev_private; /**< PMD-specific private data. */
 101         /** Device info which supplied during device initialization. */
 102         struct rte_device *device;
 103         /** Functions implemented by PMD. */
 104         const struct rte_dma_dev_ops *dev_ops;
 105         struct rte_dma_conf dev_conf; /**< DMA device configuration. */
 106         enum rte_dma_dev_state state; /**< Flag indicating the device state. */
 107         __extension__
 108         uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */
 109         uint64_t reserved[2]; /**< Reserved for future fields. */
 110 } __rte_cache_aligned;
 111
 112 extern struct rte_dma_dev *rte_dma_devices;
 113
 114 /**
 115  * @internal
 116  * Allocate a new dmadev slot for an DMA device and return the pointer to that
 117  * slot for the driver to use.
 118  *
 119  * @param name
 120  *   DMA device name.
 121  * @param numa_node
 122  *   Driver's private data's NUMA node.
 123  * @param private_data_size
 124  *   Driver's private data size.
 125  *
 126  * @return
 127  *   A pointer to the DMA device slot case of success,
 128  *   NULL otherwise.
 129  */
 130 __rte_internal
 131 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node,
 132                                          size_t private_data_size);
 133
 134 /**
 135  * @internal
 136  * Release the specified dmadev.
 137  *
 138  * @param name
 139  *   DMA device name.
 140  *
 141  * @return
 142  *   - 0 on success, negative on error.
 143  */
 144 __rte_internal
 145 int rte_dma_pmd_release(const char *name);
 146
 147 #ifdef __cplusplus
 148 }
 149 #endif
 150
 151 #endif /* RTE_DMADEV_PMD_H */