tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
USB: gadget: g_multi: added documentation and INF files
A short documentation of the g_multi driver along with INF
files for Windows XP SP3 are provided.
Signed-off-by: Michal Nazarewicz <m.nazarewicz@samsung.com>
Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
authored by
Michal Nazarewicz
and committed by
Greg Kroah-Hartman
c7ba6922
e41e134e
+155
-5
+150
Documentation/usb/gadget_multi.txt
+150
Documentation/usb/gadget_multi.txt
···
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
+
17
+
Please not that if you use non-standard configuration (that is enable
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]]
+2
-2
Documentation/usb/linux-cdc-acm.inf
+2
-2
Documentation/usb/linux-cdc-acm.inf
···
90
90
[SourceDisksFiles]
91
91
[SourceDisksNames]
92
92
[DeviceList]
93
-
%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
93
+
%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02
94
94
95
95
[DeviceList.NTamd64]
96
-
%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
96
+
%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02
97
97
98
98
99
99
;------------------------------------------------------------------------------
+3
-3
Documentation/usb/linux.inf
+3
-3
Documentation/usb/linux.inf
···
18
18
19
19
; Decoration for x86 architecture
20
20
[LinuxDevices.NTx86]
21
-
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
21
+
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00
22
22
23
23
; Decoration for x64 architecture
24
24
[LinuxDevices.NTamd64]
25
-
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
25
+
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00
26
26
27
27
; Decoration for ia64 architecture
28
28
[LinuxDevices.NTia64]
29
-
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
29
+
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00
30
30
31
31
;@@@ This is the common setting for setup
32
32
[ControlFlags]