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 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 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_ */ 636