ether.c 12 KB

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