1 // SPDX-License-Identifier: GPL-2.0+ 2 /* 3 * ether.c -- Ethernet gadget driver, with CDC and non-CDC options 4 * 5 * Copyright (C) 2003-2005,2008 David Brownell 6 * Copyright (C) 2003-2004 Robert Schwebel, Benedikt Spranger 7 * Copyright (C) 2008 Nokia Corporation 8 */ 9 10 /* #define VERBOSE_DEBUG */ 11 12 #include <linux/kernel.h> 13 #include <linux/netdevice.h> 14 15 #if defined USB_ETH_RNDIS 16 # undef USB_ETH_RNDIS 17 #endif 18 #ifdef CONFIG_USB_ETH_RNDIS 19 # define USB_ETH_RNDIS y 20 #endif 21 22 #include "u_ether.h" 23 24 25 /* 26 * Ethernet gadget driver -- with CDC and non-CDC options 27 * Builds on hardware support for a full duplex link. 28 * 29 * CDC Ethernet is the standard USB solution for sending Ethernet frames 30 * using USB. Real hardware tends to use the same framing protocol but look 31 * different for control features. This driver strongly prefers to use 32 * this USB-IF standard as its open-systems interoperability solution; 33 * most host side USB stacks (except from Microsoft) support it. 34 * 35 * This is sometimes called "CDC ECM" (Ethernet Control Model) to support 36 * TLA-soup. "CDC ACM" (Abstract Control Model) is for modems, and a new 37 * "CDC EEM" (Ethernet Emulation Model) is starting to spread. 38 * 39 * There's some hardware that can't talk CDC ECM. We make that hardware 40 * implement a "minimalist" vendor-agnostic CDC core: same framing, but 41 * link-level setup only requires activating the configuration. Only the 42 * endpoint descriptors, and product/vendor IDs, are relevant; no control 43 * operations are available. Linux supports it, but other host operating 44 * systems may not. (This is a subset of CDC Ethernet.) 45 * 46 * It turns out that if you add a few descriptors to that "CDC Subset", 47 * (Windows) host side drivers from MCCI can treat it as one submode of 48 * a proprietary scheme called "SAFE" ... without needing to know about 49 * specific product/vendor IDs. So we do that, making it easier to use 50 * those MS-Windows drivers. Those added descriptors make it resemble a 51 * CDC MDLM device, but they don't change device behavior at all. (See 52 * MCCI Engineering report 950198 "SAFE Networking Functions".) 53 * 54 * A third option is also in use. Rather than CDC Ethernet, or something 55 * simpler, Microsoft pushes their own approach: RNDIS. The published 56 * RNDIS specs are ambiguous and appear to be incomplete, and are also 57 * needlessly complex. They borrow more from CDC ACM than CDC ECM. 58 */ 59 60 #define DRIVER_DESC "Ethernet Gadget" 61 #define DRIVER_VERSION "Memorial Day 2008" 62 63 #ifdef USB_ETH_RNDIS 64 #define PREFIX "RNDIS/" 65 #else 66 #define PREFIX "" 67 #endif 68 69 /* 70 * This driver aims for interoperability by using CDC ECM unless 71 * 72 * can_support_ecm() 73 * 74 * returns false, in which case it supports the CDC Subset. By default, 75 * that returns true; most hardware has no problems with CDC ECM, that's 76 * a good default. Previous versions of this driver had no default; this 77 * version changes that, removing overhead for new controller support. 78 * 79 * IF YOUR HARDWARE CAN'T SUPPORT CDC ECM, UPDATE THAT ROUTINE! 80 */ 81 82 static inline bool has_rndis(void) 83 { 84 #ifdef USB_ETH_RNDIS 85 return true; 86 #else 87 return false; 88 #endif 89 } 90 91 #include <linux/module.h> 92 93 #include "u_ecm.h" 94 #include "u_gether.h" 95 #ifdef USB_ETH_RNDIS 96 #include "u_rndis.h" 97 #include "rndis.h" 98 #else 99 #define rndis_borrow_net(...) do {} while (0) 100 #endif 101 #include "u_eem.h" 102 103 /*-------------------------------------------------------------------------*/ 104 USB_GADGET_COMPOSITE_OPTIONS(); 105 106 USB_ETHERNET_MODULE_PARAMETERS(); 107 108 /* DO NOT REUSE THESE IDs with a protocol-incompatible driver!! Ever!! 109 * Instead: allocate your own, using normal USB-IF procedures. 110 */ 111 112 /* Thanks to NetChip Technologies for donating this product ID. 113 * It's for devices with only CDC Ethernet configurations. 114 */ 115 #define CDC_VENDOR_NUM 0x0525 /* NetChip */ 116 #define CDC_PRODUCT_NUM 0xa4a1 /* Linux-USB Ethernet Gadget */ 117 118 /* For hardware that can't talk CDC, we use the same vendor ID that 119 * ARM Linux has used for ethernet-over-usb, both with sa1100 and 120 * with pxa250. We're protocol-compatible, if the host-side drivers 121 * use the endpoint descriptors. bcdDevice (version) is nonzero, so 122 * drivers that need to hard-wire endpoint numbers have a hook. 123 * 124 * The protocol is a minimal subset of CDC Ether, which works on any bulk 125 * hardware that's not deeply broken ... even on hardware that can't talk 126 * RNDIS (like SA-1100, with no interrupt endpoint, or anything that 127 * doesn't handle control-OUT). 128 */ 129 #define SIMPLE_VENDOR_NUM 0x049f 130 #define SIMPLE_PRODUCT_NUM 0x505a 131 132 /* For hardware that can talk RNDIS and either of the above protocols, 133 * use this ID ... the windows INF files will know it. Unless it's 134 * used with CDC Ethernet, Linux 2.4 hosts will need updates to choose 135 * the non-RNDIS configuration. 136 */ 137 #define RNDIS_VENDOR_NUM 0x0525 /* NetChip */ 138 #define RNDIS_PRODUCT_NUM 0xa4a2 /* Ethernet/RNDIS Gadget */ 139 140 /* For EEM gadgets */ 141 #define EEM_VENDOR_NUM 0x1d6b /* Linux Foundation */ 142 #define EEM_PRODUCT_NUM 0x0102 /* EEM Gadget */ 143 144 /*-------------------------------------------------------------------------*/ 145 146 static struct usb_device_descriptor device_desc = { 147 .bLength = sizeof device_desc, 148 .bDescriptorType = USB_DT_DEVICE, 149 150 /* .bcdUSB = DYNAMIC */ 151 152 .bDeviceClass = USB_CLASS_COMM, 153 .bDeviceSubClass = 0, 154 .bDeviceProtocol = 0, 155 /* .bMaxPacketSize0 = f(hardware) */ 156 157 /* Vendor and product id defaults change according to what configs 158 * we support. (As does bNumConfigurations.) These values can 159 * also be overridden by module parameters. 160 */ 161 .idVendor = cpu_to_le16 (CDC_VENDOR_NUM), 162 .idProduct = cpu_to_le16 (CDC_PRODUCT_NUM), 163 /* .bcdDevice = f(hardware) */ 164 /* .iManufacturer = DYNAMIC */ 165 /* .iProduct = DYNAMIC */ 166 /* NO SERIAL NUMBER */ 167 .bNumConfigurations = 1, 168 }; 169 170 static const struct usb_descriptor_header *otg_desc[2]; 171 172 static struct usb_string strings_dev[] = { 173 [USB_GADGET_MANUFACTURER_IDX].s = "", 174 [USB_GADGET_PRODUCT_IDX].s = PREFIX DRIVER_DESC, 175 [USB_GADGET_SERIAL_IDX].s = "", 176 { } /* end of list */ 177 }; 178 179 static struct usb_gadget_strings stringtab_dev = { 180 .language = 0x0409, /* en-us */ 181 .strings = strings_dev, 182 }; 183 184 static struct usb_gadget_strings *dev_strings[] = { 185 &stringtab_dev, 186 NULL, 187 }; 188 189 static struct usb_function_instance *fi_ecm; 190 static struct usb_function *f_ecm; 191 192 static struct usb_function_instance *fi_eem; 193 static struct usb_function *f_eem; 194 195 static struct usb_function_instance *fi_geth; 196 static struct usb_function *f_geth; 197 198 static struct usb_function_instance *fi_rndis; 199 static struct usb_function *f_rndis; 200 201 /*-------------------------------------------------------------------------*/ 202 203 /* 204 * We may not have an RNDIS configuration, but if we do it needs to be 205 * the first one present. That's to make Microsoft's drivers happy, 206 * and to follow DOCSIS 1.0 (cable modem standard). 207 */ 208 static int rndis_do_config(struct usb_configuration *c) 209 { 210 int status; 211 212 /* FIXME alloc iConfiguration string, set it in c->strings */ 213 214 if (gadget_is_otg(c->cdev->gadget)) { 215 c->descriptors = otg_desc; 216 c->bmAttributes |= USB_CONFIG_ATT_WAKEUP; 217 } 218 219 f_rndis = usb_get_function(fi_rndis); 220 if (IS_ERR(f_rndis)) 221 return PTR_ERR(f_rndis); 222 223 status = usb_add_function(c, f_rndis); 224 if (status < 0) 225 usb_put_function(f_rndis); 226 227 return status; 228 } 229 230 static struct usb_configuration rndis_config_driver = { 231 .label = "RNDIS", 232 .bConfigurationValue = 2, 233 /* .iConfiguration = DYNAMIC */ 234 .bmAttributes = USB_CONFIG_ATT_SELFPOWER, 235 }; 236 237 /*-------------------------------------------------------------------------*/ 238 239 #ifdef CONFIG_USB_ETH_EEM 240 static bool use_eem = 1; 241 #else 242 static bool use_eem; 243 #endif 244 module_param(use_eem, bool, 0); 245 MODULE_PARM_DESC(use_eem, "use CDC EEM mode"); 246 247 /* 248 * We _always_ have an ECM, CDC Subset, or EEM configuration. 249 */ 250 static int eth_do_config(struct usb_configuration *c) 251 { 252 int status = 0; 253 254 /* FIXME alloc iConfiguration string, set it in c->strings */ 255 256 if (gadget_is_otg(c->cdev->gadget)) { 257 c->descriptors = otg_desc; 258 c->bmAttributes |= USB_CONFIG_ATT_WAKEUP; 259 } 260 261 if (use_eem) { 262 f_eem = usb_get_function(fi_eem); 263 if (IS_ERR(f_eem)) 264 return PTR_ERR(f_eem); 265 266 status = usb_add_function(c, f_eem); 267 if (status < 0) 268 usb_put_function(f_eem); 269 270 return status; 271 } else if (can_support_ecm(c->cdev->gadget)) { 272 f_ecm = usb_get_function(fi_ecm); 273 if (IS_ERR(f_ecm)) 274 return PTR_ERR(f_ecm); 275 276 status = usb_add_function(c, f_ecm); 277 if (status < 0) 278 usb_put_function(f_ecm); 279 280 return status; 281 } else { 282 f_geth = usb_get_function(fi_geth); 283 if (IS_ERR(f_geth)) 284 return PTR_ERR(f_geth); 285 286 status = usb_add_function(c, f_geth); 287 if (status < 0) 288 usb_put_function(f_geth); 289 290 return status; 291 } 292 293 } 294 295 static struct usb_configuration eth_config_driver = { 296 /* .label = f(hardware) */ 297 .bConfigurationValue = 1, 298 /* .iConfiguration = DYNAMIC */ 299 .bmAttributes = USB_CONFIG_ATT_SELFPOWER, 300 }; 301 302 /*-------------------------------------------------------------------------*/ 303 304 static int eth_bind(struct usb_composite_dev *cdev) 305 { 306 struct usb_gadget *gadget = cdev->gadget; 307 struct f_eem_opts *eem_opts = NULL; 308 struct f_ecm_opts *ecm_opts = NULL; 309 struct f_gether_opts *geth_opts = NULL; 310 struct net_device *net; 311 int status; 312 313 /* set up main config label and device descriptor */ 314 if (use_eem) { 315 /* EEM */ 316 fi_eem = usb_get_function_instance("eem"); 317 if (IS_ERR(fi_eem)) 318 return PTR_ERR(fi_eem); 319 320 eem_opts = container_of(fi_eem, struct f_eem_opts, func_inst); 321 322 net = eem_opts->net; 323 324 eth_config_driver.label = "CDC Ethernet (EEM)"; 325 device_desc.idVendor = cpu_to_le16(EEM_VENDOR_NUM); 326 device_desc.idProduct = cpu_to_le16(EEM_PRODUCT_NUM); 327 } else if (can_support_ecm(gadget)) { 328 /* ECM */ 329 330 fi_ecm = usb_get_function_instance("ecm"); 331 if (IS_ERR(fi_ecm)) 332 return PTR_ERR(fi_ecm); 333 334 ecm_opts = container_of(fi_ecm, struct f_ecm_opts, func_inst); 335 336 net = ecm_opts->net; 337 338 eth_config_driver.label = "CDC Ethernet (ECM)"; 339 } else { 340 /* CDC Subset */ 341 342 fi_geth = usb_get_function_instance("geth"); 343 if (IS_ERR(fi_geth)) 344 return PTR_ERR(fi_geth); 345 346 geth_opts = container_of(fi_geth, struct f_gether_opts, 347 func_inst); 348 349 net = geth_opts->net; 350 351 eth_config_driver.label = "CDC Subset/SAFE"; 352 353 device_desc.idVendor = cpu_to_le16(SIMPLE_VENDOR_NUM); 354 device_desc.idProduct = cpu_to_le16(SIMPLE_PRODUCT_NUM); 355 if (!has_rndis()) 356 device_desc.bDeviceClass = USB_CLASS_VENDOR_SPEC; 357 } 358 359 gether_set_qmult(net, qmult); 360 if (!gether_set_host_addr(net, host_addr)) 361 pr_info("using host ethernet address: %s", host_addr); 362 if (!gether_set_dev_addr(net, dev_addr)) 363 pr_info("using self ethernet address: %s", dev_addr); 364 365 if (has_rndis()) { 366 /* RNDIS plus ECM-or-Subset */ 367 gether_set_gadget(net, cdev->gadget); 368 status = gether_register_netdev(net); 369 if (status) 370 goto fail; 371 372 if (use_eem) 373 eem_opts->bound = true; 374 else if (can_support_ecm(gadget)) 375 ecm_opts->bound = true; 376 else 377 geth_opts->bound = true; 378 379 fi_rndis = usb_get_function_instance("rndis"); 380 if (IS_ERR(fi_rndis)) { 381 status = PTR_ERR(fi_rndis); 382 goto fail; 383 } 384 385 rndis_borrow_net(fi_rndis, net); 386 387 device_desc.idVendor = cpu_to_le16(RNDIS_VENDOR_NUM); 388 device_desc.idProduct = cpu_to_le16(RNDIS_PRODUCT_NUM); 389 device_desc.bNumConfigurations = 2; 390 } 391 392 /* Allocate string descriptor numbers ... note that string 393 * contents can be overridden by the composite_dev glue. 394 */ 395 396 status = usb_string_ids_tab(cdev, strings_dev); 397 if (status < 0) 398 goto fail1; 399 device_desc.iManufacturer = strings_dev[USB_GADGET_MANUFACTURER_IDX].id; 400 device_desc.iProduct = strings_dev[USB_GADGET_PRODUCT_IDX].id; 401 402 if (gadget_is_otg(gadget) && !otg_desc[0]) { 403 struct usb_descriptor_header *usb_desc; 404 405 usb_desc = usb_otg_descriptor_alloc(gadget); 406 if (!usb_desc) 407 goto fail1; 408 usb_otg_descriptor_init(gadget, usb_desc); 409 otg_desc[0] = usb_desc; 410 otg_desc[1] = NULL; 411 } 412 413 /* register our configuration(s); RNDIS first, if it's used */ 414 if (has_rndis()) { 415 status = usb_add_config(cdev, &rndis_config_driver, 416 rndis_do_config); 417 if (status < 0) 418 goto fail2; 419 } 420 421 status = usb_add_config(cdev, ð_config_driver, eth_do_config); 422 if (status < 0) 423 goto fail2; 424 425 usb_composite_overwrite_options(cdev, &coverwrite); 426 dev_info(&gadget->dev, "%s, version: " DRIVER_VERSION "\n", 427 DRIVER_DESC); 428 429 return 0; 430 431 fail2: 432 kfree(otg_desc[0]); 433 otg_desc[0] = NULL; 434 fail1: 435 if (has_rndis()) 436 usb_put_function_instance(fi_rndis); 437 fail: 438 if (use_eem) 439 usb_put_function_instance(fi_eem); 440 else if (can_support_ecm(gadget)) 441 usb_put_function_instance(fi_ecm); 442 else 443 usb_put_function_instance(fi_geth); 444 return status; 445 } 446 447 static int eth_unbind(struct usb_composite_dev *cdev) 448 { 449 if (has_rndis()) { 450 usb_put_function(f_rndis); 451 usb_put_function_instance(fi_rndis); 452 } 453 if (use_eem) { 454 usb_put_function(f_eem); 455 usb_put_function_instance(fi_eem); 456 } else if (can_support_ecm(cdev->gadget)) { 457 usb_put_function(f_ecm); 458 usb_put_function_instance(fi_ecm); 459 } else { 460 usb_put_function(f_geth); 461 usb_put_function_instance(fi_geth); 462 } 463 kfree(otg_desc[0]); 464 otg_desc[0] = NULL; 465 466 return 0; 467 } 468 469 static struct usb_composite_driver eth_driver = { 470 .name = "g_ether", 471 .dev = &device_desc, 472 .strings = dev_strings, 473 .max_speed = USB_SPEED_SUPER, 474 .bind = eth_bind, 475 .unbind = eth_unbind, 476 }; 477 478 module_usb_composite_driver(eth_driver); 479 480 MODULE_DESCRIPTION(PREFIX DRIVER_DESC); 481 MODULE_AUTHOR("David Brownell, Benedikt Spanger"); 482 MODULE_LICENSE("GPL"); 483