usb 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. .TH USB 3
  2. .SH NAME
  3. usb \- USB Host Controller Interface
  4. .SH SYNOPSIS
  5. .nf
  6. .B bind -a #U /dev
  7. .PP
  8. .nf
  9. .BI /dev/usb m
  10. .BI /dev/usb m /new
  11. .BI /dev/usb m /port
  12. .BI /dev/usb m / n
  13. .BI /dev/usb m / n /ctl
  14. .BI /dev/usb m / n /status
  15. .BI /dev/usb m / n /setup
  16. .BI /dev/usb m / n /ep k\fLdata
  17. \&...
  18. .fi
  19. .SH DESCRIPTION
  20. The Universal Serial Bus is a popular bus for connecting slow and medium speed
  21. devices, such as mice, keyboards, printers, and scanners to a PC. It is
  22. a four-wire tree-shaped bus that provides both communication and (limited)
  23. power to devices. Branching points in the tree are provided by devices
  24. called
  25. .IR hubs .
  26. .PP
  27. Most PCs have a two-slot hub built in, accommodating two USB devices. To
  28. attach more devices, one or more hubs have to be plugged in to the USB
  29. slots of the PC. The topology of the network is a tree with at most
  30. 127 nodes, counting both internal and leaf nodes.
  31. .PP
  32. The USB bus is fully controlled by the host; all devices are polled.
  33. Hubs are passive in the sense that they do not poll the devices attached
  34. to them. The host polls those devices and the hubs merely route the
  35. messages.
  36. .PP
  37. When a device is attached, the host queries it to determine its type
  38. and its speed. The querying process is standardized. The first level
  39. of querying is the same for all devices, the next is somewhat specialized
  40. for particular classes of devices (such as mice, keyboards, or audio devices).
  41. Specialization continues as subclasses and subsubclasses are explored.
  42. .PP
  43. For each connected device there is a directory in
  44. .BI #U/usb n\fR.
  45. Reading
  46. .BI #U/usb n /*/status
  47. yields the state, class/subclass/proto, vendor-id and product-id of each device in the
  48. first line. The remaining lines give the state of each of the
  49. interfaces.
  50. .PP
  51. To find a mouse, for example, scan the status files for the line beginning with
  52. .IP
  53. .EX
  54. .B "Enabled 0x020103"
  55. .EE
  56. .PP
  57. A mouse belongs to class 3 (in the least significant byte),
  58. .IR "human interface device" ,
  59. subclass 1,
  60. .IR boot ,
  61. proto 2,
  62. .I mouse
  63. (proto 1 would be the keyboard).
  64. USB class, subclass and proto codes can be found on
  65. .BR www.usb.org .
  66. .PP
  67. The control interface for each device is
  68. .I "``endpoint 0''"
  69. and is named
  70. .BI #U/usb n /*/setup \fR.
  71. The control interface of the device is accessed by reading and writing
  72. this file.
  73. .PP
  74. There is a separate
  75. .I "control interface
  76. named
  77. .BI #U/usb n /*/ctl
  78. which is used to configure the USB device
  79. .IR driver .
  80. By writing to this
  81. file, driver endpoints can be created and configured for communication with a
  82. device's data streams. A mouse, for example, has one control interface
  83. and one data interface. By communicating with the control interface,
  84. one can find out the device type (i.e., `mouse'), power consumption, number
  85. on interfaces, etc.
  86. .IR Usbd (4)
  87. will extract all this information and, in verbose mode, print it.
  88. .PP
  89. By sending an `endpoint message' to the
  90. .I ctl
  91. file, new driver endpoints can be created. The syntax of these messages
  92. is
  93. .IP
  94. .B ep
  95. .I n
  96. .B bulk
  97. .I "mode maxpkt nbuf
  98. .PP
  99. or
  100. .IP
  101. .B ep
  102. .I "n period mode samplesize hz
  103. .PP
  104. The first form configures a non-real-time stream, the second an
  105. .I isochronous
  106. (real-time) stream.
  107. In both forms,
  108. .I n
  109. is the endpoint to be configured, and
  110. .I mode
  111. is
  112. .B r
  113. for read only,
  114. .B w
  115. for write only, or
  116. .B rw
  117. for reading and writing.
  118. In the first form,
  119. .I maxpkt
  120. is the maximum packet size to be used (between 8 and 1023),
  121. and
  122. .I nbuf
  123. is the number of buffers to be allocated by the driver.
  124. .PP
  125. In the second form,
  126. .I period
  127. is the number of milliseconds between packets. This number is usually
  128. dictated by the device. It must be between 1 and 1000.
  129. The
  130. .I samplesize
  131. is the size in bytes of the data units making up packets, and
  132. .I hz
  133. is the number of data units transmitted or received per second.
  134. .PP
  135. The data rate is thus
  136. .IR hz × samplesize
  137. bytes per second, and the number of samples in a packet
  138. will be
  139. .RI ( period × hz )/1000,
  140. rounded up or down.
  141. Packets do not contain fractional samples.
  142. .PP
  143. The mouse, which produces 3-byte samples, is configured with
  144. .BR "ep 1 bulk r 3 32" :
  145. endpoint 1 is configured for non-real-time read-only 3-byte messages
  146. and allows 32 of them to be outstanding.
  147. .PP
  148. A usb audio output device at 44.1 KHz, 2 channels, 16-bit samples, on endpoint
  149. 4 will be configured with
  150. .BR "ep 4 1 w 4 44100" .
  151. .PP
  152. If the configuration is successful, a file named
  153. .BI ep n data
  154. is created which can be read and/or written depending on
  155. configuration. Configuration is not allowed when the data endpoint
  156. is open.
  157. .PP
  158. Forward
  159. .I seek
  160. operations on isochronous endpoints
  161. can be used to start the I/O at a specific time.
  162. The usb status file provides information that can be used to map file
  163. offsets to points in time: For each endpoint, the status file produces a line
  164. of the form:
  165. .IP
  166. .B "4 0x000201 \f2nnn\fP bytes \f2nnn\fP blocks
  167. .PP
  168. The fields are, from left to right,
  169. endpoint number, class/subclass/proto (as a six-digit hex number with class in the
  170. least significant byte), number of bytes read/written, number of blocks read/written.
  171. .PP
  172. For isochronous devices only, an additional line is produced of the
  173. form:
  174. .IP
  175. .B "bufsize \f2s\fP buffered \f2b\fP offset \f2o\fP time \f2t\fP
  176. .PP
  177. .I S
  178. is the size of the DMA operations on the device (i.e., the minimum useful size
  179. for reads and writes),
  180. .I b
  181. is the number of bytes currently buffered for input or output, and
  182. .I o
  183. and
  184. .I t
  185. should be interpreted to mean that byte offset
  186. .I o
  187. was/will be reached at time
  188. .I t
  189. (nanoseconds since the epoch).
  190. .PP
  191. To play or record samples exactly at some predetermined time, use
  192. .I o
  193. and
  194. .I t
  195. with the sampling rate to calculate the offset to seek to.
  196. .PP
  197. The number of bytes buffered can also be obtained using
  198. .IR stat (2)
  199. on the endpoint file. See also
  200. .IR audio (3).
  201. .SH FILES
  202. .TF "#U/usb n /*/status"
  203. .TP
  204. .BI #U/usb n /port
  205. USB port status file; for each port, space separated: port number, hexadecimal port status, port status string
  206. .TP
  207. .BI #U/usb n /*/status
  208. USB device status file; class/subclass/proto, vendor-id and product-id are found in line one
  209. .TP
  210. .BI #U/usb n /*/ctl
  211. USB
  212. .I driver
  213. control file, used to create driver endpoints, control debugging, etc.
  214. .TP
  215. .BI #U/usb n /*/setup
  216. USB
  217. .I device
  218. control file, used to exchange messages with a device's control channel.
  219. .B setup
  220. may be viewed as a preconfigured
  221. .B ep0data
  222. file.
  223. .TP
  224. .BI #U/usb n /*/ep k data
  225. USB device data channel for the
  226. .IR k 'th
  227. configuration.
  228. .SH SOURCE
  229. .B /sys/src/9/pc/usb.h
  230. .br
  231. .B /sys/src/9/pc/devusb.c
  232. .br
  233. .B /sys/src/9/pc/usbuhci.c
  234. .SH "SEE ALSO"
  235. .IR usb (4),
  236. .IR usbd (4),
  237. .IR plan9.ini (8)
  238. .SH BUGS
  239. OpenHCI (OHCI) and EHCI USB controllers are not yet supported.
  240. .PP
  241. The interface for configuring endpoints is at variance with the standard.
  242. .PP
  243. The notion that the endpoints themselves have a class and subclass
  244. is a distortion of the standard.
  245. It would be better to leave all handling of the notions of class to the
  246. user-level support programs, and remove it from the driver.
  247. .PP
  248. There may be a timing bug that makes disk accesses via UHCI much
  249. slower than necessary.