glenda.party
term% ls -F
term% cat index.txt
USB(3)                     Library Functions Manual                     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 controllers.
       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  at‐
       tached 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).  Specialization continues as subclasses and subsubclasses are
       explored.

       Enumeration of the bus and initial configuration of devices is done  by
       a user level program, usbd(4).  Device drivers are implemented by sepa‐
       rate user programs, although some of them 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 con‐
       figured 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 func‐
       tions 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.  Writing 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 manner (e.g., to write
              audio samples to a speaker).

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

   Operation
       Bus enumeration and device configuration is performed  by  usbd(4)  and
       not  by this driver.  The driver provides an interface to access exist‐
       ing 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 num‐
       ber identifying a device and M is a number identifying one of its  end‐
       points.

       For each device attached to the bus, and configured by usbd(4), an end‐
       point zero (a setup endpoint) is provided at /dev/usb/epN.0 for config‐
       uring the device.  This is always a control endpoint and represents the
       device itself.

       The device driver may use the setup endpoint to issue control  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  indi‐
       cating  that  the  number  of bytes transferred has been zero.  In most
       cases, the correct course of action after noticing the stall is for the
       device  driver  to issue a `clear halt' request (see unstall in usb(2))
       to resume I/O.  The most common error is indicating problems in  commu‐
       nication  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 control request).

   ctl and status
       The  ctl file can be read to learn about the endpoint.  It contains in‐
       formation 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
                   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(4) as an aid to locate devices.  The  status  informa‐
       tion 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 configured, 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 de‐
              tached state and no further I/O is accepted on it.  Files for an
              endpoint (including its directory) vanish when the device is de‐
              tached and its files are no longer open.  Root hubs may  not  be
              detached.

       Endpoint type
              control,  iso, interrupt, or bulk, indicating the type of trans‐
              fer supported by the endpoint.

       Endpoint mode
              One of r, w, or rw, depending on the direction 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  end‐
              points.  This value determines how often I/O happens.  Note that
              the control request adjusting the polling 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).

       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  while  the  data  file is open and otherwise.  This is useful to
              avoid disturbing 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 ex‐
              ample,  a mouse and keyboard combo may identify itself as a key‐
              board but then include two CSPs, one for the  keyboard  and  an‐
              other 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(4) or
       the usb driver library documented in usb(2).

       detach Prevent further I/O on the device (delete the endpoint) and  re‐
              move  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 de‐
              scriptor.  The interval value used is the period n in  bus  time
              units  for  low- and full-speed interrupt endpoints.  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 in‐
              terval value as found in the endpoint  descriptor.   The  kernel
              adjusts  the  value  according to the endpoint configuration 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(4)
              uses this to add device descriptions.

       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 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 integer; larger val‐
              ues make diagnostics more verbose.  stops debugging diagnostics.
              causes just problem reports.  Bigger values report almost every‐
              thing.

       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, 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 var‐
       ious  ctl  files  when read.  It accepts several requests that refer to
       the entire driver and not to particular 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/*/*usb?hci.h
       /sys/src/9/*/devusb.c
       /sys/src/9/*/usb?hci*.c

SEE ALSO
       usb(2), usb(4), usbd(4), plan9.ini(8)

BUGS
       USB controllers limit the speed of all their ports to that of the slow‐
       est 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.



                                                                        USB(3)