blob: b3146dd7aa4362dd0ce3337ef4c29d04be5a3e32 [file] [log] [blame]
Michal Nazarewiczc7ba6922010-06-21 13:57:07 +02001 -*- 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
David E. Narvaez9c8f6822014-01-04 16:30:49 -050017Please note that if you use non-standard configuration (that is enable
Michal Nazarewiczc7ba6922010-06-21 13:57:07 +020018CDC 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
Michal Nazarewicz072baa02016-06-11 02:56:37 +020039For the gadget to work under Windows two conditions have to be met:
Michal Nazarewiczc7ba6922010-06-21 13:57:07 +020040
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
Diego Herranz2dc01942016-04-12 18:13:27 +010046tries to match drivers for each individual interface (sort of, don't
Michal Nazarewiczc7ba6922010-06-21 13:57:07 +020047get 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]]