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