| 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, ð_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(ð_driver); |
| 367 | } |
| 368 | module_init(init); |
| 369 | |
| 370 | static void __exit cleanup(void) |
| 371 | { |
| 372 | usb_composite_unregister(ð_driver); |
| 373 | } |
| 374 | module_exit(cleanup); |