diff options
Diffstat (limited to 'static/netbsd/man4/ugen.4')
| -rw-r--r-- | static/netbsd/man4/ugen.4 | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/static/netbsd/man4/ugen.4 b/static/netbsd/man4/ugen.4 new file mode 100644 index 00000000..92848121 --- /dev/null +++ b/static/netbsd/man4/ugen.4 @@ -0,0 +1,448 @@ +.\" $NetBSD: ugen.4,v 1.39 2024/03/26 03:24:14 thorpej 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 March 25, 2024 +.Dt UGEN 4 +.Os +.Sh NAME +.Nm ugen +.Nd USB generic device support +.Sh SYNOPSIS +.Cd "ugen* at uhub? flags N" +.Cd "ugen* at uhub? vendor V product P flags 1" +.Cd "ugenif* at uhub? vendor V product P configuration C interface I" +.Cd "ugenif* at uhub? vendor V product P configuration C interface I flags 1" +.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 +The +.Sq ugenif +form of attachment can be used to +.Dq steal +only one interface from some device for use by the +.Nm +driver. +Most likely you want to explicitly specify at least vendor, +product and interface with this form, +as otherwise the +.Nm +driver would capture all of your +.Nm usb +devices. +If +.Dq flags 1 +is specified, the +.Sq ugenif +form will match at the lowest priority, thus allowing it to match only +otherwise unclaimed interfaces. +.Em NOTE : +You have to be extremely careful, +when using this form, +as the attached +.Nm +driver has access to all of the device +and can easily interfere with the driver(s) used for +the other interface(s). +.Pp +As an example of this second form of attachment there are +various debugging boards available based on some FTDI chip, +where one interface is used for JTAG debugging +and the other is used as a serial interface. +In this case you want to attach the +.Nm +driver to interface 0 of this particular board identified by +.Cd vendor +and +.Cd product +while letting +.Xr uftdi 4 +together with +.Xr ucom 4 +to attach at interface 1. +.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. +The +.Dv USB_SET_BULK_RA +and +.Dv USB_SET_BULK_WB +.Xr ioctl 2 +calls enable read-ahead and write-behind buffering, respectively. +This buffering supports fixed-sized USB transfers and is intended for +devices with regular and continuing data transfers. +When read-ahead or write-behind are enabled, the file descriptor +may be set to use non-blocking IO. +.Pp +When in a read-ahead/writeback 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, +.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 uai_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->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. |