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         /**< Fast-path functions and related data. */
 104         struct rte_dma_fp_object *fp_obj;
 105         /** Functions implemented by PMD. */
 106         const struct rte_dma_dev_ops *dev_ops;
 107         struct rte_dma_conf dev_conf; /**< DMA device configuration. */
 108         enum rte_dma_dev_state state; /**< Flag indicating the device state. */
 109         __extension__
 110         uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */
 111         uint64_t reserved[2]; /**< Reserved for future fields. */
 112 } __rte_cache_aligned;
 113
 114 extern struct rte_dma_dev *rte_dma_devices;
 115
 116 /**
 117  * @internal
 118  * Allocate a new dmadev slot for an DMA device and return the pointer to that
 119  * slot for the driver to use.
 120  *
 121  * @param name
 122  *   DMA device name.
 123  * @param numa_node
 124  *   Driver's private data's NUMA node.
 125  * @param private_data_size
 126  *   Driver's private data size.
 127  *
 128  * @return
 129  *   A pointer to the DMA device slot case of success,
 130  *   NULL otherwise.
 131  */
 132 __rte_internal
 133 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node,
 134                                          size_t private_data_size);
 135
 136 /**
 137  * @internal
 138  * Release the specified dmadev.
 139  *
 140  * @param name
 141  *   DMA device name.
 142  *
 143  * @return
 144  *   - 0 on success, negative on error.
 145  */
 146 __rte_internal
 147 int rte_dma_pmd_release(const char *name);
 148
 149 #ifdef __cplusplus
 150 }
 151 #endif
 152
 153 #endif /* RTE_DMADEV_PMD_H */