Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

New sentence, new line. Add "options UGEN_BULK_RA_WB" to SYNOPSIS.

Browse Source 
Bump date for previous.

XXX: there should be a sentence or two about UGEN_BULK_RA_WB.
This commit is contained in:
wiz 2006-07-24 17:00:52 +00:00
parent 5d611badde
commit 7e04cdd341
1 changed files with 60 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
share/man/man4/ugen.4
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ugen.4,v 1.22 2006/07/24 14:24:48 gdt Exp $ .\" $NetBSD: ugen.4,v 1.23 2006/07/24 17:00:52 wiz Exp $
.\" .\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc. .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved. .\" All rights reserved.
@ -34,7 +34,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE. .\" POSSIBILITY OF SUCH DAMAGE.
.\" .\"
.Dd November 22, 2005 .Dd July 24, 2006
.Dt UGEN 4 .Dt UGEN 4
.Os .Os
.Sh NAME .Sh NAME
@ -42,11 +42,13 @@
.Nd USB generic device support .Nd USB generic device support
.Sh SYNOPSIS .Sh SYNOPSIS
.Cd "ugen* at uhub? flags N" .Cd "ugen* at uhub? flags N"
.Cd options UGEN_BULK_RA_WB
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
driver provides support for all USB devices that do not have driver provides support for all USB devices that do not have
a special driver. It supports access to all parts of the device, 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. but not in a way that is as convenient as a special purpose driver.
.Pp .Pp
Normally the Normally the
@ -67,10 +69,11 @@ driver to be used for a certain
device. device.
.Pp .Pp
There can be up to 127 USB devices connected to a USB bus. 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 Each USB device can have up to 16 endpoints.
will communicate in one of four different modes: control, isochronous, Each of these endpoints will communicate in one of four different
bulk, or interrupt. Each of the endpoints will have a different modes: control, isochronous, bulk, or interrupt.
device node. The four least significant bits in the minor device 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 number determines which endpoint the device accesses and the rest
of the bits determines which USB device. of the bits determines which USB device.
.Pp .Pp
@ -83,27 +86,31 @@ operations on the control endpoint that return the USB descriptors
of the device, configurations, interfaces, and endpoints. of the device, configurations, interfaces, and endpoints.
.Pp .Pp
The control transfer mode can only happen on the control endpoint The control transfer mode can only happen on the control endpoint
which is always endpoint 0. The control endpoint accepts requests which is always endpoint 0.
and may respond with an answer to such requests. Control requests The control endpoint accepts requests
are issued by and may respond with an answer to such requests.
Control requests are issued by
.Xr ioctl 2 .Xr ioctl 2
calls. calls.
.\" .Pp .\" .Pp
.\" The isochronous transfer mode can be in or out depending on the .\" The isochronous transfer mode can be in or out depending on the
.\" endpoint. To perform IO on an isochronous endpoint .\" endpoint.
.\" To perform IO on an isochronous endpoint
.\" .Xr read 2 .\" .Xr read 2
.\" and .\" and
.\" .Xr write 2 .\" .Xr write 2
.\" should be used. .\" should be used.
.\" Before any IO operations can take place the transfer rate in .\" Before any IO operations can take place the transfer rate in
.\" bytes/second has to be set. This is done with .\" bytes/second has to be set.
.\" This is done with
.\" .Xr ioctl 2 .\" .Xr ioctl 2
.\" .Dv USB_SET_ISO_RATE . .\" .Dv USB_SET_ISO_RATE .
.\" Performing this call sets up a buffer corresponding to .\" Performing this call sets up a buffer corresponding to
.\" about 1 second of data. .\" about 1 second of data.
.Pp .Pp
The bulk transfer mode can be in or out depending on the The bulk transfer mode can be in or out depending on the
endpoint. To perform IO on a bulk endpoint endpoint.
To perform IO on a bulk endpoint
.Xr read 2 .Xr read 2
and and
.Xr write 2 .Xr write 2
@ -114,9 +121,9 @@ Buffering can be enabled using a
or or
.Dv USB_SET_BULK_WB .Dv USB_SET_BULK_WB
.Xr ioctl 2 .Xr ioctl 2
call, to enable read-ahead and write-behind respectively. When call, to enable read-ahead and write-behind respectively.
read-ahead or write-behind are enabled, the file descriptor may When read-ahead or write-behind are enabled, the file descriptor
be set to use non-blocking IO. may be set to use non-blocking IO.
.Pp .Pp
The interrupt transfer mode can be in or out depending on the The interrupt transfer mode can be in or out depending on the
endpoint. endpoint.
@ -134,13 +141,13 @@ calls:
.Pp .Pp
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Dv USB_SET_SHORT_XFER (int) .It Dv USB_SET_SHORT_XFER (int)
Allow short read transfer. Normally a transfer from the device Allow short read transfer.
which is shorter than the request specified is reported as an Normally a transfer from the device which is shorter than the
error. request specified is reported as an error.
.It Dv USB_SET_TIMEOUT (int) .It Dv USB_SET_TIMEOUT (int)
Set the timeout on the device operations, the time is specified Set the timeout on the device operations, the time is specified
in milliseconds. The value 0 is used to indicate that there is in milliseconds.
no timeout. The value 0 is used to indicate that there is no timeout.
.El .El
.Pp .Pp
The control endpoint (endpoint 0) handles the following The control endpoint (endpoint 0) handles the following
@ -232,7 +239,8 @@ The
.Dv ufd_data .Dv ufd_data
field should point to a memory area of the size given in the field should point to a memory area of the size given in the
.Dv ufd_size .Dv ufd_size
field. The proper size can be determined by first issuing a field.
The proper size can be determined by first issuing a
.Dv USB_GET_CONFIG_DESC .Dv USB_GET_CONFIG_DESC
and inspecting the and inspecting the
.Dv wTotalLength .Dv wTotalLength
@ -273,11 +281,12 @@ struct usb_ctl_request {
}; };
.Ed .Ed
This is a dangerous operation in that it can perform arbitrary operations 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 on the device.
Some of the most dangerous (e.g., changing the device
address) are not allowed. address) are not allowed.
.It Dv USB_GET_DEVICEINFO (struct usb_device_info) .It Dv USB_GET_DEVICEINFO (struct usb_device_info)
Get an information summary for the device. This call will not Get an information summary for the device.
issue any USB transactions. This call will not issue any USB transactions.
.El .El
.Pp .Pp
Bulk endpoints handle the following Bulk endpoints handle the following
@ -286,37 +295,43 @@ calls:
.Pp .Pp
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Dv USB_SET_BULK_RA (int) .It Dv USB_SET_BULK_RA (int)
Enable or disable bulk read-ahead. When enabled, the driver will Enable or disable bulk read-ahead.
begin to read data from the device into a buffer. The When enabled, the driver will
begin to read data from the device into a buffer.
The
.Xr read 2 .Xr read 2
call will read data from this buffer, blocking if necessary until call will read data from this buffer, blocking if necessary until
there is enough data to read the length of data requested. The there is enough data to read the length of data requested.
buffer size and the read request length can be set by the The buffer size and the read request length can be set by the
.Dv USB_SET_BULK_RA_OPT .Dv USB_SET_BULK_RA_OPT
.Xr ioctl 2 .Xr ioctl 2
call. call.
.It Dv USB_SET_BULK_WB (int) .It Dv USB_SET_BULK_WB (int)
Enable or disable bulk write-behind. When enabled, the driver will Enable or disable bulk write-behind.
buffer data from the When enabled, the driver will buffer data from the
.Xr write 2 .Xr write 2
call before writing it to the device. call before writing it to the device.
.Xr write 2 .Xr write 2
will block if there is not enough room in the buffer for all 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 the data.
by the The buffer size and the write request length can be set by the
.Dv USB_SET_BULK_WB_OPT .Dv USB_SET_BULK_WB_OPT
.Xr ioctl 2 .Xr ioctl 2
call. call.
.It Dv USB_SET_BULK_RA_OPT (struct usb_bulk_ra_wb_opt) .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 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 the driver when bulk read-ahead is enabled.
effect until the next time bulk read-ahead is enabled. Read requests 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 are made for the length specified, and the host controller driver
(i.e., (i.e.,
.Xr ehci 4 , .Xr ehci 4 ,
.Xr ohci 4 , and .Xr ohci 4 ,
.Xr uhci 4 ) will perform as many bus transfers as required. If and
transfers from the device should be smaller than the maximum length, .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 .Dv ra_wb_request_size
must be set to the required length. must be set to the required length.
.Bd -literal .Bd -literal
@ -327,15 +342,18 @@ struct usb_bulk_ra_wb_opt {
.Ed .Ed
.It Dv USB_SET_BULK_WB_OPT (struct usb_bulk_ra_wb_opt) .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 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 by the driver when bulk write-behind is enabled.
The changes do not
take effect until the next time bulk write-behind is enabled. take effect until the next time bulk write-behind is enabled.
.El .El
.Pp .Pp
Note that there are two different ways of addressing configurations, interfaces, Note that there are two different ways of addressing configurations, interfaces,
alternatives, and endpoints: by index or by number. alternatives, and endpoints: by index or by number.
The index is the ordinal number (starting from 0) of the descriptor The index is the ordinal number (starting from 0) of the descriptor
as presented by the device. The number is the respective number of as presented by the device.
the entity as found in its descriptor. Enumeration of descriptors 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. use the index, getting and setting typically uses numbers.
.Pp .Pp
Example: Example: