.TH USB 3.EQdelim $$.EN.SH NAMEusb \- USB Host Controller Interface.SH SYNOPSIS.nf.B bind -a #u /dev.PP.nf.B /dev/usb.B /dev/usb/ctl.BI /dev/usb/ep N . M.BI /dev/usb/ep N . M /data.BI /dev/usb/ep N . M /ctl\&....fi.SH DESCRIPTIONThe Universal Serial Bus is a complex yet popular busfor connecting all kind of devices to a computer.It is a four-wire tree-shaped bus that provides both communication and (limited)power to devices.Branching points in the tree are provided by devices called.IR hubs .Hubs provide ports where USB devices (also hubs) can be attached..PPMost PCs have one or more USB controllers called.I hostcontrollers.Each one has a built-in hub called a.I "root hub"providing several ports.In some cases, more hubs are built-inand attached to a root hub port.The topology of the network is a tree with at most127 nodes, counting both internal and leaf nodes..PPHost controllers come in four flavours:UHCI and OHCI for USB 1 (up to 12 Mb/s),EHCI for USB 2 (up to 480 Mb/s)andXHCI for USB 3 (up to 5 Gb/s).We currently support all but XHCI, which is still quite new..PPThe USB bus is fully controlled by the host; all devices are polled.Hubs are passive in the sense that they do not poll the devices attachedto them.The host polls those devices and the hubs merely route the messages..PPDevices may be added to or removed from the bus at any time.When a device is attached, the host queries it to determine its type and speed.The querying process is standardized.The first level of querying is the same for all devices,the next is somewhat specializedfor particular classes of devices (such as mice, keyboards, or audio devices).Specialization continues as subclasses and subsubclasses are explored..PPEnumeration of the bus and initial configuration of devices is doneby a user level program,.IR usbd (4).Device drivers are implemented by separate user programs, althoughsome of them may be statically linked into.IR usbd ..PPThe kernel device described in this page is responsible for providingI/O for using the devices through so called.IR endpoints .Access to the host controller is hidden from user programs, which seejust a set of endpoints.After system initialization, some endpointsare created by the device to permit I/O to root hubs.All other devices must be configured by.IR usbd ..SS Devices and EndpointsA device includes one or more functions (e.g., audio output,volume control buttons, mouse input, etc.)Communication with device functions is performedby some combination ofissuing control requests to, sending data to, and receiving data fromdevice.IR endpoints .Endpoints can be understood as addresses in the bus.There are several types:.TF "\fIIsochronous.TP.I ControlTheir main use is to configure devices.Writing a message with a specific format(specified in the USB specification)issues a request to the device.If the request implies a reply,a read can be made next to retrieve the requested data (if the write succeeded)..TP.I InterruptUsed to send and receive messages to or from a specific device function(e.g., to read events from a mouse)..TP.I BulkUsed to send and receive larger amounts of data through streams(e.g., to write blocks to a disk)..TP.I IsochronousUsed to send and receive data in a timely manner(e.g., to write audio samples to a speaker)..PD.PPAll USB devices include at leasta control endpoint to perform device configuration.This is called the.I setupendpoint or.IR "endpoint zero" .After configuring a device, other endpoints may be createdas dictated by the device to perform actual I/O..SS OperationBus enumeration and device configuration is performed by.IR usbd (4)and not by this driver.The driver provides an interfaceto access existing endpoints (initially those for the built-in root hubs),to create and configure other ones, and to perform I/O through them..PPEach directory.BI /dev/usb/ep N . Mrepresents an endpoint, where.I Nis a number identifying a device and.I Mis a number identifying one of its endpoints..PPFor each device attached to the bus, and configured by.IR usbd (4),an endpoint zero (a.I setupendpoint)is provided at.BI /dev/usb/ep N .0for configuring the device.This is always a control endpoint and represents the device itself..PPThe device driver may use the setup endpointto issue control requests and perhaps to create more endpoints for the device.Each new endpoint created has its own directory as said above.For example, if the driver for the device.BI /dev/usb/ep N . 0creates the endpoint number 3 for that device, a directory.BI /dev/usb/ep N .3will be available to access that endpoint..PPAll endpoint directories contain two files:.B dataand.BR ctl .The former has mode bit.B DMEXCLset and can be open by only one process at a time..SS data.PPThe.B datafile is used to perform actual I/O.In general, reading from it retrievesdata from the endpoint and writing into it sends data to the endpoint.For control endpoints, writing to this file issues a control request(which may include data); if the request retrieves data from the device,a following read on the file will provide such data..PPUSB errors reported by the endpoint upon I/O failuresare passed to the user process through the error string.I/O stalls not resulting from an error, usuallyan indication from the device, are reported by indicating that thenumber of bytes transferred has been zero.In most cases, the correct course of action after noticing the stallis for the device driver to issue a `clear halt' request (see.I unstallin.IR usb (2))to resume I/O.The most common error is.L crc/timeoutindicating problems in communication with the device (eg., a physicaldetach of the device or a wiring problem)..PPFor control and isochronous transfers, there is an implicittimeout performed by the kernel and it is not necessary for applicationsto place their own timers.For other transfer types, the kernel will not time out any operationby default(but see the.L timeoutcontrol request)..SS "ctl and status".PPThe.B ctlfile can be read to learn about the endpoint.It contains information that can be usedto locate a particular device (or endpoint).It also accepts writes with textual control requests described later..PPThis may result from the read of an endpoint control file:.IP.EX.I "(the first line is wrapped to make it fit here)".ft Lenabled control rw speed full maxpkt 64 pollival 0	samplesz 0 hz 0 hub 1 port 3 busystorage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II'.ft.EE.LPThe first line contains status information.The rest is information supplied by.IR usbd (4)as an aid to locate devices.The status information includes:.TF "\fREndpoint mode.PD.TPDevice stateOne of.BR config ,.BR enabled ,and.BR detached .An endpoint starts in the.B configstate, and accepts control commands written to its.B ctlfile to configure the endpoint.When configured, thestate is.B enabledand the.B datafile is used as described above (several control requests can stillbe issued to its.B ctlfile, but most will not be accepted from now on).Upon severe errors, perhaps a physicaldetachment from the bus, the endpoint enters the.B detachedstate and no further I/O is accepted on it.Files for an endpoint (including its directory)vanish when the device is detached and its files are no longer open.Root hubs may not be detached..TPEndpoint type.BR control ,.BR iso ,.BR interrupt ,or.BR bulk ,indicating the type of transfer supported by the endpoint..TPEndpoint modeOne of.BR r ,.BR w ,or.BR rw ,depending on the direction of the endpoint (in, out, or inout)..TPSpeed.BR low(1.5 Mb/s),.BR full(12 Mb/s),or.BR high(480 Mb/s)..TPMaximum packet sizeUsed when performing I/O on the data file..TPPolling intervalThe polling period expressed as a number of µframes(for high-speed endpoints) or frames (for low- and full-speed endpoints).Note that a µframe takes 125 µs while a frame takes 1 ms.This is only of relevance for interrupt and isochronous endpoints.This value determines how often I/O happens.Note that the control request adjusting the polling interval does.I notuse these units, to make things easier for USB device drivers..TPSample sizeNumber of bytes per I/O sample (isochronous endpoints only)..TPFrequencyNumber of samples per second (Hertz)..TPHub addressDevice address of the hub where the device is attached..TPPort numberPort number (in the hub) where the device is attached..TPUsage.L busywhile the data file is open and.L idleotherwise.This is useful to avoid disturbing endpoints already runby a device driver..LPThe second line contains information describing the device:.TF "\fRDevice strings.PD.TPClass nameAs provided by the device itself..TPCSPClass, Subclass, and Protocol for the device.If the device contains different functions and has more CSPs,all of them will be listed.The first one is that of the device itself.For example,a mouse and keyboard combo may identify itself as a keyboard butthen include two CSPs, one for the keyboard and another one for the mouse..TPVid and DidVendor and device identifiers..TPDevice stringsProvided by the device and identifying the manufacturer and type of device..LPFor example, to find a mouse not yet in use by a driver, scan the.B ctlfiles for.BR enabled ,.BR idle ,and.BR "csp 0x020103" .A mouse belongs to class 3 (in the least significant byte),.IR "human interface device" ,subclass 1,.IR boot ,protocol 2,.I mouse(protocol 1 would be the keyboard).USB class, subclass and proto codes can be found at.BR http://www.usb.org ..SS Control requestsEndpoint control files accept the following requests.In most casesthe driver does not issue them, leaving the task to either.IR usbd (4)or the usb driver library documented in.IR usb (2)..TF "\fLsamplehz\fI n.TP.B detachPrevent further I/O on the device (delete the endpoint)and remove its file interface as soon as no process is using their files..TP.BI maxpkt " n"Set the maximum packet size to.I nbytes..TP.BI pollival " n"Only for interrupt and isochronous endpoints.Set the polling interval as a function of the value.I ngiven by the endpoint descriptor.The interval value used is the period.I nin bus time units for low- and full-speed interrupt endpoints.Otherwise, the actual interval is$2 sup n$and not.IR n .Bus time units are 1 ms for low- and full-speed endpoints and 125 µs forhigh-speed endpoints.In most cases, the device driver may ignoreall this and issue the control request supplying thepolling interval value as foundin the endpoint descriptor.The kernel adjusts the value accordingto the endpoint configuration and converts it into the number offrames or µframes between two consecutive polls..TP.BI samplesz " n"Use.I nas the number of bytes per sample..TP.BI hz " n"Use.I nas the number of samples per second..TP.BI ntds " n"Use.I nas the number of transactions per frame (or µframe), as reportedby the descriptor..TP.B clrhaltClear the halt condition for an endpoint.Used to recover from a stall caused by a device to signal its driver(usually due to an unknown request or a failure to complete one)..TP.BI info " string"Replaces description information in.B ctlwith.IR string ..IR Usbd (4)uses this to add device descriptions..TP.B addressTell this driver that the device has been given an address,which causes the device to enter the.I enabledstate..TP.BI name " str"Generates an additional file name,.I str ,for the.B datafile of the endpoint.This file name appears in the root directory of the.L #utree.For example, this is used by the audio devicedriver to make the.B datafile also available as.BR /dev/audio ..TP.BI debug " n"Enable debugging of the endpoint..I Nis an integer;larger values make diagnostics more verbose..L 0stops debugging diagnostics..L 1causes just problem reports.Bigger values report almost everything..TP.BI timeout " n"Enable time-outs for the endpoint.Transfers are timed out by the kernel after.I nms.This should not be used for control and isochronous endpoints,which are always timed out..PD.LPSetup endpoints(those represented by.BI ep N .0directories)also accept the following requests:.TP.BI new " n type mode"Creates a new endpoint with number.I nof the given.IR type(\c.BR ctl ,.BR bulk ,.BR intr ,or.BR iso )..I Modemay be.BR r ,.BR w ,or.BR rw ,which creates, respectively, an input, output, or input/output endpoint..TP.B "speed {low|full|high}Set the endpoint speed to full, low, or high, respectively..TP.B hubTell this driver that the endpoint corresponds to a hub device..PD.PPSetup endpoints for hub devices also accept his request:.TP.B "newdev {low|full|high} \fIport\fPCreate a new setup endpoint to represent a new device.The first argument is the device speed..I Portis the port number where the device is attached(the hub is implied by the endpoint where the control request is issued)..PD.PPThe file.B /dev/usb/ctlprovides all the information provided by the various.B ctl

Lines 1–500 of 535. Load more