Bring in the ugen manual page from NetBSD.
This commit is contained in:
Josef Karthauser
parent
1ddfc2e3aa
commit
0a98bc0cfa
@ -171,6 +171,7 @@ MAN= aac.4 \
|
||||
txp.4 \
|
||||
udbp.4 \
|
||||
udp.4 \
|
||||
ugen.4 \
|
||||
uhci.4 \
|
||||
ukbd.4 \
|
||||
umass.4 \
|
||||
|
||||
298
share/man/man4/ugen.4
Normal file
298
share/man/man4/ugen.4
Normal file
@ -0,0 +1,298 @@
|
||||
.\" $NetBSD: ugen.4,v 1.13 2001/09/11 22:52:54 wiz 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd July 12, 1998
|
||||
.Dt UGEN 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm ugen
|
||||
.Nd USB generic device support
|
||||
.Sh SYNOPSIS
|
||||
.Cd "device ugen"
|
||||
.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 config_index;
|
||||
int interface_index;
|
||||
int 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 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 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 config_index;
|
||||
usb_config_descriptor_t 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 config_index;
|
||||
int interface_index;
|
||||
int alt_index;
|
||||
usb_interface_descriptor_t 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 config_index;
|
||||
int interface_index;
|
||||
int alt_index;
|
||||
int endpoint_index;
|
||||
usb_endpoint_descriptor_t 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 config_index;
|
||||
u_int size;
|
||||
u_char *data;
|
||||
};
|
||||
.Ed
|
||||
The
|
||||
.Dv data
|
||||
field should point to a memory area of of the size given in the
|
||||
.Dv 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 string_index;
|
||||
int language_id;
|
||||
usb_string_descriptor_t 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 addr
|
||||
field is ignored in this call.
|
||||
The
|
||||
.Dv flags
|
||||
field can be used to flag that the request is allowed to
|
||||
be shorter than the requested size, and the
|
||||
.Dv actlen
|
||||
will contain the actual size on completion.
|
||||
.Bd -literal
|
||||
struct usb_ctl_request {
|
||||
int addr;
|
||||
usb_device_request_t request;
|
||||
void *data;
|
||||
int flags;
|
||||
#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */
|
||||
int 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->bNumInterface-1
|
||||
and for each of these iterating the
|
||||
.Dv endpoint_index
|
||||
from 0 to
|
||||
.Dv interface_desc->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.
|
||||
Loading…
x
Reference in New Issue
Block a user