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