diff options
Diffstat (limited to 'Documentation/usb')
| -rw-r--r-- | Documentation/usb/URB.txt | 74 | ||||
| -rw-r--r-- | Documentation/usb/bluetooth.txt | 44 | ||||
| -rw-r--r-- | Documentation/usb/error-codes.txt | 5 | ||||
| -rw-r--r-- | Documentation/usb/ibmcam.txt | 4 | ||||
| -rw-r--r-- | Documentation/usb/ov511.txt | 4 | ||||
| -rw-r--r-- | Documentation/usb/rio.txt | 6 |
6 files changed, 41 insertions, 96 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index d59b95cc6f1b..a49e5f2c2b46 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt @@ -1,5 +1,6 @@ Revised: 2000-Dec-05. Again: 2002-Jul-06 +Again: 2005-Sep-19 NOTE: @@ -18,8 +19,8 @@ called USB Request Block, or URB for short. 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. + 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. @@ -94,8 +95,9 @@ 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. +You may free an urb that you've submitted, but which hasn't yet been +returned to you in a completion callback. It will automatically be +deallocated when it is no longer in use. 1.4. What has to be filled in? @@ -145,30 +147,36 @@ 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 +There are two ways to cancel an URB you've submitted but which hasn't +been returned to your driver yet. For an asynchronous cancel, 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(). +HW descriptors. The status is changed to reflect unlinking. Note +that the URB will not normally have finished when usb_unlink_urb() +returns; you must still wait for the completion handler to be called. -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. +To cancel an URB synchronously, call + + void usb_kill_urb(struct urb *urb) + +It does everything usb_unlink_urb does, and in addition it waits +until after the URB has been returned and the completion handler +has finished. It also marks the URB as temporarily unusable, so +that if the completion handler or anyone else tries to resubmit it +they will get a -EPERM error. Thus you can be sure that when +usb_kill_urb() returns, the URB is totally idle. 1.7. What about the completion handler? The handler is of the following type: - typedef void (*usb_complete_t)(struct urb *); + typedef void (*usb_complete_t)(struct urb *, struct pt_regs *) -i.e. it gets just the URB that caused the completion call. +I.e., it gets the URB that caused the completion call, plus the +register values at the time of the corresponding interrupt (if any). 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. @@ -176,17 +184,11 @@ 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. +have transferred succesfully before the completion was 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 +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 @@ -229,24 +231,10 @@ ISO data with some other event stream. 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. + +In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically +restarted when they complete. They end when the completion handler is +called, just like other URBs. If you want an interrupt URB to be restarted, +your completion handler must resubmit it. diff --git a/Documentation/usb/bluetooth.txt b/Documentation/usb/bluetooth.txt deleted file mode 100644 index 774f5d3835cc..000000000000 --- a/Documentation/usb/bluetooth.txt +++ /dev/null @@ -1,44 +0,0 @@ -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/error-codes.txt b/Documentation/usb/error-codes.txt index 1e36f1661cd0..867f4c38f356 100644 --- a/Documentation/usb/error-codes.txt +++ b/Documentation/usb/error-codes.txt @@ -46,8 +46,9 @@ USB-specific: -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) + (b) ISO packet is larger than the endpoint maxpacket. + (c) requested data transfer length is invalid: negative + or too large for the host controller. -ENOSPC This request would overcommit the usb bandwidth reserved for periodic transfers (interrupt, isochronous). diff --git a/Documentation/usb/ibmcam.txt b/Documentation/usb/ibmcam.txt index ce2f21a3eac4..c25003644131 100644 --- a/Documentation/usb/ibmcam.txt +++ b/Documentation/usb/ibmcam.txt @@ -28,8 +28,8 @@ 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. +(renamed to http://www.veo.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 diff --git a/Documentation/usb/ov511.txt b/Documentation/usb/ov511.txt index e1974ec8217e..a7fc0432bff1 100644 --- a/Documentation/usb/ov511.txt +++ b/Documentation/usb/ov511.txt @@ -22,8 +22,8 @@ WHAT YOU NEED: 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 + vidcat is part of the w3cam package: http://mpx.freeshell.net/ + xawtv is available at: http://linux.bytesex.org/xawtv/ HOW TO USE IT: diff --git a/Documentation/usb/rio.txt b/Documentation/usb/rio.txt index 0aa79ab0088c..ab21db454694 100644 --- a/Documentation/usb/rio.txt +++ b/Documentation/usb/rio.txt @@ -46,9 +46,9 @@ 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 + URL: <http://rio500.sourceforge.net>. You can also go to the project's + sourceforge home page at: <http://sourceforge.net/projects/rio500/>. + There is also a mailing list: rio500-users@lists.sourceforge.net Authors: ------- |