About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / gadget_multi.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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 note 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 to 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 match 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]]
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog