1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2017-2018 Intel Corporation
3  */
4 
5 #ifndef _RTE_COMPRESSDEV_PMD_H_
6 #define _RTE_COMPRESSDEV_PMD_H_
7 
8 /** @file
9  * RTE comp PMD APIs
10  *
11  * @note
12  * These APIs are for comp PMDs only and user applications should not call
13  * them directly.
14  */
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 #include <string.h>
21 
22 #include <rte_dev.h>
23 #include <rte_common.h>
24 
25 #include "rte_compressdev.h"
26 #include "rte_compressdev_internal.h"
27 
28 #define RTE_COMPRESSDEV_PMD_NAME_ARG			("name")
29 #define RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG		("socket_id")
30 
31 static const char * const compressdev_pmd_valid_params[] = {
32 	RTE_COMPRESSDEV_PMD_NAME_ARG,
33 	RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG
34 };
35 
36 /**
37  * @internal
38  * Initialisation parameters for comp devices
39  */
40 struct rte_compressdev_pmd_init_params {
41 	char name[RTE_COMPRESSDEV_NAME_MAX_LEN];
42 	int socket_id;
43 };
44 
45 /** Global structure used for maintaining state of allocated comp devices */
46 struct rte_compressdev_global {
47 	struct rte_compressdev *devs;	/**< Device information array */
48 	struct rte_compressdev_data *data[RTE_COMPRESS_MAX_DEVS];
49 	/**< Device private data */
50 	uint8_t nb_devs;		/**< Number of devices found */
51 	uint8_t max_devs;		/**< Max number of devices */
52 };
53 
54 /**
55  * Get the rte_compressdev structure device pointer for the named device.
56  *
57  * @param name
58  *   Compress device name
59  * @return
60  *   - The rte_compressdev structure pointer for the given device identifier.
61  */
62 struct rte_compressdev * __rte_experimental
63 rte_compressdev_pmd_get_named_dev(const char *name);
64 
65 /**
66  * Definitions of all functions exported by a driver through the
67  * the generic structure of type *comp_dev_ops* supplied in the
68  * *rte_compressdev* structure associated with a device.
69  */
70 
71 /**
72  * Function used to configure device.
73  *
74  * @param dev
75  *   Compress device
76  * @param config
77  *   Compress device configurations
78  * @return
79  *   Returns 0 on success
80  */
81 typedef int (*compressdev_configure_t)(struct rte_compressdev *dev,
82 		struct rte_compressdev_config *config);
83 
84 /**
85  * Function used to start a configured device.
86  *
87  * @param dev
88  *   Compress device
89  * @return
90  *   Returns 0 on success
91  */
92 typedef int (*compressdev_start_t)(struct rte_compressdev *dev);
93 
94 /**
95  * Function used to stop a configured device.
96  *
97  * @param dev
98  *   Compress device
99  */
100 typedef void (*compressdev_stop_t)(struct rte_compressdev *dev);
101 
102 /**
103  * Function used to close a configured device.
104  *
105  * @param dev
106  *   Compress device
107  * @return
108  * - 0 on success.
109  * - EAGAIN if can't close as device is busy
110  */
111 typedef int (*compressdev_close_t)(struct rte_compressdev *dev);
112 
113 
114 /**
115  * Function used to get statistics of a device.
116  *
117  * @param dev
118  *   Compress device
119  * @param stats
120  *   Compress device stats to populate
121  */
122 typedef void (*compressdev_stats_get_t)(struct rte_compressdev *dev,
123 				struct rte_compressdev_stats *stats);
124 
125 
126 /**
127  * Function used to reset statistics of a device.
128  *
129  * @param dev
130  *   Compress device
131  */
132 typedef void (*compressdev_stats_reset_t)(struct rte_compressdev *dev);
133 
134 
135 /**
136  * Function used to get specific information of a device.
137  *
138  * @param dev
139  *   Compress device
140  */
141 typedef void (*compressdev_info_get_t)(struct rte_compressdev *dev,
142 				struct rte_compressdev_info *dev_info);
143 
144 /**
145  * Setup a queue pair for a device.
146  *
147  * @param dev
148  *   Compress device
149  * @param qp_id
150  *   Queue pair identifier
151  * @param max_inflight_ops
152  *   Max inflight ops which qp must accommodate
153  * @param socket_id
154  *   Socket identifier
155  * @return
156  *   Returns 0 on success.
157  */
158 typedef int (*compressdev_queue_pair_setup_t)(struct rte_compressdev *dev,
159 		uint16_t qp_id,	uint32_t max_inflight_ops, int socket_id);
160 
161 /**
162  * Release memory resources allocated by given queue pair.
163  *
164  * @param dev
165  *   Compress device
166  * @param qp_id
167  *   Queue pair identifier
168  * @return
169  * - 0 on success.
170  * - EAGAIN if can't close as device is busy
171  */
172 typedef int (*compressdev_queue_pair_release_t)(struct rte_compressdev *dev,
173 		uint16_t qp_id);
174 
175 /**
176  * Get number of available queue pairs of a device.
177  *
178  * @param dev
179  *   Compress device
180  * @return
181  *   Returns number of queue pairs on success.
182  */
183 typedef uint32_t (*compressdev_queue_pair_count_t)(struct rte_compressdev *dev);
184 
185 /**
186  * Create driver private stream data.
187  *
188  * @param dev
189  *   Compressdev device
190  * @param xform
191  *   xform data
192  * @param stream
193  *   ptr where handle of pmd's private stream data should be stored
194  * @return
195  *  - Returns 0 if private stream structure has been created successfully.
196  *  - Returns -EINVAL if input parameters are invalid.
197  *  - Returns -ENOTSUP if comp device does not support STATEFUL operations.
198  *  - Returns -ENOTSUP if comp device does not support the comp transform.
199  *  - Returns -ENOMEM if the private stream could not be allocated.
200  */
201 typedef int (*compressdev_stream_create_t)(struct rte_compressdev *dev,
202 		const struct rte_comp_xform *xform, void **stream);
203 
204 /**
205  * Free driver private stream data.
206  *
207  * @param dev
208  *   Compressdev device
209  * @param stream
210  *   handle of pmd's private stream data
211  * @return
212  *  - 0 if successful
213  *  - <0 in error cases
214  *  - Returns -EINVAL if input parameters are invalid.
215  *  - Returns -ENOTSUP if comp device does not support STATEFUL operations.
216  *  - Returns -EBUSY if can't free stream as there are inflight operations
217  */
218 typedef int (*compressdev_stream_free_t)(struct rte_compressdev *dev,
219 		void *stream);
220 
221 /**
222  * Create driver private_xform data.
223  *
224  * @param dev
225  *   Compressdev device
226  * @param xform
227  *   xform data
228  * @param private_xform
229  *   ptr where handle of pmd's private_xform data should be stored
230  * @return
231  *  - if successful returns 0
232  *    and valid private_xform handle
233  *  - <0 in error cases
234  *  - Returns -EINVAL if input parameters are invalid.
235  *  - Returns -ENOTSUP if comp device does not support the comp transform.
236  *  - Returns -ENOMEM if the private_xform could not be allocated.
237  */
238 typedef int (*compressdev_private_xform_create_t)(struct rte_compressdev *dev,
239 		const struct rte_comp_xform *xform, void **private_xform);
240 
241 /**
242  * Free driver private_xform data.
243  *
244  * @param dev
245  *   Compressdev device
246  * @param private_xform
247  *   handle of pmd's private_xform data
248  * @return
249  *  - 0 if successful
250  *  - <0 in error cases
251  *  - Returns -EINVAL if input parameters are invalid.
252  *  - Returns -EBUSY if can't free private_xform due to inflight operations
253  */
254 typedef int (*compressdev_private_xform_free_t)(struct rte_compressdev *dev,
255 		void *private_xform);
256 
257 /** comp device operations function pointer table */
258 struct rte_compressdev_ops {
259 	compressdev_configure_t dev_configure;	/**< Configure device. */
260 	compressdev_start_t dev_start;		/**< Start device. */
261 	compressdev_stop_t dev_stop;		/**< Stop device. */
262 	compressdev_close_t dev_close;		/**< Close device. */
263 
264 	compressdev_info_get_t dev_infos_get;	/**< Get device info. */
265 
266 	compressdev_stats_get_t stats_get;
267 	/**< Get device statistics. */
268 	compressdev_stats_reset_t stats_reset;
269 	/**< Reset device statistics. */
270 
271 	compressdev_queue_pair_setup_t queue_pair_setup;
272 	/**< Set up a device queue pair. */
273 	compressdev_queue_pair_release_t queue_pair_release;
274 	/**< Release a queue pair. */
275 
276 	compressdev_stream_create_t stream_create;
277 	/**< Create a comp stream and initialise its private data. */
278 	compressdev_stream_free_t stream_free;
279 	/**< Free a comp stream's private data. */
280 
281 	compressdev_private_xform_create_t private_xform_create;
282 	/**< Create a comp private_xform and initialise its private data. */
283 	compressdev_private_xform_free_t private_xform_free;
284 	/**< Free a comp private_xform's data. */
285 };
286 
287 /**
288  * @internal
289  *
290  * Function for internal use by dummy drivers primarily, e.g. ring-based
291  * driver.
292  * Allocates a new compressdev slot for an comp device and returns the pointer
293  * to that slot for the driver to use.
294  *
295  * @param name
296  *   Unique identifier name for each device
297  * @param socket_id
298  *   Socket to allocate resources on
299  * @return
300  *   - Slot in the rte_dev_devices array for a new device;
301  */
302 struct rte_compressdev * __rte_experimental
303 rte_compressdev_pmd_allocate(const char *name, int socket_id);
304 
305 /**
306  * @internal
307  *
308  * Function for internal use by dummy drivers primarily, e.g. ring-based
309  * driver.
310  * Release the specified compressdev device.
311  *
312  * @param dev
313  *   Compress device
314  * @return
315  *   - 0 on success, negative on error
316  */
317 int __rte_experimental
318 rte_compressdev_pmd_release_device(struct rte_compressdev *dev);
319 
320 
321 /**
322  * @internal
323  *
324  * PMD assist function to parse initialisation arguments for comp driver
325  * when creating a new comp PMD device instance.
326  *
327  * PMD driver should set default values for that PMD before calling function,
328  * these default values will be over-written with successfully parsed values
329  * from args string.
330  *
331  * @param params
332  *   Parsed PMD initialisation parameters
333  * @param args
334  *   Input argument string to parse
335  * @return
336  *  - 0 on success
337  *  - errno on failure
338  */
339 int __rte_experimental
340 rte_compressdev_pmd_parse_input_args(
341 		struct rte_compressdev_pmd_init_params *params,
342 		const char *args);
343 
344 /**
345  * @internal
346  *
347  * PMD assist function to provide boiler plate code for comp driver to create
348  * and allocate resources for a new comp PMD device instance.
349  *
350  * @param name
351  *   Compress device name
352  * @param device
353  *   Base device instance
354  * @param params
355  *   PMD initialisation parameters
356  * @return
357  *  - comp device instance on success
358  *  - NULL on creation failure
359  */
360 struct rte_compressdev * __rte_experimental
361 rte_compressdev_pmd_create(const char *name,
362 		struct rte_device *device,
363 		size_t private_data_size,
364 		struct rte_compressdev_pmd_init_params *params);
365 
366 /**
367  * @internal
368  *
369  * PMD assist function to provide boiler plate code for comp driver to
370  * destroy and free resources associated with a comp PMD device instance.
371  *
372  * @param dev
373  *   Compress device
374  * @return
375  *  - 0 on success
376  *  - errno on failure
377  */
378 int __rte_experimental
379 rte_compressdev_pmd_destroy(struct rte_compressdev *dev);
380 
381 #ifdef __cplusplus
382 }
383 #endif
384 
385 #endif /* _RTE_COMPRESSDEV_PMD_H_ */
386