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