usb 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537
  1. .TH USB 3
  2. .EQ
  3. delim $$
  4. .EN
  5. .SH NAME
  6. usb \- USB Host Controller Interface
  7. .SH SYNOPSIS
  8. .nf
  9. .B bind -a #u /dev
  10. .PP
  11. .nf
  12. .B /dev/usb
  13. .B /dev/usb/ctl
  14. .BI /dev/usb/ep N . M
  15. .BI /dev/usb/ep N . M /data
  16. .BI /dev/usb/ep N . M /ctl
  17. \&...
  18. .fi
  19. .SH DESCRIPTION
  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)
  23. power to devices.
  24. Branching points in the tree are provided by devices called
  25. .IR hubs .
  26. Hubs provide ports where USB devices (also hubs) can be attached.
  27. .PP
  28. Most PCs have one or more USB controllers called
  29. .I host
  30. controllers.
  31. Each one has a built-in hub called a
  32. .I "root hub"
  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.
  38. .PP
  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)
  42. and
  43. XHCI for USB 3 (up to 5 Gb/s).
  44. We currently support all but XHCI, which is still quite new.
  45. .PP
  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
  48. to them.
  49. The host polls those devices and the hubs merely route the messages.
  50. .PP
  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.
  58. .PP
  59. Enumeration of the bus and initial configuration of devices is done
  60. by a user level program,
  61. .IR usbd (4).
  62. Device drivers are implemented by separate user programs, although
  63. some of them may be statically linked into
  64. .IR usbd .
  65. .PP
  66. The kernel device described in this page is responsible for providing
  67. I/O for using the devices through so called
  68. .IR endpoints .
  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
  74. .IR usbd .
  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
  81. device
  82. .IR endpoints .
  83. Endpoints can be understood as addresses in the bus.
  84. There are several types:
  85. .TF "\fIIsochronous
  86. .TP
  87. .I Control
  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).
  94. .TP
  95. .I Interrupt
  96. Used to send and receive messages to or from a specific device function
  97. (e.g., to read events from a mouse).
  98. .TP
  99. .I Bulk
  100. Used to send and receive larger amounts of data through streams
  101. (e.g., to write blocks to a disk).
  102. .TP
  103. .I Isochronous
  104. Used to send and receive data in a timely manner
  105. (e.g., to write audio samples to a speaker).
  106. .PD
  107. .PP
  108. All USB devices include at least
  109. a control endpoint to perform device configuration.
  110. This is called the
  111. .I setup
  112. endpoint or
  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.
  116. .SS Operation
  117. Bus enumeration and device configuration is performed by
  118. .IR usbd (4)
  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.
  123. .PP
  124. Each directory
  125. .BI /dev/usb/ep N . M
  126. represents an endpoint, where
  127. .I N
  128. is a number identifying a device and
  129. .I M
  130. is a number identifying one of its endpoints.
  131. .PP
  132. For each device attached to the bus, and configured by
  133. .IR usbd (4),
  134. an endpoint zero (a
  135. .I setup
  136. endpoint)
  137. is provided at
  138. .BI /dev/usb/ep N .0
  139. for configuring the device.
  140. This is always a control endpoint and represents the device itself.
  141. .PP
  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
  148. .BI /dev/usb/ep N .3
  149. will be available to access that endpoint.
  150. .PP
  151. All endpoint directories contain two files:
  152. .B data
  153. and
  154. .BR ctl .
  155. The former has mode bit
  156. .B DMEXCL
  157. set and can be open by only one process at a time.
  158. .SS data
  159. .PP
  160. The
  161. .B data
  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.
  168. .PP
  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
  176. .I unstall
  177. in
  178. .IR usb (2))
  179. to resume I/O.
  180. The most common error is
  181. .L crc/timeout
  182. indicating problems in communication with the device (eg., a physical
  183. detach of the device or a wiring problem).
  184. .PP
  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
  189. by default
  190. (but see the
  191. .L timeout
  192. control request).
  193. .SS "ctl and status"
  194. .PP
  195. The
  196. .B ctl
  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.
  201. .PP
  202. This may result from the read of an endpoint control file:
  203. .IP
  204. .EX
  205. .I "(the first line is wrapped to make it fit here)"
  206. .ft L
  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'
  210. .ft
  211. .EE
  212. .LP
  213. The first line contains status information.
  214. The rest is information supplied by
  215. .IR usbd (4)
  216. as an aid to locate devices.
  217. The status information includes:
  218. .TF "\fREndpoint mode
  219. .PD
  220. .TP
  221. Device state
  222. One of
  223. .BR config ,
  224. .BR enabled ,
  225. and
  226. .BR detached .
  227. An endpoint starts in the
  228. .B config
  229. state, and accepts control commands written to its
  230. .B ctl
  231. file to configure the endpoint.
  232. When configured, the
  233. state is
  234. .B enabled
  235. and the
  236. .B data
  237. file is used as described above (several control requests can still
  238. be issued to its
  239. .B ctl
  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
  243. .B detached
  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.
  248. .TP
  249. Endpoint type
  250. .BR control ,
  251. .BR iso ,
  252. .BR interrupt ,
  253. or
  254. .BR bulk ,
  255. indicating the type of transfer supported by the endpoint.
  256. .TP
  257. Endpoint mode
  258. One of
  259. .BR r ,
  260. .BR w ,
  261. or
  262. .BR rw ,
  263. depending on the direction of the endpoint (in, out, or inout).
  264. .TP
  265. Speed
  266. .BR low
  267. (1.5 Mb/s),
  268. .BR full
  269. (12 Mb/s),
  270. or
  271. .BR high
  272. (480 Mb/s).
  273. .TP
  274. Maximum packet size
  275. Used when performing I/O on the data file.
  276. .TP
  277. Polling interval
  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
  284. .I not
  285. use these units, to make things easier for USB device drivers.
  286. .TP
  287. Sample size
  288. Number of bytes per I/O sample (isochronous endpoints only).
  289. .TP
  290. Frequency
  291. Number of samples per second (Hertz).
  292. .TP
  293. Hub address
  294. Device address of the hub where the device is attached.
  295. .TP
  296. Port number
  297. Port number (in the hub) where the device is attached.
  298. .TP
  299. Usage
  300. .L busy
  301. while the data file is open and
  302. .L idle
  303. otherwise.
  304. This is useful to avoid disturbing endpoints already run
  305. by a device driver.
  306. .LP
  307. The second line contains information describing the device:
  308. .TF "\fRDevice strings
  309. .PD
  310. .TP
  311. Class name
  312. As provided by the device itself.
  313. .TP
  314. CSP
  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.
  319. For example,
  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.
  322. .TP
  323. Vid and Did
  324. Vendor and device identifiers.
  325. .TP
  326. Device strings
  327. Provided by the device and identifying the manufacturer and type of device.
  328. .LP
  329. For example, to find a mouse not yet in use by a driver, scan the
  330. .B ctl
  331. files for
  332. .BR enabled ,
  333. .BR idle ,
  334. and
  335. .BR "csp 0x020103" .
  336. A mouse belongs to class 3 (in the least significant byte),
  337. .IR "human interface device" ,
  338. subclass 1,
  339. .IR boot ,
  340. protocol 2,
  341. .I mouse
  342. (protocol 1 would be the keyboard).
  343. USB class, subclass and proto codes can be found at
  344. .BR http://www.usb.org .
  345. .SS Control requests
  346. Endpoint control files accept the following requests.
  347. In most cases
  348. the driver does not issue them, leaving the task to either
  349. .IR usbd (4)
  350. or the usb driver library documented in
  351. .IR usb (2).
  352. .TF "\fLsamplehz\fI n
  353. .TP
  354. .B detach
  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.
  357. .TP
  358. .BI maxpkt " n"
  359. Set the maximum packet size to
  360. .I n
  361. bytes.
  362. .TP
  363. .BI pollival " n"
  364. Only for interrupt and isochronous endpoints.
  365. Set the polling interval as a function of the value
  366. .I n
  367. given by the endpoint descriptor.
  368. The interval value used is the period
  369. .I n
  370. in bus time units for low- and full-speed interrupt endpoints.
  371. Otherwise, the actual interval is
  372. $2 sup n$
  373. and not
  374. .IR n .
  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.
  384. .TP
  385. .BI samplesz " n"
  386. Use
  387. .I n
  388. as the number of bytes per sample.
  389. .TP
  390. .BI hz " n"
  391. Use
  392. .I n
  393. as the number of samples per second.
  394. .TP
  395. .BI ntds " n"
  396. Use
  397. .I n
  398. as the number of transactions per frame (or µframe), as reported
  399. by the descriptor.
  400. .TP
  401. .B clrhalt
  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).
  405. .TP
  406. .BI info " string"
  407. Replaces description information in
  408. .B ctl
  409. with
  410. .IR string .
  411. .IR Usbd (4)
  412. uses this to add device descriptions.
  413. .TP
  414. .B address
  415. Tell this driver that the device has been given an address,
  416. which causes the device to enter the
  417. .I enabled
  418. state.
  419. .TP
  420. .BI name " str"
  421. Generates an additional file name,
  422. .I str ,
  423. for the
  424. .B data
  425. file of the endpoint.
  426. This file name appears in the root directory of the
  427. .L #u
  428. tree.
  429. For example, this is used by the audio device
  430. driver to make the
  431. .B data
  432. file also available as
  433. .BR /dev/audio .
  434. .TP
  435. .BI debug " n"
  436. Enable debugging of the endpoint.
  437. .I N
  438. is an integer;
  439. larger values make diagnostics more verbose.
  440. .L 0
  441. stops debugging diagnostics.
  442. .L 1
  443. causes just problem reports.
  444. Bigger values report almost everything.
  445. .TP
  446. .BI timeout " n"
  447. Enable time-outs for the endpoint.
  448. Transfers are timed out by the kernel after
  449. .I n
  450. ms.
  451. This should not be used for control and isochronous endpoints,
  452. which are always timed out.
  453. .PD
  454. .LP
  455. Setup endpoints
  456. (those represented by
  457. .BI ep N .0
  458. directories)
  459. also accept the following requests:
  460. .TP
  461. .BI new " n type mode"
  462. Creates a new endpoint with number
  463. .I n
  464. of the given
  465. .IR type
  466. (\c
  467. .BR ctl ,
  468. .BR bulk ,
  469. .BR intr ,
  470. or
  471. .BR iso ).
  472. .I Mode
  473. may be
  474. .BR r ,
  475. .BR w ,
  476. or
  477. .BR rw ,
  478. which creates, respectively, an input, output, or input/output endpoint.
  479. .TP
  480. .B "speed {low|full|high}
  481. Set the endpoint speed to full, low, or high, respectively.
  482. .TP
  483. .B hub
  484. Tell this driver that the endpoint corresponds to a hub device.
  485. .PD
  486. .PP
  487. Setup endpoints for hub devices also accept his request:
  488. .TP
  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.
  492. .I Port
  493. is the port number where the device is attached
  494. (the hub is implied by the endpoint where the control request is issued).
  495. .PD
  496. .PP
  497. The file
  498. .B /dev/usb/ctl
  499. provides all the information provided by the various
  500. .B ctl
  501. files when read.
  502. It accepts several requests that refer to
  503. the entire driver and not to particular endpoints:
  504. .TF "\fLdebug \fIn"
  505. .TP
  506. .B "debug \fIn\fP
  507. Sets the global debug flag to
  508. .IR n .
  509. .TP
  510. .B dump
  511. Dumps data structures for inspection.
  512. .SH FILES
  513. .TF #u/usb
  514. .TP
  515. .B #u/usb
  516. root of the USB interface
  517. .SH SOURCE
  518. .B /sys/src/9/port/usb.h
  519. .br
  520. .B /sys/src/9/*/*usb?hci.h
  521. .br
  522. .B /sys/src/9/*/devusb.c
  523. .br
  524. .B /sys/src/9/*/usb?hci*.c
  525. .SH "SEE ALSO"
  526. .IR usb (2),
  527. .IR usb (4),
  528. .IR usbd (4),
  529. .IR plan9.ini (8)
  530. .SH BUGS
  531. USB controllers limit the speed of all their ports
  532. to that of the slowest device connected to any one of them.
  533. .PP
  534. Isochronous input streams are not implemented for OHCI.
  535. .PP
  536. Some EHCI controllers drop completion interrupts and so must
  537. be polled, which hurts throughput.