The unusual_devs guide

Recently I took over maintaining the unusual_devs.h file which is part of the usb-storage driver in the linux kernel. I hope to do more kernel development in the future, but this was a healthy start.

This document was written with corrections and input from Alan Stern. Thanks!

unusual_devs.h is where we list all hardware that is a USB Storage device but somehow needs special attention. This could be because it doesn't claim it's a USB Storage device, it could be because it incorrectly impliments the spec, or because it otherwise has special needs.

How The Entry Looks

A given entry looks like this:

UNUSUAL_DEV(id_vendor, id_product, bcdDeviceMin, bcdDeviceMax, \
               vendorName, productName,useProtocol, useTransport, \
               initFunction, flags) \

And those are:

id_vendor - vendor id, obvious, hex
id_product - product id, obvious, hex
bcdDeviceMin - lowest device number this applies to, bcd
bcdDeviceMax - highest device number this applies to, bcd
vendorName - string
productName - string
useProtocol - These are listed in protocols.h with explinations. One example:
- US_SC_DEVICE - use whatever the device claims
- see drivers/usb/storage/protocol.h for a full list and comments
useTransport - These are listed in transports.h with explinations. Examples:
- US_PR_DEVICE - use wahtever the device claims
- US_PR_CB - Contorl/Bul w/o interrupt
- see drivers/usb/storage/transport.h for a full list and comments
initFunction - Some function to do initialization more often than not, this is NULL. If it's not null, usually there's a .c file somewhere with a whole bunch of logic. These devices aren't using a standard protocol. =(
- NUL - none.
- init_8200e
- sddr09_init
- There are many more, see the file for more examples
flags - Flags. See usb.h for list of them. Here's some
- 0 - none.
- US_FL_FIX_INQUIRY - Don't send the INQUIRY command, and substitute the information in the entry for the results of the query
- US_FL_SINGLE_LUN - allow only one LUN to be used
- US_FL_NEED_OVERRIDE - explanation in usb.h is confusing -- this refers to the US_SC* and US_PR* entries, and basically surpresses the warning the kernel will give if one of these isn't needed (meaning it returns the same thing as the device).
- US_FL_FIX_CAPACITY - Capacity is returned as number of blocks instead of highest block, so subtract one.
- US_FL_SCM_MULT_TARG - For devices that act like SCSI host adapters.
- see drivers/usb/storage/usb.h for a full list and commands

Protocols are transports and transports aren't... wait, what?

You will note that the entry refers to a "protocol" and a "transport"... but the spec refers to a "SubClass" and a "Protocol".

Intuitively one might match up "protocol" with "protocol," but that would be incorrect.

The SubClassProtocol and the Protocol is the Transport.

So if your kernel tells you there is an unneeded SubClass, you need to check the "protocol" field, but if it tells you there is an unneeded Protocol, you need to check the "transport" field. Confusing, I know.