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