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