On Thu, 20 Oct 2016, Oliver Neukum <oneukum@xxxxxxxx> wrote: > This just is the result of the conversion script and its addition > to the index. Just the plain automatic conversion. How does this relate to [1]? Why does this not remove the .tmpl file? BR, Jani. [1] http://lkml.kernel.org/r/1476969300-9603-1-git-send-email-oneukum@xxxxxxxx > > Signed-off-by: Oliver Neukum <oneukum@xxxxxxxx> > --- > Documentation/index.rst | 1 + > Documentation/usb/conf.py | 5 + > Documentation/usb/usb.rst | 750 ++++++++++++++++++++++++++++++++++++++++++++++ > 3 files changed, 756 insertions(+) > create mode 100644 Documentation/usb/conf.py > create mode 100644 Documentation/usb/usb.rst > > diff --git a/Documentation/index.rst b/Documentation/index.rst > index c53d089..a5bbd22 100644 > --- a/Documentation/index.rst > +++ b/Documentation/index.rst > @@ -18,6 +18,7 @@ Contents: > media/index > gpu/index > 80211/index > + usb/usb > > Indices and tables > ================== > diff --git a/Documentation/usb/conf.py b/Documentation/usb/conf.py > new file mode 100644 > index 0000000..308f907 > --- /dev/null > +++ b/Documentation/usb/conf.py > @@ -0,0 +1,5 @@ > +# -*- coding: utf-8; mode: python -*- > + > +project = "Linux USB project documentation and manual" > + > +tags.add("subproject") > diff --git a/Documentation/usb/usb.rst b/Documentation/usb/usb.rst > new file mode 100644 > index 0000000..dbbd14d > --- /dev/null > +++ b/Documentation/usb/usb.rst > @@ -0,0 +1,750 @@ > +=========================== > +The Linux-USB Host Side API > +=========================== > + > +Introduction to USB on Linux > +============================ > + > +A Universal Serial Bus (USB) is used to connect a host, such as a PC or > +workstation, to a number of peripheral devices. USB uses a tree > +structure, with the host as the root (the system's master), hubs as > +interior nodes, and peripherals as leaves (and slaves). Modern PCs > +support several such trees of USB devices, usually a few USB 3.0 (5 > +GBit/s) or USB 3.1 (10 GBit/s) and some legacy USB 2.0 (480 MBit/s) > +busses just in case. > + > +That master/slave asymmetry was designed-in for a number of reasons, one > +being ease of use. It is not physically possible to mistake upstream and > +downstream or it does not matter with a type C plug (or they are built > +into the peripheral). Also, the host software doesn't need to deal with > +distributed auto-configuration since the pre-designated master node > +manages all that. > + > +Kernel developers added USB support to Linux early in the 2.2 kernel > +series and have been developing it further since then. Besides support > +for each new generation of USB, various host controllers gained support, > +new drivers for peripherals have been added and advanced features for > +latency measurement and improved power management introduced. > + > +Linux can run inside USB devices as well as on the hosts that control > +the devices. But USB device drivers running inside those peripherals > +don't do the same things as the ones running inside hosts, so they've > +been given a different name: *gadget drivers*. This document does not > +cover gadget drivers. > + > +USB Host-Side API Model > +======================= > + > +Host-side drivers for USB devices talk to the "usbcore" APIs. There are > +two. One is intended for *general-purpose* drivers (exposed through > +driver frameworks), and the other is for drivers that are *part of the > +core*. Such core drivers include the *hub* driver (which manages trees > +of USB devices) and several different kinds of *host controller > +drivers*, which control individual busses. > + > +The device model seen by USB drivers is relatively complex. > + > +- USB supports four kinds of data transfers (control, bulk, interrupt, > + and isochronous). Two of them (control and bulk) use bandwidth as > + it's available, while the other two (interrupt and isochronous) are > + scheduled to provide guaranteed bandwidth. > + > +- The device description model includes one or more "configurations" > + per device, only one of which is active at a time. Devices are > + supposed to be capable of operating at lower than their top speeds > + and may provide a BOS descriptor showing the lowest speed they remain > + fully operational at. > + > +- From USB 3.0 on configurations have one or more "functions", which > + provide a common functionality and are grouped together for purposes > + of power management. > + > +- Configurations or functions have one or more "interfaces", each of > + which may have "alternate settings". Interfaces may be standardized > + by USB "Class" specifications, or may be specific to a vendor or > + device. > + > + USB device drivers actually bind to interfaces, not devices. Think of > + them as "interface drivers", though you may not see many devices > + where the distinction is important. *Most USB devices are simple, > + with only one configuration, one function, one interface, and one > + alternate setting.* > + > +- Interfaces have one or more "endpoints", each of which supports one > + type and direction of data transfer such as "bulk out" or "interrupt > + in". The entire configuration may have up to sixteen endpoints in > + each direction, allocated as needed among all the interfaces. > + > +- Data transfer on USB is packetized; each endpoint has a maximum > + packet size. Drivers must often be aware of conventions such as > + flagging the end of bulk transfers using "short" (including zero > + length) packets. > + > +- The Linux USB API supports synchronous calls for control and bulk > + messages. It also supports asynchronous calls for all kinds of data > + transfer, using request structures called "URBs" (USB Request > + Blocks). > + > +Accordingly, the USB Core API exposed to device drivers covers quite a > +lot of territory. You'll probably need to consult the USB 3.0 > +specification, available online from www.usb.org at no cost, as well as > +class or device specifications. > + > +The only host-side drivers that actually touch hardware (reading/writing > +registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs > +provide the same functionality through the same API. In practice, that's > +becoming mostly true, but there are still differences that crop up > +especially with fault handling on the less common controllers. Different > +controllers don't necessarily report the same aspects of failures, and > +recovery from faults (including software-induced ones like unlinking an > +URB) isn't yet fully consistent. Device driver authors should make a > +point of doing disconnect testing (while the device is active) with each > +different host controller driver, to make sure drivers don't have bugs > +of thei1r own as well as to make sure they aren't relying on some > +HCD-specific behavior. > + > +USB-Standard Types > +================== > + > +In ``<linux/usb/ch9.h>`` you will find the USB data types defined in > +chapter 9 of the USB specification. These data types are used throughout > +USB, and in APIs including this host side API, gadget APIs, and usbfs. > + > +.. kernel-doc:: include/linux/usb/ch9.h > + :internal: > + > +Host-Side Data Types and Macros > +=============================== > + > +The host side API exposes several layers to drivers, some of which are > +more necessary than others. These support lifecycle models for host side > +drivers and devices, and support passing buffers through usbcore to some > +HCD that performs the I/O for the device driver. > + > +.. kernel-doc:: include/linux/usb.h > + :internal: > + > +USB Core APIs > +============= > + > +There are two basic I/O models in the USB API. The most elemental one is > +asynchronous: drivers submit requests in the form of an URB, and the > +URB's completion callback handles the next step. All USB transfer types > +support that model, although there are special cases for control URBs > +(which always have setup and status stages, but may not have a data > +stage) and isochronous URBs (which allow large packets and include > +per-packet fault reports). Built on top of that is synchronous API > +support, where a driver calls a routine that allocates one or more URBs, > +submits them, and waits until they complete. There are synchronous > +wrappers for single-buffer control and bulk transfers (which are awkward > +to use in some driver disconnect scenarios), and for scatterlist based > +streaming i/o (bulk or interrupt). > + > +USB drivers need to provide buffers that can be used for DMA, although > +they don't necessarily need to provide the DMA mapping themselves. There > +are APIs to use used when allocating DMA buffers, which can prevent use > +of bounce buffers on some systems. In some cases, drivers may be able to > +rely on 64bit DMA to eliminate another kind of bounce buffer. > + > +.. kernel-doc:: drivers/usb/core/urb.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/message.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/file.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/driver.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/usb.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/hub.c > + :export: > + > +Host Controller APIs > +==================== > + > +These APIs are only for use by host controller drivers, most of which > +implement standard register interfaces such as XHCI, EHCI, OHCI, or > +UHCI. UHCI was one of the first interfaces, designed by Intel and also > +used by VIA; it doesn't do much in hardware. OHCI was designed later, to > +have the hardware do more work (bigger transfers, tracking protocol > +state, and so on). EHCI was designed with USB 2.0; its design has > +features that resemble OHCI (hardware does much more work) as well as > +UHCI (some parts of ISO support, TD list processing). XHCI was designed > +with USB 3.0. It continues to shift support for functionality into > +hardware. > + > +There are host controllers other than the "big three", although most PCI > +based controllers (and a few non-PCI based ones) use one of those > +interfaces. Not all host controllers use DMA; some use PIO, and there is > +also a simulator and a virtual host controller to pipe USB over the > +network. > + > +The same basic APIs are available to drivers for all those controllers. > +For historical reasons they are in two layers: :c:type:`struct > +usb_bus <usb_bus>` is a rather thin layer that became available > +in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>` > +is a more featureful layer that lets HCDs share common code, to shrink > +driver size and significantly reduce hcd-specific behaviors. > + > +.. kernel-doc:: drivers/usb/core/hcd.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/hcd-pci.c > + :export: > + > +.. kernel-doc:: drivers/usb/core/buffer.c > + :internal: > + > +The USB Filesystem (usbfs) > +========================== > + > +This chapter presents the Linux *usbfs*. You may prefer to avoid writing > +new kernel code for your USB driver; that's the problem that usbfs set > +out to solve. User mode device drivers are usually packaged as > +applications or libraries, and may use usbfs through some programming > +library that wraps it. Such libraries include > +`libusb <http://libusb.sourceforge.net>`__ for C/C++, and > +`jUSB <http://jUSB.sourceforge.net>`__ for Java. > + > + **Note** > + > + This particular documentation is incomplete, especially with respect > + to the asynchronous mode. As of kernel 2.5.66 the code and this > + (new) documentation need to be cross-reviewed. > + > +Configure usbfs into Linux kernels by enabling the *USB filesystem* > +option (CONFIG_USB_DEVICEFS), and you get basic support for user mode > +USB device drivers. Until relatively recently it was often (confusingly) > +called *usbdevfs* although it wasn't solving what *devfs* was. Every USB > +device will appear in usbfs, regardless of whether or not it has a > +kernel driver. > + > +What files are in "usbfs"? > +-------------------------- > + > +Conventionally mounted at ``/proc/bus/usb``, usbfs features include: > + > +- ``/proc/bus/usb/devices`` ... a text file showing each of the USB > + devices on known to the kernel, and their configuration descriptors. > + You can also poll() this to learn about new devices. > + > +- ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's > + configuration descriptors, and supporting a series of ioctls for > + making device requests, including I/O to devices. (Purely for access > + by programs.) > + > +Each bus is given a number (BBB) based on when it was enumerated; within > +each bus, each device is given a similar number (DDD). Those BBB/DDD > +paths are not "stable" identifiers; expect them to change even if you > +always leave the devices plugged in to the same hub port. *Don't even > +think of saving these in application configuration files.* Stable > +identifiers are available, for user mode applications that want to use > +them. HID and networking devices expose these stable IDs, so that for > +example you can be sure that you told the right UPS to power down its > +second server. "usbfs" doesn't (yet) expose those IDs. > + > +Mounting and Access Control > +--------------------------- > + > +There are a number of mount options for usbfs, which will be of most > +interest to you if you need to override the default access control > +policy. That policy is that only root may read or write device files > +(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or > +``drivers`` files. I/O requests to the device also need the > +CAP_SYS_RAWIO capability, > + > +The significance of that is that by default, all user mode device > +drivers need super-user privileges. You can change modes or ownership in > +a driver setup when the device hotplugs, or maye just start the driver > +right then, as a privileged server (or some activity within one). That's > +the most secure approach for multi-user systems, but for single user > +systems ("trusted" by that user) it's more convenient just to grant > +everyone all access (using the *devmode=0666* option) so the driver can > +start whenever it's needed. > + > +The mount options for usbfs, usable in /etc/fstab or in command line > +invocations of *mount*, are: > + > +*busgid*\ =NNNNN > + Controls the GID used for the /proc/bus/usb/BBB directories. > + (Default: 0) > + > +*busmode*\ =MMM > + Controls the file mode used for the /proc/bus/usb/BBB directories. > + (Default: 0555) > + > +*busuid*\ =NNNNN > + Controls the UID used for the /proc/bus/usb/BBB directories. > + (Default: 0) > + > +*devgid*\ =NNNNN > + Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default: > + 0) > + > +*devmode*\ =MMM > + Controls the file mode used for the /proc/bus/usb/BBB/DDD files. > + (Default: 0644) > + > +*devuid*\ =NNNNN > + Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default: > + 0) > + > +*listgid*\ =NNNNN > + Controls the GID used for the /proc/bus/usb/devices and drivers > + files. (Default: 0) > + > +*listmode*\ =MMM > + Controls the file mode used for the /proc/bus/usb/devices and > + drivers files. (Default: 0444) > + > +*listuid*\ =NNNNN > + Controls the UID used for the /proc/bus/usb/devices and drivers > + files. (Default: 0) > + > +Note that many Linux distributions hard-wire the mount options for usbfs > +in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than > +making it easy to set this per-system policy in ``/etc/fstab``. > + > +/proc/bus/usb/devices > +--------------------- > + > +This file is handy for status viewing tools in user mode, which can scan > +the text format and ignore most of it. More detailed device status > +(including class and vendor status) is available from device-specific > +files. For information about the current format of this file, see the > +``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel > +sources. > + > +This file, in combination with the poll() system call, can also be used > +to detect when devices are added or removed: > + > +:: > + > + int fd; > + struct pollfd pfd; > + > + fd = open("/proc/bus/usb/devices", O_RDONLY); > + pfd = { fd, POLLIN, 0 }; > + for (;;) { > + /* The first time through, this call will return immediately. */ > + poll(&pfd, 1, -1); > + > + /* To see what's changed, compare the file's previous and current > + contents or scan the filesystem. (Scanning is more precise.) */ > + } > + > +Note that this behavior is intended to be used for informational and > +debug purposes. It would be more appropriate to use programs such as > +udev or HAL to initialize a device or start a user-mode helper program, > +for instance. > + > +/proc/bus/usb/BBB/DDD > +--------------------- > + > +Use these files in one of these basic ways: > + > +*They can be read,* producing first the device descriptor (18 bytes) and > +then the descriptors for the current configuration. See the USB 2.0 spec > +for details about those binary data formats. You'll need to convert most > +multibyte values from little endian format to your native host byte > +order, although a few of the fields in the device descriptor (both of > +the BCD-encoded fields, and the vendor and product IDs) will be > +byteswapped for you. Note that configuration descriptors include > +descriptors for interfaces, altsettings, endpoints, and maybe additional > +class descriptors. > + > +*Perform USB operations* using *ioctl()* requests to make endpoint I/O > +requests (synchronously or asynchronously) or manage the device. These > +requests need the CAP_SYS_RAWIO capability, as well as filesystem > +access permissions. Only one ioctl request can be made on one of these > +device files at a time. This means that if you are synchronously reading > +an endpoint from one thread, you won't be able to write to a different > +endpoint from another thread until the read completes. This works for > +*half duplex* protocols, but otherwise you'd use asynchronous i/o > +requests. > + > +Life Cycle of User Mode Drivers > +------------------------------- > + > +Such a driver first needs to find a device file for a device it knows > +how to handle. Maybe it was told about it because a ``/sbin/hotplug`` > +event handling agent chose that driver to handle the new device. Or > +maybe it's an application that scans all the /proc/bus/usb device files, > +and ignores most devices. In either case, it should :c:func:`read()` > +all the descriptors from the device file, and check them against what it > +knows how to handle. It might just reject everything except a particular > +vendor and product ID, or need a more complex policy. > + > +Never assume there will only be one such device on the system at a time! > +If your code can't handle more than one device at a time, at least > +detect when there's more than one, and have your users choose which > +device to use. > + > +Once your user mode driver knows what device to use, it interacts with > +it in either of two styles. The simple style is to make only control > +requests; some devices don't need more complex interactions than those. > +(An example might be software using vendor-specific control requests for > +some initialization or configuration tasks, with a kernel driver for the > +rest.) > + > +More likely, you need a more complex style driver: one using non-control > +endpoints, reading or writing data and claiming exclusive use of an > +interface. *Bulk* transfers are easiest to use, but only their sibling > +*interrupt* transfers work with low speed devices. Both interrupt and > +*isochronous* transfers offer service guarantees because their bandwidth > +is reserved. Such "periodic" transfers are awkward to use through usbfs, > +unless you're using the asynchronous calls. However, interrupt transfers > +can also be used in a synchronous "one shot" style. > + > +Your user-mode driver should never need to worry about cleaning up > +request state when the device is disconnected, although it should close > +its open file descriptors as soon as it starts seeing the ENODEV errors. > + > +The ioctl() Requests > +-------------------- > + > +To use these ioctls, you need to include the following headers in your > +userspace program: > + > +:: > + > + #include <linux/usb.h> > + #include <linux/usbdevice_fs.h> > + #include <asm/byteorder.h> > + > +The standard USB device model requests, from "Chapter 9" of the USB 2.0 > +specification, are automatically included from the ``<linux/usb/ch9.h>`` > +header. > + > +Unless noted otherwise, the ioctl requests described here will update > +the modification time on the usbfs file to which they are applied > +(unless they fail). A return of zero indicates success; otherwise, a > +standard USB error code is returned. (These are documented in > +``Documentation/usb/error-codes.txt`` in your kernel sources.) > + > +Each of these files multiplexes access to several I/O streams, one per > +endpoint. Each device has one control endpoint (endpoint zero) which > +supports a limited RPC style RPC access. Devices are configured by > +hub_wq (in the kernel) setting a device-wide *configuration* that > +affects things like power consumption and basic functionality. The > +endpoints are part of USB *interfaces*, which may have *altsettings* > +affecting things like which endpoints are available. Many devices only > +have a single configuration and interface, so drivers for them will > +ignore configurations and altsettings. > + > +Management/Status Requests > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +A number of usbfs requests don't deal very directly with device I/O. > +They mostly relate to device management and status. These are all > +synchronous requests. > + > +USBDEVFS_CLAIMINTERFACE > + This is used to force usbfs to claim a specific interface, which has > + not previously been claimed by usbfs or any other kernel driver. The > + ioctl parameter is an integer holding the number of the interface > + (bInterfaceNumber from descriptor). > + > + Note that if your driver doesn't claim an interface before trying to > + use one of its endpoints, and no other driver has bound to it, then > + the interface is automatically claimed by usbfs. > + > + This claim will be released by a RELEASEINTERFACE ioctl, or by > + closing the file descriptor. File modification time is not updated > + by this request. > + > +USBDEVFS_CONNECTINFO > + Says whether the device is lowspeed. The ioctl parameter points to a > + structure like this: > + > + :: > + > + struct usbdevfs_connectinfo { > + unsigned int devnum; > + unsigned char slow; > + }; > + > + File modification time is not updated by this request. > + > + *You can't tell whether a "not slow" device is connected at high > + speed (480 MBit/sec) or just full speed (12 MBit/sec).* You should > + know the devnum value already, it's the DDD value of the device file > + name. > + > +USBDEVFS_GETDRIVER > + Returns the name of the kernel driver bound to a given interface (a > + string). Parameter is a pointer to this structure, which is > + modified: > + > + :: > + > + struct usbdevfs_getdriver { > + unsigned int interface; > + char driver[USBDEVFS_MAXDRIVERNAME + 1]; > + }; > + > + File modification time is not updated by this request. > + > +USBDEVFS_IOCTL > + Passes a request from userspace through to a kernel driver that has > + an ioctl entry in the *struct usb_driver* it registered. > + > + :: > + > + struct usbdevfs_ioctl { > + int ifno; > + int ioctl_code; > + void *data; > + }; > + > + /* user mode call looks like this. > + * 'request' becomes the driver->ioctl() 'code' parameter. > + * the size of 'param' is encoded in 'request', and that data > + * is copied to or from the driver->ioctl() 'buf' parameter. > + */ > + static int > + usbdev_ioctl (int fd, int ifno, unsigned request, void *param) > + { > + struct usbdevfs_ioctl wrapper; > + > + wrapper.ifno = ifno; > + wrapper.ioctl_code = request; > + wrapper.data = param; > + > + return ioctl (fd, USBDEVFS_IOCTL, &wrapper); > + } > + > + File modification time is not updated by this request. > + > + This request lets kernel drivers talk to user mode code through > + filesystem operations even when they don't create a character or > + block special device. It's also been used to do things like ask > + devices what device special file should be used. Two pre-defined > + ioctls are used to disconnect and reconnect kernel drivers, so that > + user mode code can completely manage binding and configuration of > + devices. > + > +USBDEVFS_RELEASEINTERFACE > + This is used to release the claim usbfs made on interface, either > + implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the > + file descriptor is closed. The ioctl parameter is an integer holding > + the number of the interface (bInterfaceNumber from descriptor); File > + modification time is not updated by this request. > + > + **Warning** > + > + *No security check is made to ensure that the task which made > + the claim is the one which is releasing it. This means that user > + mode driver may interfere other ones.* > + > +USBDEVFS_RESETEP > + Resets the data toggle value for an endpoint (bulk or interrupt) to > + DATA0. The ioctl parameter is an integer endpoint number (1 to 15, > + as identified in the endpoint descriptor), with USB_DIR_IN added > + if the device's endpoint sends data to the host. > + > + **Warning** > + > + *Avoid using this request. It should probably be removed.* Using > + it typically means the device and driver will lose toggle > + synchronization. If you really lost synchronization, you likely > + need to completely handshake with the device, using a request > + like CLEAR_HALT or SET_INTERFACE. > + > +USBDEVFS_DROP_PRIVILEGES > + This is used to relinquish the ability to do certain operations > + which are considered to be privileged on a usbfs file descriptor. > + This includes claiming arbitrary interfaces, resetting a device on > + which there are currently claimed interfaces from other users, and > + issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask > + of interfaces the user is allowed to claim on this file descriptor. > + You may issue this ioctl more than one time to narrow said mask. > + > +Synchronous I/O Support > +~~~~~~~~~~~~~~~~~~~~~~~ > + > +Synchronous requests involve the kernel blocking until the user mode > +request completes, either by finishing successfully or by reporting an > +error. In most cases this is the simplest way to use usbfs, although as > +noted above it does prevent performing I/O to more than one endpoint at > +a time. > + > +USBDEVFS_BULK > + Issues a bulk read or write request to the device. The ioctl > + parameter is a pointer to this structure: > + > + :: > + > + struct usbdevfs_bulktransfer { > + unsigned int ep; > + unsigned int len; > + unsigned int timeout; /* in milliseconds */ > + void *data; > + }; > + > + The "ep" value identifies a bulk endpoint number (1 to 15, as > + identified in an endpoint descriptor), masked with USB_DIR_IN when > + referring to an endpoint which sends data to the host from the > + device. The length of the data buffer is identified by "len"; Recent > + kernels support requests up to about 128KBytes. *FIXME say how read > + length is returned, and how short reads are handled.*. > + > +USBDEVFS_CLEAR_HALT > + Clears endpoint halt (stall) and resets the endpoint toggle. This is > + only meaningful for bulk or interrupt endpoints. The ioctl parameter > + is an integer endpoint number (1 to 15, as identified in an endpoint > + descriptor), masked with USB_DIR_IN when referring to an endpoint > + which sends data to the host from the device. > + > + Use this on bulk or interrupt endpoints which have stalled, > + returning *-EPIPE* status to a data transfer request. Do not issue > + the control request directly, since that could invalidate the host's > + record of the data toggle. > + > +USBDEVFS_CONTROL > + Issues a control request to the device. The ioctl parameter points > + to a structure like this: > + > + :: > + > + struct usbdevfs_ctrltransfer { > + __u8 bRequestType; > + __u8 bRequest; > + __u16 wValue; > + __u16 wIndex; > + __u16 wLength; > + __u32 timeout; /* in milliseconds */ > + void *data; > + }; > + > + The first eight bytes of this structure are the contents of the > + SETUP packet to be sent to the device; see the USB 2.0 specification > + for details. The bRequestType value is composed by combining a > + USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\* > + value (from *<linux/usb.h>*). If wLength is nonzero, it describes > + the length of the data buffer, which is either written to the device > + (USB_DIR_OUT) or read from the device (USB_DIR_IN). > + > + At this writing, you can't transfer more than 4 KBytes of data to or > + from a device; usbfs has a limit, and some host controller drivers > + have a limit. (That's not usually a problem.) *Also* there's no way > + to say it's not OK to get a short read back from the device. > + > +USBDEVFS_RESET > + Does a USB level device reset. The ioctl parameter is ignored. After > + the reset, this rebinds all device interfaces. File modification > + time is not updated by this request. > + > + **Warning** > + > + *Avoid using this call* until some usbcore bugs get fixed, since > + it does not fully synchronize device, interface, and driver (not > + just usbfs) state. > + > +USBDEVFS_SETINTERFACE > + Sets the alternate setting for an interface. The ioctl parameter is > + a pointer to a structure like this: > + > + :: > + > + struct usbdevfs_setinterface { > + unsigned int interface; > + unsigned int altsetting; > + }; > + > + File modification time is not updated by this request. > + > + Those struct members are from some interface descriptor applying to > + the current configuration. The interface number is the > + bInterfaceNumber value, and the altsetting number is the > + bAlternateSetting value. (This resets each endpoint in the > + interface.) > + > +USBDEVFS_SETCONFIGURATION > + Issues the :c:func:`usb_set_configuration()` call for the > + device. The parameter is an integer holding the number of a > + configuration (bConfigurationValue from descriptor). File > + modification time is not updated by this request. > + > + **Warning** > + > + *Avoid using this call* until some usbcore bugs get fixed, since > + it does not fully synchronize device, interface, and driver (not > + just usbfs) state. > + > +Asynchronous I/O Support > +~~~~~~~~~~~~~~~~~~~~~~~~ > + > +As mentioned above, there are situations where it may be important to > +initiate concurrent operations from user mode code. This is particularly > +important for periodic transfers (interrupt and isochronous), but it can > +be used for other kinds of USB requests too. In such cases, the > +asynchronous requests described here are essential. Rather than > +submitting one request and having the kernel block until it completes, > +the blocking is separate. > + > +These requests are packaged into a structure that resembles the URB used > +by kernel device drivers. (No POSIX Async I/O support here, sorry.) It > +identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint > +(number, masked with USB_DIR_IN as appropriate), buffer and length, > +and a user "context" value serving to uniquely identify each request. > +(It's usually a pointer to per-request data.) Flags can modify requests > +(not as many as supported for kernel drivers). > + > +Each request can specify a realtime signal number (between SIGRTMIN and > +SIGRTMAX, inclusive) to request a signal be sent when the request > +completes. > + > +When usbfs returns these urbs, the status value is updated, and the > +buffer may have been modified. Except for isochronous transfers, the > +actual_length is updated to say how many bytes were transferred; if the > +USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if > +fewer bytes were read than were requested then you get an error report. > + > +:: > + > + struct usbdevfs_iso_packet_desc { > + unsigned int length; > + unsigned int actual_length; > + unsigned int status; > + }; > + > + struct usbdevfs_urb { > + unsigned char type; > + unsigned char endpoint; > + int status; > + unsigned int flags; > + void *buffer; > + int buffer_length; > + int actual_length; > + int start_frame; > + int number_of_packets; > + int error_count; > + unsigned int signr; > + void *usercontext; > + struct usbdevfs_iso_packet_desc iso_frame_desc[]; > + }; > + > +For these asynchronous requests, the file modification time reflects > +when the request was initiated. This contrasts with their use with the > +synchronous requests, where it reflects when requests complete. > + > +USBDEVFS_DISCARDURB > + *TBS* File modification time is not updated by this request. > + > +USBDEVFS_DISCSIGNAL > + *TBS* File modification time is not updated by this request. > + > +USBDEVFS_REAPURB > + *TBS* File modification time is not updated by this request. > + > +USBDEVFS_REAPURBNDELAY > + *TBS* File modification time is not updated by this request. > + > +USBDEVFS_SUBMITURB > + *TBS* -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
