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 typecast 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.
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.
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.
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.
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.
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()
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
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
184 rte_rawdev_queue_release(uint16_t dev_id, uint16_t queue_id);
187 * Get the number of raw queues on a specific raw device
190 * Raw device identifier.
192 * - The number of configured raw queues
195 rte_rawdev_queue_count(uint16_t dev_id);
198 * Start a raw device.
200 * The device start step is the last one and consists of setting the raw
201 * queues to start accepting the raws and schedules to raw ports.
203 * On success, all basic functions exported by the API (raw enqueue,
204 * raw dequeue and so on) can be invoked.
207 * Raw device identifier
209 * - 0: Success, device started.
213 rte_rawdev_start(uint16_t dev_id);
216 * Stop a raw device. The device can be restarted with a call to
220 * Raw device identifier.
223 rte_rawdev_stop(uint16_t dev_id);
226 * Close a raw device. The device cannot be restarted after this call.
229 * Raw device identifier
232 * - 0 on successfully closing device
233 * - <0 on failure to close device
234 * - (-EAGAIN) if device is busy
237 rte_rawdev_close(uint16_t dev_id);
240 * Reset a raw device.
241 * This is different from cycle of rte_rawdev_start->rte_rawdev_stop in the
242 * sense similar to hard or soft reset.
245 * Raw device identifiers
247 * 0 for successful reset,
248 * !0 for failure in resetting
251 rte_rawdev_reset(uint16_t dev_id);
253 #define RTE_RAWDEV_NAME_MAX_LEN (64)
254 /**< @internal Max length of name of raw PMD */
259 * The data structure associated with each raw device.
260 * It is a placeholder for PMD specific data, encapsulating only information
261 * related to framework.
264 /**< Socket ID where memory is allocated */
266 /**< Device ID for this instance */
268 /**< Functions exported by PMD */
269 const struct rte_rawdev_ops *dev_ops;
270 /**< Device info. supplied during device initialization */
271 struct rte_device *device;
272 /**< Driver info. supplied by probing */
273 const char *driver_name;
276 /**< Flag indicating the device is attached */
277 uint8_t attached : 1;
278 /**< Device state: STARTED(1)/STOPPED(0) */
281 /**< PMD-specific private data */
282 rte_rawdev_obj_t dev_private;
284 char name[RTE_RAWDEV_NAME_MAX_LEN];
285 } __rte_cache_aligned;
287 /** @internal The pool of rte_rawdev structures. */
288 extern struct rte_rawdev *rte_rawdevs;
291 struct rte_rawdev_info {
292 /**< Name of driver handling this device */
293 const char *driver_name;
294 /**< Device encapsulation */
295 struct rte_device *device;
296 /**< Socket ID where memory is allocated */
298 /**< PMD-specific private data */
299 rte_rawdev_obj_t dev_private;
302 struct rte_rawdev_buf {
303 /**< Opaque buffer reference */
308 * Dump internal information about *dev_id* to the FILE* provided in *f*.
311 * The identifier of the device.
314 * A pointer to a file for output
321 rte_rawdev_dump(uint16_t dev_id, FILE *f);
324 * Get an attribute value from implementation.
325 * Attribute is an opaque handle agreed upon between application and PMD.
327 * Implementations are expected to maintain an array of attribute-value pairs
328 * based on application calls. Memory management for this structure is
329 * shared responsibility of implementation and application.
332 * The identifier of the device to configure.
334 * Opaque object representing an attribute in implementation.
335 * @param attr_value [out]
336 * Opaque response to the attribute value. In case of error, this remains
337 * untouched. This is double pointer of void type.
340 * !0 Error; attr_value remains untouched in case of error.
343 rte_rawdev_get_attr(uint16_t dev_id,
344 const char *attr_name,
345 uint64_t *attr_value);
348 * Set an attribute value.
349 * Attribute is an opaque handle agreed upon between application and PMD.
352 * The identifier of the device to configure.
354 * Opaque object representing an attribute in implementation.
356 * Value of the attribute represented by attr_name
362 rte_rawdev_set_attr(uint16_t dev_id,
363 const char *attr_name,
364 const uint64_t attr_value);
367 * Enqueue a stream of buffers to the device.
369 * Rather than specifying a queue, this API passes along an opaque object
370 * to the driver implementation. That object can be a queue or any other
371 * contextual information necessary for the device to enqueue buffers.
374 * The identifier of the device to configure.
376 * Collection of buffers for enqueuing
378 * Count of buffers to enqueue
380 * Opaque context information.
382 * >=0 for buffers enqueued
384 * Whether partial enqueue is failure or success is defined between app
385 * and driver implementation.
388 rte_rawdev_enqueue_buffers(uint16_t dev_id,
389 struct rte_rawdev_buf **buffers,
391 rte_rawdev_obj_t context);
394 * Dequeue a stream of buffers from the device.
396 * Rather than specifying a queue, this API passes along an opaque object
397 * to the driver implementation. That object can be a queue or any other
398 * contextual information necessary for the device to dequeue buffers.
400 * Application should have allocated enough space to store `count` response
402 * Releasing buffers dequeued is responsibility of the application.
405 * The identifier of the device to configure.
407 * Collection of buffers dequeued
409 * Max buffers expected to be dequeued
411 * Opaque context information.
413 * >=0 for buffers dequeued
415 * Whether partial enqueue is failure or success is defined between app
416 * and driver implementation.
419 rte_rawdev_dequeue_buffers(uint16_t dev_id,
420 struct rte_rawdev_buf **buffers,
422 rte_rawdev_obj_t context);
424 /** Maximum name length for extended statistics counters */
425 #define RTE_RAW_DEV_XSTATS_NAME_SIZE 64
428 * A name-key lookup element for extended statistics.
430 * This structure is used to map between names and ID numbers
431 * for extended ethdev statistics.
433 struct rte_rawdev_xstats_name {
434 char name[RTE_RAW_DEV_XSTATS_NAME_SIZE];
438 * Retrieve names of extended statistics of a raw device.
441 * The identifier of the raw device.
442 * @param[out] xstats_names
443 * Block of memory to insert names into. Must be at least size in capacity.
444 * If set to NULL, function returns required capacity.
446 * Capacity of xstats_names (number of names).
448 * - positive value lower or equal to size: success. The return value
449 * is the number of entries filled in the stats table.
450 * - positive value higher than size: error, the given statistics table
451 * is too small. The return value corresponds to the size that should
452 * be given to succeed. The entries in the table are not valid and
453 * shall not be used by the caller.
454 * - negative value on error:
455 * -ENODEV for invalid *dev_id*
456 * -ENOTSUP if the device doesn't support this function.
459 rte_rawdev_xstats_names_get(uint16_t dev_id,
460 struct rte_rawdev_xstats_name *xstats_names,
464 * Retrieve extended statistics of a raw device.
467 * The identifier of the device.
469 * The id numbers of the stats to get. The ids can be got from the stat
470 * position in the stat list from rte_rawdev_get_xstats_names(), or
471 * by using rte_rawdev_get_xstats_by_name()
473 * The values for each stats request by ID.
475 * The number of stats requested
477 * - positive value: number of stat entries filled into the values array
478 * - negative value on error:
479 * -ENODEV for invalid *dev_id*
480 * -ENOTSUP if the device doesn't support this function.
483 rte_rawdev_xstats_get(uint16_t dev_id,
484 const unsigned int ids[],
489 * Retrieve the value of a single stat by requesting it by name.
492 * The identifier of the device
494 * The stat name to retrieve
496 * If non-NULL, the numerical id of the stat will be returned, so that further
497 * requests for the stat can be got using rte_rawdev_xstats_get, which will
498 * be faster as it doesn't need to scan a list of names for the stat.
499 * If the stat cannot be found, the id returned will be (unsigned)-1.
501 * - positive value or zero: the stat value
502 * - negative value: -EINVAL if stat not found, -ENOTSUP if not supported.
505 rte_rawdev_xstats_by_name_get(uint16_t dev_id,
510 * Reset the values of the xstats of the selected component in the device.
513 * The identifier of the device
515 * Selects specific statistics to be reset. When NULL, all statistics
516 * will be reset. If non-NULL, must point to array of at least
519 * The number of ids available from the *ids* array. Ignored when ids is NULL.
521 * - zero: successfully reset the statistics to zero
522 * - negative value: -EINVAL invalid parameters, -ENOTSUP if not supported.
525 rte_rawdev_xstats_reset(uint16_t dev_id,
526 const uint32_t ids[],
530 * Get Firmware status of the device..
531 * Returns a memory allocated by driver/implementation containing status
532 * information block. It is responsibility of caller to release the buffer.
535 * Raw device identifier
537 * Pointer to status information area. Caller is responsible for releasing
538 * the memory associated.
541 * !0 for failure, `status_info` argument state is undefined
544 rte_rawdev_firmware_status_get(uint16_t dev_id,
545 rte_rawdev_obj_t status_info);
548 * Get Firmware version of the device.
549 * Returns a memory allocated by driver/implementation containing version
550 * information block. It is responsibility of caller to release the buffer.
553 * Raw device identifier
554 * @param version_info
555 * Pointer to version information area. Caller is responsible for releasing
556 * the memory associated.
559 * !0 for failure, `version_info` argument state is undefined
562 rte_rawdev_firmware_version_get(uint16_t dev_id,
563 rte_rawdev_obj_t version_info);
566 * Load firmware on the device.
567 * TODO: In future, methods like directly flashing from file too can be
571 * Raw device identifier
572 * @param firmware_image
573 * Pointer to buffer containing image binary data
575 * 0 for successful load
576 * !0 for failure to load the provided image, or image incorrect.
579 rte_rawdev_firmware_load(uint16_t dev_id, rte_rawdev_obj_t firmware_image);
582 * Unload firmware from the device.
585 * Raw device identifiers
587 * 0 for successful Unload
588 * !0 for failure in unloading
591 rte_rawdev_firmware_unload(uint16_t dev_id);
594 * Trigger the rawdev self test.
597 * The identifier of the device
599 * - 0: Selftest successful
600 * - -ENOTSUP if the device doesn't support selftest
601 * - other values < 0 on failure.
604 rte_rawdev_selftest(uint16_t dev_id);
610 #endif /* _RTE_RAWDEV_H_ */