297 lines
9.4 KiB
Groff
297 lines
9.4 KiB
Groff
.\" $NetBSD: ugen.4,v 1.18 2004/10/04 19:12:52 rumble 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 December 15, 2003
|
|
.Dt UGEN 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ugen
|
|
.Nd USB generic device support
|
|
.Sh SYNOPSIS
|
|
.Cd "ugen* at uhub?"
|
|
.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
|
|
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 that exist there are a series of
|
|
.Xr ioctl 2
|
|
operation on the control endpoint that returns 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 request
|
|
and may respond with an answer to such request. Control request
|
|
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 unbuffered.
|
|
.Pp
|
|
The interrupt transfer mode can only be in.
|
|
To perform input from an interrupt endpoint
|
|
.Xr read 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.
|
|
.br
|
|
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 aui_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.
|
|
.br
|
|
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
|
|
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.
|