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 /** 135 * @internal 136 * Allocate a new dmadev slot for an DMA device and return the pointer to that 137 * slot for the driver to use. 138 * 139 * @param name 140 * DMA device name. 141 * @param numa_node 142 * Driver's private data's NUMA node. 143 * @param private_data_size 144 * Driver's private data size. 145 * 146 * @return 147 * A pointer to the DMA device slot case of success, 148 * NULL otherwise. 149 */ 150 __rte_internal 151 struct rte_dma_dev *rte_dma_pmd_allocate(const char *name, int numa_node, 152 size_t private_data_size); 153 154 /** 155 * @internal 156 * Release the specified dmadev. 157 * 158 * @param name 159 * DMA device name. 160 * 161 * @return 162 * - 0 on success, negative on error. 163 */ 164 __rte_internal 165 int rte_dma_pmd_release(const char *name); 166 167 #ifdef __cplusplus 168 } 169 #endif 170 171 #endif /* RTE_DMADEV_PMD_H */ 172