1 /* SPDX-License-Identifier: BSD-3-Clause
5 #ifndef _RTE_RAWDEV_PMD_H_
6 #define _RTE_RAWDEV_PMD_H_
12 * Driver facing APIs for a raw device. These are not to be called directly by
16 * @b EXPERIMENTAL: this API may change without prior notice
26 #include <rte_malloc.h>
28 #include <rte_common.h>
30 #include "rte_rawdev.h"
32 extern int librawdev_logtype;
35 #define RTE_RDEV_LOG(level, fmt, args...) \
36 rte_log(RTE_LOG_ ## level, librawdev_logtype, "%s(): " fmt "\n", \
39 #define RTE_RDEV_ERR(fmt, args...) \
40 RTE_RDEV_LOG(ERR, fmt, ## args)
41 #define RTE_RDEV_DEBUG(fmt, args...) \
42 RTE_RDEV_LOG(DEBUG, fmt, ## args)
43 #define RTE_RDEV_INFO(fmt, args...) \
44 RTE_RDEV_LOG(INFO, fmt, ## args)
47 /* Macros to check for valid device */
48 #define RTE_RAWDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
49 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
50 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
55 #define RTE_RAWDEV_VALID_DEVID_OR_RET(dev_id) do { \
56 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
57 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
62 #define RTE_RAWDEV_DETACHED (0)
63 #define RTE_RAWDEV_ATTACHED (1)
65 /* Global structure used for maintaining state of allocated raw devices.
67 * TODO: Can be expanded to <type of raw device>:<count> in future.
68 * Applications should be able to select from a number of type of raw
69 * devices which were detected or attached to this DPDK instance.
71 struct rte_rawdev_global {
72 /**< Number of devices found */
76 extern struct rte_rawdev_global *rte_rawdev_globals;
77 /** Pointer to global raw devices data structure. */
78 extern struct rte_rawdev *rte_rawdevs;
79 /** The pool of rte_rawdev structures. */
82 * Get the rte_rawdev structure device pointer for the named device.
85 * device name to select the device structure.
88 * - The rte_rawdev structure pointer for the given device ID.
90 static inline struct rte_rawdev *
91 rte_rawdev_pmd_get_named_dev(const char *name)
93 struct rte_rawdev *dev;
99 for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) {
100 dev = &rte_rawdevs[i];
101 if ((dev->attached == RTE_RAWDEV_ATTACHED) &&
102 (strcmp(dev->name, name) == 0))
110 * Validate if the raw device index is a valid attached raw device.
116 * - If the device index is valid (1) or not (0).
118 static inline unsigned
119 rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
121 struct rte_rawdev *dev;
123 if (dev_id >= RTE_RAWDEV_MAX_DEVS)
126 dev = &rte_rawdevs[dev_id];
127 if (dev->attached != RTE_RAWDEV_ATTACHED)
134 * Definitions of all functions exported by a driver through the
135 * the generic structure of type *rawdev_ops* supplied in the
136 * *rte_rawdev* structure associated with a device.
140 * Get device information of a device.
145 * Raw device information structure
148 * Returns 0 on success
150 typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev,
151 rte_rawdev_obj_t dev_info);
154 * Configure a device.
159 * Void object containing device specific configuration
162 * Returns 0 on success
164 typedef int (*rawdev_configure_t)(const struct rte_rawdev *dev,
165 rte_rawdev_obj_t config);
168 * Start a configured device.
174 * Returns 0 on success
176 typedef int (*rawdev_start_t)(struct rte_rawdev *dev);
179 * Stop a configured device.
184 typedef void (*rawdev_stop_t)(struct rte_rawdev *dev);
187 * Close a configured device.
194 * - (-EAGAIN) if can't close as device is busy
196 typedef int (*rawdev_close_t)(struct rte_rawdev *dev);
199 * Reset a configured device.
207 typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
210 * Retrieve the current raw queue configuration.
215 * Raw device queue index
216 * @param[out] queue_conf
217 * Raw device queue configuration structure
220 typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
222 rte_rawdev_obj_t queue_conf);
225 * Setup an raw queue.
232 * Rawqueue configuration structure
235 * Returns 0 on success.
237 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev,
239 rte_rawdev_obj_t queue_conf);
242 * Release resources allocated by given raw queue.
250 typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
254 * Get the count of number of queues configured on this device.
256 * Another way to fetch this information is to fetch the device configuration.
257 * But, that assumes that the device configuration managed by the driver has
258 * that kind of information.
260 * This function helps in getting queue count supported, independently. It
261 * can help in cases where iterator needs to be implemented.
266 * Number of queues; 0 is assumed to be a valid response.
269 typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
272 * Enqueue an array of raw buffers to the device.
274 * Buffer being used is opaque - it can be obtained from mempool or from
275 * any other source. Interpretation of buffer is responsibility of driver.
282 * number of buffers passed
284 * an opaque object representing context of the call; for example, an
285 * application can pass information about the queues on which enqueue needs
286 * to be done. Or, the enqueue operation might be passed reference to an
287 * object containing a callback (agreed upon between applicatio and driver).
290 * >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
291 * <0 Error count in case of error
293 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
294 struct rte_rawdev_buf **buffers,
296 rte_rawdev_obj_t context);
299 * Dequeue an array of raw buffers from the device.
306 * Max buffers expected to be dequeued
308 * an opaque object representing context of the call. Based on this object,
309 * the application and driver can coordinate for dequeue operation involving
310 * agreed upon semantics. For example, queue information/id on which Dequeue
311 * needs to be performed.
313 * >0, ~0: Count of buffers returned
315 * Whether short dequeue is success or failure is decided between app and
318 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev,
319 struct rte_rawdev_buf **buffers,
321 rte_rawdev_obj_t context);
324 * Dump internal information
329 * A pointer to a file for output
335 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
338 * Get an attribute value from implementation.
339 * Attribute is an opaque handle agreed upon between application and PMD.
344 * Opaque object representing an attribute in implementation.
345 * @param attr_value [out]
346 * Opaque response to the attribute value. In case of error, this remains
347 * untouched. This is double pointer of void type.
350 * !0 Error; attr_value remains untouched in case of error.
352 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
353 const char *attr_name,
354 uint64_t *attr_value);
357 * Set an attribute value.
358 * Attribute is an opaque handle agreed upon between application and PMD.
363 * Opaque object representing an attribute in implementation.
365 * Value of the attribute represented by attr_name
370 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
371 const char *attr_name,
372 const uint64_t attr_value);
375 * Retrieve a set of statistics from device.
376 * Note: Being a raw device, the stats are specific to the device being
377 * implemented thus represented as xstats.
382 * The stat ids to retrieve
384 * The returned stat values
386 * The number of id values and entries in the values array
388 * The number of stat values successfully filled into the values array
390 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
391 const unsigned int ids[], uint64_t values[], unsigned int n);
394 * Resets the statistic values in xstats for the device.
396 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
397 const uint32_t ids[],
401 * Get names of extended stats of an raw device
405 * @param xstats_names
406 * Array of name values to be filled in
408 * Number of values in the xstats_names array
410 * When size >= the number of stats, return the number of stat values filled
412 * When size < the number of available stats, return the number of stats
413 * values, and do not fill in any data into xstats_names.
415 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
416 struct rte_rawdev_xstats_name *xstats_names,
420 * Get value of one stats and optionally return its id
425 * The name of the stat to retrieve
427 * Pointer to an unsigned int where we store the stat-id.
428 * This pointer may be null if the id is not required.
430 * The value of the stat, or (uint64_t)-1 if the stat is not found.
431 * If the stat is not found, the id value will be returned as (unsigned)-1,
432 * if id pointer is non-NULL
434 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
439 * Get firmware/device-stack status.
440 * Implementation to allocate buffer for returning information.
445 * void block containing device specific status information
448 * !0 for failure, with undefined value in `status_info`
450 typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev,
451 rte_rawdev_obj_t status_info);
454 * Get firmware version information
458 * @param version_info
459 * void pointer to version information returned by device
462 * !0 for failure, with undefined value in `version_info`
464 typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
465 rte_rawdev_obj_t version_info);
468 * Load firwmare from a buffer (DMA'able)
472 * @param firmware_file
473 * file pointer to firmware area
475 * >0, ~0: for successful load
478 * @see Application may use 'firmware_version_get` for ascertaining successful
481 typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
482 rte_rawdev_obj_t firmware_buf);
490 * >0, ~0 for successful unloading
491 * <0 for failure in unloading
493 * Note: Application can use the `firmware_status_get` or
494 * `firmware_version_get` to get result of unload.
496 typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
499 * Start rawdev selftest
502 * Return 0 on success
504 typedef int (*rawdev_selftest_t)(void);
506 /** Rawdevice operations function pointer table */
507 struct rte_rawdev_ops {
508 /**< Get device info. */
509 rawdev_info_get_t dev_info_get;
510 /**< Configure device. */
511 rawdev_configure_t dev_configure;
512 /**< Start device. */
513 rawdev_start_t dev_start;
515 rawdev_stop_t dev_stop;
516 /**< Close device. */
517 rawdev_close_t dev_close;
518 /**< Reset device. */
519 rawdev_reset_t dev_reset;
521 /**< Get raw queue configuration. */
522 rawdev_queue_conf_get_t queue_def_conf;
523 /**< Set up an raw queue. */
524 rawdev_queue_setup_t queue_setup;
525 /**< Release an raw queue. */
526 rawdev_queue_release_t queue_release;
527 /**< Get the number of queues attached to the device */
528 rawdev_queue_count_t queue_count;
530 /**< Enqueue an array of raw buffers to device. */
531 rawdev_enqueue_bufs_t enqueue_bufs;
532 /**< Dequeue an array of raw buffers from device. */
533 /** TODO: Callback based enqueue and dequeue support */
534 rawdev_dequeue_bufs_t dequeue_bufs;
536 /* Dump internal information */
539 /**< Get an attribute managed by the implementation */
540 rawdev_get_attr_t attr_get;
541 /**< Set an attribute managed by the implementation */
542 rawdev_set_attr_t attr_set;
544 /**< Get extended device statistics. */
545 rawdev_xstats_get_t xstats_get;
546 /**< Get names of extended stats. */
547 rawdev_xstats_get_names_t xstats_get_names;
548 /**< Get one value by name. */
549 rawdev_xstats_get_by_name_t xstats_get_by_name;
550 /**< Reset the statistics values in xstats. */
551 rawdev_xstats_reset_t xstats_reset;
553 /**< Obtainer firmware status */
554 rawdev_firmware_status_get_t firmware_status_get;
555 /**< Obtain firmware version information */
556 rawdev_firmware_version_get_t firmware_version_get;
557 /**< Load firmware */
558 rawdev_firmware_load_t firmware_load;
559 /**< Unload firmware */
560 rawdev_firmware_unload_t firmware_unload;
562 /**< Device selftest function */
563 rawdev_selftest_t dev_selftest;
567 * Allocates a new rawdev slot for an raw device and returns the pointer
568 * to that slot for the driver to use.
571 * Unique identifier name for each device
572 * @param dev_private_size
573 * Private data allocated within rte_rawdev object.
575 * Socket to allocate resources on.
577 * - Slot in the rte_dev_devices array for a new device;
580 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
584 * Release the specified rawdev device.
587 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
589 * - 0 on success, negative on error
592 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
595 * Creates a new raw device and returns the pointer to that device.
598 * Pointer to a character array containing name of the device
599 * @param dev_private_size
600 * Size of raw PMDs private data
602 * Socket to allocate resources on.
605 * - Raw device pointer if device is successfully created.
606 * - NULL if device cannot be created.
609 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
613 * Destroy a raw device
618 * - 0 on success, negative on error
621 rte_rawdev_pmd_uninit(const char *name);
627 #endif /* _RTE_RAWDEV_PMD_H_ */