[PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Dries Van Puymbroeck]

When a mutlifunctional gadget has more than 1 configuration, Windows does not
use its generic driver for multifunctional USB devices.

This commit adds an INF file that will load the required Windows driver
as well as a short description in gadget_multi.txt

Signed-off-by: Dries Van Puymbroeck <dries.vanpuymbroeck@dekimo.com>
---
I based the INF file on linux.inf. I tested it and it works, but perhaps
the style could be improved. Comments/suggestions welcome!

 Documentation/usb/gadget_multi.txt |    8 ++++--
 Documentation/usb/linux-multi.inf  |   47 ++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/usb/linux-multi.inf

diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt
index 80f4ef0..0a6dba6 100644
--- a/Documentation/usb/gadget_multi.txt
+++ b/Documentation/usb/gadget_multi.txt
@@ -49,9 +49,11 @@ 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!
+The only thing to worry about is that Windows won't use its USB Generic
+Parent Driver unless the gadget has a single configuration.
+Therefore, a dual RNDIS and CDC ECM gadget will need the
+[[file:linux-multi.inf]] file included alongside this document
+to work correctly.
 
 *** Installing drivers for each function
 
diff --git a/Documentation/usb/linux-multi.inf b/Documentation/usb/linux-multi.inf
new file mode 100644
index 0000000..836c79b
--- /dev/null
+++ b/Documentation/usb/linux-multi.inf
@@ -0,0 +1,47 @@
+; MS-Windows driver that can install usbccgp.sys
+;(generic driver for composite devices)
+; For use with composite devices that have more than 1 configuration
+; Based on linux.inf
+
+[Version]
+Signature           = "$WINDOWS NT$"
+Class               = USB
+ClassGUID           = {36fc9e60-c465-11cf-8056-444553540000}
+Provider            = %Linux%
+DriverVer           = 07/29/2010,0.0.0.0
+
+[Manufacturer]
+%Linux%	 = CCGPLoader,NTx86,NTamd64,NTia64
+
+; Decoration for x86 architecture
+[CCGPLoader.NTx86]
+%LinuxCompositeDevice% = Composite.Device,USB\VID_0525&PID_a4ab
+
+; Decoration for x64 architecture
+[LinuxDevices.NTamd64]
+%LinuxCompositeDevice% = Composite.Device,USB\VID_0525&PID_a4ab
+
+; Decoration for ia64 architecture
+[LinuxDevices.NTia64]
+%LinuxCompositeDevice% = Composite.Device,USB\VID_0525&PID_a4ab
+
+[ControlFlags]
+ExcludeFromSelect=*
+
+; Common Class Generic Parent for root ID
+[Composite.Device.NTx86]
+Include=usb.inf
+Needs=Composite.Dev.NT
+
+[Composite.Device.NTx86.Services]
+Include=usb.inf
+Needs=Composite.Dev.NT.Services
+
+[SourceDisksNames]
+1=%SourceDisk%,,1
+
+[Strings]
+ServiceDisplayName    = "USB Composite Device Driver"
+Linux                 = "Linux Developer Community"
+LinuxCompositeDevice  = "Linux Multifunction Gadget with multiple configurations"
+SourceDisk            = "Linux Composite Gadget Driver Install Disk"
-- 
1.7.0.4

Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Xiaofan Chen]

On Fri, Aug 13, 2010 at 5:31 PM, Dries Van Puymbroeck
<dries.van.puymbroeck@gmail.com> wrote:
> When a mutlifunction gadget has more than 1 configuration, Windows does not
> use its generic driver for multifunctional USB devices.

Sorry but what do you mean by the above?
As per the previous discussions, it seems that a registry entry hack
(for Vista and Windows 7) is needed.
http://msdn.microsoft.com/en-us/library/ff538059%28VS.85%29.aspx

> This commit adds an INF file that will load the required Windows driver
> as well as a short description in gadget_multi.txt

It seems to me your inf file forces the USB Generic
Parent Driver (for USB Composite Device) to load. But for which
configuration? I do not have any device to test myself. But
I tend to guess it will still be the first configuration (either
RNDIS or CDC ECM).

I did see something similar for WMCDC.
http://msdn.microsoft.com/en-us/library/ff538833%28VS.85%29.aspx
http://msdn.microsoft.com/en-us/library/ff537100%28v=VS.85%29.aspx

-- 
Xiaofan

Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Michal Nazarewicz]

Xiaofan Chen <xiaofanc@gmail.com> writes:

> On Fri, Aug 13, 2010 at 5:31 PM, Dries Van Puymbroeck
> <dries.van.puymbroeck@gmail.com> wrote:
>> When a mutlifunction gadget has more than 1 configuration, Windows does not
>> use its generic driver for multifunctional USB devices.
>
> Sorry but what do you mean by the above?
> As per the previous discussions, it seems that a registry entry hack
> (for Vista and Windows 7) is needed.
> http://msdn.microsoft.com/en-us/library/ff538059%28VS.85%29.aspx
>
>> This commit adds an INF file that will load the required Windows driver
>> as well as a short description in gadget_multi.txt
>
> It seems to me your inf file forces the USB Generic
> Parent Driver (for USB Composite Device) to load. But for which
> configuration? I do not have any device to test myself. But
> I tend to guess it will still be the first configuration (either
> RNDIS or CDC ECM).

2-configuration g_multi has configuration with RNDIS as the first one so
that's pretty perfect for us.

-- 
Best regards,                                         _     _
 .o. | Liege of Serenly Enlightened Majesty of      o' \,=./ `o
 ..o | Computer Science,  Michal "mina86" Nazarewicz   (o o)
 ooo +--<mina86-tlen.pl>--<jid:mina86-jabber.org>--ooO--(_)--Ooo--

Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Xiaofan Chen]

On Sat, Aug 14, 2010 at 4:35 AM, Michal Nazarewicz <mina86@mina86.com> wrote:
> Xiaofan Chen <xiaofanc@gmail.com> writes:
>
>> On Fri, Aug 13, 2010 at 5:31 PM, Dries Van Puymbroeck
>> <dries.van.puymbroeck@gmail.com> wrote:
>>> When a mutlifunction gadget has more than 1 configuration, Windows does not
>>> use its generic driver for multifunctional USB devices.
>>
>> Sorry but what do you mean by the above?
>> As per the previous discussions, it seems that a registry entry hack
>> (for Vista and Windows 7) is needed.
>> http://msdn.microsoft.com/en-us/library/ff538059%28VS.85%29.aspx
>>
>>> This commit adds an INF file that will load the required Windows driver
>>> as well as a short description in gadget_multi.txt
>>
>> It seems to me your inf file forces the USB Generic
>> Parent Driver (for USB Composite Device) to load. But for which
>> configuration? I do not have any device to test myself. But
>> I tend to guess it will still be the first configuration (either
>> RNDIS or CDC ECM).
>
> 2-configuration g_multi has configuration with RNDIS as the first one so
> that's pretty perfect for us.

I guess so. But I am wondering if the inf file really needed or not
in this case.

Basically I am just wondering if the following statement is true or not.
>>> When a mutlifunction gadget has more than 1 configuration, Windows does not
>>> use its generic driver for multifunction USB devices.

I am thinking the inf file is not necessary.
"When the system detects that a USB device is composite, it loads the
USB common class generic parent driver (usbccgp.sys)."
http://msdn.microsoft.com/en-us/library/ff538059%28VS.85%29.aspx

And since 1st configuration RNDIS is what desired, nothing needs to be done.

Obviously you have the device to test, I would be interested to know your
test results under XP, Vista and Win7.

-- 
Xiaofan

Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Michal Nazarewicz]

Xiaofan Chen <xiaofanc@gmail.com> writes:
> Basically I am just wondering if the following statement is true or not.

> On Fri, Aug 13, 2010 at 5:31 PM, Dries Van Puymbroeck wrote:
>> When a mutlifunction gadget has more than 1 configuration, Windows does not
>> use its generic driver for multifunction USB devices.

> I am thinking the inf file is not necessary.
> "When the system detects that a USB device is composite, it loads the
> USB common class generic parent driver (usbccgp.sys)."
> http://msdn.microsoft.com/en-us/library/ff538059%28VS.85%29.aspx

<http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx>
specifies that for a device to be identified as composite it (among
other things) "must have a single configuration".  The page has also
a passage which seems to indicate that the INF is needed:

> If you want the generic parent driver to manage your device, but your
> device does not have the characteristics necessary to ensure that the
> system will generate a compatible ID of USB\COMPOSITE, you will have
> to provide an INF file that loads the generic parent driver.

Selecting of the configuration is also mentioned as a requirement, and
the next paragraph points to a web page you've cited:

> If your composite device has multiple configurations, the INF file you
> provide must specify which configuration the generic parent should use
> in the registry. The necessary registry keys are described in
> Selecting the Configuration for a Composite USB Device.

-- 
Best regards,                                         _     _
 .o. | Liege of Serenly Enlightened Majesty of      o' \,=./ `o
 ..o | Computer Science,  Michal "mina86" Nazarewicz   (o o)
 ooo +--<mina86-tlen.pl>--<jid:mina86-jabber.org>--ooO--(_)--Ooo--

Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Xiaofan Chen]

On Sat, Aug 14, 2010 at 4:39 PM, Michal Nazarewicz <mina86@mina86.com> wrote:
> <http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx>
> specifies that for a device to be identified as composite it (among
> other things) "must have a single configuration".  The page has also
> a passage which seems to indicate that the INF is needed:
>
>" If you want the generic parent driver to manage your device, but your
> device does not have the characteristics necessary to ensure that the
> system will generate a compatible ID of USB\COMPOSITE, you will have
> to provide an INF file that loads the generic parent driver."
>
> Selecting of the configuration is also mentioned as a requirement, and
> the next paragraph points to a web page you've cited:
>
>" If your composite device has multiple configurations, the INF file you
> provide must specify which configuration the generic parent should use
> in the registry. The necessary registry keys are described in
> Selecting the Configuration for a Composite USB Device."

Thanks. Now it is clear. The patch is correct after all.

Somehow I forgot the following blog entry again. This blog entry
seems to be more clear than the MSDN entries.
http://blogs.msdn.com/b/usbcoreblog/archive/2010/05/19/multi-config-usb-devices-and-windows.aspx

+++++++++++++++++
The USBCCGP composite device driver has support for multiple device
configurations, with a few caveats.
http://msdn.microsoft.com/en-us/library/ff539242(VS.85).aspx

   1. USBCCGP will not load on a multi-config device by default because
the hub driver doesn't create a "USB\COMPOSITE" PNP ID for a composite
device if it has multiple configurations. However, you can write your own INF
that matches a device-specific PNP ID to get USBCCGP to load as your
device's function driver.

   2. To select a configuration other than index 0, you must set registry
settings as specified in "Selecting the Configuration for a Composite
USB Device".
http://msdn.microsoft.com/en-us/library/ff538059(VS.85).aspx

During enumeration, USBCCGP will first attempt to select the
configuration whose descriptor is found at the specified "original" index. If
the attempt fails, normally due to the configuration requiring more than
100mA while the device's upstream hub has only bus power, then
USBCCGP attempts to select the configuration found at the specified
"alternate" index instead.

   3. Drivers that are clients of USBCCGP cannot change the device's
configuration value.
+++++++++++++++++



-- 
Xiaofan

RE: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

[Dries Van Puymbroeck]

Hi, sorry for the delay in answering; 


FROM: Xiaofan Chen [mailto:xiaofanc@gmail.com] 
SENT: vrijdag 13 augustus 2010 15:32
TO: Dries Van Puymbroeck
CC: linux-usb@vger.kernel.org; Greg KH; Michał Nazarewicz; Michał Nazarewicz; Dries Van Puymbroeck; linux-kernel@vger.kernel.org
Onderwerp: Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

>I did see something similar for WMCDC.
>http://msdn.microsoft.com/en-us/library/ff538833%28VS.85%29.aspx
>http://msdn.microsoft.com/en-us/library/ff537100%28v=VS.85%29.aspx

This is actually what I based my INF file on. Maybe I should mention that in the comments in the INF?


FROM: Xiaofan Chen [mailto:xiaofanc@gmail.com] 
SENT: zaterdag 14 augustus 2010 3:28
TO: Michal Nazarewicz
CC: Dries Van Puymbroeck; linux-usb@vger.kernel.org; Greg KH; Michał Nazarewicz; Dries Van Puymbroeck; linux-kernel@vger.kernel.org
Onderwerp: Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

>Obviously you have the device to test, I would be interested to know your
>test results under XP, Vista and Win7.

Yes, I do have an embedded device running the g_multi driver, and have experimented with both 1 configuration (RNDIS) and 2 condfigurations (RNDIS and CDC ECM) on several windows versions (XP, Vista 32 and 64 bit, Windows 7 32 and 64 bit)

When running 1 configuration the device works: windows loads usbccgp.sys and all interfaces are detected (and the linux.inf file can be used). 

This is true for all versions I have tested except for Windows 7 64 bit. It seems here that the RNDIS interface is not detected as a network adapter but as an 'other usb device.' This then makes windows not show a driver install wizard (where one would choose the INF file). It is possible to go into the device manager and configure the RNDIS device manually as a network adapter, after which everything works the same as on other windows versions. Do you have any idea why this only happens on Windows 7 64 bit specifically? (Vista 64 bit and Windows 7 32 bit do not have this behavior, leaving me confused)

When running 2 configurations the device is simply detected as a "multifunction composite device". Usbccgp.sys is not loaded. It is possible to install linux.inf for this device, but then only the first interface (ie: the Ethernet over USB functionality) will be available, any other interfaces such as mass storage devices are not available then. What my INF file does is load usbccgp.sys so that linux.inf can use its multiple interfaces.


-----Oorspronkelijk bericht-----
FROM: Xiaofan Chen [mailto:xiaofanc@gmail.com] 
SENT: zaterdag 14 augustus 2010 10:58
TO: Michal Nazarewicz
CC: Dries Van Puymbroeck; linux-usb@vger.kernel.org; Greg KH; Michał Nazarewicz; Dries Van Puymbroeck; linux-kernel@vger.kernel.org
Onderwerp: Re: [PATCH] USB: Gadget: g_multi: added INF file for gadget with multiple configurations

>Thanks. Now it is clear. The patch is correct after all.

Thanks!

>Somehow I forgot the following blog entry again. This blog entry
>seems to be more clear than the MSDN entries.

Yes, it is, thanks for pointing this out to me, I had not found this webpage yet.