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