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