/share/man/man4/ugen.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 311 lines · 311 code · 0 blank · 0 comment · 13 complexity · 642ac7fe1f185289f0e8bea2ba1ee7aa MD5 · raw file
- .\" $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.
- .\"
- .\" 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 22, 2012
- .Dt UGEN 4
- .Os
- .Sh NAME
- .Nm ugen
- .Nd USB generic device support
- .Sh SYNOPSIS
- .Nm
- is integrated into the
- .Xr usb 4
- kernel module.
- .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 determine which endpoint the device accesses, and the rest
- of the bits determine 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 which 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 a request
- and may respond with an answer to such a request.
- 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 I/O on an isochronous endpoint
- .\" .Xr read 2
- .\" and
- .\" .Xr write 2
- .\" should be used.
- .\" Before any I/O 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 I/O on a bulk endpoint
- .Xr read 2
- and
- .Xr write 2
- should be used.
- All I/O operations on a bulk endpoint are unbuffered.
- .Pp
- The interrupt transfer mode can be in or out depending on the
- endpoint.
- To perform I/O 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:
- .Bl -tag -width indent
- .It Dv USB_SET_SHORT_XFER Pq Vt 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 Pq Vt 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:
- .Bl -tag -width indent
- .It Dv USB_GET_CONFIG Pq Vt int
- Get the device configuration number.
- .It Dv USB_SET_CONFIG Pq Vt 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 Pq Vt "struct usb_alt_interface"
- Get the alternative setting number for the interface with the given
- index.
- The
- .Va uai_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 Pq Vt "struct usb_alt_interface"
- Set the alternative setting to the given number in the interface with the
- given index.
- The
- .Va 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 Pq Vt "struct usb_alt_interface"
- Return the number of different alternate settings in the
- .Va uai_alt_no
- field.
- .It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t
- Return the device descriptor.
- .It Dv USB_GET_CONFIG_DESC Pq Vt "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 Pq Vt "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 Pq Vt "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 Pq Vt "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
- .Va ufd_data
- field should point to a memory area of the size given in the
- .Va ufd_size
- field.
- The proper size can be determined by first issuing a
- .Dv USB_GET_CONFIG_DESC
- and inspecting the
- .Va wTotalLength
- field.
- .It Dv USB_GET_STRING_DESC Pq Vt "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 Pq Vt "struct usb_ctl_request"
- Send a USB request to the device on the control endpoint.
- Any data sent to/from the device is located at
- .Va ucr_data .
- The size of the transferred data is determined from the
- .Va ucr_request .
- The
- .Va ucr_addr
- field is ignored in this call.
- The
- .Va ucr_flags
- field can be used to flag that the request is allowed to
- be shorter than the requested size, and
- .Va ucr_actlen
- 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 Pq Vt "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
- uses 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
- .Va interface_index
- from 0 to
- .Va config_desc->bNumInterface Ns \-1
- and for each of these, iterating the
- .Va endpoint_index
- from 0 to
- .Va interface_desc->bNumEndpoints .
- The
- .Va config_index
- should be set to
- .Dv USB_CURRENT_CONFIG_INDEX
- and
- .Va alt_index
- should be set to
- .Dv USB_CURRENT_ALT_INDEX .
- .Sh FILES
- .Bl -tag -width ".Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE" -compact
- .It Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE
- Endpoint
- .Ar EE
- of device
- .Ar 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.