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 * Enqueue an array of raw buffers to the device.
256 * Buffer being used is opaque - it can be obtained from mempool or from
257 * any other source. Interpretation of buffer is responsibility of driver.
264 * number of buffers passed
266 * an opaque object representing context of the call; for example, an
267 * application can pass information about the queues on which enqueue needs
268 * to be done. Or, the enqueue operation might be passed reference to an
269 * object containing a callback (agreed upon between applicatio and driver).
272 * >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
273 * <0 Error count in case of error
275 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
276 struct rte_rawdev_buf **buffers,
278 rte_rawdev_obj_t context);
281 * Dequeue an array of raw buffers from the device.
288 * Max buffers expected to be dequeued
290 * an opaque object representing context of the call. Based on this object,
291 * the application and driver can coordinate for dequeue operation involving
292 * agreed upon semantics. For example, queue information/id on which Dequeue
293 * needs to be performed.
295 * >0, ~0: Count of buffers returned
297 * Whether short dequeue is success or failure is decided between app and
300 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev,
301 struct rte_rawdev_buf **buffers,
303 rte_rawdev_obj_t context);
306 * Dump internal information
311 * A pointer to a file for output
317 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
320 * Get an attribute value from implementation.
321 * Attribute is an opaque handle agreed upon between application and PMD.
326 * Opaque object representing an attribute in implementation.
327 * @param attr_value [out]
328 * Opaque response to the attribute value. In case of error, this remains
329 * untouched. This is double pointer of void type.
332 * !0 Error; attr_value remains untouched in case of error.
334 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
335 const char *attr_name,
336 uint64_t *attr_value);
339 * Set an attribute value.
340 * Attribute is an opaque handle agreed upon between application and PMD.
345 * Opaque object representing an attribute in implementation.
347 * Value of the attribute represented by attr_name
352 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
353 const char *attr_name,
354 const uint64_t attr_value);
357 * Retrieve a set of statistics from device.
358 * Note: Being a raw device, the stats are specific to the device being
359 * implemented thus represented as xstats.
364 * The stat ids to retrieve
366 * The returned stat values
368 * The number of id values and entries in the values array
370 * The number of stat values successfully filled into the values array
372 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
373 const unsigned int ids[], uint64_t values[], unsigned int n);
376 * Resets the statistic values in xstats for the device.
378 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
379 const uint32_t ids[],
383 * Get names of extended stats of an raw device
387 * @param xstats_names
388 * Array of name values to be filled in
390 * Number of values in the xstats_names array
392 * When size >= the number of stats, return the number of stat values filled
394 * When size < the number of available stats, return the number of stats
395 * values, and do not fill in any data into xstats_names.
397 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
398 struct rte_rawdev_xstats_name *xstats_names,
402 * Get value of one stats and optionally return its id
407 * The name of the stat to retrieve
409 * Pointer to an unsigned int where we store the stat-id.
410 * This pointer may be null if the id is not required.
412 * The value of the stat, or (uint64_t)-1 if the stat is not found.
413 * If the stat is not found, the id value will be returned as (unsigned)-1,
414 * if id pointer is non-NULL
416 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
419 /** Rawdevice operations function pointer table */
420 struct rte_rawdev_ops {
421 /**< Get device info. */
422 rawdev_info_get_t dev_info_get;
423 /**< Configure device. */
424 rawdev_configure_t dev_configure;
425 /**< Start device. */
426 rawdev_start_t dev_start;
428 rawdev_stop_t dev_stop;
429 /**< Close device. */
430 rawdev_close_t dev_close;
431 /**< Reset device. */
432 rawdev_reset_t dev_reset;
434 /**< Get raw queue configuration. */
435 rawdev_queue_conf_get_t queue_def_conf;
436 /**< Set up an raw queue. */
437 rawdev_queue_setup_t queue_setup;
438 /**< Release an raw queue. */
439 rawdev_queue_release_t queue_release;
441 /**< Enqueue an array of raw buffers to device. */
442 rawdev_enqueue_bufs_t enqueue_bufs;
443 /**< Dequeue an array of raw buffers from device. */
444 /** TODO: Callback based enqueue and dequeue support */
445 rawdev_dequeue_bufs_t dequeue_bufs;
447 /* Dump internal information */
450 /**< Get an attribute managed by the implementation */
451 rawdev_get_attr_t attr_get;
452 /**< Set an attribute managed by the implementation */
453 rawdev_set_attr_t attr_set;
455 /**< Get extended device statistics. */
456 rawdev_xstats_get_t xstats_get;
457 /**< Get names of extended stats. */
458 rawdev_xstats_get_names_t xstats_get_names;
459 /**< Get one value by name. */
460 rawdev_xstats_get_by_name_t xstats_get_by_name;
461 /**< Reset the statistics values in xstats. */
462 rawdev_xstats_reset_t xstats_reset;
466 * Allocates a new rawdev slot for an raw device and returns the pointer
467 * to that slot for the driver to use.
470 * Unique identifier name for each device
471 * @param dev_private_size
472 * Private data allocated within rte_rawdev object.
474 * Socket to allocate resources on.
476 * - Slot in the rte_dev_devices array for a new device;
478 struct rte_rawdev * __rte_experimental
479 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
483 * Release the specified rawdev device.
486 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
488 * - 0 on success, negative on error
490 int __rte_experimental
491 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
494 * Creates a new raw device and returns the pointer to that device.
497 * Pointer to a character array containing name of the device
498 * @param dev_private_size
499 * Size of raw PMDs private data
501 * Socket to allocate resources on.
504 * - Raw device pointer if device is successfully created.
505 * - NULL if device cannot be created.
507 struct rte_rawdev * __rte_experimental
508 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
512 * Destroy a raw device
517 * - 0 on success, negative on error
519 int __rte_experimental
520 rte_rawdev_pmd_uninit(const char *name);
526 #endif /* _RTE_RAWDEV_PMD_H_ */