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 /**
  81  * @internal
  82  * The data part, with no function pointers, associated with each DMA device.
  83  *
  84  * This structure is safe to place in shared memory to be common among different
  85  * processes in a multi-process configuration.
  86  *
  87  * @see struct rte_dma_dev::data
  88  */
  89 struct rte_dma_dev_data {
  90         char dev_name[RTE_DEV_NAME_MAX_LEN]; /**< Unique identifier name */
  91         int16_t dev_id; /**< Device [external] identifier. */
  92         int16_t numa_node; /**< Local NUMA memory ID. -1 if unknown. */
  93         void *dev_private; /**< PMD-specific private data. */
  94         struct rte_dma_conf dev_conf; /**< DMA device configuration. */
  95         __extension__
  96         uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */
  97         uint64_t reserved[2]; /**< Reserved for future fields */
  98 } __rte_cache_aligned;
  99
 100 /**
 101  * Possible states of a DMA device.
 102  *
 103  * @see struct rte_dma_dev::state
 104  */
 105 enum rte_dma_dev_state {
 106         RTE_DMA_DEV_UNUSED = 0, /**< Device is unused. */
 107         /** Device is registered, but not ready to be used. */
 108         RTE_DMA_DEV_REGISTERED,
 109         /** Device is ready for use. This is set by the PMD. */
 110         RTE_DMA_DEV_READY,
 111 };
 112
 113 /**
 114  * @internal
 115  * The generic data structure associated with each DMA device.
 116  */
 117 struct rte_dma_dev {
 118         /** Device info which supplied during device initialization. */
 119         struct rte_device *device;
 120         struct rte_dma_dev_data *data; /**< Pointer to shared device data. */
 121         /**< Fast-path functions and related data. */
 122         struct rte_dma_fp_object *fp_obj;
 123         /** Functions implemented by PMD. */
 124         const struct rte_dma_dev_ops *dev_ops;
 125         enum rte_dma_dev_state state; /**< Flag indicating the device state. */
 126         uint64_t reserved[2]; /**< Reserved for future fields. */
 127 } __rte_cache_aligned;
 128
 129 extern struct rte_dma_dev *rte_dma_devices;
 130
 131 /**
 132  * @internal
 133  * Allocate a new dmadev slot for an DMA device and return the pointer to that
 134  * slot for the driver to use.
 135  *
 136  * @param name
 137  *   DMA device name.
 138  * @param numa_node
 139  *   Driver's private data's NUMA node.
 140  * @param private_data_size
 141  *   Driver's private data size.
 142  *
 143  * @return
 144  *   A pointer to the DMA device slot case of success,
 145  *   NULL otherwise.
 146  */
 147 __rte_internal
 148 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node,
 149                                          size_t private_data_size);
 150
 151 /**
 152  * @internal
 153  * Release the specified dmadev.
 154  *
 155  * @param name
 156  *   DMA device name.
 157  *
 158  * @return
 159  *   - 0 on success, negative on error.
 160  */
 161 __rte_internal
 162 int rte_dma_pmd_release(const char *name);
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167
 168 #endif /* RTE_DMADEV_PMD_H */