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_ */