Documentation/usb/gadget_multi.rst

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