path: root/DeviceQuirks.moin

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.