1 -*- org -*- 2 3* Overview 4 5The Multifunction Composite Gadget (or g_multi) is a composite gadget 6that makes extensive use of the composite framework to provide 7a... multifunction gadget. 8 9In it's standard configuration it provides a single USB configuration 10with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and 11USB Mass Storage functions. 12 13A CDC ECM (Ethernet) function may be turned on via a Kconfig option 14and RNDIS can be turned off. If they are both enabled the gadget will 15have two configurations -- one with RNDIS and another with CDC ECM[3]. 16 17Please not that if you use non-standard configuration (that is enable 18CDC ECM) you may need to change vendor and/or product ID. 19 20* Host drivers 21 22To make use of the gadget one needs to make it work on host side -- 23without that there's no hope of achieving anything with the gadget. 24As one might expect, things one need to do very from system to system. 25 26** Linux host drivers 27 28Since the gadget uses standard composite framework and appears as such 29to Linux host it does not need any additional drivers on Linux host 30side. All the functions are handled by respective drivers developed 31for them. 32 33This is also true for two configuration set-up with RNDIS 34configuration being the first one. Linux host will use the second 35configuration with CDC ECM which should work better under Linux. 36 37** Windows host drivers 38 39For the gadget two work under Windows two conditions have to be met: 40 41*** Detecting as composite gadget 42 43First of all, Windows need to detect the gadget as an USB composite 44gadget which on its own have some conditions[4]. If they are met, 45Windows lets USB Generic Parent Driver[5] handle the device which then 46tries to much drivers for each individual interface (sort of, don't 47get into too many details). 48 49The good news is: you do not have to worry about most of the 50conditions! 51 52The only thing to worry is that the gadget has to have a single 53configuration so a dual RNDIS and CDC ECM gadget won't work unless you 54create a proper INF -- and of course, if you do submit it! 55 56*** Installing drivers for each function 57 58The other, trickier thing is making Windows install drivers for each 59individual function. 60 61For mass storage it is trivial since Windows detect it's an interface 62implementing USB Mass Storage class and selects appropriate driver. 63 64Things are harder with RDNIS and CDC ACM. 65 66**** RNDIS 67 68To make Windows select RNDIS drivers for the first function in the 69gadget, one needs to use the [[file:linux.inf]] file provided with this 70document. It "attaches" Window's RNDIS driver to the first interface 71of the gadget. 72 73Please note, that while testing we encountered some issues[6] when 74RNDIS was not the first interface. You do not need to worry abut it 75unless you are trying to develop your own gadget in which case watch 76out for this bug. 77 78**** CDC ACM 79 80Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. 81 82**** Customising the gadget 83 84If you intend to hack the g_multi gadget be advised that rearranging 85functions will obviously change interface numbers for each of the 86functionality. As an effect provided INFs won't work since they have 87interface numbers hard-coded in them (it's not hard to change those 88though[7]). 89 90This also means, that after experimenting with g_multi and changing 91provided functions one should change gadget's vendor and/or product ID 92so there will be no collision with other customised gadgets or the 93original gadget. 94 95Failing to comply may cause brain damage after wondering for hours why 96things don't work as intended before realising Windows have cached 97some drivers information (changing USB port may sometimes help plus 98you might try using USBDeview[8] to remove the phantom device). 99 100**** INF testing 101 102Provided INF files have been tested on Windows XP SP3, Windows Vista 103and Windows 7, all 32-bit versions. It should work on 64-bit versions 104as well. It most likely won't work on Windows prior to Windows XP 105SP2. 106 107** Other systems 108 109At this moment, drivers for any other systems have not been tested. 110Knowing how MacOS is based on BSD and BSD is an Open Source it is 111believed that it should (read: "I have no idea whether it will") work 112out-of-the-box. 113 114For more exotic systems I have even less to say... 115 116Any testing and drivers *are* *welcome*! 117 118* Authors 119 120This document has been written by Michal Nazarewicz 121([[mailto:mina86@mina86.com]]). INF files have been hacked with 122support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and 123Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS 124template[9], Microchip's CDC ACM INF file and David Brownell's 125([[mailto:dbrownell@users.sourceforge.net]]) original INF files. 126 127* Footnotes 128 129[1] Remote Network Driver Interface Specification, 130[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. 131 132[2] Communications Device Class Abstract Control Model, spec for this 133and other USB classes can be found at 134[[http://www.usb.org/developers/devclass_docs/]]. 135 136[3] CDC Ethernet Control Model. 137 138[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] 139 140[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] 141 142[6] To put it in some other nice words, Windows failed to respond to 143any user input. 144 145[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] 146useful. 147 148[8] http://www.nirsoft.net/utils/usb_devices_view.html 149 150[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] 151