1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright 2014 6WIND S.A. 3 */ 4 5 #ifndef _RTE_DEVARGS_H_ 6 #define _RTE_DEVARGS_H_ 7 8 /** 9 * @file 10 * 11 * RTE devargs: list of devices and their user arguments 12 * 13 * This file stores a list of devices and their arguments given by 14 * the user when a DPDK application is started. These devices can be PCI 15 * devices or virtual devices. These devices are stored at startup in a 16 * list of rte_devargs structures. 17 */ 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 #include <stdio.h> 24 #include <sys/queue.h> 25 #include <rte_compat.h> 26 #include <rte_bus.h> 27 28 /** 29 * Bus type key in global devargs syntax. 30 * 31 * Legacy devargs parser doesn't use this key as bus type 32 * is resolved as first optional value separated by ":". 33 */ 34 #define RTE_DEVARGS_KEY_BUS "bus" 35 36 /** 37 * Class type key in global devargs syntax. 38 * 39 * Legacy devargs parser doesn't parse class type. PMD driver is 40 * encouraged to use this key to resolve class type. 41 */ 42 #define RTE_DEVARGS_KEY_CLASS "class" 43 44 /** 45 * Driver type key in global devargs syntax. 46 * 47 * Legacy devargs parser doesn't parse driver type. PMD driver is 48 * encouraged to use this key to resolve driver type. 49 */ 50 #define RTE_DEVARGS_KEY_DRIVER "driver" 51 52 /** 53 * Type of generic device 54 */ 55 enum rte_devtype { 56 RTE_DEVTYPE_ALLOWED, 57 RTE_DEVTYPE_BLOCKED, 58 RTE_DEVTYPE_VIRTUAL, 59 }; 60 61 /* Backwards compatibility will be removed later */ 62 #define RTE_DEVTYPE_WHITELISTED_PCI \ 63 RTE_DEPRECATED(RTE_DEVTYPE_WHITELISTED_PCI) RTE_DEVTYPE_ALLOWED 64 #define RTE_DEVTYPE_BLACKLISTED_PCI \ 65 RTE_DEPRECATED(RTE_DEVTYPE_BLACKLISTED_PCI) RTE_DEVTYPE_BLOCKED 66 67 /** 68 * Structure that stores a device given by the user with its arguments 69 * 70 * A user device is a physical or a virtual device given by the user to 71 * the DPDK application at startup through command line arguments. 72 * 73 * The structure stores the configuration of the device, its PCI 74 * identifier if it's a PCI device or the driver name if it's a virtual 75 * device. 76 */ 77 struct rte_devargs { 78 /** Next in list. */ 79 TAILQ_ENTRY(rte_devargs) next; 80 /** Type of device. */ 81 enum rte_devtype type; 82 /** Device policy. */ 83 enum rte_dev_policy policy; 84 /** Name of the device. */ 85 char name[RTE_DEV_NAME_MAX_LEN]; 86 RTE_STD_C11 87 union { 88 const char *args; /**< legacy name. */ 89 const char *drv_str; /**< driver-related part of device string. */ 90 }; 91 struct rte_bus *bus; /**< bus handle. */ 92 struct rte_class *cls; /**< class handle. */ 93 const char *bus_str; /**< bus-related part of device string. */ 94 const char *cls_str; /**< class-related part of device string. */ 95 char *data; /**< raw string including bus, class and driver parts. */ 96 }; 97 98 /** 99 * Parse a device string. 100 * 101 * Verify that a bus is capable of handling the device passed 102 * in argument. Store which bus will handle the device, its name 103 * and the eventual device parameters. 104 * 105 * The syntax is: 106 * 107 * bus:device_identifier,arg1=val1,arg2=val2 108 * 109 * where "bus:" is the bus name followed by any character separator. 110 * The bus name is optional. If no bus name is specified, each bus 111 * will attempt to recognize the device identifier. The first one 112 * to succeed will be used. 113 * 114 * Examples: 115 * 116 * pci:0000:05.00.0,arg=val 117 * 05.00.0,arg=val 118 * vdev:net_ring0 119 * 120 * @param da 121 * The devargs structure holding the device information. 122 * 123 * @param dev 124 * String describing a device. 125 * 126 * @return 127 * - 0 on success. 128 * - Negative errno on error. 129 */ 130 int 131 rte_devargs_parse(struct rte_devargs *da, const char *dev); 132 133 /** 134 * Parse a device string. 135 * 136 * Verify that a bus is capable of handling the device passed 137 * in argument. Store which bus will handle the device, its name 138 * and the eventual device parameters. 139 * 140 * The device string is built with a printf-like syntax. 141 * 142 * The syntax is: 143 * 144 * bus:device_identifier,arg1=val1,arg2=val2 145 * 146 * where "bus:" is the bus name followed by any character separator. 147 * The bus name is optional. If no bus name is specified, each bus 148 * will attempt to recognize the device identifier. The first one 149 * to succeed will be used. 150 * 151 * Examples: 152 * 153 * pci:0000:05.00.0,arg=val 154 * 05.00.0,arg=val 155 * vdev:net_ring0 156 * 157 * @param da 158 * The devargs structure holding the device information. 159 * @param format 160 * Format string describing a device. 161 * 162 * @return 163 * - 0 on success. 164 * - Negative errno on error. 165 */ 166 int 167 rte_devargs_parsef(struct rte_devargs *da, 168 const char *format, ...) 169 __rte_format_printf(2, 0); 170 171 /** 172 * Free resources in devargs. 173 * 174 * @param da 175 * The devargs structure holding the device information. 176 */ 177 __rte_experimental 178 void 179 rte_devargs_reset(struct rte_devargs *da); 180 181 /** 182 * Insert an rte_devargs in the global list. 183 * 184 * @param da 185 * The devargs structure to insert. 186 * If a devargs for the same device is already inserted, 187 * it will be updated and returned. It means *da pointer can change. 188 * 189 * @return 190 * - 0 on success 191 * - Negative on error. 192 */ 193 int 194 rte_devargs_insert(struct rte_devargs **da); 195 196 /** 197 * Add a device to the user device list 198 * See rte_devargs_parse() for details. 199 * 200 * @param devtype 201 * The type of the device. 202 * @param devargs_str 203 * The arguments as given by the user. 204 * 205 * @return 206 * - 0 on success 207 * - A negative value on error 208 */ 209 int rte_devargs_add(enum rte_devtype devtype, const char *devargs_str); 210 211 /** 212 * Remove a device from the user device list. 213 * Its resources are freed. 214 * If the devargs cannot be found, nothing happens. 215 * 216 * @param devargs 217 * The instance or a copy of devargs to remove. 218 * 219 * @return 220 * 0 on success. 221 * <0 on error. 222 * >0 if the devargs was not within the user device list. 223 */ 224 int rte_devargs_remove(struct rte_devargs *devargs); 225 226 /** 227 * Count the number of user devices of a specified type 228 * 229 * @param devtype 230 * The type of the devices to counted. 231 * 232 * @return 233 * The number of devices. 234 */ 235 unsigned int 236 rte_devargs_type_count(enum rte_devtype devtype); 237 238 /** 239 * This function dumps the list of user device and their arguments. 240 * 241 * @param f 242 * A pointer to a file for output 243 */ 244 void rte_devargs_dump(FILE *f); 245 246 /** 247 * Find next rte_devargs matching the provided bus name. 248 * 249 * @param busname 250 * Limit the iteration to devargs related to buses 251 * matching this name. 252 * Will return any next rte_devargs if NULL. 253 * 254 * @param start 255 * Starting iteration point. The iteration will start at 256 * the first rte_devargs if NULL. 257 * 258 * @return 259 * Next rte_devargs entry matching the requested bus, 260 * NULL if there is none. 261 */ 262 struct rte_devargs * 263 rte_devargs_next(const char *busname, const struct rte_devargs *start); 264 265 /** 266 * Iterate over all rte_devargs for a specific bus. 267 */ 268 #define RTE_EAL_DEVARGS_FOREACH(busname, da) \ 269 for (da = rte_devargs_next(busname, NULL); \ 270 da != NULL; \ 271 da = rte_devargs_next(busname, da)) \ 272 273 #ifdef __cplusplus 274 } 275 #endif 276 277 #endif /* _RTE_DEVARGS_H_ */ 278