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 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).
45 The USB bus is fully controlled by the host; all devices are polled.
46 Hubs are passive in the sense that they do not poll the devices attached
48 The host polls those devices and the hubs merely route the messages.
50 Devices may be added to or removed from the bus at any time.
51 When a device is attached, the host queries it to determine its type and speed.
52 The querying process is standardized.
53 The first level of querying is the same for all devices,
54 the next is somewhat specialized
55 for particular classes of devices (such as mice, keyboards, or audio devices).
56 Specialization continues as subclasses and subsubclasses are explored.
58 Enumeration of the bus and initial configuration of devices is done
59 by a user-level program,
61 Device drivers are implemented by separate user programs, although
62 some of them may be statically linked into
65 The kernel device described in this page is responsible for providing
66 I/O for using the devices through so called
68 Access to the host controller is hidden from user programs, which see
69 just a set of endpoints.
70 After system initialization, some endpoints
71 are created by the device to permit I/O to root hubs.
72 All other devices must be configured by
74 .SS Devices and Endpoints
75 A device includes one or more functions (e.g., audio output,
76 volume control buttons, mouse input, etc.)
77 Communication with device functions is performed
78 by some combination of
79 issuing control requests to, sending data to, and receiving data from
82 Endpoints can be understood as addresses in the bus.
83 There are several types:
87 Their main use is to configure devices.
88 Writing a message with a specific format
89 (specified in the USB specification)
90 issues a request to the device.
91 If the request implies a reply,
92 a read can be made next to retrieve the requested data (if the write succeeded).
95 Used to send and receive messages to or from a specific device function
96 (e.g., to read events from a mouse).
99 Used to send and receive larger amounts of data through streams
100 (e.g., to write blocks to a disk).
103 Used to send and receive data in a timely manner
104 (e.g., to write audio samples to a speaker).
107 All USB devices include at least
108 a control endpoint to perform device configuration.
112 .IR "endpoint zero" .
113 After configuring a device, other endpoints may be created
114 as dictated by the device to perform actual I/O.
116 Bus enumeration and device configuration is performed by
118 and not by this driver.
119 The driver provides an interface
120 to access existing endpoints (initially those for the built-in root hubs),
121 to create and configure other ones, and to perform I/O through them.
124 .BI /dev/usb/ep N . M
125 represents an endpoint, where
127 is a number identifying a device and
129 is a number identifying one of its endpoints.
131 For each device attached to the bus, and configured by
138 for configuring the device.
139 This is always a control endpoint and represents the device itself.
141 The device driver may use the setup endpoint
142 to issue control requests and perhaps to create more endpoints for the device.
143 Each new endpoint created has its own directory as said above.
144 For example, if the driver for the device
145 .BI /dev/usb/ep N . 0
146 creates the endpoint number 3 for that device, a directory
148 will be available to access that endpoint.
150 All endpoint directories contain two files:
154 The former has mode bit
156 set and can be open by only one process at a time.
161 file is used to perform actual I/O.
162 In general, reading from it retrieves
163 data from the endpoint and writing into it sends data to the endpoint.
164 For control endpoints, writing to this file issues a control request
165 (which may include data); if the request retrieves data from the device,
166 a following read on the file will provide such data.
168 USB errors reported by the endpoint upon I/O failures
169 are passed to the user process through the error string.
170 I/O stalls not resulting from an error, usually
171 an indication from the device, are reported by indicating that the
172 number of bytes transferred has been zero.
173 In most cases, the correct course of action after noticing the stall
174 is for the device driver to issue a `clear halt' request (see
179 The most common error is
181 indicating problems in communication with the device (e.g., a physical
182 detach of the device or a wiring problem).
184 For control and isochronous transfers, there is an implicit
185 timeout performed by the kernel and it is not necessary for applications
186 to place their own timers.
187 For other transfer types, the kernel will not time out any operation
196 file can be read to learn about the endpoint.
197 It contains information that can be used
198 to locate a particular device (or endpoint).
199 It also accepts writes with textual control requests described later.
201 This may result from the read of an endpoint control file:
204 .I "(the first line is wrapped to make it fit here)"
206 enabled control rw speed full maxpkt 64 pollival 0
207 samplesz 0 hz 0 hub 1 port 3 busy
208 storage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II'
212 The first line contains status information.
213 The rest is information supplied by
215 as an aid to locate devices.
216 The status information includes:
217 .TF "\fREndpoint mode
226 An endpoint starts in the
228 state, and accepts control commands written to its
230 file to configure the endpoint.
236 file is used as described above (several control requests can still
239 file, but most will not be accepted from now on).
240 Upon severe errors, perhaps a physical
241 detachment from the bus, the endpoint enters the
243 state and no further I/O is accepted on it.
244 Files for an endpoint (including its directory)
245 vanish when the device is detached and its files are no longer open.
246 Root hubs may not be detached.
254 indicating the type of transfer supported by the endpoint.
262 depending on the direction of the endpoint (in, out, or inout).
276 Used when performing I/O on the data file.
279 The polling period expressed as a number of µframes
280 (for high-speed endpoints) or frames (for low- and full-speed endpoints).
281 Note that a µframe takes 125 µs while a frame takes 1 ms.
282 This is only of relevance for interrupt and isochronous endpoints.
283 This value determines how often I/O happens.
284 Note that the control request adjusting the polling interval does
286 use these units, to make things easier for USB device drivers.
289 Number of bytes per I/O sample (isochronous endpoints only).
292 Number of samples per second (Hertz).
295 Device address of the hub where the device is attached.
298 Port number (in the hub) where the device is attached.
302 while the data file is open and
305 This is useful to avoid disturbing endpoints already run
308 The second line contains information describing the device:
309 .TF "\fRDevice strings
313 As provided by the device itself.
316 Class, Subclass, and Protocol for the device.
317 If the device contains different functions and has more CSPs,
318 all of them will be listed.
319 The first one is that of the device itself.
321 a mouse and keyboard combo may identify itself as a keyboard but
322 then include two CSPs, one for the keyboard and another one for the mouse.
325 Vendor and device identifiers.
328 Provided by the device and identifying the manufacturer and type of device.
330 For example, to find a mouse not yet in use by a driver, scan the
337 A mouse belongs to class 3 (in the least significant byte),
338 .IR "human interface device" ,
343 (protocol 1 would be the keyboard).
344 USB class, subclass and proto codes can be found at
345 .BR http://www.usb.org .
347 Endpoint control files accept the following requests.
349 the driver does not issue them, leaving the task to either
351 or the usb driver library documented in
353 .TF "\fLsamplehz\fI n
356 Prevent further I/O on the device (delete the endpoint)
357 and remove its file interface as soon as no process is using their files.
360 Set the maximum packet size to
365 Only for interrupt and isochronous endpoints.
366 Set the polling interval as a function of the value
368 given by the endpoint descriptor.
369 The interval value used is the period
371 in bus time units for low- and full-speed interrupt endpoints.
372 Otherwise, the actual interval is
376 Bus time units are 1 ms for low- and full-speed endpoints and 125 µs for
377 high-speed endpoints.
378 In most cases, the device driver may ignore
379 all this and issue the control request supplying the
380 polling interval value as found
381 in the endpoint descriptor.
382 The kernel adjusts the value according
383 to the endpoint configuration and converts it into the number of
384 frames or µframes between two consecutive polls.
389 as the number of bytes per sample.
394 as the number of samples per second.
399 as the number of transactions per frame (or µframe), as reported
405 is set to 1 for an isochronous endpoint,
407 from the data file will not cross μframe boundaries.
410 Clear the halt condition for an endpoint.
411 Used to recover from a stall caused by a device to signal its driver
412 (usually due to an unknown request or a failure to complete one).
415 Replaces description information in
420 uses this to add device descriptions.
423 Tell this driver that the device has been given an address,
424 which causes the device to enter the
429 Generates an additional file name,
433 file of the endpoint.
434 This file name appears in the root directory of the
437 For example, this is used by the audio device
440 file also available as
444 Enable debugging of the endpoint.
447 larger values make diagnostics more verbose.
449 stops debugging diagnostics.
451 causes just problem reports.
452 Bigger values report almost everything.
455 Enable time-outs for the endpoint.
456 Transfers are timed out by the kernel after
459 This should not be used for control and isochronous endpoints,
460 which are always timed out.
464 (those represented by
467 also accept the following requests:
469 .BI new " n type mode"
470 Creates a new endpoint with number
486 which creates, respectively, an input, output, or input/output endpoint.
488 .B "speed {low|full|high|super}
489 Set the endpoint speed to full, low, high, or SuperSpeed, respectively.
492 Tell this driver that the endpoint corresponds to a hub device.
495 Setup endpoints for hub devices also accept
497 .B "newdev {low|full|high|super} \fIport\fP
498 Create a new setup endpoint to represent a new device.
499 The first argument is the device speed.
501 is the port number where the device is attached
502 (the hub is implied by the endpoint where the control request is issued).
507 provides all the information provided by the various
510 It accepts several requests that refer to
511 the entire driver and not to particular endpoints:
515 Sets the global debug flag to
519 Dumps data structures for inspection.
524 root of the USB interface
526 .B /sys/src/9/port/usb.h
528 .B /sys/src/9/port/devusb.c
530 .B /sys/src/9/*/usb*.c
536 USB controllers limit the speed of all their ports
537 to that of the slowest device connected to any one of them.
539 Isochronous input streams are not implemented for OHCI.
541 Some EHCI controllers drop completion interrupts and so must
542 be polled, which hurts throughput.
projects / plan9front.git / blob