gadget_multi.rst

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