diff options
Diffstat (limited to 'static/netbsd/man4/ugen.4 3.html')
| -rw-r--r-- | static/netbsd/man4/ugen.4 3.html | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/static/netbsd/man4/ugen.4 3.html b/static/netbsd/man4/ugen.4 3.html deleted file mode 100644 index 709152ba..00000000 --- a/static/netbsd/man4/ugen.4 3.html +++ /dev/null @@ -1,331 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">UGEN(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">UGEN(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">ugen</code> — <span class="Nd">USB generic - device support</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="Cd">ugen* at uhub? flags N</code> - <br/> - <code class="Cd">ugen* at uhub? vendor V product P flags 1</code> - <br/> - <code class="Cd">ugenif* at uhub? vendor V product P configuration C interface - I</code> - <br/> - <code class="Cd">ugenif* at uhub? vendor V product P configuration C interface - I flags 1</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">ugen</code> 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.</p> -<p class="Pp">Normally the <code class="Nm">ugen</code> driver is used when no - other driver attaches to a device. If “flags 1” is specified, - the <code class="Nm">ugen</code> will instead attach with a very high - priority and always be used. Together with the - <code class="Cd">vendor</code> and <code class="Cd">product</code> locators - this can be used to force the <code class="Nm">ugen</code> driver to be used - for a certain device.</p> -<p class="Pp" id="NOTE">The ‘ugenif’ form of attachment can be - used to “steal” only one interface from some device for use by - the <code class="Nm">ugen</code> driver. Most likely you want to explicitly - specify at least vendor, product and interface with this form, as otherwise - the <code class="Nm">ugen</code> driver would capture all of your - <code class="Nm">usb</code> devices. If “flags 1” is - specified, the ‘ugenif’ form will match at the lowest - priority, thus allowing it to match only otherwise unclaimed interfaces. - <a class="permalink" href="#NOTE"><i class="Em">NOTE</i></a>: You have to be - extremely careful, when using this form, as the attached - <code class="Nm">ugen</code> driver has access to all of the device and can - easily interfere with the driver(s) used for the other interface(s).</p> -<p class="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 <code class="Nm">ugen</code> driver to interface - 0 of this particular board identified by <code class="Cd">vendor</code> and - <code class="Cd">product</code> while letting <a class="Xr">uftdi(4)</a> - together with <a class="Xr">ucom(4)</a> to attach at interface 1.</p> -<p class="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.</p> -<p class="Pp">If an endpoint address is used both for input and output the - device can be opened for both read or write.</p> -<p class="Pp">To find out what endpoints exist there are a series of - <a class="Xr">ioctl(2)</a> operations on the control endpoint that return - the USB descriptors of the device, configurations, interfaces, and - endpoints.</p> -<p class="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 - <a class="Xr">ioctl(2)</a> calls.</p> -<p class="Pp">The bulk transfer mode can be in or out depending on the endpoint. - To perform IO on a bulk endpoint <a class="Xr">read(2)</a> and - <a class="Xr">write(2)</a> should be used. All IO operations on a bulk - endpoint are normally unbuffered. The - <code class="Dv">USB_SET_BULK_RA</code> and - <code class="Dv">USB_SET_BULK_WB</code> <a class="Xr">ioctl(2)</a> 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.</p> -<p class="Pp">When in a read-ahead/writeback mode, <a class="Xr">select(2)</a> - 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, - <a class="Xr">select(2)</a> always returns true, because there is no way to - predict how the device will respond to a read or write request.</p> -<p class="Pp">The interrupt transfer mode can be in or out depending on the - endpoint. To perform IO on an interrupt endpoint <a class="Xr">read(2)</a> - and <a class="Xr">write(2)</a> should be used. A moderate amount of - buffering is done by the driver.</p> -<p class="Pp">All endpoints handle the following <a class="Xr">ioctl(2)</a> - calls:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt id="USB_SET_SHORT_XFER"><a class="permalink" href="#USB_SET_SHORT_XFER"><code class="Dv">USB_SET_SHORT_XFER</code></a> - (<code class="Dv">int</code>)</dt> - <dd>Allow short read transfer. Normally a transfer from the device which is - shorter than the request specified is reported as an error.</dd> - <dt id="USB_SET_TIMEOUT"><a class="permalink" href="#USB_SET_TIMEOUT"><code class="Dv">USB_SET_TIMEOUT</code></a> - (<code class="Dv">int</code>)</dt> - <dd>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.</dd> -</dl> -<p class="Pp">The control endpoint (endpoint 0) handles the following - <a class="Xr">ioctl(2)</a> calls:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt id="USB_GET_CONFIG"><a class="permalink" href="#USB_GET_CONFIG"><code class="Dv">USB_GET_CONFIG</code></a> - (<code class="Dv">int</code>)</dt> - <dd>Get the device configuration number.</dd> - <dt id="USB_SET_CONFIG"><a class="permalink" href="#USB_SET_CONFIG"><code class="Dv">USB_SET_CONFIG</code></a> - (<code class="Dv">int</code>)</dt> - <dd>Set the device into the given configuration number. - <p class="Pp">This operation can only be performed when the control endpoint - is the sole open endpoint.</p> - </dd> - <dt id="USB_GET_ALTINTERFACE"><a class="permalink" href="#USB_GET_ALTINTERFACE"><code class="Dv">USB_GET_ALTINTERFACE</code></a> - (<code class="Dv">struct usb_alt_interface</code>)</dt> - <dd>Get the alternative setting number for the interface with the given index. - The <code class="Dv">config_index</code> is ignored in this call. - <div class="Bd Pp Li"> - <pre>struct usb_alt_interface { - int uai_config_index; - int uai_interface_index; - int uai_alt_no; -};</pre> - </div> - </dd> - <dt id="USB_SET_ALTINTERFACE"><a class="permalink" href="#USB_SET_ALTINTERFACE"><code class="Dv">USB_SET_ALTINTERFACE</code></a> - (<code class="Dv">struct usb_alt_interface</code>)</dt> - <dd>Set the alternative setting to the given number in the interface with the - given index. The <code class="Dv">uai_config_index</code> is ignored in - this call. - <p class="Pp">This operation can only be performed when no endpoints for the - interface are open.</p> - </dd> - <dt id="USB_GET_NO_ALT"><a class="permalink" href="#USB_GET_NO_ALT"><code class="Dv">USB_GET_NO_ALT</code></a> - (<code class="Dv">struct usb_alt_interface</code>)</dt> - <dd>Return the number of different alternate settings in the - <code class="Dv">uai_alt_no</code> field.</dd> - <dt id="USB_GET_DEVICE_DESC"><a class="permalink" href="#USB_GET_DEVICE_DESC"><code class="Dv">USB_GET_DEVICE_DESC</code></a> - (<code class="Dv">usb_device_descriptor_t</code>)</dt> - <dd>Return the device descriptor.</dd> - <dt id="USB_GET_CONFIG_DESC"><a class="permalink" href="#USB_GET_CONFIG_DESC"><code class="Dv">USB_GET_CONFIG_DESC</code></a> - (<code class="Dv">struct usb_config_desc</code>)</dt> - <dd>Return the descriptor for the configuration with the given index. For - convenience the current configuration can be specified by - <code class="Dv">USB_CURRENT_CONFIG_INDEX</code>. - <div class="Bd Pp Li"> - <pre>struct usb_config_desc { - int ucd_config_index; - usb_config_descriptor_t ucd_desc; -};</pre> - </div> - </dd> - <dt id="USB_GET_INTERFACE_DESC"><a class="permalink" href="#USB_GET_INTERFACE_DESC"><code class="Dv">USB_GET_INTERFACE_DESC</code></a> - (<code class="Dv">struct usb_interface_desc</code>)</dt> - <dd>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 - <code class="Dv">USB_CURRENT_ALT_INDEX</code>. - <div class="Bd Pp Li"> - <pre>struct usb_interface_desc { - int uid_config_index; - int uid_interface_index; - int uid_alt_index; - usb_interface_descriptor_t uid_desc; -};</pre> - </div> - </dd> - <dt id="USB_GET_ENDPOINT_DESC"><a class="permalink" href="#USB_GET_ENDPOINT_DESC"><code class="Dv">USB_GET_ENDPOINT_DESC</code></a> - (<code class="Dv">struct usb_endpoint_desc</code>)</dt> - <dd>Return the endpoint descriptor for the endpoint specified by its - configuration index, interface index, alternative index, and endpoint - index. - <div class="Bd Pp Li"> - <pre>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; -};</pre> - </div> - </dd> - <dt id="USB_GET_FULL_DESC"><a class="permalink" href="#USB_GET_FULL_DESC"><code class="Dv">USB_GET_FULL_DESC</code></a> - (<code class="Dv">struct usb_full_desc</code>)</dt> - <dd>Return all the descriptors for the given configuration. - <div class="Bd Pp Li"> - <pre>struct usb_full_desc { - int ufd_config_index; - u_int ufd_size; - u_char *ufd_data; -};</pre> - </div> - The <code class="Dv">ufd_data</code> field should point to a memory area of - the size given in the <code class="Dv">ufd_size</code> field. The proper - size can be determined by first issuing a - <code class="Dv">USB_GET_CONFIG_DESC</code> and inspecting the - <code class="Dv">wTotalLength</code> field.</dd> - <dt id="USB_GET_STRING_DESC"><a class="permalink" href="#USB_GET_STRING_DESC"><code class="Dv">USB_GET_STRING_DESC</code></a> - (<code class="Dv">struct usb_string_desc</code>)</dt> - <dd>Get a string descriptor for the given language id and string index. - <div class="Bd Pp Li"> - <pre>struct usb_string_desc { - int usd_string_index; - int usd_language_id; - usb_string_descriptor_t usd_desc; -};</pre> - </div> - </dd> - <dt id="USB_DO_REQUEST"><a class="permalink" href="#USB_DO_REQUEST"><code class="Dv">USB_DO_REQUEST</code></a></dt> - <dd>Send a USB request to the device on the control endpoint. Any data sent - to/from the device is located at <code class="Dv">data</code>. The size of - the transferred data is determined from the - <code class="Dv">request</code>. The <code class="Dv">ucr_addr</code> - field is ignored in this call. The <code class="Dv">ucr_flags</code> field - can be used to flag that the request is allowed to be shorter than the - requested size, and the <code class="Dv">ucr_actlen</code> field will - contain the actual size on completion. - <div class="Bd Pp Li"> - <pre>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 */ -};</pre> - </div> - 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.</dd> - <dt id="USB_GET_DEVICEINFO"><a class="permalink" href="#USB_GET_DEVICEINFO"><code class="Dv">USB_GET_DEVICEINFO</code></a> - (<code class="Dv">struct usb_device_info</code>)</dt> - <dd>Get an information summary for the device. This call will not issue any - USB transactions.</dd> -</dl> -<p class="Pp">Bulk endpoints handle the following <a class="Xr">ioctl(2)</a> - calls:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt id="USB_SET_BULK_RA"><a class="permalink" href="#USB_SET_BULK_RA"><code class="Dv">USB_SET_BULK_RA</code></a> - (<code class="Dv">int</code>)</dt> - <dd>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 <a class="Xr">read(2)</a> - 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 - <code class="Dv">USB_SET_BULK_RA_OPT</code> <a class="Xr">ioctl(2)</a> - call.</dd> - <dt id="USB_SET_BULK_WB"><a class="permalink" href="#USB_SET_BULK_WB"><code class="Dv">USB_SET_BULK_WB</code></a> - (<code class="Dv">int</code>)</dt> - <dd>Enable or disable bulk write-behind. When enabled, the driver will buffer - data from the <a class="Xr">write(2)</a> call before writing it to the - device, enabling the <a class="Xr">write(2)</a> call to return - immediately. <a class="Xr">write(2)</a> 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 <code class="Dv">USB_SET_BULK_WB_OPT</code> - <a class="Xr">ioctl(2)</a> call.</dd> - <dt id="USB_SET_BULK_RA_OPT"><a class="permalink" href="#USB_SET_BULK_RA_OPT"><code class="Dv">USB_SET_BULK_RA_OPT</code></a> - (<code class="Dv">struct usb_bulk_ra_wb_opt</code>)</dt> - <dd>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., - <a class="Xr">ehci(4)</a>, <a class="Xr">ohci(4)</a>, and - <a class="Xr">uhci(4)</a>) will perform as many bus transfers as required. - If transfers from the device should be smaller than the maximum length, - <code class="Dv">ra_wb_request_size</code> must be set to the required - length. - <div class="Bd Pp Li"> - <pre>struct usb_bulk_ra_wb_opt { - u_int ra_wb_buffer_size; - u_int ra_wb_request_size; -};</pre> - </div> - </dd> - <dt id="USB_SET_BULK_WB_OPT"><a class="permalink" href="#USB_SET_BULK_WB_OPT"><code class="Dv">USB_SET_BULK_WB_OPT</code></a> - (<code class="Dv">struct usb_bulk_ra_wb_opt</code>)</dt> - <dd>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.</dd> -</dl> -<p class="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.</p> -<p class="Pp">Example: All endpoints (except the control endpoint) for the - current configuration can be found by iterating the - <code class="Dv">interface_index</code> from 0 to - <code class="Dv">config_desc->bNumInterface-1</code> and for each of - these iterating the <code class="Dv">endpoint_index</code> from 0 to - <code class="Dv">interface_desc->bNumEndpoints</code>. The - <code class="Dv">config_index</code> should set to - <code class="Dv">USB_CURRENT_CONFIG_INDEX</code> and - <code class="Dv">alt_index</code> should be set to - <code class="Dv">USB_CURRENT_ALT_INDEX</code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> -<dl class="Bl-tag"> - <dt><span class="Pa">/dev/ugenN.EE</span></dt> - <dd>Endpoint <span class="Pa">EE</span> of device - <span class="Pa">N</span>.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">usb(4)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">ugen</code> driver appeared in - <span class="Ux">NetBSD 1.4</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">March 25, 2024</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |