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 rte_rawdev_pmd_get_named_dev(const char *name) 88 { 89 struct rte_rawdev *dev; 90 unsigned int i; 91 92 if (name == NULL) 93 return NULL; 94 95 for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) { 96 dev = &rte_rawdevs[i]; 97 if ((dev->attached == RTE_RAWDEV_ATTACHED) && 98 (strcmp(dev->name, name) == 0)) 99 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 if (dev_id >= RTE_RAWDEV_MAX_DEVS) 120 return NULL; 121 122 dev = &rte_rawdevs[dev_id]; 123 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 if (dev_id >= RTE_RAWDEV_MAX_DEVS) 144 return 0; 145 146 dev = &rte_rawdevs[dev_id]; 147 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_ */ 661