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 <rte_compat.h> 25 #include <rte_bus.h> 26 27 /** 28 * Bus type key in global devargs syntax. 29 * 30 * Legacy devargs parser doesn't use this key as bus type 31 * is resolved as first optional value separated by ":". 32 */ 33 #define RTE_DEVARGS_KEY_BUS "bus" 34 35 /** 36 * Class type key in global devargs syntax. 37 * 38 * Legacy devargs parser doesn't parse class type. PMD driver is 39 * encouraged to use this key to resolve class type. 40 */ 41 #define RTE_DEVARGS_KEY_CLASS "class" 42 43 /** 44 * Driver type key in global devargs syntax. 45 * 46 * Legacy devargs parser doesn't parse driver type. PMD driver is 47 * encouraged to use this key to resolve driver type. 48 */ 49 #define RTE_DEVARGS_KEY_DRIVER "driver" 50 51 /** 52 * Type of generic device 53 */ 54 enum rte_devtype { 55 RTE_DEVTYPE_ALLOWED, 56 RTE_DEVTYPE_BLOCKED, 57 RTE_DEVTYPE_VIRTUAL, 58 }; 59 60 /** 61 * Structure that stores a device given by the user with its arguments 62 * 63 * A user device is a physical or a virtual device given by the user to 64 * the DPDK application at startup through command line arguments. 65 * 66 * The structure stores the configuration of the device, its PCI 67 * identifier if it's a PCI device or the driver name if it's a virtual 68 * device. 69 */ 70 struct rte_devargs { 71 /** Next in list. */ 72 RTE_TAILQ_ENTRY(rte_devargs) next; 73 /** Type of device. */ 74 enum rte_devtype type; 75 /** Device policy. */ 76 enum rte_dev_policy policy; 77 /** Name of the device. */ 78 char name[RTE_DEV_NAME_MAX_LEN]; 79 RTE_STD_C11 80 union { 81 const char *args; /**< legacy name. */ 82 const char *drv_str; /**< driver-related part of device string. */ 83 }; 84 struct rte_bus *bus; /**< bus handle. */ 85 struct rte_class *cls; /**< class handle. */ 86 const char *bus_str; /**< bus-related part of device string. */ 87 const char *cls_str; /**< class-related part of device string. */ 88 char *data; /**< raw string including bus, class and driver parts. */ 89 }; 90 91 /** 92 * Parse a device string. 93 * 94 * Verify that a bus is capable of handling the device passed 95 * in argument. Store which bus will handle the device, its name 96 * and the eventual device parameters. 97 * 98 * The syntax is: 99 * 100 * bus:device_identifier,arg1=val1,arg2=val2 101 * 102 * where "bus:" is the bus name followed by any character separator. 103 * The bus name is optional. If no bus name is specified, each bus 104 * will attempt to recognize the device identifier. The first one 105 * to succeed will be used. 106 * 107 * Examples: 108 * 109 * pci:0000:05.00.0,arg=val 110 * 05.00.0,arg=val 111 * vdev:net_ring0 112 * 113 * @param da 114 * The devargs structure holding the device information. 115 * 116 * @param dev 117 * String describing a device. 118 * 119 * @return 120 * - 0 on success. 121 * - Negative errno on error. 122 */ 123 int 124 rte_devargs_parse(struct rte_devargs *da, const char *dev); 125 126 /** 127 * Parse a device string. 128 * 129 * Verify that a bus is capable of handling the device passed 130 * in argument. Store which bus will handle the device, its name 131 * and the eventual device parameters. 132 * 133 * The device string is built with a printf-like syntax. 134 * 135 * The syntax is: 136 * 137 * bus:device_identifier,arg1=val1,arg2=val2 138 * 139 * where "bus:" is the bus name followed by any character separator. 140 * The bus name is optional. If no bus name is specified, each bus 141 * will attempt to recognize the device identifier. The first one 142 * to succeed will be used. 143 * 144 * Examples: 145 * 146 * pci:0000:05.00.0,arg=val 147 * 05.00.0,arg=val 148 * vdev:net_ring0 149 * 150 * @param da 151 * The devargs structure holding the device information. 152 * @param format 153 * Format string describing a device. 154 * 155 * @return 156 * - 0 on success. 157 * - Negative errno on error. 158 */ 159 int 160 rte_devargs_parsef(struct rte_devargs *da, 161 const char *format, ...) 162 __rte_format_printf(2, 0); 163 164 /** 165 * Free resources in devargs. 166 * 167 * @param da 168 * The devargs structure holding the device information. 169 */ 170 __rte_experimental 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