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 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 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]]