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