drivers/bus/auxiliary/rte_bus_auxiliary.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright (c) 2021 NVIDIA Corporation & Affiliates
   3  */
   4
   5 #ifndef RTE_BUS_AUXILIARY_H
   6 #define RTE_BUS_AUXILIARY_H
   7
   8 /**
   9  * @file
  10  *
  11  * Auxiliary Bus Interface.
  12  */
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 #include <stdio.h>
  19 #include <stdlib.h>
  20 #include <limits.h>
  21 #include <errno.h>
  22 #include <stdint.h>
  23 #include <inttypes.h>
  24
  25 #include <rte_debug.h>
  26 #include <rte_interrupts.h>
  27 #include <rte_dev.h>
  28 #include <rte_bus.h>
  29 #include <rte_kvargs.h>
  30
  31 #define RTE_BUS_AUXILIARY_NAME "auxiliary"
  32
  33 /* Forward declarations */
  34 struct rte_auxiliary_driver;
  35 struct rte_auxiliary_bus;
  36 struct rte_auxiliary_device;
  37
  38 /**
  39  * Match function for the driver to decide if device can be handled.
  40  *
  41  * @param name
  42  *   Pointer to the auxiliary device name.
  43  * @return
  44  *   Whether the driver can handle the auxiliary device.
  45  */
  46 typedef bool(rte_auxiliary_match_t)(const char *name);
  47
  48 /**
  49  * Initialization function for the driver called during auxiliary probing.
  50  *
  51  * @param drv
  52  *   Pointer to the auxiliary driver.
  53  * @param dev
  54  *   Pointer to the auxiliary device.
  55  * @return
  56  *   - 0 On success.
  57  *   - Negative value and rte_errno is set otherwise.
  58  */
  59 typedef int(rte_auxiliary_probe_t)(struct rte_auxiliary_driver *drv,
  60                                     struct rte_auxiliary_device *dev);
  61
  62 /**
  63  * Uninitialization function for the driver called during hotplugging.
  64  *
  65  * @param dev
  66  *   Pointer to the auxiliary device.
  67  * @return
  68  *   - 0 On success.
  69  *   - Negative value and rte_errno is set otherwise.
  70  */
  71 typedef int (rte_auxiliary_remove_t)(struct rte_auxiliary_device *dev);
  72
  73 /**
  74  * Driver-specific DMA mapping. After a successful call the device
  75  * will be able to read/write from/to this segment.
  76  *
  77  * @param dev
  78  *   Pointer to the auxiliary device.
  79  * @param addr
  80  *   Starting virtual address of memory to be mapped.
  81  * @param iova
  82  *   Starting IOVA address of memory to be mapped.
  83  * @param len
  84  *   Length of memory segment being mapped.
  85  * @return
  86  *   - 0 On success.
  87  *   - Negative value and rte_errno is set otherwise.
  88  */
  89 typedef int (rte_auxiliary_dma_map_t)(struct rte_auxiliary_device *dev,
  90                                        void *addr, uint64_t iova, size_t len);
  91
  92 /**
  93  * Driver-specific DMA un-mapping. After a successful call the device
  94  * will not be able to read/write from/to this segment.
  95  *
  96  * @param dev
  97  *   Pointer to the auxiliary device.
  98  * @param addr
  99  *   Starting virtual address of memory to be unmapped.
 100  * @param iova
 101  *   Starting IOVA address of memory to be unmapped.
 102  * @param len
 103  *   Length of memory segment being unmapped.
 104  * @return
 105  *   - 0 On success.
 106  *   - Negative value and rte_errno is set otherwise.
 107  */
 108 typedef int (rte_auxiliary_dma_unmap_t)(struct rte_auxiliary_device *dev,
 109                                          void *addr, uint64_t iova, size_t len);
 110
 111 /**
 112  * A structure describing an auxiliary device.
 113  */
 114 struct rte_auxiliary_device {
 115         RTE_TAILQ_ENTRY(rte_auxiliary_device) next; /**< Next probed device. */
 116         struct rte_device device;                 /**< Inherit core device */
 117         char name[RTE_DEV_NAME_MAX_LEN + 1];      /**< ASCII device name */
 118         struct rte_intr_handle *intr_handle;       /**< Interrupt handle */
 119         struct rte_auxiliary_driver *driver;      /**< Device driver */
 120 };
 121
 122 /**
 123  * A structure describing an auxiliary driver.
 124  */
 125 struct rte_auxiliary_driver {
 126         RTE_TAILQ_ENTRY(rte_auxiliary_driver) next; /**< Next in list. */
 127         struct rte_driver driver;             /**< Inherit core driver. */
 128         struct rte_auxiliary_bus *bus;        /**< Auxiliary bus reference. */
 129         rte_auxiliary_match_t *match;         /**< Device match function. */
 130         rte_auxiliary_probe_t *probe;         /**< Device probe function. */
 131         rte_auxiliary_remove_t *remove;       /**< Device remove function. */
 132         rte_auxiliary_dma_map_t *dma_map;     /**< Device DMA map function. */
 133         rte_auxiliary_dma_unmap_t *dma_unmap; /**< Device DMA unmap function. */
 134         uint32_t drv_flags;                   /**< Flags RTE_AUXILIARY_DRV_*. */
 135 };
 136
 137 /**
 138  * @internal
 139  * Helper macro for drivers that need to convert to struct rte_auxiliary_device.
 140  */
 141 #define RTE_DEV_TO_AUXILIARY(ptr) \
 142         container_of(ptr, struct rte_auxiliary_device, device)
 143
 144 #define RTE_DEV_TO_AUXILIARY_CONST(ptr) \
 145         container_of(ptr, const struct rte_auxiliary_device, device)
 146
 147 #define RTE_ETH_DEV_TO_AUXILIARY(eth_dev) \
 148         RTE_DEV_TO_AUXILIARY((eth_dev)->device)
 149
 150 /** Device driver needs IOVA as VA and cannot work with IOVA as PA */
 151 #define RTE_AUXILIARY_DRV_NEED_IOVA_AS_VA 0x002
 152
 153 /**
 154  * Register an auxiliary driver.
 155  *
 156  * @warning
 157  * @b EXPERIMENTAL: this API may change without prior notice.
 158  *
 159  * @param driver
 160  *   A pointer to a rte_auxiliary_driver structure describing the driver
 161  *   to be registered.
 162  */
 163 __rte_experimental
 164 void rte_auxiliary_register(struct rte_auxiliary_driver *driver);
 165
 166 /** Helper for auxiliary device registration from driver instance */
 167 #define RTE_PMD_REGISTER_AUXILIARY(nm, auxiliary_drv) \
 168         RTE_INIT(auxiliaryinitfn_ ##nm) \
 169         { \
 170                 (auxiliary_drv).driver.name = RTE_STR(nm); \
 171                 rte_auxiliary_register(&(auxiliary_drv)); \
 172         } \
 173         RTE_PMD_EXPORT_NAME(nm, __COUNTER__)
 174
 175 /**
 176  * Unregister an auxiliary driver.
 177  *
 178  * @warning
 179  * @b EXPERIMENTAL: this API may change without prior notice.
 180  *
 181  * @param driver
 182  *   A pointer to a rte_auxiliary_driver structure describing the driver
 183  *   to be unregistered.
 184  */
 185 __rte_experimental
 186 void rte_auxiliary_unregister(struct rte_auxiliary_driver *driver);
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif /* RTE_BUS_AUXILIARY_H */