The unusual_devs.h Guide
I currently maintain 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 and Matthew Dharm. 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.
Contents
A given entry looks like this:
UNUSUAL_DEV(id_vendor, id_product, bcdDeviceMin, bcdDeviceMax, \
vendorName, productName,useProtocol, useTransport, \
initFunction, flags) \
And those fields 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 SubClass the device claims it is
- US_SC_8070 - Removable Media
- ...
- see include/linux/usb_usual.h for a full list and comments
- useTransport - These are listed in transports.h with explinations. Examples:
- US_PR_DEVICE - use whatever Protocol the device claims it is
- US_PR_CB - Control/Bulk w/o interrupt
- ...
- see include/linux/usb_usual.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. =(
- NulL - none.
- init_8200e
- sddr09_init
- There are many more, see the file for more examples
- flags - Flags that determine which "special" treatment to give a device. This field is a BITWISE OR of all flags.
- 0 - none.
- FIX_INQUIRY - Don't send the INQUIRY command, and substitute the information in the entry for the results of the query
- SINGLE_LUN - allow only one LUN to be used
- 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).
- FIX_CAPACITY - Capacity is returned as number of blocks instead of highest block, so subtract one.
- SCM_MulT_TARG - For devices that act like SCSI host adapters.
- IGNORE_RESIDUE - When devices report read or write status, they also report a residue value. Residue is the difference between how many data bytes the host guessed the device would copy in the request and how many butes the device actually agreed to copy. Thus a residue indicates some disagreement or confusion between the host and the device. This usually isn't a problem and will get resolved in further reads/writes. However, some devices falsely report residue. In this case, the US_FL_IGNORE_RESIDUE flag will tell the kernel to ignore residue values. When usb-storage is in verbose debuggin mode, on the "Bulk Status" line, the residue value is the number after the "R" - if this is non-zero multiple times in a row, you may need this flag. See here for more information.
- US_FL_MODE_XLATE - This is 2.4 only. When this is set, the 2.4 driver will translate the 6-byte formsof READ, WRITE, MODE SENSE, and MODE SELECT commands to their corrsponding 10-byte forms. In 2.6 the SCSI drivers already do this.
- see include/linux/usb_usual.h for a full list and commands
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.
What the USB spec calls a SubClass is actually defining a language the device uses - what any programmer would refer to as a "protocol." What the USB spec calls a Protocol is actually the way messages are packed for transmission - what any programmer would refer to as a "transport."
In other words, spec's SubClass is our Protocol and the spec's Protocol is our 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.
Anyone may submit a patch, but should make sure to keep in mind the following:
- Be sure to follow the kernel patch submitting policies in Documentation/SubmittingPatches
- Be sure to follow the procedures outlined at the top of the unusual_devs.h file
- Be sure to put your order in entry of VendorId, then ProductId, and then bcdDevice range.
- Be sure to add a useful comment with contact information. This is because if we ever feel the entry is no longer needed we'll want someone to contact to test for us!
- Send it to the USB subsystem list and CC me, please
Last Updated: 01/23/07
Copyright © Phil Dibowitz 2004-2008