A-Team_Digital_Solutions/android_kernel_motorola_sm6375
Watch
2
0
Fork
You've already forked android_kernel_motorola_sm6375
 0
mirror of https://github.com/BobTheBlinker/android_kernel_motorola_sm6375.git synced 2026-10-28 10:41:38 -04:00
Code Issues Projects Releases Packages Wiki Activity

Linux-2.6.12-rc2

Browse source 
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!
This commit is contained in:
Linus Torvalds 2005-04-16 15:20:36 -07:00
commit 1da177e4c3
17291 changed files with 6718755 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

175
Documentation/usb/CREDITS Normal file
View file

@ -0,0 +1,175 @@
Credits for the Simple Linux USB Driver:
The following people have contributed to this code (in alphabetical
order by last name). I'm sure this list should be longer, its
difficult to maintain, add yourself with a patch if desired.
Georg Acher <[email protected]>
David Brownell <[email protected]>
Alan Cox <[email protected]>
Randy Dunlap <[email protected]>
Johannes Erdfelt <[email protected]>
Deti Fliegl <[email protected]>
ham <[email protected]>
Bradley M Keryan <[email protected]>
Greg Kroah-Hartman <[email protected]>
Pavel Machek <[email protected]>
Paul Mackerras <[email protected]>
Petko Manlolov <[email protected]>
David E. Nelson <[email protected]>
Vojtech Pavlik <[email protected]>
Bill Ryder <[email protected]>
Thomas Sailer <[email protected]>
Gregory P. Smith <[email protected]>
Linus Torvalds <[email protected]>
Roman Weissgaerber <[email protected]>
<[email protected]>
Special thanks to:
Inaky Perez Gonzalez <[email protected]> for starting the
Linux USB driver effort and writing much of the larger uusbd driver.
Much has been learned from that effort.
The NetBSD & FreeBSD USB developers. For being on the Linux USB list
and offering suggestions and sharing implementation experiences.
Additional thanks to the following companies and people for donations
of hardware, support, time and development (this is from the original
THANKS file in Inaky's driver):
The following corporations have helped us in the development
of Linux USB / UUSBD:
- 3Com GmbH for donating a ISDN Pro TA and supporting me
in technical questions and with test equipment. I'd never
expect such a great help.
- USAR Systems provided us with one of their excellent USB
Evaluation Kits. It allows us to test the Linux-USB driver
for compliance with the latest USB specification. USAR
Systems recognized the importance of an up-to-date open
Operating System and supports this project with
Hardware. Thanks!.
- Thanks to Intel Corporation for their precious help.
- We teamed up with Cherry to make Linux the first OS with
built-in USB support. Cherry is one of the biggest keyboard
makers in the world.
- CMD Technology, Inc. sponsored us kindly donating a CSA-6700
PCI-to-USB Controller Board to test the OHCI implementation.
- Due to their support to us, Keytronic can be sure that they
will sell keyboards to some of the 3 million (at least)
Linux users.
- Many thanks to ing büro h doran [http://www.ibhdoran.com]!
It was almost impossible to get a PC backplate USB connector
for the motherboard here at Europe (mine, home-made, was
quite lousy :). Now I know where to acquire nice USB stuff!
- Genius Germany donated a USB mouse to test the mouse boot
protocol. They've also donated a F-23 digital joystick and a
NetMouse Pro. Thanks!
- AVM GmbH Berlin is supporting the development of the Linux
USB driver for the AVM ISDN Controller B1 USB. AVM is a
leading manufacturer for active and passive ISDN Controllers
and CAPI 2.0-based software. The active design of the AVM B1
is open for all OS platforms, including Linux.
- Thanks to Y-E Data, Inc. for donating their FlashBuster-U
USB Floppy Disk Drive, so we could test the bulk transfer
code.
- Many thanks to Logitech for contributing a three axis USB
mouse.
Logitech designs, manufactures and markets
Human Interface Devices, having a long history and
experience in making devices such as keyboards, mice,
trackballs, cameras, loudspeakers and control devices for
gaming and professional use.
Being a recognized vendor and seller for all these devices,
they have donated USB mice, a joystick and a scanner, as a
way to acknowledge the importance of Linux and to allow
Logitech customers to enjoy support in their favorite
operating systems and all Linux users to use Logitech and
other USB hardware.
Logitech is official sponsor of the Linux Conference on
Feb. 11th 1999 in Vienna, where we'll will present the
current state of the Linux USB effort.
- CATC has provided means to uncover dark corners of the UHCI
inner workings with a USB Inspector.
- Thanks to Entrega for providing PCI to USB cards, hubs and
converter products for development.
- Thanks to ConnectTech for providing a WhiteHEAT usb to
serial converter, and the documentation for the device to
allow a driver to be written.
- Thanks to ADMtek for providing Pegasus and Pegasus II
evaluation boards, specs and valuable advices during
the driver development.
And thanks go to (hey! in no particular order :)
- Oren Tirosh <[email protected]>, for standing so patiently
all my doubts'bout USB and giving lots of cool ideas.
- Jochen Karrer <[email protected]>, for
pointing out mortal bugs and giving advice.
- Edmund Humemberger <[email protected]>, for it's great work on
public relationships and general management stuff for the
Linux-USB effort.
- Alberto Menegazzi <[email protected]> is starting the
documentation for the UUSBD. Go for it!
- Ric Klaren <[email protected]> for doing nice
introductory documents (competing with Alberto's :).
- Christian Groessler <[email protected]>, for it's help on those
itchy bits ... :)
- Paul MacKerras for polishing OHCI and pushing me harder for
the iMac support, giving improvements and enhancements.
- Fernando Herrera <[email protected]> has taken
charge of composing, maintaining and feeding the
long-awaited, unique and marvelous UUSBD FAQ! Tadaaaa!!!
- Rasca Gmelch <[email protected]> has revived the raw driver and
pointed bugs, as well as started the uusbd-utils package.
- Peter Dettori <[email protected]> is uncovering bugs like
crazy, as well as making cool suggestions, great :)
- All the Free Software and Linux community, the FSF & the GNU
project, the MIT X consortium, the TeX people ... everyone!
You know who you are!
- Big thanks to Richard Stallman for creating Emacs!
- The people at the linux-usb mailing list, for reading so
many messages :) Ok, no more kidding; for all your advises!
- All the people at the USB Implementors Forum for their
help and assistance.
- Nathan Myers <[email protected]>, for his advice! (hope you
liked Cibeles' party).
- Linus Torvalds, for starting, developing and managing Linux.
- Mike Smith, Craig Keithley, Thierry Giron and Janet Schank
for convincing me USB Standard hubs are not that standard
and that's good to allow for vendor specific quirks on the
standard hub driver.

252
Documentation/usb/URB.txt Normal file
View file

@ -0,0 +1,252 @@
Revised: 2000-Dec-05.
Again: 2002-Jul-06
NOTE:
The USB subsystem now has a substantial section in "The Linux Kernel API"
guide (in Documentation/DocBook), generated from the current source
code. This particular documentation file isn't particularly current or
complete; don't rely on it except for a quick overview.
1.1. Basic concept or 'What is an URB?'
The basic idea of the new driver is message passing, the message itself is
called USB Request Block, or URB for short.
- An URB consists of all relevant information to execute any USB transaction
and deliver the data and status back.
- Execution of an URB is inherently an asynchronous operation, i.e. the
usb_submit_urb(urb) call returns immediately after it has successfully queued
the requested action.
- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time.
- Each URB has a completion handler, which is called after the action
has been successfully completed or canceled. The URB also contains a
context-pointer for passing information to the completion handler.
- Each endpoint for a device logically supports a queue of requests.
You can fill that queue, so that the USB hardware can still transfer
data to an endpoint while your driver handles completion of another.
This maximizes use of USB bandwidth, and supports seamless streaming
of data to (or from) devices when using periodic transfer modes.
1.2. The URB structure
Some of the fields in an URB are:
struct urb
{
// (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe; // endpoint information
unsigned int transfer_flags; // ISO_ASAP, SHORT_NOT_OK, etc.
// (IN) all urbs need completion routines
void *context; // context for completion routine
void (*complete)(struct urb *); // pointer to completion routine
// (OUT) status after each completion
int status; // returned status
// (IN) buffer used for data transfers
void *transfer_buffer; // associated data buffer
int transfer_buffer_length; // data buffer length
int number_of_packets; // size of iso_frame_desc
// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
int actual_length; // actual data buffer length
// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
unsigned char* setup_packet; // setup packet (control only)
// Only for PERIODIC transfers (ISO, INTERRUPT)
// (IN/OUT) start_frame is set unless ISO_ASAP isn't set
int start_frame; // start frame
int interval; // polling interval
// ISO only: packets are only "best effort"; each can have errors
int error_count; // number of errors
struct usb_iso_packet_descriptor iso_frame_desc[0];
};
Your driver must create the "pipe" value using values from the appropriate
endpoint descriptor in an interface that it's claimed.
1.3. How to get an URB?
URBs are allocated with the following call
struct urb *usb_alloc_urb(int isoframes, int mem_flags)
Return value is a pointer to the allocated URB, 0 if allocation failed.
The parameter isoframes specifies the number of isochronous transfer frames
you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter
holds standard memory allocation flags, letting you control (among other
things) whether the underlying code may block or not.
To free an URB, use
void usb_free_urb(struct urb *urb)
You may not free an urb that you've submitted, but which hasn't yet been
returned to you in a completion callback.
1.4. What has to be filled in?
Depending on the type of transaction, there are some inline functions
defined in <linux/usb.h> to simplify the initialization, such as
fill_control_urb() and fill_bulk_urb(). In general, they need the usb
device pointer, the pipe (usual format from usb.h), the transfer buffer,
the desired transfer length, the completion handler, and its context.
Take a look at the some existing drivers to see how they're used.
Flags:
For ISO there are two startup behaviors: Specified start_frame or ASAP.
For ASAP set URB_ISO_ASAP in transfer_flags.
If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in
transfer_flags.
1.5. How to submit an URB?
Just call
int usb_submit_urb(struct urb *urb, int mem_flags)
The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
such as whether the lower levels may block when memory is tight.
It immediately returns, either with status 0 (request queued) or some
error code, usually caused by the following:
- Out of memory (-ENOMEM)
- Unplugged device (-ENODEV)
- Stalled endpoint (-EPIPE)
- Too many queued ISO transfers (-EAGAIN)
- Too many requested ISO frames (-EFBIG)
- Invalid INT interval (-EINVAL)
- More than one packet for INT (-EINVAL)
After submission, urb->status is -EINPROGRESS; however, you should never
look at that value except in your completion callback.
For isochronous endpoints, your completion handlers should (re)submit
URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
to get seamless ISO streaming.
1.6. How to cancel an already running URB?
For an URB which you've submitted, but which hasn't been returned to
your driver by the host controller, call
int usb_unlink_urb(struct urb *urb)
It removes the urb from the internal list and frees all allocated
HW descriptors. The status is changed to reflect unlinking. After
usb_unlink_urb() returns with that status code, you can free the URB
with usb_free_urb().
There is also an asynchronous unlink mode. To use this, set the
the URB_ASYNC_UNLINK flag in urb->transfer flags before calling
usb_unlink_urb(). When using async unlinking, the URB will not
normally be unlinked when usb_unlink_urb() returns. Instead, wait
for the completion handler to be called.
1.7. What about the completion handler?
The handler is of the following type:
typedef void (*usb_complete_t)(struct urb *);
i.e. it gets just the URB that caused the completion call.
In the completion handler, you should have a look at urb->status to
detect any USB errors. Since the context parameter is included in the URB,
you can pass information to the completion handler.
Note that even when an error (or unlink) is reported, data may have been
transferred. That's because USB transfers are packetized; it might take
sixteen packets to transfer your 1KByte buffer, and ten of them might
have transferred succesfully before the completion is called.
NOTE: ***** WARNING *****
Don't use urb->dev field in your completion handler; it's cleared
as part of giving urbs back to drivers. (Addressing an issue with
ownership of periodic URBs, which was otherwise ambiguous.) Instead,
use urb->context to hold all the data your driver needs.
NOTE: ***** WARNING *****
Also, NEVER SLEEP IN A COMPLETION HANDLER. These are normally called
during hardware interrupt processing. If you can, defer substantial
work to a tasklet (bottom half) to keep system latencies low. You'll
probably need to use spinlocks to protect data structures you manipulate
in completion handlers.
1.8. How to do isochronous (ISO) transfers?
For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
packet you want to schedule. You also have to set urb->interval to say
how often to make transfers; it's often one per frame (which is once
every microframe for highspeed devices). The actual interval used will
be a power of two that's no bigger than what you specify.
The usb_submit_urb() call modifies urb->interval to the implemented interval
value that is less than or equal to the requested interval value. If
ISO_ASAP scheduling is used, urb->start_frame is also updated.
For each entry you have to specify the data offset for this frame (base is
transfer_buffer), and the length you want to write/expect to read.
After completion, actual_length contains the actual transferred length and
status contains the resulting status for the ISO transfer for this frame.
It is allowed to specify a varying length from frame to frame (e.g. for
audio synchronisation/adaptive transfer rates). You can also use the length
0 to omit one or more frames (striping).
For scheduling you can choose your own start frame or ISO_ASAP. As explained
earlier, if you always keep at least one URB queued and your completion
keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
bandwidth utilization allows).
If you specify your own start frame, make sure it's several frames in advance
of the current frame. You might want this model if you're synchronizing
ISO data with some other event stream.
1.9. How to start interrupt (INT) transfers?
Interrupt transfers, like isochronous transfers, are periodic, and happen
in intervals that are powers of two (1, 2, 4 etc) units. Units are frames
for full and low speed devices, and microframes for high speed ones.
Currently, after you submit one interrupt URB, that urb is owned by the
host controller driver until you cancel it with usb_unlink_urb(). You
may unlink interrupt urbs in their completion handlers, if you need to.
After a transfer completion is called, the URB is automagically resubmitted.
THIS BEHAVIOR IS EXPECTED TO BE REMOVED!!
Interrupt transfers may only send (or receive) the "maxpacket" value for
the given interrupt endpoint; if you need more data, you will need to
copy that data out of (or into) another buffer. Similarly, you can't
queue interrupt transfers.
THESE RESTRICTIONS ARE EXPECTED TO BE REMOVED!!
Note that this automagic resubmission model does make it awkward to use
interrupt OUT transfers. The portable solution involves unlinking those
OUT urbs after the data is transferred, and perhaps submitting a final
URB for a short packet.
The usb_submit_urb() call modifies urb->interval to the implemented interval
value that is less than or equal to the requested interval value.

138
Documentation/usb/acm.txt Normal file
View file

@ -0,0 +1,138 @@
Linux ACM driver v0.16
(c) 1999 Vojtech Pavlik <[email protected]>
Sponsored by SuSE
----------------------------------------------------------------------------
0. Disclaimer
~~~~~~~~~~~~~
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA
Should you need to contact me, the author, you can do so either by e-mail
- mail your message to <[email protected]>, or by paper mail: Vojtech Pavlik,
Ucitelska 1576, Prague 8, 182 00 Czech Republic
For your convenience, the GNU General Public License version 2 is included
in the package: See the file COPYING.
1. Usage
~~~~~~~~
The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal
adapters that conform to the Universal Serial Bus Communication Device Class
Abstract Control Model (USB CDC ACM) specification.
Many modems do, here is a list of those I know of:
3Com OfficeConnect 56k
3Com Voice FaxModem Pro
3Com Sportster
MultiTech MultiModem 56k
Zoom 2986L FaxModem
Compaq 56k FaxModem
ELSA Microlink 56k
I know of one ISDN TA that does work with the acm driver:
3Com USR ISDN Pro TA
Unfortunately many modems and most ISDN TAs use proprietary interfaces and
thus won't work with this drivers. Check for ACM compliance before buying.
The driver (with devfs) creates these devices in /dev/usb/acm:
crw-r--r-- 1 root root 166, 0 Apr 1 10:49 0
crw-r--r-- 1 root root 166, 1 Apr 1 10:49 1
crw-r--r-- 1 root root 166, 2 Apr 1 10:49 2
And so on, up to 31, with the limit being possible to change in acm.c to up
to 256, so you can use up to 256 USB modems with one computer (you'll need
three USB cards for that, though).
If you don't use devfs, then you can create device nodes with the same
minor/major numbers anywhere you want, but either the above location or
/dev/usb/ttyACM0 is preferred.
To use the modems you need these modules loaded:
usbcore.ko
uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko
cdc-acm.ko
After that, the modem[s] should be accessible. You should be able to use
minicom, ppp and mgetty with them.
2. Verifying that it works
~~~~~~~~~~~~~~~~~~~~~~~~~~
The first step would be to check /proc/bus/usb/devices, it should look
like this:
T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
B: Alloc= 0/900 us ( 0%), #Int= 0, #Iso= 0
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0000 ProdID=0000 Rev= 0.00
S: Product=USB UHCI Root Hub
S: SerialNumber=6800
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2
P: Vendor=04c1 ProdID=008f Rev= 2.07
S: Manufacturer=3Com Inc.
S: Product=3Com U.S. Robotics Pro ISDN TA
S: SerialNumber=UFT53A49BVT7
C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm
E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms
C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
The presence of these three lines (and the Cls= 'comm' and 'data' classes)
is important, it means it's an ACM device. The Driver=acm means the acm
driver is used for the device. If you see only Cls=ff(vend.) then you're out
of luck, you have a device with vendor specific-interface.
D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
In the system log you should see:
usb.c: USB new device connect, assigned device number 2
usb.c: kmalloc IF c7691fa0, numif 1
usb.c: kmalloc IF c7b5f3e0, numif 2
usb.c: skipped 4 class/vendor specific interface descriptors
usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3
usb.c: USB device number 2 default language ID 0x409
Manufacturer: 3Com Inc.
Product: 3Com U.S. Robotics Pro ISDN TA
SerialNumber: UFT53A49BVT7
acm.c: probing config 1
acm.c: probing config 2
ttyACM0: USB ACM device
acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0
acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7
usb.c: acm driver claimed interface c7b5f3e0
usb.c: acm driver claimed interface c7b5f3f8
usb.c: acm driver claimed interface c7691fa0
If all this seems to be OK, fire up minicom and set it to talk to the ttyACM
device and try typing 'at'. If it responds with 'OK', then everything is
working.

30
Documentation/usb/auerswald.txt Normal file
View file

@ -0,0 +1,30 @@
Auerswald USB kernel driver
===========================
What is it? What can I do with it?
==================================
The auerswald USB kernel driver connects your linux 2.4.x
system to the auerswald usb-enabled devices.
There are two types of auerswald usb devices:
a) small PBX systems (ISDN)
b) COMfort system telephones (ISDN)
The driver installation creates the devices
/dev/usb/auer0..15. These devices carry a vendor-
specific protocol. You may run all auerswald java
software on it. The java software needs a native
library "libAuerUsbJNINative.so" installed on
your system. This library is available from
auerswald and shipped as part of the java software.
You may create the devices with:
mknod -m 666 /dev/usb/auer0 c 180 112
...
mknod -m 666 /dev/usb/auer15 c 180 127
Future plans
============
- Connection to ISDN4LINUX (the hisax interface)
The maintainer of this driver is [email protected]

44
Documentation/usb/bluetooth.txt Normal file
View file

@ -0,0 +1,44 @@
INTRODUCTION
The USB Bluetooth driver supports any USB Bluetooth device.
It currently works well with the Linux USB Bluetooth stack from Axis
(available at http://developer.axis.com/software/bluetooth/ ) and
has been rumored to work with other Linux USB Bluetooth stacks.
CONFIGURATION
Currently the driver can handle up to 256 different USB Bluetooth
devices at once.
If you are not using devfs:
The major number that the driver uses is 216 so to use the driver,
create the following nodes:
mknod /dev/ttyUB0 c 216 0
mknod /dev/ttyUB1 c 216 1
mknod /dev/ttyUB2 c 216 2
mknod /dev/ttyUB3 c 216 3
.
.
.
mknod /dev/ttyUB254 c 216 254
mknod /dev/ttyUB255 c 216 255
If you are using devfs:
The devices supported by this driver will show up as
/dev/usb/ttub/{0,1,...}
When the device is connected and recognized by the driver, the driver
will print to the system log, which node the device has been bound to.
CONTACT:
If anyone has any problems using this driver, please contact me, or
join the Linux-USB mailing list (information on joining the mailing
list, as well as a link to its searchable archive is at
http://www.linux-usb.org/ )
Greg Kroah-Hartman
[email protected]

116
Documentation/usb/dma.txt Normal file
View file

@ -0,0 +1,116 @@
In Linux 2.5 kernels (and later), USB device drivers have additional control
over how DMA may be used to perform I/O operations. The APIs are detailed
in the kernel usb programming guide (kerneldoc, from the source code).
API OVERVIEW
The big picture is that USB drivers can continue to ignore most DMA issues,
though they still must provide DMA-ready buffers (see DMA-mapping.txt).
That's how they've worked through the 2.4 (and earlier) kernels.
OR: they can now be DMA-aware.
- New calls enable DMA-aware drivers, letting them allocate dma buffers and
manage dma mappings for existing dma-ready buffers (see below).
- URBs have an additional "transfer_dma" field, as well as a transfer_flags
bit saying if it's valid. (Control requests also have "setup_dma" and a
corresponding transfer_flags bit.)
- "usbcore" will map those DMA addresses, if a DMA-aware driver didn't do
it first and set URB_NO_TRANSFER_DMA_MAP or URB_NO_SETUP_DMA_MAP. HCDs
don't manage dma mappings for URBs.
- There's a new "generic DMA API", parts of which are usable by USB device
drivers. Never use dma_set_mask() on any USB interface or device; that
would potentially break all devices sharing that bus.
ELIMINATING COPIES
It's good to avoid making CPUs copy data needlessly. The costs can add up,
and effects like cache-trashing can impose subtle penalties.
- When you're allocating a buffer for DMA purposes anyway, use the buffer
primitives. Think of them as kmalloc and kfree that give you the right
kind of addresses to store in urb->transfer_buffer and urb->transfer_dma,
while guaranteeing that no hidden copies through DMA "bounce" buffers will
slow things down. You'd also set URB_NO_TRANSFER_DMA_MAP in
urb->transfer_flags:
void *usb_buffer_alloc (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
void usb_buffer_free (struct usb_device *dev, size_t size,
void *addr, dma_addr_t dma);
For control transfers you can use the buffer primitives or not for each
of the transfer buffer and setup buffer independently. Set the flag bits
URB_NO_TRANSFER_DMA_MAP and URB_NO_SETUP_DMA_MAP to indicate which
buffers you have prepared. For non-control transfers URB_NO_SETUP_DMA_MAP
is ignored.
The memory buffer returned is "dma-coherent"; sometimes you might need to
force a consistent memory access ordering by using memory barriers. It's
not using a streaming DMA mapping, so it's good for small transfers on
systems where the I/O would otherwise tie up an IOMMU mapping. (See
Documentation/DMA-mapping.txt for definitions of "coherent" and "streaming"
DMA mappings.)
Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
space-efficient.
- Devices on some EHCI controllers could handle DMA to/from high memory.
Driver probe() routines can notice this using a generic DMA call, then
tell higher level code (network, scsi, etc) about it like this:
if (dma_supported (&intf->dev, 0xffffffffffffffffULL))
net->features |= NETIF_F_HIGHDMA;
That can eliminate dma bounce buffering of requests that originate (or
terminate) in high memory, in cases where the buffers aren't allocated
with usb_buffer_alloc() but instead are dma-mapped.
WORKING WITH EXISTING BUFFERS
Existing buffers aren't usable for DMA without first being mapped into the
DMA address space of the device.
- When you're using scatterlists, you can map everything at once. On some
systems, this kicks in an IOMMU and turns the scatterlists into single
DMA transactions:
int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
struct scatterlist *sg, int nents);
void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe,
struct scatterlist *sg, int n_hw_ents);
void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe,
struct scatterlist *sg, int n_hw_ents);
It's probably easier to use the new usb_sg_*() calls, which do the DMA
mapping and apply other tweaks to make scatterlist i/o be fast.
- Some drivers may prefer to work with the model that they're mapping large
buffers, synchronizing their safe re-use. (If there's no re-use, then let
usbcore do the map/unmap.) Large periodic transfers make good examples
here, since it's cheaper to just synchronize the buffer than to unmap it
each time an urb completes and then re-map it on during resubmission.
These calls all work with initialized urbs: urb->dev, urb->pipe,
urb->transfer_buffer, and urb->transfer_buffer_length must all be
valid when these calls are used (urb->setup_packet must be valid too
if urb is a control request):
struct urb *usb_buffer_map (struct urb *urb);
void usb_buffer_dmasync (struct urb *urb);
void usb_buffer_unmap (struct urb *urb);
The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP
so that usbcore won't map or unmap the buffer. The same goes for
urb->setup_dma and URB_NO_SETUP_DMA_MAP for control requests.

212
Documentation/usb/ehci.txt Normal file
View file

@ -0,0 +1,212 @@
27-Dec-2002
The EHCI driver is used to talk to high speed USB 2.0 devices using
USB 2.0-capable host controller hardware. The USB 2.0 standard is
compatible with the USB 1.1 standard. It defines three transfer speeds:
- "High Speed" 480 Mbit/sec (60 MByte/sec)
- "Full Speed" 12 Mbit/sec (1.5 MByte/sec)
- "Low Speed" 1.5 Mbit/sec
USB 1.1 only addressed full speed and low speed. High speed devices
can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds.
USB 1.1 devices may also be used on USB 2.0 systems. When plugged
into an EHCI controller, they are given to a USB 1.1 "companion"
controller, which is a OHCI or UHCI controller as normally used with
such devices. When USB 1.1 devices plug into USB 2.0 hubs, they
interact with the EHCI controller through a "Transaction Translator"
(TT) in the hub, which turns low or full speed transactions into
high speed "split transactions" that don't waste transfer bandwidth.
At this writing, this driver has been seen to work with implementations
of EHCI from (in alphabetical order): Intel, NEC, Philips, and VIA.
Other EHCI implementations are becoming available from other vendors;
you should expect this driver to work with them too.
While usb-storage devices have been available since mid-2001 (working
quite speedily on the 2.4 version of this driver), hubs have only
been available since late 2001, and other kinds of high speed devices
appear to be on hold until more systems come with USB 2.0 built-in.
Such new systems have been available since early 2002, and became much
more typical in the second half of 2002.
Note that USB 2.0 support involves more than just EHCI. It requires
other changes to the Linux-USB core APIs, including the hub driver,
but those changes haven't needed to really change the basic "usbcore"
APIs exposed to USB device drivers.
- David Brownell
<[email protected]>
FUNCTIONALITY
This driver is regularly tested on x86 hardware, and has also been
used on PPC hardware so big/little endianness issues should be gone.
It's believed to do all the right PCI magic so that I/O works even on
systems with interesting DMA mapping issues.
Transfer Types
At this writing the driver should comfortably handle all control, bulk,
and interrupt transfers, including requests to USB 1.1 devices through
transaction translators (TTs) in USB 2.0 hubs. But you may find bugs.
High Speed Isochronous (ISO) transfer support is also functional, but
at this writing no Linux drivers have been using that support.
Full Speed Isochronous transfer support, through transaction translators,
is not yet available. Note that split transaction support for ISO
transfers can't share much code with the code for high speed ISO transfers,
since EHCI represents these with a different data structure. So for now,
most USB audio and video devices can't be connected to high speed buses.
Driver Behavior
Transfers of all types can be queued. This means that control transfers
from a driver on one interface (or through usbfs) won't interfere with
ones from another driver, and that interrupt transfers can use periods
of one frame without risking data loss due to interrupt processing costs.
The EHCI root hub code hands off USB 1.1 devices to its companion
controller. This driver doesn't need to know anything about those
drivers; a OHCI or UHCI driver that works already doesn't need to change
just because the EHCI driver is also present.
There are some issues with power management; suspend/resume doesn't
behave quite right at the moment.
Also, some shortcuts have been taken with the scheduling periodic
transactions (interrupt and isochronous transfers). These place some
limits on the number of periodic transactions that can be scheduled,
and prevent use of polling intervals of less than one frame.
USE BY
Assuming you have an EHCI controller (on a PCI card or motherboard)
and have compiled this driver as a module, load this like:
# modprobe ehci-hcd
and remove it by:
# rmmod ehci-hcd
You should also have a driver for a "companion controller", such as
"ohci-hcd" or "uhci-hcd". In case of any trouble with the EHCI driver,
remove its module and then the driver for that companion controller will
take over (at lower speed) all the devices that were previously handled
by the EHCI driver.
Module parameters (pass to "modprobe") include:
log2_irq_thresh (default 0):
Log2 of default interrupt delay, in microframes. The default
value is 0, indicating 1 microframe (125 usec). Maximum value
is 6, indicating 2^6 = 64 microframes. This controls how often
the EHCI controller can issue interrupts.
If you're using this driver on a 2.5 kernel, and you've enabled USB
debugging support, you'll see three files in the "sysfs" directory for
any EHCI controller:
"async" dumps the asynchronous schedule, used for control
and bulk transfers. Shows each active qh and the qtds
pending, usually one qtd per urb. (Look at it with
usb-storage doing disk I/O; watch the request queues!)
"periodic" dumps the periodic schedule, used for interrupt
and isochronous transfers. Doesn't show qtds.
"registers" show controller register state, and
The contents of those files can help identify driver problems.
Device drivers shouldn't care whether they're running over EHCI or not,
but they may want to check for "usb_device->speed == USB_SPEED_HIGH".
High speed devices can do things that full speed (or low speed) ones
can't, such as "high bandwidth" periodic (interrupt or ISO) transfers.
Also, some values in device descriptors (such as polling intervals for
periodic transfers) use different encodings when operating at high speed.
However, do make a point of testing device drivers through USB 2.0 hubs.
Those hubs report some failures, such as disconnections, differently when
transaction translators are in use; some drivers have been seen to behave
badly when they see different faults than OHCI or UHCI report.
PERFORMANCE
USB 2.0 throughput is gated by two main factors: how fast the host
controller can process requests, and how fast devices can respond to
them. The 480 Mbit/sec "raw transfer rate" is obeyed by all devices,
but aggregate throughput is also affected by issues like delays between
individual high speed packets, driver intelligence, and of course the
overall system load. Latency is also a performance concern.
Bulk transfers are most often used where throughput is an issue. It's
good to keep in mind that bulk transfers are always in 512 byte packets,
and at most 13 of those fit into one USB 2.0 microframe. Eight USB 2.0
microframes fit in a USB 1.1 frame; a microframe is 1 msec/8 = 125 usec.
So more than 50 MByte/sec is available for bulk transfers, when both
hardware and device driver software allow it. Periodic transfer modes
(isochronous and interrupt) allow the larger packet sizes which let you
approach the quoted 480 MBit/sec transfer rate.
Hardware Performance
At this writing, individual USB 2.0 devices tend to max out at around
20 MByte/sec transfer rates. This is of course subject to change;
and some devices now go faster, while others go slower.
The first NEC implementation of EHCI seems to have a hardware bottleneck
at around 28 MByte/sec aggregate transfer rate. While this is clearly
enough for a single device at 20 MByte/sec, putting three such devices
onto one bus does not get you 60 MByte/sec. The issue appears to be
that the controller hardware won't do concurrent USB and PCI access,
so that it's only trying six (or maybe seven) USB transactions each
microframe rather than thirteen. (Seems like a reasonable trade off
for a product that beat all the others to market by over a year!)
It's expected that newer implementations will better this, throwing
more silicon real estate at the problem so that new motherboard chip
sets will get closer to that 60 MByte/sec target. That includes an
updated implementation from NEC, as well as other vendors' silicon.
There's a minimum latency of one microframe (125 usec) for the host
to receive interrupts from the EHCI controller indicating completion
of requests. That latency is tunable; there's a module option. By
default ehci-hcd driver uses the minimum latency, which means that if
you issue a control or bulk request you can often expect to learn that
it completed in less than 250 usec (depending on transfer size).
Software Performance
To get even 20 MByte/sec transfer rates, Linux-USB device drivers will
need to keep the EHCI queue full. That means issuing large requests,
or using bulk queuing if a series of small requests needs to be issued.
When drivers don't do that, their performance results will show it.
In typical situations, a usb_bulk_msg() loop writing out 4 KB chunks is
going to waste more than half the USB 2.0 bandwidth. Delays between the
I/O completion and the driver issuing the next request will take longer
than the I/O. If that same loop used 16 KB chunks, it'd be better; a
sequence of 128 KB chunks would waste a lot less.
But rather than depending on such large I/O buffers to make synchronous
I/O be efficient, it's better to just queue up several (bulk) requests
to the HC, and wait for them all to complete (or be canceled on error).
Such URB queuing should work with all the USB 1.1 HC drivers too.
In the Linux 2.5 kernels, new usb_sg_*() api calls have been defined; they
queue all the buffers from a scatterlist. They also use scatterlist DMA
mapping (which might apply an IOMMU) and IRQ reduction, all of which will
help make high speed transfers run as fast as they can.
TBD: Interrupt and ISO transfer performance issues. Those periodic
transfers are fully scheduled, so the main issue is likely to be how
to trigger "high bandwidth" modes.

167
Documentation/usb/error-codes.txt Normal file
View file

@ -0,0 +1,167 @@
Revised: 2004-Oct-21
This is the documentation of (hopefully) all possible error codes (and
their interpretation) that can be returned from usbcore.
Some of them are returned by the Host Controller Drivers (HCDs), which
device drivers only see through usbcore. As a rule, all the HCDs should
behave the same except for transfer speed dependent behaviors and the
way certain faults are reported.
**************************************************************************
* Error codes returned by usb_submit_urb *
**************************************************************************
Non-USB-specific:
0 URB submission went fine
-ENOMEM no memory for allocation of internal structures
USB-specific:
-ENODEV specified USB-device or bus doesn't exist
-ENOENT specified interface or endpoint does not exist or
is not enabled
-ENXIO host controller driver does not support queuing of this type
of urb. (treat as a host controller bug.)
-EINVAL a) Invalid transfer type specified (or not supported)
b) Invalid or unsupported periodic transfer interval
c) ISO: attempted to change transfer interval
d) ISO: number_of_packets is < 0
e) various other cases
-EAGAIN a) specified ISO start frame too early
b) (using ISO-ASAP) too much scheduled for the future
wait some time and try again.
-EFBIG Host controller driver can't schedule that many ISO frames.
-EPIPE Specified endpoint is stalled. For non-control endpoints,
reset this status with usb_clear_halt().
-EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable
in the current interface altsetting.
(b) ISO packet is biger than endpoint maxpacket
(c) requested data transfer size is invalid (negative)
-ENOSPC This request would overcommit the usb bandwidth reserved
for periodic transfers (interrupt, isochronous).
-ESHUTDOWN The device or host controller has been disabled due to some
problem that could not be worked around.
-EPERM Submission failed because urb->reject was set.
-EHOSTUNREACH URB was rejected because the device is suspended.
**************************************************************************
* Error codes returned by in urb->status *
* or in iso_frame_desc[n].status (for ISO) *
**************************************************************************
USB device drivers may only test urb status values in completion handlers.
This is because otherwise there would be a race between HCDs updating
these values on one CPU, and device drivers testing them on another CPU.
A transfer's actual_length may be positive even when an error has been
reported. That's because transfers often involve several packets, so that
one or more packets could finish before an error stops further endpoint I/O.
0 Transfer completed successfully
-ENOENT URB was synchronously unlinked by usb_unlink_urb
-EINPROGRESS URB still pending, no results yet
(That is, if drivers see this it's a bug.)
-EPROTO (*, **) a) bitstuff error
b) no response packet received within the
prescribed bus turn-around time
c) unknown USB error
-EILSEQ (*, **) a) CRC mismatch
b) no response packet received within the
prescribed bus turn-around time
c) unknown USB error
Note that often the controller hardware does not
distinguish among cases a), b), and c), so a
driver cannot tell whether there was a protocol
error, a failure to respond (often caused by
device disconnect), or some other fault.
-ETIMEDOUT (**) No response packet received within the prescribed
bus turn-around time. This error may instead be
reported as -EPROTO or -EILSEQ.
Note that the synchronous USB message functions
also use this code to indicate timeout expired
before the transfer completed.
-EPIPE (**) Endpoint stalled. For non-control endpoints,
reset this status with usb_clear_halt().
-ECOMM During an IN transfer, the host controller
received data from an endpoint faster than it
could be written to system memory
-ENOSR During an OUT transfer, the host controller
could not retrieve data from system memory fast
enough to keep up with the USB data rate
-EOVERFLOW (*) The amount of data returned by the endpoint was
greater than either the max packet size of the
endpoint or the remaining buffer size. "Babble".
-EREMOTEIO The data read from the endpoint did not fill the
specified buffer, and URB_SHORT_NOT_OK was set in
urb->transfer_flags.
-ENODEV Device was removed. Often preceded by a burst of
other errors, since the hub driver does't detect
device removal events immediately.
-EXDEV ISO transfer only partially completed
look at individual frame status for details
-EINVAL ISO madness, if this happens: Log off and go home
-ECONNRESET URB was asynchronously unlinked by usb_unlink_urb
-ESHUTDOWN The device or host controller has been disabled due
to some problem that could not be worked around,
such as a physical disconnect.
(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate
hardware problems such as bad devices (including firmware) or cables.
(**) This is also one of several codes that different kinds of host
controller use to to indicate a transfer has failed because of device
disconnect. In the interval before the hub driver starts disconnect
processing, devices may receive such fault reports for every request.
**************************************************************************
* Error codes returned by usbcore-functions *
* (expect also other submit and transfer status codes) *
**************************************************************************
usb_register():
-EINVAL error during registering new driver
usb_get_*/usb_set_*():
usb_control_msg():
usb_bulk_msg():
-ETIMEDOUT Timeout expired before the transfer completed.
In the future this code may change to -ETIME,
whose definition is a closer match to this sort
of error.

332
Documentation/usb/gadget_serial.txt Normal file
View file

@ -0,0 +1,332 @@
Linux Gadget Serial Driver v2.0
11/20/2004
License and Disclaimer
----------------------
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.
This document and the the gadget serial driver itself are
Copyright (C) 2004 by Al Borchers ([email protected]).
If you have questions, problems, or suggestions for this driver
please contact Al Borchers at [email protected].
Prerequisites
-------------
Versions of the gadget serial driver are available for the
2.4 Linux kernels, but this document assumes you are using
version 2.0 or later of the gadget serial driver in a 2.6
Linux kernel.
This document assumes that you are familiar with Linux and
Windows and know how to configure and build Linux kernels, run
standard utilities, use minicom and HyperTerminal, and work with
USB and serial devices. It also assumes you configure the Linux
gadget and usb drivers as modules.
Overview
--------
The gadget serial driver is a Linux USB gadget driver, a USB device
side driver. It runs on a Linux system that has USB device side
hardware; for example, a PDA, an embedded Linux system, or a PC
with a USB development card.
The gadget serial driver talks over USB to either a CDC ACM driver
or a generic USB serial driver running on a host PC.
Host
--------------------------------------
| Host-Side CDC ACM USB Host |
| Operating | or | Controller | USB
| System | Generic USB | Driver |--------
| (Linux or | Serial | and | |
| Windows) Driver USB Stack | |
-------------------------------------- |
|
|
|
Gadget |
-------------------------------------- |
| Gadget USB Periph. | |
| Device-Side | Gadget | Controller | |
| Linux | Serial | Driver |--------
| Operating | Driver | and |
| System USB Stack |
--------------------------------------
On the device-side Linux system, the gadget serial driver looks
like a serial device.
On the host-side system, the gadget serial device looks like a
CDC ACM compliant class device or a simple vendor specific device
with bulk in and bulk out endpoints, and it is treated similarly
to other serial devices.
The host side driver can potentially be any ACM compliant driver
or any driver that can talk to a device with a simple bulk in/out
interface. Gadget serial has been tested with the Linux ACM driver,
the Windows usbser.sys ACM driver, and the Linux USB generic serial
driver.
With the gadget serial driver and the host side ACM or generic
serial driver running, you should be able to communicate between
the host and the gadget side systems as if they were connected by a
serial cable.
The gadget serial driver only provides simple unreliable data
communication. It does not yet handle flow control or many other
features of normal serial devices.
Installing the Gadget Serial Driver
-----------------------------------
To use the gadget serial driver you must configure the Linux gadget
side kernel for "Support for USB Gadgets", for a "USB Peripheral
Controller" (for example, net2280), and for the "Serial Gadget"
driver. All this are listed under "USB Gadget Support" when
configuring the kernel. Then rebuild and install the kernel or
modules.
The gadget serial driver uses major number 127, for now. So you
will need to create a device node for it, like this:
mknod /dev/ttygserial c 127 0
You only need to do this once.
Then you must load the gadget serial driver. To load it as an
ACM device, do this:
modprobe g_serial use_acm=1
To load it as a vendor specific bulk in/out device, do this:
modprobe g_serial
This will also automatically load the underlying gadget peripheral
controller driver. This must be done each time you reboot the gadget
side Linux system. You can add this to the start up scripts, if
desired.
If gadget serial is loaded as an ACM device you will want to use
either the Windows or Linux ACM driver on the host side. If gadget
serial is loaded as a bulk in/out device, you will want to use the
Linux generic serial driver on the host side. Follow the appropriate
instructions below to install the host side driver.
Installing the Windows Host ACM Driver
--------------------------------------
To use the Windows ACM driver you must have the files "gserial.inf"
and "usbser.sys" together in a folder on the Windows machine.
The "gserial.inf" file is given here.
-------------------- CUT HERE --------------------
[Version]
Signature="$Windows NT$"
Class=Ports
ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318}
Provider=%LINUX%
DriverVer=08/17/2004,0.0.2.0
; Copyright (C) 2004 Al Borchers ([email protected])
[Manufacturer]
%LINUX%=GSerialDeviceList
[GSerialDeviceList]
%GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7
[DestinationDirs]
DefaultDestDir=10,System32\Drivers
[GSerialInstall]
CopyFiles=GSerialCopyFiles
AddReg=GSerialAddReg
[GSerialCopyFiles]
usbser.sys
[GSerialAddReg]
HKR,,DevLoader,,*ntkern
HKR,,NTMPDriver,,usbser.sys
HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider"
[GSerialInstall.Services]
AddService = usbser,0x0002,GSerialService
[GSerialService]
DisplayName = %GSERIAL_DISPLAY_NAME%
ServiceType = 1 ; SERVICE_KERNEL_DRIVER
StartType = 3 ; SERVICE_DEMAND_START
ErrorControl = 1 ; SERVICE_ERROR_NORMAL
ServiceBinary = %10%\System32\Drivers\usbser.sys
LoadOrderGroup = Base
[Strings]
LINUX = "Linux"
GSERIAL = "Gadget Serial"
GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver"
-------------------- CUT HERE --------------------
The "usbser.sys" file comes with various versions of Windows.
For example, it can be found on Windows XP typically in
C:\WINDOWS\Driver Cache\i386\driver.cab
Or it can be found on the Windows 98SE CD in the "win98" folder
in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will
need the DOS "expand" program, the Cygwin "cabextract" program, or
a similar program to unpack these cab files and extract "usbser.sys".
For example, to extract "usbser.sys" into the current directory
on Windows XP, open a DOS window and run a command like
expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys .
(Thanks to Nishant Kamat for pointing out this DOS command.)
When the gadget serial driver is loaded and the USB device connected
to the Windows host with a USB cable, Windows should recognize the
gadget serial device and ask for a driver. Tell Windows to find the
driver in the folder that contains "gserial.inf" and "usbser.sys".
For example, on Windows XP, when the gadget serial device is first
plugged in, the "Found New Hardware Wizard" starts up. Select
"Install from a list or specific location (Advanced)", then on
the next screen select "Include this location in the search" and
enter the path or browse to the folder containing "gserial.inf" and
"usbser.sys". Windows will complain that the Gadget Serial driver
has not passed Windows Logo testing, but select "Continue anyway"
and finish the driver installation.
On Windows XP, in the "Device Manager" (under "Control Panel",
"System", "Hardware") expand the "Ports (COM & LPT)" entry and you
should see "Gadget Serial" listed as the driver for one of the COM
ports.
To uninstall the Windows XP driver for "Gadget Serial", right click
on the "Gadget Serial" entry in the "Device Manager" and select
"Uninstall".
Installing the Linux Host ACM Driver
------------------------------------
To use the Linux ACM driver you must configure the Linux host side
kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM)
support".
Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command
cat /proc/bus/usb/devices
should show something like this:
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a7 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial
S: SerialNumber=0
C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms
I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
If the host side Linux system is configured properly, the ACM driver
should be loaded automatically. The command "lsmod" should show the
"acm" module is loaded.
Installing the Linux Host Generic USB Serial Driver
---------------------------------------------------
To use the Linux generic USB serial driver you must configure the
Linux host side kernel for "Support for Host-side USB", for "USB
Serial Converter support", and for the "USB Generic Serial Driver".
Once the gadget serial driver is loaded and the USB device connected
to the Linux host with a USB cable, the host system should recognize
the gadget serial device. For example, the command
cat /proc/bus/usb/devices
should show something like this:
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0
D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
P: Vendor=0525 ProdID=a4a6 Rev= 2.01
S: Manufacturer=Linux 2.6.8.1 with net2280
S: Product=Gadget Serial
S: SerialNumber=0
C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA
I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
You must explicitly load the usbserial driver with parameters to
configure it to recognize the gadget serial device, like this:
modprobe usbserial vendor=0x0525 product=0xA4A6
If everything is working, usbserial will print a message in the
system log saying something like "Gadget Serial converter now
attached to ttyUSB0".
Testing with Minicom or HyperTerminal
-------------------------------------
Once the gadget serial driver and the host driver are both installed,
and a USB cable connects the gadget device to the host, you should
be able to communicate over USB between the gadget and host systems.
You can use minicom or HyperTerminal to try this out.
On the gadget side run "minicom -s" to configure a new minicom
session. Under "Serial port setup" set "/dev/ttygserial" as the
"Serial Device". Set baud rate, data bits, parity, and stop bits,
to 9600, 8, none, and 1--these settings mostly do not matter.
Under "Modem and dialing" erase all the modem and dialing strings.
On a Linux host running the ACM driver, configure minicom similarly
but use "/dev/ttyACM0" as the "Serial Device". (If you have other
ACM devices connected, change the device name appropriately.)
On a Linux host running the USB generic serial driver, configure
minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device".
(If you have other USB serial devices connected, change the device
name appropriately.)
On a Windows host configure a new HyperTerminal session to use the
COM port assigned to Gadget Serial. The "Port Settings" will be
set automatically when HyperTerminal connects to the gadget serial
device, so you can leave them set to the default values--these
settings mostly do not matter.
With minicom configured and running on the gadget side and with
minicom or HyperTerminal configured and running on the host side,
you should be able to send data back and forth between the gadget
side and host side systems. Anything you type on the terminal
window on the gadget side should appear in the terminal window on
the host side and vice versa.

205
Documentation/usb/hiddev.txt Normal file
View file

@ -0,0 +1,205 @@
Care and feeding of your Human Interface Devices
INTRODUCTION
In addition to the normal input type HID devices, USB also uses the
human interface device protocols for things that are not really human
interfaces, but have similar sorts of communication needs. The two big
examples for this are power devices (especially uninterruptable power
supplies) and monitor control on higher end monitors.
To support these disparite requirements, the Linux USB system provides
HID events to two separate interfaces:
* the input subsystem, which converts HID events into normal input
device interfaces (such as keyboard, mouse and joystick) and a
normalised event interface - see Documentation/input/input.txt
* the hiddev interface, which provides fairly raw HID events
The data flow for a HID event produced by a device is something like
the following :
usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
|
|
--> hiddev.c ----> POWER / MONITOR CONTROL
In addition, other subsystems (apart from USB) can potentially feed
events into the input subsystem, but these have no effect on the hid
device interface.
USING THE HID DEVICE INTERFACE
The hiddev interface is a char interface using the normal USB major,
with the minor numbers starting at 96 and finishing at 111. Therefore,
you need the following commands:
mknod /dev/usb/hiddev0 c 180 96
mknod /dev/usb/hiddev1 c 180 97
mknod /dev/usb/hiddev2 c 180 98
mknod /dev/usb/hiddev3 c 180 99
mknod /dev/usb/hiddev4 c 180 100
mknod /dev/usb/hiddev5 c 180 101
mknod /dev/usb/hiddev6 c 180 102
mknod /dev/usb/hiddev7 c 180 103
mknod /dev/usb/hiddev8 c 180 104
mknod /dev/usb/hiddev9 c 180 105
mknod /dev/usb/hiddev10 c 180 106
mknod /dev/usb/hiddev11 c 180 107
mknod /dev/usb/hiddev12 c 180 108
mknod /dev/usb/hiddev13 c 180 109
mknod /dev/usb/hiddev14 c 180 110
mknod /dev/usb/hiddev15 c 180 111
So you point your hiddev compliant user-space program at the correct
interface for your device, and it all just works.
Assuming that you have a hiddev compliant user-space program, of
course. If you need to write one, read on.
THE HIDDEV API
This description should be read in conjunction with the HID
specification, freely available from http://www.usb.org, and
conveniently linked of http://www.linux-usb.org.
The hiddev API uses a read() interface, and a set of ioctl() calls.
HID devices exchange data with the host computer using data
bundles called "reports". Each report is divided into "fields",
each of which can have one or more "usages". In the hid-core,
each one of these usages has a single signed 32 bit value.
read():
This is the event interface. When the HID device's state changes,
it performs an interrupt transfer containing a report which contains
the changed value. The hid-core.c module parses the report, and
returns to hiddev.c the individual usages that have changed within
the report. In its basic mode, the hiddev will make these individual
usage changes available to the reader using a struct hiddev_event:
struct hiddev_event {
unsigned hid;
signed int value;
};
containing the HID usage identifier for the status that changed, and
the value that it was changed to. Note that the structure is defined
within <linux/hiddev.h>, along with some other useful #defines and
structures. The HID usage identifier is a composite of the HID usage
page shifted to the 16 high order bits ORed with the usage code. The
behavior of the read() function can be modified using the HIDIOCSFLAG
ioctl() described below.
ioctl():
This is the control interface. There are a number of controls:
HIDIOCGVERSION - int (read)
Gets the version code out of the hiddev driver.
HIDIOCAPPLICATION - (none)
This ioctl call returns the HID application usage associated with the
hid device. The third argument to ioctl() specifies which application
index to get. This is useful when the device has more than one
application collection. If the index is invalid (greater or equal to
the number of application collections this device has) the ioctl
returns -1. You can find out beforehand how many application
collections the device has from the num_applications field from the
hiddev_devinfo structure.
HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
This returns a superset of the information above, providing not only
application collections, but all the collections the device has. It
also returns the level the collection lives in the hierarchy.
The user passes in a hiddev_collection_info struct with the index
field set to the index that should be returned. The ioctl fills in
the other fields. If the index is larger than the last collection
index, the ioctl returns -1 and sets errno to -EINVAL.
HIDIOCGDEVINFO - struct hiddev_devinfo (read)
Gets a hiddev_devinfo structure which describes the device.
HIDIOCGSTRING - struct struct hiddev_string_descriptor (read/write)
Gets a string descriptor from the device. The caller must fill in the
"index" field to indicate which descriptor should be returned.
HIDIOCINITREPORT - (none)
Instructs the kernel to retrieve all input and feature report values
from the device. At this point, all the usage structures will contain
current values for the device, and will maintain it as the device
changes. Note that the use of this ioctl is unnecessary in general,
since later kernels automatically initialize the reports from the
device at attach time.
HIDIOCGNAME - string (variable length)
Gets the device name
HIDIOCGREPORT - struct hiddev_report_info (write)
Instructs the kernel to get a feature or input report from the device,
in order to selectively update the usage structures (in contrast to
INITREPORT).
HIDIOCSREPORT - struct hiddev_report_info (write)
Instructs the kernel to send a report to the device. This report can
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
individual usage values in the report before sending the report in full
to the device.
HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
Fills in a hiddev_report_info structure for the user. The report is
looked up by type (input, output or feature) and id, so these fields
must be filled in by the user. The ID can be absolute -- the actual
report id as reported by the device -- or relative --
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
report_id) for the next report after report_id. Without a-priori
information about report ids, the right way to use this ioctl is to
use the relative IDs above to enumerate the valid IDs. The ioctl
returns non-zero when there is no more next ID. The real report ID is
filled into the returned hiddev_report_info structure.
HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
Returns the field information associated with a report in a
hiddev_field_info structure. The user must fill in report_id and
report_type in this structure, as above. The field_index should also
be filled in, which should be a number from 0 and maxfield-1, as
returned from a previous HIDIOCGREPORTINFO call.
HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
Returns the usage_code in a hiddev_usage_ref structure, given that
given its report type, report id, field index, and index within the
field have already been filled into the structure.
HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
Returns the value of a usage in a hiddev_usage_ref structure. The
usage to be retrieved can be specified as above, or the user can
choose to fill in the report_type field and specify the report_id as
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
filled in with the report and field information associated with this
usage if it is found.
HIDIOCSUSAGE - struct hiddev_usage_ref (write)
Sets the value of a usage in an output report. The user fills in
the hiddev_usage_ref structure as above, but additionally fills in
the value field.
HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
Returns the collection index associated with this usage. This
indicates where in the collection hierarchy this usage sits.
HIDIOCGFLAG - int (read)
HIDIOCSFLAG - int (write)
These operations respectively inspect and replace the mode flags
that influence the read() call above. The flags are as follows:
HIDDEV_FLAG_UREF - read() calls will now return
struct hiddev_usage_ref instead of struct hiddev_event.
This is a larger structure, but in situations where the
device has more than one usage in its reports with the
same usage code, this mode serves to resolve such
ambiguity.
HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
with HIDDEV_FLAG_UREF. With this flag set, when the device
sends a report, a struct hiddev_usage_ref will be returned
to read() filled in with the report_type and report_id, but
with field_index set to FIELD_INDEX_NONE. This serves as
additional notification when the device has sent a report.

148
Documentation/usb/hotplug.txt Normal file
View file

@ -0,0 +1,148 @@
LINUX HOTPLUGGING
In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
into the bus with power on. In most cases, users expect the devices to become
immediately usable. That means the system must do many things, including:
- Find a driver that can handle the device. That may involve
loading a kernel module; newer drivers can use module-init-tools
to publish their device (and class) support to user utilities.
- Bind a driver to that device. Bus frameworks do that using a
device driver's probe() routine.
- Tell other subsystems to configure the new device. Print
queues may need to be enabled, networks brought up, disk
partitions mounted, and so on. In some cases these will
be driver-specific actions.
This involves a mix of kernel mode and user mode actions. Making devices
be immediately usable means that any user mode actions can't wait for an
administrator to do them: the kernel must trigger them, either passively
(triggering some monitoring daemon to invoke a helper program) or
actively (calling such a user mode helper program directly).
Those triggered actions must support a system's administrative policies;
such programs are called "policy agents" here. Typically they involve
shell scripts that dispatch to more familiar administration tools.
Because some of those actions rely on information about drivers (metadata)
that is currently available only when the drivers are dynamically linked,
you get the best hotplugging when you configure a highly modular system.
KERNEL HOTPLUG HELPER (/sbin/hotplug)
When you compile with CONFIG_HOTPLUG, you get a new kernel parameter:
/proc/sys/kernel/hotplug, which normally holds the pathname "/sbin/hotplug".
That parameter names a program which the kernel may invoke at various times.
The /sbin/hotplug program can be invoked by any subsystem as part of its
reaction to a configuration change, from a thread in that subsystem.
Only one parameter is required: the name of a subsystem being notified of
some kernel event. That name is used as the first key for further event
dispatch; any other argument and environment parameters are specified by
the subsystem making that invocation.
Hotplug software and other resources is available at:
http://linux-hotplug.sourceforge.net
Mailing list information is also available at that site.
--------------------------------------------------------------------------
USB POLICY AGENT
The USB subsystem currently invokes /sbin/hotplug when USB devices
are added or removed from system. The invocation is done by the kernel
hub daemon thread [khubd], or else as part of root hub initialization
(done by init, modprobe, kapmd, etc). Its single command line parameter
is the string "usb", and it passes these environment variables:
ACTION ... "add", "remove"
PRODUCT ... USB vendor, product, and version codes (hex)
TYPE ... device class codes (decimal)
INTERFACE ... interface 0 class codes (decimal)
If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is
the pathname of the device, and is useful for devices with multiple and/or
alternate interfaces that complicate driver selection. By design, USB
hotplugging is independent of "usbdevfs": you can do most essential parts
of USB device setup without using that filesystem, and without running a
user mode daemon to detect changes in system configuration.
Currently available policy agent implementations can load drivers for
modules, and can invoke driver-specific setup scripts. The newest ones
leverage USB module-init-tools support. Later agents might unload drivers.
USB MODUTILS SUPPORT
Current versions of module-init-tools will create a "modules.usbmap" file
which contains the entries from each driver's MODULE_DEVICE_TABLE. Such
files can be used by various user mode policy agents to make sure all the
right driver modules get loaded, either at boot time or later.
See <linux/usb.h> for full information about such table entries; or look
at existing drivers. Each table entry describes one or more criteria to
be used when matching a driver to a device or class of devices. The
specific criteria are identified by bits set in "match_flags", paired
with field values. You can construct the criteria directly, or with
macros such as these, and use driver_info to store more information.
USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
USB_DEVICE_VER (vendorId, productId, lo, hi)
... like USB_DEVICE with lo <= productversion <= hi
USB_INTERFACE_INFO (class, subclass, protocol)
... matching specified interface class info
USB_DEVICE_INFO (class, subclass, protocol)
... matching specified device class info
A short example, for a driver that supports several specific USB devices
and their quirks, might have a MODULE_DEVICE_TABLE like this:
static const struct usb_device_id mydriver_id_table = {
{ USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
{ USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },
...
{ } /* end with an all-zeroes entry */
}
MODULE_DEVICE_TABLE (usb, mydriver_id_table);
Most USB device drivers should pass these tables to the USB subsystem as
well as to the module management subsystem. Not all, though: some driver
frameworks connect using interfaces layered over USB, and so they won't
need such a "struct usb_driver".
Drivers that connect directly to the USB subsystem should be declared
something like this:
static struct usb_driver mydriver = {
.name = "mydriver",
.id_table = mydriver_id_table,
.probe = my_probe,
.disconnect = my_disconnect,
/*
if using the usb chardev framework:
.minor = MY_USB_MINOR_START,
.fops = my_file_ops,
if exposing any operations through usbdevfs:
.ioctl = my_ioctl,
*/
}
When the USB subsystem knows about a driver's device ID table, it's used when
choosing drivers to probe(). The thread doing new device processing checks
drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and
device descriptors for the device. It will only call probe() if there is a
match, and the third argument to probe() will be the entry that matched.
If you don't provide an id_table for your driver, then your driver may get
probed for each new device; the third parameter to probe() will be null.

324
Documentation/usb/ibmcam.txt Normal file
View file

@ -0,0 +1,324 @@
README for Linux device driver for the IBM "C-It" USB video camera
INTRODUCTION:
This driver does not use all features known to exist in
the IBM camera. However most of needed features work well.
This driver was developed using logs of observed USB traffic
which was produced by standard Windows driver (c-it98.sys).
I did not have data sheets from Xirlink.
Video formats:
128x96 [model 1]
176x144
320x240 [model 2]
352x240 [model 2]
352x288
Frame rate: 3 - 30 frames per second (FPS)
External interface: USB
Internal interface: Video For Linux (V4L)
Supported controls:
- by V4L: Contrast, Brightness, Color, Hue
- by driver options: frame rate, lighting conditions, video format,
default picture settings, sharpness.
SUPPORTED CAMERAS:
Xirlink "C-It" camera, also known as "IBM PC Camera".
The device uses proprietary ASIC (and compression method);
it is manufactured by Xirlink. See http://www.xirlink.com/
http://www.ibmpccamera.com or http://www.c-itnow.com/ for
details and pictures.
This very chipset ("X Chip", as marked at the factory)
is used in several other cameras, and they are supported
as well:
- IBM NetCamera
- Veo Stingray
The Linux driver was developed with camera with following
model number (or FCC ID): KSX-XVP510. This camera has three
interfaces, each with one endpoint (control, iso, iso). This
type of cameras is referred to as "model 1". These cameras are
no longer manufactured.
Xirlink now manufactures new cameras which are somewhat different.
In particular, following models [FCC ID] belong to that category:
XVP300 [KSX-X9903]
XVP600 [KSX-X9902]
XVP610 [KSX-X9902]
(see http://www.xirlink.com/ibmpccamera/ for updates, they refer
to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
These cameras have two interfaces, one endpoint in each (iso, bulk).
Such type of cameras is referred to as "model 2". They are supported
(with exception of 352x288 native mode).
Some IBM NetCameras (Model 4) are made to generate only compressed
video streams. This is great for performance, but unfortunately
nobody knows how to decompress the stream :-( Therefore, these
cameras are *unsupported* and if you try to use one of those, all
you get is random colored horizontal streaks, not the image!
If you have one of those cameras, you probably should return it
to the store and get something that is supported.
Tell me more about all that "model" business
--------------------------------------------
I just invented model numbers to uniquely identify flavors of the
hardware/firmware that were sold. It was very confusing to use
brand names or some other internal numbering schemes. So I found
by experimentation that all Xirlink chipsets fall into four big
classes, and I called them "models". Each model is programmed in
its own way, and each model sends back the video in its own way.
Quirks of Model 2 cameras:
-------------------------
Model 2 does not have hardware contrast control. Corresponding V4L
control is implemented in software, which is not very nice to your
CPU, but at least it works.
This driver provides 352x288 mode by switching the camera into
quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
this mode to 10 frames per second or less, in ideal conditions on
the bus (USB is shared, after all). The frame rate
has to be programmed very conservatively. Additional concern is that
frame rate depends on brightness setting; therefore the picture can
be good at one brightness and broken at another! I did not want to fix
the frame rate at slowest setting, but I had to move it pretty much down
the scale (so that framerate option barely matters). I also noticed that
camera after first powering up produces frames slightly faster than during
consecutive uses. All this means that if you use 352x288 (which is
default), be warned - you may encounter broken picture on first connect;
try to adjust brightness - brighter image is slower, so USB will be able
to send all data. However if you regularly use Model 2 cameras you may
prefer 176x144 which makes perfectly good I420, with no scaling and
lesser demands on USB (300 Kbits per second, or 26 frames per second).
Another strange effect of 352x288 mode is the fine vertical grid visible
on some colored surfaces. I am sure it is caused by me not understanding
what the camera is trying to say. Blame trade secrets for that.
The camera that I had also has a hardware quirk: if disconnected,
it needs few minutes to "relax" before it can be plugged in again
(poorly designed USB processor reset circuit?)
[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
observed this particular flaw in it.]
Model 2 camera can be programmed for very high sensitivity (even starlight
may be enough), this makes it convenient for tinkering with. The driver
code has enough comments to help a programmer to tweak the camera
as s/he feels necessary.
WHAT YOU NEED:
- A supported IBM PC (C-it) camera (model 1 or 2)
- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
- A Video4Linux compatible frame grabber program such as xawtv.
HOW TO COMPILE THE DRIVER:
You need to compile the driver only if you are a developer
or if you want to make changes to the code. Most distributions
precompile all modules, so you can go directly to the next
section "HOW TO USE THE DRIVER".
The ibmcam driver uses usbvideo helper library (module),
so if you are studying the ibmcam code you will be led there.
The driver itself consists of only one file in usb/ directory:
ibmcam.c. This file is included into the Linux kernel build
process if you configure the kernel for CONFIG_USB_IBMCAM.
Run "make xconfig" and in USB section you will find the IBM
camera driver. Select it, save the configuration and recompile.
HOW TO USE THE DRIVER:
I recommend to compile driver as a module. This gives you an
easier access to its configuration. The camera has many more
settings than V4L can operate, so some settings are done using
module options.
To begin with, on most modern Linux distributions the driver
will be automatically loaded whenever you plug the supported
camera in. Therefore, you don't need to do anything. However
if you want to experiment with some module parameters then
you can load and unload the driver manually, with camera
plugged in or unplugged.
Typically module is installed with command 'modprobe', like this:
# modprobe ibmcam framerate=1
Alternatively you can use 'insmod' in similar fashion:
# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
Module can be inserted with camera connected or disconnected.
The driver can have options, though some defaults are provided.
Driver options: (* indicates that option is model-dependent)
Name Type Range [default] Example
-------------- -------------- -------------- ------------------
debug Integer 0-9 [0] debug=1
flags Integer 0-0xFF [0] flags=0x0d
framerate Integer 0-6 [2] framerate=1
hue_correction Integer 0-255 [128] hue_correction=115
init_brightness Integer 0-255 [128] init_brightness=100
init_contrast Integer 0-255 [192] init_contrast=200
init_color Integer 0-255 [128] init_color=130
init_hue Integer 0-255 [128] init_hue=115
lighting Integer 0-2* [1] lighting=2
sharpness Integer 0-6* [4] sharpness=3
size Integer 0-2* [2] size=1
Options for Model 2 only:
Name Type Range [default] Example
-------------- -------------- -------------- ------------------
init_model2_rg Integer 0..255 [0x70] init_model2_rg=128
init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50
init_model2_sat Integer 0..255 [0x34] init_model2_sat=65
init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200
debug You don't need this option unless you are a developer.
If you are a developer then you will see in the code
what values do what. 0=off.
flags This is a bit mask, and you can combine any number of
bits to produce what you want. Usually you don't want
any of extra features this option provides:
FLAGS_RETRY_VIDIOCSYNC 1 This bit allows to retry failed
VIDIOCSYNC ioctls without failing.
Will work with xawtv, will not
with xrealproducer. Default is
not set.
FLAGS_MONOCHROME 2 Activates monochrome (b/w) mode.
FLAGS_DISPLAY_HINTS 4 Shows colored pixels which have
magic meaning to developers.
FLAGS_OVERLAY_STATS 8 Shows tiny numbers on screen,
useful only for debugging.
FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers.
FLAGS_SEPARATE_FRAMES 32 Shows each frame separately, as
it was received from the camera.
Default (not set) is to mix the
preceding frame in to compensate
for occasional loss of Isoc data
on high frame rates.
FLAGS_CLEAN_FRAMES 64 Forces "cleanup" of each frame
prior to use; relevant only if
FLAGS_SEPARATE_FRAMES is set.
Default is not to clean frames,
this is a little faster but may
produce flicker if frame rate is
too high and Isoc data gets lost.
FLAGS_NO_DECODING 128 This flag turns the video stream
decoder off, and dumps the raw
Isoc data from the camera into
the reading process. Useful to
developers, but not to users.
framerate This setting controls frame rate of the camera. This is
an approximate setting (in terms of "worst" ... "best")
because camera changes frame rate depending on amount
of light available. Setting 0 is slowest, 6 is fastest.
Beware - fast settings are very demanding and may not
work well with all video sizes. Be conservative.
hue_correction This highly optional setting allows to adjust the
hue of the image in a way slightly different from
what usual "hue" control does. Both controls affect
YUV colorspace: regular "hue" control adjusts only
U component, and this "hue_correction" option similarly
adjusts only V component. However usually it is enough
to tweak only U or V to compensate for colored light or
color temperature; this option simply allows more
complicated correction when and if it is necessary.
init_brightness These settings specify _initial_ values which will be
init_contrast used to set up the camera. If your V4L application has
init_color its own controls to adjust the picture then these
init_hue controls will be used too. These options allow you to
preconfigure the camera when it gets connected, before
any V4L application connects to it. Good for webcams.
init_model2_rg These initial settings alter color balance of the
init_model2_rg2 camera on hardware level. All four settings may be used
init_model2_sat to tune the camera to specific lighting conditions. These
init_model2_yb settings only apply to Model 2 cameras.
lighting This option selects one of three hardware-defined
photosensitivity settings of the camera. 0=bright light,
1=Medium (default), 2=Low light. This setting affects
frame rate: the dimmer the lighting the lower the frame
rate (because longer exposition time is needed). The
Model 2 cameras allow values more than 2 for this option,
thus enabling extremely high sensitivity at cost of frame
rate, color saturation and imaging sensor noise.
sharpness This option controls smoothing (noise reduction)
made by camera. Setting 0 is most smooth, setting 6
is most sharp. Be aware that CMOS sensor used in the
camera is pretty noisy, so if you choose 6 you will
be greeted with "snowy" image. Default is 4. Model 2
cameras do not support this feature.
size This setting chooses one of several image sizes that are
supported by this driver. Cameras may support more, but
it's difficult to reverse-engineer all formats.
Following video sizes are supported:
size=0 128x96 (Model 1 only)
size=1 160x120
size=2 176x144
size=3 320x240 (Model 2 only)
size=4 352x240 (Model 2 only)
size=5 352x288
size=6 640x480 (Model 3 only)
The 352x288 is the native size of the Model 1 sensor
array, so it's the best resolution the camera can
yield. The best resolution of Model 2 is 176x144, and
larger images are produced by stretching the bitmap.
Model 3 has sensor with 640x480 grid, and it works too,
but the frame rate will be exceptionally low (1-2 FPS);
it may be still OK for some applications, like security.
Choose the image size you need. The smaller image can
support faster frame rate. Default is 352x288.
For more information and the Troubleshooting FAQ visit this URL:
http://www.linux-usb.org/ibmcam/
WHAT NEEDS TO BE DONE:
- The button on the camera is not used. I don't know how to get to it.
I know now how to read button on Model 2, but what to do with it?
- Camera reports its status back to the driver; however I don't know
what returned data means. If camera fails at some initialization
stage then something should be done, and I don't do that because
I don't even know that some command failed. This is mostly Model 1
concern because Model 2 uses different commands which do not return
status (and seem to complete successfully every time).
- Some flavors of Model 4 NetCameras produce only compressed video
streams, and I don't know how to decode them.
CREDITS:
The code is based in no small part on the CPiA driver by Johannes Erdfelt,
Randy Dunlap, and others. Big thanks to them for their pioneering work on that
and the USB stack.
I also thank John Lightsey for his donation of the Veo Stingray camera.

200
Documentation/usb/linux.inf Normal file
View file

@ -0,0 +1,200 @@
; MS-Windows driver config matching some basic modes of the
; Linux-USB Ethernet/RNDIS gadget firmware:
;
; - RNDIS plus CDC Ethernet ... this may be familiar as a DOCSIS
; cable modem profile, and supports most non-Microsoft USB hosts
;
; - RNDIS plus CDC Subset ... used by hardware that incapable of
; full CDC Ethernet support.
;
; Microsoft only directly supports RNDIS drivers, and bundled them into XP.
; The Microsoft "Remote NDIS USB Driver Kit" is currently found at:
; http://www.microsoft.com/whdc/hwdev/resources/HWservices/rndis.mspx
[Version]
Signature = "$CHICAGO$"
Class = Net
ClassGUID = {4d36e972-e325-11ce-bfc1-08002be10318}
Provider = %Linux%
Compatible = 1
MillenniumPreferred = .ME
DriverVer = 03/30/2004,0.0.0.0
; catalog file would be used by WHQL
;CatalogFile = Linux.cat
[Manufacturer]
%Linux% = LinuxDevices,NT.5.1
[LinuxDevices]
; NetChip IDs, used by both firmware modes
%LinuxDevice% = RNDIS, USB\VID_0525&PID_a4a2
[LinuxDevices.NT.5.1]
%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2
[ControlFlags]
ExcludeFromSelect=*
; Windows 98, Windows 98 Second Edition specific sections --------
[RNDIS]
DeviceID = usb8023
MaxInstance = 512
DriverVer = 03/30/2004,0.0.0.0
AddReg = RNDIS_AddReg_98, RNDIS_AddReg_Common
[RNDIS_AddReg_98]
HKR, , DevLoader, 0, *ndis
HKR, , DeviceVxDs, 0, usb8023.sys
HKR, NDIS, LogDriverName, 0, "usb8023"
HKR, NDIS, MajorNdisVersion, 1, 5
HKR, NDIS, MinorNdisVersion, 1, 0
HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5"
HKR, Ndi\Interfaces, DefLower, 0, "ethernet"
HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5"
HKR, Ndi\Interfaces, LowerRange, 0, "ethernet"
HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_98"
HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_98"
HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_98"
HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2"
[RNDIS_Install_98]
CopyFiles=RNDIS_CopyFiles_98
[RNDIS_CopyFiles_98]
usb8023.sys, usb8023w.sys, , 0
rndismp.sys, rndismpw.sys, , 0
; Windows Millennium Edition specific sections --------------------
[RNDIS.ME]
DeviceID = usb8023
MaxInstance = 512
DriverVer = 03/30/2004,0.0.0.0
AddReg = RNDIS_AddReg_ME, RNDIS_AddReg_Common
Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI
BusType = 15
[RNDIS_AddReg_ME]
HKR, , DevLoader, 0, *ndis
HKR, , DeviceVxDs, 0, usb8023.sys
HKR, NDIS, LogDriverName, 0, "usb8023"
HKR, NDIS, MajorNdisVersion, 1, 5
HKR, NDIS, MinorNdisVersion, 1, 0
HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5"
HKR, Ndi\Interfaces, DefLower, 0, "ethernet"
HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5"
HKR, Ndi\Interfaces, LowerRange, 0, "ethernet"
HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_ME"
HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_ME"
HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_ME"
HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2"
[RNDIS_Install_ME]
CopyFiles=RNDIS_CopyFiles_ME
[RNDIS_CopyFiles_ME]
usb8023.sys, usb8023m.sys, , 0
rndismp.sys, rndismpm.sys, , 0
; Windows 2000 specific sections ---------------------------------
[RNDIS.NT]
Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI
BusType = 15
DriverVer = 03/30/2004,0.0.0.0
AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common
CopyFiles = RNDIS_CopyFiles_NT
[RNDIS.NT.Services]
AddService = USB_RNDIS, 2, RNDIS_ServiceInst_NT, RNDIS_EventLog
[RNDIS_CopyFiles_NT]
; no rename of files on Windows 2000, use the 'k' names as is
usb8023k.sys, , , 0
rndismpk.sys, , , 0
[RNDIS_ServiceInst_NT]
DisplayName = %ServiceDisplayName%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\usb8023k.sys
LoadOrderGroup = NDIS
AddReg = RNDIS_WMI_AddReg_NT
[RNDIS_WMI_AddReg_NT]
HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismpk.sys"
; Windows XP specific sections -----------------------------------
[RNDIS.NT.5.1]
Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI
BusType = 15
DriverVer = 03/30/2004,0.0.0.0
AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common
; no copyfiles - the files are already in place
[RNDIS.NT.5.1.Services]
AddService = USB_RNDIS, 2, RNDIS_ServiceInst_51, RNDIS_EventLog
[RNDIS_ServiceInst_51]
DisplayName = %ServiceDisplayName%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\usb8023.sys
LoadOrderGroup = NDIS
AddReg = RNDIS_WMI_AddReg_51
[RNDIS_WMI_AddReg_51]
HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismp.sys"
; Windows 2000 and Windows XP common sections --------------------
[RNDIS_AddReg_NT]
HKR, Ndi, Service, 0, "USB_RNDIS"
HKR, Ndi\Interfaces, UpperRange, 0, "ndis5"
HKR, Ndi\Interfaces, LowerRange, 0, "ethernet"
[RNDIS_EventLog]
AddReg = RNDIS_EventLog_AddReg
[RNDIS_EventLog_AddReg]
HKR, , EventMessageFile, 0x00020000, "%%SystemRoot%%\System32\netevent.dll"
HKR, , TypesSupported, 0x00010001, 7
; Common Sections -------------------------------------------------
[RNDIS_AddReg_Common]
HKR, NDI\params\NetworkAddress, ParamDesc, 0, %NetworkAddress%
HKR, NDI\params\NetworkAddress, type, 0, "edit"
HKR, NDI\params\NetworkAddress, LimitText, 0, "12"
HKR, NDI\params\NetworkAddress, UpperCase, 0, "1"
HKR, NDI\params\NetworkAddress, default, 0, " "
HKR, NDI\params\NetworkAddress, optional, 0, "1"
[SourceDisksNames]
1=%SourceDisk%,,1
[SourceDisksFiles]
usb8023m.sys=1
rndismpm.sys=1
usb8023w.sys=1
rndismpw.sys=1
usb8023k.sys=1
rndismpk.sys=1
[DestinationDirs]
RNDIS_CopyFiles_98 = 10, system32/drivers
RNDIS_CopyFiles_ME = 10, system32/drivers
RNDIS_CopyFiles_NT = 12
[Strings]
ServiceDisplayName = "USB Remote NDIS Network Device Driver"
NetworkAddress = "Network Address"
Linux = "Linux Developer Community"
LinuxDevice = "Linux USB Ethernet/RNDIS Gadget"
SourceDisk = "Ethernet/RNDIS Gadget Driver Install Disk"

76
Documentation/usb/mtouchusb.txt Normal file
View file

@ -0,0 +1,76 @@
CHANGES
- 0.3 - Created based off of scanner & INSTALL from the original touchscreen
driver on freshmeat (http://freshmeat.net/projects/3mtouchscreendriver)
- Amended for linux-2.4.18, then 2.4.19
- 0.5 - Complete rewrite using Linux Input in 2.6.3
Unfortunately no calibration support at this time
- 1.4 - Multiple changes to support the EXII 5000UC and house cleaning
Changed reset from standard USB dev reset to vendor reset
Changed data sent to host from compensated to raw coordinates
Eliminated vendor/product module params
Performed multiple successfull tests with an EXII-5010UC
SUPPORTED HARDWARE:
All controllers have the Vendor: 0x0596 & Product: 0x0001
Controller Description Part Number
------------------------------------------------------
USB Capacitive - Pearl Case 14-205 (Discontinued)
USB Capacitive - Black Case 14-124 (Discontinued)
USB Capacitive - No Case 14-206 (Discontinued)
USB Capacitive - Pearl Case EXII-5010UC
USB Capacitive - Black Case EXII-5030UC
USB Capacitive - No Case EXII-5050UC
DRIVER NOTES:
Installation is simple, you only need to add Linux Input, Linux USB, and the
driver to the kernel. The driver can also be optionally built as a module.
This driver appears to be one of possible 2 Linux USB Input Touchscreen
drivers. Although 3M produces a binary only driver available for
download, I persist in updating this driver since I would like to use the
touchscreen for embedded apps using QTEmbedded, DirectFB, etc. So I feel the
logical choice is to use Linux Imput.
Currently there is no way to calibrate the device via this driver. Even if
the device could be calibrated, the driver pulls to raw coordinate data from
the controller. This means calibration must be performed within the
userspace.
The controller screen resolution is now 0 to 16384 for both X and Y reporting
the raw touch data. This is the same for the old and new capacitive USB
controllers.
Perhaps at some point an abstract function will be placed into evdev so
generic functions like calibrations, resets, and vendor information can be
requested from the userspace (And the drivers would handle the vendor specific
tasks).
ADDITIONAL INFORMATION/UPDATES/X CONFIGURATION EXAMPLE:
http://groomlakelabs.com/grandamp/code/microtouch/
TODO:
Implement a control urb again to handle requests to and from the device
such as calibration, etc once/if it becomes available.
DISCLAMER:
I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support
this driver! If you want touch drivers only supported within X, please go to:
http://www.3m.com/3MTouchSystems/downloads/
THANKS:
A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for
testing!

32
Documentation/usb/ohci.txt Normal file
View file

@ -0,0 +1,32 @@
23-Aug-2002
The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived
from the "usb-ohci" driver from the 2.4 kernel series. The "usb-ohci" code
was written primarily by Roman Weissgaerber <[email protected]> but with
contributions from many others (read its copyright/licencing header).
It supports the "Open Host Controller Interface" (OHCI), which standardizes
hardware register protocols used to talk to USB 1.1 host controllers. As
compared to the earlier "Universal Host Controller Interface" (UHCI) from
Intel, it pushes more intelligence into the hardware. USB 1.1 controllers
from vendors other than Intel and VIA generally use OHCI.
Changes since the 2.4 kernel include
- improved robustness; bugfixes; and less overhead
- supports the updated and simplified usbcore APIs
- interrupt transfers can be larger, and can be queued
- less code, by using the upper level "hcd" framework
- supports some non-PCI implementations of OHCI
- ... more
The "ohci-hcd" driver handles all USB 1.1 transfer types. Transfers of all
types can be queued. That was also true in "usb-ohci", except for interrupt
transfers. Previously, using periods of one frame would risk data loss due
to overhead in IRQ processing. When interrupt transfers are queued, those
risks can be minimized by making sure the hardware always has transfers to
work on while the OS is getting around to the relevant IRQ processing.
- David Brownell
<[email protected]>

289
Documentation/usb/ov511.txt Normal file
View file

@ -0,0 +1,289 @@
-------------------------------------------------------------------------------
Readme for Linux device driver for the OmniVision OV511 USB to camera bridge IC
-------------------------------------------------------------------------------
Author: Mark McClelland
Homepage: http://alpha.dyndns.org/ov511
INTRODUCTION:
This is a driver for the OV511, a USB-only chip used in many "webcam" devices.
Any camera using the OV511/OV511+ and the OV6620/OV7610/20/20AE should work.
Video capture devices that use the Philips SAA7111A decoder also work. It
supports streaming and capture of color or monochrome video via the Video4Linux
API. Most V4L apps are compatible with it. Most resolutions with a width and
height that are a multiple of 8 are supported.
If you need more information, please visit the OV511 homepage at the above URL.
WHAT YOU NEED:
- If you want to help with the development, get the chip's specification docs at
http://www.ovt.com/omniusbp.html
- A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv)
vidcat is part of the w3cam package: http://www.hdk-berlin.de/~rasca/w3cam/
xawtv is available at: http://www.in-berlin.de/User/kraxel/xawtv.html
HOW TO USE IT:
Note: These are simplified instructions. For complete instructions see:
http://alpha.dyndns.org/ov511/install.html
You must have first compiled USB support, support for your specific USB host
controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled.
Next, (as root):
modprobe usbcore
modprobe usb-uhci <OR> modprobe usb-ohci
modprobe videodev
modprobe ov511
If it is not already there (it usually is), create the video device:
mknod /dev/video0 c 81 0
Optionally, symlink /dev/video to /dev/video0
You will have to set permissions on this device to allow you to read/write
from it:
chmod 666 /dev/video
chmod 666 /dev/video0 (if necessary)
Now you are ready to run a video app! Both vidcat and xawtv work well for me
at 640x480.
[Using vidcat:]
vidcat -s 640x480 -p c > test.jpg
xview test.jpg
[Using xawtv:]
From the main xawtv directory:
make clean
./configure
make
make install
Now you should be able to run xawtv. Right click for the options dialog.
MODULE PARAMETERS:
You can set these with: insmod ov511 NAME=VALUE
There is currently no way to set these on a per-camera basis.
NAME: autobright
TYPE: integer (Boolean)
DEFAULT: 1
DESC: Brightness is normally under automatic control and can't be set
manually by the video app. Set to 0 for manual control.
NAME: autogain
TYPE: integer (Boolean)
DEFAULT: 1
DESC: Auto Gain Control enable. This feature is not yet implemented.
NAME: autoexp
TYPE: integer (Boolean)
DEFAULT: 1
DESC: Auto Exposure Control enable. This feature is not yet implemented.
NAME: debug
TYPE: integer (0-6)
DEFAULT: 3
DESC: Sets the threshold for printing debug messages. The higher the value,
the more is printed. The levels are cumulative, and are as follows:
0=no debug messages
1=init/detection/unload and other significant messages
2=some warning messages
3=config/control function calls
4=most function calls and data parsing messages
5=highly repetitive mesgs
NAME: snapshot
TYPE: integer (Boolean)
DEFAULT: 0
DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until
the snapshot button is pressed. Note: enabling this mode disables
/proc/video/ov511/<minor#>/button
NAME: cams
TYPE: integer (1-4 for OV511, 1-31 for OV511+)
DEFAULT: 1
DESC: Number of cameras allowed to stream simultaneously on a single bus.
Values higher than 1 reduce the data rate of each camera, allowing two
or more to be used at once. If you have a complicated setup involving
both OV511 and OV511+ cameras, trial-and-error may be necessary for
finding the optimum setting.
NAME: compress
TYPE: integer (Boolean)
DEFAULT: 0
DESC: Set this to 1 to turn on the camera's compression engine. This can
potentially increase the frame rate at the expense of quality, if you
have a fast CPU. You must load the proper compression module for your
camera before starting your application (ov511_decomp or ov518_decomp).
NAME: testpat
TYPE: integer (Boolean)
DEFAULT: 0
DESC: This configures the camera's sensor to transmit a colored test-pattern
instead of an image. This does not work correctly yet.
NAME: dumppix
TYPE: integer (0-2)
DEFAULT: 0
DESC: Dumps raw pixel data and skips post-processing and format conversion.
It is for debugging purposes only. Options are:
0: Disable (default)
1: Dump raw data from camera, excluding headers and trailers
2: Dumps data exactly as received from camera
NAME: led
TYPE: integer (0-2)
DEFAULT: 1 (Always on)
DESC: Controls whether the LED (the little light) on the front of the camera
is always off (0), always on (1), or only on when driver is open (2).
This is not supported with the OV511, and might only work with certain
cameras (ones that actually have the LED wired to the control pin, and
not just hard-wired to be on all the time).
NAME: dump_bridge
TYPE: integer (Boolean)
DEFAULT: 0
DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system
log. Only useful for serious debugging/development purposes.
NAME: dump_sensor
TYPE: integer (Boolean)
DEFAULT: 0
DESC: Dumps the sensor register values to the system log. Only useful for
serious debugging/development purposes.
NAME: printph
TYPE: integer (Boolean)
DEFAULT: 0
DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This
is only useful if you are trying to debug problems with the isoc data
stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be
warned that this dumps a large number of messages to your kernel log.
NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv
TYPE: integer (0-63 for phy and phuv, 0-255 for rest)
DEFAULT: OV511 default values
DESC: These are registers 70h - 77h of the OV511, which control the
prediction ranges and quantization thresholds of the compressor, for
the Y and UV channels in the horizontal and vertical directions. See
the OV511 or OV511+ data sheet for more detailed descriptions. These
normally do not need to be changed.
NAME: lightfreq
TYPE: integer (0, 50, or 60)
DEFAULT: 0 (use sensor default)
DESC: Sets the sensor to match your lighting frequency. This can reduce the
appearance of "banding", i.e. horizontal lines or waves of light and
dark that are often caused by artificial lighting. Valid values are:
0 - Use default (depends on sensor, most likely 60 Hz)
50 - For European and Asian 50 Hz power
60 - For American 60 Hz power
NAME: bandingfilter
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Enables the sensor´s banding filter exposure algorithm. This reduces
or stabilizes the "banding" caused by some artificial light sources
(especially fluorescent). You might have to set lightfreq correctly for
this to work right. As an added bonus, this sometimes makes it
possible to capture your monitor´s output.
NAME: fastset
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Allows picture settings (brightness, contrast, color, and hue) to take
effect immediately, even in the middle of a frame. This reduces the
time to change settings, but can ruin frames during the change. Only
affects OmniVision sensors.
NAME: force_palette
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Forces the palette (color format) to a specific value. If an
application requests a different palette, it will be rejected, thereby
forcing it to try others until it succeeds. This is useful for forcing
greyscale mode with a color camera, for example. Supported modes are:
0 (Allows all the following formats)
1 VIDEO_PALETTE_GREY (Linear greyscale)
10 VIDEO_PALETTE_YUV420 (YUV 4:2:0 Planar)
15 VIDEO_PALETTE_YUV420P (YUV 4:2:0 Planar, same as 10)
NAME: backlight
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Setting this flag changes the exposure algorithm for OmniVision sensors
such that objects in the camera's view (i.e. your head) can be clearly
seen when they are illuminated from behind. It reduces or eliminates
the sensor's auto-exposure function, so it should only be used when
needed. Additionally, it is only supported with the OV6620 and OV7620.
NAME: unit_video
TYPE: Up to 16 comma-separated integers
DEFAULT: 0,0,0... (automatically assign the next available minor(s))
DESC: You can specify up to 16 minor numbers to be assigned to ov511 devices.
For example, "unit_video=1,3" will make the driver use /dev/video1 and
/dev/video3 for the first two devices it detects. Additional devices
will be assigned automatically starting at the first available device
node (/dev/video0 in this case). Note that you cannot specify 0 as a
minor number. This feature requires kernel version 2.4.5 or higher.
NAME: remove_zeros
TYPE: integer (Boolean)
DEFAULT: 0 (do not skip any incoming data)
DESC: Setting this to 1 will remove zero-padding from incoming data. This
will compensate for the blocks of corruption that can appear when the
camera cannot keep up with the speed of the USB bus (eg. at low frame
resolutions). This feature is always enabled when compression is on.
NAME: mirror
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This
might be necessary if your camera has a custom lens assembly. This has
no effect with video capture devices.
NAME: ov518_color
TYPE: integer (Boolean)
DEFAULT: 0 (off)
DESC: Enable OV518 color support. This is off by default since it doesn't
work most of the time. If you want to try it, you must also load
ov518_decomp with the "nouv=0" parameter. If you get improper colors or
diagonal lines through the image, restart your video app and try again.
Repeat as necessary.
WORKING FEATURES:
o Color streaming/capture at most widths and heights that are multiples of 8.
o Monochrome (use force_palette=1 to enable)
o Setting/getting of saturation, contrast, brightness, and hue (only some of
them work the OV7620 and OV7620AE)
o /proc status reporting
o SAA7111A video capture support at 320x240 and 640x480
o Compression support
o SMP compatibility
HOW TO CONTACT ME:
You can email me at [email protected] . Please prefix the subject line
with "OV511: " so that I am certain to notice your message.
CREDITS:
The code is based in no small part on the CPiA driver by Johannes Erdfelt,
Randy Dunlap, and others. Big thanks to them for their pioneering work on that
and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
Matsuoka for their work as well.

371
Documentation/usb/proc_usb_info.txt Normal file
View file

@ -0,0 +1,371 @@
/proc/bus/usb filesystem output
===============================
(version 2003.05.30)
The usbfs filesystem for USB devices is traditionally mounted at
/proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as
the /proc/bus/usb/BBB/DDD files.
**NOTE**: If /proc/bus/usb appears empty, and a host controller
driver has been linked, then you need to mount the
filesystem. Issue the command (as root):
mount -t usbfs none /proc/bus/usb
An alternative and more permanent method would be to add
none /proc/bus/usb usbfs defaults 0 0
to /etc/fstab. This will mount usbfs at each reboot.
You can then issue `cat /proc/bus/usb/devices` to extract
USB device information, and user mode drivers can use usbfs
to interact with USB devices.
There are a number of mount options supported by usbfs.
Consult the source code (linux/drivers/usb/core/inode.c) for
information about those options.
**NOTE**: The filesystem has been renamed from "usbdevfs" to
"usbfs", to reduce confusion with "devfs". You may
still see references to the older "usbdevfs" name.
For more information on mounting the usbfs file system, see the
"USB Device Filesystem" section of the USB Guide. The latest copy
of the USB Guide can be found at http://www.linux-usb.org/
THE /proc/bus/usb/BBB/DDD FILES:
--------------------------------
Each connected USB device has one file. The BBB indicates the bus
number. The DDD indicates the device address on that bus. Both
of these numbers are assigned sequentially, and can be reused, so
you can't rely on them for stable access to devices. For example,
it's relatively common for devices to re-enumerate while they are
still connected (perhaps someone jostled their power supply, hub,
or USB cable), so a device might be 002/027 when you first connect
it and 002/048 sometime later.
These files can be read as binary data. The binary data consists
of first the device descriptor, then the descriptors for each
configuration of the device. That information is also shown in
text form by the /proc/bus/usb/devices file, described later.
These files may also be used to write user-level drivers for the USB
devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
read its descriptors to make sure it's the device you expect, and then
bind to an interface (or perhaps several) using an ioctl call. You
would issue more ioctls to the device to communicate to it using
control, bulk, or other kinds of USB transfers. The IOCTLs are
listed in the <linux/usbdevice_fs.h> file, and at this writing the
source code (linux/drivers/usb/devio.c) is the primary reference
for how to access devices through those files.
Note that since by default these BBB/DDD files are writable only by
root, only root can write such user mode drivers. You can selectively
grant read/write permissions to other users by using "chmod". Also,
usbfs mount options such as "devmode=0666" may be helpful.
THE /proc/bus/usb/devices FILE:
-------------------------------
In /proc/bus/usb/devices, each device's output has multiple
lines of ASCII output.
I made it ASCII instead of binary on purpose, so that someone
can obtain some useful data from it without the use of an
auxiliary program. However, with an auxiliary program, the numbers
in the first 4 columns of each "T:" line (topology info:
Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
Each line is tagged with a one-character ID for that line:
T = Topology (etc.)
B = Bandwidth (applies only to USB host controllers, which are
virtualized as root hubs)
D = Device descriptor info.
P = Product ID info. (from Device descriptor, but they won't fit
together on one line)
S = String descriptors.
C = Configuration descriptor info. (* = active configuration)
I = Interface descriptor info.
E = Endpoint descriptor info.
=======================================================================
/proc/bus/usb/devices output format:
Legend:
d = decimal number (may have leading spaces or 0's)
x = hexadecimal number (may have leading spaces or 0's)
s = string
Topology info:
T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd
| | | | | | | | |__MaxChildren
| | | | | | | |__Device Speed in Mbps
| | | | | | |__DeviceNumber
| | | | | |__Count of devices at this level
| | | | |__Connector/Port on Parent for this device
| | | |__Parent DeviceNumber
| | |__Level in topology for this bus
| |__Bus number
|__Topology info tag
Speed may be:
1.5 Mbit/s for low speed USB
12 Mbit/s for full speed USB
480 Mbit/s for high speed USB (added for USB 2.0)
Bandwidth info:
B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
| | | |__Number of isochronous requests
| | |__Number of interrupt requests
| |__Total Bandwidth allocated to this bus
|__Bandwidth info tag
Bandwidth allocation is an approximation of how much of one frame
(millisecond) is in use. It reflects only periodic transfers, which
are the only transfers that reserve bandwidth. Control and bulk
transfers use all other bandwidth, including reserved bandwidth that
is not used for transfers (such as for short packets).
The percentage is how much of the "reserved" bandwidth is scheduled by
those transfers. For a low or full speed bus (loosely, "USB 1.1"),
90% of the bus bandwidth is reserved. For a high speed bus (loosely,
"USB 2.0") 80% is reserved.
Device descriptor info & Product ID info:
D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
where
D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
| | | | | | |__NumberConfigurations
| | | | | |__MaxPacketSize of Default Endpoint
| | | | |__DeviceProtocol
| | | |__DeviceSubClass
| | |__DeviceClass
| |__Device USB version
|__Device info tag #1
where
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
| | | |__Product revision number
| | |__Product ID code
| |__Vendor ID code
|__Device info tag #2
String descriptor info:
S: Manufacturer=ssss
| |__Manufacturer of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this may
| be omitted, or (for newer drivers) will identify the kernel
| version and the driver which provides this hub emulation.
|__String info tag
S: Product=ssss
| |__Product description of this device as read from the device.
| For older USB host controller drivers (virtual root hubs) this
| indicates the driver; for newer ones, it's a product (and vendor)
| description that often comes from the kernel's PCI ID database.
|__String info tag
S: SerialNumber=ssss
| |__Serial Number of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this is
| some unique ID, normally a bus ID (address or slot name) that
| can't be shared with any other device.
|__String info tag
Configuration descriptor info:
C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
| | | | | |__MaxPower in mA
| | | | |__Attributes
| | | |__ConfiguratioNumber
| | |__NumberOfInterfaces
| |__ "*" indicates the active configuration (others are " ")
|__Config info tag
USB devices may have multiple configurations, each of which act
rather differently. For example, a bus-powered configuration
might be much less capable than one that is self-powered. Only
one device configuration can be active at a time; most devices
have only one configuration.
Each configuration consists of one or more interfaces. Each
interface serves a distinct "function", which is typically bound
to a different USB device driver. One common example is a USB
speaker with an audio interface for playback, and a HID interface
for use with software volume control.
Interface descriptor info (can be multiple per Config):
I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
| | | | | | | |__Driver name
| | | | | | | or "(none)"
| | | | | | |__InterfaceProtocol
| | | | | |__InterfaceSubClass
| | | | |__InterfaceClass
| | | |__NumberOfEndpoints
| | |__AlternateSettingNumber
| |__InterfaceNumber
|__Interface info tag
A given interface may have one or more "alternate" settings.
For example, default settings may not use more than a small
amount of periodic bandwidth. To use significant fractions
of bus bandwidth, drivers must select a non-default altsetting.
Only one setting for an interface may be active at a time, and
only one driver may bind to an interface at a time. Most devices
have only one alternate setting per interface.
Endpoint descriptor info (can be multiple per Interface):
E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
| | | | |__Interval (max) between transfers
| | | |__EndpointMaxPacketSize
| | |__Attributes(EndpointType)
| |__EndpointAddress(I=In,O=Out)
|__Endpoint info tag
The interval is nonzero for all periodic (interrupt or isochronous)
endpoints. For high speed endpoints the transfer interval may be
measured in microseconds rather than milliseconds.
For high speed periodic endpoints, the "MaxPacketSize" reflects
the per-microframe data transfer size. For "high bandwidth"
endpoints, that can reflect two or three packets (for up to
3KBytes every 125 usec) per endpoint.
With the Linux-USB stack, periodic bandwidth reservations use the
transfer intervals and sizes provided by URBs, which can be less
than those found in endpoint descriptor.
=======================================================================
If a user or script is interested only in Topology info, for
example, use something like "grep ^T: /proc/bus/usb/devices"
for only the Topology lines. A command like
"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
only the lines that begin with the characters in square brackets,
where the valid characters are TDPCIE. With a slightly more able
script, it can display any selected lines (for example, only T, D,
and P lines) and change their output format. (The "procusb"
Perl script is the beginning of this idea. It will list only
selected lines [selected from TBDPSCIE] or "All" lines from
/proc/bus/usb/devices.)
The Topology lines can be used to generate a graphic/pictorial
of the USB devices on a system's root hub. (See more below
on how to do this.)
The Interface lines can be used to determine what driver is
being used for each device.
The Configuration lines could be used to list maximum power
(in milliamps) that a system's USB devices are using.
For example, "grep ^C: /proc/bus/usb/devices".
Here's an example, from a system which has a UHCI root hub,
an external hub connected to the root hub, and a mouse and
a serial converter connected to the external hub.
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0000 ProdID=0000 Rev= 0.00
S: Product=USB UHCI Root Hub
S: SerialNumber=dce0
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0451 ProdID=1446 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=04b4 ProdID=0001 Rev= 0.00
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0565 ProdID=0001 Rev= 1.08
S: Manufacturer=Peracom Networks, Inc.
S: Product=Peracom USB to Serial Converter
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
Selecting only the "T:" and "I:" lines from this (for example, by using
"procusb ti"), we have:
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
Physically this looks like (or could be converted to):
+------------------+
| PC/root_hub (12)| Dev# = 1
+------------------+ (nn) is Mbps.
Level 0 | CN.0 | CN.1 | [CN = connector/port #]
+------------------+
/
/
+-----------------------+
Level 1 | Dev#2: 4-port hub (12)|
+-----------------------+
|CN.0 |CN.1 |CN.2 |CN.3 |
+-----------------------+
\ \____________________
\_____ \
\ \
+--------------------+ +--------------------+
Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)|
+--------------------+ +--------------------+
Or, in a more tree-like structure (ports [Connectors] without
connections could be omitted):
PC: Dev# 1, root hub, 2 ports, 12 Mbps
|_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps
|_ CN.0: Dev #3, mouse, 1.5 Mbps
|_ CN.1:
|_ CN.2: Dev #4, serial, 12 Mbps
|_ CN.3:
|_ CN.1:
### END ###

138
Documentation/usb/rio.txt Normal file
View file

@ -0,0 +1,138 @@
Copyright (C) 1999, 2000 Bruce Tenison
Portions Copyright (C) 1999, 2000 David Nelson
Thanks to David Nelson for guidance and the usage of the scanner.txt
and scanner.c files to model our driver and this informative file.
Mar. 2, 2000
CHANGES
- Initial Revision
OVERVIEW
This README will address issues regarding how to configure the kernel
to access a RIO 500 mp3 player.
Before I explain how to use this to access the Rio500 please be warned:
W A R N I N G:
--------------
Please note that this software is still under development. The authors
are in no way responsible for any damage that may occur, no matter how
inconsequential.
It seems that the Rio has a problem when sending .mp3 with low batteries.
I suggest when the batteries are low and want to transfer stuff that you
replace it with a fresh one. In my case, what happened is I lost two 16kb
blocks (they are no longer usable to store information to it). But I don't
know if thats normal or not. It could simply be a problem with the flash
memory.
In an extreme case, I left my Rio playing overnight and the batteries wore
down to nothing and appear to have corrupted the flash memory. My RIO
needed to be replaced as a result. Diamond tech support is aware of the
problem. Do NOT allow your batteries to wear down to nothing before
changing them. It appears RIO 500 firmware does not handle low battery
power well at all.
On systems with OHCI controllers, the kernel OHCI code appears to have
power on problems with some chipsets. If you are having problems
connecting to your RIO 500, try turning it on first and then plugging it
into the USB cable.
Contact information:
--------------------
The main page for the project is hosted at sourceforge.net in the following
address: http://rio500.sourceforge.net You can also go to the sourceforge
project page at: http://sourceforge.net/project/?group_id=1944 There is
also a mailing list: [email protected]
Authors:
-------
Most of the code was written by Cesar Miquel <[email protected]>. Keith
Clayton <[email protected]> is incharge of the PPC port and making sure
things work there. Bruce Tenison <[email protected]> is adding support
for .fon files and also does testing. The program will mostly sure be
re-written and Pete Ikusz along with the rest will re-design it. I would
also like to thank Tri Nguyen <[email protected]> who provided use
with some important information regarding the communication with the Rio.
ADDITIONAL INFORMATION and Userspace tools
http://rio500.sourceforge.net/
REQUIREMENTS
A host with a USB port. Ideally, either a UHCI (Intel) or OHCI
(Compaq and others) hardware port should work.
A Linux development kernel (2.3.x) with USB support enabled or a
backported version to linux-2.2.x. See http://www.linux-usb.org for
more information on accomplishing this.
A Linux kernel with RIO 500 support enabled.
'lspci' which is only needed to determine the type of USB hardware
available in your machine.
CONFIGURATION
Using `lspci -v`, determine the type of USB hardware available.
If you see something like:
USB Controller: ......
Flags: .....
I/O ports at ....
Then you have a UHCI based controller.
If you see something like:
USB Controller: .....
Flags: ....
Memory at .....
Then you have a OHCI based controller.
Using `make menuconfig` or your preferred method for configuring the
kernel, select 'Support for USB', 'OHCI/UHCI' depending on your
hardware (determined from the steps above), 'USB Diamond Rio500 support', and
'Preliminary USB device filesystem'. Compile and install the modules
(you may need to execute `depmod -a` to update the module
dependencies).
Add a device for the USB rio500:
`mknod /dev/usb/rio500 c 180 64`
Set appropriate permissions for /dev/usb/rio500 (don't forget about
group and world permissions). Both read and write permissions are
required for proper operation.
Load the appropriate modules (if compiled as modules):
OHCI:
modprobe usbcore
modprobe usb-ohci
modprobe rio500
UHCI:
modprobe usbcore
modprobe usb-uhci (or uhci)
modprobe rio500
That's it. The Rio500 Utils at: http://rio500.sourceforge.net should
be able to access the rio500.
BUGS
If you encounter any problems feel free to drop me an email.
Bruce Tenison
[email protected]

54
Documentation/usb/se401.txt Normal file
View file

@ -0,0 +1,54 @@
Linux driver for SE401 based USB cameras
Copyright, 2001, Jeroen Vreeken
INTRODUCTION:
The SE401 chip is the used in low-cost usb webcams.
It is produced by Endpoints Inc. (www.endpoints.com).
It interfaces directly to a cmos image sensor and USB. The only other major
part in a se401 based camera is a dram chip.
The following cameras are known to work with this driver:
Aox se401 (non-branded) cameras
Philips PVCV665 USB VGA webcam 'Vesta Fun'
Kensington VideoCAM PC Camera Model 67014
Kensington VideoCAM PC Camera Model 67015
Kensington VideoCAM PC Camera Model 67016
Kensington VideoCAM PC Camera Model 67017
WHAT YOU NEED:
- USB support
- VIDEO4LINUX support
More information about USB support for linux can be found at:
http://www.linux-usb.org
MODULE OPTIONS:
When the driver is compiled as a module you can also use the 'flickerless'
option. With it exposure is limited to values that do not interfere with the
net frequency. Valid options for this option are 0, 50 and 60. (0=disable,
50=50hz, 60=60hz)
KNOWN PROBLEMS:
The driver works fine with the usb-ohci and uhci host controller drivers,
the default settings also work with usb-uhci. But sending more than one bulk
transfer at a time with usb-uhci doesn't work yet.
Users of usb-ohci and uhci can safely enlarge SE401_NUMSBUF in se401.h in
order to increase the throughput (and thus framerate).
HELP:
The latest info on this driver can be found at:
http://www.chello.nl/~j.vreeken/se401/
And questions to me can be send to:
[email protected]

480
Documentation/usb/sn9c102.txt Normal file
View file

@ -0,0 +1,480 @@
SN9C10x PC Camera Controllers
Driver for Linux
=============================
- Documentation -
Index
=====
1. Copyright
2. Disclaimer
3. License
4. Overview and features
5. Module dependencies
6. Module loading
7. Module parameters
8. Optional device control through "sysfs"
9. Supported devices
10. How to add plug-in's for new image sensors
11. Notes for V4L2 application developers
12. Video frame formats
13. Contact information
14. Credits
1. Copyright
============
Copyright (C) 2004-2005 by Luca Risolia <[email protected]>
2. Disclaimer
=============
SONiX is a trademark of SONiX Technology Company Limited, inc.
This software is not sponsored or developed by SONiX.
3. License
==========
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
4. Overview and features
========================
This driver attempts to support the video and audio streaming capabilities of
the devices mounting the SONiX SN9C101, SN9C102 and SN9C103 PC Camera
Controllers.
It's worth to note that SONiX has never collaborated with the author during the
development of this project, despite several requests for enough detailed
specifications of the register tables, compression engine and video data format
of the above chips. Nevertheless, these informations are no longer necessary,
becouse all the aspects related to these chips are known and have been
described in detail in this documentation.
The driver relies on the Video4Linux2 and USB core modules. It has been
designed to run properly on SMP systems as well.
The latest version of the SN9C10x driver can be found at the following URL:
http://www.linux-projects.org/
Some of the features of the driver are:
- full compliance with the Video4Linux2 API (see also "Notes for V4L2
application developers" paragraph);
- available mmap or read/poll methods for video streaming through isochronous
data transfers;
- automatic detection of image sensor;
- support for any window resolutions and optional panning within the maximum
pixel area of image sensor;
- image downscaling with arbitrary scaling factors from 1, 2 and 4 in both
directions (see "Notes for V4L2 application developers" paragraph);
- two different video formats for uncompressed or compressed data in low or
high compression quality (see also "Notes for V4L2 application developers"
and "Video frame formats" paragraphs);
- full support for the capabilities of many of the possible image sensors that
can be connected to the SN9C10x bridges, including, for istance, red, green,
blue and global gain adjustments and exposure (see "Supported devices"
paragraph for details);
- use of default color settings for sunlight conditions;
- dynamic I/O interface for both SN9C10x and image sensor control and
monitoring (see "Optional device control through 'sysfs'" paragraph);
- dynamic driver control thanks to various module parameters (see "Module
parameters" paragraph);
- up to 64 cameras can be handled at the same time; they can be connected and
disconnected from the host many times without turning off the computer, if
your system supports hotplugging;
- no known bugs.
5. Module dependencies
======================
For it to work properly, the driver needs kernel support for Video4Linux and
USB.
The following options of the kernel configuration file must be enabled and
corresponding modules must be compiled:
# Multimedia devices
#
CONFIG_VIDEO_DEV=m
# USB support
#
CONFIG_USB=m
In addition, depending on the hardware being used, the modules below are
necessary:
# USB Host Controller Drivers
#
CONFIG_USB_EHCI_HCD=m
CONFIG_USB_UHCI_HCD=m
CONFIG_USB_OHCI_HCD=m
And finally:
# USB Multimedia devices
#
CONFIG_USB_SN9C102=m
6. Module loading
=================
To use the driver, it is necessary to load the "sn9c102" module into memory
after every other module required: "videodev", "usbcore" and, depending on
the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
Loading can be done as shown below:
[root@localhost home]# modprobe sn9c102
At this point the devices should be recognized. You can invoke "dmesg" to
analyze kernel messages and verify that the loading process has gone well:
[user@localhost home]$ dmesg
7. Module parameters
====================
Module parameters are listed below:
-------------------------------------------------------------------------------
Name: video_nr
Type: int array (min = 0, max = 64)
Syntax: <-1|n[,...]>
Description: Specify V4L2 minor mode number:
-1 = use next available
n = use minor number n
You can specify up to 64 cameras this way.
For example:
video_nr=-1,2,-1 would assign minor number 2 to the second
recognized camera and use auto for the first one and for every
other camera.
Default: -1
-------------------------------------------------------------------------------
Name: force_munmap;
Type: bool array (min = 0, max = 64)
Syntax: <0|1[,...]>
Description: Force the application to unmap previously mapped buffer memory
before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not
all the applications support this feature. This parameter is
specific for each detected camera.
0 = do not force memory unmapping"
1 = force memory unmapping (save memory)"
Default: 0
-------------------------------------------------------------------------------
Name: debug
Type: int
Syntax: <n>
Description: Debugging information level, from 0 to 3:
0 = none (use carefully)
1 = critical errors
2 = significant informations
3 = more verbose messages
Level 3 is useful for testing only, when only one device
is used. It also shows some more informations about the
hardware being detected. This parameter can be changed at
runtime thanks to the /sys filesystem.
Default: 2
-------------------------------------------------------------------------------
8. Optional device control through "sysfs" [1]
==========================================
It is possible to read and write both the SN9C10x and the image sensor
registers by using the "sysfs" filesystem interface.
Every time a supported device is recognized, a write-only file named "green" is
created in the /sys/class/video4linux/videoX directory. You can set the green
channel's gain by writing the desired value to it. The value may range from 0
to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges.
Similarly, only for SN9C103 controllers, blue and red gain control files are
available in the same directory, for which accepted values may range from 0 to
127.
There are other four entries in the directory above for each registered camera:
"reg", "val", "i2c_reg" and "i2c_val". The first two files control the
SN9C10x bridge, while the other two control the sensor chip. "reg" and
"i2c_reg" hold the values of the current register index where the following
reading/writing operations are addressed at through "val" and "i2c_val". Their
use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not
be created if the sensor does not actually support the standard I2C protocol or
its registers are not 8-bit long. Also, remember that you must be logged in as
root before writing to them.
As an example, suppose we were to want to read the value contained in the
register number 1 of the sensor register table - which is usually the product
identifier - of the camera registered as "/dev/video0":
[root@localhost #] cd /sys/class/video4linux/video0
[root@localhost #] echo 1 > i2c_reg
[root@localhost #] cat i2c_val
Note that "cat" will fail if sensor registers cannot be read.
Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2:
[root@localhost #] echo 0x11 > reg
[root@localhost #] echo 2 > val
Note that the SN9C10x always returns 0 when some of its registers are read.
To avoid race conditions, all the I/O accesses to the above files are
serialized.
The sysfs interface also provides the "frame_header" entry, which exports the
frame header of the most recent requested and captured video frame. The header
is 12-bytes long and is appended to every video frame by the SN9C10x
controllers. As an example, this additional information can be used by the user
application for implementing auto-exposure features via software.
The following table describes the frame header:
Byte # Value Description
------ ----- -----------
0x00 0xFF Frame synchronisation pattern.
0x01 0xFF Frame synchronisation pattern.
0x02 0x00 Frame synchronisation pattern.
0x03 0xC4 Frame synchronisation pattern.
0x04 0xC4 Frame synchronisation pattern.
0x05 0x96 Frame synchronisation pattern.
0x06 0x00 or 0x01 Unknown meaning. The exact value depends on the chip.
0x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a
frame counter, u is unknown, zz is a size indicator
(00 = VGA, 01 = SIF, 10 = QSIF) and c stands for
"compression enabled" (1 = yes, 0 = no).
0x08 0xXX Brightness sum inside Auto-Exposure area (low-byte).
0x09 0xXX Brightness sum inside Auto-Exposure area (high-byte).
For a pure white image, this number will be equal to 500
times the area of the specified AE area. For images
that are not pure white, the value scales down according
to relative whiteness.
0x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte).
0x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte).
For a pure white image, this number will be equal to 125
times the area outside of the specified AE area. For
images that are not pure white, the value scales down
according to relative whiteness.
The AE area (sx, sy, ex, ey) in the active window can be set by programming the
registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit
corresponds to 32 pixels.
[1] The frame header has been documented by Bertrik Sikken.
9. Supported devices
====================
None of the names of the companies as well as their products will be mentioned
here. They have never collaborated with the author, so no advertising.
From the point of view of a driver, what unambiguously identify a device are
its vendor and product USB identifiers. Below is a list of known identifiers of
devices mounting the SN9C10x PC camera controllers:
Vendor ID Product ID
--------- ----------
0x0c45 0x6001
0x0c45 0x6005
0x0c45 0x6009
0x0c45 0x600d
0x0c45 0x6024
0x0c45 0x6025
0x0c45 0x6028
0x0c45 0x6029
0x0c45 0x602a
0x0c45 0x602b
0x0c45 0x602c
0x0c45 0x6030
0x0c45 0x6080
0x0c45 0x6082
0x0c45 0x6083
0x0c45 0x6088
0x0c45 0x608a
0x0c45 0x608b
0x0c45 0x608c
0x0c45 0x608e
0x0c45 0x608f
0x0c45 0x60a0
0x0c45 0x60a2
0x0c45 0x60a3
0x0c45 0x60a8
0x0c45 0x60aa
0x0c45 0x60ab
0x0c45 0x60ac
0x0c45 0x60ae
0x0c45 0x60af
0x0c45 0x60b0
0x0c45 0x60b2
0x0c45 0x60b3
0x0c45 0x60b8
0x0c45 0x60ba
0x0c45 0x60bb
0x0c45 0x60bc
0x0c45 0x60be
The list above does not imply that all those devices work with this driver: up
until now only the ones that mount the following image sensors are supported;
kernel messages will always tell you whether this is the case:
Model Manufacturer
----- ------------
HV7131D Hynix Semiconductor, Inc.
MI-0343 Micron Technology, Inc.
PAS106B PixArt Imaging, Inc.
PAS202BCB PixArt Imaging, Inc.
TAS5110C1B Taiwan Advanced Sensor Corporation
TAS5130D1B Taiwan Advanced Sensor Corporation
All the available control settings of each image sensor are supported through
the V4L2 interface.
Donations of new models for further testing and support would be much
appreciated. Non-available hardware will not be supported by the author of this
driver.
10. How to add plug-in's for new image sensors
==============================================
It should be easy to write plug-in's for new sensors by using the small API
that has been created for this purpose, which is present in "sn9c102_sensor.h"
(documentation is included there). As an example, have a look at the code in
"sn9c102_pas106b.c", which uses the mentioned interface.
At the moment, possible unsupported image sensors are: CIS-VF10 (VGA),
OV7620 (VGA), OV7630 (VGA).
11. Notes for V4L2 application developers
=========================================
This driver follows the V4L2 API specifications. In particular, it enforces two
rules:
- exactly one I/O method, either "mmap" or "read", is associated with each
file descriptor. Once it is selected, the application must close and reopen the
device to switch to the other I/O method;
- although it is not mandatory, previously mapped buffer memory should always
be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
The same number of buffers as before will be allocated again to match the size
of the new video frames, so you have to map the buffers again before any I/O
attempts on them.
Consistently with the hardware limits, this driver also supports image
downscaling with arbitrary scaling factors from 1, 2 and 4 in both directions.
However, the V4L2 API specifications don't correctly define how the scaling
factor can be chosen arbitrarily by the "negotiation" of the "source" and
"target" rectangles. To work around this flaw, we have added the convention
that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
scaling factor is restored to 1.
This driver supports two different video formats: the first one is the "8-bit
Sequential Bayer" format and can be used to obtain uncompressed video data
from the device through the current I/O method, while the second one provides
"raw" compressed video data (without frame headers not related to the
compressed data). The compression quality may vary from 0 to 1 and can be
selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP V4L2
ioctl's. For maximum flexibility, both the default active video format and the
default compression quality depend on how the image sensor being used is
initialized (as described in the documentation of the API for the image sensors
supplied by this driver).
12. Video frame formats [1]
=======================
The SN9C10x PC Camera Controllers can send images in two possible video
formats over the USB: either native "Sequential RGB Bayer" or Huffman
compressed. The latter is used to achieve high frame rates. The current video
format may be selected or queried from the user application by calling the
VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API
specifications.
The name "Sequential Bayer" indicates the organization of the red, green and
blue pixels in one video frame. Each pixel is associated with a 8-bit long
value and is disposed in memory according to the pattern shown below:
B[0] G[1] B[2] G[3] ... B[m-2] G[m-1]
G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1]
...
... B[(n-1)(m-2)] G[(n-1)(m-1)]
... G[n(m-2)] R[n(m-1)]
The above matrix also represents the sequential or progressive read-out mode of
the (n, m) Bayer color filter array used in many CCD/CMOS image sensors.
One compressed video frame consists of a bitstream that encodes for every R, G,
or B pixel the difference between the value of the pixel itself and some
reference pixel value. Pixels are organised in the Bayer pattern and the Bayer
sub-pixels are tracked individually and alternatingly. For example, in the
first line values for the B and G1 pixels are alternatingly encoded, while in
the second line values for the G2 and R pixels are alternatingly encoded.
The pixel reference value is calculated as follows:
- the 4 top left pixels are encoded in raw uncompressed 8-bit format;
- the value in the top two rows is the value of the pixel left of the current
pixel;
- the value in the left column is the value of the pixel above the current
pixel;
- for all other pixels, the reference value is the average of the value of the
pixel on the left and the value of the pixel above the current pixel;
- there is one code in the bitstream that specifies the value of a pixel
directly (in 4-bit resolution);
- pixel values need to be clamped inside the range [0..255] for proper
decoding.
The algorithm purely describes the conversion from compressed Bayer code used
in the SN9C10x chips to uncompressed Bayer. Additional steps are required to
convert this to a color image (i.e. a color interpolation algorithm).
The following Huffman codes have been found:
0: +0 (relative to reference pixel value)
100: +4
101: -4?
1110xxxx: set absolute value to xxxx.0000
1101: +11
1111: -11
11001: +20
110000: -20
110001: ??? - these codes are apparently not used
[1] The Huffman compression algorithm has been reverse-engineered and
documented by Bertrik Sikken.
13. Contact information
=======================
The author may be contacted by e-mail at <[email protected]>.
GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
'FCE635A4'; the public 1024-bit key should be available at any keyserver;
the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
14. Credits
===========
Many thanks to following persons for their contribute (listed in alphabetical
order):
- Luca Capello for the donation of a webcam;
- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the
donation of a webcam;
- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB
image sensor;
- Stefano Mozzi, who donated 45 EU;
- Bertrik Sikken, who reverse-engineered and documented the Huffman compression
algorithm used in the SN9C10x controllers and implemented the first decoder;
- Mizuno Takafumi for the donation of a webcam;
- An "anonymous" donator (who didn't want his name to be revealed) for the
donation of a webcam.

55
Documentation/usb/stv680.txt Normal file
View file

@ -0,0 +1,55 @@
Linux driver for STV0680 based USB cameras
Copyright, 2001, Kevin Sisson
INTRODUCTION:
STMicroelectronics produces the STV0680B chip, which comes in two
types, -001 and -003. The -003 version allows the recording and downloading
of sound clips from the camera, and allows a flash attachment. Otherwise,
it uses the same commands as the -001 version. Both versions support a
variety of SDRAM sizes and sensors, allowing for a maximum of 26 VGA or 20
CIF pictures. The STV0680 supports either a serial or a usb interface, and
video is possible through the usb interface.
The following cameras are known to work with this driver, although any
camera with Vendor/Product codes of 0553/0202 should work:
Aiptek Pencam (various models)
Nisis QuickPix 2
Radio Shack 'Kid's digital camera' (#60-1207)
At least one Trust Spycam model
Several other European brand models
WHAT YOU NEED:
- USB support
- VIDEO4LINUX support
More information about USB support for linux can be found at:
http://www.linux-usb.org
MODULE OPTIONS:
When the driver is compiled as a module, you can set a "swapRGB=1"
option, if necessary, for those applications that require it
(such as xawtv). However, the driver should detect and set this
automatically, so this option should not normally be used.
KNOWN PROBLEMS:
The driver seems to work better with the usb-ohci than the usb-uhci host
controller driver.
HELP:
The latest info on this driver can be found at:
http://personal.clt.bellsouth.net/~kjsisson or at
http://stv0680-usb.sourceforge.net
Any questions to me can be send to: [email protected]

165
Documentation/usb/uhci.txt Normal file
View file

@ -0,0 +1,165 @@
Specification and Internals for the New UHCI Driver (Whitepaper...)
brought to you by
Georg Acher, [email protected] (executive slave) (base guitar)
Deti Fliegl, [email protected] (executive slave) (lead voice)
Thomas Sailer, [email protected] (chief consultant) (cheer leader)
$Id: README.uhci,v 1.1 1999/12/14 14:03:02 fliegl Exp $
This document and the new uhci sources can be found on
http://hotswap.in.tum.de/usb
1. General issues
1.1 Why a new UHCI driver, we already have one?!?
Correct, but its internal structure got more and more mixed up by the (still
ongoing) efforts to get isochronous transfers (ISO) to work.
Since there is an increasing need for reliable ISO-transfers (especially
for USB-audio needed by TS and for a DAB-USB-Receiver build by GA and DF),
this state was a bit unsatisfying in our opinion, so we've decided (based
on knowledge and experiences with the old UHCI driver) to start
from scratch with a new approach, much simpler but at the same time more
powerful.
It is inspired by the way Win98/Win2000 handles USB requests via URBs,
but it's definitely 100% free of MS-code and doesn't crash while
unplugging an used ISO-device like Win98 ;-)
Some code for HW setup and root hub management was taken from the
original UHCI driver, but heavily modified to fit into the new code.
The invention of the basic concept, and major coding were completed in two
days (and nights) on the 16th and 17th of October 1999, now known as the
great USB-October-Revolution started by GA, DF, and TS ;-)
Since the concept is in no way UHCI dependent, we hope that it will also be
transferred to the OHCI-driver, so both drivers share a common API.
1.2. Advantages and disadvantages
+ All USB transfer types work now!
+ Asynchronous operation
+ Simple, but powerful interface (only two calls for start and cancel)
+ Easy migration to the new API, simplified by a compatibility API
+ Simple usage of ISO transfers
+ Automatic linking of requests
+ ISO transfers allow variable length for each frame and striping
+ No CPU dependent and non-portable atomic memory access, no asm()-inlines
+ Tested on x86 and Alpha
- Rewriting for ISO transfers needed
1.3. Is there some compatibility to the old API?
Yes, but only for control, bulk and interrupt transfers. We've implemented
some wrapper calls for these transfer types. The usbcore works fine with
these wrappers. For ISO there's no compatibility, because the old ISO-API
and its semantics were unnecessary complicated in our opinion.
1.4. What's really working?
As said above, CTRL and BULK already work fine even with the wrappers,
so legacy code wouldn't notice the change.
Regarding to Thomas, ISO transfers now run stable with USB audio.
INT transfers (e.g. mouse driver) work fine, too.
1.5. Are there any bugs?
No ;-)
Hm...
Well, of course this implementation needs extensive testing on all available
hardware, but we believe that any fixes shouldn't harm the overall concept.
1.6. What should be done next?
A large part of the request handling seems to be identical for UHCI and
OHCI, so it would be a good idea to extract the common parts and have only
the HW specific stuff in uhci.c. Furthermore, all other USB device drivers
should need URBification, if they use isochronous or interrupt transfers.
One thing missing in the current implementation (and the old UHCI driver)
is fair queueing for BULK transfers. Since this would need (in principle)
the alteration of already constructed TD chains (to switch from depth to
breadth execution), another way has to be found. Maybe some simple
heuristics work with the same effect.
---------------------------------------------------------------------------
2. Internal structure and mechanisms
To get quickly familiar with the internal structures, here's a short
description how the new UHCI driver works. However, the ultimate source of
truth is only uhci.c!
2.1. Descriptor structure (QHs and TDs)
During initialization, the following skeleton is allocated in init_skel:
framespecific | common chain
framelist[]
[ 0 ]-----> TD --> TD -------\
[ 1 ]-----> TD --> TD --------> TD ----> QH -------> QH -------> QH ---> NULL
... TD --> TD -------/
[1023]-----> TD --> TD ------/
^^ ^^ ^^ ^^ ^^ ^^
1024 TDs for 7 TDs for 1 TD for Start of Start of End Chain
ISO INT (2-128ms) 1ms-INT CTRL Chain BULK Chain
For each CTRL or BULK transfer a new QH is allocated and the containing data
transfers are appended as (vertical) TDs. After building the whole QH with its
dangling TDs, the QH is inserted before the BULK Chain QH (for CTRL) or
before the End Chain QH (for BULK). Since only the QH->next pointers are
affected, no atomic memory operation is required. The three QHs in the
common chain are never equipped with TDs!
For ISO or INT, the TD for each frame is simply inserted into the appropriate
ISO/INT-TD-chain for the desired frame. The 7 skeleton INT-TDs are scattered
among the 1024 frames similar to the old UHCI driver.
For CTRL/BULK/ISO, the last TD in the transfer has the IOC-bit set. For INT,
every TD (there is only one...) has the IOC-bit set.
Besides the data for the UHCI controller (2 or 4 32bit words), the descriptors
are double-linked through the .vertical and .horizontal elements in the
SW data of the descriptor (using the double-linked list structures and
operations), but SW-linking occurs only in closed domains, i.e. for each of
the 1024 ISO-chains and the 8 INT-chains there is a closed cycle. This
simplifies all insertions and unlinking operations and avoids costly
bus_to_virt()-calls.
2.2. URB structure and linking to QH/TDs
During assembly of the QH and TDs of the requested action, these descriptors
are stored in urb->urb_list, so the allocated QH/TD descriptors are bound to
this URB.
If the assembly was successful and the descriptors were added to the HW chain,
the corresponding URB is inserted into a global URB list for this controller.
This list stores all pending URBs.
2.3. Interrupt processing
Since UHCI provides no means to directly detect completed transactions, the
following is done in each UHCI interrupt (uhci_interrupt()):
For each URB in the pending queue (process_urb()), the ACTIVE-flag of the
associated TDs are processed (depending on the transfer type
process_{transfer|interrupt|iso}()). If the TDs are not active anymore,
they indicate the completion of the transaction and the status is calculated.
Inactive QH/TDs are removed from the HW chain (since the host controller
already removed the TDs from the QH, no atomic access is needed) and
eventually the URB is marked as completed (OK or errors) and removed from the
pending queue. Then the next linked URB is submitted. After (or immediately
before) that, the completion handler is called.
2.4. Unlinking URBs
First, all QH/TDs stored in the URB are unlinked from the HW chain.
To ensure that the host controller really left a vertical TD chain, we
wait for one frame. After that, the TDs are physically destroyed.
2.5. URB linking and the consequences
Since URBs can be linked and the corresponding submit_urb is called in
the UHCI-interrupt, all work associated with URB/QH/TD assembly has to be
interrupt save. This forces kmalloc to use GFP_ATOMIC in the interrupt.

19
Documentation/usb/usb-help.txt Normal file
View file

@ -0,0 +1,19 @@
usb-help.txt
2000-July-12
For USB help other than the readme files that are located in
Documentation/usb/*, see the following:
Linux-USB project: http://www.linux-usb.org
mirrors at http://www.suse.cz/development/linux-usb/
and http://usb.in.tum.de/linux-usb/
and http://it.linux-usb.org
Linux USB Guide: http://linux-usb.sourceforge.net
Linux-USB device overview (working devices and drivers):
http://www.qbik.ch/usb/devices/
The Linux-USB mailing lists are:
[email protected] for general user help
[email protected] for developer discussions
###

470
Documentation/usb/usb-serial.txt Normal file
View file

@ -0,0 +1,470 @@
INTRODUCTION
The USB serial driver currently supports a number of different USB to
serial converter products, as well as some devices that use a serial
interface from userspace to talk to the device.
See the individual product section below for specific information about
the different devices.
CONFIGURATION
Currently the driver can handle up to 256 different serial interfaces at
one time.
If you are not using devfs:
The major number that the driver uses is 188 so to use the driver,
create the following nodes:
mknod /dev/ttyUSB0 c 188 0
mknod /dev/ttyUSB1 c 188 1
mknod /dev/ttyUSB2 c 188 2
mknod /dev/ttyUSB3 c 188 3
.
.
.
mknod /dev/ttyUSB254 c 188 254
mknod /dev/ttyUSB255 c 188 255
If you are using devfs:
The devices supported by this driver will show up as
/dev/usb/tts/{0,1,...}
When the device is connected and recognized by the driver, the driver
will print to the system log, which node(s) the device has been bound
to.
SPECIFIC DEVICES SUPPORTED
ConnectTech WhiteHEAT 4 port converter
ConnectTech has been very forthcoming with information about their
device, including providing a unit to test with.
The driver is officially supported by Connect Tech Inc.
http://www.connecttech.com
For any questions or problems with this driver, please contact
Stuart MacDonald at [email protected]
HandSpring Visor, Palm USB, and Clié USB driver
This driver works with all HandSpring USB, Palm USB, and Sony Clié USB
devices.
Only when the device tries to connect to the host, will the device show
up to the host as a valid USB device. When this happens, the device is
properly enumerated, assigned a port, and then communication _should_ be
possible. The driver cleans up properly when the device is removed, or
the connection is canceled on the device.
NOTE:
This means that in order to talk to the device, the sync button must be
pressed BEFORE trying to get any program to communicate to the device.
This goes against the current documentation for pilot-xfer and other
packages, but is the only way that it will work due to the hardware
in the device.
When the device is connected, try talking to it on the second port
(this is usually /dev/ttyUSB1 if you do not have any other usb-serial
devices in the system.) The system log should tell you which port is
the port to use for the HotSync transfer. The "Generic" port can be used
for other device communication, such as a PPP link.
For some Sony Clié devices, /dev/ttyUSB0 must be used to talk to the
device. This is true for all OS version 3.5 devices, and most devices
that have had a flash upgrade to a newer version of the OS. See the
kernel system log for information on which is the correct port to use.
If after pressing the sync button, nothing shows up in the system log,
try resetting the device, first a hot reset, and then a cold reset if
necessary. Some devices need this before they can talk to the USB port
properly.
Devices that are not compiled into the kernel can be specified with module
parameters. e.g. modprobe visor vendor=0x54c product=0x66
There is a webpage and mailing lists for this portion of the driver at:
http://usbvisor.sourceforge.net/
For any questions or problems with this driver, please contact Greg
Kroah-Hartman at [email protected]
PocketPC PDA Driver
This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500
and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB
cable/cradle.
Most devices supported by ActiveSync are supported out of the box.
For others, please use module parameters to specify the product and vendor
id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125
The driver presents a serial interface (usually on /dev/ttyUSB0) over
which one may run ppp and establish a TCP/IP link to the PDA. Once this
is done, you can transfer files, backup, download email etc. The most
significant advantage of using USB is speed - I can get 73 to 113
kbytes/sec for download/upload to my iPAQ.
This driver is only one of a set of components required to utilize
the USB connection. Please visit http://synce.sourceforge.net which
contains the necessary packages and a simple step-by-step howto.
Once connected, you can use Win CE programs like ftpView, Pocket Outlook
from the PDA and xcerdisp, synce utilities from the Linux side.
To use Pocket IE, follow the instructions given at
http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing
on Win98. Omit the proxy server part; Linux is quite capable of forwarding
packets unlike Win98. Another modification is required at least for the
iPAQ - disable autosync by going to the Start/Settings/Connections menu
and unchecking the "Automatically synchronize ..." box. Go to
Start/Programs/Connections, connect the cable and select "usbdial" (or
whatever you named your new USB connection). You should finally wind
up with a "Connected to usbdial" window with status shown as connected.
Now start up PIE and browse away.
If it doesn't work for some reason, load both the usbserial and ipaq module
with the module parameter "debug" set to 1 and examine the system log.
You can also try soft-resetting your PDA before attempting a connection.
Other functionality may be possible depending on your PDA. According to
Wes Cilldhaire <[email protected]>, with the Toshiba E570,
...if you boot into the bootloader (hold down the power when hitting the
reset button, continuing to hold onto the power until the bootloader screen
is displayed), then put it in the cradle with the ipaq driver loaded, open
a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can
be used to flash the ROM, as well as the microP code.. so much for needing
Toshiba's $350 serial cable for flashing!! :D
NOTE: This has NOT been tested. Use at your own risk.
For any questions or problems with the driver, please contact Ganesh
Varadarajan <[email protected]>
Keyspan PDA Serial Adapter
Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly
sold in Macintosh catalogs, comes in a translucent white/green dongle).
Fairly simple device. Firmware is homebrew.
This driver also works for the Xircom/Entrgra single port serial adapter.
Current status:
Things that work:
basic input/output (tested with 'cu')
blocking write when serial line can't keep up
changing baud rates (up to 115200)
getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC})
sending break (although duration looks suspect)
Things that don't:
device strings (as logged by kernel) have trailing binary garbage
device ID isn't right, might collide with other Keyspan products
changing baud rates ought to flush tx/rx to avoid mangled half characters
Big Things on the todo list:
parity, 7 vs 8 bits per char, 1 or 2 stop bits
HW flow control
not all of the standard USB descriptors are handled: Get_Status, Set_Feature
O_NONBLOCK, select()
For any questions or problems with this driver, please contact Brian
Warner at [email protected]
Keyspan USA-series Serial Adapters
Single, Dual and Quad port adapters - driver uses Keyspan supplied
firmware and is being developed with their support.
Current status:
The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and
have been pretty throughly tested at various baud rates with 8-N-1
character settings. Other character lengths and parity setups are
presently untested.
The USA-28 isn't yet supported though doing so should be pretty
straightforward. Contact the maintainer if you require this
functionality.
More information is available at:
http://misc.nu/hugh/keyspan.html
For any questions or problems with this driver, please contact Hugh
Blemings at [email protected]
FTDI Single Port Serial Driver
This is a single port DB-25 serial adapter. More information about this
device and the Linux driver can be found at:
http://reality.sgi.com/bryder_wellington/ftdi_sio/
For any questions or problems with this driver, please contact Bill Ryder
at [email protected]
ZyXEL omni.net lcd plus ISDN TA
This is an ISDN TA. Please report both successes and troubles to
[email protected]
Cypress M8 CY4601 Family Serial Driver
This driver was in most part developed by Neil "koyama" Whelchel. It
has been improved since that previous form to support dynamic serial
line settings and improved line handling. The driver is for the most
part stable and has been tested on an smp machine. (dual p2)
Chipsets supported under CY4601 family:
CY7C63723, CY7C63742, CY7C63743, CY7C64013
Devices supported:
-DeLorme's USB Earthmate (SiRF Star II lp arch)
-Cypress HID->COM RS232 adapter
Note: Cypress Semiconductor claims no affiliation with the
the hid->com device.
Most devices using chipsets under the CY4601 family should
work with the driver. As long as they stay true to the CY4601
usbserial specification.
Technical notes:
The Earthmate starts out at 4800 8N1 by default... the driver will
upon start init to this setting. usbserial core provides the rest
of the termios settings, along with some custom termios so that the
output is in proper format and parsable.
The device can be put into sirf mode by issuing NMEA command:
$PSRF100,<protocol>,<baud>,<databits>,<stopbits>,<parity>*CHECKSUM
$PSRF100,0,9600,8,1,0*0C
It should then be sufficient to change the port termios to match this
to begin communicating.
As far as I can tell it supports pretty much every sirf command as
documented online available with firmware 2.31, with some unknown
message ids.
The hid->com adapter can run at a maximum baud of 115200bps. Please note
that the device has trouble or is incapable of raising line voltage properly.
It will be fine with null modem links, as long as you do not try to link two
together without hacking the adapter to set the line high.
The driver is smp safe. Performance with the driver is rather low when using
it for transfering files. This is being worked on, but I would be willing to
accept patches. An urb queue or packet buffer would likely fit the bill here.
If you have any questions, problems, patches, feature requests, etc. you can
contact me here via email:
[email protected]
(your problems/patches can alternately be submitted to usb-devel)
Digi AccelePort Driver
This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port
(plus a parallel port) and 4 port USB serial converters. The driver
does NOT yet support the Digi AccelePort USB 8.
This driver works under SMP with the usb-uhci driver. It does not
work under SMP with the uhci driver.
The driver is generally working, though we still have a few more ioctls
to implement and final testing and debugging to do. The paralled port
on the USB 2 is supported as a serial to parallel converter; in other
words, it appears as another USB serial port on Linux, even though
physically it is really a parallel port. The Digi Acceleport USB 8
is not yet supported.
Please contact Peter Berger ([email protected]) or Al Borchers
([email protected]) for questions or problems with this
driver.
Belkin USB Serial Adapter F5U103
Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs.
The Peracom single port serial adapter also works with this driver, as
well as the GoHubs adapter.
Current status:
The following have been tested and work:
Baud rate 300-230400
Data bits 5-8
Stop bits 1-2
Parity N,E,O,M,S
Handshake None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR)*
Break Set and clear
Line contrl Input/Output query and control **
* Hardware input flow control is only enabled for firmware
levels above 2.06. Read source code comments describing Belkin
firmware errata. Hardware output flow control is working for all
firmware versions.
** Queries of inputs (CTS,DSR,CD,RI) show the last
reported state. Queries of outputs (DTR,RTS) show the last
requested state and may not reflect current state as set by
automatic hardware flow control.
TO DO List:
-- Add true modem contol line query capability. Currently tracks the
states reported by the interrupt and the states requested.
-- Add error reporting back to application for UART error conditions.
-- Add support for flush ioctls.
-- Add everything else that is missing :)
For any questions or problems with this driver, please contact William
Greathouse at [email protected]
Empeg empeg-car Mark I/II Driver
This is an experimental driver to provide connectivity support for the
client synchronization tools for an Empeg empeg-car mp3 player.
Tips:
* Don't forget to create the device nodes for ttyUSB{0,1,2,...}
* modprobe empeg (modprobe is your friend)
* emptool --usb /dev/ttyUSB0 (or whatever you named your device node)
For any questions or problems with this driver, please contact Gary
Brubaker at [email protected]
MCT USB Single Port Serial Adapter U232
This driver is for the MCT USB-RS232 Converter (25 pin, Model No.
U232-P25) from Magic Control Technology Corp. (there is also a 9 pin
Model No. U232-P9). More information about this device can be found at
the manufacture's web-site: http://www.mct.com.tw.
The driver is generally working, though it still needs some more testing.
It is derived from the Belkin USB Serial Adapter F5U103 driver and its
TODO list is valid for this driver as well.
This driver has also been found to work for other products, which have
the same Vendor ID but different Product IDs. Sitecom's U232-P25 serial
converter uses Product ID 0x230 and Vendor ID 0x711 and works with this
driver. Also, D-Link's DU-H3SP USB BAY also works with this driver.
For any questions or problems with this driver, please contact Wolfgang
Grandegger at [email protected]
Inside Out Networks Edgeport Driver
This driver supports all devices made by Inside Out Networks, specifically
the following models:
Edgeport/4
Rapidport/4
Edgeport/4t
Edgeport/2
Edgeport/4i
Edgeport/2i
Edgeport/421
Edgeport/21
Edgeport/8
Edgeport/8 Dual
Edgeport/2D8
Edgeport/4D8
Edgeport/8i
Edgeport/2 DIN
Edgeport/4 DIN
Edgeport/16 Dual
For any questions or problems with this driver, please contact Greg
Kroah-Hartman at [email protected]
REINER SCT cyberJack pinpad/e-com USB chipcard reader
Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs.
Current status:
This is the kernel part of the driver for this USB card reader.
There is also a user part for a CT-API driver available. A site
for downloading is TBA. For now, you can request it from the
maintainer ([email protected]).
For any questions or problems with this driver, please contact
[email protected]
Prolific PL2303 Driver
This driver support any device that has the PL2303 chip from Prolific
in it. This includes a number of single port USB to serial
converters and USB GPS devices. Devices from Aten (the UC-232) and
IO-Data work with this driver.
For any questions or problems with this driver, please contact Greg
Kroah-Hartman at [email protected]
KL5KUSB105 chipset / PalmConnect USB single-port adapter
Current status:
The driver was put together by looking at the usb bus transactions
done by Palm's driver under Windows, so a lot of functionality is
still missing. Notably, serial ioctls are sometimes faked or not yet
implemented. Support for finding out about DSR and CTS line status is
however implemented (though not nicely), so your favorite autopilot(1)
and pilot-manager -daemon calls will work. Baud rates up to 115200
are supported, but handshaking (software or hardware) is not, which is
why it is wise to cut down on the rate used is wise for large
transfers until this is settled.
Options supported:
If this driver is compiled as a module you can pass the following
options to it:
debug - extra verbose debugging info
(default: 0; nonzero enables)
use_lowlatency - use low_latency flag to speed up tty layer
when reading from from the device.
(default: 0; nonzero enables)
See http://www.uuhaus.de/linux/palmconnect.html for up-to-date
information on this driver.
Generic Serial driver
If your device is not one of the above listed devices, compatible with
the above models, you can try out the "generic" interface. This
interface does not provide any type of control messages sent to the
device, and does not support any kind of device flow control. All that
is required of your device is that it has at least one bulk in endpoint,
or one bulk out endpoint.
To enable the generic driver to recognize your device, build the driver
as a module and load it by the following invocation:
insmod usbserial vendor=0x#### product=0x####
where the #### is replaced with the hex representation of your device's
vendor id and product id.
This driver has been successfully used to connect to the NetChip USB
development board, providing a way to develop USB firmware without
having to write a custom driver.
For any questions or problems with this driver, please contact Greg
Kroah-Hartman at [email protected]
CONTACT:
If anyone has any problems using these drivers, with any of the above
specified products, please contact the specific driver's author listed
above, or join the Linux-USB mailing list (information on joining the
mailing list, as well as a link to its searchable archive is at
http://www.linux-usb.org/ )
Greg Kroah-Hartman
[email protected]

156
Documentation/usb/usbmon.txt Normal file
View file

@ -0,0 +1,156 @@
* Introduction
The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.
The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.
* How to use usbmon to collect raw text traces
Unlike the packet socket, usbmon has an interface which provides traces
in a text format. This is used for two purposes. First, it serves as a
common trace exchange format for tools while most sophisticated formats
are finalized. Second, humans can read it in case tools are not available.
To collect a raw text trace, execute following steps.
1. Prepare
Mount debugfs (it has to be enabled in your kernel configuration), and
load the usbmon module (if built as module). The second step is skipped
if usbmon is built into the kernel.
# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
Verify that bus sockets are present.
[root@lembas zaitcev]# ls /sys/kernel/debug/usbmon
1s 1t 2s 2t 3s 3t 4s 4t
[root@lembas zaitcev]#
# ls /sys/kernel
2. Find which bus connects to the desired device
Run "cat /proc/bus/usb/devices", and find the T-line which corresponds to
the device. Usually you do it by looking for the vendor string. If you have
many similar devices, unplug one and compare two /proc/bus/usb/devices outputs.
The T-line will have a bus number. Example:
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Manufacturer=ATEN
S: Product=UC100KM V2.00
Bus=03 means it's bus 3.
3. Start 'cat'
# cat /sys/kernel/debug/usbmon/3t > /tmp/1.mon.out
This process will be reading until killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going
to be quite long.
4. Perform the desired operation on the USB bus
This is where you do something that creates the traffic: plug in a flash key,
copy files, control a webcam, etc.
5. Kill cat
Usually it's done with a keyboard interrupt (Control-C).
At this point the output file (/tmp/1.mon.out in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor.
* Raw text data format
The '0t' type data consists of a stream of events, such as URB submission,
URB callback, submission error. Every event is a text line, which consists
of whitespace separated words. The number of position of words may depend
on the event type, but there is a set of words, common for all types.
Here is the list of words, from left to right:
- URB Tag. This is used to identify URBs is normally a kernel mode address
of the URB structure in hexadecimal.
- Timestamp in microseconds, a decimal number. The timestamp's resolution
depends on available clock, and so it can be much worse than a microsecond
(if the implementation uses jiffies, for example).
- Event Type. This type refers to the format of the event, not URB type.
Available types are: S - submission, C - callback, E - submission error.
- "Pipe". The pipe concept is deprecated. This is a composite word, used to
be derived from information in pipes. It consists of three fields, separated
by colons: URB type and direction, Device address, Endpoint number.
Type and direction are encoded with two bytes in the following manner:
Ci Co Control input and output
Zi Zo Isochronous input and output
Ii Io Interrupt input and output
Bi Bo Bulk input and output
Device address and Endpoint number are decimal numbers with leading zeroes
or 3 and 2 positions, correspondingly.
- URB Status. This field makes no sense for submissions, but is present
to help scripts with parsing. In error case, it contains the error code.
- Data Length. This is the actual length in the URB.
- Data tag. The usbmon may not always capture data, even if length is nonzero.
Only if tag is '=', the data words are present.
- Data words follow, in big endian hexadecimal format. Notice that they are
not machine words, but really just a byte stream split into words to make
it easier to read. Thus, the last word may contain from one to four bytes.
The length of collected data is limited and can be less than the data length
report in Data Length word.
Here is an example of code to read the data stream in a well known programming
language:
class ParsedLine {
int data_len; /* Available length of data */
byte data[];
void parseData(StringTokenizer st) {
int availwords = st.countTokens();
data = new byte[availwords * 4];
data_len = 0;
while (st.hasMoreTokens()) {
String data_str = st.nextToken();
int len = data_str.length() / 2;
int i;
for (i = 0; i < len; i++) {
data[data_len] = Byte.parseByte(
data_str.substring(i*2, i*2 + 2),
16);
data_len++;
}
}
}
}
This format is obviously deficient. For example, the setup packet for control
transfers is not delivered. This will change in the future.
Examples:
An input control transfer to get a port status:
d74ff9a0 2640288196 S Ci:001:00 -115 4 <
d74ff9a0 2640288202 C Ci:001:00 0 4 = 01010100
An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper
to a storage device at address 5:
dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000
dd65f0e8 4128379808 C Bo:005:02 0 31 >
* Raw binary format and API
TBD

481
Documentation/usb/w9968cf.txt Normal file
View file

@ -0,0 +1,481 @@
W996[87]CF JPEG USB Dual Mode Camera Chip
Driver for Linux 2.6 (basic version)
=========================================
- Documentation -
Index
=====
1. Copyright
2. Disclaimer
3. License
4. Overview
5. Supported devices
6. Module dependencies
7. Module loading
8. Module paramaters
9. Contact information
10. Credits
1. Copyright
============
Copyright (C) 2002-2004 by Luca Risolia <[email protected]>
2. Disclaimer
=============
Winbond is a trademark of Winbond Electronics Corporation.
This software is not sponsored or developed by Winbond.
3. License
==========
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
4. Overview
===========
This driver supports the video streaming capabilities of the devices mounting
Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
based cameras should be supported as well.
The driver is divided into two modules: the basic one, "w9968cf", is needed for
the supported devices to work; the second one, "w9968cf-vpp", is an optional
module, which provides some useful video post-processing functions like video
decoding, up-scaling and colour conversions. Once the driver is installed,
every time an application tries to open a recognized device, "w9968cf" checks
the presence of the "w9968cf-vpp" module and loads it automatically by default.
Please keep in mind that official kernels do not include the second module for
performance purposes. However it is always recommended to download and install
the latest and complete release of the driver, replacing the existing one, if
present: it will be still even possible not to load the "w9968cf-vpp" module at
all, if you ever want to. Another important missing feature of the version in
the official Linux 2.4 kernels is the writeable /proc filesystem interface.
The latest and full-featured version of the W996[87]CF driver can be found at:
http://www.linux-projects.org. Please refer to the documentation included in
that package, if you are going to use it.
Up to 32 cameras can be handled at the same time. They can be connected and
disconnected from the host many times without turning off the computer, if
your system supports the hotplug facility.
To change the default settings for each camera, many parameters can be passed
through command line when the module is loaded into memory.
The driver relies on the Video4Linux, USB and I2C core modules. It has been
designed to run properly on SMP systems as well. An additional module,
"ovcamchip", is mandatory; it provides support for some OmniVision image
sensors connected to the W996[87]CF chips; if found in the system, the module
will be automatically loaded by default (provided that the kernel has been
compiled with the automatic module loading option).
5. Supported devices
====================
At the moment, known W996[87]CF and OV681 based devices are:
- Aroma Digi Pen VGA Dual Mode ADG-5000 (unknown image sensor)
- AVerMedia AVerTV USB (SAA7111A, Philips FI1216Mk2 tuner, PT2313L audio chip)
- Creative Labs Video Blaster WebCam Go (OmniVision OV7610 sensor)
- Creative Labs Video Blaster WebCam Go Plus (OmniVision OV7620 sensor)
- Lebon LDC-035A (unknown image sensor)
- Ezonics EZ-802 EZMega Cam (OmniVision OV8610C sensor)
- OmniVision OV8610-EDE (OmniVision OV8610 sensor)
- OPCOM Digi Pen VGA Dual Mode Pen Camera (unknown image sensor)
- Pretec Digi Pen-II (OmniVision OV7620 sensor)
- Pretec DigiPen-480 (OmniVision OV8610 sensor)
If you know any other W996[87]CF or OV681 based cameras, please contact me.
The list above does not imply that all those devices work with this driver: up
until now only webcams that have an image sensor supported by the "ovcamchip"
module work. Kernel messages will always tell you whether this is case.
Possible external microcontrollers of those webcams are not supported: this
means that still images cannot be downloaded from the device memory.
Furthermore, it's worth to note that I was only able to run tests on my
"Creative Labs Video Blaster WebCam Go". Donations of other models, for
additional testing and full support, would be much appreciated.
6. Module dependencies
======================
For it to work properly, the driver needs kernel support for Video4Linux, USB
and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
actually using any external "ovcamchip" module, given that the W996[87]CF
driver depends on the version of the module present in the official kernels.
The following options of the kernel configuration file must be enabled and
corresponding modules must be compiled:
# Multimedia devices
#
CONFIG_VIDEO_DEV=m
# I2C support
#
CONFIG_I2C=m
The I2C core module can be compiled statically in the kernel as well.
# OmniVision Camera Chip support
#
CONFIG_VIDEO_OVCAMCHIP=m
# USB support
#
CONFIG_USB=m
In addition, depending on the hardware being used, only one of the modules
below is necessary:
# USB Host Controller Drivers
#
CONFIG_USB_EHCI_HCD=m
CONFIG_USB_UHCI_HCD=m
CONFIG_USB_OHCI_HCD=m
And finally:
# USB Multimedia devices
#
CONFIG_USB_W9968CF=m
7. Module loading
=================
To use the driver, it is necessary to load the "w9968cf" module into memory
after every other module required.
Loading can be done this way, from root:
[root@localhost home]# modprobe usbcore
[root@localhost home]# modprobe i2c-core
[root@localhost home]# modprobe videodev
[root@localhost home]# modprobe w9968cf
At this point the pertinent devices should be recognized: "dmesg" can be used
to analyze kernel messages:
[user@localhost home]$ dmesg
There are a lot of parameters the module can use to change the default
settings for each device. To list every possible parameter with a brief
explanation about them and which syntax to use, it is recommended to run the
"modinfo" command:
[root@locahost home]# modinfo w9968cf
8. Module parameters
====================
Module parameters are listed below:
-------------------------------------------------------------------------------
Name: ovmod_load
Type: bool
Syntax: <0|1>
Description: Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
If enabled, 'insmod' searches for the required 'ovcamchip'
module in the system, according to its configuration, and
loads that module automatically. This action is performed as
once soon as the 'w9968cf' module is loaded into memory.
Default: 1
Note: The kernel must be compiled with the CONFIG_KMOD option
enabled for the 'ovcamchip' module to be loaded and for
this parameter to be present.
-------------------------------------------------------------------------------
Name: vppmod_load
Type: bool
Syntax: <0|1>
Description: Automatic 'w9968cf-vpp' module loading: 0 disabled, 1 enabled.
If enabled, every time an application attempts to open a
camera, 'insmod' searches for the video post-processing module
in the system and loads it automatically (if present).
The optional 'w9968cf-vpp' module adds extra image manipulation
capabilities to the 'w9968cf' module,like software up-scaling,
colour conversions and video decompression for very high frame
rates.
Default: 1
Note: The kernel must be compiled with the CONFIG_KMOD option
enabled for the 'w9968cf-vpp' module to be loaded and for
this parameter to be present.
-------------------------------------------------------------------------------
Name: simcams
Type: int
Syntax: <n>
Description: Number of cameras allowed to stream simultaneously.
n may vary from 0 to 32.
Default: 32
-------------------------------------------------------------------------------
Name: video_nr
Type: int array (min = 0, max = 32)
Syntax: <-1|n[,...]>
Description: Specify V4L minor mode number.
-1 = use next available
n = use minor number n
You can specify up to 32 cameras this way.
For example:
video_nr=-1,2,-1 would assign minor number 2 to the second
recognized camera and use auto for the first one and for every
other camera.
Default: -1
-------------------------------------------------------------------------------
Name: packet_size
Type: int array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Specify the maximum data payload size in bytes for alternate
settings, for each device. n is scaled between 63 and 1023.
Default: 1023
-------------------------------------------------------------------------------
Name: max_buffers
Type: int array (min = 0, max = 32)
Syntax: <n[,...]>
Description: For advanced users.
Specify the maximum number of video frame buffers to allocate
for each device, from 2 to 32.
Default: 2
-------------------------------------------------------------------------------
Name: double_buffer
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Hardware double buffering: 0 disabled, 1 enabled.
It should be enabled if you want smooth video output: if you
obtain out of sync. video, disable it, or try to
decrease the 'clockdiv' module parameter value.
Default: 1 for every device.
-------------------------------------------------------------------------------
Name: clamping
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Video data clamping: 0 disabled, 1 enabled.
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: filter_type
Type: int array (min = 0, max = 32)
Syntax: <0|1|2[,...]>
Description: Video filter type.
0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter.
The filter is used to reduce noise and aliasing artifacts
produced by the CCD or CMOS image sensor.
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: largeview
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Large view: 0 disabled, 1 enabled.
Default: 1 for every device.
-------------------------------------------------------------------------------
Name: upscaling
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Software scaling (for non-compressed video only):
0 disabled, 1 enabled.
Disable it if you have a slow CPU or you don't have enough
memory.
Default: 0 for every device.
Note: If 'w9968cf-vpp' is not present, this parameter is set to 0.
-------------------------------------------------------------------------------
Name: decompression
Type: int array (min = 0, max = 32)
Syntax: <0|1|2[,...]>
Description: Software video decompression:
0 = disables decompression
(doesn't allow formats needing decompression).
1 = forces decompression
(allows formats needing decompression only).
2 = allows any permitted formats.
Formats supporting (de)compressed video are YUV422P and
YUV420P/YUV420 in any resolutions where width and height are
multiples of 16.
Default: 2 for every device.
Note: If 'w9968cf-vpp' is not present, forcing decompression is not
allowed; in this case this parameter is set to 2.
-------------------------------------------------------------------------------
Name: force_palette
Type: int array (min = 0, max = 32)
Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
Description: Force picture palette.
In order:
0 = Off - allows any of the following formats:
9 = UYVY 16 bpp - Original video, compression disabled
10 = YUV420 12 bpp - Original video, compression enabled
13 = YUV422P 16 bpp - Original video, compression enabled
15 = YUV420P 12 bpp - Original video, compression enabled
8 = YUVY 16 bpp - Software conversion from UYVY
7 = YUV422 16 bpp - Software conversion from UYVY
1 = GREY 8 bpp - Software conversion from UYVY
6 = RGB555 16 bpp - Software conversion from UYVY
3 = RGB565 16 bpp - Software conversion from UYVY
4 = RGB24 24 bpp - Software conversion from UYVY
5 = RGB32 32 bpp - Software conversion from UYVY
When not 0, this parameter will override 'decompression'.
Default: 0 for every device. Initial palette is 9 (UYVY).
Note: If 'w9968cf-vpp' is not present, this parameter is set to 9.
-------------------------------------------------------------------------------
Name: force_rgb
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Read RGB video data instead of BGR:
1 = use RGB component ordering.
0 = use BGR component ordering.
This parameter has effect when using RGBX palettes only.
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: autobright
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Image sensor automatically changes brightness:
0 = no, 1 = yes
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: autoexp
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Image sensor automatically changes exposure:
0 = no, 1 = yes
Default: 1 for every device.
-------------------------------------------------------------------------------
Name: lightfreq
Type: int array (min = 0, max = 32)
Syntax: <50|60[,...]>
Description: Light frequency in Hz:
50 for European and Asian lighting, 60 for American lighting.
Default: 50 for every device.
-------------------------------------------------------------------------------
Name: bandingfilter
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Banding filter to reduce effects of fluorescent
lighting:
0 disabled, 1 enabled.
This filter tries to reduce the pattern of horizontal
light/dark bands caused by some (usually fluorescent) lighting.
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: clockdiv
Type: int array (min = 0, max = 32)
Syntax: <-1|n[,...]>
Description: Force pixel clock divisor to a specific value (for experts):
n may vary from 0 to 127.
-1 for automatic value.
See also the 'double_buffer' module parameter.
Default: -1 for every device.
-------------------------------------------------------------------------------
Name: backlight
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Objects are lit from behind:
0 = no, 1 = yes
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: mirror
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: Reverse image horizontally:
0 = no, 1 = yes
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: monochrome
Type: bool array (min = 0, max = 32)
Syntax: <0|1[,...]>
Description: The image sensor is monochrome:
0 = no, 1 = yes
Default: 0 for every device.
-------------------------------------------------------------------------------
Name: brightness
Type: long array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Set picture brightness (0-65535).
This parameter has no effect if 'autobright' is enabled.
Default: 31000 for every device.
-------------------------------------------------------------------------------
Name: hue
Type: long array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Set picture hue (0-65535).
Default: 32768 for every device.
-------------------------------------------------------------------------------
Name: colour
Type: long array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Set picture saturation (0-65535).
Default: 32768 for every device.
-------------------------------------------------------------------------------
Name: contrast
Type: long array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Set picture contrast (0-65535).
Default: 50000 for every device.
-------------------------------------------------------------------------------
Name: whiteness
Type: long array (min = 0, max = 32)
Syntax: <n[,...]>
Description: Set picture whiteness (0-65535).
Default: 32768 for every device.
-------------------------------------------------------------------------------
Name: debug
Type: int
Syntax: <n>
Description: Debugging information level, from 0 to 6:
0 = none (use carefully)
1 = critical errors
2 = significant informations
3 = configuration or general messages
4 = warnings
5 = called functions
6 = function internals
Level 5 and 6 are useful for testing only, when only one
device is used.
Default: 2
-------------------------------------------------------------------------------
Name: specific_debug
Type: bool
Syntax: <0|1>
Description: Enable or disable specific debugging messages:
0 = print messages concerning every level <= 'debug' level.
1 = print messages concerning the level indicated by 'debug'.
Default: 0
-------------------------------------------------------------------------------
9. Contact information
======================
I may be contacted by e-mail at <[email protected]>.
I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
My public 1024-bit key should be available at your keyserver; the fingerprint
is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
10. Credits
==========
The development would not have proceed much further without having looked at
the source code of other drivers and without the help of several persons; in
particular:
- the I2C interface to kernel and high-level image sensor control routines have
been taken from the OV511 driver by Mark McClelland;
- memory management code has been copied from the bttv driver by Ralph Metzler,
Marcus Metzler and Gerd Knorr;
- the low-level I2C read function has been written by Frederic Jouault;
- the low-level I2C fast write function has been written by Piotr Czerczak.