USB: gadget: g_multi: added documentation and INF files (c7ba6922) · Commits · e / devices / android_kernel_xiaomi_markw

Documentation/usb/gadget_multi.txt

0 → 100644

+150 −0

Original line number	Diff line number	Diff line
		-- 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 Windows 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
		conditions!

		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
		though[7]).

		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 likely won't work on Windows prior to Windows XP
		SP2.

		** 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
		out-of-the-box.

		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
		([[mailto:mina86@mina86.com]]). INF files have been hacked with
		support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and
		Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS
		template[9], Microchip's CDC ACM INF file and David Brownell's
		([[mailto:dbrownell@users.sourceforge.net]]) original INF files.

		* Footnotes

		[1] Remote Network Driver Interface Specification,
		[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]].

		[2] Communications Device Class Abstract Control Model, spec for this
		and other USB classes can be found at
		[[http://www.usb.org/developers/devclass_docs/]].

		[3] CDC Ethernet Control Model.

		[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]

		[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]

		[6] To put it in some other nice words, Windows failed to respond to
		any user input.

		[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]]
		useful.

		[8] http://www.nirsoft.net/utils/usb_devices_view.html

		[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]]

Documentation/usb/linux-cdc-acm.inf

+2 −2

Original line number	Diff line number	Diff line
		@@ -90,10 +90,10 @@ ServiceBinary=%12%\USBSER.sys
		[SourceDisksFiles]
		[SourceDisksNames]
		[DeviceList]
		%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
		%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02

		[DeviceList.NTamd64]
		%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7
		%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02


		;------------------------------------------------------------------------------

Documentation/usb/linux.inf

+3 −3

Original line number	Diff line number	Diff line
		@@ -18,15 +18,15 @@ DriverVer = 06/21/2006,6.0.6000.16384

		; Decoration for x86 architecture
		[LinuxDevices.NTx86]
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

		; Decoration for x64 architecture
		[LinuxDevices.NTamd64]
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

		; Decoration for ia64 architecture
		[LinuxDevices.NTia64]
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
		%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00

		;@@@ This is the common setting for setup
		[ControlFlags]