diff options
| author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 15:20:36 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 15:20:36 -0700 |
| commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
| tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/usb | |
Linux-2.6.12-rc2v2.6.12-rc2
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!
Diffstat (limited to 'Documentation/usb')
26 files changed, 5129 insertions, 0 deletions
diff --git a/Documentation/usb/CREDITS b/Documentation/usb/CREDITS new file mode 100644 index 000000000000..01e7f857ef35 --- /dev/null +++ b/Documentation/usb/CREDITS @@ -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 <acher@informatik.tu-muenchen.de> + David Brownell <dbrownell@users.sourceforge.net> + Alan Cox <alan@lxorguk.ukuu.org.uk> + Randy Dunlap <randy.dunlap@intel.com> + Johannes Erdfelt <johannes@erdfelt.com> + Deti Fliegl <deti@fliegl.de> + ham <ham@unsuave.com> + Bradley M Keryan <keryan@andrew.cmu.edu> + Greg Kroah-Hartman <greg@kroah.com> + Pavel Machek <pavel@suse.cz> + Paul Mackerras <paulus@cs.anu.edu.au> + Petko Manlolov <petkan@dce.bg> + David E. Nelson <dnelson@jump.net> + Vojtech Pavlik <vojtech@suse.cz> + Bill Ryder <bryder@sgi.com> + Thomas Sailer <sailer@ife.ee.ethz.ch> + Gregory P. Smith <greg@electricrain.com> + Linus Torvalds <torvalds@osdl.org> + Roman Weissgaerber <weissg@vienna.at> + <Kazuki.Yasumatsu@fujixerox.co.jp> + +Special thanks to: + + Inaky Perez Gonzalez <inaky@peloncho.fis.ucm.es> 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 <orenti@hishome.net>, for standing so patiently + all my doubts'bout USB and giving lots of cool ideas. + + - Jochen Karrer <karrer@wpfd25.physik.uni-wuerzburg.de>, for + pointing out mortal bugs and giving advice. + + - Edmund Humemberger <ed@atnet.at>, for it's great work on + public relationships and general management stuff for the + Linux-USB effort. + + - Alberto Menegazzi <flash@flash.iol.it> is starting the + documentation for the UUSBD. Go for it! + + - Ric Klaren <ia_ric@cs.utwente.nl> for doing nice + introductory documents (competing with Alberto's :). + + - Christian Groessler <cpg@aladdin.de>, 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 <fherrera@eurielec.etsit.upm.es> has taken + charge of composing, maintaining and feeding the + long-awaited, unique and marvelous UUSBD FAQ! Tadaaaa!!! + + - Rasca Gmelch <thron@gmx.de> has revived the raw driver and + pointed bugs, as well as started the uusbd-utils package. + + - Peter Dettori <dettori@ozy.dec.com> 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 <ncm@cantrip.org>, 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. diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt new file mode 100644 index 000000000000..d59b95cc6f1b --- /dev/null +++ b/Documentation/usb/URB.txt @@ -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. diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt new file mode 100644 index 000000000000..8ef45ea8f691 --- /dev/null +++ b/Documentation/usb/acm.txt @@ -0,0 +1,138 @@ + Linux ACM driver v0.16 + (c) 1999 Vojtech Pavlik <vojtech@suse.cz> + 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 <vojtech@suse.cz>, 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. diff --git a/Documentation/usb/auerswald.txt b/Documentation/usb/auerswald.txt new file mode 100644 index 000000000000..7ee4d8f69116 --- /dev/null +++ b/Documentation/usb/auerswald.txt @@ -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 wolfgang@iksw-muees.de diff --git a/Documentation/usb/bluetooth.txt b/Documentation/usb/bluetooth.txt new file mode 100644 index 000000000000..774f5d3835cc --- /dev/null +++ b/Documentation/usb/bluetooth.txt @@ -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 +greg@kroah.com diff --git a/Documentation/usb/dma.txt b/Documentation/usb/dma.txt new file mode 100644 index 000000000000..62844aeba69c --- /dev/null +++ b/Documentation/usb/dma.txt @@ -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. diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt new file mode 100644 index 000000000000..1536b7e75134 --- /dev/null +++ b/Documentation/usb/ehci.txt @@ -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 + <dbrownell@users.sourceforge.net> + + +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. + diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt new file mode 100644 index 000000000000..1e36f1661cd0 --- /dev/null +++ b/Documentation/usb/error-codes.txt @@ -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. diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt new file mode 100644 index 000000000000..a938c3dd13d6 --- /dev/null +++ b/Documentation/usb/gadget_serial.txt @@ -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 (alborchers@steinerpoint.com). + +If you have questions, problems, or suggestions for this driver +please contact Al Borchers at alborchers@steinerpoint.com. + + +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 (alborchers@steinerpoint.com) + +[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. + + diff --git a/Documentation/usb/hiddev.txt b/Documentation/usb/hiddev.txt new file mode 100644 index 000000000000..cd6fb4b58e1f --- /dev/null +++ b/Documentation/usb/hiddev.txt @@ -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. diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt new file mode 100644 index 000000000000..f53170665f37 --- /dev/null +++ b/Documentation/usb/hotplug.txt @@ -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. + + diff --git a/Documentation/usb/ibmcam.txt b/Documentation/usb/ibmcam.txt new file mode 100644 index 000000000000..ce2f21a3eac4 --- /dev/null +++ b/Documentation/usb/ibmcam.txt @@ -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. diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf new file mode 100644 index 000000000000..2f7217d124ff --- /dev/null +++ b/Documentation/usb/linux.inf @@ -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" + diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt new file mode 100644 index 000000000000..cd806bfc8b81 --- /dev/null +++ b/Documentation/usb/mtouchusb.txt @@ -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! diff --git a/Documentation/usb/ohci.txt b/Documentation/usb/ohci.txt new file mode 100644 index 000000000000..99320d9fa523 --- /dev/null +++ b/Documentation/usb/ohci.txt @@ -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 <weissg@vienna.at> 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 + <dbrownell@users.sourceforge.net> + diff --git a/Documentation/usb/ov511.txt b/Documentation/usb/ov511.txt new file mode 100644 index 000000000000..e1974ec8217e --- /dev/null +++ b/Documentation/usb/ov511.txt @@ -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 mark@alpha.dyndns.org . 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. + diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt new file mode 100644 index 000000000000..729c72d34c89 --- /dev/null +++ b/Documentation/usb/proc_usb_info.txt @@ -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 ### diff --git a/Documentation/usb/rio.txt b/Documentation/usb/rio.txt new file mode 100644 index 000000000000..0aa79ab0088c --- /dev/null +++ b/Documentation/usb/rio.txt @@ -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: rio500-users@lists.sourceforge.net + +Authors: +------- + +Most of the code was written by Cesar Miquel <miquel@df.uba.ar>. Keith +Clayton <kclayton@jps.net> is incharge of the PPC port and making sure +things work there. Bruce Tenison <btenison@dibbs.net> 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 <tmn_3022000@hotmail.com> 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 +btenison@dibbs.net + diff --git a/Documentation/usb/se401.txt b/Documentation/usb/se401.txt new file mode 100644 index 000000000000..7b9d1c960a10 --- /dev/null +++ b/Documentation/usb/se401.txt @@ -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: +pe1rxq@amsat.org diff --git a/Documentation/usb/sn9c102.txt b/Documentation/usb/sn9c102.txt new file mode 100644 index 000000000000..cf9a1187edce --- /dev/null +++ b/Documentation/usb/sn9c102.txt @@ -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 <luca.risolia@studio.unibo.it> + + +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 <luca.risolia@studio.unibo.it>. + +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. diff --git a/Documentation/usb/stv680.txt b/Documentation/usb/stv680.txt new file mode 100644 index 000000000000..6448041e7a37 --- /dev/null +++ b/Documentation/usb/stv680.txt @@ -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: kjsisson@bellsouth.net + + diff --git a/Documentation/usb/uhci.txt b/Documentation/usb/uhci.txt new file mode 100644 index 000000000000..2f25952c86c6 --- /dev/null +++ b/Documentation/usb/uhci.txt @@ -0,0 +1,165 @@ +Specification and Internals for the New UHCI Driver (Whitepaper...) + + brought to you by + + Georg Acher, acher@in.tum.de (executive slave) (base guitar) + Deti Fliegl, deti@fliegl.de (executive slave) (lead voice) + Thomas Sailer, sailer@ife.ee.ethz.ch (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. diff --git a/Documentation/usb/usb-help.txt b/Documentation/usb/usb-help.txt new file mode 100644 index 000000000000..b7c324973695 --- /dev/null +++ b/Documentation/usb/usb-help.txt @@ -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: + linux-usb-users@lists.sourceforge.net for general user help + linux-usb-devel@lists.sourceforge.net for developer discussions + +### diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt new file mode 100644 index 000000000000..f001cd93b79b --- /dev/null +++ b/Documentation/usb/usb-serial.txt @@ -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 stuartm@connecttech.com + + +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 greg@kroah.com + + +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 <billybobjoehenrybob@hotmail.com>, 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 <ganesh@veritas.com> + + +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 warner@lothar.com + + +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 hugh@misc.nu + + +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 bryder@sgi.com + + +ZyXEL omni.net lcd plus ISDN TA + + This is an ISDN TA. Please report both successes and troubles to + azummo@towertech.it + + +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: + dignome@gmail.com + (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 (pberger@brimson.com) or Al Borchers + (alborchers@steinerpoint.com) 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 wgreathouse@smva.com + + +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 xavyer@ix.netcom.com + + +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 wolfgang@ces.ch + + +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 greg@kroah.com + + +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 (linux-usb@sii.li). + + For any questions or problems with this driver, please contact + linux-usb@sii.li + + +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 greg@kroah.com + + +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 greg@kroah.com + + +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 +greg@kroah.com diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt new file mode 100644 index 000000000000..2f8431f92b77 --- /dev/null +++ b/Documentation/usb/usbmon.txt @@ -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 diff --git a/Documentation/usb/w9968cf.txt b/Documentation/usb/w9968cf.txt new file mode 100644 index 000000000000..18a47738d56c --- /dev/null +++ b/Documentation/usb/w9968cf.txt @@ -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 <luca.risolia@studio.unibo.it> + + +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 <luca.risolia@studio.unibo.it>. + +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. |