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