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