1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright 2016 NXP 3 */ 4 5 #ifndef _RTE_BUS_H_ 6 #define _RTE_BUS_H_ 7 8 /** 9 * @file 10 * 11 * DPDK device bus interface 12 * 13 * This file exposes API and interfaces for bus abstraction 14 * over the devices and drivers in EAL. 15 */ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <stdio.h> 22 #include <sys/queue.h> 23 24 #include <rte_log.h> 25 #include <rte_dev.h> 26 27 /** Double linked list of buses */ 28 TAILQ_HEAD(rte_bus_list, rte_bus); 29 30 31 /** 32 * IOVA mapping mode. 33 * 34 * IOVA mapping mode is iommu programming mode of a device. 35 * That device (for example: IOMMU backed DMA device) based 36 * on rte_iova_mode will generate physical or virtual address. 37 * 38 */ 39 enum rte_iova_mode { 40 RTE_IOVA_DC = 0, /* Don't care mode */ 41 RTE_IOVA_PA = (1 << 0), /* DMA using physical address */ 42 RTE_IOVA_VA = (1 << 1) /* DMA using virtual address */ 43 }; 44 45 /** 46 * Bus specific scan for devices attached on the bus. 47 * For each bus object, the scan would be responsible for finding devices and 48 * adding them to its private device list. 49 * 50 * A bus should mandatorily implement this method. 51 * 52 * @return 53 * 0 for successful scan 54 * <0 for unsuccessful scan with error value 55 */ 56 typedef int (*rte_bus_scan_t)(void); 57 58 /** 59 * Implementation specific probe function which is responsible for linking 60 * devices on that bus with applicable drivers. 61 * 62 * This is called while iterating over each registered bus. 63 * 64 * @return 65 * 0 for successful probe 66 * !0 for any error while probing 67 */ 68 typedef int (*rte_bus_probe_t)(void); 69 70 /** 71 * Device iterator to find a device on a bus. 72 * 73 * This function returns an rte_device if one of those held by the bus 74 * matches the data passed as parameter. 75 * 76 * If the comparison function returns zero this function should stop iterating 77 * over any more devices. To continue a search the device of a previous search 78 * can be passed via the start parameter. 79 * 80 * @param cmp 81 * Comparison function. 82 * 83 * @param data 84 * Data to compare each device against. 85 * 86 * @param start 87 * starting point for the iteration 88 * 89 * @return 90 * The first device matching the data, NULL if none exists. 91 */ 92 typedef struct rte_device * 93 (*rte_bus_find_device_t)(const struct rte_device *start, rte_dev_cmp_t cmp, 94 const void *data); 95 96 /** 97 * Implementation specific probe function which is responsible for linking 98 * devices on that bus with applicable drivers. 99 * 100 * @param dev 101 * Device pointer that was returned by a previous call to find_device. 102 * 103 * @return 104 * 0 on success. 105 * !0 on error. 106 */ 107 typedef int (*rte_bus_plug_t)(struct rte_device *dev); 108 109 /** 110 * Implementation specific remove function which is responsible for unlinking 111 * devices on that bus from assigned driver. 112 * 113 * @param dev 114 * Device pointer that was returned by a previous call to find_device. 115 * 116 * @return 117 * 0 on success. 118 * !0 on error. 119 */ 120 typedef int (*rte_bus_unplug_t)(struct rte_device *dev); 121 122 /** 123 * Bus specific parsing function. 124 * Validates the syntax used in the textual representation of a device, 125 * If the syntax is valid and ``addr`` is not NULL, writes the bus-specific 126 * device representation to ``addr``. 127 * 128 * @param[in] name 129 * device textual description 130 * 131 * @param[out] addr 132 * device information location address, into which parsed info 133 * should be written. If NULL, nothing should be written, which 134 * is not an error. 135 * 136 * @return 137 * 0 if parsing was successful. 138 * !0 for any error. 139 */ 140 typedef int (*rte_bus_parse_t)(const char *name, void *addr); 141 142 /** 143 * Parse bus part of the device arguments. 144 * 145 * The field name of the struct rte_devargs will be set. 146 * 147 * @param da 148 * Pointer to the devargs to parse. 149 * 150 * @return 151 * 0 on successful parsing, otherwise rte_errno is set. 152 * -EINVAL: on parsing error. 153 * -ENODEV: if no key matching a device argument is specified. 154 * -E2BIG: device name is too long. 155 */ 156 typedef int (*rte_bus_devargs_parse_t)(struct rte_devargs *da); 157 158 /** 159 * Device level DMA map function. 160 * After a successful call, the memory segment will be mapped to the 161 * given device. 162 * 163 * @param dev 164 * Device pointer. 165 * @param addr 166 * Virtual address to map. 167 * @param iova 168 * IOVA address to map. 169 * @param len 170 * Length of the memory segment being mapped. 171 * 172 * @return 173 * 0 if mapping was successful. 174 * Negative value and rte_errno is set otherwise. 175 */ 176 typedef int (*rte_dev_dma_map_t)(struct rte_device *dev, void *addr, 177 uint64_t iova, size_t len); 178 179 /** 180 * Device level DMA unmap function. 181 * After a successful call, the memory segment will no longer be 182 * accessible by the given device. 183 * 184 * @param dev 185 * Device pointer. 186 * @param addr 187 * Virtual address to unmap. 188 * @param iova 189 * IOVA address to unmap. 190 * @param len 191 * Length of the memory segment being mapped. 192 * 193 * @return 194 * 0 if un-mapping was successful. 195 * Negative value and rte_errno is set otherwise. 196 */ 197 typedef int (*rte_dev_dma_unmap_t)(struct rte_device *dev, void *addr, 198 uint64_t iova, size_t len); 199 200 /** 201 * Implement a specific hot-unplug handler, which is responsible for 202 * handle the failure when device be hot-unplugged. When the event of 203 * hot-unplug be detected, it could call this function to handle 204 * the hot-unplug failure and avoid app crash. 205 * @param dev 206 * Pointer of the device structure. 207 * 208 * @return 209 * 0 on success. 210 * !0 on error. 211 */ 212 typedef int (*rte_bus_hot_unplug_handler_t)(struct rte_device *dev); 213 214 /** 215 * Implement a specific sigbus handler, which is responsible for handling 216 * the sigbus error which is either original memory error, or specific memory 217 * error that caused of device be hot-unplugged. When sigbus error be captured, 218 * it could call this function to handle sigbus error. 219 * @param failure_addr 220 * Pointer of the fault address of the sigbus error. 221 * 222 * @return 223 * 0 for success handle the sigbus for hot-unplug. 224 * 1 for not process it, because it is a generic sigbus error. 225 * -1 for failed to handle the sigbus for hot-unplug. 226 */ 227 typedef int (*rte_bus_sigbus_handler_t)(const void *failure_addr); 228 229 /** 230 * Bus scan policies 231 */ 232 enum rte_bus_scan_mode { 233 RTE_BUS_SCAN_UNDEFINED, 234 RTE_BUS_SCAN_ALLOWLIST, 235 RTE_BUS_SCAN_BLOCKLIST, 236 }; 237 238 /* Backwards compatibility will be removed */ 239 #define RTE_BUS_SCAN_WHITELIST \ 240 RTE_DEPRECATED(RTE_BUS_SCAN_WHITELIST) RTE_BUS_SCAN_ALLOWLIST 241 #define RTE_BUS_SCAN_BLACKLIST \ 242 RTE_DEPRECATED(RTE_BUS_SCAN_BLACKLIST) RTE_BUS_SCAN_BLOCKLIST 243 244 /** 245 * A structure used to configure bus operations. 246 */ 247 struct rte_bus_conf { 248 enum rte_bus_scan_mode scan_mode; /**< Scan policy. */ 249 }; 250 251 252 /** 253 * Get common iommu class of the all the devices on the bus. The bus may 254 * check that those devices are attached to iommu driver. 255 * If no devices are attached to the bus. The bus may return with don't care 256 * (_DC) value. 257 * Otherwise, The bus will return appropriate _pa or _va iova mode. 258 * 259 * @return 260 * enum rte_iova_mode value. 261 */ 262 typedef enum rte_iova_mode (*rte_bus_get_iommu_class_t)(void); 263 264 265 /** 266 * A structure describing a generic bus. 267 */ 268 struct rte_bus { 269 TAILQ_ENTRY(rte_bus) next; /**< Next bus object in linked list */ 270 const char *name; /**< Name of the bus */ 271 rte_bus_scan_t scan; /**< Scan for devices attached to bus */ 272 rte_bus_probe_t probe; /**< Probe devices on bus */ 273 rte_bus_find_device_t find_device; /**< Find a device on the bus */ 274 rte_bus_plug_t plug; /**< Probe single device for drivers */ 275 rte_bus_unplug_t unplug; /**< Remove single device from driver */ 276 rte_bus_parse_t parse; /**< Parse a device name */ 277 rte_bus_devargs_parse_t devargs_parse; /**< Parse bus devargs */ 278 rte_dev_dma_map_t dma_map; /**< DMA map for device in the bus */ 279 rte_dev_dma_unmap_t dma_unmap; /**< DMA unmap for device in the bus */ 280 struct rte_bus_conf conf; /**< Bus configuration */ 281 rte_bus_get_iommu_class_t get_iommu_class; /**< Get iommu class */ 282 rte_dev_iterate_t dev_iterate; /**< Device iterator. */ 283 rte_bus_hot_unplug_handler_t hot_unplug_handler; 284 /**< handle hot-unplug failure on the bus */ 285 rte_bus_sigbus_handler_t sigbus_handler; 286 /**< handle sigbus error on the bus */ 287 288 }; 289 290 /** 291 * Register a Bus handler. 292 * 293 * @param bus 294 * A pointer to a rte_bus structure describing the bus 295 * to be registered. 296 */ 297 void rte_bus_register(struct rte_bus *bus); 298 299 /** 300 * Unregister a Bus handler. 301 * 302 * @param bus 303 * A pointer to a rte_bus structure describing the bus 304 * to be unregistered. 305 */ 306 void rte_bus_unregister(struct rte_bus *bus); 307 308 /** 309 * Scan all the buses. 310 * 311 * @return 312 * 0 in case of success in scanning all buses 313 * !0 in case of failure to scan 314 */ 315 int rte_bus_scan(void); 316 317 /** 318 * For each device on the buses, perform a driver 'match' and call the 319 * driver-specific probe for device initialization. 320 * 321 * @return 322 * 0 for successful match/probe 323 * !0 otherwise 324 */ 325 int rte_bus_probe(void); 326 327 /** 328 * Dump information of all the buses registered with EAL. 329 * 330 * @param f 331 * A valid and open output stream handle 332 */ 333 void rte_bus_dump(FILE *f); 334 335 /** 336 * Bus comparison function. 337 * 338 * @param bus 339 * Bus under test. 340 * 341 * @param data 342 * Data to compare against. 343 * 344 * @return 345 * 0 if the bus matches the data. 346 * !0 if the bus does not match. 347 * <0 if ordering is possible and the bus is lower than the data. 348 * >0 if ordering is possible and the bus is greater than the data. 349 */ 350 typedef int (*rte_bus_cmp_t)(const struct rte_bus *bus, const void *data); 351 352 /** 353 * Bus iterator to find a particular bus. 354 * 355 * This function compares each registered bus to find one that matches 356 * the data passed as parameter. 357 * 358 * If the comparison function returns zero this function will stop iterating 359 * over any more buses. To continue a search the bus of a previous search can 360 * be passed via the start parameter. 361 * 362 * @param start 363 * Starting point for the iteration. 364 * 365 * @param cmp 366 * Comparison function. 367 * 368 * @param data 369 * Data to pass to comparison function. 370 * 371 * @return 372 * A pointer to a rte_bus structure or NULL in case no bus matches 373 */ 374 struct rte_bus *rte_bus_find(const struct rte_bus *start, rte_bus_cmp_t cmp, 375 const void *data); 376 377 /** 378 * Find the registered bus for a particular device. 379 */ 380 struct rte_bus *rte_bus_find_by_device(const struct rte_device *dev); 381 382 /** 383 * Find the registered bus for a given name. 384 */ 385 struct rte_bus *rte_bus_find_by_name(const char *busname); 386 387 388 /** 389 * Get the common iommu class of devices bound on to buses available in the 390 * system. RTE_IOVA_DC means that no preference has been expressed. 391 * 392 * @return 393 * enum rte_iova_mode value. 394 */ 395 enum rte_iova_mode rte_bus_get_iommu_class(void); 396 397 /** 398 * Helper for Bus registration. 399 * The constructor has higher priority than PMD constructors. 400 */ 401 #define RTE_REGISTER_BUS(nm, bus) \ 402 RTE_INIT_PRIO(businitfn_ ##nm, BUS) \ 403 {\ 404 (bus).name = RTE_STR(nm);\ 405 rte_bus_register(&bus); \ 406 } 407 408 #ifdef __cplusplus 409 } 410 #endif 411 412 #endif /* _RTE_BUS_H */ 413