lib/eal/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 typedef 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  */
  54 enum 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  */
  68 struct 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  */
  77 struct 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  */
  92 struct 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  */
 109 int 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  */
 127 int 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  */
 141 int 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  */
 156 int 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  */
 169 int 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  */
 190 typedef 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) \
 195 static 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) \
 201 static const char DRV_EXP_TAG(name, pci_tbl_export)[] __rte_used = \
 202 RTE_STR(table)
 203
 204 #define RTE_PMD_REGISTER_PARAM_STRING(name, str) \
 205 static 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) \
 230 static 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  */
 238 struct 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  */
 276 typedef 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
 301 int
 302 rte_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
 321 struct rte_device *
 322 rte_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
 354 int
 355 rte_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
 379 int
 380 rte_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
 397 void
 398 rte_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
 412 int
 413 rte_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
 426 int
 427 rte_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
 440 int
 441 rte_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
 454 int
 455 rte_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
 478 int
 479 rte_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
 502 int
 503 rte_dev_dma_unmap(struct rte_device *dev, void *addr, uint64_t iova,
 504                   size_t len);
 505
 506 #endif /* _RTE_DEV_H_ */