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 : : #ifdef __cplusplus
17 : : extern "C" {
18 : : #endif
19 : :
20 : : #include <string.h>
21 : :
22 : : #include <dev_driver.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 : : #define RTE_LOGTYPE_RAWDEV librawdev_logtype
31 : :
32 : : /* Logging Macros */
33 : : #define RTE_RDEV_LOG(level, fmt, args...) \
34 : : RTE_LOG_LINE(level, RAWDEV, "%s(): " fmt, __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 *
86 : 38 : rte_rawdev_pmd_get_named_dev(const char *name)
87 : : {
88 : : struct rte_rawdev *dev;
89 : : unsigned int i;
90 : :
91 [ + - ]: 38 : if (name == NULL)
92 : : return NULL;
93 : :
94 [ + + ]: 2342 : for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) {
95 : 2306 : dev = &rte_rawdevs[i];
96 [ + + ]: 2306 : if ((dev->attached == RTE_RAWDEV_ATTACHED) &&
97 [ + - ]: 2 : (strcmp(dev->name, name) == 0))
98 : 2 : 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
114 : : rte_rawdev_pmd_is_valid_dev(uint8_t dev_id)
115 : : {
116 : : struct rte_rawdev *dev;
117 : :
118 [ - - - - : 42 : if (dev_id >= RTE_RAWDEV_MAX_DEVS)
- - + - +
- + - + -
+ - + - -
- - - - -
- - - - -
- - - + -
+ - + - +
- + - + -
+ - + - +
- + - +
+ ]
119 : : return 0;
120 : :
121 : 41 : dev = &rte_rawdevs[dev_id];
122 [ - - - - : 41 : 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 : : typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
259 : : uint16_t queue_id);
260 : :
261 : : /**
262 : : * Get the count of number of queues configured on this device.
263 : : *
264 : : * Another way to fetch this information is to fetch the device configuration.
265 : : * But, that assumes that the device configuration managed by the driver has
266 : : * that kind of information.
267 : : *
268 : : * This function helps in getting queue count supported, independently. It
269 : : * can help in cases where iterator needs to be implemented.
270 : : *
271 : : * @param dev
272 : : * Raw device pointer
273 : : * @return
274 : : * Number of queues; 0 is assumed to be a valid response.
275 : : */
276 : : typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
277 : :
278 : : /**
279 : : * Enqueue an array of raw buffers to the device.
280 : : *
281 : : * Buffer being used is opaque - it can be obtained from mempool or from
282 : : * any other source. Interpretation of buffer is responsibility of driver.
283 : : *
284 : : * @param dev
285 : : * Raw device pointer
286 : : * @param buffers
287 : : * array of buffers
288 : : * @param count
289 : : * number of buffers passed
290 : : * @param context
291 : : * an opaque object representing context of the call; for example, an
292 : : * application can pass information about the queues on which enqueue needs
293 : : * to be done. Or, the enqueue operation might be passed reference to an
294 : : * object containing a callback (agreed upon between application and driver).
295 : : *
296 : : * @return
297 : : * >=0 Count of buffers successfully enqueued (0: no buffers enqueued)
298 : : * <0 Error count in case of error
299 : : */
300 : : typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
301 : : struct rte_rawdev_buf **buffers,
302 : : unsigned int count,
303 : : rte_rawdev_obj_t context);
304 : :
305 : : /**
306 : : * Dequeue an array of raw buffers from the device.
307 : : *
308 : : * @param dev
309 : : * Raw device pointer
310 : : * @param buffers
311 : : * array of buffers
312 : : * @param count
313 : : * Max buffers expected to be dequeued
314 : : * @param context
315 : : * an opaque object representing context of the call. Based on this object,
316 : : * the application and driver can coordinate for dequeue operation involving
317 : : * agreed upon semantics. For example, queue information/id on which Dequeue
318 : : * needs to be performed.
319 : : * @return
320 : : * >0, ~0: Count of buffers returned
321 : : * <0: Error
322 : : * Whether short dequeue is success or failure is decided between app and
323 : : * driver.
324 : : */
325 : : typedef int (*rawdev_dequeue_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 : : * Dump internal information
332 : : *
333 : : * @param dev
334 : : * Raw device pointer
335 : : * @param f
336 : : * A pointer to a file for output
337 : : * @return
338 : : * 0 for success,
339 : : * !0 Error
340 : : */
341 : : typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f);
342 : :
343 : : /**
344 : : * Get an attribute value from implementation.
345 : : * Attribute is an opaque handle agreed upon between application and PMD.
346 : : *
347 : : * @param dev
348 : : * Raw device pointer
349 : : * @param attr_name
350 : : * Opaque object representing an attribute in implementation.
351 : : * @param attr_value [out]
352 : : * Opaque response to the attribute value. In case of error, this remains
353 : : * untouched. This is double pointer of void type.
354 : : * @return
355 : : * 0 for success
356 : : * !0 Error; attr_value remains untouched in case of error.
357 : : */
358 : : typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev,
359 : : const char *attr_name,
360 : : uint64_t *attr_value);
361 : :
362 : : /**
363 : : * Set an attribute value.
364 : : * Attribute is an opaque handle agreed upon between application and PMD.
365 : : *
366 : : * @param dev
367 : : * Raw device pointer
368 : : * @param attr_name
369 : : * Opaque object representing an attribute in implementation.
370 : : * @param attr_value
371 : : * Value of the attribute represented by attr_name
372 : : * @return
373 : : * 0 for success
374 : : * !0 Error
375 : : */
376 : : typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev,
377 : : const char *attr_name,
378 : : const uint64_t attr_value);
379 : :
380 : : /**
381 : : * Retrieve a set of statistics from device.
382 : : * Note: Being a raw device, the stats are specific to the device being
383 : : * implemented thus represented as xstats.
384 : : *
385 : : * @param dev
386 : : * Raw device pointer
387 : : * @param ids
388 : : * The stat ids to retrieve
389 : : * @param values
390 : : * The returned stat values
391 : : * @param n
392 : : * The number of id values and entries in the values array
393 : : * @return
394 : : * The number of stat values successfully filled into the values array
395 : : */
396 : : typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev,
397 : : const unsigned int ids[], uint64_t values[], unsigned int n);
398 : :
399 : : /**
400 : : * Resets the statistic values in xstats for the device.
401 : : */
402 : : typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev,
403 : : const uint32_t ids[],
404 : : uint32_t nb_ids);
405 : :
406 : : /**
407 : : * Get names of extended stats of an raw device
408 : : *
409 : : * @param dev
410 : : * Raw device pointer
411 : : * @param xstats_names
412 : : * Array of name values to be filled in
413 : : * @param size
414 : : * Number of values in the xstats_names array
415 : : * @return
416 : : * When size >= the number of stats, return the number of stat values filled
417 : : * into the array.
418 : : * When size < the number of available stats, return the number of stats
419 : : * values, and do not fill in any data into xstats_names.
420 : : */
421 : : typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev,
422 : : struct rte_rawdev_xstats_name *xstats_names,
423 : : unsigned int size);
424 : :
425 : : /**
426 : : * Get value of one stats and optionally return its id
427 : : *
428 : : * @param dev
429 : : * Raw device pointer
430 : : * @param name
431 : : * The name of the stat to retrieve
432 : : * @param id
433 : : * Pointer to an unsigned int where we store the stat-id.
434 : : * This pointer may be null if the id is not required.
435 : : * @return
436 : : * The value of the stat, or (uint64_t)-1 if the stat is not found.
437 : : * If the stat is not found, the id value will be returned as (unsigned)-1,
438 : : * if id pointer is non-NULL
439 : : */
440 : : typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
441 : : const char *name,
442 : : unsigned int *id);
443 : :
444 : : /**
445 : : * Get firmware/device-stack status.
446 : : * Implementation to allocate buffer for returning information.
447 : : *
448 : : * @param dev
449 : : * Raw device pointer
450 : : * @param status_info
451 : : * void block containing device specific status information
452 : : * @return
453 : : * 0 for success,
454 : : * !0 for failure, with undefined value in `status_info`
455 : : */
456 : : typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev,
457 : : rte_rawdev_obj_t status_info);
458 : :
459 : : /**
460 : : * Get firmware version information
461 : : *
462 : : * @param dev
463 : : * Raw device pointer
464 : : * @param version_info
465 : : * void pointer to version information returned by device
466 : : * @return
467 : : * 0 for success,
468 : : * !0 for failure, with undefined value in `version_info`
469 : : */
470 : : typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
471 : : rte_rawdev_obj_t version_info);
472 : :
473 : : /**
474 : : * Load firmware from a buffer (DMA'able)
475 : : *
476 : : * @param dev
477 : : * Raw device pointer
478 : : * @param firmware_buf
479 : : * Pointer to firmware image
480 : : * @return
481 : : * >0, ~0: for successful load
482 : : * <0: for failure
483 : : *
484 : : * @see Application may use 'firmware_version_get` for ascertaining successful
485 : : * load
486 : : */
487 : : typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev,
488 : : rte_rawdev_obj_t firmware_buf);
489 : :
490 : : /**
491 : : * Unload firmware
492 : : *
493 : : * @param dev
494 : : * Raw device pointer
495 : : * @return
496 : : * >0, ~0 for successful unloading
497 : : * <0 for failure in unloading
498 : : *
499 : : * Note: Application can use the `firmware_status_get` or
500 : : * `firmware_version_get` to get result of unload.
501 : : */
502 : : typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev);
503 : :
504 : : /**
505 : : * Start rawdev selftest
506 : : *
507 : : * @return
508 : : * Return 0 on success
509 : : */
510 : : typedef int (*rawdev_selftest_t)(uint16_t dev_id);
511 : :
512 : : /** Rawdevice operations function pointer table */
513 : : struct rte_rawdev_ops {
514 : : /**< Get device info. */
515 : : rawdev_info_get_t dev_info_get;
516 : : /**< Configure device. */
517 : : rawdev_configure_t dev_configure;
518 : : /**< Start device. */
519 : : rawdev_start_t dev_start;
520 : : /**< Stop device. */
521 : : rawdev_stop_t dev_stop;
522 : : /**< Close device. */
523 : : rawdev_close_t dev_close;
524 : : /**< Reset device. */
525 : : rawdev_reset_t dev_reset;
526 : :
527 : : /**< Get raw queue configuration. */
528 : : rawdev_queue_conf_get_t queue_def_conf;
529 : : /**< Set up an raw queue. */
530 : : rawdev_queue_setup_t queue_setup;
531 : : /**< Release an raw queue. */
532 : : rawdev_queue_release_t queue_release;
533 : : /**< Get the number of queues attached to the device */
534 : : rawdev_queue_count_t queue_count;
535 : :
536 : : /**< Enqueue an array of raw buffers to device. */
537 : : rawdev_enqueue_bufs_t enqueue_bufs;
538 : : /**< Dequeue an array of raw buffers from device. */
539 : : /** TODO: Callback based enqueue and dequeue support */
540 : : rawdev_dequeue_bufs_t dequeue_bufs;
541 : :
542 : : /* Dump internal information */
543 : : rawdev_dump_t dump;
544 : :
545 : : /**< Get an attribute managed by the implementation */
546 : : rawdev_get_attr_t attr_get;
547 : : /**< Set an attribute managed by the implementation */
548 : : rawdev_set_attr_t attr_set;
549 : :
550 : : /**< Get extended device statistics. */
551 : : rawdev_xstats_get_t xstats_get;
552 : : /**< Get names of extended stats. */
553 : : rawdev_xstats_get_names_t xstats_get_names;
554 : : /**< Get one value by name. */
555 : : rawdev_xstats_get_by_name_t xstats_get_by_name;
556 : : /**< Reset the statistics values in xstats. */
557 : : rawdev_xstats_reset_t xstats_reset;
558 : :
559 : : /**< Obtain firmware status */
560 : : rawdev_firmware_status_get_t firmware_status_get;
561 : : /**< Obtain firmware version information */
562 : : rawdev_firmware_version_get_t firmware_version_get;
563 : : /**< Load firmware */
564 : : rawdev_firmware_load_t firmware_load;
565 : : /**< Unload firmware */
566 : : rawdev_firmware_unload_t firmware_unload;
567 : :
568 : : /**< Device selftest function */
569 : : rawdev_selftest_t dev_selftest;
570 : : };
571 : :
572 : : /**
573 : : * Allocates a new rawdev slot for an raw device and returns the pointer
574 : : * to that slot for the driver to use.
575 : : *
576 : : * @param name
577 : : * Unique identifier name for each device
578 : : * @param dev_private_size
579 : : * Size of private data memory allocated within rte_rawdev object.
580 : : * Set to 0 to disable internal memory allocation and allow for
581 : : * self-allocation.
582 : : * @param socket_id
583 : : * Socket to allocate resources on.
584 : : * @return
585 : : * - Slot in the rte_dev_devices array for a new device;
586 : : */
587 : : struct rte_rawdev *
588 : : rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size,
589 : : int socket_id);
590 : :
591 : : /**
592 : : * Release the specified rawdev device.
593 : : *
594 : : * @param rawdev
595 : : * The *rawdev* pointer is the address of the *rte_rawdev* structure.
596 : : * @return
597 : : * - 0 on success, negative on error
598 : : */
599 : : int
600 : : rte_rawdev_pmd_release(struct rte_rawdev *rawdev);
601 : :
602 : : /**
603 : : * Creates a new raw device and returns the pointer to that device.
604 : : *
605 : : * @param name
606 : : * Pointer to a character array containing name of the device
607 : : * @param dev_private_size
608 : : * Size of raw PMDs private data
609 : : * @param socket_id
610 : : * Socket to allocate resources on.
611 : : *
612 : : * @return
613 : : * - Raw device pointer if device is successfully created.
614 : : * - NULL if device cannot be created.
615 : : */
616 : : struct rte_rawdev *
617 : : rte_rawdev_pmd_init(const char *name, size_t dev_private_size,
618 : : int socket_id);
619 : :
620 : : /**
621 : : * Destroy a raw device
622 : : *
623 : : * @param name
624 : : * Name of the device
625 : : * @return
626 : : * - 0 on success, negative on error
627 : : */
628 : : int
629 : : rte_rawdev_pmd_uninit(const char *name);
630 : :
631 : : #ifdef __cplusplus
632 : : }
633 : : #endif
634 : :
635 : : #endif /* _RTE_RAWDEV_PMD_H_ */
|