Based on kernel version 4.15. Page generated on 2018-01-29 10:01 EST.
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 (that is Ethernet), USB CDC 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. 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 to 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. If they are met, 45 Windows lets USB Generic Parent Driver handle the device which then 46 tries to match 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 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). 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 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:email@example.com]]). INF files have been hacked with 122 support of Marek Szyprowski ([[mailto:firstname.lastname@example.org]]) and 123 Xiaofan Chen ([[mailto:email@example.com]]) basing on the MS RNDIS 124 template, Microchip's CDC ACM INF file and David Brownell's 125 ([[mailto:firstname.lastname@example.org]]) original INF files. 126 127 * Footnotes 128 129  Remote Network Driver Interface Specification, 130 [[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. 131 132  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  CDC Ethernet Control Model. 137 138  [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] 139 140  [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] 141 142  To put it in some other nice words, Windows failed to respond to 143 any user input. 144 145  You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] 146 useful. 147 148  http://www.nirsoft.net/utils/usb_devices_view.html 149 150  [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]]