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