lib/librte_eal/common/include/rte_dev.h

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