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 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 * 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 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