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