1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2017 NXP
3 */
4
5 #ifndef _RTE_RAWDEV_PMD_H_
6 #define _RTE_RAWDEV_PMD_H_
7
8 /** @file
9 * RTE RAW PMD APIs
10 *
11 * @note
12 * Driver facing APIs for a raw device. These are not to be called directly by
13 * any application.
14 */
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 #include <string.h>
21
22 #include <rte_dev.h>
23 #include <rte_malloc.h>
24 #include <rte_log.h>
25 #include <rte_common.h>
26
27 #include "rte_rawdev.h"
28
29 extern int librawdev_logtype;
30
31 /* Logging Macros */
32 #define RTE_RDEV_LOG(level, fmt, args...) \
33 rte_log(RTE_LOG_ ## level, librawdev_logtype, "%s(): " fmt "\n", \
34 __func__, ##args)
35
36 #define RTE_RDEV_ERR(fmt, args...) \
37 RTE_RDEV_LOG(ERR, fmt, ## args)
38 #define RTE_RDEV_DEBUG(fmt, args...) \
39 RTE_RDEV_LOG(DEBUG, fmt, ## args)
40 #define RTE_RDEV_INFO(fmt, args...) \
41 RTE_RDEV_LOG(INFO, fmt, ## args)
42
43
44 /* Macros to check for valid device */
45 #define RTE_RAWDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
46 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
47 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
48 return retval; \
49 } \
50 } while (0)
51
52 #define RTE_RAWDEV_VALID_DEVID_OR_RET(dev_id) do { \
53 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \
54 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \
55 return; \
56 } \
57 } while (0)
58
59 #define RTE_RAWDEV_DETACHED (0)
60 #define RTE_RAWDEV_ATTACHED (1)
61
62 /* Global structure used for maintaining state of allocated raw devices.
63 *
64 * TODO: Can be expanded to <type of raw device>:<count> in future.
65 * Applications should be able to select from a number of type of raw
66 * devices which were detected or attached to this DPDK instance.
67 */
68 struct rte_rawdev_global {
69 /**< Number of devices found */
70 uint16_t nb_devs;
71 };
72
73 extern struct rte_rawdev *rte_rawdevs;
74 /** The pool of rte_rawdev structures. */
75
76 /**
77 * Get the rte_rawdev structure device pointer for the named device.
78 *
79 * @param name
80 * device name to select the device structure.
81 *
82 * @return
83 * - The rte_rawdev structure pointer for the given device ID.
84 */
85 static inline struct rte_rawdev *
rte_rawdev_pmd_get_named_dev(const char * name)86 rte_rawdev_pmd_get_named_dev(const char *name)
87 {
88 struct rte_rawdev *dev;
89 unsigned int i;
90
91 if (name == NULL)
92 return NULL;
93
94 for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) {
95 dev = &rte_rawdevs[i];
96 if ((dev->attached == RTE_RAWDEV_ATTACHED) &&
97 (strcmp(dev->name, name) == 0))
98 return dev;
99 }
100
101 return NULL;
102 }
103
104 /**
105 * Validate if the raw device index is a valid attached raw device.
106 *
107 * @param dev_id
108 * raw device index.
109 *
110 * @return
111 * - If the device index is valid (1) or not (0).
112 */
113 static inline unsigned
rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)114 rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
115 {
116 struct rte_rawdev *dev;
117
118 if (dev_id >= RTE_RAWDEV_MAX_DEVS)
119 return 0;
120
121 dev = &rte_rawdevs[dev_id];
122 if (dev->attached != RTE_RAWDEV_ATTACHED)
123 return 0;
124 else
125 return 1;
126 }
127
128 /**
129 * Definitions of all functions exported by a driver through
130 * the generic structure of type *rawdev_ops* supplied in the
131 * *rte_rawdev* structure associated with a device.
132 */
133
134 /**
135 * Get device information of a device.
136 *
137 * @param dev
138 * Raw device pointer
139 * @param dev_info
140 * Raw device information structure
141 * @param dev_private_size
142 * The size of the structure pointed to by dev_info->dev_private
143 *
144 * @return
145 * Returns 0 on success, negative error code on failure
146 */
147 typedef int (*rawdev_info_get_t)(struct rte_rawdev *dev,
148 rte_rawdev_obj_t dev_info,
149 size_t dev_private_size);
150
151 /**
152 * Configure a device.
153 *
154 * @param dev
155 * Raw device pointer
156 * @param config
157 * Void object containing device specific configuration
158 * @param config_size
159 * Size of the memory allocated for the configuration
160 *
161 * @return
162 * Returns 0 on success
163 */
164 typedef int (*rawdev_configure_t)(const struct rte_rawdev *dev,
165 rte_rawdev_obj_t config,
166 size_t config_size);
167
168 /**
169 * Start a configured device.
170 *
171 * @param dev
172 * Raw device pointer
173 *
174 * @return
175 * Returns 0 on success
176 */
177 typedef int (*rawdev_start_t)(struct rte_rawdev *dev);
178
179 /**
180 * Stop a configured device.
181 *
182 * @param dev
183 * Raw device pointer
184 */
185 typedef void (*rawdev_stop_t)(struct rte_rawdev *dev);
186
187 /**
188 * Close a configured device.
189 *
190 * @param dev
191 * Raw device pointer
192 *
193 * @return
194 * - 0 on success
195 * - (-EAGAIN) if can't close as device is busy
196 */
197 typedef int (*rawdev_close_t)(struct rte_rawdev *dev);
198
199 /**
200 * Reset a configured device.
201 *
202 * @param dev
203 * Raw device pointer
204 * @return
205 * 0 for success
206 * !0 for failure
207 */
208 typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
209
210 /**
211 * Retrieve the current raw queue configuration.
212 *
213 * @param dev
214 * Raw device pointer
215 * @param queue_id
216 * Raw device queue index
217 * @param[out] queue_conf
218 * Raw device queue configuration structure
219 * @param queue_conf_size
220 * Size of the memory allocated for the configuration
221 *
222 * @return
223 * Returns 0 on success, negative errno on failure
224 */
225 typedef int (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
226 uint16_t queue_id,
227 rte_rawdev_obj_t queue_conf,
228 size_t queue_conf_size);
229
230 /**
231 * Setup an raw queue.
232 *
233 * @param dev
234 * Raw device pointer
235 * @param queue_id
236 * Rawqueue index
237 * @param queue_conf
238 * Rawqueue configuration structure
239 * @param queue_conf_size
240 * Size of the memory allocated for the configuration
241 *
242 * @return
243 * Returns 0 on success.
244 */
245 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev,
246 uint16_t queue_id,
247 rte_rawdev_obj_t queue_conf,
248 size_t queue_conf_size);
249
250 /**
251 * Release resources allocated by given raw queue.
252 *
253 * @param dev
254 * Raw device pointer
255 * @param queue_id
256 * Raw queue index
257 *
258 */
259 typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
260 uint16_t queue_id);
261
262 /**
263 * Get the count of number of queues configured on this device.
264 *
265 * Another way to fetch this information is to fetch the device configuration.
266 * But, that assumes that the device configuration managed by the driver has
267 * that kind of information.
268 *
269 * This function helps in getting queue count supported, independently. It
270 * can help in cases where iterator needs to be implemented.
271 *
272 * @param dev
273 * Raw device pointer
274 * @return
275 * Number of queues; 0 is assumed to be a valid response.
276 *
277 */
278 typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
279
280 /**
281 * Enqueue an array of raw buffers to the device.
282 *
283 * Buffer being used is opaque - it can be obtained from mempool or from
284 * any other source. Interpretation of buffer is responsibility of driver.
285 *
286 * @param dev
287 * Raw device pointer
288 * @param buffers
289 * array of buffers
290 * @param count
291 * number of buffers passed
292 * @param context
293 * an opaque object representing context of the call; for example, an
294 * application can pass information about the queues on which enqueue needs
295 * to be done. Or, the enqueue operation might be passed reference to an
296 * object containing a callback (agreed upon between application and driver).
297 *
298 * @return
299 * >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
300 * <0 Error count in case of error
301 */
302 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
303 struct rte_rawdev_buf **buffers,
304 unsigned int count,
305 rte_rawdev_obj_t context);
306
307 /**
308 * Dequeue an array of raw buffers from the device.
309 *
310 * @param dev
311 * Raw device pointer
312 * @param buffers
313 * array of buffers
314 * @param count
315 * Max buffers expected to be dequeued
316 * @param context
317 * an opaque object representing context of the call. Based on this object,
318 * the application and driver can coordinate for dequeue operation involving
319 * agreed upon semantics. For example, queue information/id on which Dequeue
320 * needs to be performed.
321 * @return
322 * >0, ~0: Count of buffers returned
323 * <0: Error
324 * Whether short dequeue is success or failure is decided between app and
325 * driver.
326 */
327 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev,
328 struct rte_rawdev_buf **buffers,
329 unsigned int count,
330 rte_rawdev_obj_t context);
331
332 /**
333 * Dump internal information
334 *
335 * @param dev
336 * Raw device pointer
337 * @param f
338 * A pointer to a file for output
339 * @return
340 * 0 for success,
341 * !0 Error
342 *
343 */
344 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
345
346 /**
347 * Get an attribute value from implementation.
348 * Attribute is an opaque handle agreed upon between application and PMD.
349 *
350 * @param dev
351 * Raw device pointer
352 * @param attr_name
353 * Opaque object representing an attribute in implementation.
354 * @param attr_value [out]
355 * Opaque response to the attribute value. In case of error, this remains
356 * untouched. This is double pointer of void type.
357 * @return
358 * 0 for success
359 * !0 Error; attr_value remains untouched in case of error.
360 */
361 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
362 const char *attr_name,
363 uint64_t *attr_value);
364
365 /**
366 * Set an attribute value.
367 * Attribute is an opaque handle agreed upon between application and PMD.
368 *
369 * @param dev
370 * Raw device pointer
371 * @param attr_name
372 * Opaque object representing an attribute in implementation.
373 * @param attr_value
374 * Value of the attribute represented by attr_name
375 * @return
376 * 0 for success
377 * !0 Error
378 */
379 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
380 const char *attr_name,
381 const uint64_t attr_value);
382
383 /**
384 * Retrieve a set of statistics from device.
385 * Note: Being a raw device, the stats are specific to the device being
386 * implemented thus represented as xstats.
387 *
388 * @param dev
389 * Raw device pointer
390 * @param ids
391 * The stat ids to retrieve
392 * @param values
393 * The returned stat values
394 * @param n
395 * The number of id values and entries in the values array
396 * @return
397 * The number of stat values successfully filled into the values array
398 */
399 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
400 const unsigned int ids[], uint64_t values[], unsigned int n);
401
402 /**
403 * Resets the statistic values in xstats for the device.
404 */
405 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
406 const uint32_t ids[],
407 uint32_t nb_ids);
408
409 /**
410 * Get names of extended stats of an raw device
411 *
412 * @param dev
413 * Raw device pointer
414 * @param xstats_names
415 * Array of name values to be filled in
416 * @param size
417 * Number of values in the xstats_names array
418 * @return
419 * When size >= the number of stats, return the number of stat values filled
420 * into the array.
421 * When size < the number of available stats, return the number of stats
422 * values, and do not fill in any data into xstats_names.
423 */
424 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
425 struct rte_rawdev_xstats_name *xstats_names,
426 unsigned int size);
427
428 /**
429 * Get value of one stats and optionally return its id
430 *
431 * @param dev
432 * Raw device pointer
433 * @param name
434 * The name of the stat to retrieve
435 * @param id
436 * Pointer to an unsigned int where we store the stat-id.
437 * This pointer may be null if the id is not required.
438 * @return
439 * The value of the stat, or (uint64_t)-1 if the stat is not found.
440 * If the stat is not found, the id value will be returned as (unsigned)-1,
441 * if id pointer is non-NULL
442 */
443 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
444 const char *name,
445 unsigned int *id);
446
447 /**
448 * Get firmware/device-stack status.
449 * Implementation to allocate buffer for returning information.
450 *
451 * @param dev
452 * Raw device pointer
453 * @param status_info
454 * void block containing device specific status information
455 * @return
456 * 0 for success,
457 * !0 for failure, with undefined value in `status_info`
458 */
459 typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev,
460 rte_rawdev_obj_t status_info);
461
462 /**
463 * Get firmware version information
464 *
465 * @param dev
466 * Raw device pointer
467 * @param version_info
468 * void pointer to version information returned by device
469 * @return
470 * 0 for success,
471 * !0 for failure, with undefined value in `version_info`
472 */
473 typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
474 rte_rawdev_obj_t version_info);
475
476 /**
477 * Load firmware from a buffer (DMA'able)
478 *
479 * @param dev
480 * Raw device pointer
481 * @param firmware_buf
482 * Pointer to firmware image
483 * @return
484 * >0, ~0: for successful load
485 * <0: for failure
486 *
487 * @see Application may use 'firmware_version_get` for ascertaining successful
488 * load
489 */
490 typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
491 rte_rawdev_obj_t firmware_buf);
492
493 /**
494 * Unload firmware
495 *
496 * @param dev
497 * Raw device pointer
498 * @return
499 * >0, ~0 for successful unloading
500 * <0 for failure in unloading
501 *
502 * Note: Application can use the `firmware_status_get` or
503 * `firmware_version_get` to get result of unload.
504 */
505 typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
506
507 /**
508 * Start rawdev selftest
509 *
510 * @return
511 * Return 0 on success
512 */
513 typedef int (*rawdev_selftest_t)(uint16_t dev_id);
514
515 /** Rawdevice operations function pointer table */
516 struct rte_rawdev_ops {
517 /**< Get device info. */
518 rawdev_info_get_t dev_info_get;
519 /**< Configure device. */
520 rawdev_configure_t dev_configure;
521 /**< Start device. */
522 rawdev_start_t dev_start;
523 /**< Stop device. */
524 rawdev_stop_t dev_stop;
525 /**< Close device. */
526 rawdev_close_t dev_close;
527 /**< Reset device. */
528 rawdev_reset_t dev_reset;
529
530 /**< Get raw queue configuration. */
531 rawdev_queue_conf_get_t queue_def_conf;
532 /**< Set up an raw queue. */
533 rawdev_queue_setup_t queue_setup;
534 /**< Release an raw queue. */
535 rawdev_queue_release_t queue_release;
536 /**< Get the number of queues attached to the device */
537 rawdev_queue_count_t queue_count;
538
539 /**< Enqueue an array of raw buffers to device. */
540 rawdev_enqueue_bufs_t enqueue_bufs;
541 /**< Dequeue an array of raw buffers from device. */
542 /** TODO: Callback based enqueue and dequeue support */
543 rawdev_dequeue_bufs_t dequeue_bufs;
544
545 /* Dump internal information */
546 rawdev_dump_t dump;
547
548 /**< Get an attribute managed by the implementation */
549 rawdev_get_attr_t attr_get;
550 /**< Set an attribute managed by the implementation */
551 rawdev_set_attr_t attr_set;
552
553 /**< Get extended device statistics. */
554 rawdev_xstats_get_t xstats_get;
555 /**< Get names of extended stats. */
556 rawdev_xstats_get_names_t xstats_get_names;
557 /**< Get one value by name. */
558 rawdev_xstats_get_by_name_t xstats_get_by_name;
559 /**< Reset the statistics values in xstats. */
560 rawdev_xstats_reset_t xstats_reset;
561
562 /**< Obtain firmware status */
563 rawdev_firmware_status_get_t firmware_status_get;
564 /**< Obtain firmware version information */
565 rawdev_firmware_version_get_t firmware_version_get;
566 /**< Load firmware */
567 rawdev_firmware_load_t firmware_load;
568 /**< Unload firmware */
569 rawdev_firmware_unload_t firmware_unload;
570
571 /**< Device selftest function */
572 rawdev_selftest_t dev_selftest;
573 };
574
575 /**
576 * Allocates a new rawdev slot for an raw device and returns the pointer
577 * to that slot for the driver to use.
578 *
579 * @param name
580 * Unique identifier name for each device
581 * @param dev_private_size
582 * Size of private data memory allocated within rte_rawdev object.
583 * Set to 0 to disable internal memory allocation and allow for
584 * self-allocation.
585 * @param socket_id
586 * Socket to allocate resources on.
587 * @return
588 * - Slot in the rte_dev_devices array for a new device;
589 */
590 struct rte_rawdev *
591 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
592 int socket_id);
593
594 /**
595 * Release the specified rawdev device.
596 *
597 * @param rawdev
598 * The *rawdev* pointer is the address of the *rte_rawdev* structure.
599 * @return
600 * - 0 on success, negative on error
601 */
602 int
603 rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
604
605 /**
606 * Creates a new raw device and returns the pointer to that device.
607 *
608 * @param name
609 * Pointer to a character array containing name of the device
610 * @param dev_private_size
611 * Size of raw PMDs private data
612 * @param socket_id
613 * Socket to allocate resources on.
614 *
615 * @return
616 * - Raw device pointer if device is successfully created.
617 * - NULL if device cannot be created.
618 */
619 struct rte_rawdev *
620 rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
621 int socket_id);
622
623 /**
624 * Destroy a raw device
625 *
626 * @param name
627 * Name of the device
628 * @return
629 * - 0 on success, negative on error
630 */
631 int
632 rte_rawdev_pmd_uninit(const char *name);
633
634 #ifdef __cplusplus
635 }
636 #endif
637
638 #endif /* _RTE_RAWDEV_PMD_H_ */
639