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 <dev_driver.h> 18 19 #include <rte_compat.h> 20 #include "rte_dmadev.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 struct rte_dma_dev; 27 28 /** @internal Used to get device information of a device. */ 29 typedef int (*rte_dma_info_get_t)(const struct rte_dma_dev *dev, 30 struct rte_dma_info *dev_info, 31 uint32_t info_sz); 32 33 /** @internal Used to configure a device. */ 34 typedef int (*rte_dma_configure_t)(struct rte_dma_dev *dev, 35 const struct rte_dma_conf *dev_conf, 36 uint32_t conf_sz); 37 38 /** @internal Used to start a configured device. */ 39 typedef int (*rte_dma_start_t)(struct rte_dma_dev *dev); 40 41 /** @internal Used to stop a configured device. */ 42 typedef int (*rte_dma_stop_t)(struct rte_dma_dev *dev); 43 44 /** @internal Used to close a configured device. */ 45 typedef int (*rte_dma_close_t)(struct rte_dma_dev *dev); 46 47 /** @internal Used to allocate and set up a virtual DMA channel. */ 48 typedef int (*rte_dma_vchan_setup_t)(struct rte_dma_dev *dev, uint16_t vchan, 49 const struct rte_dma_vchan_conf *conf, 50 uint32_t conf_sz); 51 52 /** @internal Used to retrieve basic statistics. */ 53 typedef int (*rte_dma_stats_get_t)(const struct rte_dma_dev *dev, 54 uint16_t vchan, struct rte_dma_stats *stats, 55 uint32_t stats_sz); 56 57 /** @internal Used to reset basic statistics. */ 58 typedef int (*rte_dma_stats_reset_t)(struct rte_dma_dev *dev, uint16_t vchan); 59 60 /** @internal Used to check if a virtual channel has finished all jobs. */ 61 typedef int (*rte_dma_vchan_status_t)(const struct rte_dma_dev *dev, uint16_t vchan, 62 enum rte_dma_vchan_status *status); 63 64 /** @internal Used to dump internal information. */ 65 typedef int (*rte_dma_dump_t)(const struct rte_dma_dev *dev, FILE *f); 66 67 /** 68 * DMA device operations function pointer table. 69 * 70 * @see struct rte_dma_dev:dev_ops 71 */ 72 struct rte_dma_dev_ops { 73 rte_dma_info_get_t dev_info_get; 74 rte_dma_configure_t dev_configure; 75 rte_dma_start_t dev_start; 76 rte_dma_stop_t dev_stop; 77 rte_dma_close_t dev_close; 78 79 rte_dma_vchan_setup_t vchan_setup; 80 81 rte_dma_stats_get_t stats_get; 82 rte_dma_stats_reset_t stats_reset; 83 84 rte_dma_vchan_status_t vchan_status; 85 rte_dma_dump_t dev_dump; 86 }; 87 88 /** 89 * @internal 90 * The data part, with no function pointers, associated with each DMA device. 91 * 92 * This structure is safe to place in shared memory to be common among different 93 * processes in a multi-process configuration. 94 * 95 * @see struct rte_dma_dev::data 96 */ 97 struct __rte_cache_aligned rte_dma_dev_data { 98 char dev_name[RTE_DEV_NAME_MAX_LEN]; /**< Unique identifier name */ 99 int16_t dev_id; /**< Device [external] identifier. */ 100 int16_t numa_node; /**< Local NUMA memory ID. -1 if unknown. */ 101 void *dev_private; /**< PMD-specific private data. */ 102 struct rte_dma_conf dev_conf; /**< DMA device configuration. */ 103 __extension__ 104 uint8_t dev_started : 1; /**< Device state: STARTED(1)/STOPPED(0). */ 105 uint64_t reserved[2]; /**< Reserved for future fields */ 106 }; 107 108 /** 109 * Possible states of a DMA device. 110 * 111 * @see struct rte_dma_dev::state 112 */ 113 enum rte_dma_dev_state { 114 RTE_DMA_DEV_UNUSED = 0, /**< Device is unused. */ 115 /** Device is registered, but not ready to be used. */ 116 RTE_DMA_DEV_REGISTERED, 117 /** Device is ready for use. This is set by the PMD. */ 118 RTE_DMA_DEV_READY, 119 }; 120 121 /** 122 * @internal 123 * The generic data structure associated with each DMA device. 124 */ 125 struct __rte_cache_aligned rte_dma_dev { 126 /** Device info which supplied during device initialization. */ 127 struct rte_device *device; 128 struct rte_dma_dev_data *data; /**< Pointer to shared device data. */ 129 /**< Fast-path functions and related data. */ 130 struct rte_dma_fp_object *fp_obj; 131 /** Functions implemented by PMD. */ 132 const struct rte_dma_dev_ops *dev_ops; 133 enum rte_dma_dev_state state; /**< Flag indicating the device state. */ 134 uint64_t reserved[2]; /**< Reserved for future fields. */ 135 }; 136 137 /** 138 * @internal 139 * Allocate a new dmadev slot for an DMA device and return the pointer to that 140 * slot for the driver to use. 141 * 142 * @param name 143 * DMA device name. 144 * @param numa_node 145 * Driver's private data's NUMA node. 146 * @param private_data_size 147 * Driver's private data size. 148 * 149 * @return 150 * A pointer to the DMA device slot case of success, 151 * NULL otherwise. 152 */ 153 __rte_internal 154 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node, 155 size_t private_data_size); 156 157 /** 158 * @internal 159 * Release the specified dmadev. 160 * 161 * @param name 162 * DMA device name. 163 * 164 * @return 165 * - 0 on success, negative on error. 166 */ 167 __rte_internal 168 int rte_dma_pmd_release(const char *name); 169 170 /** 171 * @internal 172 * Get the rte_dma_dev structure device pointer for the device ID. 173 * 174 * @param dev_id 175 * DMA device index in dmadev library. 176 * 177 * @return 178 * rte_dma_dev structure pointer on success, NULL otherwise. 179 */ 180 __rte_internal 181 struct rte_dma_dev *rte_dma_pmd_get_dev_by_id(int16_t dev_id); 182 183 #ifdef __cplusplus 184 } 185 #endif 186 187 #endif /* RTE_DMADEV_PMD_H */ 188