xref: /dpdk/lib/dmadev/rte_dmadev_pmd.h (revision c6552d9a8deffa448de2d5e2e726f50508c1efd2)
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