1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2014 6WIND S.A. 3 */ 4 5 #ifndef _RTE_DEV_H_ 6 #define _RTE_DEV_H_ 7 8 /** 9 * @file 10 * 11 * RTE PMD Registration Interface 12 * 13 * This file manages the list of device drivers. 14 */ 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #include <stdio.h> 21 22 #include <rte_config.h> 23 #include <rte_common.h> 24 #include <rte_compat.h> 25 #include <rte_log.h> 26 27 struct rte_bus; 28 struct rte_devargs; 29 struct rte_device; 30 struct rte_driver; 31 32 /** 33 * The device event type. 34 */ 35 enum rte_dev_event_type { 36 RTE_DEV_EVENT_ADD, /**< device being added */ 37 RTE_DEV_EVENT_REMOVE, /**< device being removed */ 38 RTE_DEV_EVENT_MAX /**< max value of this enum */ 39 }; 40 41 typedef void (*rte_dev_event_cb_fn)(const char *device_name, 42 enum rte_dev_event_type event, 43 void *cb_arg); 44 45 /* Macros to check for invalid function pointers */ 46 #define RTE_FUNC_PTR_OR_ERR_RET(func, retval) RTE_DEPRECATED(RTE_FUNC_PTR_OR_ERR_RET) \ 47 do { \ 48 if ((func) == NULL) \ 49 return retval; \ 50 } while (0) 51 52 #define RTE_FUNC_PTR_OR_RET(func) RTE_DEPRECATED(RTE_FUNC_PTR_OR_RET) \ 53 do { \ 54 if ((func) == NULL) \ 55 return; \ 56 } while (0) 57 58 /** 59 * Device policies. 60 */ 61 enum rte_dev_policy { 62 RTE_DEV_ALLOWED, 63 RTE_DEV_BLOCKED, 64 }; 65 66 /** 67 * A generic memory resource representation. 68 */ 69 struct rte_mem_resource { 70 uint64_t phys_addr; /**< Physical address, 0 if not resource. */ 71 uint64_t len; /**< Length of the resource. */ 72 void *addr; /**< Virtual address, NULL when not mapped. */ 73 }; 74 75 /** 76 * Retrieve a driver name. 77 * 78 * @param driver 79 * A pointer to a driver structure. 80 * @return 81 * A pointer to the driver name string. 82 */ 83 const char * 84 rte_driver_name(const struct rte_driver *driver); 85 86 /** 87 * Retrieve a device bus. 88 * 89 * @param dev 90 * A pointer to a device structure. 91 * @return 92 * A pointer to this device bus. 93 */ 94 const struct rte_bus * 95 rte_dev_bus(const struct rte_device *dev); 96 97 /** 98 * Retrieve bus specific information for a device. 99 * 100 * @param dev 101 * A pointer to a device structure. 102 * @return 103 * A string describing this device or NULL if none is available. 104 */ 105 const char * 106 rte_dev_bus_info(const struct rte_device *dev); 107 108 /** 109 * Retrieve a device arguments. 110 * 111 * @param dev 112 * A pointer to a device structure. 113 * @return 114 * A pointer to this device devargs. 115 */ 116 const struct rte_devargs * 117 rte_dev_devargs(const struct rte_device *dev); 118 119 /** 120 * Retrieve a device driver. 121 * 122 * @param dev 123 * A pointer to a device structure. 124 * @return 125 * A pointer to this device driver. 126 */ 127 const struct rte_driver * 128 rte_dev_driver(const struct rte_device *dev); 129 130 /** 131 * Retrieve a device name. 132 * 133 * @param dev 134 * A pointer to a device structure. 135 * @return 136 * A pointer to this device name. 137 */ 138 const char * 139 rte_dev_name(const struct rte_device *dev); 140 141 /** 142 * Retrieve a device numa node. 143 * 144 * @param dev 145 * A pointer to a device structure. 146 * @return 147 * A pointer to this device numa node. 148 */ 149 int 150 rte_dev_numa_node(const struct rte_device *dev); 151 152 /* 153 * Internal identifier length 154 * Sufficiently large to allow for UUID or PCI address 155 */ 156 #define RTE_DEV_NAME_MAX_LEN 64 157 158 /** 159 * Query status of a device. 160 * 161 * @param dev 162 * Generic device pointer. 163 * @return 164 * (int)true if already probed successfully, 0 otherwise. 165 */ 166 int rte_dev_is_probed(const struct rte_device *dev); 167 168 /** 169 * Hotplug add a given device to a specific bus. 170 * 171 * In multi-process, it will request other processes to add the same device. 172 * A failure, in any process, will rollback the action 173 * 174 * @param busname 175 * The bus name the device is added to. 176 * @param devname 177 * The device name. Based on this device name, eal will identify a driver 178 * capable of handling it and pass it to the driver probing function. 179 * @param drvargs 180 * Device arguments to be passed to the driver. 181 * @return 182 * 0 on success, negative on error. 183 */ 184 int rte_eal_hotplug_add(const char *busname, const char *devname, 185 const char *drvargs); 186 187 /** 188 * Add matching devices. 189 * 190 * In multi-process, it will request other processes to add the same device. 191 * A failure, in any process, will rollback the action 192 * 193 * @param devargs 194 * Device arguments including bus, class and driver properties. 195 * @return 196 * 0 on success, negative on error. 197 */ 198 int rte_dev_probe(const char *devargs); 199 200 /** 201 * Hotplug remove a given device from a specific bus. 202 * 203 * In multi-process, it will request other processes to remove the same device. 204 * A failure, in any process, will rollback the action 205 * 206 * @param busname 207 * The bus name the device is removed from. 208 * @param devname 209 * The device name being removed. 210 * @return 211 * 0 on success, negative on error. 212 */ 213 int rte_eal_hotplug_remove(const char *busname, const char *devname); 214 215 /** 216 * Remove one device. 217 * 218 * In multi-process, it will request other processes to remove the same device. 219 * A failure, in any process, will rollback the action 220 * 221 * @param dev 222 * Data structure of the device to remove. 223 * @return 224 * 0 on success, negative on error. 225 */ 226 int rte_dev_remove(struct rte_device *dev); 227 228 /** 229 * Device comparison function. 230 * 231 * This type of function is used to compare an rte_device with arbitrary 232 * data. 233 * 234 * @param dev 235 * Device handle. 236 * 237 * @param data 238 * Data to compare against. The type of this parameter is determined by 239 * the kind of comparison performed by the function. 240 * 241 * @return 242 * 0 if the device matches the data. 243 * !0 if the device does not match. 244 * <0 if ordering is possible and the device is lower than the data. 245 * >0 if ordering is possible and the device is greater than the data. 246 */ 247 typedef int (*rte_dev_cmp_t)(const struct rte_device *dev, const void *data); 248 249 #define RTE_PMD_EXPORT_NAME_ARRAY(n, idx) n##idx[] 250 251 #define RTE_PMD_EXPORT_NAME(name, idx) \ 252 static const char RTE_PMD_EXPORT_NAME_ARRAY(this_pmd_name, idx) \ 253 __rte_used = RTE_STR(name) 254 255 #define DRV_EXP_TAG(name, tag) __##name##_##tag 256 257 #define RTE_PMD_REGISTER_PCI_TABLE(name, table) \ 258 static const char DRV_EXP_TAG(name, pci_tbl_export)[] __rte_used = \ 259 RTE_STR(table) 260 261 #define RTE_PMD_REGISTER_PARAM_STRING(name, str) \ 262 static const char DRV_EXP_TAG(name, param_string_export)[] \ 263 __rte_used = str 264 265 /** 266 * Advertise the list of kernel modules required to run this driver 267 * 268 * This string lists the kernel modules required for the devices 269 * associated to a PMD. The format of each line of the string is: 270 * "<device-pattern> <kmod-expression>". 271 * 272 * The possible formats for the device pattern are: 273 * "*" all devices supported by this driver 274 * "pci:*" all PCI devices supported by this driver 275 * "pci:v8086:d*:sv*:sd*" all PCI devices supported by this driver 276 * whose vendor id is 0x8086. 277 * 278 * The format of the kernel modules list is a parenthesized expression 279 * containing logical-and (&) and logical-or (|). 280 * 281 * The device pattern and the kmod expression are separated by a space. 282 * 283 * Example: 284 * - "* igb_uio | uio_pci_generic | vfio" 285 */ 286 #define RTE_PMD_REGISTER_KMOD_DEP(name, str) \ 287 static const char DRV_EXP_TAG(name, kmod_dep_export)[] \ 288 __rte_used = str 289 290 /** 291 * Iteration context. 292 * 293 * This context carries over the current iteration state. 294 */ 295 struct rte_dev_iterator { 296 const char *dev_str; /**< device string. */ 297 const char *bus_str; /**< bus-related part of device string. */ 298 const char *cls_str; /**< class-related part of device string. */ 299 struct rte_bus *bus; /**< bus handle. */ 300 struct rte_class *cls; /**< class handle. */ 301 struct rte_device *device; /**< current position. */ 302 void *class_device; /**< additional specialized context. */ 303 }; 304 305 /** 306 * Device iteration function. 307 * 308 * Find the next device matching properties passed in parameters. 309 * The function takes an additional ``start`` parameter, that is 310 * used as starting context when relevant. 311 * 312 * The function returns the current element in the iteration. 313 * This return value will potentially be used as a start parameter 314 * in subsequent calls to the function. 315 * 316 * The additional iterator parameter is only there if a specific 317 * implementation needs additional context. It must not be modified by 318 * the iteration function itself. 319 * 320 * @param start 321 * Starting iteration context. 322 * 323 * @param devstr 324 * Device description string. 325 * 326 * @param it 327 * Device iterator. 328 * 329 * @return 330 * The address of the current element matching the device description 331 * string. 332 */ 333 typedef void *(*rte_dev_iterate_t)(const void *start, 334 const char *devstr, 335 const struct rte_dev_iterator *it); 336 337 /** 338 * Initializes a device iterator. 339 * 340 * This iterator allows accessing a list of devices matching a criteria. 341 * The device matching is made among all buses and classes currently registered, 342 * filtered by the device description given as parameter. 343 * 344 * This function will not allocate any memory. It is safe to stop the 345 * iteration at any moment and let the iterator go out of context. 346 * 347 * @param it 348 * Device iterator handle. 349 * 350 * @param str 351 * Device description string. 352 * 353 * @return 354 * 0 on successful initialization. 355 * <0 on error. 356 */ 357 __rte_experimental 358 int 359 rte_dev_iterator_init(struct rte_dev_iterator *it, const char *str); 360 361 /** 362 * Iterates on a device iterator. 363 * 364 * Generates a new rte_device handle corresponding to the next element 365 * in the list described in comprehension by the iterator. 366 * 367 * The next object is returned, and the iterator is updated. 368 * 369 * @param it 370 * Device iterator handle. 371 * 372 * @return 373 * An rte_device handle if found. 374 * NULL if an error occurred (rte_errno is set). 375 * NULL if no device could be found (rte_errno is not set). 376 */ 377 __rte_experimental 378 struct rte_device * 379 rte_dev_iterator_next(struct rte_dev_iterator *it); 380 381 #define RTE_DEV_FOREACH(dev, devstr, it) \ 382 for (rte_dev_iterator_init(it, devstr), \ 383 dev = rte_dev_iterator_next(it); \ 384 dev != NULL; \ 385 dev = rte_dev_iterator_next(it)) 386 387 /** 388 * @warning 389 * @b EXPERIMENTAL: this API may change without prior notice 390 * 391 * It registers the callback for the specific device. 392 * Multiple callbacks can be registered at the same time. 393 * 394 * @param device_name 395 * The device name, that is the param name of the struct rte_device, 396 * null value means for all devices. 397 * @param cb_fn 398 * callback address. 399 * @param cb_arg 400 * address of parameter for callback. 401 * 402 * @return 403 * - On success, zero. 404 * - On failure, a negative value. 405 */ 406 __rte_experimental 407 int 408 rte_dev_event_callback_register(const char *device_name, 409 rte_dev_event_cb_fn cb_fn, 410 void *cb_arg); 411 412 /** 413 * @warning 414 * @b EXPERIMENTAL: this API may change without prior notice 415 * 416 * It unregisters the callback according to the specified device. 417 * 418 * @param device_name 419 * The device name, that is the param name of the struct rte_device, 420 * null value means for all devices and their callbacks. 421 * @param cb_fn 422 * callback address. 423 * @param cb_arg 424 * address of parameter for callback, (void *)-1 means to remove all 425 * registered which has the same callback address. 426 * 427 * @return 428 * - On success, return the number of callback entities removed. 429 * - On failure, a negative value. 430 */ 431 __rte_experimental 432 int 433 rte_dev_event_callback_unregister(const char *device_name, 434 rte_dev_event_cb_fn cb_fn, 435 void *cb_arg); 436 437 /** 438 * @warning 439 * @b EXPERIMENTAL: this API may change without prior notice 440 * 441 * Executes all the user application registered callbacks for 442 * the specific device. 443 * 444 * @param device_name 445 * The device name. 446 * @param event 447 * the device event type. 448 */ 449 __rte_experimental 450 void 451 rte_dev_event_callback_process(const char *device_name, 452 enum rte_dev_event_type event); 453 454 /** 455 * @warning 456 * @b EXPERIMENTAL: this API may change without prior notice 457 * 458 * Start the device event monitoring. 459 * 460 * @return 461 * - On success, zero. 462 * - On failure, a negative value. 463 */ 464 __rte_experimental 465 int 466 rte_dev_event_monitor_start(void); 467 468 /** 469 * @warning 470 * @b EXPERIMENTAL: this API may change without prior notice 471 * 472 * Stop the device event monitoring. 473 * 474 * @return 475 * - On success, zero. 476 * - On failure, a negative value. 477 */ 478 __rte_experimental 479 int 480 rte_dev_event_monitor_stop(void); 481 482 /** 483 * @warning 484 * @b EXPERIMENTAL: this API may change without prior notice 485 * 486 * Enable hotplug handling for devices. 487 * 488 * @return 489 * - On success, zero. 490 * - On failure, a negative value. 491 */ 492 __rte_experimental 493 int 494 rte_dev_hotplug_handle_enable(void); 495 496 /** 497 * @warning 498 * @b EXPERIMENTAL: this API may change without prior notice 499 * 500 * Disable hotplug handling for devices. 501 * 502 * @return 503 * - On success, zero. 504 * - On failure, a negative value. 505 */ 506 __rte_experimental 507 int 508 rte_dev_hotplug_handle_disable(void); 509 510 /** 511 * Device level DMA map function. 512 * After a successful call, the memory segment will be mapped to the 513 * given device. 514 * 515 * @note: Memory must be registered in advance using rte_extmem_* APIs. 516 * 517 * @param dev 518 * Device pointer. 519 * @param addr 520 * Virtual address to map. 521 * @param iova 522 * IOVA address to map. 523 * @param len 524 * Length of the memory segment being mapped. 525 * 526 * @return 527 * 0 if mapping was successful. 528 * Negative value and rte_errno is set otherwise. 529 */ 530 __rte_experimental 531 int 532 rte_dev_dma_map(struct rte_device *dev, void *addr, uint64_t iova, size_t len); 533 534 /** 535 * Device level DMA unmap function. 536 * After a successful call, the memory segment will no longer be 537 * accessible by the given device. 538 * 539 * @note: Memory must be registered in advance using rte_extmem_* APIs. 540 * 541 * @param dev 542 * Device pointer. 543 * @param addr 544 * Virtual address to unmap. 545 * @param iova 546 * IOVA address to unmap. 547 * @param len 548 * Length of the memory segment being mapped. 549 * 550 * @return 551 * 0 if un-mapping was successful. 552 * Negative value and rte_errno is set otherwise. 553 */ 554 __rte_experimental 555 int 556 rte_dev_dma_unmap(struct rte_device *dev, void *addr, uint64_t iova, 557 size_t len); 558 559 #ifdef __cplusplus 560 } 561 #endif 562 563 #endif /* _RTE_DEV_H_ */ 564