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 * @warning 16 * @b EXPERIMENTAL: this API may change without prior notice 17 */ 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 #include <string.h> 24 25 #include <rte_dev.h> 26 #include <rte_malloc.h> 27 #include <rte_log.h> 28 #include <rte_common.h> 29 30 #include "rte_rawdev.h" 31 32 extern int librawdev_logtype; 33 34 /* Logging Macros */ 35 #define RTE_RDEV_LOG(level, fmt, args...) \ 36 rte_log(RTE_LOG_ ## level, librawdev_logtype, "%s(): " fmt "\n", \ 37 __func__, ##args) 38 39 #define RTE_RDEV_ERR(fmt, args...) \ 40 RTE_RDEV_LOG(ERR, fmt, ## args) 41 #define RTE_RDEV_DEBUG(fmt, args...) \ 42 RTE_RDEV_LOG(DEBUG, fmt, ## args) 43 #define RTE_RDEV_INFO(fmt, args...) \ 44 RTE_RDEV_LOG(INFO, fmt, ## args) 45 46 47 /* Macros to check for valid device */ 48 #define RTE_RAWDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \ 49 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \ 50 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \ 51 return retval; \ 52 } \ 53 } while (0) 54 55 #define RTE_RAWDEV_VALID_DEVID_OR_RET(dev_id) do { \ 56 if (!rte_rawdev_pmd_is_valid_dev((dev_id))) { \ 57 RTE_RDEV_ERR("Invalid dev_id=%d", dev_id); \ 58 return; \ 59 } \ 60 } while (0) 61 62 #define RTE_RAWDEV_DETACHED (0) 63 #define RTE_RAWDEV_ATTACHED (1) 64 65 /* Global structure used for maintaining state of allocated raw devices. 66 * 67 * TODO: Can be expanded to <type of raw device>:<count> in future. 68 * Applications should be able to select from a number of type of raw 69 * devices which were detected or attached to this DPDK instance. 70 */ 71 struct rte_rawdev_global { 72 /**< Number of devices found */ 73 uint16_t nb_devs; 74 }; 75 76 extern struct rte_rawdev *rte_rawdevs; 77 /** The pool of rte_rawdev structures. */ 78 79 /** 80 * Get the rte_rawdev structure device pointer for the named device. 81 * 82 * @param name 83 * device name to select the device structure. 84 * 85 * @return 86 * - The rte_rawdev structure pointer for the given device ID. 87 */ 88 static inline struct rte_rawdev * 89 rte_rawdev_pmd_get_named_dev(const char *name) 90 { 91 struct rte_rawdev *dev; 92 unsigned int i; 93 94 if (name == NULL) 95 return NULL; 96 97 for (i = 0; i < RTE_RAWDEV_MAX_DEVS; i++) { 98 dev = &rte_rawdevs[i]; 99 if ((dev->attached == RTE_RAWDEV_ATTACHED) && 100 (strcmp(dev->name, name) == 0)) 101 return dev; 102 } 103 104 return NULL; 105 } 106 107 /** 108 * Validate if the raw device index is a valid attached raw device. 109 * 110 * @param dev_id 111 * raw device index. 112 * 113 * @return 114 * - If the device index is valid (1) or not (0). 115 */ 116 static inline unsigned 117 rte_rawdev_pmd_is_valid_dev(uint8_t dev_id) 118 { 119 struct rte_rawdev *dev; 120 121 if (dev_id >= RTE_RAWDEV_MAX_DEVS) 122 return 0; 123 124 dev = &rte_rawdevs[dev_id]; 125 if (dev->attached != RTE_RAWDEV_ATTACHED) 126 return 0; 127 else 128 return 1; 129 } 130 131 /** 132 * Definitions of all functions exported by a driver through the 133 * the generic structure of type *rawdev_ops* supplied in the 134 * *rte_rawdev* structure associated with a device. 135 */ 136 137 /** 138 * Get device information of a device. 139 * 140 * @param dev 141 * Raw device pointer 142 * @param dev_info 143 * Raw device information structure 144 * 145 * @return 146 * Returns 0 on success 147 */ 148 typedef void (*rawdev_info_get_t)(struct rte_rawdev *dev, 149 rte_rawdev_obj_t dev_info); 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 165 /** 166 * Start a configured device. 167 * 168 * @param dev 169 * Raw device pointer 170 * 171 * @return 172 * Returns 0 on success 173 */ 174 typedef int (*rawdev_start_t)(struct rte_rawdev *dev); 175 176 /** 177 * Stop a configured device. 178 * 179 * @param dev 180 * Raw device pointer 181 */ 182 typedef void (*rawdev_stop_t)(struct rte_rawdev *dev); 183 184 /** 185 * Close a configured device. 186 * 187 * @param dev 188 * Raw device pointer 189 * 190 * @return 191 * - 0 on success 192 * - (-EAGAIN) if can't close as device is busy 193 */ 194 typedef int (*rawdev_close_t)(struct rte_rawdev *dev); 195 196 /** 197 * Reset a configured device. 198 * 199 * @param dev 200 * Raw device pointer 201 * @return 202 * 0 for success 203 * !0 for failure 204 */ 205 typedef int (*rawdev_reset_t)(struct rte_rawdev *dev); 206 207 /** 208 * Retrieve the current raw queue configuration. 209 * 210 * @param dev 211 * Raw device pointer 212 * @param queue_id 213 * Raw device queue index 214 * @param[out] queue_conf 215 * Raw device queue configuration structure 216 * 217 */ 218 typedef void (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev, 219 uint16_t queue_id, 220 rte_rawdev_obj_t queue_conf); 221 222 /** 223 * Setup an raw queue. 224 * 225 * @param dev 226 * Raw device pointer 227 * @param queue_id 228 * Rawqueue index 229 * @param queue_conf 230 * Rawqueue configuration structure 231 * 232 * @return 233 * Returns 0 on success. 234 */ 235 typedef int (*rawdev_queue_setup_t)(struct rte_rawdev *dev, 236 uint16_t queue_id, 237 rte_rawdev_obj_t queue_conf); 238 239 /** 240 * Release resources allocated by given raw queue. 241 * 242 * @param dev 243 * Raw device pointer 244 * @param queue_id 245 * Raw queue index 246 * 247 */ 248 typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev, 249 uint16_t queue_id); 250 251 /** 252 * Get the count of number of queues configured on this device. 253 * 254 * Another way to fetch this information is to fetch the device configuration. 255 * But, that assumes that the device configuration managed by the driver has 256 * that kind of information. 257 * 258 * This function helps in getting queue count supported, independently. It 259 * can help in cases where iterator needs to be implemented. 260 * 261 * @param 262 * Raw device pointer 263 * @return 264 * Number of queues; 0 is assumed to be a valid response. 265 * 266 */ 267 typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev); 268 269 /** 270 * Enqueue an array of raw buffers to the device. 271 * 272 * Buffer being used is opaque - it can be obtained from mempool or from 273 * any other source. Interpretation of buffer is responsibility of driver. 274 * 275 * @param dev 276 * Raw device pointer 277 * @param bufs 278 * array of buffers 279 * @param count 280 * number of buffers passed 281 * @param context 282 * an opaque object representing context of the call; for example, an 283 * application can pass information about the queues on which enqueue needs 284 * to be done. Or, the enqueue operation might be passed reference to an 285 * object containing a callback (agreed upon between application and driver). 286 * 287 * @return 288 * >=0 Count of buffers successfully enqueued (0: no buffers enqueued) 289 * <0 Error count in case of error 290 */ 291 typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev, 292 struct rte_rawdev_buf **buffers, 293 unsigned int count, 294 rte_rawdev_obj_t context); 295 296 /** 297 * Dequeue an array of raw buffers from the device. 298 * 299 * @param dev 300 * Raw device pointer 301 * @param bufs 302 * array of buffers 303 * @param count 304 * Max buffers expected to be dequeued 305 * @param context 306 * an opaque object representing context of the call. Based on this object, 307 * the application and driver can coordinate for dequeue operation involving 308 * agreed upon semantics. For example, queue information/id on which Dequeue 309 * needs to be performed. 310 * @return 311 * >0, ~0: Count of buffers returned 312 * <0: Error 313 * Whether short dequeue is success or failure is decided between app and 314 * driver. 315 */ 316 typedef int (*rawdev_dequeue_bufs_t)(struct rte_rawdev *dev, 317 struct rte_rawdev_buf **buffers, 318 unsigned int count, 319 rte_rawdev_obj_t context); 320 321 /** 322 * Dump internal information 323 * 324 * @param dev 325 * Raw device pointer 326 * @param f 327 * A pointer to a file for output 328 * @return 329 * 0 for success, 330 * !0 Error 331 * 332 */ 333 typedef int (*rawdev_dump_t)(struct rte_rawdev *dev, FILE *f); 334 335 /** 336 * Get an attribute value from implementation. 337 * Attribute is an opaque handle agreed upon between application and PMD. 338 * 339 * @param dev 340 * Raw device pointer 341 * @param attr_name 342 * Opaque object representing an attribute in implementation. 343 * @param attr_value [out] 344 * Opaque response to the attribute value. In case of error, this remains 345 * untouched. This is double pointer of void type. 346 * @return 347 * 0 for success 348 * !0 Error; attr_value remains untouched in case of error. 349 */ 350 typedef int (*rawdev_get_attr_t)(struct rte_rawdev *dev, 351 const char *attr_name, 352 uint64_t *attr_value); 353 354 /** 355 * Set an attribute value. 356 * Attribute is an opaque handle agreed upon between application and PMD. 357 * 358 * @param dev 359 * Raw device pointer 360 * @param attr_name 361 * Opaque object representing an attribute in implementation. 362 * @param attr_value 363 * Value of the attribute represented by attr_name 364 * @return 365 * 0 for success 366 * !0 Error 367 */ 368 typedef int (*rawdev_set_attr_t)(struct rte_rawdev *dev, 369 const char *attr_name, 370 const uint64_t attr_value); 371 372 /** 373 * Retrieve a set of statistics from device. 374 * Note: Being a raw device, the stats are specific to the device being 375 * implemented thus represented as xstats. 376 * 377 * @param dev 378 * Raw device pointer 379 * @param ids 380 * The stat ids to retrieve 381 * @param values 382 * The returned stat values 383 * @param n 384 * The number of id values and entries in the values array 385 * @return 386 * The number of stat values successfully filled into the values array 387 */ 388 typedef int (*rawdev_xstats_get_t)(const struct rte_rawdev *dev, 389 const unsigned int ids[], uint64_t values[], unsigned int n); 390 391 /** 392 * Resets the statistic values in xstats for the device. 393 */ 394 typedef int (*rawdev_xstats_reset_t)(struct rte_rawdev *dev, 395 const uint32_t ids[], 396 uint32_t nb_ids); 397 398 /** 399 * Get names of extended stats of an raw device 400 * 401 * @param dev 402 * Raw device pointer 403 * @param xstats_names 404 * Array of name values to be filled in 405 * @param size 406 * Number of values in the xstats_names array 407 * @return 408 * When size >= the number of stats, return the number of stat values filled 409 * into the array. 410 * When size < the number of available stats, return the number of stats 411 * values, and do not fill in any data into xstats_names. 412 */ 413 typedef int (*rawdev_xstats_get_names_t)(const struct rte_rawdev *dev, 414 struct rte_rawdev_xstats_name *xstats_names, 415 unsigned int size); 416 417 /** 418 * Get value of one stats and optionally return its id 419 * 420 * @param dev 421 * Raw device pointer 422 * @param name 423 * The name of the stat to retrieve 424 * @param id 425 * Pointer to an unsigned int where we store the stat-id. 426 * This pointer may be null if the id is not required. 427 * @return 428 * The value of the stat, or (uint64_t)-1 if the stat is not found. 429 * If the stat is not found, the id value will be returned as (unsigned)-1, 430 * if id pointer is non-NULL 431 */ 432 typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev, 433 const char *name, 434 unsigned int *id); 435 436 /** 437 * Get firmware/device-stack status. 438 * Implementation to allocate buffer for returning information. 439 * 440 * @param dev 441 * Raw device pointer 442 * @param status 443 * void block containing device specific status information 444 * @return 445 * 0 for success, 446 * !0 for failure, with undefined value in `status_info` 447 */ 448 typedef int (*rawdev_firmware_status_get_t)(struct rte_rawdev *dev, 449 rte_rawdev_obj_t status_info); 450 451 /** 452 * Get firmware version information 453 * 454 * @param dev 455 * Raw device pointer 456 * @param version_info 457 * void pointer to version information returned by device 458 * @return 459 * 0 for success, 460 * !0 for failure, with undefined value in `version_info` 461 */ 462 typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev, 463 rte_rawdev_obj_t version_info); 464 465 /** 466 * Load firmware from a buffer (DMA'able) 467 * 468 * @param dev 469 * Raw device pointer 470 * @param firmware_file 471 * file pointer to firmware area 472 * @return 473 * >0, ~0: for successful load 474 * <0: for failure 475 * 476 * @see Application may use 'firmware_version_get` for ascertaining successful 477 * load 478 */ 479 typedef int (*rawdev_firmware_load_t)(struct rte_rawdev *dev, 480 rte_rawdev_obj_t firmware_buf); 481 482 /** 483 * Unload firmware 484 * 485 * @param dev 486 * Raw device pointer 487 * @return 488 * >0, ~0 for successful unloading 489 * <0 for failure in unloading 490 * 491 * Note: Application can use the `firmware_status_get` or 492 * `firmware_version_get` to get result of unload. 493 */ 494 typedef int (*rawdev_firmware_unload_t)(struct rte_rawdev *dev); 495 496 /** 497 * Start rawdev selftest 498 * 499 * @return 500 * Return 0 on success 501 */ 502 typedef int (*rawdev_selftest_t)(uint16_t dev_id); 503 504 /** Rawdevice operations function pointer table */ 505 struct rte_rawdev_ops { 506 /**< Get device info. */ 507 rawdev_info_get_t dev_info_get; 508 /**< Configure device. */ 509 rawdev_configure_t dev_configure; 510 /**< Start device. */ 511 rawdev_start_t dev_start; 512 /**< Stop device. */ 513 rawdev_stop_t dev_stop; 514 /**< Close device. */ 515 rawdev_close_t dev_close; 516 /**< Reset device. */ 517 rawdev_reset_t dev_reset; 518 519 /**< Get raw queue configuration. */ 520 rawdev_queue_conf_get_t queue_def_conf; 521 /**< Set up an raw queue. */ 522 rawdev_queue_setup_t queue_setup; 523 /**< Release an raw queue. */ 524 rawdev_queue_release_t queue_release; 525 /**< Get the number of queues attached to the device */ 526 rawdev_queue_count_t queue_count; 527 528 /**< Enqueue an array of raw buffers to device. */ 529 rawdev_enqueue_bufs_t enqueue_bufs; 530 /**< Dequeue an array of raw buffers from device. */ 531 /** TODO: Callback based enqueue and dequeue support */ 532 rawdev_dequeue_bufs_t dequeue_bufs; 533 534 /* Dump internal information */ 535 rawdev_dump_t dump; 536 537 /**< Get an attribute managed by the implementation */ 538 rawdev_get_attr_t attr_get; 539 /**< Set an attribute managed by the implementation */ 540 rawdev_set_attr_t attr_set; 541 542 /**< Get extended device statistics. */ 543 rawdev_xstats_get_t xstats_get; 544 /**< Get names of extended stats. */ 545 rawdev_xstats_get_names_t xstats_get_names; 546 /**< Get one value by name. */ 547 rawdev_xstats_get_by_name_t xstats_get_by_name; 548 /**< Reset the statistics values in xstats. */ 549 rawdev_xstats_reset_t xstats_reset; 550 551 /**< Obtain firmware status */ 552 rawdev_firmware_status_get_t firmware_status_get; 553 /**< Obtain firmware version information */ 554 rawdev_firmware_version_get_t firmware_version_get; 555 /**< Load firmware */ 556 rawdev_firmware_load_t firmware_load; 557 /**< Unload firmware */ 558 rawdev_firmware_unload_t firmware_unload; 559 560 /**< Device selftest function */ 561 rawdev_selftest_t dev_selftest; 562 }; 563 564 /** 565 * Allocates a new rawdev slot for an raw device and returns the pointer 566 * to that slot for the driver to use. 567 * 568 * @param name 569 * Unique identifier name for each device 570 * @param dev_private_size 571 * Size of private data memory allocated within rte_rawdev object. 572 * Set to 0 to disable internal memory allocation and allow for 573 * self-allocation. 574 * @param socket_id 575 * Socket to allocate resources on. 576 * @return 577 * - Slot in the rte_dev_devices array for a new device; 578 */ 579 struct rte_rawdev * 580 rte_rawdev_pmd_allocate(const char *name, size_t dev_private_size, 581 int socket_id); 582 583 /** 584 * Release the specified rawdev device. 585 * 586 * @param rawdev 587 * The *rawdev* pointer is the address of the *rte_rawdev* structure. 588 * @return 589 * - 0 on success, negative on error 590 */ 591 int 592 rte_rawdev_pmd_release(struct rte_rawdev *rawdev); 593 594 /** 595 * Creates a new raw device and returns the pointer to that device. 596 * 597 * @param name 598 * Pointer to a character array containing name of the device 599 * @param dev_private_size 600 * Size of raw PMDs private data 601 * @param socket_id 602 * Socket to allocate resources on. 603 * 604 * @return 605 * - Raw device pointer if device is successfully created. 606 * - NULL if device cannot be created. 607 */ 608 struct rte_rawdev * 609 rte_rawdev_pmd_init(const char *name, size_t dev_private_size, 610 int socket_id); 611 612 /** 613 * Destroy a raw device 614 * 615 * @param name 616 * Name of the device 617 * @return 618 * - 0 on success, negative on error 619 */ 620 int 621 rte_rawdev_pmd_uninit(const char *name); 622 623 #ifdef __cplusplus 624 } 625 #endif 626 627 #endif /* _RTE_RAWDEV_PMD_H_ */ 628