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