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