1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>The ioctl() Requests</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="The Linux-USB Host Side API"><link rel="up" href="usbfs.html" title="Chapter 7. The USB Filesystem (usbfs)"><link rel="prev" href="usbfs-lifecycle.html" title="Life Cycle of User Mode Drivers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The ioctl() Requests</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="usbfs-lifecycle.html">Prev</a> </td><th width="60%" align="center">Chapter 7. The USB Filesystem (usbfs)</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usbfs-ioctl"></a>The ioctl() Requests</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="usbfs-ioctl.html#usbfs-mgmt">Management/Status Requests</a></span></dt><dt><span class="sect2"><a href="usbfs-ioctl.html#usbfs-sync">Synchronous I/O Support</a></span></dt><dt><span class="sect2"><a href="usbfs-ioctl.html#usbfs-async">Asynchronous I/O Support</a></span></dt></dl></div><p>To use these ioctls, you need to include the following 2 headers in your userspace program: 3</p><pre class="programlisting">#include <linux/usb.h> 4#include <linux/usbdevice_fs.h> 5#include <asm/byteorder.h></pre><p> 6 The standard USB device model requests, from "Chapter 9" of 7 the USB 2.0 specification, are automatically included from 8 the <code class="filename"><linux/usb/ch9.h></code> header. 9 </p><p>Unless noted otherwise, the ioctl requests 10 described here will 11 update the modification time on the usbfs file to which 12 they are applied (unless they fail). 13 A return of zero indicates success; otherwise, a 14 standard USB error code is returned. (These are 15 documented in 16 <code class="filename">Documentation/usb/error-codes.txt</code> 17 in your kernel sources.) 18 </p><p>Each of these files multiplexes access to several 19 I/O streams, one per endpoint. 20 Each device has one control endpoint (endpoint zero) 21 which supports a limited RPC style RPC access. 22 Devices are configured 23 by hub_wq (in the kernel) setting a device-wide 24 <span class="emphasis"><em>configuration</em></span> that affects things 25 like power consumption and basic functionality. 26 The endpoints are part of USB <span class="emphasis"><em>interfaces</em></span>, 27 which may have <span class="emphasis"><em>altsettings</em></span> 28 affecting things like which endpoints are available. 29 Many devices only have a single configuration and interface, 30 so drivers for them will ignore configurations and altsettings. 31 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="usbfs-mgmt"></a>Management/Status Requests</h3></div></div></div><p>A number of usbfs requests don't deal very directly 32 with device I/O. 33 They mostly relate to device management and status. 34 These are all synchronous requests. 35 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">USBDEVFS_CLAIMINTERFACE</span></dt><dd><p>This is used to force usbfs to 36 claim a specific interface, 37 which has not previously been claimed by usbfs or any other 38 kernel driver. 39 The ioctl parameter is an integer holding the number of 40 the interface (bInterfaceNumber from descriptor). 41 </p><p> 42 Note that if your driver doesn't claim an interface 43 before trying to use one of its endpoints, and no 44 other driver has bound to it, then the interface is 45 automatically claimed by usbfs. 46 </p><p> 47 This claim will be released by a RELEASEINTERFACE ioctl, 48 or by closing the file descriptor. 49 File modification time is not updated by this request. 50 </p></dd><dt><span class="term">USBDEVFS_CONNECTINFO</span></dt><dd><p>Says whether the device is lowspeed. 51 The ioctl parameter points to a structure like this: 52</p><pre class="programlisting">struct usbdevfs_connectinfo { 53 unsigned int devnum; 54 unsigned char slow; 55}; </pre><p> 56 File modification time is not updated by this request. 57 </p><p> 58 <span class="emphasis"><em>You can't tell whether a "not slow" 59 device is connected at high speed (480 MBit/sec) 60 or just full speed (12 MBit/sec).</em></span> 61 You should know the devnum value already, 62 it's the DDD value of the device file name. 63 </p></dd><dt><span class="term">USBDEVFS_GETDRIVER</span></dt><dd><p>Returns the name of the kernel driver 64 bound to a given interface (a string). Parameter 65 is a pointer to this structure, which is modified: 66</p><pre class="programlisting">struct usbdevfs_getdriver { 67 unsigned int interface; 68 char driver[USBDEVFS_MAXDRIVERNAME + 1]; 69};</pre><p> 70 File modification time is not updated by this request. 71 </p></dd><dt><span class="term">USBDEVFS_IOCTL</span></dt><dd><p>Passes a request from userspace through 72 to a kernel driver that has an ioctl entry in the 73 <span class="emphasis"><em>struct usb_driver</em></span> it registered. 74</p><pre class="programlisting">struct usbdevfs_ioctl { 75 int ifno; 76 int ioctl_code; 77 void *data; 78}; 79 80/* user mode call looks like this. 81 * 'request' becomes the driver->ioctl() 'code' parameter. 82 * the size of 'param' is encoded in 'request', and that data 83 * is copied to or from the driver->ioctl() 'buf' parameter. 84 */ 85static int 86usbdev_ioctl (int fd, int ifno, unsigned request, void *param) 87{ 88 struct usbdevfs_ioctl wrapper; 89 90 wrapper.ifno = ifno; 91 wrapper.ioctl_code = request; 92 wrapper.data = param; 93 94 return ioctl (fd, USBDEVFS_IOCTL, &wrapper); 95} </pre><p> 96 File modification time is not updated by this request. 97 </p><p> 98 This request lets kernel drivers talk to user mode code 99 through filesystem operations even when they don't create 100 a character or block special device. 101 It's also been used to do things like ask devices what 102 device special file should be used. 103 Two pre-defined ioctls are used 104 to disconnect and reconnect kernel drivers, so 105 that user mode code can completely manage binding 106 and configuration of devices. 107 </p></dd><dt><span class="term">USBDEVFS_RELEASEINTERFACE</span></dt><dd><p>This is used to release the claim usbfs 108 made on interface, either implicitly or because of a 109 USBDEVFS_CLAIMINTERFACE call, before the file 110 descriptor is closed. 111 The ioctl parameter is an integer holding the number of 112 the interface (bInterfaceNumber from descriptor); 113 File modification time is not updated by this request. 114 </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> 115 <span class="emphasis"><em>No security check is made to ensure 116 that the task which made the claim is the one 117 which is releasing it. 118 This means that user mode driver may interfere 119 other ones. </em></span> 120 </p></div></dd><dt><span class="term">USBDEVFS_RESETEP</span></dt><dd><p>Resets the data toggle value for an endpoint 121 (bulk or interrupt) to DATA0. 122 The ioctl parameter is an integer endpoint number 123 (1 to 15, as identified in the endpoint descriptor), 124 with USB_DIR_IN added if the device's endpoint sends 125 data to the host. 126 </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> 127 <span class="emphasis"><em>Avoid using this request. 128 It should probably be removed.</em></span> 129 Using it typically means the device and driver will lose 130 toggle synchronization. If you really lost synchronization, 131 you likely need to completely handshake with the device, 132 using a request like CLEAR_HALT 133 or SET_INTERFACE. 134 </p></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="usbfs-sync"></a>Synchronous I/O Support</h3></div></div></div><p>Synchronous requests involve the kernel blocking 135 until the user mode request completes, either by 136 finishing successfully or by reporting an error. 137 In most cases this is the simplest way to use usbfs, 138 although as noted above it does prevent performing I/O 139 to more than one endpoint at a time. 140 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">USBDEVFS_BULK</span></dt><dd><p>Issues a bulk read or write request to the 141 device. 142 The ioctl parameter is a pointer to this structure: 143</p><pre class="programlisting">struct usbdevfs_bulktransfer { 144 unsigned int ep; 145 unsigned int len; 146 unsigned int timeout; /* in milliseconds */ 147 void *data; 148};</pre><p> 149 </p><p>The "ep" value identifies a 150 bulk endpoint number (1 to 15, as identified in an endpoint 151 descriptor), 152 masked with USB_DIR_IN when referring to an endpoint which 153 sends data to the host from the device. 154 The length of the data buffer is identified by "len"; 155 Recent kernels support requests up to about 128KBytes. 156 <span class="emphasis"><em>FIXME say how read length is returned, 157 and how short reads are handled.</em></span>. 158 </p></dd><dt><span class="term">USBDEVFS_CLEAR_HALT</span></dt><dd><p>Clears endpoint halt (stall) and 159 resets the endpoint toggle. This is only 160 meaningful for bulk or interrupt endpoints. 161 The ioctl parameter is an integer endpoint number 162 (1 to 15, as identified in an endpoint descriptor), 163 masked with USB_DIR_IN when referring to an endpoint which 164 sends data to the host from the device. 165 </p><p> 166 Use this on bulk or interrupt endpoints which have 167 stalled, returning <span class="emphasis"><em>-EPIPE</em></span> status 168 to a data transfer request. 169 Do not issue the control request directly, since 170 that could invalidate the host's record of the 171 data toggle. 172 </p></dd><dt><span class="term">USBDEVFS_CONTROL</span></dt><dd><p>Issues a control request to the device. 173 The ioctl parameter points to a structure like this: 174</p><pre class="programlisting">struct usbdevfs_ctrltransfer { 175 __u8 bRequestType; 176 __u8 bRequest; 177 __u16 wValue; 178 __u16 wIndex; 179 __u16 wLength; 180 __u32 timeout; /* in milliseconds */ 181 void *data; 182};</pre><p> 183 </p><p> 184 The first eight bytes of this structure are the contents 185 of the SETUP packet to be sent to the device; see the 186 USB 2.0 specification for details. 187 The bRequestType value is composed by combining a 188 USB_TYPE_* value, a USB_DIR_* value, and a 189 USB_RECIP_* value (from 190 <span class="emphasis"><em><linux/usb.h></em></span>). 191 If wLength is nonzero, it describes the length of the data 192 buffer, which is either written to the device 193 (USB_DIR_OUT) or read from the device (USB_DIR_IN). 194 </p><p> 195 At this writing, you can't transfer more than 4 KBytes 196 of data to or from a device; usbfs has a limit, and 197 some host controller drivers have a limit. 198 (That's not usually a problem.) 199 <span class="emphasis"><em>Also</em></span> there's no way to say it's 200 not OK to get a short read back from the device. 201 </p></dd><dt><span class="term">USBDEVFS_RESET</span></dt><dd><p>Does a USB level device reset. 202 The ioctl parameter is ignored. 203 After the reset, this rebinds all device interfaces. 204 File modification time is not updated by this request. 205 </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> 206 <span class="emphasis"><em>Avoid using this call</em></span> 207 until some usbcore bugs get fixed, 208 since it does not fully synchronize device, interface, 209 and driver (not just usbfs) state. 210 </p></div></dd><dt><span class="term">USBDEVFS_SETINTERFACE</span></dt><dd><p>Sets the alternate setting for an 211 interface. The ioctl parameter is a pointer to a 212 structure like this: 213</p><pre class="programlisting">struct usbdevfs_setinterface { 214 unsigned int interface; 215 unsigned int altsetting; 216}; </pre><p> 217 File modification time is not updated by this request. 218 </p><p> 219 Those struct members are from some interface descriptor 220 applying to the current configuration. 221 The interface number is the bInterfaceNumber value, and 222 the altsetting number is the bAlternateSetting value. 223 (This resets each endpoint in the interface.) 224 </p></dd><dt><span class="term">USBDEVFS_SETCONFIGURATION</span></dt><dd><p>Issues the 225 <code class="function">usb_set_configuration</code> call 226 for the device. 227 The parameter is an integer holding the number of 228 a configuration (bConfigurationValue from descriptor). 229 File modification time is not updated by this request. 230 </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> 231 <span class="emphasis"><em>Avoid using this call</em></span> 232 until some usbcore bugs get fixed, 233 since it does not fully synchronize device, interface, 234 and driver (not just usbfs) state. 235 </p></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="usbfs-async"></a>Asynchronous I/O Support</h3></div></div></div><p>As mentioned above, there are situations where it may be 236 important to initiate concurrent operations from user mode code. 237 This is particularly important for periodic transfers 238 (interrupt and isochronous), but it can be used for other 239 kinds of USB requests too. 240 In such cases, the asynchronous requests described here 241 are essential. Rather than submitting one request and having 242 the kernel block until it completes, the blocking is separate. 243 </p><p>These requests are packaged into a structure that 244 resembles the URB used by kernel device drivers. 245 (No POSIX Async I/O support here, sorry.) 246 It identifies the endpoint type (USBDEVFS_URB_TYPE_*), 247 endpoint (number, masked with USB_DIR_IN as appropriate), 248 buffer and length, and a user "context" value serving to 249 uniquely identify each request. 250 (It's usually a pointer to per-request data.) 251 Flags can modify requests (not as many as supported for 252 kernel drivers). 253 </p><p>Each request can specify a realtime signal number 254 (between SIGRTMIN and SIGRTMAX, inclusive) to request a 255 signal be sent when the request completes. 256 </p><p>When usbfs returns these urbs, the status value 257 is updated, and the buffer may have been modified. 258 Except for isochronous transfers, the actual_length is 259 updated to say how many bytes were transferred; if the 260 USBDEVFS_URB_DISABLE_SPD flag is set 261 ("short packets are not OK"), if fewer bytes were read 262 than were requested then you get an error report. 263 </p><pre class="programlisting">struct usbdevfs_iso_packet_desc { 264 unsigned int length; 265 unsigned int actual_length; 266 unsigned int status; 267}; 268 269struct usbdevfs_urb { 270 unsigned char type; 271 unsigned char endpoint; 272 int status; 273 unsigned int flags; 274 void *buffer; 275 int buffer_length; 276 int actual_length; 277 int start_frame; 278 int number_of_packets; 279 int error_count; 280 unsigned int signr; 281 void *usercontext; 282 struct usbdevfs_iso_packet_desc iso_frame_desc[]; 283};</pre><p> For these asynchronous requests, the file modification 284 time reflects when the request was initiated. 285 This contrasts with their use with the synchronous requests, 286 where it reflects when requests complete. 287 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">USBDEVFS_DISCARDURB</span></dt><dd><p> 288 <span class="emphasis"><em>TBS</em></span> 289 File modification time is not updated by this request. 290 </p><p> 291 </p></dd><dt><span class="term">USBDEVFS_DISCSIGNAL</span></dt><dd><p> 292 <span class="emphasis"><em>TBS</em></span> 293 File modification time is not updated by this request. 294 </p><p> 295 </p></dd><dt><span class="term">USBDEVFS_REAPURB</span></dt><dd><p> 296 <span class="emphasis"><em>TBS</em></span> 297 File modification time is not updated by this request. 298 </p><p> 299 </p></dd><dt><span class="term">USBDEVFS_REAPURBNDELAY</span></dt><dd><p> 300 <span class="emphasis"><em>TBS</em></span> 301 File modification time is not updated by this request. 302 </p><p> 303 </p></dd><dt><span class="term">USBDEVFS_SUBMITURB</span></dt><dd><p> 304 <span class="emphasis"><em>TBS</em></span> 305 </p><p> 306 </p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="usbfs-lifecycle.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="usbfs.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Life Cycle of User Mode Drivers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html> 307