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