USB(4)                                                     USB(4)

     NAME
          audio, ccid, disk, ether, kb, print, probe, serial,
          usbeject, usbfat: - Universal Serial Bus device drivers

     SYNOPSIS
          usb/kb [ -dkm ] [ -a accel ] [ dev ... ]

          usb/disk [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]

          usbfat: [ disk ... ]

          usbeject [ disk ... ]

          usb/audio [ -dpV ] [ -m mnt ] [ -s srv ] [ -v vol ] [ dev ]

          usb/ether [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]

          usb/serial [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]

          usb/print [ -d ] [ dev ... ]

          usb/ccid [ -d ] usb/probe

     DESCRIPTION
          These programs drive USB devices of specific classes via
          usb(3). Usually they are started by usbd(4) upon attachment
          of the device to the bus.  Less often, users start them man-
          ually, depending on usbd(4)'s configuration.  Usually, kb
          and disk are started by usbd and other programs are started
          by hand.

          Without arguments, the drivers handle all the devices (of
          the appropriate USB class) found on the bus.  To make a
          driver handle only certain devices, supply as arguments the
          paths for the directories of the devices (actually of their
          zero endpoints).

          Drivers that provide file systems accept options -s and -m
          to instruct them to post a 9P connection at srv(3) with the
          given name and/or to mount themselves at mnt. When embedded
          into usbd these options may not be used.  In this case, the
          file tree supplied by the device driver is available through
          the file system provided by usbd, usually mounted at /dev
          and reachable through the 9P connection posted at /srv/usb.

          Options -d and -D present on most drivers trigger debug
          diagnostics and file system debugging diagnostics.  Repeat-
          ing any one of these may increase verbosity.

          To help locate devices of interest, probe lists all the USB

     USB(4)                                                     USB(4)

          devices available, including those with no driver started.

        Keyboards and mice
          Kb supports USB keyboards and mice either as separate USB
          devices or as a single combined USB device.  Scan codes from
          the keyboard are sent to /dev/kbin to let the kernel process
          them.  Mouse events are sent to /dev/mousein in the same
          way.

          The following options are understood:

          -a  Accelerate the mouse to level n (similar to the kernel
              mouse driver acceleration).
          -k  Serve just the keyboard (and not the mouse).
          -m  Serve just the mouse (and not the keyboard).

        Disks
          Disk configures and manages USB mass storage devices. It
          provides a file system (usually seen at /dev) that includes
          one directory per storage device, named sdUN.M in correspon-
          dence with the usb device number and the storage unit number
          (or LUN).  For example, LUN number 2 on /dev/usb/ep3.0 can
          be accessed through /dev/sdU3.2.

          The storage device directory contains the usual files served
          by sd(3): data, raw, and ctl.

          The ctl file supplies the device geometry when read.

          The script usbfat: mounts the FAT file systems in the DOS
          partitions of the named disks; if none, it mounts those file
          systems found at /dev/sdU*.*/data.  When more than one par-
          tition is found, a suffix is appended to the disk name to
          identify the partition number.  The script usbeject undoes
          the effect. If no argument is given, it unmounts all USB
          disks. An argument sdUN unmounts all partitions from disk
          with USB target N.

        Printers
          Print provides a single file can be written to print on a
          USB printer.  Options are similar to those of disk. The file
          is also bound at /dev/lp as is customary.

        Ethernet adapters
          Ether provides a file interface similar to that of ether(3)
          for each USB Ethernet adapter found.  The name of an Ether-
          net device is etherUN where N is the device name.  When
          started manually, the file interface is mounted at /net as
          is customary.

        Serial and JTAG ports
          Serial provides a file system (usually mounted at /dev) that

     USB(4)                                                     USB(4)

          includes one directory per USB serial port, named eiaUN or
          eiaUN.M.  In this directory there are two files, eiaU, simi-
          lar to eiaN in uart(3), and eiaUctl, which admits writes in
          the same format as eiaNctl in uart(3). Reading from eiaUctl
          gives the serial port's settings in the same format as
          eiaNstatus in uart(3). Options are similar to those of disk.

          JTAG ports are similar but the files are named jtag and
          jtagctl.

        Audio devices
          Usbaudio configures and manages a USB audio device.  It
          implements a file system, normally mounted on /dev, but this
          can be changed with -m, containing files volume, audioctl,
          audio, and audioin.  The names volume and audio maintain
          backward compatibility with the Soundblaster driver.

          The -V option (verbose) causes audio to print information
          about the device on startup.  The -s option specifies a name
          for a file descriptor to be posted in /srv.  The -v options
          sets initial volume.

          Reading volume or audioctl yields the device's settings.
          The data format of volume is compatible with the Sound-
          blaster and produces output in this format:

               audio out 65
               treb out 0
               bass out 0
               speed out 44100

          This file can be written using the same syntax.  The keyword
          `out' may be omitted.  Settings are given as percentages of
          the range, except for speed which is in Hz.

          The file audioctl provides more information, using up to 6
          columns of 12 characters each.  From left to right, the
          fields are: control name, in or out, current value, minimum
          value, maximum, and resolution. There are 3, 5, or 6 columns
          present.  Maxima and resolution are omitted when they are
          not available or not applicable.  The resolution for speed
          is reported as 1 (one) if the sampling frequency is continu-
          ously variable.  It is absent if it is settable at a fixed
          number of discrete values only.

          When all values from audioctl have been read, a zero-length
          buffer is returned (the usual end-of-file indication).  A
          new read will then block until one of the settings changes,
          then report its new value.

          The file audioctl can be written like volume.

     USB(4)                                                     USB(4)

          Audio data is written to audio and read from audioin.  The
          data format is little-endian, samples ordered primarily by
          time and secondarily by channel.  Samples occupy the minimum
          integral number of bytes.  Read and write operations of
          arbitrary size are allowed.

        Ccid
          Ccid discovers and configures SIM or SAM cards using the
          CCID standard.  It provides a file system (usually mounted
          at /dev) that includes three files, ctl, raw and rpc.  Read-
          ing from ctl a description of the smartcard reader capabili-
          ties is printed.  raw is just intended for debugging.  Reads
          and writes to the raw file send and receive raw CCID pack-
          ets.  Smart cards identify themselves by giving out an ATR,
          an array of characters describing the card uniquely.  Users
          of the driver write the ATR to the rpc file and are blocked
          until a card with that ATR is seen.  From then on they can
          do ICC RPCs using whatever language the smart card speaks. A
          small write cancels an outstanding RPC.

          The driver takes care of powering the card adequately, based
          on its ATR, and tunnelling the RPCs through the USB device.
          Only slot 0 is supported.

          When the smartcard disappears, all reads and write fail
          until the file is reopened and a new ATR is written to it.

     SOURCE
          /sys/src/cmd/usb

     SEE ALSO
          kbin(3), mouse(3), sd(3), uart(3), usb(3), usbd(4),
          partfs(8)

     BUGS
          The various device drivers are generic USB drivers and may
          work only for certain devices on each class.

          USB ATA storage devices are not supported.

          The Ethernet device works only for certain ASIX-based cards
          and for CDC devices.  Both the Ethernet and printer drivers
          have not been tested and it is likely they will fail.

          The serial driver works only for the Prolific chip and Ftdi,
          and control of the dcd and dsr signals and some of the extra
          features are unimplemented.  For Ftdi, only the Sheevaplug
          and Guruplug have been tried.  There is support for the EHCI
          debug port, but it loses bytes.