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 check if a virtual channel has finished all jobs. */
  58 typedef int (*rte_dma_vchan_status_t)(const struct rte_dma_dev *dev, uint16_t vchan,
  59                 enum rte_dma_vchan_status *status);
  60
  61 /** @internal Used to dump internal information. */
  62 typedef int (*rte_dma_dump_t)(const struct rte_dma_dev *dev, FILE *f);
  63
  64 /**
  65  * DMA device operations function pointer table.
  66  *
  67  * @see struct rte_dma_dev:dev_ops
  68  */
  69 struct rte_dma_dev_ops {
  70         rte_dma_info_get_t         dev_info_get;
  71         rte_dma_configure_t        dev_configure;
  72         rte_dma_start_t            dev_start;
  73         rte_dma_stop_t             dev_stop;
  74         rte_dma_close_t            dev_close;
  75
  76         rte_dma_vchan_setup_t      vchan_setup;
  77
  78         rte_dma_stats_get_t        stats_get;
  79         rte_dma_stats_reset_t      stats_reset;
  80
  81         rte_dma_vchan_status_t     vchan_status;
  82         rte_dma_dump_t             dev_dump;
  83 };
  84
  85 /**
  86  * @internal
  87  * The data part, with no function pointers, associated with each DMA device.
  88  *
  89  * This structure is safe to place in shared memory to be common among different
  90  * processes in a multi-process configuration.
  91  *
  92  * @see struct rte_dma_dev::data
  93  */
  94 struct rte_dma_dev_data {
  95         char dev_name[RTE_DEV_NAME_MAX_LEN]; /**< Unique identifier name */
  96         int16_t dev_id; /**< Device [external] identifier. */
  97         int16_t numa_node; /**< Local NUMA memory ID. -1 if unknown. */
  98         void *dev_private; /**< PMD-specific private data. */
  99         struct rte_dma_conf dev_conf; /**< DMA device configuration. */
 100         __extension__
 101         uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */
 102         uint64_t reserved[2]; /**< Reserved for future fields */
 103 } __rte_cache_aligned;
 104
 105 /**
 106  * Possible states of a DMA device.
 107  *
 108  * @see struct rte_dma_dev::state
 109  */
 110 enum rte_dma_dev_state {
 111         RTE_DMA_DEV_UNUSED = 0, /**< Device is unused. */
 112         /** Device is registered, but not ready to be used. */
 113         RTE_DMA_DEV_REGISTERED,
 114         /** Device is ready for use. This is set by the PMD. */
 115         RTE_DMA_DEV_READY,
 116 };
 117
 118 /**
 119  * @internal
 120  * The generic data structure associated with each DMA device.
 121  */
 122 struct rte_dma_dev {
 123         /** Device info which supplied during device initialization. */
 124         struct rte_device *device;
 125         struct rte_dma_dev_data *data; /**< Pointer to shared device data. */
 126         /**< Fast-path functions and related data. */
 127         struct rte_dma_fp_object *fp_obj;
 128         /** Functions implemented by PMD. */
 129         const struct rte_dma_dev_ops *dev_ops;
 130         enum rte_dma_dev_state state; /**< Flag indicating the device state. */
 131         uint64_t reserved[2]; /**< Reserved for future fields. */
 132 } __rte_cache_aligned;
 133
 134 extern struct rte_dma_dev *rte_dma_devices;
 135
 136 /**
 137  * @internal
 138  * Allocate a new dmadev slot for an DMA device and return the pointer to that
 139  * slot for the driver to use.
 140  *
 141  * @param name
 142  *   DMA device name.
 143  * @param numa_node
 144  *   Driver's private data's NUMA node.
 145  * @param private_data_size
 146  *   Driver's private data size.
 147  *
 148  * @return
 149  *   A pointer to the DMA device slot case of success,
 150  *   NULL otherwise.
 151  */
 152 __rte_internal
 153 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node,
 154                                          size_t private_data_size);
 155
 156 /**
 157  * @internal
 158  * Release the specified dmadev.
 159  *
 160  * @param name
 161  *   DMA device name.
 162  *
 163  * @return
 164  *   - 0 on success, negative on error.
 165  */
 166 __rte_internal
 167 int rte_dma_pmd_release(const char *name);
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif
 172
 173 #endif /* RTE_DMADEV_PMD_H */