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