drivers/usb/gadget/ether.c

   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
  87 static 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
 159 static 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
 183 static 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
 193 static 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
 204 static char manufacturer[50];
 205
 206 static 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
 212 static struct usb_gadget_strings stringtab_dev = {
 213         .language       = 0x0409,       /* en-us */
 214         .strings        = strings_dev,
 215 };
 216
 217 static struct usb_gadget_strings *dev_strings[] = {
 218         &stringtab_dev,
 219         NULL,
 220 };
 221
 222 static 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  */
 231 static 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
 243 static 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
 253 static int use_eem = 1;
 254 #else
 255 static int use_eem;
 256 #endif
 257 module_param(use_eem, bool, 0);
 258 MODULE_PARM_DESC(use_eem, "use CDC EEM mode");
 259
 260 /*
 261  * We _always_ have an ECM, CDC Subset, or EEM configuration.
 262  */
 263 static 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
 280 static 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
 289 static 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, &eth_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
 380 fail:
 381         gether_cleanup();
 382         return status;
 383 }
 384
 385 static int __exit eth_unbind(struct usb_composite_dev *cdev)
 386 {
 387         gether_cleanup();
 388         return 0;
 389 }
 390
 391 static 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
 399 MODULE_DESCRIPTION(PREFIX DRIVER_DESC);
 400 MODULE_AUTHOR("David Brownell, Benedikt Spanger");
 401 MODULE_LICENSE("GPL");
 402
 403 static int __init init(void)
 404 {
 405         return usb_composite_probe(&eth_driver, eth_bind);
 406 }
 407 module_init(init);
 408
 409 static void __exit cleanup(void)
 410 {
 411         usb_composite_unregister(&eth_driver);
 412 }
 413 module_exit(cleanup);