usb man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

USB(3)									USB(3)

delim $$

       usb - USB Host Controller Interface

       bind -a #u /dev


       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
       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).  Specialization continues as subclasses and subsubclasses are

       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

       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:

	      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

	      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).

	      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.

       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‐

       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.

       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
       information that can be used to locate a	 particular  device  (or  end‐
       point).	It also accepts writes with textual control requests described

       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
	      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

       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 endpoints.
	      This value determines how often I/O happens.  Note that the con‐
	      trol  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).

	      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
	      example, a mouse and keyboard combo may  identify	 itself	 as  a
	      keyboard	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

   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
	      remove its file interface as soon as no process is  using	 their

       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
	      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  interval
	      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

       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.

	      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.

	      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‐

       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.

       #u/usb root of the USB interface


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

       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.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net