1 |
.\" $NetBSD: ugen.4,v 1.13 2001/09/11 22:52:54 wiz Exp $ |
2 |
.\" |
3 |
.\" Copyright (c) 1999 The NetBSD Foundation, Inc. |
4 |
.\" All rights reserved. |
5 |
.\" |
6 |
.\" This code is derived from software contributed to The NetBSD Foundation |
7 |
.\" by Lennart Augustsson. |
8 |
.\" |
9 |
.\" Redistribution and use in source and binary forms, with or without |
10 |
.\" modification, are permitted provided that the following conditions |
11 |
.\" are met: |
12 |
.\" 1. Redistributions of source code must retain the above copyright |
13 |
.\" notice, this list of conditions and the following disclaimer. |
14 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
15 |
.\" notice, this list of conditions and the following disclaimer in the |
16 |
.\" documentation and/or other materials provided with the distribution. |
17 |
.\" 3. All advertising materials mentioning features or use of this software |
18 |
.\" must display the following acknowledgement: |
19 |
.\" This product includes software developed by the NetBSD |
20 |
.\" Foundation, Inc. and its contributors. |
21 |
.\" 4. Neither the name of The NetBSD Foundation nor the names of its |
22 |
.\" contributors may be used to endorse or promote products derived |
23 |
.\" from this software without specific prior written permission. |
24 |
.\" |
25 |
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS |
26 |
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED |
27 |
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
28 |
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS |
29 |
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
30 |
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
31 |
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
32 |
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
33 |
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
34 |
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
35 |
.\" POSSIBILITY OF SUCH DAMAGE. |
36 |
.\" |
37 |
.\" $FreeBSD: src/share/man/man4/ugen.4,v 1.6 2006/11/22 21:30:02 brueffer Exp $ |
38 |
.\" |
39 |
.Dd November 22, 2006 |
40 |
.Dt UGEN 4 |
41 |
.Os |
42 |
.Sh NAME |
43 |
.Nm ugen |
44 |
.Nd USB generic device support |
45 |
.Sh SYNOPSIS |
46 |
To compile this driver into the kernel, |
47 |
place the following line in your |
48 |
kernel configuration file: |
49 |
.Bd -ragged -offset indent |
50 |
.Cd "device ugen" |
51 |
.Ed |
52 |
.Pp |
53 |
Alternatively, to load the driver as a |
54 |
module at boot time, place the following line in |
55 |
.Xr loader.conf 5 : |
56 |
.Bd -literal -offset indent |
57 |
ugen_load="YES" |
58 |
.Ed |
59 |
.Sh DESCRIPTION |
60 |
The |
61 |
.Nm |
62 |
driver provides support for all USB devices that do not have |
63 |
a special driver. |
64 |
It supports access to all parts of the device, |
65 |
but not in a way that is as convenient as a special purpose driver. |
66 |
.Pp |
67 |
There can be up to 127 USB devices connected to a USB bus. |
68 |
Each USB device can have up to 16 endpoints. |
69 |
Each of these endpoints |
70 |
will communicate in one of four different modes: control, isochronous, |
71 |
bulk, or interrupt. |
72 |
Each of the endpoints will have a different |
73 |
device node. |
74 |
The four least significant bits in the minor device |
75 |
number determines which endpoint the device accesses and the rest |
76 |
of the bits determines which USB device. |
77 |
.Pp |
78 |
If an endpoint address is used both for input and output the device |
79 |
can be opened for both read or write. |
80 |
.Pp |
81 |
To find out what endpoints that exist there are a series of |
82 |
.Xr ioctl 2 |
83 |
operation on the control endpoint that returns the USB descriptors |
84 |
of the device, configurations, interfaces, and endpoints. |
85 |
.Pp |
86 |
The control transfer mode can only happen on the control endpoint |
87 |
which is always endpoint 0. |
88 |
The control endpoint accepts request |
89 |
and may respond with an answer to such request. |
90 |
Control request |
91 |
are issued by |
92 |
.Xr ioctl 2 |
93 |
calls. |
94 |
.\" .Pp |
95 |
.\" The isochronous transfer mode can be in or out depending on the |
96 |
.\" endpoint. |
97 |
.\" To perform I/O on an isochronous endpoint |
98 |
.\" .Xr read 2 |
99 |
.\" and |
100 |
.\" .Xr write 2 |
101 |
.\" should be used. |
102 |
.\" Before any I/O operations can take place the transfer rate in |
103 |
.\" bytes/second has to be set. |
104 |
.\" This is done with |
105 |
.\" .Xr ioctl 2 |
106 |
.\" .Dv USB_SET_ISO_RATE . |
107 |
.\" Performing this call sets up a buffer corresponding to |
108 |
.\" about 1 second of data. |
109 |
.Pp |
110 |
The bulk transfer mode can be in or out depending on the |
111 |
endpoint. |
112 |
To perform I/O on a bulk endpoint |
113 |
.Xr read 2 |
114 |
and |
115 |
.Xr write 2 |
116 |
should be used. |
117 |
All I/O operations on a bulk endpoint are unbuffered. |
118 |
.Pp |
119 |
The interrupt transfer mode can be in or out depending on the |
120 |
endpoint. |
121 |
To perform I/O on an interrupt endpoint |
122 |
.Xr read 2 |
123 |
and |
124 |
.Xr write 2 |
125 |
should be used. |
126 |
A moderate amount of buffering is done |
127 |
by the driver. |
128 |
.Pp |
129 |
All endpoints handle the following |
130 |
.Xr ioctl 2 |
131 |
calls: |
132 |
.Bl -tag -width indent |
133 |
.It Dv USB_SET_SHORT_XFER Pq Vt int |
134 |
Allow short read transfer. |
135 |
Normally a transfer from the device |
136 |
which is shorter than the request specified is reported as an |
137 |
error. |
138 |
.It Dv USB_SET_TIMEOUT Pq Vt int |
139 |
Set the timeout on the device operations, the time is specified |
140 |
in milliseconds. |
141 |
The value 0 is used to indicate that there is |
142 |
no timeout. |
143 |
.El |
144 |
.Pp |
145 |
The control endpoint (endpoint 0) handles the following |
146 |
.Xr ioctl 2 |
147 |
calls: |
148 |
.Bl -tag -width indent |
149 |
.It Dv USB_GET_CONFIG Pq Vt int |
150 |
Get the device configuration number. |
151 |
.It Dv USB_SET_CONFIG Pq Vt int |
152 |
Set the device into the given configuration number. |
153 |
.Pp |
154 |
This operation can only be performed when the control endpoint |
155 |
is the sole open endpoint. |
156 |
.It Dv USB_GET_ALTINTERFACE Pq Vt "struct usb_alt_interface" |
157 |
Get the alternative setting number for the interface with the given |
158 |
index. |
159 |
The |
160 |
.Va uai_config_index |
161 |
is ignored in this call. |
162 |
.Bd -literal |
163 |
struct usb_alt_interface { |
164 |
int uai_config_index; |
165 |
int uai_interface_index; |
166 |
int uai_alt_no; |
167 |
}; |
168 |
.Ed |
169 |
.It Dv USB_SET_ALTINTERFACE Pq Vt "struct usb_alt_interface" |
170 |
Set the alternative setting to the given number in the interface with the |
171 |
given index. |
172 |
The |
173 |
.Va uai_config_index |
174 |
is ignored in this call. |
175 |
.Pp |
176 |
This operation can only be performed when no endpoints for the interface |
177 |
are open. |
178 |
.It Dv USB_GET_NO_ALT Pq Vt "struct usb_alt_interface" |
179 |
Return the number of different alternate settings in the |
180 |
.Va uai_alt_no |
181 |
field. |
182 |
.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t |
183 |
Return the device descriptor. |
184 |
.It Dv USB_GET_CONFIG_DESC Pq Vt "struct usb_config_desc" |
185 |
Return the descriptor for the configuration with the given index. |
186 |
For convenience the current configuration can be specified by |
187 |
.Dv USB_CURRENT_CONFIG_INDEX . |
188 |
.Bd -literal |
189 |
struct usb_config_desc { |
190 |
int ucd_config_index; |
191 |
usb_config_descriptor_t ucd_desc; |
192 |
}; |
193 |
.Ed |
194 |
.It Dv USB_GET_INTERFACE_DESC Pq Vt "struct usb_interface_desc" |
195 |
Return the interface descriptor for an interface specified by its |
196 |
configuration index, interface index, and alternative index. |
197 |
For convenience the current alternative can be specified by |
198 |
.Dv USB_CURRENT_ALT_INDEX . |
199 |
.Bd -literal |
200 |
struct usb_interface_desc { |
201 |
int uid_config_index; |
202 |
int uid_interface_index; |
203 |
int uid_alt_index; |
204 |
usb_interface_descriptor_t uid_desc; |
205 |
}; |
206 |
.Ed |
207 |
.It Dv USB_GET_ENDPOINT_DESC Pq Vt "struct usb_endpoint_desc" |
208 |
Return the endpoint descriptor for the endpoint specified by its |
209 |
configuration index, interface index, alternative index, and |
210 |
endpoint index. |
211 |
.Bd -literal |
212 |
struct usb_endpoint_desc { |
213 |
int ued_config_index; |
214 |
int ued_interface_index; |
215 |
int ued_alt_index; |
216 |
int ued_endpoint_index; |
217 |
usb_endpoint_descriptor_t ued_desc; |
218 |
}; |
219 |
.Ed |
220 |
.It Dv USB_GET_FULL_DESC Pq Vt "struct usb_full_desc" |
221 |
Return all the descriptors for the given configuration. |
222 |
.Bd -literal |
223 |
struct usb_full_desc { |
224 |
int ufd_config_index; |
225 |
u_int ufd_size; |
226 |
u_char *ufd_data; |
227 |
}; |
228 |
.Ed |
229 |
The |
230 |
.Va ufd_data |
231 |
field should point to a memory area of the size given in the |
232 |
.Va ufd_size |
233 |
field. |
234 |
The proper size can be determined by first issuing a |
235 |
.Dv USB_GET_CONFIG_DESC |
236 |
and inspecting the |
237 |
.Va wTotalLength |
238 |
field. |
239 |
.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc" |
240 |
Get a string descriptor for the given language ID and |
241 |
string index. |
242 |
.Bd -literal |
243 |
struct usb_string_desc { |
244 |
int usd_string_index; |
245 |
int usd_language_id; |
246 |
usb_string_descriptor_t usd_desc; |
247 |
}; |
248 |
.Ed |
249 |
.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request" |
250 |
Send a USB request to the device on the control endpoint. |
251 |
Any data sent to/from the device is located at |
252 |
.Va ucr_data . |
253 |
The size of the transferred data is determined from the |
254 |
.Va ucr_request . |
255 |
The |
256 |
.Va ucr_addr |
257 |
field is ignored in this call. |
258 |
The |
259 |
.Va ucr_flags |
260 |
field can be used to flag that the request is allowed to |
261 |
be shorter than the requested size, and the |
262 |
.Va ucr_actlen |
263 |
will contain the actual size on completion. |
264 |
.Bd -literal |
265 |
struct usb_ctl_request { |
266 |
int ucr_addr; |
267 |
usb_device_request_t ucr_request; |
268 |
void *ucr_data; |
269 |
int ucr_flags; |
270 |
#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ |
271 |
int ucr_actlen; /* actual length transferred */ |
272 |
}; |
273 |
.Ed |
274 |
This is a dangerous operation in that it can perform arbitrary operations |
275 |
on the device. |
276 |
Some of the most dangerous (e.g., changing the device |
277 |
address) are not allowed. |
278 |
.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info" |
279 |
Get an information summary for the device. |
280 |
This call will not |
281 |
issue any USB transactions. |
282 |
.El |
283 |
.Pp |
284 |
Note that there are two different ways of addressing configurations, interfaces, |
285 |
alternatives, and endpoints: by index or by number. |
286 |
The index is the ordinal number (starting from 0) of the descriptor |
287 |
as presented by the device. |
288 |
The number is the respective number of |
289 |
the entity as found in its descriptor. |
290 |
Enumeration of descriptors |
291 |
use the index, getting and setting typically uses numbers. |
292 |
.Pp |
293 |
Example: |
294 |
all endpoints (except the control endpoint) for the current configuration |
295 |
can be found by iterating the |
296 |
.Va interface_index |
297 |
from 0 to |
298 |
.Va config_desc->bNumInterface Ns \-1 |
299 |
and for each of these iterating the |
300 |
.Va endpoint_index |
301 |
from 0 to |
302 |
.Va interface_desc->bNumEndpoints . |
303 |
The |
304 |
.Va config_index |
305 |
should set to |
306 |
.Dv USB_CURRENT_CONFIG_INDEX |
307 |
and |
308 |
.Va alt_index |
309 |
should be set to |
310 |
.Dv USB_CURRENT_ALT_INDEX . |
311 |
.Sh FILES |
312 |
.Bl -tag -width ".Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE" -compact |
313 |
.It Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE |
314 |
Endpoint |
315 |
.Ar EE |
316 |
of device |
317 |
.Ar N . |
318 |
.El |
319 |
.Sh SEE ALSO |
320 |
.Xr usb 4 |
321 |
.Sh HISTORY |
322 |
The |
323 |
.Nm |
324 |
driver |
325 |
appeared in |
326 |
.Nx 1.4 . |
327 |
.\" .Sh BUGS |
328 |
.\" The driver is not yet finished; there is no access to isochronous endpoints. |