sys/man/4/usbd

   1 .TH USBD 4
   2 .SH NAME
   3 usbd \- Universal Serial Bus daemon
   4 .SH SYNOPSIS
   5 .B usbd
   6 [
   7 .B -Dd
   8 ]
   9 [
  10 .B -s
  11 .I srv
  12 ]
  13 [
  14 .B -m
  15 .I mnt
  16 ]
  17 [
  18 .I hub...
  19 ]
  20 .SH DESCRIPTION
  21 .I Usbd
  22 complements
  23 .IR usb (3)
  24 to provide USB I/O for device drivers.
  25 It enumerates the bus, polling
  26 hub ports to detect device attachments and detachments, performs
  27 initial configuration of setup endpoints, and writes extra information into
  28 .IR usb (3)
  29 endpoint control files, to ease device location.
  30 .PP
  31 By default,
  32 .I usbd
  33 opens all setup endpoints found at
  34 .B #u/usb
  35 (which correspond to built-in hubs initialized by the kernel during boot).
  36 Paths to directories representing setup endpoints for hubs can be given
  37 as arguments to restrict
  38 .I usbd
  39 operation to such hubs.
  40 .PP
  41 When a device is attached,
  42 depending upon a configuration file compiled into
  43 .I usbd ,
  44 the appropriate device driver may be started without
  45 user intervention.
  46 This mechanism can be used to statically link some USB device drivers into
  47 .I usbd
  48 itself.
  49 Initial configuration for setup endpoints is performed independently
  50 of this configuration.
  51 .PP
  52 .I Usbd
  53 provides a file interface used to change debugging flags, and also used by
  54 USB device drivers statically linked into
  55 .IR usbd .
  56 By default, the file system is mounted (after) at
  57 .B /dev
  58 and a 9P connection is posted at
  59 .BR /srv/usb .
  60 .PP
  61 Besides files provided by device drivers, the file
  62 .B usbdctl
  63 is always present in the file interface.
  64 It accepts these control requests:
  65 .TF "fsdebug\fI n
  66 .TP
  67 .BI debug " n"
  68 Sets the debugging level to
  69 .IR n .
  70 .TP
  71 .BI fsdebug " n"
  72 Sets the file system debugging level to
  73 .IR n .
  74 .TP
  75 .B dump
  76 Prints the list of devices and file systems known by
  77 .IR usbd .
  78 .PD
  79 .PP
  80 .I Usbd
  81 recognizes the following options:
  82 .TF "-m\fI mnt
  83 .TP
  84 .B -d
  85 Print debugging diagnostics.
  86 Repeating the option increases verbosity.
  87 .TP
  88 .B -D
  89 Print debugging diagnostics for the file system interface.
  90 .TP
  91 .BI -m " mnt"
  92 Mount the served file system at
  93 .IR mnt .
  94 .TP
  95 .BI -s " srv"
  96 Post a 9P connection at
  97 .BI #s/ srv.
  98 .PD
  99 .SS Configuration
 100 .PP
 101 .I Usbd
 102 can be configured to start drivers for devices matching one or more CSPs
 103 (hex representation of USB class, subclass and protocol), class,
 104 subclass, protocol, vendor id, or device id.
 105 When a new device is attached,
 106 .I usbd
 107 scans the configuration and, if an entry matches the device descriptor, starts
 108 the driver.
 109 If no driver is configured, the setup endpoint for the device is left
 110 configured to let the user start the driver by hand.
 111 .PP
 112 Configuration is via compilation
 113 because one of the options is to embed (link) the driver into the
 114 .I usbd
 115 binary.
 116 If the driver is embedded,
 117 .I usbd
 118 creates a process for it and calls its main entry point.
 119 Otherwise,
 120 .I usbd
 121 tries to locate the driver binary in
 122 .B /bin/usb
 123 and creates a process to execute it.
 124 .PP
 125 The configuration file,
 126 .BR usbdb ,
 127 has two sections:
 128 .B embed
 129 and
 130 .BR auto .
 131 Each section includes lines to configure particular drivers.
 132 A driver may have more than one line if necessary.
 133 Each line includes the name of the
 134 driver (the base name of the binary) and one or more attributes of the form
 135 .IP
 136 .IR name = value
 137 .PP
 138 The following attributes exist:
 139 .TF subclass
 140 .TP
 141 .B class
 142 .I Value
 143 may be the name of the class
 144 or a number identifying the device class (using C syntax).
 145 The following class names are known:
 146 .BR audio ,
 147 .BR comms ,
 148 .BR hid ,
 149 .BR printer ,
 150 .BR storage ,
 151 .BR hub ,
 152 and
 153 .BR data .
 154 .TP
 155 .B subclass
 156 .I Value
 157 is the number of the device subclass.
 158 .TP
 159 .B proto
 160 .I Value
 161 is the number of the device protocol.
 162 .TP
 163 .B csp
 164 .I Value
 165 is the hexadecimal number describing the CSP for the device.
 166 .TP
 167 .B vid
 168 .I Value
 169 is the vendor id.
 170 .TP
 171 .B did
 172 .I Value
 173 is the device id.
 174 .TP
 175 .B args
 176 This must be the last field.
 177 The value is the rest of the line,
 178 and is supplied as arguments to the driver process.
 179 .PD
 180 .LP
 181 Several environment variables can be used to alter the behaviour of
 182 .IR usbd ,
 183 for example, for use in
 184 .IR plan9.ini (8).
 185 .B usbdebug
 186 sets a debug level (zero for no diagnostics and positive
 187 values for increasing verbosity).
 188 .B kbargs
 189 overrides the keyboard arguments as specified by the configuration file.
 190 .B diskargs
 191 overrides the disk arguments in the same way.
 192 .SH EXAMPLE
 193 This configuration file links
 194 .B usb/kb
 195 into
 196 .I usbd
 197 when it is compiled.
 198 It arranges for the driver's entry point,
 199 .B kbmain
 200 in this case,
 201 to be called for any device with CSPs matching either
 202 .B 0x010103
 203 or
 204 .BR 0x020103 .
 205 Option
 206 .B -d
 207 will be supplied as command line arguments for
 208 .BR kbmain .
 209 This configuration also arranges for
 210 .B /bin/usb/disk
 211 to start (with no arguments) whenever a device of class
 212 .B storage
 213 is attached.
 214 .IP
 215 .EX
 216 embed
 217         kb      csp=0x010103 csp=0x020103       args=-d
 218 auto
 219         disk    class=storage   args=
 220 .EE
 221 .SH FILES
 222 .TF /srv/usb
 223 .TP
 224 .B /srv/usb
 225 9P connection to the driver file system.
 226 .TP
 227 .B /dev
 228 mount point for the driver file system.
 229 .TP
 230 .B /sys/src/cmd/usb/usbd/usbdb
 231 Configuration file deciding which devices are included into
 232 .I usbd
 233 and which ones are started automatically.
 234 .SH SOURCE
 235 .B /sys/src/cmd/usb/usbd
 236 .SH "SEE ALSO"
 237 .IR usb (2),
 238 .IR usb (3),
 239 .IR usb (4)
 240 .SH BUGS
 241 .I Usbd
 242 is not supposed to be restarted.
 243 This is arguable.
 244 .PP
 245 Not heavily exercised yet.