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_dev.h>
  18
  19 #include "rte_dmadev.h"
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 struct rte_dma_dev;
  26
  27 /** @internal Used to get device information of a device. */
  28 typedef int (*rte_dma_info_get_t)(const struct rte_dma_dev *dev,
  29                                   struct rte_dma_info *dev_info,
  30                                   uint32_t info_sz);
  31
  32 /** @internal Used to configure a device. */
  33 typedef int (*rte_dma_configure_t)(struct rte_dma_dev *dev,
  34                                    const struct rte_dma_conf *dev_conf,
  35                                    uint32_t conf_sz);
  36
  37 /** @internal Used to start a configured device. */
  38 typedef int (*rte_dma_start_t)(struct rte_dma_dev *dev);
  39
  40 /** @internal Used to stop a configured device. */
  41 typedef int (*rte_dma_stop_t)(struct rte_dma_dev *dev);
  42
  43 /** @internal Used to close a configured device. */
  44 typedef int (*rte_dma_close_t)(struct rte_dma_dev *dev);
  45
  46 /** @internal Used to allocate and set up a virtual DMA channel. */
  47 typedef int (*rte_dma_vchan_setup_t)(struct rte_dma_dev *dev, uint16_t vchan,
  48                                 const struct rte_dma_vchan_conf *conf,
  49                                 uint32_t conf_sz);
  50
  51 /** @internal Used to retrieve basic statistics. */
  52 typedef int (*rte_dma_stats_get_t)(const struct rte_dma_dev *dev,
  53                         uint16_t vchan, struct rte_dma_stats *stats,
  54                         uint32_t stats_sz);
  55
  56 /** @internal Used to reset basic statistics. */
  57 typedef int (*rte_dma_stats_reset_t)(struct rte_dma_dev *dev, uint16_t vchan);
  58
  59 /** @internal Used to check if a virtual channel has finished all jobs. */
  60 typedef int (*rte_dma_vchan_status_t)(const struct rte_dma_dev *dev, uint16_t vchan,
  61                 enum rte_dma_vchan_status *status);
  62
  63 /** @internal Used to dump internal information. */
  64 typedef int (*rte_dma_dump_t)(const struct rte_dma_dev *dev, FILE *f);
  65
  66 /**
  67  * DMA device operations function pointer table.
  68  *
  69  * @see struct rte_dma_dev:dev_ops
  70  */
  71 struct rte_dma_dev_ops {
  72         rte_dma_info_get_t         dev_info_get;
  73         rte_dma_configure_t        dev_configure;
  74         rte_dma_start_t            dev_start;
  75         rte_dma_stop_t             dev_stop;
  76         rte_dma_close_t            dev_close;
  77
  78         rte_dma_vchan_setup_t      vchan_setup;
  79
  80         rte_dma_stats_get_t        stats_get;
  81         rte_dma_stats_reset_t      stats_reset;
  82
  83         rte_dma_vchan_status_t     vchan_status;
  84         rte_dma_dump_t             dev_dump;
  85 };
  86
  87 /**
  88  * @internal
  89  * The data part, with no function pointers, associated with each DMA device.
  90  *
  91  * This structure is safe to place in shared memory to be common among different
  92  * processes in a multi-process configuration.
  93  *
  94  * @see struct rte_dma_dev::data
  95  */
  96 struct rte_dma_dev_data {
  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         struct rte_dma_conf dev_conf; /**< DMA device configuration. */
 102         __extension__
 103         uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */
 104         uint64_t reserved[2]; /**< Reserved for future fields */
 105 } __rte_cache_aligned;
 106
 107 /**
 108  * Possible states of a DMA device.
 109  *
 110  * @see struct rte_dma_dev::state
 111  */
 112 enum rte_dma_dev_state {
 113         RTE_DMA_DEV_UNUSED = 0, /**< Device is unused. */
 114         /** Device is registered, but not ready to be used. */
 115         RTE_DMA_DEV_REGISTERED,
 116         /** Device is ready for use. This is set by the PMD. */
 117         RTE_DMA_DEV_READY,
 118 };
 119
 120 /**
 121  * @internal
 122  * The generic data structure associated with each DMA device.
 123  */
 124 struct rte_dma_dev {
 125         /** Device info which supplied during device initialization. */
 126         struct rte_device *device;
 127         struct rte_dma_dev_data *data; /**< Pointer to shared device data. */
 128         /**< Fast-path functions and related data. */
 129         struct rte_dma_fp_object *fp_obj;
 130         /** Functions implemented by PMD. */
 131         const struct rte_dma_dev_ops *dev_ops;
 132         enum rte_dma_dev_state state; /**< Flag indicating the device state. */
 133         uint64_t reserved[2]; /**< Reserved for future fields. */
 134 } __rte_cache_aligned;
 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 */