USB(3)                                                     USB(3)

              delim $$

     NAME
          usb - USB Host Controller Interface

     SYNOPSIS
          bind -a #u /dev

          /dev/usb
          /dev/usb/ctl
          /dev/usb/epN.M
          /dev/usb/epN.M/data
          /dev/usb/epN.M/ctl
          ...

     DESCRIPTION
          The Universal Serial Bus is a complex yet popular bus for
          connecting all kind of devices to a computer.  It is a
          four-wire tree-shaped bus that provides both communication
          and (limited) power to devices.  Branching points in the
          tree are provided by devices called hubs. Hubs provide ports
          where USB devices (also hubs) can be attached.

          Most PCs have one or more USB controllers called host con-
          trollers.  Each one has a built-in hub called a root hub
          providing several ports.  In some cases, more hubs are
          built-in and attached to a root hub port.  The topology of
          the network is a tree with at most 127 nodes, counting both
          internal and leaf nodes.

          Host controllers come in four flavours: UHCI and OHCI for
          USB 1 (up to 12 Mb/s), EHCI for USB 2 (up to 480 Mb/s) and
          XHCI for USB 3 (up to 5 Gb/s).  We currently support all but
          XHCI, which is still quite new.

          The USB bus is fully controlled by the host; all devices are
          polled.  Hubs are passive in the sense that they do not poll
          the devices attached to them.  The host polls those devices
          and the hubs merely route the messages.

          Devices may be added to or removed from the bus at any time.
          When a device is attached, the host queries it to determine
          its type and speed.  The querying process is standardized.
          The first level of querying is the same for all devices, the
          next is somewhat specialized for particular classes of
          devices (such as mice, keyboards, or audio devices).  Spe-
          cialization continues as subclasses and subsubclasses are
          explored.

          Enumeration of the bus and initial configuration of devices
          is done by a user level program, usbd. Device drivers are
          implemented by separate user programs, although some of them

     USB(3)                                                     USB(3)

          may be statically linked into usbd.

          The kernel device described in this page is responsible for
          providing I/O for using the devices through so called
          endpoints. Access to the host controller is hidden from user
          programs, which see just a set of endpoints.  After system
          initialization, some endpoints are created by the device to
          permit I/O to root hubs.  All other devices must be config-
          ured by usbd.

        Devices and Endpoints
          A device includes one or more functions (e.g., audio output,
          volume control buttons, mouse input, etc.)  Communication
          with device functions is performed by some combination of
          issuing control requests to, sending data to, and receiving
          data from device endpoints. Endpoints can be understood as
          addresses in the bus.  There are several types:

          Control      Their main use is to configure devices.  Writ-
                       ing a message with a specific format (specified
                       in the USB specification) issues a request to
                       the device.  If the request implies a reply, a
                       read can be made next to retrieve the requested
                       data (if the write succeeded).
          Interrupt    Used to send and receive messages to or from a
                       specific device function (e.g., to read events
                       from a mouse).
          Bulk         Used to send and receive larger amounts of data
                       through streams (e.g., to write blocks to a
                       disk).
          Isochronous  Used to send and receive data in a timely man-
                       ner (e.g., to write audio samples to a
                       speaker).

          All USB devices include at least a control endpoint to per-
          form device configuration.  This is called the setup end-
          point or endpoint zero. After configuring a device, other
          endpoints may be created as dictated by the device to per-
          form actual I/O.

        Operation
          Bus enumeration and device configuration is performed by
          usbd and not by this driver.  The driver provides an inter-
          face to access existing endpoints (initially those for the
          built-in root hubs), to create and configure other ones, and
          to perform I/O through them.

          Each directory /dev/usb/epN.M represents an endpoint, where
          N is a number identifying a device and M is a number identi-
          fying one of its endpoints.

          For each device attached to the bus, and configured by usbd,

     USB(3)                                                     USB(3)

          an endpoint zero (a setup endpoint) is provided at
          /dev/usb/epN.0 for configuring the device.  This is always a
          control endpoint and represents the device itself.

          The device driver may use the setup endpoint to issue con-
          trol requests and perhaps to create more endpoints for the
          device.  Each new endpoint created has its own directory as
          said above.  For example, if the driver for the device
          /dev/usb/epN.0 creates the endpoint number 3 for that
          device, a directory /dev/usb/epN.3 will be available to
          access that endpoint.

          All endpoint directories contain two files: data and ctl.
          The former has mode bit DMEXCL set and can be open by only
          one process at a time.

        data
          The data file is used to perform actual I/O.  In general,
          reading from it retrieves data from the endpoint and writing
          into it sends data to the endpoint.  For control endpoints,
          writing to this file issues a control request (which may
          include data); if the request retrieves data from the
          device, a following read on the file will provide such data.

          USB errors reported by the endpoint upon I/O failures are
          passed to the user process through the error string.  I/O
          stalls not resulting from an error, usually an indication
          from the device, are reported by indicating that the number
          of bytes transferred has been zero.  In most cases, the cor-
          rect course of action after noticing the stall is for the
          device driver to issue a `clear halt' request (see unstall
          in nusb(2)) to resume I/O.  The most common error is
          `crc/timeout' indicating problems in communication with the
          device (eg., a physical detach of the device or a wiring
          problem).

          For control and isochronous transfers, there is an implicit
          timeout performed by the kernel and it is not necessary for
          applications to place their own timers.  For other transfer
          types, the kernel will not time out any operation by default
          (but see the `timeout' control request).

        ctl and status
          The ctl file can be read to learn about the endpoint.  It
          contains information that can be used to locate a particular
          device (or endpoint).  It also accepts writes with textual
          control requests described later.

          This may result from the read of an endpoint control file:

               (the first line is wrapped to make it fit here)
               enabled control rw speed full maxpkt 64 pollival 0

     USB(3)                                                     USB(3)

                    samplesz 0 hz 0 hub 1 port 3 busy
               storage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II'

          The first line contains status information.  The rest is
          information supplied by usbd as an aid to locate devices.
          The status information includes:

          Device state   One of config, enabled, and detached.  An
                         endpoint starts in the config state, and
                         accepts control commands written to its ctl
                         file to configure the endpoint.  When config-
                         ured, the state is enabled and the data file
                         is used as described above (several control
                         requests can still be issued to its ctl file,
                         but most will not be accepted from now on).
                         Upon severe errors, perhaps a physical
                         detachment from the bus, the endpoint enters
                         the detached state and no further I/O is
                         accepted on it.  Files for an endpoint
                         (including its directory) vanish when the
                         device is detached and its files are no
                         longer open.  Root hubs may not be detached.

          Endpoint type  control, iso, interrupt, or bulk, indicating
                         the type of transfer supported by the end-
                         point.

          Endpoint mode  One of r, w, or rw, depending on the direc-
                         tion of the endpoint (in, out, or inout).

          Speed          low (1.5 Mb/s), full (12 Mb/s), or high (480
                         Mb/s).

          Maximum packet size
                         Used when performing I/O on the data file.

          Polling interval
                         The polling period expressed as a number of
                         µframes (for high-speed endpoints) or frames
                         (for low- and full-speed endpoints).  Note
                         that a µframe takes 125 µs while a frame
                         takes 1 ms.  This is only of relevance for
                         interrupt and isochronous endpoints.  This
                         value determines how often I/O happens.  Note
                         that the control request adjusting the pol-
                         ling interval does not use these units, to
                         make things easier for USB device drivers.

          Sample size    Number of bytes per I/O sample (isochronous
                         endpoints only).

     USB(3)                                                     USB(3)

          Frequency      Number of samples per second (Hertz).

          Hub address    Device address of the hub where the device is
                         attached.

          Port number    Port number (in the hub) where the device is
                         attached.

          Usage          `busy' while the data file is open and `idle'
                         otherwise.  This is useful to avoid disturb-
                         ing endpoints already run by a device driver.

          The second line contains information describing the device:

          Class name      As provided by the device itself.

          CSP             Class, Subclass, and Protocol for the
                          device.  If the device contains different
                          functions and has more CSPs, all of them
                          will be listed.  The first one is that of
                          the device itself.  For example, a mouse and
                          keyboard combo may identify itself as a key-
                          board but then include two CSPs, one for the
                          keyboard and another one for the mouse.

          Vid and Did     Vendor and device identifiers.

          Device strings  Provided by the device and identifying the
                          manufacturer and type of device.

          For example, to find a mouse not yet in use by a driver,
          scan the ctl files for enabled, idle, and csp 0x020103.  A
          mouse belongs to class 3 (in the least significant byte),
          human interface device, subclass 1, boot, protocol 2, mouse
          (protocol 1 would be the keyboard).  USB class, subclass and
          proto codes can be found at http://www.usb.org.

        Control requests
          Endpoint control files accept the following requests.  In
          most cases the driver does not issue them, leaving the task
          to either usbd or the usb driver library documented in
          nusb(2).

          detach      Prevent further I/O on the device (delete the
                      endpoint) and remove its file interface as soon
                      as no process is using their files.
          maxpkt n    Set the maximum packet size to n bytes.
          pollival n  Only for interrupt and isochronous endpoints.
                      Set the polling interval as a function of the
                      value n given by the endpoint descriptor.  The
                      interval value used is the period n in bus time

     USB(3)                                                     USB(3)

                      units for low- and full-speed interrupt end-
                      points.  Otherwise, the actual interval is $2
                      sup n$ and not n. Bus time units are 1 ms for
                      low- and full-speed endpoints and 125 µs for
                      high-speed endpoints.  In most cases, the device
                      driver may ignore all this and issue the control
                      request supplying the polling interval value as
                      found in the endpoint descriptor.  The kernel
                      adjusts the value according to the endpoint con-
                      figuration and converts it into the number of
                      frames or µframes between two consecutive polls.
          samplesz n  Use n as the number of bytes per sample.
          hz n        Use n as the number of samples per second.
          ntds n      Use n as the number of transactions per frame
                      (or µframe), as reported by the descriptor.
          clrhalt     Clear the halt condition for an endpoint.  Used
                      to recover from a stall caused by a device to
                      signal its driver (usually due to an unknown
                      request or a failure to complete one).
          info string Replaces description information in ctl with
                      string. Usbd uses this to add device descrip-
                      tions.
          address     Tell this driver that the device has been given
                      an address, which causes the device to enter the
                      enabled state.
          name str    Generates an additional file name, str , for the
                      data file of the endpoint.  This file name
                      appears in the root directory of the `#u' tree.
                      For example, this is used by the audio device
                      driver to make the data file also available as
                      /dev/audio.
          debug n     Enable debugging of the endpoint.  N is an inte-
                      ger; larger values make diagnostics more ver-
                      bose.  `0' stops debugging diagnostics.  `1'
                      causes just problem reports.  Bigger values
                      report almost everything.
          timeout n   Enable time-outs for the endpoint.  Transfers
                      are timed out by the kernel after n ms.  This
                      should not be used for control and isochronous
                      endpoints, which are always timed out.

          Setup endpoints (those represented by epN.0 directories)
          also accept the following requests:

          new n type mode
               Creates a new endpoint with number n of the given type
               (ctl, bulk, intr, or iso).  Mode may be r, w, or rw,
               which creates, respectively, an input, output, or
               input/output endpoint.

          speed {low|full|high}
               Set the endpoint speed to full, low, or high,

     USB(3)                                                     USB(3)

               respectively.

          hub  Tell this driver that the endpoint corresponds to a hub
               device.

          Setup endpoints for hub devices also accept his request:

          newdev {low|full|high} port
               Create a new setup endpoint to represent a new device.
               The first argument is the device speed.  Port is the
               port number where the device is attached (the hub is
               implied by the endpoint where the control request is
               issued).

          The file /dev/usb/ctl provides all the information provided
          by the various ctl files when read.  It accepts several
          requests that refer to the entire driver and not to particu-
          lar endpoints:

          debug n  Sets the global debug flag to n.
          dump     Dumps data structures for inspection.

     FILES
          #u/usb  root of the USB interface

     SOURCE
          /sys/src/9/port/usb.h
          /sys/src/9/port/devusb.c
          /sys/src/9/*/usb*.c

     SEE ALSO
          nusb(2), nusb(4), plan9.ini(8)

     BUGS
          USB controllers limit the speed of all their ports to that
          of the slowest device connected to any one of them.

          Isochronous input streams are not implemented for OHCI.

          Some EHCI controllers drop completion interrupts and so must
          be polled, which hurts throughput.