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         char buffer[vsnprintf(NULL, 0, fmt, ap) + 1];
  55
  56         va_end(ap);
  57
  58         va_start(ap, fmt);
  59         vsnprintf(buffer, sizeof(buffer), fmt, ap);
  60         va_end(ap);
  61
  62         rte_log(RTE_LOG_ERR, RTE_LOGTYPE_PMD, "%s: %s", func_name, buffer);
  63 }
  64
  65 /*
  66  * Enable RTE_PMD_DEBUG_TRACE() when at least one component relying on the
  67  * RTE_*_RET() macros defined below is compiled in debug mode.
  68  */
  69 #if defined(RTE_LIBRTE_ETHDEV_DEBUG) || \
  70         defined(RTE_LIBRTE_CRYPTODEV_DEBUG) || \
  71         defined(RTE_LIBRTE_EVENTDEV_DEBUG)
  72 #define RTE_PMD_DEBUG_TRACE(...) \
  73         rte_pmd_debug_trace(__func__, __VA_ARGS__)
  74 #else
  75 #define RTE_PMD_DEBUG_TRACE(...) (void)0
  76 #endif
  77
  78 /* Macros for checking for restricting functions to primary instance only */
  79 #define RTE_PROC_PRIMARY_OR_ERR_RET(retval) do { \
  80         if (rte_eal_process_type() != RTE_PROC_PRIMARY) { \
  81                 RTE_PMD_DEBUG_TRACE("Cannot run in secondary processes\n"); \
  82                 return retval; \
  83         } \
  84 } while (0)
  85
  86 #define RTE_PROC_PRIMARY_OR_RET() do { \
  87         if (rte_eal_process_type() != RTE_PROC_PRIMARY) { \
  88                 RTE_PMD_DEBUG_TRACE("Cannot run in secondary processes\n"); \
  89                 return; \
  90         } \
  91 } while (0)
  92
  93 /* Macros to check for invalid function pointers */
  94 #define RTE_FUNC_PTR_OR_ERR_RET(func, retval) do { \
  95         if ((func) == NULL) { \
  96                 RTE_PMD_DEBUG_TRACE("Function not supported\n"); \
  97                 return retval; \
  98         } \
  99 } while (0)
 100
 101 #define RTE_FUNC_PTR_OR_RET(func) do { \
 102         if ((func) == NULL) { \
 103                 RTE_PMD_DEBUG_TRACE("Function not supported\n"); \
 104                 return; \
 105         } \
 106 } while (0)
 107
 108 /**
 109  * Device driver.
 110  */
 111 enum rte_kernel_driver {
 112         RTE_KDRV_UNKNOWN = 0,
 113         RTE_KDRV_IGB_UIO,
 114         RTE_KDRV_VFIO,
 115         RTE_KDRV_UIO_GENERIC,
 116         RTE_KDRV_NIC_UIO,
 117         RTE_KDRV_NONE,
 118 };
 119
 120 /**
 121  * Device policies.
 122  */
 123 enum rte_dev_policy {
 124         RTE_DEV_WHITELISTED,
 125         RTE_DEV_BLACKLISTED,
 126 };
 127
 128 /**
 129  * A generic memory resource representation.
 130  */
 131 struct rte_mem_resource {
 132         uint64_t phys_addr; /**< Physical address, 0 if not resource. */
 133         uint64_t len;       /**< Length of the resource. */
 134         void *addr;         /**< Virtual address, NULL when not mapped. */
 135 };
 136
 137 /**
 138  * A structure describing a device driver.
 139  */
 140 struct rte_driver {
 141         TAILQ_ENTRY(rte_driver) next;  /**< Next in list. */
 142         const char *name;                   /**< Driver name. */
 143         const char *alias;              /**< Driver alias. */
 144 };
 145
 146 /*
 147  * Internal identifier length
 148  * Sufficiently large to allow for UUID or PCI address
 149  */
 150 #define RTE_DEV_NAME_MAX_LEN 64
 151
 152 /**
 153  * A structure describing a generic device.
 154  */
 155 struct rte_device {
 156         TAILQ_ENTRY(rte_device) next; /**< Next device */
 157         const char *name;             /**< Device name */
 158         const struct rte_driver *driver;/**< Associated driver */
 159         int numa_node;                /**< NUMA node connection */
 160         struct rte_devargs *devargs;  /**< Device user arguments */
 161 };
 162
 163 /**
 164  * Attach a device to a registered driver.
 165  *
 166  * @param name
 167  *   The device name, that refers to a pci device (or some private
 168  *   way of designating a vdev device). Based on this device name, eal
 169  *   will identify a driver capable of handling it and pass it to the
 170  *   driver probing function.
 171  * @param devargs
 172  *   Device arguments to be passed to the driver.
 173  * @return
 174  *   0 on success, negative on error.
 175  */
 176 int rte_eal_dev_attach(const char *name, const char *devargs);
 177
 178 /**
 179  * Detach a device from its driver.
 180  *
 181  * @param dev
 182  *   A pointer to a rte_device structure.
 183  * @return
 184  *   0 on success, negative on error.
 185  */
 186 int rte_eal_dev_detach(struct rte_device *dev);
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice
 191  *
 192  * Hotplug add a given device to a specific bus.
 193  *
 194  * @param busname
 195  *   The bus name the device is added to.
 196  * @param devname
 197  *   The device name. Based on this device name, eal will identify a driver
 198  *   capable of handling it and pass it to the driver probing function.
 199  * @param devargs
 200  *   Device arguments to be passed to the driver.
 201  * @return
 202  *   0 on success, negative on error.
 203  */
 204 int __rte_experimental rte_eal_hotplug_add(const char *busname, const char *devname,
 205                         const char *devargs);
 206
 207 /**
 208  * @warning
 209  * @b EXPERIMENTAL: this API may change without prior notice
 210  *
 211  * Hotplug remove a given device from a specific bus.
 212  *
 213  * @param busname
 214  *   The bus name the device is removed from.
 215  * @param devname
 216  *   The device name being removed.
 217  * @return
 218  *   0 on success, negative on error.
 219  */
 220 int __rte_experimental rte_eal_hotplug_remove(const char *busname,
 221                                           const char *devname);
 222
 223 /**
 224  * Device comparison function.
 225  *
 226  * This type of function is used to compare an rte_device with arbitrary
 227  * data.
 228  *
 229  * @param dev
 230  *   Device handle.
 231  *
 232  * @param data
 233  *   Data to compare against. The type of this parameter is determined by
 234  *   the kind of comparison performed by the function.
 235  *
 236  * @return
 237  *   0 if the device matches the data.
 238  *   !0 if the device does not match.
 239  *   <0 if ordering is possible and the device is lower than the data.
 240  *   >0 if ordering is possible and the device is greater than the data.
 241  */
 242 typedef int (*rte_dev_cmp_t)(const struct rte_device *dev, const void *data);
 243
 244 #define RTE_PMD_EXPORT_NAME_ARRAY(n, idx) n##idx[]
 245
 246 #define RTE_PMD_EXPORT_NAME(name, idx) \
 247 static const char RTE_PMD_EXPORT_NAME_ARRAY(this_pmd_name, idx) \
 248 __attribute__((used)) = RTE_STR(name)
 249
 250 #define DRV_EXP_TAG(name, tag) __##name##_##tag
 251
 252 #define RTE_PMD_REGISTER_PCI_TABLE(name, table) \
 253 static const char DRV_EXP_TAG(name, pci_tbl_export)[] __attribute__((used)) = \
 254 RTE_STR(table)
 255
 256 #define RTE_PMD_REGISTER_PARAM_STRING(name, str) \
 257 static const char DRV_EXP_TAG(name, param_string_export)[] \
 258 __attribute__((used)) = str
 259
 260 /**
 261  * Advertise the list of kernel modules required to run this driver
 262  *
 263  * This string lists the kernel modules required for the devices
 264  * associated to a PMD. The format of each line of the string is:
 265  * "<device-pattern> <kmod-expression>".
 266  *
 267  * The possible formats for the device pattern are:
 268  *   "*"                     all devices supported by this driver
 269  *   "pci:*"                 all PCI devices supported by this driver
 270  *   "pci:v8086:d*:sv*:sd*"  all PCI devices supported by this driver
 271  *                           whose vendor id is 0x8086.
 272  *
 273  * The format of the kernel modules list is a parenthesed expression
 274  * containing logical-and (&) and logical-or (|).
 275  *
 276  * The device pattern and the kmod expression are separated by a space.
 277  *
 278  * Example:
 279  * - "* igb_uio | uio_pci_generic | vfio"
 280  */
 281 #define RTE_PMD_REGISTER_KMOD_DEP(name, str) \
 282 static const char DRV_EXP_TAG(name, kmod_dep_export)[] \
 283 __attribute__((used)) = str
 284
 285 #ifdef __cplusplus
 286 }
 287 #endif
 288
 289 /**
 290  * @warning
 291  * @b EXPERIMENTAL: this API may change without prior notice
 292  *
 293  * It registers the callback for the specific device.
 294  * Multiple callbacks cal be registered at the same time.
 295  *
 296  * @param device_name
 297  *  The device name, that is the param name of the struct rte_device,
 298  *  null value means for all devices.
 299  * @param cb_fn
 300  *  callback address.
 301  * @param cb_arg
 302  *  address of parameter for callback.
 303  *
 304  * @return
 305  *  - On success, zero.
 306  *  - On failure, a negative value.
 307  */
 308 int __rte_experimental
 309 rte_dev_event_callback_register(const char *device_name,
 310                                 rte_dev_event_cb_fn cb_fn,
 311                                 void *cb_arg);
 312
 313 /**
 314  * @warning
 315  * @b EXPERIMENTAL: this API may change without prior notice
 316  *
 317  * It unregisters the callback according to the specified device.
 318  *
 319  * @param device_name
 320  *  The device name, that is the param name of the struct rte_device,
 321  *  null value means for all devices and their callbacks.
 322  * @param cb_fn
 323  *  callback address.
 324  * @param cb_arg
 325  *  address of parameter for callback, (void *)-1 means to remove all
 326  *  registered which has the same callback address.
 327  *
 328  * @return
 329  *  - On success, return the number of callback entities removed.
 330  *  - On failure, a negative value.
 331  */
 332 int __rte_experimental
 333 rte_dev_event_callback_unregister(const char *device_name,
 334                                   rte_dev_event_cb_fn cb_fn,
 335                                   void *cb_arg);
 336
 337 /**
 338  * @warning
 339  * @b EXPERIMENTAL: this API may change without prior notice
 340  *
 341  * Start the device event monitoring.
 342  *
 343  * @return
 344  *   - On success, zero.
 345  *   - On failure, a negative value.
 346  */
 347 int __rte_experimental
 348 rte_dev_event_monitor_start(void);
 349
 350 /**
 351  * @warning
 352  * @b EXPERIMENTAL: this API may change without prior notice
 353  *
 354  * Stop the device event monitoring.
 355  *
 356  * @return
 357  *   - On success, zero.
 358  *   - On failure, a negative value.
 359  */
 360 int __rte_experimental
 361 rte_dev_event_monitor_stop(void);
 362
 363 #endif /* _RTE_DEV_H_ */