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