usb 6.8 KB

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