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);
356 /** Rawdevice operations function pointer table */
357 struct rte_rawdev_ops {
358 /**< Get device info. */
359 rawdev_info_get_t dev_info_get;
360 /**< Configure device. */
361 rawdev_configure_t dev_configure;
362 /**< Start device. */
363 rawdev_start_t dev_start;
365 rawdev_stop_t dev_stop;
366 /**< Close device. */
367 rawdev_close_t dev_close;
368 /**< Reset device. */
369 rawdev_reset_t dev_reset;
371 /**< Get raw queue configuration. */
372 rawdev_queue_conf_get_t queue_def_conf;
373 /**< Set up an raw queue. */
374 rawdev_queue_setup_t queue_setup;
375 /**< Release an raw queue. */
376 rawdev_queue_release_t queue_release;
378 /**< Enqueue an array of raw buffers to device. */
379 rawdev_enqueue_bufs_t enqueue_bufs;
380 /**< Dequeue an array of raw buffers from device. */
381 /** TODO: Callback based enqueue and dequeue support */
382 rawdev_dequeue_bufs_t dequeue_bufs;
384 /* Dump internal information */
387 /**< Get an attribute managed by the implementation */
388 rawdev_get_attr_t attr_get;
389 /**< Set an attribute managed by the implementation */
390 rawdev_set_attr_t attr_set;
394 * Allocates a new rawdev slot for an raw device and returns the pointer
395 * to that slot for the driver to use.
398 * Unique identifier name for each device
399 * @param dev_private_size
400 * Private data allocated within rte_rawdev object.
402 * Socket to allocate resources on.
404 * - Slot in the rte_dev_devices array for a new device;
406 struct rte_rawdev * __rte_experimental
407 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
411 * Release the specified rawdev device.
414 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
416 * - 0 on success, negative on error
418 int __rte_experimental
419 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
422 * Creates a new raw device and returns the pointer to that device.
425 * Pointer to a character array containing name of the device
426 * @param dev_private_size
427 * Size of raw PMDs private data
429 * Socket to allocate resources on.
432 * - Raw device pointer if device is successfully created.
433 * - NULL if device cannot be created.
435 struct rte_rawdev * __rte_experimental
436 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
440 * Destroy a raw device
445 * - 0 on success, negative on error
447 int __rte_experimental
448 rte_rawdev_pmd_uninit(const char *name);
454 #endif /* _RTE_RAWDEV_PMD_H_ */