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 */ 174