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