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