6 usb \- USB Host Controller Interface
15 .BI /dev/usb/ep N . M /data
16 .BI /dev/usb/ep N . M /ctl
20 The Universal Serial Bus is a complex yet popular bus
21 for connecting all kind of devices to a computer.
22 It is a four-wire tree-shaped bus that provides both communication and (limited)
24 Branching points in the tree are provided by devices called
26 Hubs provide ports where USB devices (also hubs) can be attached.
28 Most PCs have one or more USB controllers called
31 Each one has a built-in hub called a
33 providing several ports.
34 In some cases, more hubs are built-in
35 and attached to a root hub port.
36 The topology of the network is a tree with at most
37 127 nodes, counting both internal and leaf nodes.
39 Host controllers come in four flavours:
40 UHCI and OHCI for USB 1 (up to 12 Mb/s),
41 EHCI for USB 2 (up to 480 Mb/s)
43 XHCI for USB 3 (up to 5 Gb/s).
44 We currently support all but XHCI, which is still quite new.
46 The USB bus is fully controlled by the host; all devices are polled.
47 Hubs are passive in the sense that they do not poll the devices attached
49 The host polls those devices and the hubs merely route the messages.
51 Devices may be added to or removed from the bus at any time.
52 When a device is attached, the host queries it to determine its type and speed.
53 The querying process is standardized.
54 The first level of querying is the same for all devices,
55 the next is somewhat specialized
56 for particular classes of devices (such as mice, keyboards, or audio devices).
57 Specialization continues as subclasses and subsubclasses are explored.
59 Enumeration of the bus and initial configuration of devices is done
60 by a user level program,
62 Device drivers are implemented by separate user programs, although
63 some of them may be statically linked into
66 The kernel device described in this page is responsible for providing
67 I/O for using the devices through so called
69 Access to the host controller is hidden from user programs, which see
70 just a set of endpoints.
71 After system initialization, some endpoints
72 are created by the device to permit I/O to root hubs.
73 All other devices must be configured by
75 .SS Devices and Endpoints
76 A device includes one or more functions (e.g., audio output,
77 volume control buttons, mouse input, etc.)
78 Communication with device functions is performed
79 by some combination of
80 issuing control requests to, sending data to, and receiving data from
83 Endpoints can be understood as addresses in the bus.
84 There are several types:
88 Their main use is to configure devices.
89 Writing a message with a specific format
90 (specified in the USB specification)
91 issues a request to the device.
92 If the request implies a reply,
93 a read can be made next to retrieve the requested data (if the write succeeded).
96 Used to send and receive messages to or from a specific device function
97 (e.g., to read events from a mouse).
100 Used to send and receive larger amounts of data through streams
101 (e.g., to write blocks to a disk).
104 Used to send and receive data in a timely manner
105 (e.g., to write audio samples to a speaker).
108 All USB devices include at least
109 a control endpoint to perform device configuration.
113 .IR "endpoint zero" .
114 After configuring a device, other endpoints may be created
115 as dictated by the device to perform actual I/O.
117 Bus enumeration and device configuration is performed by
119 and not by this driver.
120 The driver provides an interface
121 to access existing endpoints (initially those for the built-in root hubs),
122 to create and configure other ones, and to perform I/O through them.
125 .BI /dev/usb/ep N . M
126 represents an endpoint, where
128 is a number identifying a device and
130 is a number identifying one of its endpoints.
132 For each device attached to the bus, and configured by
139 for configuring the device.
140 This is always a control endpoint and represents the device itself.
142 The device driver may use the setup endpoint
143 to issue control requests and perhaps to create more endpoints for the device.
144 Each new endpoint created has its own directory as said above.
145 For example, if the driver for the device
146 .BI /dev/usb/ep N . 0
147 creates the endpoint number 3 for that device, a directory
149 will be available to access that endpoint.
151 All endpoint directories contain two files:
155 The former has mode bit
157 set and can be open by only one process at a time.
162 file is used to perform actual I/O.
163 In general, reading from it retrieves
164 data from the endpoint and writing into it sends data to the endpoint.
165 For control endpoints, writing to this file issues a control request
166 (which may include data); if the request retrieves data from the device,
167 a following read on the file will provide such data.
169 USB errors reported by the endpoint upon I/O failures
170 are passed to the user process through the error string.
171 I/O stalls not resulting from an error, usually
172 an indication from the device, are reported by indicating that the
173 number of bytes transferred has been zero.
174 In most cases, the correct course of action after noticing the stall
175 is for the device driver to issue a `clear halt' request (see
180 The most common error is
182 indicating problems in communication with the device (eg., a physical
183 detach of the device or a wiring problem).
185 For control and isochronous transfers, there is an implicit
186 timeout performed by the kernel and it is not necessary for applications
187 to place their own timers.
188 For other transfer types, the kernel will not time out any operation
197 file can be read to learn about the endpoint.
198 It contains information that can be used
199 to locate a particular device (or endpoint).
200 It also accepts writes with textual control requests described later.
202 This may result from the read of an endpoint control file:
205 .I "(the first line is wrapped to make it fit here)"
207 enabled control rw speed full maxpkt 64 pollival 0
208 samplesz 0 hz 0 hub 1 port 3 busy
209 storage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II'
213 The first line contains status information.
214 The rest is information supplied by
216 as an aid to locate devices.
217 The status information includes:
218 .TF "\fREndpoint mode
227 An endpoint starts in the
229 state, and accepts control commands written to its
231 file to configure the endpoint.
237 file is used as described above (several control requests can still
240 file, but most will not be accepted from now on).
241 Upon severe errors, perhaps a physical
242 detachment from the bus, the endpoint enters the
244 state and no further I/O is accepted on it.
245 Files for an endpoint (including its directory)
246 vanish when the device is detached and its files are no longer open.
247 Root hubs may not be detached.
255 indicating the type of transfer supported by the endpoint.
263 depending on the direction of the endpoint (in, out, or inout).
275 Used when performing I/O on the data file.
278 The polling period expressed as a number of µframes
279 (for high-speed endpoints) or frames (for low- and full-speed endpoints).
280 Note that a µframe takes 125 µs while a frame takes 1 ms.
281 This is only of relevance for interrupt and isochronous endpoints.
282 This value determines how often I/O happens.
283 Note that the control request adjusting the polling interval does
285 use these units, to make things easier for USB device drivers.
288 Number of bytes per I/O sample (isochronous endpoints only).
291 Number of samples per second (Hertz).
294 Device address of the hub where the device is attached.
297 Port number (in the hub) where the device is attached.
301 while the data file is open and
304 This is useful to avoid disturbing endpoints already run
307 The second line contains information describing the device:
308 .TF "\fRDevice strings
312 As provided by the device itself.
315 Class, Subclass, and Protocol for the device.
316 If the device contains different functions and has more CSPs,
317 all of them will be listed.
318 The first one is that of the device itself.
320 a mouse and keyboard combo may identify itself as a keyboard but
321 then include two CSPs, one for the keyboard and another one for the mouse.
324 Vendor and device identifiers.
327 Provided by the device and identifying the manufacturer and type of device.
329 For example, to find a mouse not yet in use by a driver, scan the
336 A mouse belongs to class 3 (in the least significant byte),
337 .IR "human interface device" ,
342 (protocol 1 would be the keyboard).
343 USB class, subclass and proto codes can be found at
344 .BR http://www.usb.org .
346 Endpoint control files accept the following requests.
348 the driver does not issue them, leaving the task to either
350 or the usb driver library documented in
352 .TF "\fLsamplehz\fI n
355 Prevent further I/O on the device (delete the endpoint)
356 and remove its file interface as soon as no process is using their files.
359 Set the maximum packet size to
364 Only for interrupt and isochronous endpoints.
365 Set the polling interval as a function of the value
367 given by the endpoint descriptor.
368 The interval value used is the period
370 in bus time units for low- and full-speed interrupt endpoints.
371 Otherwise, the actual interval is
375 Bus time units are 1 ms for low- and full-speed endpoints and 125 µs for
376 high-speed endpoints.
377 In most cases, the device driver may ignore
378 all this and issue the control request supplying the
379 polling interval value as found
380 in the endpoint descriptor.
381 The kernel adjusts the value according
382 to the endpoint configuration and converts it into the number of
383 frames or µframes between two consecutive polls.
388 as the number of bytes per sample.
393 as the number of samples per second.
398 as the number of transactions per frame (or µframe), as reported
402 Clear the halt condition for an endpoint.
403 Used to recover from a stall caused by a device to signal its driver
404 (usually due to an unknown request or a failure to complete one).
407 Replaces description information in
412 uses this to add device descriptions.
415 Tell this driver that the device has been given an address,
416 which causes the device to enter the
421 Generates an additional file name,
425 file of the endpoint.
426 This file name appears in the root directory of the
429 For example, this is used by the audio device
432 file also available as
436 Enable debugging of the endpoint.
439 larger values make diagnostics more verbose.
441 stops debugging diagnostics.
443 causes just problem reports.
444 Bigger values report almost everything.
447 Enable time-outs for the endpoint.
448 Transfers are timed out by the kernel after
451 This should not be used for control and isochronous endpoints,
452 which are always timed out.
456 (those represented by
459 also accept the following requests:
461 .BI new " n type mode"
462 Creates a new endpoint with number
478 which creates, respectively, an input, output, or input/output endpoint.
480 .B "speed {low|full|high}
481 Set the endpoint speed to full, low, or high, respectively.
484 Tell this driver that the endpoint corresponds to a hub device.
487 Setup endpoints for hub devices also accept his request:
489 .B "newdev {low|full|high} \fIport\fP
490 Create a new setup endpoint to represent a new device.
491 The first argument is the device speed.
493 is the port number where the device is attached
494 (the hub is implied by the endpoint where the control request is issued).
499 provides all the information provided by the various
502 It accepts several requests that refer to
503 the entire driver and not to particular endpoints:
507 Sets the global debug flag to
511 Dumps data structures for inspection.
516 root of the USB interface
518 .B /sys/src/9/port/usb.h
520 .B /sys/src/9/pc/devusb.c
522 .B /sys/src/9/pc/usb?hci.c
528 USB controllers limit the speed of all their ports
529 to that of the slowest device connected to any one of them.
531 Isochronous input streams are not implemented for OHCI.
533 Some EHCI controllers drop completion interrupts and so must
534 be polled, which hurts throughput.
projects / plan9front.git / blob