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 * Dump internal information
259 * A pointer to a file for output
265 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
268 * Get an attribute value from implementation.
269 * Attribute is an opaque handle agreed upon between application and PMD.
274 * Opaque object representing an attribute in implementation.
275 * @param attr_value [out]
276 * Opaque response to the attribute value. In case of error, this remains
277 * untouched. This is double pointer of void type.
280 * !0 Error; attr_value remains untouched in case of error.
282 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
283 const char *attr_name,
284 uint64_t *attr_value);
287 * Set an attribute value.
288 * Attribute is an opaque handle agreed upon between application and PMD.
293 * Opaque object representing an attribute in implementation.
295 * Value of the attribute represented by attr_name
300 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
301 const char *attr_name,
302 const uint64_t attr_value);
304 /** Rawdevice operations function pointer table */
305 struct rte_rawdev_ops {
306 /**< Get device info. */
307 rawdev_info_get_t dev_info_get;
308 /**< Configure device. */
309 rawdev_configure_t dev_configure;
310 /**< Start device. */
311 rawdev_start_t dev_start;
313 rawdev_stop_t dev_stop;
314 /**< Close device. */
315 rawdev_close_t dev_close;
316 /**< Reset device. */
317 rawdev_reset_t dev_reset;
319 /**< Get raw queue configuration. */
320 rawdev_queue_conf_get_t queue_def_conf;
321 /**< Set up an raw queue. */
322 rawdev_queue_setup_t queue_setup;
323 /**< Release an raw queue. */
324 rawdev_queue_release_t queue_release;
326 /* Dump internal information */
329 /**< Get an attribute managed by the implementation */
330 rawdev_get_attr_t attr_get;
331 /**< Set an attribute managed by the implementation */
332 rawdev_set_attr_t attr_set;
336 * Allocates a new rawdev slot for an raw device and returns the pointer
337 * to that slot for the driver to use.
340 * Unique identifier name for each device
341 * @param dev_private_size
342 * Private data allocated within rte_rawdev object.
344 * Socket to allocate resources on.
346 * - Slot in the rte_dev_devices array for a new device;
348 struct rte_rawdev * __rte_experimental
349 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
353 * Release the specified rawdev device.
356 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
358 * - 0 on success, negative on error
360 int __rte_experimental
361 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
364 * Creates a new raw device and returns the pointer to that device.
367 * Pointer to a character array containing name of the device
368 * @param dev_private_size
369 * Size of raw PMDs private data
371 * Socket to allocate resources on.
374 * - Raw device pointer if device is successfully created.
375 * - NULL if device cannot be created.
377 struct rte_rawdev * __rte_experimental
378 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
382 * Destroy a raw device
387 * - 0 on success, negative on error
389 int __rte_experimental
390 rte_rawdev_pmd_uninit(const char *name);
396 #endif /* _RTE_RAWDEV_PMD_H_ */