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 * 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 if (dev_id >= RTE_RAWDEV_MAX_DEVS) 120 return 0; 121 122 dev = &rte_rawdevs[dev_id]; 123 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_ */ 637