[lkml]   [2010]   [Jun]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
    Patch in this message
    Subject[PATCHv5 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 Windown 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 likesy 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 3bed2e9..971285d 100644
    --- a/Documentation/usb/linux.inf
    +++ b/Documentation/usb/linux.inf
    @@ -19,15 +19,15 @@ DriverVer = 06/21/2006,6.0.6000.16384

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

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

    ; Decoration for ia64 architecture
    -%RndisDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
    +%RndisDevice% = 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-16 12:11    [W:0.033 / U:19.096 seconds]
    ©2003-2017 Jasper Spaans. hosted at Digital OceanAdvertise on this site