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