[lkml]   [2010]   [Jun]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCHv7 09/11] 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 <>
Signed-off-by: Kyungmin Park <>
Documentation/usb/gadget_multi.txt | 150 +++++++++++++++++++++++++++++++++++
Documentation/usb/linux-cdc-acm.inf | 4 +-
Documentation/usb/linux.inf | 6 +-
3 files changed, 155 insertions(+), 5 deletions(-)
create mode 100644 Documentation/usb/gadget_multi.txt
diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt
new file mode 100644
index 0000000..008c69f
--- /dev/null
+++ b/Documentation/usb/gadget_multi.txt
@@ -0,0 +1,150 @@
+ -*- org -*-
+* Overview
+The Multifunction Composite Gadget (or g_multi) is a composite gadget
+that makes extensive use of the composite framework to provide
+a... multifunction gadget.
+In it's standard configuration it provides a single USB configuration
+with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and
+USB Mass Storage functions.
+A CDC ECM (Ethernet) function may be turned on via a Kconfig option
+and RNDIS can be turned off. If they are both enabled the gadget will
+have two configurations -- one with RNDIS and another with CDC ECM[3].
+Please not that if you use non-standard configuration (that is enable
+CDC ECM) you may need to change vendor and/or product ID.
+* Host drivers
+To make use of the gadget one needs to make it work on host side --
+without that there's no hope of achieving anything with the gadget.
+As one might expect, things one need to do very from system to system.
+** Linux host drivers
+Since the gadget uses standard composite framework and appears as such
+to Linux host it does not need any additional drivers on Linux host
+side. All the functions are handled by respective drivers developed
+for them.
+This is also true for two configuration set-up with RNDIS
+configuration being the first one. Linux host will use the second
+configuration with CDC ECM which should work better under Linux.
+** Windows host drivers
+For the gadget two work under Windows two conditions have to be met:
+*** Detecting as composite gadget
+First of all, Windows need to detect the gadget as an USB composite
+gadget which on its own have some conditions[4]. If they are met,
+Windows lets USB Generic Parent Driver[5] handle the device which then
+tries to much drivers for each individual interface (sort of, don't
+get into too many details).
+The good news is: you do not have to worry about most of the
+The only thing to worry is that the gadget has to have a single
+configuration so a dual RNDIS and CDC ECM gadget won't work unless you
+create a proper INF -- and of course, if you do submit it!
+*** Installing drivers for each function
+The other, trickier thing is making Windows install drivers for each
+individual function.
+For mass storage it is trivial since Windows detect it's an interface
+implementing USB Mass Storage class and selects appropriate driver.
+Things are harder with RDNIS and CDC ACM.
+**** RNDIS
+To make Windows select RNDIS drivers for the first function in the
+gadget, one needs to use the [[file:linux.inf]] file provided with this
+document. It "attaches" Window's RNDIS driver to the first interface
+of the gadget.
+Please note, that while testing we encountered some issues[6] when
+RNDIS was not the first interface. You do not need to worry abut it
+unless you are trying to develop your own gadget in which case watch
+out for this bug.
+**** CDC ACM
+Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM.
+**** Customising the gadget
+If you intend to hack the g_multi gadget be advised that rearranging
+functions will obviously change interface numbers for each of the
+functionality. As an effect provided INFs won't work since they have
+interface numbers hard-coded in them (it's not hard to change those
+This also means, that after experimenting with g_multi and changing
+provided functions one should change gadget's vendor and/or product ID
+so there will be no collision with other customised gadgets or the
+original gadget.
+Failing to comply may cause brain damage after wondering for hours why
+things don't work as intended before realising Windows have cached
+some drivers information (changing USB port may sometimes help plus
+you might try using USBDeview[8] to remove the phantom device).
+**** INF testing
+Provided INF files have been tested on Windows XP SP3, Windows Vista
+and Windows 7, all 32-bit versions. It should work on 64-bit versions
+as well. It most likely won't work on Windows prior to Windows XP
+** Other systems
+At this moment, drivers for any other systems have not been tested.
+Knowing how MacOS is based on BSD and BSD is an Open Source it is
+believed that it should (read: "I have no idea whether it will") work
+For more exotic systems I have even less to say...
+Any testing and drivers *are* *welcome*!
+* Authors
+This document has been written by Michal Nazarewicz
+([[]]). INF files have been hacked with
+support of Marek Szyprowski ([[]]) and
+Xiaofan Chen ([[]]) basing on the MS RNDIS
+template[9], Microchip's CDC ACM INF file and David Brownell's
+([[]]) original INF files.
+* Footnotes
+[1] Remote Network Driver Interface Specification,
+[2] Communications Device Class Abstract Control Model, spec for this
+and other USB classes can be found at
+[3] CDC Ethernet Control Model.
+[4] [[]]
+[5] [[]]
+[6] To put it in some other nice words, Windows failed to respond to
+any user input.
+[7] You may find [[]]
+[9] [[]]
diff --git a/Documentation/usb/linux-cdc-acm.inf b/Documentation/usb/linux-cdc-acm.inf
index 77636dd..d4a1a5e 100644
--- a/Documentation/usb/linux-cdc-acm.inf
+++ b/Documentation/usb/linux-cdc-acm.inf
@@ -90,10 +90,10 @@ end of the line.
-%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
+%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02

-%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
+%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02

diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf
index b9e538c..4dee958 100644
--- a/Documentation/usb/linux.inf
+++ b/Documentation/usb/linux.inf
@@ -18,15 +18,15 @@ DriverVer = 06/21/2006,6.0.6000.16384

; Decoration for x86 architecture
-%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
+%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

; Decoration for x64 architecture
-%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
+%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

; Decoration for ia64 architecture
-%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
+%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

;@@@ This is the common setting for setup

 \ /
  Last update: 2010-06-21 13:59    [from the cache]
©2003-2014 Jasper Spaans. hosted at Digital Ocean