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  * 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
  88 static 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 /* DO NOT REUSE THESE IDs with a protocol-incompatible driver!!  Ever!!
 100  * Instead:  allocate your own, using normal USB-IF procedures.
 101  */
 102
 103 /* Thanks to NetChip Technologies for donating this product ID.
 104  * It's for devices with only CDC Ethernet configurations.
 105  */
 106 #define CDC_VENDOR_NUM          0x0525  /* NetChip */
 107 #define CDC_PRODUCT_NUM         0xa4a1  /* Linux-USB Ethernet Gadget */
 108
 109 /* For hardware that can't talk CDC, we use the same vendor ID that
 110  * ARM Linux has used for ethernet-over-usb, both with sa1100 and
 111  * with pxa250.  We're protocol-compatible, if the host-side drivers
 112  * use the endpoint descriptors.  bcdDevice (version) is nonzero, so
 113  * drivers that need to hard-wire endpoint numbers have a hook.
 114  *
 115  * The protocol is a minimal subset of CDC Ether, which works on any bulk
 116  * hardware that's not deeply broken ... even on hardware that can't talk
 117  * RNDIS (like SA-1100, with no interrupt endpoint, or anything that
 118  * doesn't handle control-OUT).
 119  */
 120 #define SIMPLE_VENDOR_NUM       0x049f
 121 #define SIMPLE_PRODUCT_NUM      0x505a
 122
 123 /* For hardware that can talk RNDIS and either of the above protocols,
 124  * use this ID ... the windows INF files will know it.  Unless it's
 125  * used with CDC Ethernet, Linux 2.4 hosts will need updates to choose
 126  * the non-RNDIS configuration.
 127  */
 128 #define RNDIS_VENDOR_NUM        0x0525  /* NetChip */
 129 #define RNDIS_PRODUCT_NUM       0xa4a2  /* Ethernet/RNDIS Gadget */
 130
 131 /*-------------------------------------------------------------------------*/
 132
 133 static struct usb_device_descriptor device_desc = {
 134         .bLength =              sizeof device_desc,
 135         .bDescriptorType =      USB_DT_DEVICE,
 136
 137         .bcdUSB =               __constant_cpu_to_le16 (0x0200),
 138
 139         .bDeviceClass =         USB_CLASS_COMM,
 140         .bDeviceSubClass =      0,
 141         .bDeviceProtocol =      0,
 142         /* .bMaxPacketSize0 = f(hardware) */
 143
 144         /* Vendor and product id defaults change according to what configs
 145          * we support.  (As does bNumConfigurations.)  These values can
 146          * also be overridden by module parameters.
 147          */
 148         .idVendor =             __constant_cpu_to_le16 (CDC_VENDOR_NUM),
 149         .idProduct =            __constant_cpu_to_le16 (CDC_PRODUCT_NUM),
 150         /* .bcdDevice = f(hardware) */
 151         /* .iManufacturer = DYNAMIC */
 152         /* .iProduct = DYNAMIC */
 153         /* NO SERIAL NUMBER */
 154         .bNumConfigurations =   1,
 155 };
 156
 157 static struct usb_otg_descriptor otg_descriptor = {
 158         .bLength =              sizeof otg_descriptor,
 159         .bDescriptorType =      USB_DT_OTG,
 160
 161         /* REVISIT SRP-only hardware is possible, although
 162          * it would not be called "OTG" ...
 163          */
 164         .bmAttributes =         USB_OTG_SRP | USB_OTG_HNP,
 165 };
 166
 167 static const struct usb_descriptor_header *otg_desc[] = {
 168         (struct usb_descriptor_header *) &otg_descriptor,
 169         NULL,
 170 };
 171
 172
 173 /* string IDs are assigned dynamically */
 174
 175 #define STRING_MANUFACTURER_IDX         0
 176 #define STRING_PRODUCT_IDX              1
 177
 178 static char manufacturer[50];
 179
 180 static struct usb_string strings_dev[] = {
 181         [STRING_MANUFACTURER_IDX].s = manufacturer,
 182         [STRING_PRODUCT_IDX].s = PREFIX DRIVER_DESC,
 183         {  } /* end of list */
 184 };
 185
 186 static struct usb_gadget_strings stringtab_dev = {
 187         .language       = 0x0409,       /* en-us */
 188         .strings        = strings_dev,
 189 };
 190
 191 static struct usb_gadget_strings *dev_strings[] = {
 192         &stringtab_dev,
 193         NULL,
 194 };
 195
 196 static u8 hostaddr[ETH_ALEN];
 197
 198 /*-------------------------------------------------------------------------*/
 199
 200 /*
 201  * We may not have an RNDIS configuration, but if we do it needs to be
 202  * the first one present.  That's to make Microsoft's drivers happy,
 203  * and to follow DOCSIS 1.0 (cable modem standard).
 204  */
 205 static int __init rndis_do_config(struct usb_configuration *c)
 206 {
 207         /* FIXME alloc iConfiguration string, set it in c->strings */
 208
 209         if (gadget_is_otg(c->cdev->gadget)) {
 210                 c->descriptors = otg_desc;
 211                 c->bmAttributes |= USB_CONFIG_ATT_WAKEUP;
 212         }
 213
 214         return rndis_bind_config(c, hostaddr);
 215 }
 216
 217 static struct usb_configuration rndis_config_driver = {
 218         .label                  = "RNDIS",
 219         .bind                   = rndis_do_config,
 220         .bConfigurationValue    = 2,
 221         /* .iConfiguration = DYNAMIC */
 222         .bmAttributes           = USB_CONFIG_ATT_SELFPOWER,
 223         .bMaxPower              = 1,    /* 2 mA, minimal */
 224 };
 225
 226 /*-------------------------------------------------------------------------*/
 227
 228 /*
 229  * We _always_ have an ECM or CDC Subset configuration.
 230  */
 231 static int __init eth_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         if (can_support_ecm(c->cdev->gadget))
 241                 return ecm_bind_config(c, hostaddr);
 242         else
 243                 return geth_bind_config(c, hostaddr);
 244 }
 245
 246 static struct usb_configuration eth_config_driver = {
 247         /* .label = f(hardware) */
 248         .bind                   = eth_do_config,
 249         .bConfigurationValue    = 1,
 250         /* .iConfiguration = DYNAMIC */
 251         .bmAttributes           = USB_CONFIG_ATT_SELFPOWER,
 252         .bMaxPower              = 1,    /* 2 mA, minimal */
 253 };
 254
 255 /*-------------------------------------------------------------------------*/
 256
 257 static int __init eth_bind(struct usb_composite_dev *cdev)
 258 {
 259         int                     gcnum;
 260         struct usb_gadget       *gadget = cdev->gadget;
 261         int                     status;
 262
 263         /* set up network link layer */
 264         status = gether_setup(cdev->gadget, hostaddr);
 265         if (status < 0)
 266                 return status;
 267
 268         /* set up main config label and device descriptor */
 269         if (can_support_ecm(cdev->gadget)) {
 270                 /* ECM */
 271                 eth_config_driver.label = "CDC Ethernet (ECM)";
 272         } else {
 273                 /* CDC Subset */
 274                 eth_config_driver.label = "CDC Subset/SAFE";
 275
 276                 device_desc.idVendor = cpu_to_le16(SIMPLE_VENDOR_NUM),
 277                 device_desc.idProduct = cpu_to_le16(SIMPLE_PRODUCT_NUM),
 278                 device_desc.bDeviceClass = USB_CLASS_VENDOR_SPEC;
 279         }
 280
 281         if (has_rndis()) {
 282                 /* RNDIS plus ECM-or-Subset */
 283                 device_desc.idVendor = cpu_to_le16(RNDIS_VENDOR_NUM),
 284                 device_desc.idProduct = cpu_to_le16(RNDIS_PRODUCT_NUM),
 285                 device_desc.bNumConfigurations = 2;
 286         }
 287
 288         gcnum = usb_gadget_controller_number(gadget);
 289         if (gcnum >= 0)
 290                 device_desc.bcdDevice = cpu_to_le16(0x0300 | gcnum);
 291         else {
 292                 /* We assume that can_support_ecm() tells the truth;
 293                  * but if the controller isn't recognized at all then
 294                  * that assumption is a bit more likely to be wrong.
 295                  */
 296                 WARNING(cdev, "controller '%s' not recognized; trying %s\n",
 297                                 gadget->name,
 298                                 eth_config_driver.label);
 299                 device_desc.bcdDevice =
 300                         __constant_cpu_to_le16(0x0300 | 0x0099);
 301         }
 302
 303
 304         /* Allocate string descriptor numbers ... note that string
 305          * contents can be overridden by the composite_dev glue.
 306          */
 307
 308         /* device descriptor strings: manufacturer, product */
 309         snprintf(manufacturer, sizeof manufacturer, "%s %s with %s",
 310                 init_utsname()->sysname, init_utsname()->release,
 311                 gadget->name);
 312         status = usb_string_id(cdev);
 313         if (status < 0)
 314                 goto fail;
 315         strings_dev[STRING_MANUFACTURER_IDX].id = status;
 316         device_desc.iManufacturer = status;
 317
 318         status = usb_string_id(cdev);
 319         if (status < 0)
 320                 goto fail;
 321         strings_dev[STRING_PRODUCT_IDX].id = status;
 322         device_desc.iProduct = status;
 323
 324         /* register our configuration(s); RNDIS first, if it's used */
 325         if (has_rndis()) {
 326                 status = usb_add_config(cdev, &rndis_config_driver);
 327                 if (status < 0)
 328                         goto fail;
 329         }
 330
 331         status = usb_add_config(cdev, &eth_config_driver);
 332         if (status < 0)
 333                 goto fail;
 334
 335         INFO(cdev, "%s, version: " DRIVER_VERSION "\n", DRIVER_DESC);
 336
 337         return 0;
 338
 339 fail:
 340         gether_cleanup();
 341         return status;
 342 }
 343
 344 static int __exit eth_unbind(struct usb_composite_dev *cdev)
 345 {
 346         gether_cleanup();
 347         return 0;
 348 }
 349
 350 static struct usb_composite_driver eth_driver = {
 351         .name           = "g_ether",
 352         .dev            = &device_desc,
 353         .strings        = dev_strings,
 354         .bind           = eth_bind,
 355         .unbind         = __exit_p(eth_unbind),
 356 };
 357
 358 MODULE_DESCRIPTION(PREFIX DRIVER_DESC);
 359 MODULE_AUTHOR("David Brownell, Benedikt Spanger");
 360 MODULE_LICENSE("GPL");
 361
 362 static int __init init(void)
 363 {
 364         return usb_composite_register(&eth_driver);
 365 }
 366 module_init(init);
 367
 368 static void __exit cleanup(void)
 369 {
 370         usb_composite_unregister(&eth_driver);
 371 }
 372 module_exit(cleanup);