407 lines
12 KiB
Groff
407 lines
12 KiB
Groff
.\" $NetBSD: ugen.4,v 1.27 2009/04/10 15:07:08 joerg Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Lennart Augustsson.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 19, 2008
|
|
.Dt UGEN 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ugen
|
|
.Nd USB generic device support
|
|
.Sh SYNOPSIS
|
|
.Cd "ugen* at uhub? flags N"
|
|
.Cd options UGEN_BULK_RA_WB
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for all USB devices that do not have
|
|
a special driver.
|
|
It supports access to all parts of the device,
|
|
but not in a way that is as convenient as a special purpose driver.
|
|
.Pp
|
|
Normally the
|
|
.Nm
|
|
driver is used when no other driver attaches to a device.
|
|
If
|
|
.Dq flags 1
|
|
is specified, the
|
|
.Nm
|
|
will instead attach with a very high priority and always be used.
|
|
Together with the
|
|
.Cd vendor
|
|
and
|
|
.Cd product
|
|
locators this can be used to force the
|
|
.Nm
|
|
driver to be used for a certain
|
|
device.
|
|
.Pp
|
|
There can be up to 127 USB devices connected to a USB bus.
|
|
Each USB device can have up to 16 endpoints.
|
|
Each of these endpoints will communicate in one of four different
|
|
modes: control, isochronous, bulk, or interrupt.
|
|
Each of the endpoints will have a different device node.
|
|
The four least significant bits in the minor device
|
|
number determines which endpoint the device accesses and the rest
|
|
of the bits determines which USB device.
|
|
.Pp
|
|
If an endpoint address is used both for input and output the device
|
|
can be opened for both read or write.
|
|
.Pp
|
|
To find out what endpoints exist there are a series of
|
|
.Xr ioctl 2
|
|
operations on the control endpoint that return the USB descriptors
|
|
of the device, configurations, interfaces, and endpoints.
|
|
.Pp
|
|
The control transfer mode can only happen on the control endpoint
|
|
which is always endpoint 0.
|
|
The control endpoint accepts requests
|
|
and may respond with an answer to such requests.
|
|
Control requests are issued by
|
|
.Xr ioctl 2
|
|
calls.
|
|
.\" .Pp
|
|
.\" The isochronous transfer mode can be in or out depending on the
|
|
.\" endpoint.
|
|
.\" To perform IO on an isochronous endpoint
|
|
.\" .Xr read 2
|
|
.\" and
|
|
.\" .Xr write 2
|
|
.\" should be used.
|
|
.\" Before any IO operations can take place the transfer rate in
|
|
.\" bytes/second has to be set.
|
|
.\" This is done with
|
|
.\" .Xr ioctl 2
|
|
.\" .Dv USB_SET_ISO_RATE .
|
|
.\" Performing this call sets up a buffer corresponding to
|
|
.\" about 1 second of data.
|
|
.Pp
|
|
The bulk transfer mode can be in or out depending on the
|
|
endpoint.
|
|
To perform IO on a bulk endpoint
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
should be used.
|
|
All IO operations on a bulk endpoint are normally unbuffered.
|
|
On kernels built with the
|
|
.Dv UGEN_BULK_RA_WB
|
|
option, the
|
|
.Dv USB_SET_BULK_RA
|
|
and
|
|
.Dv USB_SET_BULK_WB
|
|
.Xr ioctl 2
|
|
calls are available, and enable read-ahead and write-behind buffering
|
|
respectively.
|
|
When read-ahead or write-behind are enabled, the file descriptor
|
|
may be set to use non-blocking IO.
|
|
.Pp
|
|
When in a
|
|
.Dv UGEN_BULK_RA_WB
|
|
mode,
|
|
.Xr select 2
|
|
for read and write operates normally, returning true if there is data
|
|
in the read buffer and space in the write buffer, respectively.
|
|
When not in a
|
|
.Dv UGEN_BULK_RA_WB
|
|
mode,
|
|
.Xr select 2
|
|
always returns true, because there is no way to predict how the device
|
|
will respond to a read or write request.
|
|
.Pp
|
|
The interrupt transfer mode can be in or out depending on the
|
|
endpoint.
|
|
To perform IO on an interrupt endpoint
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
should be used.
|
|
A moderate amount of buffering is done
|
|
by the driver.
|
|
.Pp
|
|
All endpoints handle the following
|
|
.Xr ioctl 2
|
|
calls:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Dv USB_SET_SHORT_XFER (int)
|
|
Allow short read transfer.
|
|
Normally a transfer from the device which is shorter than the
|
|
request specified is reported as an error.
|
|
.It Dv USB_SET_TIMEOUT (int)
|
|
Set the timeout on the device operations, the time is specified
|
|
in milliseconds.
|
|
The value 0 is used to indicate that there is no timeout.
|
|
.El
|
|
.Pp
|
|
The control endpoint (endpoint 0) handles the following
|
|
.Xr ioctl 2
|
|
calls:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Dv USB_GET_CONFIG (int)
|
|
Get the device configuration number.
|
|
.It Dv USB_SET_CONFIG (int)
|
|
Set the device into the given configuration number.
|
|
.Pp
|
|
This operation can only be performed when the control endpoint
|
|
is the sole open endpoint.
|
|
.It Dv USB_GET_ALTINTERFACE (struct usb_alt_interface)
|
|
Get the alternative setting number for the interface with the given
|
|
index.
|
|
The
|
|
.Dv config_index
|
|
is ignored in this call.
|
|
.Bd -literal
|
|
struct usb_alt_interface {
|
|
int uai_config_index;
|
|
int uai_interface_index;
|
|
int uai_alt_no;
|
|
};
|
|
.Ed
|
|
.It Dv USB_SET_ALTINTERFACE (struct usb_alt_interface)
|
|
Set the alternative setting to the given number in the interface with the
|
|
given index.
|
|
The
|
|
.Dv uai_config_index
|
|
is ignored in this call.
|
|
.Pp
|
|
This operation can only be performed when no endpoints for the interface
|
|
are open.
|
|
.It Dv USB_GET_NO_ALT (struct usb_alt_interface)
|
|
Return the number of different alternate settings in the
|
|
.Dv aui_alt_no
|
|
field.
|
|
.It Dv USB_GET_DEVICE_DESC (usb_device_descriptor_t)
|
|
Return the device descriptor.
|
|
.It Dv USB_GET_CONFIG_DESC (struct usb_config_desc)
|
|
Return the descriptor for the configuration with the given index.
|
|
For convenience the current configuration can be specified by
|
|
.Dv USB_CURRENT_CONFIG_INDEX .
|
|
.Bd -literal
|
|
struct usb_config_desc {
|
|
int ucd_config_index;
|
|
usb_config_descriptor_t ucd_desc;
|
|
};
|
|
.Ed
|
|
.It Dv USB_GET_INTERFACE_DESC (struct usb_interface_desc)
|
|
Return the interface descriptor for an interface specified by its
|
|
configuration index, interface index, and alternative index.
|
|
For convenience the current alternative can be specified by
|
|
.Dv USB_CURRENT_ALT_INDEX .
|
|
.Bd -literal
|
|
struct usb_interface_desc {
|
|
int uid_config_index;
|
|
int uid_interface_index;
|
|
int uid_alt_index;
|
|
usb_interface_descriptor_t uid_desc;
|
|
};
|
|
.Ed
|
|
.It Dv USB_GET_ENDPOINT_DESC (struct usb_endpoint_desc)
|
|
Return the endpoint descriptor for the endpoint specified by its
|
|
configuration index, interface index, alternative index, and
|
|
endpoint index.
|
|
.Bd -literal
|
|
struct usb_endpoint_desc {
|
|
int ued_config_index;
|
|
int ued_interface_index;
|
|
int ued_alt_index;
|
|
int ued_endpoint_index;
|
|
usb_endpoint_descriptor_t ued_desc;
|
|
};
|
|
.Ed
|
|
.It Dv USB_GET_FULL_DESC (struct usb_full_desc)
|
|
Return all the descriptors for the given configuration.
|
|
.Bd -literal
|
|
struct usb_full_desc {
|
|
int ufd_config_index;
|
|
u_int ufd_size;
|
|
u_char *ufd_data;
|
|
};
|
|
.Ed
|
|
The
|
|
.Dv ufd_data
|
|
field should point to a memory area of the size given in the
|
|
.Dv ufd_size
|
|
field.
|
|
The proper size can be determined by first issuing a
|
|
.Dv USB_GET_CONFIG_DESC
|
|
and inspecting the
|
|
.Dv wTotalLength
|
|
field.
|
|
.It Dv USB_GET_STRING_DESC (struct usb_string_desc)
|
|
Get a string descriptor for the given language id and
|
|
string index.
|
|
.Bd -literal
|
|
struct usb_string_desc {
|
|
int usd_string_index;
|
|
int usd_language_id;
|
|
usb_string_descriptor_t usd_desc;
|
|
};
|
|
.Ed
|
|
.It Dv USB_DO_REQUEST
|
|
Send a USB request to the device on the control endpoint.
|
|
Any data sent to/from the device is located at
|
|
.Dv data .
|
|
The size of the transferred data is determined from the
|
|
.Dv request .
|
|
The
|
|
.Dv ucr_addr
|
|
field is ignored in this call.
|
|
The
|
|
.Dv ucr_flags
|
|
field can be used to flag that the request is allowed to
|
|
be shorter than the requested size, and the
|
|
.Dv ucr_actlen
|
|
field will contain the actual size on completion.
|
|
.Bd -literal
|
|
struct usb_ctl_request {
|
|
int ucr_addr;
|
|
usb_device_request_t ucr_request;
|
|
void *ucr_data;
|
|
int ucr_flags;
|
|
#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */
|
|
int ucr_actlen; /* actual length transferred */
|
|
};
|
|
.Ed
|
|
This is a dangerous operation in that it can perform arbitrary operations
|
|
on the device.
|
|
Some of the most dangerous (e.g., changing the device
|
|
address) are not allowed.
|
|
.It Dv USB_GET_DEVICEINFO (struct usb_device_info)
|
|
Get an information summary for the device.
|
|
This call will not issue any USB transactions.
|
|
.El
|
|
.Pp
|
|
Bulk endpoints handle the following
|
|
.Xr ioctl 2
|
|
calls:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Dv USB_SET_BULK_RA (int)
|
|
Enable or disable bulk read-ahead.
|
|
When enabled, the driver will begin to read data from the device into
|
|
a buffer, and will perform reads from the device whenever there is
|
|
room in the buffer.
|
|
The
|
|
.Xr read 2
|
|
call will read data from this buffer, blocking if necessary until
|
|
there is enough data to read the length of data requested.
|
|
The buffer size and the read request length can be set by the
|
|
.Dv USB_SET_BULK_RA_OPT
|
|
.Xr ioctl 2
|
|
call.
|
|
.It Dv USB_SET_BULK_WB (int)
|
|
Enable or disable bulk write-behind.
|
|
When enabled, the driver will buffer data from the
|
|
.Xr write 2
|
|
call before writing it to the device, enabling the
|
|
.Xr write 2
|
|
call to return immediately.
|
|
.Xr write 2
|
|
will block if there is not enough room in the buffer for all
|
|
the data.
|
|
The buffer size and the write request length can be set by the
|
|
.Dv USB_SET_BULK_WB_OPT
|
|
.Xr ioctl 2
|
|
call.
|
|
.It Dv USB_SET_BULK_RA_OPT (struct usb_bulk_ra_wb_opt)
|
|
Set the size of the buffer and the length of the read requests used by
|
|
the driver when bulk read-ahead is enabled.
|
|
The changes do not take
|
|
effect until the next time bulk read-ahead is enabled.
|
|
Read requests
|
|
are made for the length specified, and the host controller driver
|
|
(i.e.,
|
|
.Xr ehci 4 ,
|
|
.Xr ohci 4 ,
|
|
and
|
|
.Xr uhci 4 )
|
|
will perform as many bus transfers as required.
|
|
If transfers from the device should be smaller than the maximum length,
|
|
.Dv ra_wb_request_size
|
|
must be set to the required length.
|
|
.Bd -literal
|
|
struct usb_bulk_ra_wb_opt {
|
|
u_int ra_wb_buffer_size;
|
|
u_int ra_wb_request_size;
|
|
};
|
|
.Ed
|
|
.It Dv USB_SET_BULK_WB_OPT (struct usb_bulk_ra_wb_opt)
|
|
Set the size of the buffer and the length of the write requests used
|
|
by the driver when bulk write-behind is enabled.
|
|
The changes do not
|
|
take effect until the next time bulk write-behind is enabled.
|
|
.El
|
|
.Pp
|
|
Note that there are two different ways of addressing configurations, interfaces,
|
|
alternatives, and endpoints: by index or by number.
|
|
The index is the ordinal number (starting from 0) of the descriptor
|
|
as presented by the device.
|
|
The number is the respective number of
|
|
the entity as found in its descriptor.
|
|
Enumeration of descriptors
|
|
use the index, getting and setting typically uses numbers.
|
|
.Pp
|
|
Example:
|
|
All endpoints (except the control endpoint) for the current configuration
|
|
can be found by iterating the
|
|
.Dv interface_index
|
|
from 0 to
|
|
.Dv config_desc-\*[Gt]bNumInterface-1
|
|
and for each of these iterating the
|
|
.Dv endpoint_index
|
|
from 0 to
|
|
.Dv interface_desc-\*[Gt]bNumEndpoints .
|
|
The
|
|
.Dv config_index
|
|
should set to
|
|
.Dv USB_CURRENT_CONFIG_INDEX
|
|
and
|
|
.Dv alt_index
|
|
should be set to
|
|
.Dv USB_CURRENT_ALT_INDEX .
|
|
.Sh FILES
|
|
.Bl -tag -width Pa
|
|
.It Pa /dev/ugenN.EE
|
|
Endpoint
|
|
.Pa EE
|
|
of device
|
|
.Pa N .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr usb 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver
|
|
appeared in
|
|
.Nx 1.4 .
|
|
.\" .Sh BUGS
|
|
.\" The driver is not yet finished; there is no access to isochronous endpoints.
|