1 /* SPDX-License-Identifier: BSD-3-Clause
11 * Generic device abstraction APIs.
13 * This API allow applications to configure and use generic devices having
14 * no specific type already available in DPDK.
17 * @b EXPERIMENTAL: this API may change without prior notice
24 #include <rte_common.h>
25 #include <rte_memory.h>
26 #include <rte_errno.h>
28 /* Rawdevice object - essentially a void to be typecasted by implementation */
29 typedef void *rte_rawdev_obj_t;
32 * Get the total number of raw devices that have been successfully
36 * The total number of usable raw devices.
38 uint8_t __rte_experimental
39 rte_rawdev_count(void);
42 * Get the device identifier for the named raw device.
45 * Raw device name to select the raw device identifier.
48 * Returns raw device identifier on success.
49 * - <0: Failure to find named raw device.
51 uint16_t __rte_experimental
52 rte_rawdev_get_dev_id(const char *name);
55 * Return the NUMA socket to which a device is connected.
58 * The identifier of the device.
60 * The NUMA socket id to which the device is connected or
61 * a default of zero if the socket could not be determined.
62 * -(-EINVAL) dev_id value is out of range.
64 int __rte_experimental
65 rte_rawdev_socket_id(uint16_t dev_id);
68 * Raw device information forward declaration
70 struct rte_rawdev_info;
73 * Retrieve the contextual information of a raw device.
76 * The identifier of the device.
78 * @param[out] dev_info
79 * A pointer to a structure of type *rte_rawdev_info* to be filled with the
80 * contextual information of the device.
83 * - 0: Success, driver updates the contextual information of the raw device
84 * - <0: Error code returned by the driver info get function.
87 int __rte_experimental
88 rte_rawdev_info_get(uint16_t dev_id, struct rte_rawdev_info *dev_info);
91 * Configure a raw device.
93 * This function must be invoked first before any other function in the
94 * API. This function can also be re-invoked when a device is in the
97 * The caller may use rte_rawdev_info_get() to get the capability of each
98 * resources available for this raw device.
101 * The identifier of the device to configure.
103 * The raw device configuration structure encapsulated into rte_rawdev_info
105 * It is assumed that the opaque object has enough information which the
106 * driver/implementation can use to configure the device. It is also assumed
107 * that once the configuration is done, a `queue_id` type field can be used
108 * to refer to some arbitrary internal representation of a queue.
111 * - 0: Success, device configured.
112 * - <0: Error code returned by the driver configuration function.
114 int __rte_experimental
115 rte_rawdev_configure(uint16_t dev_id, struct rte_rawdev_info *dev_conf);
119 * Retrieve the current configuration information of a raw queue designated
120 * by its *queue_id* from the raw driver for a raw device.
122 * This function intended to be used in conjunction with rte_raw_queue_setup()
123 * where caller needs to set up the queue by overriding few default values.
126 * The identifier of the device.
128 * The index of the raw queue to get the configuration information.
129 * The value must be in the range [0, nb_raw_queues - 1]
130 * previously supplied to rte_rawdev_configure().
131 * @param[out] queue_conf
132 * The pointer to the default raw queue configuration data.
134 * - 0: Success, driver updates the default raw queue configuration data.
135 * - <0: Error code returned by the driver info get function.
137 * @see rte_raw_queue_setup()
140 int __rte_experimental
141 rte_rawdev_queue_conf_get(uint16_t dev_id,
143 rte_rawdev_obj_t queue_conf);
146 * Allocate and set up a raw queue for a raw device.
149 * The identifier of the device.
151 * The index of the raw queue to setup. The value must be in the range
152 * [0, nb_raw_queues - 1] previously supplied to rte_rawdev_configure().
154 * The pointer to the configuration data to be used for the raw queue.
155 * NULL value is allowed, in which case default configuration used.
157 * @see rte_rawdev_queue_conf_get()
160 * - 0: Success, raw queue correctly set up.
161 * - <0: raw queue configuration failed
163 int __rte_experimental
164 rte_rawdev_queue_setup(uint16_t dev_id,
166 rte_rawdev_obj_t queue_conf);
169 * Release and deallocate a raw queue from a raw device.
172 * The identifier of the device.
174 * The index of the raw queue to release. The value must be in the range
175 * [0, nb_raw_queues - 1] previously supplied to rte_rawdev_configure().
177 * @see rte_rawdev_queue_conf_get()
180 * - 0: Success, raw queue released.
181 * - <0: raw queue configuration failed
183 int __rte_experimental
184 rte_rawdev_queue_release(uint16_t dev_id, uint16_t queue_id);
186 * Get the number of raw queues on a specific raw device
189 * Raw device identifier.
191 * - The number of configured raw queues
193 uint16_t __rte_experimental
194 rte_rawdev_queue_count(uint16_t dev_id);
197 * Start a raw device.
199 * The device start step is the last one and consists of setting the raw
200 * queues to start accepting the raws and schedules to raw ports.
202 * On success, all basic functions exported by the API (raw enqueue,
203 * raw dequeue and so on) can be invoked.
206 * Raw device identifier
208 * - 0: Success, device started.
211 int __rte_experimental
212 rte_rawdev_start(uint16_t dev_id);
215 * Stop a raw device. The device can be restarted with a call to
219 * Raw device identifier.
221 void __rte_experimental
222 rte_rawdev_stop(uint16_t dev_id);
225 * Close a raw device. The device cannot be restarted after this call.
228 * Raw device identifier
231 * - 0 on successfully closing device
232 * - <0 on failure to close device
233 * - (-EAGAIN) if device is busy
235 int __rte_experimental
236 rte_rawdev_close(uint16_t dev_id);
239 * Reset a raw device.
240 * This is different from cycle of rte_rawdev_start->rte_rawdev_stop in the
241 * sense similar to hard or soft reset.
244 * Raw device identifiers
246 * 0 for sucessful reset,
247 * !0 for failure in resetting
249 int __rte_experimental
250 rte_rawdev_reset(uint16_t dev_id);
252 #define RTE_RAWDEV_NAME_MAX_LEN (64)
253 /**< @internal Max length of name of raw PMD */
258 * The data structure associated with each raw device.
259 * It is a placeholder for PMD specific data, encapsulating only information
260 * related to framework.
263 /**< Socket ID where memory is allocated */
265 /**< Device ID for this instance */
267 /**< Functions exported by PMD */
268 const struct rte_rawdev_ops *dev_ops;
269 /**< Device info. supplied during device initialization */
270 struct rte_device *device;
271 /**< Driver info. supplied by probing */
272 const char *driver_name;
275 /**< Flag indicating the device is attached */
276 uint8_t attached : 1;
277 /**< Device state: STARTED(1)/STOPPED(0) */
280 /**< PMD-specific private data */
281 rte_rawdev_obj_t dev_private;
283 char name[RTE_RAWDEV_NAME_MAX_LEN];
284 } __rte_cache_aligned;
286 /** @internal The pool of rte_rawdev structures. */
287 extern struct rte_rawdev *rte_rawdevs;
290 struct rte_rawdev_info {
291 /**< Name of driver handling this device */
292 const char *driver_name;
293 /**< Device encapsulation */
294 struct rte_device *device;
295 /**< Socket ID where memory is allocated */
297 /**< PMD-specific private data */
298 rte_rawdev_obj_t dev_private;
301 struct rte_rawdev_buf {
302 /**< Opaque buffer reference */
307 * Dump internal information about *dev_id* to the FILE* provided in *f*.
310 * The identifier of the device.
313 * A pointer to a file for output
319 int __rte_experimental
320 rte_rawdev_dump(uint16_t dev_id, FILE *f);
323 * Get an attribute value from implementation.
324 * Attribute is an opaque handle agreed upon between application and PMD.
326 * Implementations are expected to maintain an array of attribute-value pairs
327 * based on application calls. Memory management for this structure is
328 * shared responsibility of implementation and application.
331 * The identifier of the device to configure.
333 * Opaque object representing an attribute in implementation.
334 * @param attr_value [out]
335 * Opaque response to the attribute value. In case of error, this remains
336 * untouched. This is double pointer of void type.
339 * !0 Error; attr_value remains untouched in case of error.
341 int __rte_experimental
342 rte_rawdev_get_attr(uint16_t dev_id,
343 const char *attr_name,
344 uint64_t *attr_value);
347 * Set an attribute value.
348 * Attribute is an opaque handle agreed upon between application and PMD.
351 * The identifier of the device to configure.
353 * Opaque object representing an attribute in implementation.
355 * Value of the attribute represented by attr_name
360 int __rte_experimental
361 rte_rawdev_set_attr(uint16_t dev_id,
362 const char *attr_name,
363 const uint64_t attr_value);
366 * Enqueue a stream of buffers to the device.
368 * Rather than specifying a queue, this API passes along an opaque object
369 * to the driver implementation. That object can be a queue or any other
370 * contextual information necessary for the device to enqueue buffers.
373 * The identifier of the device to configure.
375 * Collection of buffers for enqueueing
377 * Count of buffers to enqueue
379 * Opaque context information.
381 * >=0 for buffers enqueued
383 * Whether partial enqueue is failure or success is defined between app
384 * and driver implementation.
386 int __rte_experimental
387 rte_rawdev_enqueue_buffers(uint16_t dev_id,
388 struct rte_rawdev_buf **buffers,
390 rte_rawdev_obj_t context);
393 * Dequeue a stream of buffers from the device.
395 * Rather than specifying a queue, this API passes along an opaque object
396 * to the driver implementation. That object can be a queue or any other
397 * contextual information necessary for the device to dequeue buffers.
399 * Application should have allocated enough space to store `count` response
401 * Releasing buffers dequeued is responsibility of the application.
404 * The identifier of the device to configure.
406 * Collection of buffers dequeued
408 * Max buffers expected to be dequeued
410 * Opaque context information.
412 * >=0 for buffers dequeued
414 * Whether partial enqueue is failure or success is defined between app
415 * and driver implementation.
417 int __rte_experimental
418 rte_rawdev_dequeue_buffers(uint16_t dev_id,
419 struct rte_rawdev_buf **buffers,
421 rte_rawdev_obj_t context);
427 #endif /* _RTE_RAWDEV_H_ */