1
0

usb 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514
  1. .TH USB 4
  2. .SH NAME
  3. audio,
  4. ccid,
  5. disk,
  6. ether,
  7. kb,
  8. print,
  9. probe,
  10. serial,
  11. usbeject,
  12. usbfat:
  13. \- Universal Serial Bus device drivers
  14. .SH SYNOPSIS
  15. .B usb/kb
  16. [
  17. .B -dkm
  18. ] [
  19. .B -a
  20. .I accel
  21. ] [
  22. .I dev ...
  23. ]
  24. .PP
  25. .B usb/disk
  26. [
  27. .B -Dd
  28. ] [
  29. .B -m
  30. .I mnt
  31. ] [
  32. .B -s
  33. .I srv
  34. ] [
  35. .I dev ...
  36. ]
  37. .PP
  38. .B usbfat:
  39. [
  40. .I disk ...
  41. ]
  42. .PP
  43. .B usbeject
  44. [
  45. .I disk ...
  46. ]
  47. .PP
  48. .B usb/audio
  49. [
  50. .B -dpV
  51. ] [
  52. .B -m
  53. .I mnt
  54. ] [
  55. .B -s
  56. .I srv
  57. ] [
  58. .B -v
  59. .I vol
  60. ] [
  61. .I dev
  62. ]
  63. .PP
  64. .B usb/ether
  65. [
  66. .B -Dd
  67. ] [
  68. .B -m
  69. .I mnt
  70. ] [
  71. .B -s
  72. .I srv
  73. ] [
  74. .I dev ...
  75. ]
  76. .PP
  77. .B usb/serial
  78. [
  79. .B -Dd
  80. ] [
  81. .B -m
  82. .I mnt
  83. ] [
  84. .B -s
  85. .I srv
  86. ] [
  87. .I dev ...
  88. ]
  89. .PP
  90. .B usb/print
  91. [
  92. .B -d
  93. ] [
  94. .I dev ...
  95. ]
  96. .PP
  97. .B usb/ccid
  98. [
  99. .B -d
  100. ]
  101. .ig
  102. .PP
  103. .B usb/ibuddy
  104. [
  105. .B -Dd
  106. ] [
  107. .B -m
  108. .I mnt
  109. ] [
  110. .B -s
  111. .I srv
  112. ] [
  113. .I dev ...
  114. ]
  115. ..
  116. .B usb/probe
  117. .SH DESCRIPTION
  118. These programs drive USB devices of specific classes via
  119. .IR usb (3).
  120. Usually they are started by
  121. .IR usbd (4)
  122. upon attachment of the device to the bus.
  123. Less often, users start them manually, depending on
  124. .IR usbd (4)'s
  125. configuration.
  126. Usually,
  127. .I kb
  128. and
  129. .I disk
  130. are started by
  131. .I usbd
  132. and other programs are started by hand.
  133. .PP
  134. Without arguments, the drivers handle all the devices (of
  135. the appropriate USB class) found on the bus.
  136. To make a driver handle only certain devices, supply as arguments
  137. the paths for the directories of the devices
  138. (actually of their zero endpoints).
  139. .PP
  140. Drivers that provide file systems accept options
  141. .B -s
  142. and
  143. .B -m
  144. to instruct them to post a 9P connection at
  145. .IR srv (3)
  146. with the given name and/or to mount themselves at
  147. .IR mnt .
  148. When embedded into
  149. .IR usbd
  150. these options may not be used.
  151. In this case,
  152. the file tree supplied by the device driver is
  153. available through the file system provided by
  154. .IR usbd ,
  155. usually mounted at
  156. .B /dev
  157. and reachable through the 9P connection posted at
  158. .BR /srv/usb .
  159. .PP
  160. Options
  161. .B -d
  162. and
  163. .B -D
  164. present on most drivers trigger debug diagnostics and
  165. file system debugging diagnostics.
  166. Repeating any one of these may increase verbosity.
  167. .PP
  168. To help locate devices of interest,
  169. .I probe
  170. lists all the USB devices available,
  171. including those with no driver started.
  172. .SS Keyboards and mice
  173. .I Kb
  174. supports USB keyboards and mice either as separate USB devices
  175. or as a single combined USB device.
  176. Scan codes from the keyboard are sent to
  177. .B /dev/kbin
  178. to let the kernel process them.
  179. Mouse events are sent to
  180. .B /dev/mousein
  181. in the same way.
  182. .PP
  183. The following options are understood:
  184. .TF -k
  185. .TP
  186. .B \-a
  187. Accelerate the mouse to level
  188. .I n
  189. (similar to the kernel mouse driver acceleration).
  190. .TP
  191. .B \-k
  192. Serve just the keyboard (and not the mouse).
  193. .TP
  194. .B \-m
  195. Serve just the mouse (and not the keyboard).
  196. .SS Disks
  197. .I Disk
  198. configures and manages USB mass storage devices. It
  199. provides a file system (usually seen at
  200. .BR /dev )
  201. that includes one directory per storage device, named
  202. .BI sdU N . M
  203. in correspondence with the usb device number and the storage
  204. unit number (or LUN).
  205. For example, LUN number 2 on
  206. .B /dev/usb/ep3.0
  207. can be accessed through
  208. .BR /dev/sdU3.2 .
  209. .PP
  210. The storage device directory contains the usual files
  211. served by
  212. .IR sd (3):
  213. .BR data ,
  214. .BR raw ,
  215. and
  216. .BR ctl .
  217. .PP
  218. The
  219. .B ctl
  220. file supplies the device
  221. geometry when read.
  222. .PP
  223. The script
  224. .B usbfat:
  225. mounts the FAT file systems in the DOS partitions of the named
  226. .IR disk s;
  227. if none, it mounts those file systems found at
  228. .BR /dev/sdU*.*/data .
  229. When more than one partition is found, a suffix is appended to
  230. the disk name to identify the partition number.
  231. The script
  232. .B usbeject
  233. undoes the effect. If no argument is given, it unmounts all USB
  234. disks. An argument
  235. .BI sdU N
  236. unmounts all partitions from disk with USB target
  237. .IR N .
  238. .ig
  239. An argument
  240. .BI sdU N . M
  241. or
  242. .BI sdU N . M . P
  243. .\" TODO: fill in missing words
  244. ..
  245. .SS Printers
  246. .I Print
  247. provides a single file can be written to print on a USB printer.
  248. Options are similar to those of
  249. .IR disk .
  250. The file is also bound at
  251. .B /dev/lp
  252. as is customary.
  253. .SS Ethernet adapters
  254. .I Ether
  255. provides a file interface similar to that of
  256. .IR ether (3)
  257. for each USB Ethernet adapter found.
  258. The name of an Ethernet device is
  259. .BI etherU N
  260. where
  261. .I N
  262. is the device name.
  263. When started manually, the file interface is mounted at
  264. .B /net
  265. as is customary.
  266. .
  267. .SS Serial and JTAG ports
  268. .I Serial
  269. provides a file system (usually mounted at
  270. .BR /dev )
  271. that includes one directory per USB serial port, named
  272. .BI eiaU N
  273. or
  274. .BI eiaU N . M.
  275. In this directory there are two files,
  276. .BR eiaU ,
  277. similar to
  278. .BI eia N
  279. in
  280. .IR uart (3),
  281. and
  282. .BR eiaUctl ,
  283. which admits writes in the same format as
  284. .BI eia N ctl
  285. in
  286. .IR uart (3).
  287. Reading from
  288. .B eiaUctl
  289. gives the serial port's settings in the same format as
  290. .BI eia N status
  291. in
  292. .IR uart (3).
  293. Options are similar to those of
  294. .IR disk .
  295. .PP
  296. JTAG ports are similar
  297. but the files are named
  298. .B jtag
  299. and
  300. .BR jtagctl .
  301. .
  302. .SS Audio devices
  303. .I Usbaudio
  304. configures and manages a USB audio device.
  305. It implements a file system,
  306. normally mounted on
  307. .BI /dev ,
  308. but this can be changed with
  309. .BR \-m ,
  310. containing files
  311. .BR volume ,
  312. .BR audioctl ,
  313. .BR audio ,
  314. and
  315. .BR audioin .
  316. The names
  317. .B volume
  318. and
  319. .B audio
  320. maintain backward compatibility with the Soundblaster driver.
  321. .PP
  322. The
  323. .B \-V
  324. option (verbose)
  325. causes
  326. .I audio
  327. to print information about the device on startup.
  328. The
  329. .B \-s
  330. option specifies a name for a file descriptor to be posted in
  331. .BR /srv .
  332. The
  333. .B \-v
  334. options sets initial
  335. .IR volume .
  336. .PP
  337. Reading
  338. .B volume
  339. or
  340. .B audioctl
  341. yields the device's settings.
  342. The data format of
  343. .B volume
  344. is compatible with the Soundblaster and produces output in this
  345. format:
  346. .IP
  347. .EX
  348. audio out 65
  349. treb out 0
  350. bass out 0
  351. speed out 44100
  352. .EE
  353. .PP
  354. This file can be written using the same syntax.
  355. The keyword
  356. .L out
  357. may be omitted.
  358. Settings are given as percentages of the range,
  359. except for speed which is in Hz.
  360. .PP
  361. The file
  362. .B audioctl
  363. provides more information, using up to 6 columns of 12 characters each.
  364. From left to right, the fields are:
  365. .IR "control name" ,
  366. .I in
  367. or
  368. .IR out ,
  369. .IR "current value" ,
  370. .IR "minimum value" ,
  371. .IR maximum ,
  372. and
  373. .IR resolution .
  374. There are 3, 5, or 6 columns present.
  375. Maxima and resolution are omitted when they are not available or not applicable.
  376. The resolution for
  377. .I speed
  378. is reported as 1 (one) if the sampling frequency is continuously variable.
  379. It is absent if it is settable at a fixed number of discrete values only.
  380. .PP
  381. When all values from
  382. .B audioctl
  383. have been read, a zero-length buffer is returned
  384. (the usual end-of-file indication).
  385. A new
  386. .I read
  387. will then block until one of the settings changes,
  388. then report its new value.
  389. .PP
  390. The file
  391. .B audioctl
  392. can be written like
  393. .BR volume .
  394. .PP
  395. Audio data is written to
  396. .B audio
  397. and read from
  398. .BR audioin .
  399. The data format is little-endian,
  400. samples ordered primarily by time and
  401. secondarily by channel.
  402. Samples occupy the minimum integral number of bytes.
  403. Read and write operations of arbitrary size are allowed.
  404. .
  405. .SS Ccid
  406. .I Ccid
  407. discovers and configures SIM or SAM cards using the CCID standard.
  408. It provides a file system (usually mounted at
  409. .BR /dev )
  410. that includes three files,
  411. .BI ctl ,
  412. .B raw
  413. and
  414. .BI rpc .
  415. Reading from
  416. .B ctl
  417. a description of the smartcard reader capabilities is printed.
  418. .B raw
  419. is just intended for debugging.
  420. Reads and writes to the
  421. raw file send and receive raw CCID packets.
  422. Smart cards identify themselves by giving out an ATR,
  423. an array of characters describing the card uniquely.
  424. Users of the driver write the ATR to the
  425. .B rpc
  426. file and are blocked until a card with that ATR is seen.
  427. From then on they can do ICC RPCs using whatever
  428. language the smart card speaks. A small write cancels
  429. an outstanding RPC.
  430. .PP
  431. The driver takes care of powering the card adequately, based
  432. on its ATR, and tunnelling the RPCs through the USB device.
  433. Only slot 0 is supported.
  434. .PP
  435. When the smartcard disappears,
  436. all reads and write fail until the file is reopened and
  437. a new ATR is written to it.
  438. .
  439. .ig
  440. .SS Ibuddy
  441. .PP
  442. Ibuddy supports a USB I-buddy toy, a little winged-demon.
  443. The driver provides one directory per attached toy with a single
  444. .BR ctl
  445. file to control the device.
  446. Directories are named
  447. .BR ibuddyN ,
  448. being
  449. .I N
  450. the corresponding usb device number.
  451. When read, the
  452. .BR ctl
  453. file provides the state of the device in this form:
  454. .IP
  455. .EX
  456. hips right|left
  457. wings open|close
  458. red on|off
  459. green on|off
  460. blue on|off
  461. heart on|off
  462. .EE
  463. .PP
  464. Each line describes the status of one feature.
  465. .IR Red ,
  466. .IR blue ,
  467. and
  468. .IR green
  469. are the different leds in the head of
  470. the toy.
  471. .IR Heart
  472. represents the red led in the chest of
  473. the toy.
  474. .IR Wings
  475. represents the status of the wings, which
  476. can be closed or open.
  477. .IR Hips
  478. represents the orientation
  479. of the toy (left or right, from the figure's point of view).
  480. .PP
  481. Lines can be written to the
  482. .BR ctl
  483. file to command the device.
  484. Multiple lines (six at most) can be written
  485. at once, with one action per line.
  486. ..
  487. .SH SOURCE
  488. .B /sys/src/cmd/usb
  489. .SH "SEE ALSO"
  490. .IR kbin (3),
  491. .IR mouse (3),
  492. .IR sd (3),
  493. .IR uart (3),
  494. .IR usb (3),
  495. .IR usbd (4),
  496. .IR partfs (8)
  497. .SH BUGS
  498. The various device drivers are generic USB drivers and
  499. may work only for certain devices on each class.
  500. .PP
  501. USB ATA storage devices are not supported.
  502. .PP
  503. The Ethernet device works only for certain ASIX-based cards and for CDC devices.
  504. Both the Ethernet and printer drivers have not
  505. been tested and it is likely they will fail.
  506. .PP
  507. The serial driver works only for the Prolific chip and Ftdi,
  508. and control of the
  509. .B dcd
  510. and
  511. .B dsr
  512. signals and some of the extra features are unimplemented.
  513. For Ftdi, only the Sheevaplug and Guruplug have been tried.
  514. There is support for the EHCI debug port, but it loses bytes.