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