moin2mdwn: convert page DeviceQuirks

2 files changed, 177 insertions, 206 deletions

diff --git a/DeviceQuirks.mdwn b/DeviceQuirks.mdwn
new file mode 100644
index 0000000..5f8de41
--- /dev/null
+++ b/DeviceQuirks.mdwn
@@ -0,0 +1,177 @@
+
+Some [[DisplayLink|DisplayLink]] devices have multiple USB configurations, with the default configuration reporting a class code which will cause them to get matched with a Linux kernel input or cdrom driver, before the displaylink-mod kernel framebuffer driver has a chance to see the device. In that case, obviously the [[DisplayLink|DisplayLink]] device will appear not to work. 
+
+This happens because some [[DisplayLink|DisplayLink]] devices come up in a default configuration other than #1 and report USB HID or USB mass storage class codes, in order to provide a special autoinstall path on Windows.  
+
+In all cases, if the USB configuration of the [[DisplayLink|DisplayLink]] device is set to 1 (from whatever the default is, which is usually 2 for these type of devices), then the [[DisplayLink|DisplayLink]] device will report no special class code, and will get matched against the correct driver.  
+
+So how can the devices which won't work by default be handled? 
+
+
+# Solutions
+
+
+## udev rule
+
+One solution may be a udev script and utility solution like this: 
+
+
+[[!format txt """
+cat /etc/udev/rules.d/60-displaylink.rules
+# DisplayLink devices always have the active configuration on configuration #1
+SYSFS{idVendor}=="17e9", SYSFS{bConfigurationValue}=="2", RUN+="/usr/bin/dlconfig /sys%p/bConfigurationValue"
+
+cat /usr/bin/dlconfig
+#! /bin/bash
+if [ -e /sys$1/device/bConfigurationValue ]; then
+    echo 1 > /sys$1/device/bConfigurationValue
+fi;
+
+if [ -e /sys$1/bConfigurationValue ]; then
+    echo 1 > /sys$1/bConfigurationValue
+fi;
+"""]]
+This results in the configuration being switched for DL devices. It works on both HID and MSC variants of the autoinstall. udev gets called with different device paths for HID and MSC, hence the two parts to the dlconfig script. 
+
+Technically, this covers 100% of the cases.  Practically, this method may be problematic in that these short udev scripts must get picked up by every Linux distribution (or users must run them) 
+
+However, for multiseat solutions, it's possible to use udev rules to find groupings of display, keyboard, mouse, etc. under the same USB hub, record that in the /dev filesystem as a seat, and then launch a (gdmdynamic) login prompt for that "seat".  If a udev script providing that kind of functionality is appealing enough to get picked up by most/all Linux distros, then setting configuration 1 for all [[DisplayLink|DisplayLink]] devices in that script might be a good catch-all solution.   
+
+
+## blacklisting in the HID and mass storage (MSC) class drivers
+
+This has lots of precedents, but there are problems.  Some HID interfaces expose real functionality (like dock buttons) which others exist only to hide the main displaylink device to prevent unwanted Windows dialogs.  If the match is done on PID, it can only match historical devices. That said, HID blacklisting for the limited set of [[DisplayLink|DisplayLink]] devices would be easily feasible: [[http://lxr.linux.no/linux+v2.6.30/drivers/hid/usbhid/hid-quirks.c|http://lxr.linux.no/linux+v2.6.30/drivers/hid/usbhid/hid-quirks.c]] 
+
+And for [[DisplayLink|DisplayLink]], there are many PIDs which show as Mass Storage class, and there is no important case where Linux would benefit from access to the driver, so a VID match would be better.  But the mass storage driver's logic would have to be modified to allow a VID match on all PIDs: [[http://lxr.linux.no/linux+v2.6.30/drivers/usb/storage/usual-tables.c|http://lxr.linux.no/linux+v2.6.30/drivers/usb/storage/usual-tables.c]]  
+
+
+## usb-modeswitch
+
+There are other types of devices which have similar behaviors.  Some of these use the usb-modeswitch package to allow a user to easily switch configuration.  Support for the affected [[DisplayLink|DisplayLink]] devices could be integrated with [[http://packages.debian.org/sid/usb-modeswitch|http://packages.debian.org/sid/usb-modeswitch]]  
+
+
+# Lists of DisplayLink PIDs of each type
+
+
+## Appear as USB HID
+
+Some [[DisplayLink|DisplayLink]] devices appear to be USB HID (input) devices.  They come up in a configuration other than #1, and should be switched to USB configuration #1 to enable normal use of the device.  This is done to prevent Win XP Found New Hardware Wizard from appearing when the device is connected. See "Background" below. 
+
+Affected devices as of July 2009 
+
+
+[[!format csv """
+#!CSV , 
+Product Name, PID
+Samsung Ubisync 940UX, 0x0101
+Samsung 22” monitor, 0x0105
+LG L206WU, 0x0120
+LG L226WU, 0x0121
+HP Dock, 0x01d4
+"""]]
+
+## Appear as USB Mass Storage
+
+In order to support providing Windows Drivers on device in flash, some [[DisplayLink|DisplayLink]] devices appear at boot to be CDROM devices. 
+
+These device's default USB configuration returns class code = mass storage, vendor ID = [[DisplayLink|DisplayLink]], and product ID matching the particular [[DisplayLink|DisplayLink]] device.  Only when the device is switched to configuration #1 does the device function as a display.  That configuration shows class code 0xff - vendor specific. 
+
+The following devices have this configuration, as of July 2009 
+
+
+[[!format csv """
+#!CSV , 
+ Product Name, PID
+ VNS Graphics Adapter, 0x0130
+ Graphics Adapter, 0x0137
+ test Osprey, 0x013a
+ DL-195 Adapter, 0x013C
+ USB TO DVI, 0x0140
+ 195 USB Adapter, 0x0141
+ I-O DATA LCD-USB7X, 0x0153
+ V-Jack Osprey, 0x015A
+ Nanovision MiMo, 0x016A
+ nanovision MiMo, 0x016C
+ SB TG, 0x016F
+ VL-165D Auto 061509, 0x0176
+ Touch screen mini-mo, 0x0180
+ USB LCD, 0x019F
+ Touch screen mini-mo, 0x01D0
+ MINIMONITOR, 0x01D1
+ UWB Display Adapter, 0x0208
+ VodafoneUVGA Adapter, 0x0209
+ AL5720_rev3_195_SPI, 0x020E
+ AL5730_Rev1_165_SPI, 0x0210
+ TVI USB Monitor, 0x0219
+ USB-VGA Adapter, 0x021a
+ ACCELL VGA Adapter, 0x021C
+ ACCELL USB-VGA, 0x021D
+ USB-DVI Adapter, 0x0221
+ MMD-2001B1-165, 0x0223
+ 195 USB Adapter, 0x0238
+ VT ViBook 2, 0x023D
+ ViBook Plus, 0x023E
+ MEDL display adaptor, 0x024D
+ BUFFALO FTD-W71USB, 0x025B
+ UMD-700, 0x025B
+ DL-195 Adapter, 0x025B
+ Buffalo FTD-W71USB, 0x025B
+ DL-195 Adapter, 0x025C
+ LCOS Projector SVGA, 0x0261
+ Tac-Eye USB Adaptor, 0x0275
+ IOI WVGA, 0x0280
+ IO DATA Mini Display, 0x028B
+ GH-USD7, 0x028B
+ Mini Display, 0x028B
+ Mini Monitor, 0x028E
+ AN2440D3, 0x028F
+ AN2440D3, 0x028F
+ DL-165_SPI, 0x0292
+ DL-125_SPI, 0x0293
+ WUSB-921, 0x02A3
+ USB to VGA Adapter, 0x02A4
+ UV195, 0x02A5
+ UV165, 0x02A6
+ DisplayLink Adapter, 0x02A7
+ UV-DLA1-DLRO, 0x02A7
+ USB TO DVI, 0x02A8
+ Adamo LCD Monitor, 0x02BF
+ Projector, 0x0300
+ Infocus Projector, 0x0301
+ Projector, 0x0301
+ Projector, 0x0302
+ Projector, 0x0305
+ Projector, 0x0306
+ Projector, 0x0307
+ Mini Display, 0x4012
+ nanovision MiMo, 0x401A
+ Buffalo FTD-W71USB, 0x4028
+ KTG Office Dock, 0x4032
+ Kensington Dock, 0x8032
+ Hawk, 0x8044
+ Osprey-WXGA, 0x8051
+ Pegasus DVI, 0x8063
+ Leo Dock, 0x8074
+ OllieB Dev Board, 0xC002
+ Leo Dock, 0xC032
+"""]]
+
+# Background
+
+A bit more background on the "whys", so the Linux solution can be understood: 
+
+It's not uncommon for USB devices to play some games with USB class codes, in order to improve the Windows XP install experience.  Many [[DisplayLink|DisplayLink]] devices do this.  Unfortunately, it creates a hassle for Linux.  But there are solutions, we just need to get them in place. Here's the background: 
+
+On Windows XP, the Found New Hardware Wizard pops up when any device without drivers arrives.  Unfortunately, it's a UI that users typically get lost in (without ultimately finding appropriate drivers).  Vista and now particularly Win7 do a much better job, but XP is still an important case. 
+
+To make the device install experience on XP better, companies take pains to avoid FNHW: stickers over the USB connector saying "install driver disk first", etc.  They may also have the device report a USB class code that is matched by an in-box driver that's otherwise benign, so FNHW is never shown. HID matches that bill.  Windows pnp logic is always to use the most specific driver match - so it will silently match HID initially, but once drivers are installed (e.g. from disk, or from internet) that match more specifically on VID/PID, Windows will automatically prefer those drivers over those that only match on the class code. 
+
+The second common scenario is the device may actually appear first as a USB CDROM with Windows drivers on it, and only once the proper configuration is set, it turns into the "real" device. On [[DisplayLink|DisplayLink]] devices - the core graphics function is always on configuration #1 (even if the default configuration is something else like 2, to hide the device without in-OS drivers). You can see how libdlo handles this (not smart or graceful, but does make libdlo work 100% of the time) at [[http://cgit.freedesktop.org/libdlo/tree/src/dlo_usb.c|http://cgit.freedesktop.org/libdlo/tree/src/dlo_usb.c]] around line 319. 
+
+Greg has recommended taking this approach, based on a long history of dealing with quirks of this type: 
+
+1) Actively set configuration 1 in the displaylink kernel framebuffer driver (call function [[http://lxr.linux.no/linux+v2.6.30/drivers/usb/core/usb.h#L31|http://lxr.linux.no/linux+v2.6.30/drivers/usb/core/usb.h#L31]]) 2) Because Linux doesn't have the same assumption as Windows for matching best driver based on specificity of IDs, it may (non-deterministicly?) load a HID or MSC driver instead of the real [[DisplayLink|DisplayLink]] framebuffer driver.  To avoid this problem completely, we have to add displaylink devices to the proper blacklists, e.g. as these examples of adding other devices to the HID blacklist: [[http://www.google.co.uk/search?q=linux+kernel+usb+hid+blacklist|http://www.google.co.uk/search?q=linux+kernel+usb+hid+blacklist]] 
+
+However, as mentioned above, the MSC blacklisting is messy on [[DisplayLink|DisplayLink]], and there isn't as much of a precedent for non-storage devices to be  blacklisted in the storage drivers, as would be the case here. 
+
+If someone wanted to get wild and crazy, they could also take a look at a more comprehensive solution for #2 -- better aligning Linux's plug and play assumptions about driver matching based on specificity of class/vid/pid/rev, etc. with Windows' assumptions. 
diff --git a/DeviceQuirks.moin b/DeviceQuirks.moin
deleted file mode 100644
index ed367fa..0000000
--- a/DeviceQuirks.moin
+++ /dev/null
@@ -1,206 +0,0 @@
-Some DisplayLink devices have multiple USB configurations, with the default configuration reporting a class code which will cause them to get matched with a Linux kernel input or cdrom driver, before the displaylink-mod kernel framebuffer driver has a chance to see the device. In that case, obviously the DisplayLink device will appear not to work.

-

-This happens because some DisplayLink devices come up in a default configuration other than #1 and report USB HID or USB mass storage class codes, in order to provide a special autoinstall path on Windows. 

-

-In all cases, if the USB configuration of the DisplayLink device is set to 1 (from whatever the default is, which is usually 2 for these type of devices), then the DisplayLink device will report no special class code, and will get matched against the correct driver. 

-

-So how can the devices which won't work by default be handled?

-

-= Solutions =

-

-== udev rule ==

-

-One solution may be a udev script and utility solution like this:

-

-{{{

-cat /etc/udev/rules.d/60-displaylink.rules

-# DisplayLink devices always have the active configuration on configuration #1

-SYSFS{idVendor}=="17e9", SYSFS{bConfigurationValue}=="2", RUN+="/usr/bin/dlconfig /sys%p/bConfigurationValue"

-

-cat /usr/bin/dlconfig

-#! /bin/bash

-if [ -e /sys$1/device/bConfigurationValue ]; then

-    echo 1 > /sys$1/device/bConfigurationValue

-fi;

-

-if [ -e /sys$1/bConfigurationValue ]; then

-    echo 1 > /sys$1/bConfigurationValue

-fi;

-}}}

-

-This results in the configuration being switched for DL devices. It works on both HID and MSC variants of the autoinstall. udev gets called with different device paths for HID and MSC, hence the two parts to the dlconfig script.

-

-Technically, this covers 100% of the cases.  Practically, this method may be problematic in that these short udev scripts must get picked up by every Linux distribution (or users must run them)

-

-However, for multiseat solutions, it's possible to use udev rules to find groupings of display, keyboard, mouse, etc. under the same USB hub, record that in the /dev filesystem as a seat, and then launch a (gdmdynamic) login prompt for that "seat".  If a udev script providing that kind of functionality is appealing enough to get picked up by most/all Linux distros, then setting configuration 1 for all DisplayLink devices in that script might be a good catch-all solution.  

-

-== blacklisting in the HID and mass storage (MSC) class drivers ==

-

-This has lots of precedents, but there are problems.  Some HID interfaces expose real functionality (like dock buttons) which others exist only to hide the main displaylink device to prevent unwanted Windows dialogs.  If the match is done on PID, it can only match historical devices. That said, HID blacklisting for the limited set of DisplayLink devices would be easily feasible: http://lxr.linux.no/linux+v2.6.30/drivers/hid/usbhid/hid-quirks.c

-

-And for DisplayLink, there are many PIDs which show as Mass Storage class, and there is no important case where Linux would benefit from access to the driver, so a VID match would be better.  But the mass storage driver's logic would have to be modified to allow a VID match on all PIDs: http://lxr.linux.no/linux+v2.6.30/drivers/usb/storage/usual-tables.c 

-

-== usb-modeswitch ==

-

-There are other types of devices which have similar behaviors.  Some of these use the usb-modeswitch package to allow a user to easily switch configuration.  Support for the affected DisplayLink devices could be integrated with http://packages.debian.org/sid/usb-modeswitch 

-

-= Lists of DisplayLink PIDs of each type =

-

-== Appear as USB HID ==

-

-Some DisplayLink devices appear to be USB HID (input) devices.  They come up in a configuration other than #1, and should be switched to USB configuration #1 to enable normal use of the device.  This is done to prevent Win XP Found New Hardware Wizard from appearing when the device is connected. See "Background" below.

-

-Affected devices as of July 2009

-

-{{{#!CSV ,

-Product Name, PID

-Samsung Ubisync 940UX, 0x0101

-Samsung 22” monitor, 0x0105

-LG L206WU, 0x0120

-LG L226WU, 0x0121

-HP Dock, 0x01d4

-}}}

-

-== Appear as USB Mass Storage ==

-

-In order to support providing Windows Drivers on device in flash, some DisplayLink devices appear at boot to be CDROM devices.

-

-These device's default USB configuration returns class code = mass storage, vendor ID = DisplayLink, and product ID matching the particular DisplayLink device.  Only when the device is switched to configuration #1 does the device function as a display.  That configuration shows class code 0xff - vendor specific.

-

-The following devices have this configuration, as of July 2009

-

-{{{#!CSV ,

- Product Name, PID

- VNS Graphics Adapter, 0x0130

- Graphics Adapter, 0x0137

- test Osprey, 0x013a

- DL-195 Adapter, 0x013C

- USB TO DVI, 0x0140

- 195 USB Adapter, 0x0141

- I-O DATA LCD-USB7X, 0x0153

- V-Jack Osprey, 0x015A

- Nanovision MiMo, 0x016A

- nanovision MiMo, 0x016C

- SB TG, 0x016F

- VL-165D Auto 061509, 0x0176

- Touch screen mini-mo, 0x0180

- USB LCD, 0x019F

- Touch screen mini-mo, 0x01D0

- MINIMONITOR, 0x01D1

- UWB Display Adapter, 0x0208

- VodafoneUVGA Adapter, 0x0209

- AL5720_rev3_195_SPI, 0x020E

- AL5730_Rev1_165_SPI, 0x0210

- TVI USB Monitor, 0x0219

- USB-VGA Adapter, 0x021a

- ACCELL VGA Adapter, 0x021C

- ACCELL USB-VGA, 0x021D

- USB-DVI Adapter, 0x0221

- MMD-2001B1-165, 0x0223

- 195 USB Adapter, 0x0238

- VT ViBook 2, 0x023D

- ViBook Plus, 0x023E

- MEDL display adaptor, 0x024D

- BUFFALO FTD-W71USB, 0x025B

- UMD-700, 0x025B

- DL-195 Adapter, 0x025B

- Buffalo FTD-W71USB, 0x025B

- DL-195 Adapter, 0x025C

- LCOS Projector SVGA, 0x0261

- Tac-Eye USB Adaptor, 0x0275

- IOI WVGA, 0x0280

- IO DATA Mini Display, 0x028B

- GH-USD7, 0x028B

- Mini Display, 0x028B

- Mini Monitor, 0x028E

- AN2440D3, 0x028F

- AN2440D3, 0x028F

- DL-165_SPI, 0x0292

- DL-125_SPI, 0x0293

- WUSB-921, 0x02A3

- USB to VGA Adapter, 0x02A4

- UV195, 0x02A5

- UV165, 0x02A6

- DisplayLink Adapter, 0x02A7

- UV-DLA1-DLRO, 0x02A7

- USB TO DVI, 0x02A8

- Adamo LCD Monitor, 0x02BF

- Projector, 0x0300

- Infocus Projector, 0x0301

- Projector, 0x0301

- Projector, 0x0302

- Projector, 0x0305

- Projector, 0x0306

- Projector, 0x0307

- Mini Display, 0x4012

- nanovision MiMo, 0x401A

- Buffalo FTD-W71USB, 0x4028

- KTG Office Dock, 0x4032

- Kensington Dock, 0x8032

- Hawk, 0x8044

- Osprey-WXGA, 0x8051

- Pegasus DVI, 0x8063

- Leo Dock, 0x8074

- OllieB Dev Board, 0xC002

- Leo Dock, 0xC032

-}}}

-

-= Background =

-

-A bit more background on the "whys", so the Linux solution can be understood:

-

-It's not uncommon for USB devices to play some games with USB class

-codes, in order to improve the Windows XP install experience.  Many

-DisplayLink devices do this.  Unfortunately, it creates a hassle for

-Linux.  But there are solutions, we just need to get them in place.

-Here's the background:

-

-On Windows XP, the Found New Hardware Wizard pops up when any device

-without drivers arrives.  Unfortunately, it's a UI that users

-typically get lost in (without ultimately finding appropriate

-drivers).  Vista and now particularly Win7 do a much better job, but

-XP is still an important case.

-

-To make the device install experience on XP better, companies take

-pains to avoid FNHW: stickers over the USB connector saying "install

-driver disk first", etc.  They may also have the device report a USB

-class code that is matched by an in-box driver that's otherwise

-benign, so FNHW is never shown. HID matches that bill.  Windows pnp

-logic is always to use the most specific driver match - so it will

-silently match HID initially, but once drivers are installed (e.g.

-from disk, or from internet) that match more specifically on VID/PID,

-Windows will automatically prefer those drivers over those that only

-match on the class code.

-

-The second common scenario is the device may actually appear first as

-a USB CDROM with Windows drivers on it, and only once the proper

-configuration is set, it turns into the "real" device. On DisplayLink

-devices - the core graphics function is always on configuration #1

-(even if the default configuration is something else like 2, to hide

-the device without in-OS drivers).

-You can see how libdlo handles this (not smart or graceful, but does

-make libdlo work 100% of the time) at

-http://cgit.freedesktop.org/libdlo/tree/src/dlo_usb.c around line 319.

-

-Greg has recommended taking this approach, based on a long

-history of dealing with quirks of this type:

-

-1) Actively set configuration 1 in the displaylink kernel framebuffer

-driver (call function

-http://lxr.linux.no/linux+v2.6.30/drivers/usb/core/usb.h#L31)

-2) Because Linux doesn't have the same assumption as Windows for

-matching best driver based on specificity of IDs, it may

-(non-deterministicly?) load a HID or MSC driver instead of the real

-DisplayLink framebuffer driver.  To avoid this problem completely, we

-have to add displaylink devices to the proper blacklists, e.g. as

-these examples of adding other devices to the HID blacklist:

-http://www.google.co.uk/search?q=linux+kernel+usb+hid+blacklist

-

-However, as mentioned above, the MSC blacklisting is messy on DisplayLink,

-and there isn't as much of a precedent for non-storage devices to be 

-blacklisted in the storage drivers, as would be the case here.

-

-If someone wanted to get wild and crazy, they could also take a look

-at a more comprehensive solution for #2 -- better aligning Linux's

-plug and play assumptions about driver matching based on specificity

-of class/vid/pid/rev, etc. with Windows' assumptions.