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