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);
267 /** Rawdevice operations function pointer table */
268 struct rte_rawdev_ops {
269 /**< Get device info. */
270 rawdev_info_get_t dev_info_get;
271 /**< Configure device. */
272 rawdev_configure_t dev_configure;
273 /**< Start device. */
274 rawdev_start_t dev_start;
276 rawdev_stop_t dev_stop;
277 /**< Close device. */
278 rawdev_close_t dev_close;
279 /**< Reset device. */
280 rawdev_reset_t dev_reset;
282 /**< Get raw queue configuration. */
283 rawdev_queue_conf_get_t queue_def_conf;
284 /**< Set up an raw queue. */
285 rawdev_queue_setup_t queue_setup;
286 /**< Release an raw queue. */
287 rawdev_queue_release_t queue_release;
289 /* Dump internal information */
294 * Allocates a new rawdev slot for an raw device and returns the pointer
295 * to that slot for the driver to use.
298 * Unique identifier name for each device
299 * @param dev_private_size
300 * Private data allocated within rte_rawdev object.
302 * Socket to allocate resources on.
304 * - Slot in the rte_dev_devices array for a new device;
306 struct rte_rawdev * __rte_experimental
307 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
311 * Release the specified rawdev device.
314 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
316 * - 0 on success, negative on error
318 int __rte_experimental
319 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
322 * Creates a new raw device and returns the pointer to that device.
325 * Pointer to a character array containing name of the device
326 * @param dev_private_size
327 * Size of raw PMDs private data
329 * Socket to allocate resources on.
332 * - Raw device pointer if device is successfully created.
333 * - NULL if device cannot be created.
335 struct rte_rawdev * __rte_experimental
336 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
340 * Destroy a raw device
345 * - 0 on success, negative on error
347 int __rte_experimental
348 rte_rawdev_pmd_uninit(const char *name);
354 #endif /* _RTE_RAWDEV_PMD_H_ */