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