1/* 2 * ether.c -- Ethernet gadget driver, with CDC and non-CDC options 3 * 4 * Copyright (C) 2003-2005,2008 David Brownell 5 * Copyright (C) 2003-2004 Robert Schwebel, Benedikt Spranger 6 * Copyright (C) 2008 Nokia Corporation 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 */ 13 14/* #define VERBOSE_DEBUG */ 15 16#include <linux/kernel.h> 17#include <linux/utsname.h> 18 19 20#if defined USB_ETH_RNDIS 21# undef USB_ETH_RNDIS 22#endif 23#ifdef CONFIG_USB_ETH_RNDIS 24# define USB_ETH_RNDIS y 25#endif 26 27#include "u_ether.h" 28 29 30/* 31 * Ethernet gadget driver -- with CDC and non-CDC options 32 * Builds on hardware support for a full duplex link. 33 * 34 * CDC Ethernet is the standard USB solution for sending Ethernet frames 35 * using USB. Real hardware tends to use the same framing protocol but look 36 * different for control features. This driver strongly prefers to use 37 * this USB-IF standard as its open-systems interoperability solution; 38 * most host side USB stacks (except from Microsoft) support it. 39 * 40 * This is sometimes called "CDC ECM" (Ethernet Control Model) to support 41 * TLA-soup. "CDC ACM" (Abstract Control Model) is for modems, and a new 42 * "CDC EEM" (Ethernet Emulation Model) is starting to spread. 43 * 44 * There's some hardware that can't talk CDC ECM. We make that hardware 45 * implement a "minimalist" vendor-agnostic CDC core: same framing, but 46 * link-level setup only requires activating the configuration. Only the 47 * endpoint descriptors, and product/vendor IDs, are relevant; no control 48 * operations are available. Linux supports it, but other host operating 49 * systems may not. (This is a subset of CDC Ethernet.) 50 * 51 * It turns out that if you add a few descriptors to that "CDC Subset", 52 * (Windows) host side drivers from MCCI can treat it as one submode of 53 * a proprietary scheme called "SAFE" ... without needing to know about 54 * specific product/vendor IDs. So we do that, making it easier to use 55 * those MS-Windows drivers. Those added descriptors make it resemble a 56 * CDC MDLM device, but they don't change device behavior at all. (See 57 * MCCI Engineering report 950198 "SAFE Networking Functions".) 58 * 59 * A third option is also in use. Rather than CDC Ethernet, or something 60 * simpler, Microsoft pushes their own approach: RNDIS. The published 61 * RNDIS specs are ambiguous and appear to be incomplete, and are also 62 * needlessly complex. They borrow more from CDC ACM than CDC ECM. 63 */ 64 65#define DRIVER_DESC "Ethernet Gadget" 66#define DRIVER_VERSION "Memorial Day 2008" 67 68#ifdef USB_ETH_RNDIS 69#define PREFIX "RNDIS/" 70#else 71#define PREFIX "" 72#endif 73 74/* 75 * This driver aims for interoperability by using CDC ECM unless 76 * 77 * can_support_ecm() 78 * 79 * returns false, in which case it supports the CDC Subset. By default, 80 * that returns true; most hardware has no problems with CDC ECM, that's 81 * a good default. Previous versions of this driver had no default; this 82 * version changes that, removing overhead for new controller support. 83 * 84 * IF YOUR HARDWARE CAN'T SUPPORT CDC ECM, UPDATE THAT ROUTINE! 85 */ 86 87static inline bool has_rndis(void) 88{ 89#ifdef USB_ETH_RNDIS 90 return true; 91#else 92 return false; 93#endif 94} 95 96/*-------------------------------------------------------------------------*/ 97 98/* 99 * Kbuild is not very cooperative with respect to linking separately 100 * compiled library objects into one module. So for now we won't use 101 * separate compilation ... ensuring init/exit sections work to shrink 102 * the runtime footprint, and giving us at least some parts of what 103 * a "gcc --combine ... part1.c part2.c part3.c ... " build would. 104 */ 105#include "composite.c" 106#include "usbstring.c" 107#include "config.c" 108#include "epautoconf.c" 109 110#include "f_ecm.c" 111#include "f_subset.c" 112#ifdef USB_ETH_RNDIS 113#include "f_rndis.c" 114#include "rndis.c" 115#endif 116#include "f_eem.c" 117#include "u_ether.c" 118 119/*-------------------------------------------------------------------------*/ 120 121/* DO NOT REUSE THESE IDs with a protocol-incompatible driver!! Ever!! 122 * Instead: allocate your own, using normal USB-IF procedures. 123 */ 124 125/* Thanks to NetChip Technologies for donating this product ID. 126 * It's for devices with only CDC Ethernet configurations. 127 */ 128#define CDC_VENDOR_NUM 0x0525 /* NetChip */ 129#define CDC_PRODUCT_NUM 0xa4a1 /* Linux-USB Ethernet Gadget */ 130 131/* For hardware that can't talk CDC, we use the same vendor ID that 132 * ARM Linux has used for ethernet-over-usb, both with sa1100 and 133 * with pxa250. We're protocol-compatible, if the host-side drivers 134 * use the endpoint descriptors. bcdDevice (version) is nonzero, so 135 * drivers that need to hard-wire endpoint numbers have a hook. 136 * 137 * The protocol is a minimal subset of CDC Ether, which works on any bulk 138 * hardware that's not deeply broken ... even on hardware that can't talk 139 * RNDIS (like SA-1100, with no interrupt endpoint, or anything that 140 * doesn't handle control-OUT). 141 */ 142#define SIMPLE_VENDOR_NUM 0x049f 143#define SIMPLE_PRODUCT_NUM 0x505a 144 145/* For hardware that can talk RNDIS and either of the above protocols, 146 * use this ID ... the windows INF files will know it. Unless it's 147 * used with CDC Ethernet, Linux 2.4 hosts will need updates to choose 148 * the non-RNDIS configuration. 149 */ 150#define RNDIS_VENDOR_NUM 0x0525 /* NetChip */ 151#define RNDIS_PRODUCT_NUM 0xa4a2 /* Ethernet/RNDIS Gadget */ 152 153/* For EEM gadgets */ 154#define EEM_VENDOR_NUM 0x1d6b /* Linux Foundation */ 155#define EEM_PRODUCT_NUM 0x0102 /* EEM Gadget */ 156 157/*-------------------------------------------------------------------------*/ 158 159static struct usb_device_descriptor device_desc = { 160 .bLength = sizeof device_desc, 161 .bDescriptorType = USB_DT_DEVICE, 162 163 .bcdUSB = cpu_to_le16 (0x0200), 164 165 .bDeviceClass = USB_CLASS_COMM, 166 .bDeviceSubClass = 0, 167 .bDeviceProtocol = 0, 168 /* .bMaxPacketSize0 = f(hardware) */ 169 170 /* Vendor and product id defaults change according to what configs 171 * we support. (As does bNumConfigurations.) These values can 172 * also be overridden by module parameters. 173 */ 174 .idVendor = cpu_to_le16 (CDC_VENDOR_NUM), 175 .idProduct = cpu_to_le16 (CDC_PRODUCT_NUM), 176 /* .bcdDevice = f(hardware) */ 177 /* .iManufacturer = DYNAMIC */ 178 /* .iProduct = DYNAMIC */ 179 /* NO SERIAL NUMBER */ 180 .bNumConfigurations = 1, 181}; 182 183static struct usb_otg_descriptor otg_descriptor = { 184 .bLength = sizeof otg_descriptor, 185 .bDescriptorType = USB_DT_OTG, 186 187 /* REVISIT SRP-only hardware is possible, although 188 * it would not be called "OTG" ... 189 */ 190 .bmAttributes = USB_OTG_SRP | USB_OTG_HNP, 191}; 192 193static const struct usb_descriptor_header *otg_desc[] = { 194 (struct usb_descriptor_header *) &otg_descriptor, 195 NULL, 196}; 197 198 199/* string IDs are assigned dynamically */ 200 201#define STRING_MANUFACTURER_IDX 0 202#define STRING_PRODUCT_IDX 1 203 204static char manufacturer[50]; 205 206static struct usb_string strings_dev[] = { 207 [STRING_MANUFACTURER_IDX].s = manufacturer, 208 [STRING_PRODUCT_IDX].s = PREFIX DRIVER_DESC, 209 { } /* end of list */ 210}; 211 212static struct usb_gadget_strings stringtab_dev = { 213 .language = 0x0409, /* en-us */ 214 .strings = strings_dev, 215}; 216 217static struct usb_gadget_strings *dev_strings[] = { 218 &stringtab_dev, 219 NULL, 220}; 221 222static u8 hostaddr[ETH_ALEN]; 223 224/*-------------------------------------------------------------------------*/ 225 226/* 227 * We may not have an RNDIS configuration, but if we do it needs to be 228 * the first one present. That's to make Microsoft's drivers happy, 229 * and to follow DOCSIS 1.0 (cable modem standard). 230 */ 231static int __init rndis_do_config(struct usb_configuration *c) 232{ 233 /* FIXME alloc iConfiguration string, set it in c->strings */ 234 235 if (gadget_is_otg(c->cdev->gadget)) { 236 c->descriptors = otg_desc; 237 c->bmAttributes |= USB_CONFIG_ATT_WAKEUP; 238 } 239 240 return rndis_bind_config(c, hostaddr); 241} 242 243static struct usb_configuration rndis_config_driver = { 244 .label = "RNDIS", 245 .bConfigurationValue = 2, 246 /* .iConfiguration = DYNAMIC */ 247 .bmAttributes = USB_CONFIG_ATT_SELFPOWER, 248}; 249 250/*-------------------------------------------------------------------------*/ 251 252#ifdef CONFIG_USB_ETH_EEM 253static bool use_eem = 1; 254#else 255static bool use_eem; 256#endif 257module_param(use_eem, bool, 0); 258MODULE_PARM_DESC(use_eem, "use CDC EEM mode"); 259 260/* 261 * We _always_ have an ECM, CDC Subset, or EEM configuration. 262 */ 263static int __init eth_do_config(struct usb_configuration *c) 264{ 265 /* FIXME alloc iConfiguration string, set it in c->strings */ 266 267 if (gadget_is_otg(c->cdev->gadget)) { 268 c->descriptors = otg_desc; 269 c->bmAttributes |= USB_CONFIG_ATT_WAKEUP; 270 } 271 272 if (use_eem) 273 return eem_bind_config(c); 274 else if (can_support_ecm(c->cdev->gadget)) 275 return ecm_bind_config(c, hostaddr); 276 else 277 return geth_bind_config(c, hostaddr); 278} 279 280static struct usb_configuration eth_config_driver = { 281 /* .label = f(hardware) */ 282 .bConfigurationValue = 1, 283 /* .iConfiguration = DYNAMIC */ 284 .bmAttributes = USB_CONFIG_ATT_SELFPOWER, 285}; 286 287/*-------------------------------------------------------------------------*/ 288 289static int __init eth_bind(struct usb_composite_dev *cdev) 290{ 291 int gcnum; 292 struct usb_gadget *gadget = cdev->gadget; 293 int status; 294 295 /* set up network link layer */ 296 status = gether_setup(cdev->gadget, hostaddr); 297 if (status < 0) 298 return status; 299 300 /* set up main config label and device descriptor */ 301 if (use_eem) { 302 /* EEM */ 303 eth_config_driver.label = "CDC Ethernet (EEM)"; 304 device_desc.idVendor = cpu_to_le16(EEM_VENDOR_NUM); 305 device_desc.idProduct = cpu_to_le16(EEM_PRODUCT_NUM); 306 } else if (can_support_ecm(cdev->gadget)) { 307 /* ECM */ 308 eth_config_driver.label = "CDC Ethernet (ECM)"; 309 } else { 310 /* CDC Subset */ 311 eth_config_driver.label = "CDC Subset/SAFE"; 312 313 device_desc.idVendor = cpu_to_le16(SIMPLE_VENDOR_NUM); 314 device_desc.idProduct = cpu_to_le16(SIMPLE_PRODUCT_NUM); 315 if (!has_rndis()) 316 device_desc.bDeviceClass = USB_CLASS_VENDOR_SPEC; 317 } 318 319 if (has_rndis()) { 320 /* RNDIS plus ECM-or-Subset */ 321 device_desc.idVendor = cpu_to_le16(RNDIS_VENDOR_NUM); 322 device_desc.idProduct = cpu_to_le16(RNDIS_PRODUCT_NUM); 323 device_desc.bNumConfigurations = 2; 324 } 325 326 gcnum = usb_gadget_controller_number(gadget); 327 if (gcnum >= 0) 328 device_desc.bcdDevice = cpu_to_le16(0x0300 | gcnum); 329 else { 330 /* We assume that can_support_ecm() tells the truth; 331 * but if the controller isn't recognized at all then 332 * that assumption is a bit more likely to be wrong. 333 */ 334 dev_warn(&gadget->dev, 335 "controller '%s' not recognized; trying %s\n", 336 gadget->name, 337 eth_config_driver.label); 338 device_desc.bcdDevice = 339 cpu_to_le16(0x0300 | 0x0099); 340 } 341 342 343 /* Allocate string descriptor numbers ... note that string 344 * contents can be overridden by the composite_dev glue. 345 */ 346 347 /* device descriptor strings: manufacturer, product */ 348 snprintf(manufacturer, sizeof manufacturer, "%s %s with %s", 349 init_utsname()->sysname, init_utsname()->release, 350 gadget->name); 351 status = usb_string_id(cdev); 352 if (status < 0) 353 goto fail; 354 strings_dev[STRING_MANUFACTURER_IDX].id = status; 355 device_desc.iManufacturer = status; 356 357 status = usb_string_id(cdev); 358 if (status < 0) 359 goto fail; 360 strings_dev[STRING_PRODUCT_IDX].id = status; 361 device_desc.iProduct = status; 362 363 /* register our configuration(s); RNDIS first, if it's used */ 364 if (has_rndis()) { 365 status = usb_add_config(cdev, &rndis_config_driver, 366 rndis_do_config); 367 if (status < 0) 368 goto fail; 369 } 370 371 status = usb_add_config(cdev, ð_config_driver, eth_do_config); 372 if (status < 0) 373 goto fail; 374 375 dev_info(&gadget->dev, "%s, version: " DRIVER_VERSION "\n", 376 DRIVER_DESC); 377 378 return 0; 379 380fail: 381 gether_cleanup(); 382 return status; 383} 384 385static int __exit eth_unbind(struct usb_composite_dev *cdev) 386{ 387 gether_cleanup(); 388 return 0; 389} 390 391static struct usb_composite_driver eth_driver = { 392 .name = "g_ether", 393 .dev = &device_desc, 394 .strings = dev_strings, 395 .max_speed = USB_SPEED_SUPER, 396 .unbind = __exit_p(eth_unbind), 397}; 398 399MODULE_DESCRIPTION(PREFIX DRIVER_DESC); 400MODULE_AUTHOR("David Brownell, Benedikt Spanger"); 401MODULE_LICENSE("GPL"); 402 403static int __init init(void) 404{ 405 return usb_composite_probe(ð_driver, eth_bind); 406} 407module_init(init); 408 409static void __exit cleanup(void) 410{ 411 usb_composite_unregister(ð_driver); 412} 413module_exit(cleanup); 414