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