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