1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="Linux-USB-API"> 6 <bookinfo> 7 <title>The Linux-USB Host Side API</title> 8 9 <legalnotice> 10 <para> 11 This documentation is free software; you can redistribute 12 it and/or modify it under the terms of the GNU General Public 13 License as published by the Free Software Foundation; either 14 version 2 of the License, or (at your option) any later 15 version. 16 </para> 17 18 <para> 19 This program is distributed in the hope that it will be 20 useful, but WITHOUT ANY WARRANTY; without even the implied 21 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 22 See the GNU General Public License for more details. 23 </para> 24 25 <para> 26 You should have received a copy of the GNU General Public 27 License along with this program; if not, write to the Free 28 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 29 MA 02111-1307 USA 30 </para> 31 32 <para> 33 For more details see the file COPYING in the source 34 distribution of Linux. 35 </para> 36 </legalnotice> 37 </bookinfo> 38 39<toc></toc> 40 41<chapter id="intro"> 42 <title>Introduction to USB on Linux</title> 43 44 <para>A Universal Serial Bus (USB) is used to connect a host, 45 such as a PC or workstation, to a number of peripheral 46 devices. USB uses a tree structure, with the host as the 47 root (the system's master), hubs as interior nodes, and 48 peripherals as leaves (and slaves). 49 Modern PCs support several such trees of USB devices, usually 50 one USB 2.0 tree (480 Mbit/sec each) with 51 a few USB 1.1 trees (12 Mbit/sec each) that are used when you 52 connect a USB 1.1 device directly to the machine's "root hub". 53 </para> 54 55 <para>That master/slave asymmetry was designed-in for a number of 56 reasons, one being ease of use. It is not physically possible to 57 assemble (legal) USB cables incorrectly: all upstream "to the host" 58 connectors are the rectangular type (matching the sockets on 59 root hubs), and all downstream connectors are the squarish type 60 (or they are built into the peripheral). 61 Also, the host software doesn't need to deal with distributed 62 auto-configuration since the pre-designated master node manages all that. 63 And finally, at the electrical level, bus protocol overhead is reduced by 64 eliminating arbitration and moving scheduling into the host software. 65 </para> 66 67 <para>USB 1.0 was announced in January 1996 and was revised 68 as USB 1.1 (with improvements in hub specification and 69 support for interrupt-out transfers) in September 1998. 70 USB 2.0 was released in April 2000, adding high-speed 71 transfers and transaction-translating hubs (used for USB 1.1 72 and 1.0 backward compatibility). 73 </para> 74 75 <para>Kernel developers added USB support to Linux early in the 2.2 kernel 76 series, shortly before 2.3 development forked. Updates from 2.3 were 77 regularly folded back into 2.2 releases, which improved reliability and 78 brought <filename>/sbin/hotplug</filename> support as well more drivers. 79 Such improvements were continued in the 2.5 kernel series, where they added 80 USB 2.0 support, improved performance, and made the host controller drivers 81 (HCDs) more consistent. They also simplified the API (to make bugs less 82 likely) and added internal "kerneldoc" documentation. 83 </para> 84 85 <para>Linux can run inside USB devices as well as on 86 the hosts that control the devices. 87 But USB device drivers running inside those peripherals 88 don't do the same things as the ones running inside hosts, 89 so they've been given a different name: 90 <emphasis>gadget drivers</emphasis>. 91 This document does not cover gadget drivers. 92 </para> 93 94 </chapter> 95 96<chapter id="host"> 97 <title>USB Host-Side API Model</title> 98 99 <para>Host-side drivers for USB devices talk to the "usbcore" APIs. 100 There are two. One is intended for 101 <emphasis>general-purpose</emphasis> drivers (exposed through 102 driver frameworks), and the other is for drivers that are 103 <emphasis>part of the core</emphasis>. 104 Such core drivers include the <emphasis>hub</emphasis> driver 105 (which manages trees of USB devices) and several different kinds 106 of <emphasis>host controller drivers</emphasis>, 107 which control individual busses. 108 </para> 109 110 <para>The device model seen by USB drivers is relatively complex. 111 </para> 112 113 <itemizedlist> 114 115 <listitem><para>USB supports four kinds of data transfers 116 (control, bulk, interrupt, and isochronous). Two of them (control 117 and bulk) use bandwidth as it's available, 118 while the other two (interrupt and isochronous) 119 are scheduled to provide guaranteed bandwidth. 120 </para></listitem> 121 122 <listitem><para>The device description model includes one or more 123 "configurations" per device, only one of which is active at a time. 124 Devices that are capable of high-speed operation must also support 125 full-speed configurations, along with a way to ask about the 126 "other speed" configurations which might be used. 127 </para></listitem> 128 129 <listitem><para>Configurations have one or more "interfaces", each 130 of which may have "alternate settings". Interfaces may be 131 standardized by USB "Class" specifications, or may be specific to 132 a vendor or device.</para> 133 134 <para>USB device drivers actually bind to interfaces, not devices. 135 Think of them as "interface drivers", though you 136 may not see many devices where the distinction is important. 137 <emphasis>Most USB devices are simple, with only one configuration, 138 one interface, and one alternate setting.</emphasis> 139 </para></listitem> 140 141 <listitem><para>Interfaces have one or more "endpoints", each of 142 which supports one type and direction of data transfer such as 143 "bulk out" or "interrupt in". The entire configuration may have 144 up to sixteen endpoints in each direction, allocated as needed 145 among all the interfaces. 146 </para></listitem> 147 148 <listitem><para>Data transfer on USB is packetized; each endpoint 149 has a maximum packet size. 150 Drivers must often be aware of conventions such as flagging the end 151 of bulk transfers using "short" (including zero length) packets. 152 </para></listitem> 153 154 <listitem><para>The Linux USB API supports synchronous calls for 155 control and bulk messages. 156 It also supports asynchronous calls for all kinds of data transfer, 157 using request structures called "URBs" (USB Request Blocks). 158 </para></listitem> 159 160 </itemizedlist> 161 162 <para>Accordingly, the USB Core API exposed to device drivers 163 covers quite a lot of territory. You'll probably need to consult 164 the USB 2.0 specification, available online from www.usb.org at 165 no cost, as well as class or device specifications. 166 </para> 167 168 <para>The only host-side drivers that actually touch hardware 169 (reading/writing registers, handling IRQs, and so on) are the HCDs. 170 In theory, all HCDs provide the same functionality through the same 171 API. In practice, that's becoming more true on the 2.5 kernels, 172 but there are still differences that crop up especially with 173 fault handling. Different controllers don't necessarily report 174 the same aspects of failures, and recovery from faults (including 175 software-induced ones like unlinking an URB) isn't yet fully 176 consistent. 177 Device driver authors should make a point of doing disconnect 178 testing (while the device is active) with each different host 179 controller driver, to make sure drivers don't have bugs of 180 their own as well as to make sure they aren't relying on some 181 HCD-specific behavior. 182 (You will need external USB 1.1 and/or 183 USB 2.0 hubs to perform all those tests.) 184 </para> 185 186 </chapter> 187 188<chapter id="types"><title>USB-Standard Types</title> 189 190 <para>In <filename><linux/usb/ch9.h></filename> you will find 191 the USB data types defined in chapter 9 of the USB specification. 192 These data types are used throughout USB, and in APIs including 193 this host side API, gadget APIs, and usbfs. 194 </para> 195 196<!-- include/linux/usb/ch9.h --> 197<refentry id="API-usb-speed-string"> 198<refentryinfo> 199 <title>LINUX</title> 200 <productname>Kernel Hackers Manual</productname> 201 <date>July 2017</date> 202</refentryinfo> 203<refmeta> 204 <refentrytitle><phrase>usb_speed_string</phrase></refentrytitle> 205 <manvolnum>9</manvolnum> 206 <refmiscinfo class="version">4.1.27</refmiscinfo> 207</refmeta> 208<refnamediv> 209 <refname>usb_speed_string</refname> 210 <refpurpose> 211 Returns human readable-name of the speed. 212 </refpurpose> 213</refnamediv> 214<refsynopsisdiv> 215 <title>Synopsis</title> 216 <funcsynopsis><funcprototype> 217 <funcdef>const char * <function>usb_speed_string </function></funcdef> 218 <paramdef>enum usb_device_speed <parameter>speed</parameter></paramdef> 219 </funcprototype></funcsynopsis> 220</refsynopsisdiv> 221<refsect1> 222 <title>Arguments</title> 223 <variablelist> 224 <varlistentry> 225 <term><parameter>speed</parameter></term> 226 <listitem> 227 <para> 228 The speed to return human-readable name for. If it's not 229 any of the speeds defined in usb_device_speed enum, string for 230 USB_SPEED_UNKNOWN will be returned. 231 </para> 232 </listitem> 233 </varlistentry> 234 </variablelist> 235</refsect1> 236</refentry> 237 238<refentry id="API-usb-state-string"> 239<refentryinfo> 240 <title>LINUX</title> 241 <productname>Kernel Hackers Manual</productname> 242 <date>July 2017</date> 243</refentryinfo> 244<refmeta> 245 <refentrytitle><phrase>usb_state_string</phrase></refentrytitle> 246 <manvolnum>9</manvolnum> 247 <refmiscinfo class="version">4.1.27</refmiscinfo> 248</refmeta> 249<refnamediv> 250 <refname>usb_state_string</refname> 251 <refpurpose> 252 Returns human readable name for the state. 253 </refpurpose> 254</refnamediv> 255<refsynopsisdiv> 256 <title>Synopsis</title> 257 <funcsynopsis><funcprototype> 258 <funcdef>const char * <function>usb_state_string </function></funcdef> 259 <paramdef>enum usb_device_state <parameter>state</parameter></paramdef> 260 </funcprototype></funcsynopsis> 261</refsynopsisdiv> 262<refsect1> 263 <title>Arguments</title> 264 <variablelist> 265 <varlistentry> 266 <term><parameter>state</parameter></term> 267 <listitem> 268 <para> 269 The state to return a human-readable name for. If it's not 270 any of the states devices in usb_device_state_string enum, 271 the string UNKNOWN will be returned. 272 </para> 273 </listitem> 274 </varlistentry> 275 </variablelist> 276</refsect1> 277</refentry> 278 279 280 </chapter> 281 282<chapter id="hostside"><title>Host-Side Data Types and Macros</title> 283 284 <para>The host side API exposes several layers to drivers, some of 285 which are more necessary than others. 286 These support lifecycle models for host side drivers 287 and devices, and support passing buffers through usbcore to 288 some HCD that performs the I/O for the device driver. 289 </para> 290 291 292<!-- include/linux/usb.h --> 293<refentry id="API-struct-usb-host-endpoint"> 294<refentryinfo> 295 <title>LINUX</title> 296 <productname>Kernel Hackers Manual</productname> 297 <date>July 2017</date> 298</refentryinfo> 299<refmeta> 300 <refentrytitle><phrase>struct usb_host_endpoint</phrase></refentrytitle> 301 <manvolnum>9</manvolnum> 302 <refmiscinfo class="version">4.1.27</refmiscinfo> 303</refmeta> 304<refnamediv> 305 <refname>struct usb_host_endpoint</refname> 306 <refpurpose> 307 host-side endpoint descriptor and queue 308 </refpurpose> 309</refnamediv> 310<refsynopsisdiv> 311 <title>Synopsis</title> 312 <programlisting> 313struct usb_host_endpoint { 314 struct usb_endpoint_descriptor desc; 315 struct usb_ss_ep_comp_descriptor ss_ep_comp; 316 struct list_head urb_list; 317 void * hcpriv; 318 struct ep_device * ep_dev; 319 unsigned char * extra; 320 int extralen; 321 int enabled; 322 int streams; 323}; </programlisting> 324</refsynopsisdiv> 325 <refsect1> 326 <title>Members</title> 327 <variablelist> 328 <varlistentry> <term>desc</term> 329 <listitem><para> 330descriptor for this endpoint, wMaxPacketSize in native byteorder 331 </para></listitem> 332 </varlistentry> 333 <varlistentry> <term>ss_ep_comp</term> 334 <listitem><para> 335SuperSpeed companion descriptor for this endpoint 336 </para></listitem> 337 </varlistentry> 338 <varlistentry> <term>urb_list</term> 339 <listitem><para> 340urbs queued to this endpoint; maintained by usbcore 341 </para></listitem> 342 </varlistentry> 343 <varlistentry> <term>hcpriv</term> 344 <listitem><para> 345for use by HCD; typically holds hardware dma queue head (QH) 346with one or more transfer descriptors (TDs) per urb 347 </para></listitem> 348 </varlistentry> 349 <varlistentry> <term>ep_dev</term> 350 <listitem><para> 351ep_device for sysfs info 352 </para></listitem> 353 </varlistentry> 354 <varlistentry> <term>extra</term> 355 <listitem><para> 356descriptors following this endpoint in the configuration 357 </para></listitem> 358 </varlistentry> 359 <varlistentry> <term>extralen</term> 360 <listitem><para> 361how many bytes of <quote>extra</quote> are valid 362 </para></listitem> 363 </varlistentry> 364 <varlistentry> <term>enabled</term> 365 <listitem><para> 366URBs may be submitted to this endpoint 367 </para></listitem> 368 </varlistentry> 369 <varlistentry> <term>streams</term> 370 <listitem><para> 371number of USB-3 streams allocated on the endpoint 372 </para></listitem> 373 </varlistentry> 374 </variablelist> 375 </refsect1> 376<refsect1> 377<title>Description</title> 378<para> 379 USB requests are always queued to a given endpoint, identified by a 380 descriptor within an active interface in a given USB configuration. 381</para> 382</refsect1> 383</refentry> 384 385<refentry id="API-struct-usb-interface"> 386<refentryinfo> 387 <title>LINUX</title> 388 <productname>Kernel Hackers Manual</productname> 389 <date>July 2017</date> 390</refentryinfo> 391<refmeta> 392 <refentrytitle><phrase>struct usb_interface</phrase></refentrytitle> 393 <manvolnum>9</manvolnum> 394 <refmiscinfo class="version">4.1.27</refmiscinfo> 395</refmeta> 396<refnamediv> 397 <refname>struct usb_interface</refname> 398 <refpurpose> 399 what usb device drivers talk to 400 </refpurpose> 401</refnamediv> 402<refsynopsisdiv> 403 <title>Synopsis</title> 404 <programlisting> 405struct usb_interface { 406 struct usb_host_interface * altsetting; 407 struct usb_host_interface * cur_altsetting; 408 unsigned num_altsetting; 409 struct usb_interface_assoc_descriptor * intf_assoc; 410 int minor; 411 enum usb_interface_condition condition; 412 unsigned sysfs_files_created:1; 413 unsigned ep_devs_created:1; 414 unsigned unregistering:1; 415 unsigned needs_remote_wakeup:1; 416 unsigned needs_altsetting0:1; 417 unsigned needs_binding:1; 418 unsigned resetting_device:1; 419 struct device dev; 420 struct device * usb_dev; 421 atomic_t pm_usage_cnt; 422 struct work_struct reset_ws; 423}; </programlisting> 424</refsynopsisdiv> 425 <refsect1> 426 <title>Members</title> 427 <variablelist> 428 <varlistentry> <term>altsetting</term> 429 <listitem><para> 430 array of interface structures, one for each alternate 431 setting that may be selected. Each one includes a set of 432 endpoint configurations. They will be in no particular order. 433 </para></listitem> 434 </varlistentry> 435 <varlistentry> <term>cur_altsetting</term> 436 <listitem><para> 437 the current altsetting. 438 </para></listitem> 439 </varlistentry> 440 <varlistentry> <term>num_altsetting</term> 441 <listitem><para> 442 number of altsettings defined. 443 </para></listitem> 444 </varlistentry> 445 <varlistentry> <term>intf_assoc</term> 446 <listitem><para> 447 interface association descriptor 448 </para></listitem> 449 </varlistentry> 450 <varlistentry> <term>minor</term> 451 <listitem><para> 452 the minor number assigned to this interface, if this 453 interface is bound to a driver that uses the USB major number. 454 If this interface does not use the USB major, this field should 455 be unused. The driver should set this value in the <function>probe</function> 456 function of the driver, after it has been assigned a minor 457 number from the USB core by calling <function>usb_register_dev</function>. 458 </para></listitem> 459 </varlistentry> 460 <varlistentry> <term>condition</term> 461 <listitem><para> 462 binding state of the interface: not bound, binding 463 (in <function>probe</function>), bound to a driver, or unbinding (in <function>disconnect</function>) 464 </para></listitem> 465 </varlistentry> 466 <varlistentry> <term>sysfs_files_created</term> 467 <listitem><para> 468 sysfs attributes exist 469 </para></listitem> 470 </varlistentry> 471 <varlistentry> <term>ep_devs_created</term> 472 <listitem><para> 473 endpoint child pseudo-devices exist 474 </para></listitem> 475 </varlistentry> 476 <varlistentry> <term>unregistering</term> 477 <listitem><para> 478 flag set when the interface is being unregistered 479 </para></listitem> 480 </varlistentry> 481 <varlistentry> <term>needs_remote_wakeup</term> 482 <listitem><para> 483 flag set when the driver requires remote-wakeup 484 capability during autosuspend. 485 </para></listitem> 486 </varlistentry> 487 <varlistentry> <term>needs_altsetting0</term> 488 <listitem><para> 489 flag set when a set-interface request for altsetting 0 490 has been deferred. 491 </para></listitem> 492 </varlistentry> 493 <varlistentry> <term>needs_binding</term> 494 <listitem><para> 495 flag set when the driver should be re-probed or unbound 496 following a reset or suspend operation it doesn't support. 497 </para></listitem> 498 </varlistentry> 499 <varlistentry> <term>resetting_device</term> 500 <listitem><para> 501 USB core reset the device, so use alt setting 0 as 502 current; needs bandwidth alloc after reset. 503 </para></listitem> 504 </varlistentry> 505 <varlistentry> <term>dev</term> 506 <listitem><para> 507 driver model's view of this device 508 </para></listitem> 509 </varlistentry> 510 <varlistentry> <term>usb_dev</term> 511 <listitem><para> 512 if an interface is bound to the USB major, this will point 513 to the sysfs representation for that device. 514 </para></listitem> 515 </varlistentry> 516 <varlistentry> <term>pm_usage_cnt</term> 517 <listitem><para> 518 PM usage counter for this interface 519 </para></listitem> 520 </varlistentry> 521 <varlistentry> <term>reset_ws</term> 522 <listitem><para> 523 Used for scheduling resets from atomic context. 524 </para></listitem> 525 </varlistentry> 526 </variablelist> 527 </refsect1> 528<refsect1> 529<title>Description</title> 530<para> 531 USB device drivers attach to interfaces on a physical device. Each 532 interface encapsulates a single high level function, such as feeding 533 an audio stream to a speaker or reporting a change in a volume control. 534 Many USB devices only have one interface. The protocol used to talk to 535 an interface's endpoints can be defined in a usb <quote>class</quote> specification, 536 or by a product's vendor. The (default) control endpoint is part of 537 every interface, but is never listed among the interface's descriptors. 538 </para><para> 539 540 The driver that is bound to the interface can use standard driver model 541 calls such as <function>dev_get_drvdata</function> on the dev member of this structure. 542 </para><para> 543 544 Each interface may have alternate settings. The initial configuration 545 of a device sets altsetting 0, but the device driver can change 546 that setting using <function>usb_set_interface</function>. Alternate settings are often 547 used to control the use of periodic endpoints, such as by having 548 different endpoints use different amounts of reserved USB bandwidth. 549 All standards-conformant USB devices that use isochronous endpoints 550 will use them in non-default settings. 551 </para><para> 552 553 The USB specification says that alternate setting numbers must run from 554 0 to one less than the total number of alternate settings. But some 555 devices manage to mess this up, and the structures aren't necessarily 556 stored in numerical order anyhow. Use <function>usb_altnum_to_altsetting</function> to 557 look up an alternate setting in the altsetting array based on its number. 558</para> 559</refsect1> 560</refentry> 561 562<refentry id="API-struct-usb-interface-cache"> 563<refentryinfo> 564 <title>LINUX</title> 565 <productname>Kernel Hackers Manual</productname> 566 <date>July 2017</date> 567</refentryinfo> 568<refmeta> 569 <refentrytitle><phrase>struct usb_interface_cache</phrase></refentrytitle> 570 <manvolnum>9</manvolnum> 571 <refmiscinfo class="version">4.1.27</refmiscinfo> 572</refmeta> 573<refnamediv> 574 <refname>struct usb_interface_cache</refname> 575 <refpurpose> 576 long-term representation of a device interface 577 </refpurpose> 578</refnamediv> 579<refsynopsisdiv> 580 <title>Synopsis</title> 581 <programlisting> 582struct usb_interface_cache { 583 unsigned num_altsetting; 584 struct kref ref; 585 struct usb_host_interface altsetting[0]; 586}; </programlisting> 587</refsynopsisdiv> 588 <refsect1> 589 <title>Members</title> 590 <variablelist> 591 <varlistentry> <term>num_altsetting</term> 592 <listitem><para> 593 number of altsettings defined. 594 </para></listitem> 595 </varlistentry> 596 <varlistentry> <term>ref</term> 597 <listitem><para> 598 reference counter. 599 </para></listitem> 600 </varlistentry> 601 <varlistentry> <term>altsetting[0]</term> 602 <listitem><para> 603 variable-length array of interface structures, one for 604 each alternate setting that may be selected. Each one includes a 605 set of endpoint configurations. They will be in no particular order. 606 </para></listitem> 607 </varlistentry> 608 </variablelist> 609 </refsect1> 610<refsect1> 611<title>Description</title> 612<para> 613 These structures persist for the lifetime of a usb_device, unlike 614 struct usb_interface (which persists only as long as its configuration 615 is installed). The altsetting arrays can be accessed through these 616 structures at any time, permitting comparison of configurations and 617 providing support for the /proc/bus/usb/devices pseudo-file. 618</para> 619</refsect1> 620</refentry> 621 622<refentry id="API-struct-usb-host-config"> 623<refentryinfo> 624 <title>LINUX</title> 625 <productname>Kernel Hackers Manual</productname> 626 <date>July 2017</date> 627</refentryinfo> 628<refmeta> 629 <refentrytitle><phrase>struct usb_host_config</phrase></refentrytitle> 630 <manvolnum>9</manvolnum> 631 <refmiscinfo class="version">4.1.27</refmiscinfo> 632</refmeta> 633<refnamediv> 634 <refname>struct usb_host_config</refname> 635 <refpurpose> 636 representation of a device's configuration 637 </refpurpose> 638</refnamediv> 639<refsynopsisdiv> 640 <title>Synopsis</title> 641 <programlisting> 642struct usb_host_config { 643 struct usb_config_descriptor desc; 644 char * string; 645 struct usb_interface_assoc_descriptor * intf_assoc[USB_MAXIADS]; 646 struct usb_interface * interface[USB_MAXINTERFACES]; 647 struct usb_interface_cache * intf_cache[USB_MAXINTERFACES]; 648 unsigned char * extra; 649 int extralen; 650}; </programlisting> 651</refsynopsisdiv> 652 <refsect1> 653 <title>Members</title> 654 <variablelist> 655 <varlistentry> <term>desc</term> 656 <listitem><para> 657 the device's configuration descriptor. 658 </para></listitem> 659 </varlistentry> 660 <varlistentry> <term>string</term> 661 <listitem><para> 662 pointer to the cached version of the iConfiguration string, if 663 present for this configuration. 664 </para></listitem> 665 </varlistentry> 666 <varlistentry> <term>intf_assoc[USB_MAXIADS]</term> 667 <listitem><para> 668 list of any interface association descriptors in this config 669 </para></listitem> 670 </varlistentry> 671 <varlistentry> <term>interface[USB_MAXINTERFACES]</term> 672 <listitem><para> 673 array of pointers to usb_interface structures, one for each 674 interface in the configuration. The number of interfaces is stored 675 in desc.bNumInterfaces. These pointers are valid only while the 676 the configuration is active. 677 </para></listitem> 678 </varlistentry> 679 <varlistentry> <term>intf_cache[USB_MAXINTERFACES]</term> 680 <listitem><para> 681 array of pointers to usb_interface_cache structures, one 682 for each interface in the configuration. These structures exist 683 for the entire life of the device. 684 </para></listitem> 685 </varlistentry> 686 <varlistentry> <term>extra</term> 687 <listitem><para> 688 pointer to buffer containing all extra descriptors associated 689 with this configuration (those preceding the first interface 690 descriptor). 691 </para></listitem> 692 </varlistentry> 693 <varlistentry> <term>extralen</term> 694 <listitem><para> 695 length of the extra descriptors buffer. 696 </para></listitem> 697 </varlistentry> 698 </variablelist> 699 </refsect1> 700<refsect1> 701<title>Description</title> 702<para> 703 USB devices may have multiple configurations, but only one can be active 704 at any time. Each encapsulates a different operational environment; 705 for example, a dual-speed device would have separate configurations for 706 full-speed and high-speed operation. The number of configurations 707 available is stored in the device descriptor as bNumConfigurations. 708 </para><para> 709 710 A configuration can contain multiple interfaces. Each corresponds to 711 a different function of the USB device, and all are available whenever 712 the configuration is active. The USB standard says that interfaces 713 are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot 714 of devices get this wrong. In addition, the interface array is not 715 guaranteed to be sorted in numerical order. Use <function>usb_ifnum_to_if</function> to 716 look up an interface entry based on its number. 717 </para><para> 718 719 Device drivers should not attempt to activate configurations. The choice 720 of which configuration to install is a policy decision based on such 721 considerations as available power, functionality provided, and the user's 722 desires (expressed through userspace tools). However, drivers can call 723 <function>usb_reset_configuration</function> to reinitialize the current configuration and 724 all its interfaces. 725</para> 726</refsect1> 727</refentry> 728 729<refentry id="API-struct-usb-device"> 730<refentryinfo> 731 <title>LINUX</title> 732 <productname>Kernel Hackers Manual</productname> 733 <date>July 2017</date> 734</refentryinfo> 735<refmeta> 736 <refentrytitle><phrase>struct usb_device</phrase></refentrytitle> 737 <manvolnum>9</manvolnum> 738 <refmiscinfo class="version">4.1.27</refmiscinfo> 739</refmeta> 740<refnamediv> 741 <refname>struct usb_device</refname> 742 <refpurpose> 743 kernel's representation of a USB device 744 </refpurpose> 745</refnamediv> 746<refsynopsisdiv> 747 <title>Synopsis</title> 748 <programlisting> 749struct usb_device { 750 int devnum; 751 char devpath[16]; 752 u32 route; 753 enum usb_device_state state; 754 enum usb_device_speed speed; 755 struct usb_tt * tt; 756 int ttport; 757 unsigned int toggle[2]; 758 struct usb_device * parent; 759 struct usb_bus * bus; 760 struct usb_host_endpoint ep0; 761 struct device dev; 762 struct usb_device_descriptor descriptor; 763 struct usb_host_bos * bos; 764 struct usb_host_config * config; 765 struct usb_host_config * actconfig; 766 struct usb_host_endpoint * ep_in[16]; 767 struct usb_host_endpoint * ep_out[16]; 768 char ** rawdescriptors; 769 unsigned short bus_mA; 770 u8 portnum; 771 u8 level; 772 unsigned can_submit:1; 773 unsigned persist_enabled:1; 774 unsigned have_langid:1; 775 unsigned authorized:1; 776 unsigned authenticated:1; 777 unsigned wusb:1; 778 unsigned lpm_capable:1; 779 unsigned usb2_hw_lpm_capable:1; 780 unsigned usb2_hw_lpm_besl_capable:1; 781 unsigned usb2_hw_lpm_enabled:1; 782 unsigned usb2_hw_lpm_allowed:1; 783 unsigned usb3_lpm_enabled:1; 784 int string_langid; 785 char * product; 786 char * manufacturer; 787 char * serial; 788 struct list_head filelist; 789 int maxchild; 790 u32 quirks; 791 atomic_t urbnum; 792 unsigned long active_duration; 793#ifdef CONFIG_PM 794 unsigned long connect_time; 795 unsigned do_remote_wakeup:1; 796 unsigned reset_resume:1; 797 unsigned port_is_suspended:1; 798#endif 799 struct wusb_dev * wusb_dev; 800 int slot_id; 801 enum usb_device_removable removable; 802 struct usb2_lpm_parameters l1_params; 803 struct usb3_lpm_parameters u1_params; 804 struct usb3_lpm_parameters u2_params; 805 unsigned lpm_disable_count; 806}; </programlisting> 807</refsynopsisdiv> 808 <refsect1> 809 <title>Members</title> 810 <variablelist> 811 <varlistentry> <term>devnum</term> 812 <listitem><para> 813 device number; address on a USB bus 814 </para></listitem> 815 </varlistentry> 816 <varlistentry> <term>devpath[16]</term> 817 <listitem><para> 818 device ID string for use in messages (e.g., /port/...) 819 </para></listitem> 820 </varlistentry> 821 <varlistentry> <term>route</term> 822 <listitem><para> 823 tree topology hex string for use with xHCI 824 </para></listitem> 825 </varlistentry> 826 <varlistentry> <term>state</term> 827 <listitem><para> 828 device state: configured, not attached, etc. 829 </para></listitem> 830 </varlistentry> 831 <varlistentry> <term>speed</term> 832 <listitem><para> 833 device speed: high/full/low (or error) 834 </para></listitem> 835 </varlistentry> 836 <varlistentry> <term>tt</term> 837 <listitem><para> 838 Transaction Translator info; used with low/full speed dev, highspeed hub 839 </para></listitem> 840 </varlistentry> 841 <varlistentry> <term>ttport</term> 842 <listitem><para> 843 device port on that tt hub 844 </para></listitem> 845 </varlistentry> 846 <varlistentry> <term>toggle[2]</term> 847 <listitem><para> 848 one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints 849 </para></listitem> 850 </varlistentry> 851 <varlistentry> <term>parent</term> 852 <listitem><para> 853 our hub, unless we're the root 854 </para></listitem> 855 </varlistentry> 856 <varlistentry> <term>bus</term> 857 <listitem><para> 858 bus we're part of 859 </para></listitem> 860 </varlistentry> 861 <varlistentry> <term>ep0</term> 862 <listitem><para> 863 endpoint 0 data (default control pipe) 864 </para></listitem> 865 </varlistentry> 866 <varlistentry> <term>dev</term> 867 <listitem><para> 868 generic device interface 869 </para></listitem> 870 </varlistentry> 871 <varlistentry> <term>descriptor</term> 872 <listitem><para> 873 USB device descriptor 874 </para></listitem> 875 </varlistentry> 876 <varlistentry> <term>bos</term> 877 <listitem><para> 878 USB device BOS descriptor set 879 </para></listitem> 880 </varlistentry> 881 <varlistentry> <term>config</term> 882 <listitem><para> 883 all of the device's configs 884 </para></listitem> 885 </varlistentry> 886 <varlistentry> <term>actconfig</term> 887 <listitem><para> 888 the active configuration 889 </para></listitem> 890 </varlistentry> 891 <varlistentry> <term>ep_in[16]</term> 892 <listitem><para> 893 array of IN endpoints 894 </para></listitem> 895 </varlistentry> 896 <varlistentry> <term>ep_out[16]</term> 897 <listitem><para> 898 array of OUT endpoints 899 </para></listitem> 900 </varlistentry> 901 <varlistentry> <term>rawdescriptors</term> 902 <listitem><para> 903 raw descriptors for each config 904 </para></listitem> 905 </varlistentry> 906 <varlistentry> <term>bus_mA</term> 907 <listitem><para> 908 Current available from the bus 909 </para></listitem> 910 </varlistentry> 911 <varlistentry> <term>portnum</term> 912 <listitem><para> 913 parent port number (origin 1) 914 </para></listitem> 915 </varlistentry> 916 <varlistentry> <term>level</term> 917 <listitem><para> 918 number of USB hub ancestors 919 </para></listitem> 920 </varlistentry> 921 <varlistentry> <term>can_submit</term> 922 <listitem><para> 923 URBs may be submitted 924 </para></listitem> 925 </varlistentry> 926 <varlistentry> <term>persist_enabled</term> 927 <listitem><para> 928 USB_PERSIST enabled for this device 929 </para></listitem> 930 </varlistentry> 931 <varlistentry> <term>have_langid</term> 932 <listitem><para> 933 whether string_langid is valid 934 </para></listitem> 935 </varlistentry> 936 <varlistentry> <term>authorized</term> 937 <listitem><para> 938 policy has said we can use it; 939 (user space) policy determines if we authorize this device to be 940 used or not. By default, wired USB devices are authorized. 941 WUSB devices are not, until we authorize them from user space. 942 FIXME -- complete doc 943 </para></listitem> 944 </varlistentry> 945 <varlistentry> <term>authenticated</term> 946 <listitem><para> 947 Crypto authentication passed 948 </para></listitem> 949 </varlistentry> 950 <varlistentry> <term>wusb</term> 951 <listitem><para> 952 device is Wireless USB 953 </para></listitem> 954 </varlistentry> 955 <varlistentry> <term>lpm_capable</term> 956 <listitem><para> 957 device supports LPM 958 </para></listitem> 959 </varlistentry> 960 <varlistentry> <term>usb2_hw_lpm_capable</term> 961 <listitem><para> 962 device can perform USB2 hardware LPM 963 </para></listitem> 964 </varlistentry> 965 <varlistentry> <term>usb2_hw_lpm_besl_capable</term> 966 <listitem><para> 967 device can perform USB2 hardware BESL LPM 968 </para></listitem> 969 </varlistentry> 970 <varlistentry> <term>usb2_hw_lpm_enabled</term> 971 <listitem><para> 972 USB2 hardware LPM is enabled 973 </para></listitem> 974 </varlistentry> 975 <varlistentry> <term>usb2_hw_lpm_allowed</term> 976 <listitem><para> 977 Userspace allows USB 2.0 LPM to be enabled 978 </para></listitem> 979 </varlistentry> 980 <varlistentry> <term>usb3_lpm_enabled</term> 981 <listitem><para> 982 USB3 hardware LPM enabled 983 </para></listitem> 984 </varlistentry> 985 <varlistentry> <term>string_langid</term> 986 <listitem><para> 987 language ID for strings 988 </para></listitem> 989 </varlistentry> 990 <varlistentry> <term>product</term> 991 <listitem><para> 992 iProduct string, if present (static) 993 </para></listitem> 994 </varlistentry> 995 <varlistentry> <term>manufacturer</term> 996 <listitem><para> 997 iManufacturer string, if present (static) 998 </para></listitem> 999 </varlistentry> 1000 <varlistentry> <term>serial</term> 1001 <listitem><para> 1002 iSerialNumber string, if present (static) 1003 </para></listitem> 1004 </varlistentry> 1005 <varlistentry> <term>filelist</term> 1006 <listitem><para> 1007 usbfs files that are open to this device 1008 </para></listitem> 1009 </varlistentry> 1010 <varlistentry> <term>maxchild</term> 1011 <listitem><para> 1012 number of ports if hub 1013 </para></listitem> 1014 </varlistentry> 1015 <varlistentry> <term>quirks</term> 1016 <listitem><para> 1017 quirks of the whole device 1018 </para></listitem> 1019 </varlistentry> 1020 <varlistentry> <term>urbnum</term> 1021 <listitem><para> 1022 number of URBs submitted for the whole device 1023 </para></listitem> 1024 </varlistentry> 1025 <varlistentry> <term>active_duration</term> 1026 <listitem><para> 1027 total time device is not suspended 1028 </para></listitem> 1029 </varlistentry> 1030 <varlistentry> <term>connect_time</term> 1031 <listitem><para> 1032 time device was first connected 1033 </para></listitem> 1034 </varlistentry> 1035 <varlistentry> <term>do_remote_wakeup</term> 1036 <listitem><para> 1037 remote wakeup should be enabled 1038 </para></listitem> 1039 </varlistentry> 1040 <varlistentry> <term>reset_resume</term> 1041 <listitem><para> 1042 needs reset instead of resume 1043 </para></listitem> 1044 </varlistentry> 1045 <varlistentry> <term>port_is_suspended</term> 1046 <listitem><para> 1047 the upstream port is suspended (L2 or U3) 1048 </para></listitem> 1049 </varlistentry> 1050 <varlistentry> <term>wusb_dev</term> 1051 <listitem><para> 1052 if this is a Wireless USB device, link to the WUSB 1053 specific data for the device. 1054 </para></listitem> 1055 </varlistentry> 1056 <varlistentry> <term>slot_id</term> 1057 <listitem><para> 1058 Slot ID assigned by xHCI 1059 </para></listitem> 1060 </varlistentry> 1061 <varlistentry> <term>removable</term> 1062 <listitem><para> 1063 Device can be physically removed from this port 1064 </para></listitem> 1065 </varlistentry> 1066 <varlistentry> <term>l1_params</term> 1067 <listitem><para> 1068 best effor service latency for USB2 L1 LPM state, and L1 timeout. 1069 </para></listitem> 1070 </varlistentry> 1071 <varlistentry> <term>u1_params</term> 1072 <listitem><para> 1073 exit latencies for USB3 U1 LPM state, and hub-initiated timeout. 1074 </para></listitem> 1075 </varlistentry> 1076 <varlistentry> <term>u2_params</term> 1077 <listitem><para> 1078 exit latencies for USB3 U2 LPM state, and hub-initiated timeout. 1079 </para></listitem> 1080 </varlistentry> 1081 <varlistentry> <term>lpm_disable_count</term> 1082 <listitem><para> 1083 Ref count used by <function>usb_disable_lpm</function> and <function>usb_enable_lpm</function> 1084 to keep track of the number of functions that require USB 3.0 Link Power 1085 Management to be disabled for this usb_device. This count should only 1086 be manipulated by those functions, with the bandwidth_mutex is held. 1087 </para></listitem> 1088 </varlistentry> 1089 </variablelist> 1090 </refsect1> 1091<refsect1> 1092<title>Notes</title> 1093<para> 1094 Usbcore drivers should not set usbdev->state directly. Instead use 1095 <function>usb_set_device_state</function>. 1096</para> 1097</refsect1> 1098</refentry> 1099 1100<refentry id="API-usb-hub-for-each-child"> 1101<refentryinfo> 1102 <title>LINUX</title> 1103 <productname>Kernel Hackers Manual</productname> 1104 <date>July 2017</date> 1105</refentryinfo> 1106<refmeta> 1107 <refentrytitle><phrase>usb_hub_for_each_child</phrase></refentrytitle> 1108 <manvolnum>9</manvolnum> 1109 <refmiscinfo class="version">4.1.27</refmiscinfo> 1110</refmeta> 1111<refnamediv> 1112 <refname>usb_hub_for_each_child</refname> 1113 <refpurpose> 1114 iterate over all child devices on the hub 1115 </refpurpose> 1116</refnamediv> 1117<refsynopsisdiv> 1118 <title>Synopsis</title> 1119 <funcsynopsis><funcprototype> 1120 <funcdef> <function>usb_hub_for_each_child </function></funcdef> 1121 <paramdef> <parameter>hdev</parameter></paramdef> 1122 <paramdef> <parameter>port1</parameter></paramdef> 1123 <paramdef> <parameter>child</parameter></paramdef> 1124 </funcprototype></funcsynopsis> 1125</refsynopsisdiv> 1126<refsect1> 1127 <title>Arguments</title> 1128 <variablelist> 1129 <varlistentry> 1130 <term><parameter>hdev</parameter></term> 1131 <listitem> 1132 <para> 1133 USB device belonging to the usb hub 1134 </para> 1135 </listitem> 1136 </varlistentry> 1137 <varlistentry> 1138 <term><parameter>port1</parameter></term> 1139 <listitem> 1140 <para> 1141 portnum associated with child device 1142 </para> 1143 </listitem> 1144 </varlistentry> 1145 <varlistentry> 1146 <term><parameter>child</parameter></term> 1147 <listitem> 1148 <para> 1149 child device pointer 1150 </para> 1151 </listitem> 1152 </varlistentry> 1153 </variablelist> 1154</refsect1> 1155</refentry> 1156 1157<refentry id="API-usb-interface-claimed"> 1158<refentryinfo> 1159 <title>LINUX</title> 1160 <productname>Kernel Hackers Manual</productname> 1161 <date>July 2017</date> 1162</refentryinfo> 1163<refmeta> 1164 <refentrytitle><phrase>usb_interface_claimed</phrase></refentrytitle> 1165 <manvolnum>9</manvolnum> 1166 <refmiscinfo class="version">4.1.27</refmiscinfo> 1167</refmeta> 1168<refnamediv> 1169 <refname>usb_interface_claimed</refname> 1170 <refpurpose> 1171 returns true iff an interface is claimed 1172 </refpurpose> 1173</refnamediv> 1174<refsynopsisdiv> 1175 <title>Synopsis</title> 1176 <funcsynopsis><funcprototype> 1177 <funcdef>int <function>usb_interface_claimed </function></funcdef> 1178 <paramdef>struct usb_interface * <parameter>iface</parameter></paramdef> 1179 </funcprototype></funcsynopsis> 1180</refsynopsisdiv> 1181<refsect1> 1182 <title>Arguments</title> 1183 <variablelist> 1184 <varlistentry> 1185 <term><parameter>iface</parameter></term> 1186 <listitem> 1187 <para> 1188 the interface being checked 1189 </para> 1190 </listitem> 1191 </varlistentry> 1192 </variablelist> 1193</refsect1> 1194<refsect1> 1195<title>Return</title> 1196<para> 1197 <constant>true</constant> (nonzero) iff the interface is claimed, else <constant>false</constant> 1198 (zero). 1199</para> 1200</refsect1> 1201<refsect1> 1202<title>Note</title> 1203<para> 1204 Callers must own the driver model's usb bus readlock. So driver 1205 <function>probe</function> entries don't need extra locking, but other call contexts 1206 may need to explicitly claim that lock. 1207</para> 1208</refsect1> 1209</refentry> 1210 1211<refentry id="API-usb-make-path"> 1212<refentryinfo> 1213 <title>LINUX</title> 1214 <productname>Kernel Hackers Manual</productname> 1215 <date>July 2017</date> 1216</refentryinfo> 1217<refmeta> 1218 <refentrytitle><phrase>usb_make_path</phrase></refentrytitle> 1219 <manvolnum>9</manvolnum> 1220 <refmiscinfo class="version">4.1.27</refmiscinfo> 1221</refmeta> 1222<refnamediv> 1223 <refname>usb_make_path</refname> 1224 <refpurpose> 1225 returns stable device path in the usb tree 1226 </refpurpose> 1227</refnamediv> 1228<refsynopsisdiv> 1229 <title>Synopsis</title> 1230 <funcsynopsis><funcprototype> 1231 <funcdef>int <function>usb_make_path </function></funcdef> 1232 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 1233 <paramdef>char * <parameter>buf</parameter></paramdef> 1234 <paramdef>size_t <parameter>size</parameter></paramdef> 1235 </funcprototype></funcsynopsis> 1236</refsynopsisdiv> 1237<refsect1> 1238 <title>Arguments</title> 1239 <variablelist> 1240 <varlistentry> 1241 <term><parameter>dev</parameter></term> 1242 <listitem> 1243 <para> 1244 the device whose path is being constructed 1245 </para> 1246 </listitem> 1247 </varlistentry> 1248 <varlistentry> 1249 <term><parameter>buf</parameter></term> 1250 <listitem> 1251 <para> 1252 where to put the string 1253 </para> 1254 </listitem> 1255 </varlistentry> 1256 <varlistentry> 1257 <term><parameter>size</parameter></term> 1258 <listitem> 1259 <para> 1260 how big is <quote>buf</quote>? 1261 </para> 1262 </listitem> 1263 </varlistentry> 1264 </variablelist> 1265</refsect1> 1266<refsect1> 1267<title>Return</title> 1268<para> 1269 Length of the string (> 0) or negative if size was too small. 1270</para> 1271</refsect1> 1272<refsect1> 1273<title>Note</title> 1274<para> 1275 This identifier is intended to be <quote>stable</quote>, reflecting physical paths in 1276 hardware such as physical bus addresses for host controllers or ports on 1277 USB hubs. That makes it stay the same until systems are physically 1278 reconfigured, by re-cabling a tree of USB devices or by moving USB host 1279 controllers. Adding and removing devices, including virtual root hubs 1280 in host controller driver modules, does not change these path identifiers; 1281 neither does rebooting or re-enumerating. These are more useful identifiers 1282 than changeable (<quote>unstable</quote>) ones like bus numbers or device addresses. 1283 </para><para> 1284 1285 With a partial exception for devices connected to USB 2.0 root hubs, these 1286 identifiers are also predictable. So long as the device tree isn't changed, 1287 plugging any USB device into a given hub port always gives it the same path. 1288 Because of the use of <quote>companion</quote> controllers, devices connected to ports on 1289 USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are 1290 high speed, and a different one if they are full or low speed. 1291</para> 1292</refsect1> 1293</refentry> 1294 1295<refentry id="API-USB-DEVICE"> 1296<refentryinfo> 1297 <title>LINUX</title> 1298 <productname>Kernel Hackers Manual</productname> 1299 <date>July 2017</date> 1300</refentryinfo> 1301<refmeta> 1302 <refentrytitle><phrase>USB_DEVICE</phrase></refentrytitle> 1303 <manvolnum>9</manvolnum> 1304 <refmiscinfo class="version">4.1.27</refmiscinfo> 1305</refmeta> 1306<refnamediv> 1307 <refname>USB_DEVICE</refname> 1308 <refpurpose> 1309 macro used to describe a specific usb device 1310 </refpurpose> 1311</refnamediv> 1312<refsynopsisdiv> 1313 <title>Synopsis</title> 1314 <funcsynopsis><funcprototype> 1315 <funcdef> <function>USB_DEVICE </function></funcdef> 1316 <paramdef> <parameter>vend</parameter></paramdef> 1317 <paramdef> <parameter>prod</parameter></paramdef> 1318 </funcprototype></funcsynopsis> 1319</refsynopsisdiv> 1320<refsect1> 1321 <title>Arguments</title> 1322 <variablelist> 1323 <varlistentry> 1324 <term><parameter>vend</parameter></term> 1325 <listitem> 1326 <para> 1327 the 16 bit USB Vendor ID 1328 </para> 1329 </listitem> 1330 </varlistentry> 1331 <varlistentry> 1332 <term><parameter>prod</parameter></term> 1333 <listitem> 1334 <para> 1335 the 16 bit USB Product ID 1336 </para> 1337 </listitem> 1338 </varlistentry> 1339 </variablelist> 1340</refsect1> 1341<refsect1> 1342<title>Description</title> 1343<para> 1344 This macro is used to create a struct usb_device_id that matches a 1345 specific device. 1346</para> 1347</refsect1> 1348</refentry> 1349 1350<refentry id="API-USB-DEVICE-VER"> 1351<refentryinfo> 1352 <title>LINUX</title> 1353 <productname>Kernel Hackers Manual</productname> 1354 <date>July 2017</date> 1355</refentryinfo> 1356<refmeta> 1357 <refentrytitle><phrase>USB_DEVICE_VER</phrase></refentrytitle> 1358 <manvolnum>9</manvolnum> 1359 <refmiscinfo class="version">4.1.27</refmiscinfo> 1360</refmeta> 1361<refnamediv> 1362 <refname>USB_DEVICE_VER</refname> 1363 <refpurpose> 1364 describe a specific usb device with a version range 1365 </refpurpose> 1366</refnamediv> 1367<refsynopsisdiv> 1368 <title>Synopsis</title> 1369 <funcsynopsis><funcprototype> 1370 <funcdef> <function>USB_DEVICE_VER </function></funcdef> 1371 <paramdef> <parameter>vend</parameter></paramdef> 1372 <paramdef> <parameter>prod</parameter></paramdef> 1373 <paramdef> <parameter>lo</parameter></paramdef> 1374 <paramdef> <parameter>hi</parameter></paramdef> 1375 </funcprototype></funcsynopsis> 1376</refsynopsisdiv> 1377<refsect1> 1378 <title>Arguments</title> 1379 <variablelist> 1380 <varlistentry> 1381 <term><parameter>vend</parameter></term> 1382 <listitem> 1383 <para> 1384 the 16 bit USB Vendor ID 1385 </para> 1386 </listitem> 1387 </varlistentry> 1388 <varlistentry> 1389 <term><parameter>prod</parameter></term> 1390 <listitem> 1391 <para> 1392 the 16 bit USB Product ID 1393 </para> 1394 </listitem> 1395 </varlistentry> 1396 <varlistentry> 1397 <term><parameter>lo</parameter></term> 1398 <listitem> 1399 <para> 1400 the bcdDevice_lo value 1401 </para> 1402 </listitem> 1403 </varlistentry> 1404 <varlistentry> 1405 <term><parameter>hi</parameter></term> 1406 <listitem> 1407 <para> 1408 the bcdDevice_hi value 1409 </para> 1410 </listitem> 1411 </varlistentry> 1412 </variablelist> 1413</refsect1> 1414<refsect1> 1415<title>Description</title> 1416<para> 1417 This macro is used to create a struct usb_device_id that matches a 1418 specific device, with a version range. 1419</para> 1420</refsect1> 1421</refentry> 1422 1423<refentry id="API-USB-DEVICE-INTERFACE-CLASS"> 1424<refentryinfo> 1425 <title>LINUX</title> 1426 <productname>Kernel Hackers Manual</productname> 1427 <date>July 2017</date> 1428</refentryinfo> 1429<refmeta> 1430 <refentrytitle><phrase>USB_DEVICE_INTERFACE_CLASS</phrase></refentrytitle> 1431 <manvolnum>9</manvolnum> 1432 <refmiscinfo class="version">4.1.27</refmiscinfo> 1433</refmeta> 1434<refnamediv> 1435 <refname>USB_DEVICE_INTERFACE_CLASS</refname> 1436 <refpurpose> 1437 describe a usb device with a specific interface class 1438 </refpurpose> 1439</refnamediv> 1440<refsynopsisdiv> 1441 <title>Synopsis</title> 1442 <funcsynopsis><funcprototype> 1443 <funcdef> <function>USB_DEVICE_INTERFACE_CLASS </function></funcdef> 1444 <paramdef> <parameter>vend</parameter></paramdef> 1445 <paramdef> <parameter>prod</parameter></paramdef> 1446 <paramdef> <parameter>cl</parameter></paramdef> 1447 </funcprototype></funcsynopsis> 1448</refsynopsisdiv> 1449<refsect1> 1450 <title>Arguments</title> 1451 <variablelist> 1452 <varlistentry> 1453 <term><parameter>vend</parameter></term> 1454 <listitem> 1455 <para> 1456 the 16 bit USB Vendor ID 1457 </para> 1458 </listitem> 1459 </varlistentry> 1460 <varlistentry> 1461 <term><parameter>prod</parameter></term> 1462 <listitem> 1463 <para> 1464 the 16 bit USB Product ID 1465 </para> 1466 </listitem> 1467 </varlistentry> 1468 <varlistentry> 1469 <term><parameter>cl</parameter></term> 1470 <listitem> 1471 <para> 1472 bInterfaceClass value 1473 </para> 1474 </listitem> 1475 </varlistentry> 1476 </variablelist> 1477</refsect1> 1478<refsect1> 1479<title>Description</title> 1480<para> 1481 This macro is used to create a struct usb_device_id that matches a 1482 specific interface class of devices. 1483</para> 1484</refsect1> 1485</refentry> 1486 1487<refentry id="API-USB-DEVICE-INTERFACE-PROTOCOL"> 1488<refentryinfo> 1489 <title>LINUX</title> 1490 <productname>Kernel Hackers Manual</productname> 1491 <date>July 2017</date> 1492</refentryinfo> 1493<refmeta> 1494 <refentrytitle><phrase>USB_DEVICE_INTERFACE_PROTOCOL</phrase></refentrytitle> 1495 <manvolnum>9</manvolnum> 1496 <refmiscinfo class="version">4.1.27</refmiscinfo> 1497</refmeta> 1498<refnamediv> 1499 <refname>USB_DEVICE_INTERFACE_PROTOCOL</refname> 1500 <refpurpose> 1501 describe a usb device with a specific interface protocol 1502 </refpurpose> 1503</refnamediv> 1504<refsynopsisdiv> 1505 <title>Synopsis</title> 1506 <funcsynopsis><funcprototype> 1507 <funcdef> <function>USB_DEVICE_INTERFACE_PROTOCOL </function></funcdef> 1508 <paramdef> <parameter>vend</parameter></paramdef> 1509 <paramdef> <parameter>prod</parameter></paramdef> 1510 <paramdef> <parameter>pr</parameter></paramdef> 1511 </funcprototype></funcsynopsis> 1512</refsynopsisdiv> 1513<refsect1> 1514 <title>Arguments</title> 1515 <variablelist> 1516 <varlistentry> 1517 <term><parameter>vend</parameter></term> 1518 <listitem> 1519 <para> 1520 the 16 bit USB Vendor ID 1521 </para> 1522 </listitem> 1523 </varlistentry> 1524 <varlistentry> 1525 <term><parameter>prod</parameter></term> 1526 <listitem> 1527 <para> 1528 the 16 bit USB Product ID 1529 </para> 1530 </listitem> 1531 </varlistentry> 1532 <varlistentry> 1533 <term><parameter>pr</parameter></term> 1534 <listitem> 1535 <para> 1536 bInterfaceProtocol value 1537 </para> 1538 </listitem> 1539 </varlistentry> 1540 </variablelist> 1541</refsect1> 1542<refsect1> 1543<title>Description</title> 1544<para> 1545 This macro is used to create a struct usb_device_id that matches a 1546 specific interface protocol of devices. 1547</para> 1548</refsect1> 1549</refentry> 1550 1551<refentry id="API-USB-DEVICE-INTERFACE-NUMBER"> 1552<refentryinfo> 1553 <title>LINUX</title> 1554 <productname>Kernel Hackers Manual</productname> 1555 <date>July 2017</date> 1556</refentryinfo> 1557<refmeta> 1558 <refentrytitle><phrase>USB_DEVICE_INTERFACE_NUMBER</phrase></refentrytitle> 1559 <manvolnum>9</manvolnum> 1560 <refmiscinfo class="version">4.1.27</refmiscinfo> 1561</refmeta> 1562<refnamediv> 1563 <refname>USB_DEVICE_INTERFACE_NUMBER</refname> 1564 <refpurpose> 1565 describe a usb device with a specific interface number 1566 </refpurpose> 1567</refnamediv> 1568<refsynopsisdiv> 1569 <title>Synopsis</title> 1570 <funcsynopsis><funcprototype> 1571 <funcdef> <function>USB_DEVICE_INTERFACE_NUMBER </function></funcdef> 1572 <paramdef> <parameter>vend</parameter></paramdef> 1573 <paramdef> <parameter>prod</parameter></paramdef> 1574 <paramdef> <parameter>num</parameter></paramdef> 1575 </funcprototype></funcsynopsis> 1576</refsynopsisdiv> 1577<refsect1> 1578 <title>Arguments</title> 1579 <variablelist> 1580 <varlistentry> 1581 <term><parameter>vend</parameter></term> 1582 <listitem> 1583 <para> 1584 the 16 bit USB Vendor ID 1585 </para> 1586 </listitem> 1587 </varlistentry> 1588 <varlistentry> 1589 <term><parameter>prod</parameter></term> 1590 <listitem> 1591 <para> 1592 the 16 bit USB Product ID 1593 </para> 1594 </listitem> 1595 </varlistentry> 1596 <varlistentry> 1597 <term><parameter>num</parameter></term> 1598 <listitem> 1599 <para> 1600 bInterfaceNumber value 1601 </para> 1602 </listitem> 1603 </varlistentry> 1604 </variablelist> 1605</refsect1> 1606<refsect1> 1607<title>Description</title> 1608<para> 1609 This macro is used to create a struct usb_device_id that matches a 1610 specific interface number of devices. 1611</para> 1612</refsect1> 1613</refentry> 1614 1615<refentry id="API-USB-DEVICE-INFO"> 1616<refentryinfo> 1617 <title>LINUX</title> 1618 <productname>Kernel Hackers Manual</productname> 1619 <date>July 2017</date> 1620</refentryinfo> 1621<refmeta> 1622 <refentrytitle><phrase>USB_DEVICE_INFO</phrase></refentrytitle> 1623 <manvolnum>9</manvolnum> 1624 <refmiscinfo class="version">4.1.27</refmiscinfo> 1625</refmeta> 1626<refnamediv> 1627 <refname>USB_DEVICE_INFO</refname> 1628 <refpurpose> 1629 macro used to describe a class of usb devices 1630 </refpurpose> 1631</refnamediv> 1632<refsynopsisdiv> 1633 <title>Synopsis</title> 1634 <funcsynopsis><funcprototype> 1635 <funcdef> <function>USB_DEVICE_INFO </function></funcdef> 1636 <paramdef> <parameter>cl</parameter></paramdef> 1637 <paramdef> <parameter>sc</parameter></paramdef> 1638 <paramdef> <parameter>pr</parameter></paramdef> 1639 </funcprototype></funcsynopsis> 1640</refsynopsisdiv> 1641<refsect1> 1642 <title>Arguments</title> 1643 <variablelist> 1644 <varlistentry> 1645 <term><parameter>cl</parameter></term> 1646 <listitem> 1647 <para> 1648 bDeviceClass value 1649 </para> 1650 </listitem> 1651 </varlistentry> 1652 <varlistentry> 1653 <term><parameter>sc</parameter></term> 1654 <listitem> 1655 <para> 1656 bDeviceSubClass value 1657 </para> 1658 </listitem> 1659 </varlistentry> 1660 <varlistentry> 1661 <term><parameter>pr</parameter></term> 1662 <listitem> 1663 <para> 1664 bDeviceProtocol value 1665 </para> 1666 </listitem> 1667 </varlistentry> 1668 </variablelist> 1669</refsect1> 1670<refsect1> 1671<title>Description</title> 1672<para> 1673 This macro is used to create a struct usb_device_id that matches a 1674 specific class of devices. 1675</para> 1676</refsect1> 1677</refentry> 1678 1679<refentry id="API-USB-INTERFACE-INFO"> 1680<refentryinfo> 1681 <title>LINUX</title> 1682 <productname>Kernel Hackers Manual</productname> 1683 <date>July 2017</date> 1684</refentryinfo> 1685<refmeta> 1686 <refentrytitle><phrase>USB_INTERFACE_INFO</phrase></refentrytitle> 1687 <manvolnum>9</manvolnum> 1688 <refmiscinfo class="version">4.1.27</refmiscinfo> 1689</refmeta> 1690<refnamediv> 1691 <refname>USB_INTERFACE_INFO</refname> 1692 <refpurpose> 1693 macro used to describe a class of usb interfaces 1694 </refpurpose> 1695</refnamediv> 1696<refsynopsisdiv> 1697 <title>Synopsis</title> 1698 <funcsynopsis><funcprototype> 1699 <funcdef> <function>USB_INTERFACE_INFO </function></funcdef> 1700 <paramdef> <parameter>cl</parameter></paramdef> 1701 <paramdef> <parameter>sc</parameter></paramdef> 1702 <paramdef> <parameter>pr</parameter></paramdef> 1703 </funcprototype></funcsynopsis> 1704</refsynopsisdiv> 1705<refsect1> 1706 <title>Arguments</title> 1707 <variablelist> 1708 <varlistentry> 1709 <term><parameter>cl</parameter></term> 1710 <listitem> 1711 <para> 1712 bInterfaceClass value 1713 </para> 1714 </listitem> 1715 </varlistentry> 1716 <varlistentry> 1717 <term><parameter>sc</parameter></term> 1718 <listitem> 1719 <para> 1720 bInterfaceSubClass value 1721 </para> 1722 </listitem> 1723 </varlistentry> 1724 <varlistentry> 1725 <term><parameter>pr</parameter></term> 1726 <listitem> 1727 <para> 1728 bInterfaceProtocol value 1729 </para> 1730 </listitem> 1731 </varlistentry> 1732 </variablelist> 1733</refsect1> 1734<refsect1> 1735<title>Description</title> 1736<para> 1737 This macro is used to create a struct usb_device_id that matches a 1738 specific class of interfaces. 1739</para> 1740</refsect1> 1741</refentry> 1742 1743<refentry id="API-USB-DEVICE-AND-INTERFACE-INFO"> 1744<refentryinfo> 1745 <title>LINUX</title> 1746 <productname>Kernel Hackers Manual</productname> 1747 <date>July 2017</date> 1748</refentryinfo> 1749<refmeta> 1750 <refentrytitle><phrase>USB_DEVICE_AND_INTERFACE_INFO</phrase></refentrytitle> 1751 <manvolnum>9</manvolnum> 1752 <refmiscinfo class="version">4.1.27</refmiscinfo> 1753</refmeta> 1754<refnamediv> 1755 <refname>USB_DEVICE_AND_INTERFACE_INFO</refname> 1756 <refpurpose> 1757 describe a specific usb device with a class of usb interfaces 1758 </refpurpose> 1759</refnamediv> 1760<refsynopsisdiv> 1761 <title>Synopsis</title> 1762 <funcsynopsis><funcprototype> 1763 <funcdef> <function>USB_DEVICE_AND_INTERFACE_INFO </function></funcdef> 1764 <paramdef> <parameter>vend</parameter></paramdef> 1765 <paramdef> <parameter>prod</parameter></paramdef> 1766 <paramdef> <parameter>cl</parameter></paramdef> 1767 <paramdef> <parameter>sc</parameter></paramdef> 1768 <paramdef> <parameter>pr</parameter></paramdef> 1769 </funcprototype></funcsynopsis> 1770</refsynopsisdiv> 1771<refsect1> 1772 <title>Arguments</title> 1773 <variablelist> 1774 <varlistentry> 1775 <term><parameter>vend</parameter></term> 1776 <listitem> 1777 <para> 1778 the 16 bit USB Vendor ID 1779 </para> 1780 </listitem> 1781 </varlistentry> 1782 <varlistentry> 1783 <term><parameter>prod</parameter></term> 1784 <listitem> 1785 <para> 1786 the 16 bit USB Product ID 1787 </para> 1788 </listitem> 1789 </varlistentry> 1790 <varlistentry> 1791 <term><parameter>cl</parameter></term> 1792 <listitem> 1793 <para> 1794 bInterfaceClass value 1795 </para> 1796 </listitem> 1797 </varlistentry> 1798 <varlistentry> 1799 <term><parameter>sc</parameter></term> 1800 <listitem> 1801 <para> 1802 bInterfaceSubClass value 1803 </para> 1804 </listitem> 1805 </varlistentry> 1806 <varlistentry> 1807 <term><parameter>pr</parameter></term> 1808 <listitem> 1809 <para> 1810 bInterfaceProtocol value 1811 </para> 1812 </listitem> 1813 </varlistentry> 1814 </variablelist> 1815</refsect1> 1816<refsect1> 1817<title>Description</title> 1818<para> 1819 This macro is used to create a struct usb_device_id that matches a 1820 specific device with a specific class of interfaces. 1821 </para><para> 1822 1823 This is especially useful when explicitly matching devices that have 1824 vendor specific bDeviceClass values, but standards-compliant interfaces. 1825</para> 1826</refsect1> 1827</refentry> 1828 1829<refentry id="API-USB-VENDOR-AND-INTERFACE-INFO"> 1830<refentryinfo> 1831 <title>LINUX</title> 1832 <productname>Kernel Hackers Manual</productname> 1833 <date>July 2017</date> 1834</refentryinfo> 1835<refmeta> 1836 <refentrytitle><phrase>USB_VENDOR_AND_INTERFACE_INFO</phrase></refentrytitle> 1837 <manvolnum>9</manvolnum> 1838 <refmiscinfo class="version">4.1.27</refmiscinfo> 1839</refmeta> 1840<refnamediv> 1841 <refname>USB_VENDOR_AND_INTERFACE_INFO</refname> 1842 <refpurpose> 1843 describe a specific usb vendor with a class of usb interfaces 1844 </refpurpose> 1845</refnamediv> 1846<refsynopsisdiv> 1847 <title>Synopsis</title> 1848 <funcsynopsis><funcprototype> 1849 <funcdef> <function>USB_VENDOR_AND_INTERFACE_INFO </function></funcdef> 1850 <paramdef> <parameter>vend</parameter></paramdef> 1851 <paramdef> <parameter>cl</parameter></paramdef> 1852 <paramdef> <parameter>sc</parameter></paramdef> 1853 <paramdef> <parameter>pr</parameter></paramdef> 1854 </funcprototype></funcsynopsis> 1855</refsynopsisdiv> 1856<refsect1> 1857 <title>Arguments</title> 1858 <variablelist> 1859 <varlistentry> 1860 <term><parameter>vend</parameter></term> 1861 <listitem> 1862 <para> 1863 the 16 bit USB Vendor ID 1864 </para> 1865 </listitem> 1866 </varlistentry> 1867 <varlistentry> 1868 <term><parameter>cl</parameter></term> 1869 <listitem> 1870 <para> 1871 bInterfaceClass value 1872 </para> 1873 </listitem> 1874 </varlistentry> 1875 <varlistentry> 1876 <term><parameter>sc</parameter></term> 1877 <listitem> 1878 <para> 1879 bInterfaceSubClass value 1880 </para> 1881 </listitem> 1882 </varlistentry> 1883 <varlistentry> 1884 <term><parameter>pr</parameter></term> 1885 <listitem> 1886 <para> 1887 bInterfaceProtocol value 1888 </para> 1889 </listitem> 1890 </varlistentry> 1891 </variablelist> 1892</refsect1> 1893<refsect1> 1894<title>Description</title> 1895<para> 1896 This macro is used to create a struct usb_device_id that matches a 1897 specific vendor with a specific class of interfaces. 1898 </para><para> 1899 1900 This is especially useful when explicitly matching devices that have 1901 vendor specific bDeviceClass values, but standards-compliant interfaces. 1902</para> 1903</refsect1> 1904</refentry> 1905 1906<refentry id="API-struct-usbdrv-wrap"> 1907<refentryinfo> 1908 <title>LINUX</title> 1909 <productname>Kernel Hackers Manual</productname> 1910 <date>July 2017</date> 1911</refentryinfo> 1912<refmeta> 1913 <refentrytitle><phrase>struct usbdrv_wrap</phrase></refentrytitle> 1914 <manvolnum>9</manvolnum> 1915 <refmiscinfo class="version">4.1.27</refmiscinfo> 1916</refmeta> 1917<refnamediv> 1918 <refname>struct usbdrv_wrap</refname> 1919 <refpurpose> 1920 wrapper for driver-model structure 1921 </refpurpose> 1922</refnamediv> 1923<refsynopsisdiv> 1924 <title>Synopsis</title> 1925 <programlisting> 1926struct usbdrv_wrap { 1927 struct device_driver driver; 1928 int for_devices; 1929}; </programlisting> 1930</refsynopsisdiv> 1931 <refsect1> 1932 <title>Members</title> 1933 <variablelist> 1934 <varlistentry> <term>driver</term> 1935 <listitem><para> 1936 The driver-model core driver structure. 1937 </para></listitem> 1938 </varlistentry> 1939 <varlistentry> <term>for_devices</term> 1940 <listitem><para> 1941 Non-zero for device drivers, 0 for interface drivers. 1942 </para></listitem> 1943 </varlistentry> 1944 </variablelist> 1945 </refsect1> 1946</refentry> 1947 1948<refentry id="API-struct-usb-driver"> 1949<refentryinfo> 1950 <title>LINUX</title> 1951 <productname>Kernel Hackers Manual</productname> 1952 <date>July 2017</date> 1953</refentryinfo> 1954<refmeta> 1955 <refentrytitle><phrase>struct usb_driver</phrase></refentrytitle> 1956 <manvolnum>9</manvolnum> 1957 <refmiscinfo class="version">4.1.27</refmiscinfo> 1958</refmeta> 1959<refnamediv> 1960 <refname>struct usb_driver</refname> 1961 <refpurpose> 1962 identifies USB interface driver to usbcore 1963 </refpurpose> 1964</refnamediv> 1965<refsynopsisdiv> 1966 <title>Synopsis</title> 1967 <programlisting> 1968struct usb_driver { 1969 const char * name; 1970 int (* probe) (struct usb_interface *intf,const struct usb_device_id *id); 1971 void (* disconnect) (struct usb_interface *intf); 1972 int (* unlocked_ioctl) (struct usb_interface *intf, unsigned int code,void *buf); 1973 int (* suspend) (struct usb_interface *intf, pm_message_t message); 1974 int (* resume) (struct usb_interface *intf); 1975 int (* reset_resume) (struct usb_interface *intf); 1976 int (* pre_reset) (struct usb_interface *intf); 1977 int (* post_reset) (struct usb_interface *intf); 1978 const struct usb_device_id * id_table; 1979 struct usb_dynids dynids; 1980 struct usbdrv_wrap drvwrap; 1981 unsigned int no_dynamic_id:1; 1982 unsigned int supports_autosuspend:1; 1983 unsigned int disable_hub_initiated_lpm:1; 1984 unsigned int soft_unbind:1; 1985}; </programlisting> 1986</refsynopsisdiv> 1987 <refsect1> 1988 <title>Members</title> 1989 <variablelist> 1990 <varlistentry> <term>name</term> 1991 <listitem><para> 1992 The driver name should be unique among USB drivers, 1993 and should normally be the same as the module name. 1994 </para></listitem> 1995 </varlistentry> 1996 <varlistentry> <term>probe</term> 1997 <listitem><para> 1998 Called to see if the driver is willing to manage a particular 1999 interface on a device. If it is, probe returns zero and uses 2000 <function>usb_set_intfdata</function> to associate driver-specific data with the 2001 interface. It may also use <function>usb_set_interface</function> to specify the 2002 appropriate altsetting. If unwilling to manage the interface, 2003 return -ENODEV, if genuine IO errors occurred, an appropriate 2004 negative errno value. 2005 </para></listitem> 2006 </varlistentry> 2007 <varlistentry> <term>disconnect</term> 2008 <listitem><para> 2009 Called when the interface is no longer accessible, usually 2010 because its device has been (or is being) disconnected or the 2011 driver module is being unloaded. 2012 </para></listitem> 2013 </varlistentry> 2014 <varlistentry> <term>unlocked_ioctl</term> 2015 <listitem><para> 2016 Used for drivers that want to talk to userspace through 2017 the <quote>usbfs</quote> filesystem. This lets devices provide ways to 2018 expose information to user space regardless of where they 2019 do (or don't) show up otherwise in the filesystem. 2020 </para></listitem> 2021 </varlistentry> 2022 <varlistentry> <term>suspend</term> 2023 <listitem><para> 2024 Called when the device is going to be suspended by the 2025 system either from system sleep or runtime suspend context. The 2026 return value will be ignored in system sleep context, so do NOT 2027 try to continue using the device if suspend fails in this case. 2028 Instead, let the resume or reset-resume routine recover from 2029 the failure. 2030 </para></listitem> 2031 </varlistentry> 2032 <varlistentry> <term>resume</term> 2033 <listitem><para> 2034 Called when the device is being resumed by the system. 2035 </para></listitem> 2036 </varlistentry> 2037 <varlistentry> <term>reset_resume</term> 2038 <listitem><para> 2039 Called when the suspended device has been reset instead 2040 of being resumed. 2041 </para></listitem> 2042 </varlistentry> 2043 <varlistentry> <term>pre_reset</term> 2044 <listitem><para> 2045 Called by <function>usb_reset_device</function> when the device is about to be 2046 reset. This routine must not return until the driver has no active 2047 URBs for the device, and no more URBs may be submitted until the 2048 post_reset method is called. 2049 </para></listitem> 2050 </varlistentry> 2051 <varlistentry> <term>post_reset</term> 2052 <listitem><para> 2053 Called by <function>usb_reset_device</function> after the device 2054 has been reset 2055 </para></listitem> 2056 </varlistentry> 2057 <varlistentry> <term>id_table</term> 2058 <listitem><para> 2059 USB drivers use ID table to support hotplugging. 2060 Export this with MODULE_DEVICE_TABLE(usb,...). This must be set 2061 or your driver's probe function will never get called. 2062 </para></listitem> 2063 </varlistentry> 2064 <varlistentry> <term>dynids</term> 2065 <listitem><para> 2066 used internally to hold the list of dynamically added device 2067 ids for this driver. 2068 </para></listitem> 2069 </varlistentry> 2070 <varlistentry> <term>drvwrap</term> 2071 <listitem><para> 2072 Driver-model core structure wrapper. 2073 </para></listitem> 2074 </varlistentry> 2075 <varlistentry> <term>no_dynamic_id</term> 2076 <listitem><para> 2077 if set to 1, the USB core will not allow dynamic ids to be 2078 added to this driver by preventing the sysfs file from being created. 2079 </para></listitem> 2080 </varlistentry> 2081 <varlistentry> <term>supports_autosuspend</term> 2082 <listitem><para> 2083 if set to 0, the USB core will not allow autosuspend 2084 for interfaces bound to this driver. 2085 </para></listitem> 2086 </varlistentry> 2087 <varlistentry> <term>disable_hub_initiated_lpm</term> 2088 <listitem><para> 2089 if set to 1, the USB core will not allow hubs 2090 to initiate lower power link state transitions when an idle timeout 2091 occurs. Device-initiated USB 3.0 link PM will still be allowed. 2092 </para></listitem> 2093 </varlistentry> 2094 <varlistentry> <term>soft_unbind</term> 2095 <listitem><para> 2096 if set to 1, the USB core will not kill URBs and disable 2097 endpoints before calling the driver's disconnect method. 2098 </para></listitem> 2099 </varlistentry> 2100 </variablelist> 2101 </refsect1> 2102<refsect1> 2103<title>Description</title> 2104<para> 2105 USB interface drivers must provide a name, <function>probe</function> and <function>disconnect</function> 2106 methods, and an id_table. Other driver fields are optional. 2107 </para><para> 2108 2109 The id_table is used in hotplugging. It holds a set of descriptors, 2110 and specialized data may be associated with each entry. That table 2111 is used by both user and kernel mode hotplugging support. 2112 </para><para> 2113 2114 The <function>probe</function> and <function>disconnect</function> methods are called in a context where 2115 they can sleep, but they should avoid abusing the privilege. Most 2116 work to connect to a device should be done when the device is opened, 2117 and undone at the last close. The disconnect code needs to address 2118 concurrency issues with respect to <function>open</function> and <function>close</function> methods, as 2119 well as forcing all pending I/O requests to complete (by unlinking 2120 them as necessary, and blocking until the unlinks complete). 2121</para> 2122</refsect1> 2123</refentry> 2124 2125<refentry id="API-struct-usb-device-driver"> 2126<refentryinfo> 2127 <title>LINUX</title> 2128 <productname>Kernel Hackers Manual</productname> 2129 <date>July 2017</date> 2130</refentryinfo> 2131<refmeta> 2132 <refentrytitle><phrase>struct usb_device_driver</phrase></refentrytitle> 2133 <manvolnum>9</manvolnum> 2134 <refmiscinfo class="version">4.1.27</refmiscinfo> 2135</refmeta> 2136<refnamediv> 2137 <refname>struct usb_device_driver</refname> 2138 <refpurpose> 2139 identifies USB device driver to usbcore 2140 </refpurpose> 2141</refnamediv> 2142<refsynopsisdiv> 2143 <title>Synopsis</title> 2144 <programlisting> 2145struct usb_device_driver { 2146 const char * name; 2147 int (* probe) (struct usb_device *udev); 2148 void (* disconnect) (struct usb_device *udev); 2149 int (* suspend) (struct usb_device *udev, pm_message_t message); 2150 int (* resume) (struct usb_device *udev, pm_message_t message); 2151 struct usbdrv_wrap drvwrap; 2152 unsigned int supports_autosuspend:1; 2153}; </programlisting> 2154</refsynopsisdiv> 2155 <refsect1> 2156 <title>Members</title> 2157 <variablelist> 2158 <varlistentry> <term>name</term> 2159 <listitem><para> 2160 The driver name should be unique among USB drivers, 2161 and should normally be the same as the module name. 2162 </para></listitem> 2163 </varlistentry> 2164 <varlistentry> <term>probe</term> 2165 <listitem><para> 2166 Called to see if the driver is willing to manage a particular 2167 device. If it is, probe returns zero and uses <function>dev_set_drvdata</function> 2168 to associate driver-specific data with the device. If unwilling 2169 to manage the device, return a negative errno value. 2170 </para></listitem> 2171 </varlistentry> 2172 <varlistentry> <term>disconnect</term> 2173 <listitem><para> 2174 Called when the device is no longer accessible, usually 2175 because it has been (or is being) disconnected or the driver's 2176 module is being unloaded. 2177 </para></listitem> 2178 </varlistentry> 2179 <varlistentry> <term>suspend</term> 2180 <listitem><para> 2181 Called when the device is going to be suspended by the system. 2182 </para></listitem> 2183 </varlistentry> 2184 <varlistentry> <term>resume</term> 2185 <listitem><para> 2186 Called when the device is being resumed by the system. 2187 </para></listitem> 2188 </varlistentry> 2189 <varlistentry> <term>drvwrap</term> 2190 <listitem><para> 2191 Driver-model core structure wrapper. 2192 </para></listitem> 2193 </varlistentry> 2194 <varlistentry> <term>supports_autosuspend</term> 2195 <listitem><para> 2196 if set to 0, the USB core will not allow autosuspend 2197 for devices bound to this driver. 2198 </para></listitem> 2199 </varlistentry> 2200 </variablelist> 2201 </refsect1> 2202<refsect1> 2203<title>Description</title> 2204<para> 2205 USB drivers must provide all the fields listed above except drvwrap. 2206</para> 2207</refsect1> 2208</refentry> 2209 2210<refentry id="API-struct-usb-class-driver"> 2211<refentryinfo> 2212 <title>LINUX</title> 2213 <productname>Kernel Hackers Manual</productname> 2214 <date>July 2017</date> 2215</refentryinfo> 2216<refmeta> 2217 <refentrytitle><phrase>struct usb_class_driver</phrase></refentrytitle> 2218 <manvolnum>9</manvolnum> 2219 <refmiscinfo class="version">4.1.27</refmiscinfo> 2220</refmeta> 2221<refnamediv> 2222 <refname>struct usb_class_driver</refname> 2223 <refpurpose> 2224 identifies a USB driver that wants to use the USB major number 2225 </refpurpose> 2226</refnamediv> 2227<refsynopsisdiv> 2228 <title>Synopsis</title> 2229 <programlisting> 2230struct usb_class_driver { 2231 char * name; 2232 char *(* devnode) (struct device *dev, umode_t *mode); 2233 const struct file_operations * fops; 2234 int minor_base; 2235}; </programlisting> 2236</refsynopsisdiv> 2237 <refsect1> 2238 <title>Members</title> 2239 <variablelist> 2240 <varlistentry> <term>name</term> 2241 <listitem><para> 2242 the usb class device name for this driver. Will show up in sysfs. 2243 </para></listitem> 2244 </varlistentry> 2245 <varlistentry> <term>devnode</term> 2246 <listitem><para> 2247 Callback to provide a naming hint for a possible 2248 device node to create. 2249 </para></listitem> 2250 </varlistentry> 2251 <varlistentry> <term>fops</term> 2252 <listitem><para> 2253 pointer to the struct file_operations of this driver. 2254 </para></listitem> 2255 </varlistentry> 2256 <varlistentry> <term>minor_base</term> 2257 <listitem><para> 2258 the start of the minor range for this driver. 2259 </para></listitem> 2260 </varlistentry> 2261 </variablelist> 2262 </refsect1> 2263<refsect1> 2264<title>Description</title> 2265<para> 2266 This structure is used for the <function>usb_register_dev</function> and 2267 <function>usb_unregister_dev</function> functions, to consolidate a number of the 2268 parameters used for them. 2269</para> 2270</refsect1> 2271</refentry> 2272 2273<refentry id="API-module-usb-driver"> 2274<refentryinfo> 2275 <title>LINUX</title> 2276 <productname>Kernel Hackers Manual</productname> 2277 <date>July 2017</date> 2278</refentryinfo> 2279<refmeta> 2280 <refentrytitle><phrase>module_usb_driver</phrase></refentrytitle> 2281 <manvolnum>9</manvolnum> 2282 <refmiscinfo class="version">4.1.27</refmiscinfo> 2283</refmeta> 2284<refnamediv> 2285 <refname>module_usb_driver</refname> 2286 <refpurpose> 2287 Helper macro for registering a USB driver 2288 </refpurpose> 2289</refnamediv> 2290<refsynopsisdiv> 2291 <title>Synopsis</title> 2292 <funcsynopsis><funcprototype> 2293 <funcdef> <function>module_usb_driver </function></funcdef> 2294 <paramdef> <parameter>__usb_driver</parameter></paramdef> 2295 </funcprototype></funcsynopsis> 2296</refsynopsisdiv> 2297<refsect1> 2298 <title>Arguments</title> 2299 <variablelist> 2300 <varlistentry> 2301 <term><parameter>__usb_driver</parameter></term> 2302 <listitem> 2303 <para> 2304 usb_driver struct 2305 </para> 2306 </listitem> 2307 </varlistentry> 2308 </variablelist> 2309</refsect1> 2310<refsect1> 2311<title>Description</title> 2312<para> 2313 Helper macro for USB drivers which do not do anything special in module 2314 init/exit. This eliminates a lot of boilerplate. Each module may only 2315 use this macro once, and calling it replaces <function>module_init</function> and <function>module_exit</function> 2316</para> 2317</refsect1> 2318</refentry> 2319 2320<refentry id="API-struct-urb"> 2321<refentryinfo> 2322 <title>LINUX</title> 2323 <productname>Kernel Hackers Manual</productname> 2324 <date>July 2017</date> 2325</refentryinfo> 2326<refmeta> 2327 <refentrytitle><phrase>struct urb</phrase></refentrytitle> 2328 <manvolnum>9</manvolnum> 2329 <refmiscinfo class="version">4.1.27</refmiscinfo> 2330</refmeta> 2331<refnamediv> 2332 <refname>struct urb</refname> 2333 <refpurpose> 2334 USB Request Block 2335 </refpurpose> 2336</refnamediv> 2337<refsynopsisdiv> 2338 <title>Synopsis</title> 2339 <programlisting> 2340struct urb { 2341 struct list_head urb_list; 2342 struct list_head anchor_list; 2343 struct usb_anchor * anchor; 2344 struct usb_device * dev; 2345 struct usb_host_endpoint * ep; 2346 unsigned int pipe; 2347 unsigned int stream_id; 2348 int status; 2349 unsigned int transfer_flags; 2350 void * transfer_buffer; 2351 dma_addr_t transfer_dma; 2352 struct scatterlist * sg; 2353 int num_mapped_sgs; 2354 int num_sgs; 2355 u32 transfer_buffer_length; 2356 u32 actual_length; 2357 unsigned char * setup_packet; 2358 dma_addr_t setup_dma; 2359 int start_frame; 2360 int number_of_packets; 2361 int interval; 2362 int error_count; 2363 void * context; 2364 usb_complete_t complete; 2365 struct usb_iso_packet_descriptor iso_frame_desc[0]; 2366}; </programlisting> 2367</refsynopsisdiv> 2368 <refsect1> 2369 <title>Members</title> 2370 <variablelist> 2371 <varlistentry> <term>urb_list</term> 2372 <listitem><para> 2373 For use by current owner of the URB. 2374 </para></listitem> 2375 </varlistentry> 2376 <varlistentry> <term>anchor_list</term> 2377 <listitem><para> 2378 membership in the list of an anchor 2379 </para></listitem> 2380 </varlistentry> 2381 <varlistentry> <term>anchor</term> 2382 <listitem><para> 2383 to anchor URBs to a common mooring 2384 </para></listitem> 2385 </varlistentry> 2386 <varlistentry> <term>dev</term> 2387 <listitem><para> 2388 Identifies the USB device to perform the request. 2389 </para></listitem> 2390 </varlistentry> 2391 <varlistentry> <term>ep</term> 2392 <listitem><para> 2393 Points to the endpoint's data structure. Will eventually 2394 replace <parameter>pipe</parameter>. 2395 </para></listitem> 2396 </varlistentry> 2397 <varlistentry> <term>pipe</term> 2398 <listitem><para> 2399 Holds endpoint number, direction, type, and more. 2400 Create these values with the eight macros available; 2401 usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is <quote>ctrl</quote> 2402 (control), <quote>bulk</quote>, <quote>int</quote> (interrupt), or <quote>iso</quote> (isochronous). 2403 For example <function>usb_sndbulkpipe</function> or <function>usb_rcvintpipe</function>. Endpoint 2404 numbers range from zero to fifteen. Note that <quote>in</quote> endpoint two 2405 is a different endpoint (and pipe) from <quote>out</quote> endpoint two. 2406 The current configuration controls the existence, type, and 2407 maximum packet size of any given endpoint. 2408 </para></listitem> 2409 </varlistentry> 2410 <varlistentry> <term>stream_id</term> 2411 <listitem><para> 2412 the endpoint's stream ID for bulk streams 2413 </para></listitem> 2414 </varlistentry> 2415 <varlistentry> <term>status</term> 2416 <listitem><para> 2417 This is read in non-iso completion functions to get the 2418 status of the particular request. ISO requests only use it 2419 to tell whether the URB was unlinked; detailed status for 2420 each frame is in the fields of the iso_frame-desc. 2421 </para></listitem> 2422 </varlistentry> 2423 <varlistentry> <term>transfer_flags</term> 2424 <listitem><para> 2425 A variety of flags may be used to affect how URB 2426 submission, unlinking, or operation are handled. Different 2427 kinds of URB can use different flags. 2428 </para></listitem> 2429 </varlistentry> 2430 <varlistentry> <term>transfer_buffer</term> 2431 <listitem><para> 2432 This identifies the buffer to (or from) which the I/O 2433 request will be performed unless URB_NO_TRANSFER_DMA_MAP is set 2434 (however, do not leave garbage in transfer_buffer even then). 2435 This buffer must be suitable for DMA; allocate it with 2436 <function>kmalloc</function> or equivalent. For transfers to <quote>in</quote> endpoints, contents 2437 of this buffer will be modified. This buffer is used for the data 2438 stage of control transfers. 2439 </para></listitem> 2440 </varlistentry> 2441 <varlistentry> <term>transfer_dma</term> 2442 <listitem><para> 2443 When transfer_flags includes URB_NO_TRANSFER_DMA_MAP, 2444 the device driver is saying that it provided this DMA address, 2445 which the host controller driver should use in preference to the 2446 transfer_buffer. 2447 </para></listitem> 2448 </varlistentry> 2449 <varlistentry> <term>sg</term> 2450 <listitem><para> 2451 scatter gather buffer list, the buffer size of each element in 2452 the list (except the last) must be divisible by the endpoint's 2453 max packet size if no_sg_constraint isn't set in 'struct usb_bus' 2454 </para></listitem> 2455 </varlistentry> 2456 <varlistentry> <term>num_mapped_sgs</term> 2457 <listitem><para> 2458 (internal) number of mapped sg entries 2459 </para></listitem> 2460 </varlistentry> 2461 <varlistentry> <term>num_sgs</term> 2462 <listitem><para> 2463 number of entries in the sg list 2464 </para></listitem> 2465 </varlistentry> 2466 <varlistentry> <term>transfer_buffer_length</term> 2467 <listitem><para> 2468 How big is transfer_buffer. The transfer may 2469 be broken up into chunks according to the current maximum packet 2470 size for the endpoint, which is a function of the configuration 2471 and is encoded in the pipe. When the length is zero, neither 2472 transfer_buffer nor transfer_dma is used. 2473 </para></listitem> 2474 </varlistentry> 2475 <varlistentry> <term>actual_length</term> 2476 <listitem><para> 2477 This is read in non-iso completion functions, and 2478 it tells how many bytes (out of transfer_buffer_length) were 2479 transferred. It will normally be the same as requested, unless 2480 either an error was reported or a short read was performed. 2481 The URB_SHORT_NOT_OK transfer flag may be used to make such 2482 short reads be reported as errors. 2483 </para></listitem> 2484 </varlistentry> 2485 <varlistentry> <term>setup_packet</term> 2486 <listitem><para> 2487 Only used for control transfers, this points to eight bytes 2488 of setup data. Control transfers always start by sending this data 2489 to the device. Then transfer_buffer is read or written, if needed. 2490 </para></listitem> 2491 </varlistentry> 2492 <varlistentry> <term>setup_dma</term> 2493 <listitem><para> 2494 DMA pointer for the setup packet. The caller must not use 2495 this field; setup_packet must point to a valid buffer. 2496 </para></listitem> 2497 </varlistentry> 2498 <varlistentry> <term>start_frame</term> 2499 <listitem><para> 2500 Returns the initial frame for isochronous transfers. 2501 </para></listitem> 2502 </varlistentry> 2503 <varlistentry> <term>number_of_packets</term> 2504 <listitem><para> 2505 Lists the number of ISO transfer buffers. 2506 </para></listitem> 2507 </varlistentry> 2508 <varlistentry> <term>interval</term> 2509 <listitem><para> 2510 Specifies the polling interval for interrupt or isochronous 2511 transfers. The units are frames (milliseconds) for full and low 2512 speed devices, and microframes (1/8 millisecond) for highspeed 2513 and SuperSpeed devices. 2514 </para></listitem> 2515 </varlistentry> 2516 <varlistentry> <term>error_count</term> 2517 <listitem><para> 2518 Returns the number of ISO transfers that reported errors. 2519 </para></listitem> 2520 </varlistentry> 2521 <varlistentry> <term>context</term> 2522 <listitem><para> 2523 For use in completion functions. This normally points to 2524 request-specific driver context. 2525 </para></listitem> 2526 </varlistentry> 2527 <varlistentry> <term>complete</term> 2528 <listitem><para> 2529 Completion handler. This URB is passed as the parameter to the 2530 completion function. The completion function may then do what 2531 it likes with the URB, including resubmitting or freeing it. 2532 </para></listitem> 2533 </varlistentry> 2534 <varlistentry> <term>iso_frame_desc[0]</term> 2535 <listitem><para> 2536 Used to provide arrays of ISO transfer buffers and to 2537 collect the transfer status for each buffer. 2538 </para></listitem> 2539 </varlistentry> 2540 </variablelist> 2541 </refsect1> 2542<refsect1> 2543<title>Description</title> 2544<para> 2545 This structure identifies USB transfer requests. URBs must be allocated by 2546 calling <function>usb_alloc_urb</function> and freed with a call to <function>usb_free_urb</function>. 2547 Initialization may be done using various usb_fill_*<function>_urb</function> functions. URBs 2548 are submitted using <function>usb_submit_urb</function>, and pending requests may be canceled 2549 using <function>usb_unlink_urb</function> or <function>usb_kill_urb</function>. 2550</para> 2551</refsect1> 2552<refsect1> 2553<title>Data Transfer Buffers</title> 2554<para> 2555 </para><para> 2556 2557 Normally drivers provide I/O buffers allocated with <function>kmalloc</function> or otherwise 2558 taken from the general page pool. That is provided by transfer_buffer 2559 (control requests also use setup_packet), and host controller drivers 2560 perform a dma mapping (and unmapping) for each buffer transferred. Those 2561 mapping operations can be expensive on some platforms (perhaps using a dma 2562 bounce buffer or talking to an IOMMU), 2563 although they're cheap on commodity x86 and ppc hardware. 2564 </para><para> 2565 2566 Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer flag, 2567 which tells the host controller driver that no such mapping is needed for 2568 the transfer_buffer since 2569 the device driver is DMA-aware. For example, a device driver might 2570 allocate a DMA buffer with <function>usb_alloc_coherent</function> or call <function>usb_buffer_map</function>. 2571 When this transfer flag is provided, host controller drivers will 2572 attempt to use the dma address found in the transfer_dma 2573 field rather than determining a dma address themselves. 2574 </para><para> 2575 2576 Note that transfer_buffer must still be set if the controller 2577 does not support DMA (as indicated by bus.uses_dma) and when talking 2578 to root hub. If you have to trasfer between highmem zone and the device 2579 on such controller, create a bounce buffer or bail out with an error. 2580 If transfer_buffer cannot be set (is in highmem) and the controller is DMA 2581 capable, assign NULL to it, so that usbmon knows not to use the value. 2582 The setup_packet must always be set, so it cannot be located in highmem. 2583</para> 2584</refsect1> 2585<refsect1> 2586<title>Initialization</title> 2587<para> 2588 </para><para> 2589 2590 All URBs submitted must initialize the dev, pipe, transfer_flags (may be 2591 zero), and complete fields. All URBs must also initialize 2592 transfer_buffer and transfer_buffer_length. They may provide the 2593 URB_SHORT_NOT_OK transfer flag, indicating that short reads are 2594 to be treated as errors; that flag is invalid for write requests. 2595 </para><para> 2596 2597 Bulk URBs may 2598 use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers 2599 should always terminate with a short packet, even if it means adding an 2600 extra zero length packet. 2601 </para><para> 2602 2603 Control URBs must provide a valid pointer in the setup_packet field. 2604 Unlike the transfer_buffer, the setup_packet may not be mapped for DMA 2605 beforehand. 2606 </para><para> 2607 2608 Interrupt URBs must provide an interval, saying how often (in milliseconds 2609 or, for highspeed devices, 125 microsecond units) 2610 to poll for transfers. After the URB has been submitted, the interval 2611 field reflects how the transfer was actually scheduled. 2612 The polling interval may be more frequent than requested. 2613 For example, some controllers have a maximum interval of 32 milliseconds, 2614 while others support intervals of up to 1024 milliseconds. 2615 Isochronous URBs also have transfer intervals. (Note that for isochronous 2616 endpoints, as well as high speed interrupt endpoints, the encoding of 2617 the transfer interval in the endpoint descriptor is logarithmic. 2618 Device drivers must convert that value to linear units themselves.) 2619 </para><para> 2620 2621 If an isochronous endpoint queue isn't already running, the host 2622 controller will schedule a new URB to start as soon as bandwidth 2623 utilization allows. If the queue is running then a new URB will be 2624 scheduled to start in the first transfer slot following the end of the 2625 preceding URB, if that slot has not already expired. If the slot has 2626 expired (which can happen when IRQ delivery is delayed for a long time), 2627 the scheduling behavior depends on the URB_ISO_ASAP flag. If the flag 2628 is clear then the URB will be scheduled to start in the expired slot, 2629 implying that some of its packets will not be transferred; if the flag 2630 is set then the URB will be scheduled in the first unexpired slot, 2631 breaking the queue's synchronization. Upon URB completion, the 2632 start_frame field will be set to the (micro)frame number in which the 2633 transfer was scheduled. Ranges for frame counter values are HC-specific 2634 and can go from as low as 256 to as high as 65536 frames. 2635 </para><para> 2636 2637 Isochronous URBs have a different data transfer model, in part because 2638 the quality of service is only <quote>best effort</quote>. Callers provide specially 2639 allocated URBs, with number_of_packets worth of iso_frame_desc structures 2640 at the end. Each such packet is an individual ISO transfer. Isochronous 2641 URBs are normally queued, submitted by drivers to arrange that 2642 transfers are at least double buffered, and then explicitly resubmitted 2643 in completion handlers, so 2644 that data (such as audio or video) streams at as constant a rate as the 2645 host controller scheduler can support. 2646</para> 2647</refsect1> 2648<refsect1> 2649<title>Completion Callbacks</title> 2650<para> 2651 </para><para> 2652 2653 The completion callback is made <function>in_interrupt</function>, and one of the first 2654 things that a completion handler should do is check the status field. 2655 The status field is provided for all URBs. It is used to report 2656 unlinked URBs, and status for all non-ISO transfers. It should not 2657 be examined before the URB is returned to the completion handler. 2658 </para><para> 2659 2660 The context field is normally used to link URBs back to the relevant 2661 driver or request state. 2662 </para><para> 2663 2664 When the completion callback is invoked for non-isochronous URBs, the 2665 actual_length field tells how many bytes were transferred. This field 2666 is updated even when the URB terminated with an error or was unlinked. 2667 </para><para> 2668 2669 ISO transfer status is reported in the status and actual_length fields 2670 of the iso_frame_desc array, and the number of errors is reported in 2671 error_count. Completion callbacks for ISO transfers will normally 2672 (re)submit URBs to ensure a constant transfer rate. 2673 </para><para> 2674 2675 Note that even fields marked <quote>public</quote> should not be touched by the driver 2676 when the urb is owned by the hcd, that is, since the call to 2677 <function>usb_submit_urb</function> till the entry into the completion routine. 2678</para> 2679</refsect1> 2680</refentry> 2681 2682<refentry id="API-usb-fill-control-urb"> 2683<refentryinfo> 2684 <title>LINUX</title> 2685 <productname>Kernel Hackers Manual</productname> 2686 <date>July 2017</date> 2687</refentryinfo> 2688<refmeta> 2689 <refentrytitle><phrase>usb_fill_control_urb</phrase></refentrytitle> 2690 <manvolnum>9</manvolnum> 2691 <refmiscinfo class="version">4.1.27</refmiscinfo> 2692</refmeta> 2693<refnamediv> 2694 <refname>usb_fill_control_urb</refname> 2695 <refpurpose> 2696 initializes a control urb 2697 </refpurpose> 2698</refnamediv> 2699<refsynopsisdiv> 2700 <title>Synopsis</title> 2701 <funcsynopsis><funcprototype> 2702 <funcdef>void <function>usb_fill_control_urb </function></funcdef> 2703 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 2704 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 2705 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 2706 <paramdef>unsigned char * <parameter>setup_packet</parameter></paramdef> 2707 <paramdef>void * <parameter>transfer_buffer</parameter></paramdef> 2708 <paramdef>int <parameter>buffer_length</parameter></paramdef> 2709 <paramdef>usb_complete_t <parameter>complete_fn</parameter></paramdef> 2710 <paramdef>void * <parameter>context</parameter></paramdef> 2711 </funcprototype></funcsynopsis> 2712</refsynopsisdiv> 2713<refsect1> 2714 <title>Arguments</title> 2715 <variablelist> 2716 <varlistentry> 2717 <term><parameter>urb</parameter></term> 2718 <listitem> 2719 <para> 2720 pointer to the urb to initialize. 2721 </para> 2722 </listitem> 2723 </varlistentry> 2724 <varlistentry> 2725 <term><parameter>dev</parameter></term> 2726 <listitem> 2727 <para> 2728 pointer to the struct usb_device for this urb. 2729 </para> 2730 </listitem> 2731 </varlistentry> 2732 <varlistentry> 2733 <term><parameter>pipe</parameter></term> 2734 <listitem> 2735 <para> 2736 the endpoint pipe 2737 </para> 2738 </listitem> 2739 </varlistentry> 2740 <varlistentry> 2741 <term><parameter>setup_packet</parameter></term> 2742 <listitem> 2743 <para> 2744 pointer to the setup_packet buffer 2745 </para> 2746 </listitem> 2747 </varlistentry> 2748 <varlistentry> 2749 <term><parameter>transfer_buffer</parameter></term> 2750 <listitem> 2751 <para> 2752 pointer to the transfer buffer 2753 </para> 2754 </listitem> 2755 </varlistentry> 2756 <varlistentry> 2757 <term><parameter>buffer_length</parameter></term> 2758 <listitem> 2759 <para> 2760 length of the transfer buffer 2761 </para> 2762 </listitem> 2763 </varlistentry> 2764 <varlistentry> 2765 <term><parameter>complete_fn</parameter></term> 2766 <listitem> 2767 <para> 2768 pointer to the usb_complete_t function 2769 </para> 2770 </listitem> 2771 </varlistentry> 2772 <varlistentry> 2773 <term><parameter>context</parameter></term> 2774 <listitem> 2775 <para> 2776 what to set the urb context to. 2777 </para> 2778 </listitem> 2779 </varlistentry> 2780 </variablelist> 2781</refsect1> 2782<refsect1> 2783<title>Description</title> 2784<para> 2785 Initializes a control urb with the proper information needed to submit 2786 it to a device. 2787</para> 2788</refsect1> 2789</refentry> 2790 2791<refentry id="API-usb-fill-bulk-urb"> 2792<refentryinfo> 2793 <title>LINUX</title> 2794 <productname>Kernel Hackers Manual</productname> 2795 <date>July 2017</date> 2796</refentryinfo> 2797<refmeta> 2798 <refentrytitle><phrase>usb_fill_bulk_urb</phrase></refentrytitle> 2799 <manvolnum>9</manvolnum> 2800 <refmiscinfo class="version">4.1.27</refmiscinfo> 2801</refmeta> 2802<refnamediv> 2803 <refname>usb_fill_bulk_urb</refname> 2804 <refpurpose> 2805 macro to help initialize a bulk urb 2806 </refpurpose> 2807</refnamediv> 2808<refsynopsisdiv> 2809 <title>Synopsis</title> 2810 <funcsynopsis><funcprototype> 2811 <funcdef>void <function>usb_fill_bulk_urb </function></funcdef> 2812 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 2813 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 2814 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 2815 <paramdef>void * <parameter>transfer_buffer</parameter></paramdef> 2816 <paramdef>int <parameter>buffer_length</parameter></paramdef> 2817 <paramdef>usb_complete_t <parameter>complete_fn</parameter></paramdef> 2818 <paramdef>void * <parameter>context</parameter></paramdef> 2819 </funcprototype></funcsynopsis> 2820</refsynopsisdiv> 2821<refsect1> 2822 <title>Arguments</title> 2823 <variablelist> 2824 <varlistentry> 2825 <term><parameter>urb</parameter></term> 2826 <listitem> 2827 <para> 2828 pointer to the urb to initialize. 2829 </para> 2830 </listitem> 2831 </varlistentry> 2832 <varlistentry> 2833 <term><parameter>dev</parameter></term> 2834 <listitem> 2835 <para> 2836 pointer to the struct usb_device for this urb. 2837 </para> 2838 </listitem> 2839 </varlistentry> 2840 <varlistentry> 2841 <term><parameter>pipe</parameter></term> 2842 <listitem> 2843 <para> 2844 the endpoint pipe 2845 </para> 2846 </listitem> 2847 </varlistentry> 2848 <varlistentry> 2849 <term><parameter>transfer_buffer</parameter></term> 2850 <listitem> 2851 <para> 2852 pointer to the transfer buffer 2853 </para> 2854 </listitem> 2855 </varlistentry> 2856 <varlistentry> 2857 <term><parameter>buffer_length</parameter></term> 2858 <listitem> 2859 <para> 2860 length of the transfer buffer 2861 </para> 2862 </listitem> 2863 </varlistentry> 2864 <varlistentry> 2865 <term><parameter>complete_fn</parameter></term> 2866 <listitem> 2867 <para> 2868 pointer to the usb_complete_t function 2869 </para> 2870 </listitem> 2871 </varlistentry> 2872 <varlistentry> 2873 <term><parameter>context</parameter></term> 2874 <listitem> 2875 <para> 2876 what to set the urb context to. 2877 </para> 2878 </listitem> 2879 </varlistentry> 2880 </variablelist> 2881</refsect1> 2882<refsect1> 2883<title>Description</title> 2884<para> 2885 Initializes a bulk urb with the proper information needed to submit it 2886 to a device. 2887</para> 2888</refsect1> 2889</refentry> 2890 2891<refentry id="API-usb-fill-int-urb"> 2892<refentryinfo> 2893 <title>LINUX</title> 2894 <productname>Kernel Hackers Manual</productname> 2895 <date>July 2017</date> 2896</refentryinfo> 2897<refmeta> 2898 <refentrytitle><phrase>usb_fill_int_urb</phrase></refentrytitle> 2899 <manvolnum>9</manvolnum> 2900 <refmiscinfo class="version">4.1.27</refmiscinfo> 2901</refmeta> 2902<refnamediv> 2903 <refname>usb_fill_int_urb</refname> 2904 <refpurpose> 2905 macro to help initialize a interrupt urb 2906 </refpurpose> 2907</refnamediv> 2908<refsynopsisdiv> 2909 <title>Synopsis</title> 2910 <funcsynopsis><funcprototype> 2911 <funcdef>void <function>usb_fill_int_urb </function></funcdef> 2912 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 2913 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 2914 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 2915 <paramdef>void * <parameter>transfer_buffer</parameter></paramdef> 2916 <paramdef>int <parameter>buffer_length</parameter></paramdef> 2917 <paramdef>usb_complete_t <parameter>complete_fn</parameter></paramdef> 2918 <paramdef>void * <parameter>context</parameter></paramdef> 2919 <paramdef>int <parameter>interval</parameter></paramdef> 2920 </funcprototype></funcsynopsis> 2921</refsynopsisdiv> 2922<refsect1> 2923 <title>Arguments</title> 2924 <variablelist> 2925 <varlistentry> 2926 <term><parameter>urb</parameter></term> 2927 <listitem> 2928 <para> 2929 pointer to the urb to initialize. 2930 </para> 2931 </listitem> 2932 </varlistentry> 2933 <varlistentry> 2934 <term><parameter>dev</parameter></term> 2935 <listitem> 2936 <para> 2937 pointer to the struct usb_device for this urb. 2938 </para> 2939 </listitem> 2940 </varlistentry> 2941 <varlistentry> 2942 <term><parameter>pipe</parameter></term> 2943 <listitem> 2944 <para> 2945 the endpoint pipe 2946 </para> 2947 </listitem> 2948 </varlistentry> 2949 <varlistentry> 2950 <term><parameter>transfer_buffer</parameter></term> 2951 <listitem> 2952 <para> 2953 pointer to the transfer buffer 2954 </para> 2955 </listitem> 2956 </varlistentry> 2957 <varlistentry> 2958 <term><parameter>buffer_length</parameter></term> 2959 <listitem> 2960 <para> 2961 length of the transfer buffer 2962 </para> 2963 </listitem> 2964 </varlistentry> 2965 <varlistentry> 2966 <term><parameter>complete_fn</parameter></term> 2967 <listitem> 2968 <para> 2969 pointer to the usb_complete_t function 2970 </para> 2971 </listitem> 2972 </varlistentry> 2973 <varlistentry> 2974 <term><parameter>context</parameter></term> 2975 <listitem> 2976 <para> 2977 what to set the urb context to. 2978 </para> 2979 </listitem> 2980 </varlistentry> 2981 <varlistentry> 2982 <term><parameter>interval</parameter></term> 2983 <listitem> 2984 <para> 2985 what to set the urb interval to, encoded like 2986 the endpoint descriptor's bInterval value. 2987 </para> 2988 </listitem> 2989 </varlistentry> 2990 </variablelist> 2991</refsect1> 2992<refsect1> 2993<title>Description</title> 2994<para> 2995 Initializes a interrupt urb with the proper information needed to submit 2996 it to a device. 2997 </para><para> 2998 2999 Note that High Speed and SuperSpeed interrupt endpoints use a logarithmic 3000 encoding of the endpoint interval, and express polling intervals in 3001 microframes (eight per millisecond) rather than in frames (one per 3002 millisecond). 3003 </para><para> 3004 3005 Wireless USB also uses the logarithmic encoding, but specifies it in units of 3006 128us instead of 125us. For Wireless USB devices, the interval is passed 3007 through to the host controller, rather than being translated into microframe 3008 units. 3009</para> 3010</refsect1> 3011</refentry> 3012 3013<refentry id="API-usb-urb-dir-in"> 3014<refentryinfo> 3015 <title>LINUX</title> 3016 <productname>Kernel Hackers Manual</productname> 3017 <date>July 2017</date> 3018</refentryinfo> 3019<refmeta> 3020 <refentrytitle><phrase>usb_urb_dir_in</phrase></refentrytitle> 3021 <manvolnum>9</manvolnum> 3022 <refmiscinfo class="version">4.1.27</refmiscinfo> 3023</refmeta> 3024<refnamediv> 3025 <refname>usb_urb_dir_in</refname> 3026 <refpurpose> 3027 check if an URB describes an IN transfer 3028 </refpurpose> 3029</refnamediv> 3030<refsynopsisdiv> 3031 <title>Synopsis</title> 3032 <funcsynopsis><funcprototype> 3033 <funcdef>int <function>usb_urb_dir_in </function></funcdef> 3034 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3035 </funcprototype></funcsynopsis> 3036</refsynopsisdiv> 3037<refsect1> 3038 <title>Arguments</title> 3039 <variablelist> 3040 <varlistentry> 3041 <term><parameter>urb</parameter></term> 3042 <listitem> 3043 <para> 3044 URB to be checked 3045 </para> 3046 </listitem> 3047 </varlistentry> 3048 </variablelist> 3049</refsect1> 3050<refsect1> 3051<title>Return</title> 3052<para> 3053 1 if <parameter>urb</parameter> describes an IN transfer (device-to-host), 3054 otherwise 0. 3055</para> 3056</refsect1> 3057</refentry> 3058 3059<refentry id="API-usb-urb-dir-out"> 3060<refentryinfo> 3061 <title>LINUX</title> 3062 <productname>Kernel Hackers Manual</productname> 3063 <date>July 2017</date> 3064</refentryinfo> 3065<refmeta> 3066 <refentrytitle><phrase>usb_urb_dir_out</phrase></refentrytitle> 3067 <manvolnum>9</manvolnum> 3068 <refmiscinfo class="version">4.1.27</refmiscinfo> 3069</refmeta> 3070<refnamediv> 3071 <refname>usb_urb_dir_out</refname> 3072 <refpurpose> 3073 check if an URB describes an OUT transfer 3074 </refpurpose> 3075</refnamediv> 3076<refsynopsisdiv> 3077 <title>Synopsis</title> 3078 <funcsynopsis><funcprototype> 3079 <funcdef>int <function>usb_urb_dir_out </function></funcdef> 3080 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3081 </funcprototype></funcsynopsis> 3082</refsynopsisdiv> 3083<refsect1> 3084 <title>Arguments</title> 3085 <variablelist> 3086 <varlistentry> 3087 <term><parameter>urb</parameter></term> 3088 <listitem> 3089 <para> 3090 URB to be checked 3091 </para> 3092 </listitem> 3093 </varlistentry> 3094 </variablelist> 3095</refsect1> 3096<refsect1> 3097<title>Return</title> 3098<para> 3099 1 if <parameter>urb</parameter> describes an OUT transfer (host-to-device), 3100 otherwise 0. 3101</para> 3102</refsect1> 3103</refentry> 3104 3105<refentry id="API-struct-usb-sg-request"> 3106<refentryinfo> 3107 <title>LINUX</title> 3108 <productname>Kernel Hackers Manual</productname> 3109 <date>July 2017</date> 3110</refentryinfo> 3111<refmeta> 3112 <refentrytitle><phrase>struct usb_sg_request</phrase></refentrytitle> 3113 <manvolnum>9</manvolnum> 3114 <refmiscinfo class="version">4.1.27</refmiscinfo> 3115</refmeta> 3116<refnamediv> 3117 <refname>struct usb_sg_request</refname> 3118 <refpurpose> 3119 support for scatter/gather I/O 3120 </refpurpose> 3121</refnamediv> 3122<refsynopsisdiv> 3123 <title>Synopsis</title> 3124 <programlisting> 3125struct usb_sg_request { 3126 int status; 3127 size_t bytes; 3128}; </programlisting> 3129</refsynopsisdiv> 3130 <refsect1> 3131 <title>Members</title> 3132 <variablelist> 3133 <varlistentry> <term>status</term> 3134 <listitem><para> 3135 zero indicates success, else negative errno 3136 </para></listitem> 3137 </varlistentry> 3138 <varlistentry> <term>bytes</term> 3139 <listitem><para> 3140 counts bytes transferred. 3141 </para></listitem> 3142 </varlistentry> 3143 </variablelist> 3144 </refsect1> 3145<refsect1> 3146<title>Description</title> 3147<para> 3148 These requests are initialized using <function>usb_sg_init</function>, and then are used 3149 as request handles passed to <function>usb_sg_wait</function> or <function>usb_sg_cancel</function>. Most 3150 members of the request object aren't for driver access. 3151 </para><para> 3152 3153 The status and bytecount values are valid only after <function>usb_sg_wait</function> 3154 returns. If the status is zero, then the bytecount matches the total 3155 from the request. 3156 </para><para> 3157 3158 After an error completion, drivers may need to clear a halt condition 3159 on the endpoint. 3160</para> 3161</refsect1> 3162</refentry> 3163 3164 3165 </chapter> 3166 3167 <chapter id="usbcore"><title>USB Core APIs</title> 3168 3169 <para>There are two basic I/O models in the USB API. 3170 The most elemental one is asynchronous: drivers submit requests 3171 in the form of an URB, and the URB's completion callback 3172 handle the next step. 3173 All USB transfer types support that model, although there 3174 are special cases for control URBs (which always have setup 3175 and status stages, but may not have a data stage) and 3176 isochronous URBs (which allow large packets and include 3177 per-packet fault reports). 3178 Built on top of that is synchronous API support, where a 3179 driver calls a routine that allocates one or more URBs, 3180 submits them, and waits until they complete. 3181 There are synchronous wrappers for single-buffer control 3182 and bulk transfers (which are awkward to use in some 3183 driver disconnect scenarios), and for scatterlist based 3184 streaming i/o (bulk or interrupt). 3185 </para> 3186 3187 <para>USB drivers need to provide buffers that can be 3188 used for DMA, although they don't necessarily need to 3189 provide the DMA mapping themselves. 3190 There are APIs to use used when allocating DMA buffers, 3191 which can prevent use of bounce buffers on some systems. 3192 In some cases, drivers may be able to rely on 64bit DMA 3193 to eliminate another kind of bounce buffer. 3194 </para> 3195 3196<!-- drivers/usb/core/urb.c --> 3197<refentry id="API-usb-init-urb"> 3198<refentryinfo> 3199 <title>LINUX</title> 3200 <productname>Kernel Hackers Manual</productname> 3201 <date>July 2017</date> 3202</refentryinfo> 3203<refmeta> 3204 <refentrytitle><phrase>usb_init_urb</phrase></refentrytitle> 3205 <manvolnum>9</manvolnum> 3206 <refmiscinfo class="version">4.1.27</refmiscinfo> 3207</refmeta> 3208<refnamediv> 3209 <refname>usb_init_urb</refname> 3210 <refpurpose> 3211 initializes a urb so that it can be used by a USB driver 3212 </refpurpose> 3213</refnamediv> 3214<refsynopsisdiv> 3215 <title>Synopsis</title> 3216 <funcsynopsis><funcprototype> 3217 <funcdef>void <function>usb_init_urb </function></funcdef> 3218 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3219 </funcprototype></funcsynopsis> 3220</refsynopsisdiv> 3221<refsect1> 3222 <title>Arguments</title> 3223 <variablelist> 3224 <varlistentry> 3225 <term><parameter>urb</parameter></term> 3226 <listitem> 3227 <para> 3228 pointer to the urb to initialize 3229 </para> 3230 </listitem> 3231 </varlistentry> 3232 </variablelist> 3233</refsect1> 3234<refsect1> 3235<title>Description</title> 3236<para> 3237 Initializes a urb so that the USB subsystem can use it properly. 3238 </para><para> 3239 3240 If a urb is created with a call to <function>usb_alloc_urb</function> it is not 3241 necessary to call this function. Only use this if you allocate the 3242 space for a struct urb on your own. If you call this function, be 3243 careful when freeing the memory for your urb that it is no longer in 3244 use by the USB core. 3245 </para><para> 3246 3247 Only use this function if you _really_ understand what you are doing. 3248</para> 3249</refsect1> 3250</refentry> 3251 3252<refentry id="API-usb-alloc-urb"> 3253<refentryinfo> 3254 <title>LINUX</title> 3255 <productname>Kernel Hackers Manual</productname> 3256 <date>July 2017</date> 3257</refentryinfo> 3258<refmeta> 3259 <refentrytitle><phrase>usb_alloc_urb</phrase></refentrytitle> 3260 <manvolnum>9</manvolnum> 3261 <refmiscinfo class="version">4.1.27</refmiscinfo> 3262</refmeta> 3263<refnamediv> 3264 <refname>usb_alloc_urb</refname> 3265 <refpurpose> 3266 creates a new urb for a USB driver to use 3267 </refpurpose> 3268</refnamediv> 3269<refsynopsisdiv> 3270 <title>Synopsis</title> 3271 <funcsynopsis><funcprototype> 3272 <funcdef>struct urb * <function>usb_alloc_urb </function></funcdef> 3273 <paramdef>int <parameter>iso_packets</parameter></paramdef> 3274 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 3275 </funcprototype></funcsynopsis> 3276</refsynopsisdiv> 3277<refsect1> 3278 <title>Arguments</title> 3279 <variablelist> 3280 <varlistentry> 3281 <term><parameter>iso_packets</parameter></term> 3282 <listitem> 3283 <para> 3284 number of iso packets for this urb 3285 </para> 3286 </listitem> 3287 </varlistentry> 3288 <varlistentry> 3289 <term><parameter>mem_flags</parameter></term> 3290 <listitem> 3291 <para> 3292 the type of memory to allocate, see <function>kmalloc</function> for a list of 3293 valid options for this. 3294 </para> 3295 </listitem> 3296 </varlistentry> 3297 </variablelist> 3298</refsect1> 3299<refsect1> 3300<title>Description</title> 3301<para> 3302 Creates an urb for the USB driver to use, initializes a few internal 3303 structures, increments the usage counter, and returns a pointer to it. 3304 </para><para> 3305 3306 If the driver want to use this urb for interrupt, control, or bulk 3307 endpoints, pass '0' as the number of iso packets. 3308 </para><para> 3309 3310 The driver must call <function>usb_free_urb</function> when it is finished with the urb. 3311</para> 3312</refsect1> 3313<refsect1> 3314<title>Return</title> 3315<para> 3316 A pointer to the new urb, or <constant>NULL</constant> if no memory is available. 3317</para> 3318</refsect1> 3319</refentry> 3320 3321<refentry id="API-usb-free-urb"> 3322<refentryinfo> 3323 <title>LINUX</title> 3324 <productname>Kernel Hackers Manual</productname> 3325 <date>July 2017</date> 3326</refentryinfo> 3327<refmeta> 3328 <refentrytitle><phrase>usb_free_urb</phrase></refentrytitle> 3329 <manvolnum>9</manvolnum> 3330 <refmiscinfo class="version">4.1.27</refmiscinfo> 3331</refmeta> 3332<refnamediv> 3333 <refname>usb_free_urb</refname> 3334 <refpurpose> 3335 frees the memory used by a urb when all users of it are finished 3336 </refpurpose> 3337</refnamediv> 3338<refsynopsisdiv> 3339 <title>Synopsis</title> 3340 <funcsynopsis><funcprototype> 3341 <funcdef>void <function>usb_free_urb </function></funcdef> 3342 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3343 </funcprototype></funcsynopsis> 3344</refsynopsisdiv> 3345<refsect1> 3346 <title>Arguments</title> 3347 <variablelist> 3348 <varlistentry> 3349 <term><parameter>urb</parameter></term> 3350 <listitem> 3351 <para> 3352 pointer to the urb to free, may be NULL 3353 </para> 3354 </listitem> 3355 </varlistentry> 3356 </variablelist> 3357</refsect1> 3358<refsect1> 3359<title>Description</title> 3360<para> 3361 Must be called when a user of a urb is finished with it. When the last user 3362 of the urb calls this function, the memory of the urb is freed. 3363</para> 3364</refsect1> 3365<refsect1> 3366<title>Note</title> 3367<para> 3368 The transfer buffer associated with the urb is not freed unless the 3369 URB_FREE_BUFFER transfer flag is set. 3370</para> 3371</refsect1> 3372</refentry> 3373 3374<refentry id="API-usb-get-urb"> 3375<refentryinfo> 3376 <title>LINUX</title> 3377 <productname>Kernel Hackers Manual</productname> 3378 <date>July 2017</date> 3379</refentryinfo> 3380<refmeta> 3381 <refentrytitle><phrase>usb_get_urb</phrase></refentrytitle> 3382 <manvolnum>9</manvolnum> 3383 <refmiscinfo class="version">4.1.27</refmiscinfo> 3384</refmeta> 3385<refnamediv> 3386 <refname>usb_get_urb</refname> 3387 <refpurpose> 3388 increments the reference count of the urb 3389 </refpurpose> 3390</refnamediv> 3391<refsynopsisdiv> 3392 <title>Synopsis</title> 3393 <funcsynopsis><funcprototype> 3394 <funcdef>struct urb * <function>usb_get_urb </function></funcdef> 3395 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3396 </funcprototype></funcsynopsis> 3397</refsynopsisdiv> 3398<refsect1> 3399 <title>Arguments</title> 3400 <variablelist> 3401 <varlistentry> 3402 <term><parameter>urb</parameter></term> 3403 <listitem> 3404 <para> 3405 pointer to the urb to modify, may be NULL 3406 </para> 3407 </listitem> 3408 </varlistentry> 3409 </variablelist> 3410</refsect1> 3411<refsect1> 3412<title>Description</title> 3413<para> 3414 This must be called whenever a urb is transferred from a device driver to a 3415 host controller driver. This allows proper reference counting to happen 3416 for urbs. 3417</para> 3418</refsect1> 3419<refsect1> 3420<title>Return</title> 3421<para> 3422 A pointer to the urb with the incremented reference counter. 3423</para> 3424</refsect1> 3425</refentry> 3426 3427<refentry id="API-usb-anchor-urb"> 3428<refentryinfo> 3429 <title>LINUX</title> 3430 <productname>Kernel Hackers Manual</productname> 3431 <date>July 2017</date> 3432</refentryinfo> 3433<refmeta> 3434 <refentrytitle><phrase>usb_anchor_urb</phrase></refentrytitle> 3435 <manvolnum>9</manvolnum> 3436 <refmiscinfo class="version">4.1.27</refmiscinfo> 3437</refmeta> 3438<refnamediv> 3439 <refname>usb_anchor_urb</refname> 3440 <refpurpose> 3441 anchors an URB while it is processed 3442 </refpurpose> 3443</refnamediv> 3444<refsynopsisdiv> 3445 <title>Synopsis</title> 3446 <funcsynopsis><funcprototype> 3447 <funcdef>void <function>usb_anchor_urb </function></funcdef> 3448 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3449 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 3450 </funcprototype></funcsynopsis> 3451</refsynopsisdiv> 3452<refsect1> 3453 <title>Arguments</title> 3454 <variablelist> 3455 <varlistentry> 3456 <term><parameter>urb</parameter></term> 3457 <listitem> 3458 <para> 3459 pointer to the urb to anchor 3460 </para> 3461 </listitem> 3462 </varlistentry> 3463 <varlistentry> 3464 <term><parameter>anchor</parameter></term> 3465 <listitem> 3466 <para> 3467 pointer to the anchor 3468 </para> 3469 </listitem> 3470 </varlistentry> 3471 </variablelist> 3472</refsect1> 3473<refsect1> 3474<title>Description</title> 3475<para> 3476 This can be called to have access to URBs which are to be executed 3477 without bothering to track them 3478</para> 3479</refsect1> 3480</refentry> 3481 3482<refentry id="API-usb-unanchor-urb"> 3483<refentryinfo> 3484 <title>LINUX</title> 3485 <productname>Kernel Hackers Manual</productname> 3486 <date>July 2017</date> 3487</refentryinfo> 3488<refmeta> 3489 <refentrytitle><phrase>usb_unanchor_urb</phrase></refentrytitle> 3490 <manvolnum>9</manvolnum> 3491 <refmiscinfo class="version">4.1.27</refmiscinfo> 3492</refmeta> 3493<refnamediv> 3494 <refname>usb_unanchor_urb</refname> 3495 <refpurpose> 3496 unanchors an URB 3497 </refpurpose> 3498</refnamediv> 3499<refsynopsisdiv> 3500 <title>Synopsis</title> 3501 <funcsynopsis><funcprototype> 3502 <funcdef>void <function>usb_unanchor_urb </function></funcdef> 3503 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3504 </funcprototype></funcsynopsis> 3505</refsynopsisdiv> 3506<refsect1> 3507 <title>Arguments</title> 3508 <variablelist> 3509 <varlistentry> 3510 <term><parameter>urb</parameter></term> 3511 <listitem> 3512 <para> 3513 pointer to the urb to anchor 3514 </para> 3515 </listitem> 3516 </varlistentry> 3517 </variablelist> 3518</refsect1> 3519<refsect1> 3520<title>Description</title> 3521<para> 3522 Call this to stop the system keeping track of this URB 3523</para> 3524</refsect1> 3525</refentry> 3526 3527<refentry id="API-usb-submit-urb"> 3528<refentryinfo> 3529 <title>LINUX</title> 3530 <productname>Kernel Hackers Manual</productname> 3531 <date>July 2017</date> 3532</refentryinfo> 3533<refmeta> 3534 <refentrytitle><phrase>usb_submit_urb</phrase></refentrytitle> 3535 <manvolnum>9</manvolnum> 3536 <refmiscinfo class="version">4.1.27</refmiscinfo> 3537</refmeta> 3538<refnamediv> 3539 <refname>usb_submit_urb</refname> 3540 <refpurpose> 3541 issue an asynchronous transfer request for an endpoint 3542 </refpurpose> 3543</refnamediv> 3544<refsynopsisdiv> 3545 <title>Synopsis</title> 3546 <funcsynopsis><funcprototype> 3547 <funcdef>int <function>usb_submit_urb </function></funcdef> 3548 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3549 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 3550 </funcprototype></funcsynopsis> 3551</refsynopsisdiv> 3552<refsect1> 3553 <title>Arguments</title> 3554 <variablelist> 3555 <varlistentry> 3556 <term><parameter>urb</parameter></term> 3557 <listitem> 3558 <para> 3559 pointer to the urb describing the request 3560 </para> 3561 </listitem> 3562 </varlistentry> 3563 <varlistentry> 3564 <term><parameter>mem_flags</parameter></term> 3565 <listitem> 3566 <para> 3567 the type of memory to allocate, see <function>kmalloc</function> for a list 3568 of valid options for this. 3569 </para> 3570 </listitem> 3571 </varlistentry> 3572 </variablelist> 3573</refsect1> 3574<refsect1> 3575<title>Description</title> 3576<para> 3577 This submits a transfer request, and transfers control of the URB 3578 describing that request to the USB subsystem. Request completion will 3579 be indicated later, asynchronously, by calling the completion handler. 3580 The three types of completion are success, error, and unlink 3581 (a software-induced fault, also called <quote>request cancellation</quote>). 3582 </para><para> 3583 3584 URBs may be submitted in interrupt context. 3585 </para><para> 3586 3587 The caller must have correctly initialized the URB before submitting 3588 it. Functions such as <function>usb_fill_bulk_urb</function> and <function>usb_fill_control_urb</function> are 3589 available to ensure that most fields are correctly initialized, for 3590 the particular kind of transfer, although they will not initialize 3591 any transfer flags. 3592 </para><para> 3593 3594 If the submission is successful, the <function>complete</function> callback from the URB 3595 will be called exactly once, when the USB core and Host Controller Driver 3596 (HCD) are finished with the URB. When the completion function is called, 3597 control of the URB is returned to the device driver which issued the 3598 request. The completion handler may then immediately free or reuse that 3599 URB. 3600 </para><para> 3601 3602 With few exceptions, USB device drivers should never access URB fields 3603 provided by usbcore or the HCD until its <function>complete</function> is called. 3604 The exceptions relate to periodic transfer scheduling. For both 3605 interrupt and isochronous urbs, as part of successful URB submission 3606 urb->interval is modified to reflect the actual transfer period used 3607 (normally some power of two units). And for isochronous urbs, 3608 urb->start_frame is modified to reflect when the URB's transfers were 3609 scheduled to start. 3610 </para><para> 3611 3612 Not all isochronous transfer scheduling policies will work, but most 3613 host controller drivers should easily handle ISO queues going from now 3614 until 10-200 msec into the future. Drivers should try to keep at 3615 least one or two msec of data in the queue; many controllers require 3616 that new transfers start at least 1 msec in the future when they are 3617 added. If the driver is unable to keep up and the queue empties out, 3618 the behavior for new submissions is governed by the URB_ISO_ASAP flag. 3619 If the flag is set, or if the queue is idle, then the URB is always 3620 assigned to the first available (and not yet expired) slot in the 3621 endpoint's schedule. If the flag is not set and the queue is active 3622 then the URB is always assigned to the next slot in the schedule 3623 following the end of the endpoint's previous URB, even if that slot is 3624 in the past. When a packet is assigned in this way to a slot that has 3625 already expired, the packet is not transmitted and the corresponding 3626 usb_iso_packet_descriptor's status field will return -EXDEV. If this 3627 would happen to all the packets in the URB, submission fails with a 3628 -EXDEV error code. 3629 </para><para> 3630 3631 For control endpoints, the synchronous <function>usb_control_msg</function> call is 3632 often used (in non-interrupt context) instead of this call. 3633 That is often used through convenience wrappers, for the requests 3634 that are standardized in the USB 2.0 specification. For bulk 3635 endpoints, a synchronous <function>usb_bulk_msg</function> call is available. 3636</para> 3637</refsect1> 3638<refsect1> 3639<title>Return</title> 3640<para> 3641 0 on successful submissions. A negative error number otherwise. 3642</para> 3643</refsect1> 3644<refsect1> 3645<title>Request Queuing</title> 3646<para> 3647 </para><para> 3648 3649 URBs may be submitted to endpoints before previous ones complete, to 3650 minimize the impact of interrupt latencies and system overhead on data 3651 throughput. With that queuing policy, an endpoint's queue would never 3652 be empty. This is required for continuous isochronous data streams, 3653 and may also be required for some kinds of interrupt transfers. Such 3654 queuing also maximizes bandwidth utilization by letting USB controllers 3655 start work on later requests before driver software has finished the 3656 completion processing for earlier (successful) requests. 3657 </para><para> 3658 3659 As of Linux 2.6, all USB endpoint transfer queues support depths greater 3660 than one. This was previously a HCD-specific behavior, except for ISO 3661 transfers. Non-isochronous endpoint queues are inactive during cleanup 3662 after faults (transfer errors or cancellation). 3663</para> 3664</refsect1> 3665<refsect1> 3666<title>Reserved Bandwidth Transfers</title> 3667<para> 3668 </para><para> 3669 3670 Periodic transfers (interrupt or isochronous) are performed repeatedly, 3671 using the interval specified in the urb. Submitting the first urb to 3672 the endpoint reserves the bandwidth necessary to make those transfers. 3673 If the USB subsystem can't allocate sufficient bandwidth to perform 3674 the periodic request, submitting such a periodic request should fail. 3675 </para><para> 3676 3677 For devices under xHCI, the bandwidth is reserved at configuration time, or 3678 when the alt setting is selected. If there is not enough bus bandwidth, the 3679 configuration/alt setting request will fail. Therefore, submissions to 3680 periodic endpoints on devices under xHCI should never fail due to bandwidth 3681 constraints. 3682 </para><para> 3683 3684 Device drivers must explicitly request that repetition, by ensuring that 3685 some URB is always on the endpoint's queue (except possibly for short 3686 periods during completion callbacks). When there is no longer an urb 3687 queued, the endpoint's bandwidth reservation is canceled. This means 3688 drivers can use their completion handlers to ensure they keep bandwidth 3689 they need, by reinitializing and resubmitting the just-completed urb 3690 until the driver longer needs that periodic bandwidth. 3691</para> 3692</refsect1> 3693<refsect1> 3694<title>Memory Flags</title> 3695<para> 3696 </para><para> 3697 3698 The general rules for how to decide which mem_flags to use 3699 are the same as for kmalloc. There are four 3700 different possible values; GFP_KERNEL, GFP_NOFS, GFP_NOIO and 3701 GFP_ATOMIC. 3702 </para><para> 3703 3704 GFP_NOFS is not ever used, as it has not been implemented yet. 3705 </para><para> 3706 3707 GFP_ATOMIC is used when 3708 (a) you are inside a completion handler, an interrupt, bottom half, 3709 tasklet or timer, or 3710 (b) you are holding a spinlock or rwlock (does not apply to 3711 semaphores), or 3712 (c) current->state != TASK_RUNNING, this is the case only after 3713 you've changed it. 3714 </para><para> 3715 3716 GFP_NOIO is used in the block io path and error handling of storage 3717 devices. 3718 </para><para> 3719 3720 All other situations use GFP_KERNEL. 3721 </para><para> 3722 3723 Some more specific rules for mem_flags can be inferred, such as 3724 (1) start_xmit, timeout, and receive methods of network drivers must 3725 use GFP_ATOMIC (they are called with a spinlock held); 3726 (2) queuecommand methods of scsi drivers must use GFP_ATOMIC (also 3727 called with a spinlock held); 3728 (3) If you use a kernel thread with a network driver you must use 3729 GFP_NOIO, unless (b) or (c) apply; 3730 (4) after you have done a <function>down</function> you can use GFP_KERNEL, unless (b) or (c) 3731 apply or your are in a storage driver's block io path; 3732 (5) USB probe and disconnect can use GFP_KERNEL unless (b) or (c) apply; and 3733 (6) changing firmware on a running storage or net device uses 3734 GFP_NOIO, unless b) or c) apply 3735</para> 3736</refsect1> 3737</refentry> 3738 3739<refentry id="API-usb-unlink-urb"> 3740<refentryinfo> 3741 <title>LINUX</title> 3742 <productname>Kernel Hackers Manual</productname> 3743 <date>July 2017</date> 3744</refentryinfo> 3745<refmeta> 3746 <refentrytitle><phrase>usb_unlink_urb</phrase></refentrytitle> 3747 <manvolnum>9</manvolnum> 3748 <refmiscinfo class="version">4.1.27</refmiscinfo> 3749</refmeta> 3750<refnamediv> 3751 <refname>usb_unlink_urb</refname> 3752 <refpurpose> 3753 abort/cancel a transfer request for an endpoint 3754 </refpurpose> 3755</refnamediv> 3756<refsynopsisdiv> 3757 <title>Synopsis</title> 3758 <funcsynopsis><funcprototype> 3759 <funcdef>int <function>usb_unlink_urb </function></funcdef> 3760 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3761 </funcprototype></funcsynopsis> 3762</refsynopsisdiv> 3763<refsect1> 3764 <title>Arguments</title> 3765 <variablelist> 3766 <varlistentry> 3767 <term><parameter>urb</parameter></term> 3768 <listitem> 3769 <para> 3770 pointer to urb describing a previously submitted request, 3771 may be NULL 3772 </para> 3773 </listitem> 3774 </varlistentry> 3775 </variablelist> 3776</refsect1> 3777<refsect1> 3778<title>Description</title> 3779<para> 3780 This routine cancels an in-progress request. URBs complete only once 3781 per submission, and may be canceled only once per submission. 3782 Successful cancellation means termination of <parameter>urb</parameter> will be expedited 3783 and the completion handler will be called with a status code 3784 indicating that the request has been canceled (rather than any other 3785 code). 3786 </para><para> 3787 3788 Drivers should not call this routine or related routines, such as 3789 <function>usb_kill_urb</function> or <function>usb_unlink_anchored_urbs</function>, after their disconnect 3790 method has returned. The disconnect function should synchronize with 3791 a driver's I/O routines to insure that all URB-related activity has 3792 completed before it returns. 3793 </para><para> 3794 3795 This request is asynchronous, however the HCD might call the -><function>complete</function> 3796 callback during unlink. Therefore when drivers call <function>usb_unlink_urb</function>, they 3797 must not hold any locks that may be taken by the completion function. 3798 Success is indicated by returning -EINPROGRESS, at which time the URB will 3799 probably not yet have been given back to the device driver. When it is 3800 eventually called, the completion function will see <parameter>urb</parameter>->status == 3801 -ECONNRESET. 3802 Failure is indicated by <function>usb_unlink_urb</function> returning any other value. 3803 Unlinking will fail when <parameter>urb</parameter> is not currently <quote>linked</quote> (i.e., it was 3804 never submitted, or it was unlinked before, or the hardware is already 3805 finished with it), even if the completion handler has not yet run. 3806 </para><para> 3807 3808 The URB must not be deallocated while this routine is running. In 3809 particular, when a driver calls this routine, it must insure that the 3810 completion handler cannot deallocate the URB. 3811</para> 3812</refsect1> 3813<refsect1> 3814<title>Return</title> 3815<para> 3816 -EINPROGRESS on success. See description for other values on 3817 failure. 3818</para> 3819</refsect1> 3820<refsect1> 3821<title>Unlinking and Endpoint Queues</title> 3822<para> 3823 </para><para> 3824 3825 [The behaviors and guarantees described below do not apply to virtual 3826 root hubs but only to endpoint queues for physical USB devices.] 3827 </para><para> 3828 3829 Host Controller Drivers (HCDs) place all the URBs for a particular 3830 endpoint in a queue. Normally the queue advances as the controller 3831 hardware processes each request. But when an URB terminates with an 3832 error its queue generally stops (see below), at least until that URB's 3833 completion routine returns. It is guaranteed that a stopped queue 3834 will not restart until all its unlinked URBs have been fully retired, 3835 with their completion routines run, even if that's not until some time 3836 after the original completion handler returns. The same behavior and 3837 guarantee apply when an URB terminates because it was unlinked. 3838 </para><para> 3839 3840 Bulk and interrupt endpoint queues are guaranteed to stop whenever an 3841 URB terminates with any sort of error, including -ECONNRESET, -ENOENT, 3842 and -EREMOTEIO. Control endpoint queues behave the same way except 3843 that they are not guaranteed to stop for -EREMOTEIO errors. Queues 3844 for isochronous endpoints are treated differently, because they must 3845 advance at fixed rates. Such queues do not stop when an URB 3846 encounters an error or is unlinked. An unlinked isochronous URB may 3847 leave a gap in the stream of packets; it is undefined whether such 3848 gaps can be filled in. 3849 </para><para> 3850 3851 Note that early termination of an URB because a short packet was 3852 received will generate a -EREMOTEIO error if and only if the 3853 URB_SHORT_NOT_OK flag is set. By setting this flag, USB device 3854 drivers can build deep queues for large or complex bulk transfers 3855 and clean them up reliably after any sort of aborted transfer by 3856 unlinking all pending URBs at the first fault. 3857 </para><para> 3858 3859 When a control URB terminates with an error other than -EREMOTEIO, it 3860 is quite likely that the status stage of the transfer will not take 3861 place. 3862</para> 3863</refsect1> 3864</refentry> 3865 3866<refentry id="API-usb-kill-urb"> 3867<refentryinfo> 3868 <title>LINUX</title> 3869 <productname>Kernel Hackers Manual</productname> 3870 <date>July 2017</date> 3871</refentryinfo> 3872<refmeta> 3873 <refentrytitle><phrase>usb_kill_urb</phrase></refentrytitle> 3874 <manvolnum>9</manvolnum> 3875 <refmiscinfo class="version">4.1.27</refmiscinfo> 3876</refmeta> 3877<refnamediv> 3878 <refname>usb_kill_urb</refname> 3879 <refpurpose> 3880 cancel a transfer request and wait for it to finish 3881 </refpurpose> 3882</refnamediv> 3883<refsynopsisdiv> 3884 <title>Synopsis</title> 3885 <funcsynopsis><funcprototype> 3886 <funcdef>void <function>usb_kill_urb </function></funcdef> 3887 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3888 </funcprototype></funcsynopsis> 3889</refsynopsisdiv> 3890<refsect1> 3891 <title>Arguments</title> 3892 <variablelist> 3893 <varlistentry> 3894 <term><parameter>urb</parameter></term> 3895 <listitem> 3896 <para> 3897 pointer to URB describing a previously submitted request, 3898 may be NULL 3899 </para> 3900 </listitem> 3901 </varlistentry> 3902 </variablelist> 3903</refsect1> 3904<refsect1> 3905<title>Description</title> 3906<para> 3907 This routine cancels an in-progress request. It is guaranteed that 3908 upon return all completion handlers will have finished and the URB 3909 will be totally idle and available for reuse. These features make 3910 this an ideal way to stop I/O in a <function>disconnect</function> callback or <function>close</function> 3911 function. If the request has not already finished or been unlinked 3912 the completion handler will see urb->status == -ENOENT. 3913 </para><para> 3914 3915 While the routine is running, attempts to resubmit the URB will fail 3916 with error -EPERM. Thus even if the URB's completion handler always 3917 tries to resubmit, it will not succeed and the URB will become idle. 3918 </para><para> 3919 3920 The URB must not be deallocated while this routine is running. In 3921 particular, when a driver calls this routine, it must insure that the 3922 completion handler cannot deallocate the URB. 3923 </para><para> 3924 3925 This routine may not be used in an interrupt context (such as a bottom 3926 half or a completion handler), or when holding a spinlock, or in other 3927 situations where the caller can't <function>schedule</function>. 3928 </para><para> 3929 3930 This routine should not be called by a driver after its disconnect 3931 method has returned. 3932</para> 3933</refsect1> 3934</refentry> 3935 3936<refentry id="API-usb-poison-urb"> 3937<refentryinfo> 3938 <title>LINUX</title> 3939 <productname>Kernel Hackers Manual</productname> 3940 <date>July 2017</date> 3941</refentryinfo> 3942<refmeta> 3943 <refentrytitle><phrase>usb_poison_urb</phrase></refentrytitle> 3944 <manvolnum>9</manvolnum> 3945 <refmiscinfo class="version">4.1.27</refmiscinfo> 3946</refmeta> 3947<refnamediv> 3948 <refname>usb_poison_urb</refname> 3949 <refpurpose> 3950 reliably kill a transfer and prevent further use of an URB 3951 </refpurpose> 3952</refnamediv> 3953<refsynopsisdiv> 3954 <title>Synopsis</title> 3955 <funcsynopsis><funcprototype> 3956 <funcdef>void <function>usb_poison_urb </function></funcdef> 3957 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 3958 </funcprototype></funcsynopsis> 3959</refsynopsisdiv> 3960<refsect1> 3961 <title>Arguments</title> 3962 <variablelist> 3963 <varlistentry> 3964 <term><parameter>urb</parameter></term> 3965 <listitem> 3966 <para> 3967 pointer to URB describing a previously submitted request, 3968 may be NULL 3969 </para> 3970 </listitem> 3971 </varlistentry> 3972 </variablelist> 3973</refsect1> 3974<refsect1> 3975<title>Description</title> 3976<para> 3977 This routine cancels an in-progress request. It is guaranteed that 3978 upon return all completion handlers will have finished and the URB 3979 will be totally idle and cannot be reused. These features make 3980 this an ideal way to stop I/O in a <function>disconnect</function> callback. 3981 If the request has not already finished or been unlinked 3982 the completion handler will see urb->status == -ENOENT. 3983 </para><para> 3984 3985 After and while the routine runs, attempts to resubmit the URB will fail 3986 with error -EPERM. Thus even if the URB's completion handler always 3987 tries to resubmit, it will not succeed and the URB will become idle. 3988 </para><para> 3989 3990 The URB must not be deallocated while this routine is running. In 3991 particular, when a driver calls this routine, it must insure that the 3992 completion handler cannot deallocate the URB. 3993 </para><para> 3994 3995 This routine may not be used in an interrupt context (such as a bottom 3996 half or a completion handler), or when holding a spinlock, or in other 3997 situations where the caller can't <function>schedule</function>. 3998 </para><para> 3999 4000 This routine should not be called by a driver after its disconnect 4001 method has returned. 4002</para> 4003</refsect1> 4004</refentry> 4005 4006<refentry id="API-usb-block-urb"> 4007<refentryinfo> 4008 <title>LINUX</title> 4009 <productname>Kernel Hackers Manual</productname> 4010 <date>July 2017</date> 4011</refentryinfo> 4012<refmeta> 4013 <refentrytitle><phrase>usb_block_urb</phrase></refentrytitle> 4014 <manvolnum>9</manvolnum> 4015 <refmiscinfo class="version">4.1.27</refmiscinfo> 4016</refmeta> 4017<refnamediv> 4018 <refname>usb_block_urb</refname> 4019 <refpurpose> 4020 reliably prevent further use of an URB 4021 </refpurpose> 4022</refnamediv> 4023<refsynopsisdiv> 4024 <title>Synopsis</title> 4025 <funcsynopsis><funcprototype> 4026 <funcdef>void <function>usb_block_urb </function></funcdef> 4027 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 4028 </funcprototype></funcsynopsis> 4029</refsynopsisdiv> 4030<refsect1> 4031 <title>Arguments</title> 4032 <variablelist> 4033 <varlistentry> 4034 <term><parameter>urb</parameter></term> 4035 <listitem> 4036 <para> 4037 pointer to URB to be blocked, may be NULL 4038 </para> 4039 </listitem> 4040 </varlistentry> 4041 </variablelist> 4042</refsect1> 4043<refsect1> 4044<title>Description</title> 4045<para> 4046 After the routine has run, attempts to resubmit the URB will fail 4047 with error -EPERM. Thus even if the URB's completion handler always 4048 tries to resubmit, it will not succeed and the URB will become idle. 4049 </para><para> 4050 4051 The URB must not be deallocated while this routine is running. In 4052 particular, when a driver calls this routine, it must insure that the 4053 completion handler cannot deallocate the URB. 4054</para> 4055</refsect1> 4056</refentry> 4057 4058<refentry id="API-usb-kill-anchored-urbs"> 4059<refentryinfo> 4060 <title>LINUX</title> 4061 <productname>Kernel Hackers Manual</productname> 4062 <date>July 2017</date> 4063</refentryinfo> 4064<refmeta> 4065 <refentrytitle><phrase>usb_kill_anchored_urbs</phrase></refentrytitle> 4066 <manvolnum>9</manvolnum> 4067 <refmiscinfo class="version">4.1.27</refmiscinfo> 4068</refmeta> 4069<refnamediv> 4070 <refname>usb_kill_anchored_urbs</refname> 4071 <refpurpose> 4072 cancel transfer requests en masse 4073 </refpurpose> 4074</refnamediv> 4075<refsynopsisdiv> 4076 <title>Synopsis</title> 4077 <funcsynopsis><funcprototype> 4078 <funcdef>void <function>usb_kill_anchored_urbs </function></funcdef> 4079 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4080 </funcprototype></funcsynopsis> 4081</refsynopsisdiv> 4082<refsect1> 4083 <title>Arguments</title> 4084 <variablelist> 4085 <varlistentry> 4086 <term><parameter>anchor</parameter></term> 4087 <listitem> 4088 <para> 4089 anchor the requests are bound to 4090 </para> 4091 </listitem> 4092 </varlistentry> 4093 </variablelist> 4094</refsect1> 4095<refsect1> 4096<title>Description</title> 4097<para> 4098 this allows all outstanding URBs to be killed starting 4099 from the back of the queue 4100 </para><para> 4101 4102 This routine should not be called by a driver after its disconnect 4103 method has returned. 4104</para> 4105</refsect1> 4106</refentry> 4107 4108<refentry id="API-usb-poison-anchored-urbs"> 4109<refentryinfo> 4110 <title>LINUX</title> 4111 <productname>Kernel Hackers Manual</productname> 4112 <date>July 2017</date> 4113</refentryinfo> 4114<refmeta> 4115 <refentrytitle><phrase>usb_poison_anchored_urbs</phrase></refentrytitle> 4116 <manvolnum>9</manvolnum> 4117 <refmiscinfo class="version">4.1.27</refmiscinfo> 4118</refmeta> 4119<refnamediv> 4120 <refname>usb_poison_anchored_urbs</refname> 4121 <refpurpose> 4122 cease all traffic from an anchor 4123 </refpurpose> 4124</refnamediv> 4125<refsynopsisdiv> 4126 <title>Synopsis</title> 4127 <funcsynopsis><funcprototype> 4128 <funcdef>void <function>usb_poison_anchored_urbs </function></funcdef> 4129 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4130 </funcprototype></funcsynopsis> 4131</refsynopsisdiv> 4132<refsect1> 4133 <title>Arguments</title> 4134 <variablelist> 4135 <varlistentry> 4136 <term><parameter>anchor</parameter></term> 4137 <listitem> 4138 <para> 4139 anchor the requests are bound to 4140 </para> 4141 </listitem> 4142 </varlistentry> 4143 </variablelist> 4144</refsect1> 4145<refsect1> 4146<title>Description</title> 4147<para> 4148 this allows all outstanding URBs to be poisoned starting 4149 from the back of the queue. Newly added URBs will also be 4150 poisoned 4151 </para><para> 4152 4153 This routine should not be called by a driver after its disconnect 4154 method has returned. 4155</para> 4156</refsect1> 4157</refentry> 4158 4159<refentry id="API-usb-unpoison-anchored-urbs"> 4160<refentryinfo> 4161 <title>LINUX</title> 4162 <productname>Kernel Hackers Manual</productname> 4163 <date>July 2017</date> 4164</refentryinfo> 4165<refmeta> 4166 <refentrytitle><phrase>usb_unpoison_anchored_urbs</phrase></refentrytitle> 4167 <manvolnum>9</manvolnum> 4168 <refmiscinfo class="version">4.1.27</refmiscinfo> 4169</refmeta> 4170<refnamediv> 4171 <refname>usb_unpoison_anchored_urbs</refname> 4172 <refpurpose> 4173 let an anchor be used successfully again 4174 </refpurpose> 4175</refnamediv> 4176<refsynopsisdiv> 4177 <title>Synopsis</title> 4178 <funcsynopsis><funcprototype> 4179 <funcdef>void <function>usb_unpoison_anchored_urbs </function></funcdef> 4180 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4181 </funcprototype></funcsynopsis> 4182</refsynopsisdiv> 4183<refsect1> 4184 <title>Arguments</title> 4185 <variablelist> 4186 <varlistentry> 4187 <term><parameter>anchor</parameter></term> 4188 <listitem> 4189 <para> 4190 anchor the requests are bound to 4191 </para> 4192 </listitem> 4193 </varlistentry> 4194 </variablelist> 4195</refsect1> 4196<refsect1> 4197<title>Description</title> 4198<para> 4199 Reverses the effect of usb_poison_anchored_urbs 4200 the anchor can be used normally after it returns 4201</para> 4202</refsect1> 4203</refentry> 4204 4205<refentry id="API-usb-unlink-anchored-urbs"> 4206<refentryinfo> 4207 <title>LINUX</title> 4208 <productname>Kernel Hackers Manual</productname> 4209 <date>July 2017</date> 4210</refentryinfo> 4211<refmeta> 4212 <refentrytitle><phrase>usb_unlink_anchored_urbs</phrase></refentrytitle> 4213 <manvolnum>9</manvolnum> 4214 <refmiscinfo class="version">4.1.27</refmiscinfo> 4215</refmeta> 4216<refnamediv> 4217 <refname>usb_unlink_anchored_urbs</refname> 4218 <refpurpose> 4219 asynchronously cancel transfer requests en masse 4220 </refpurpose> 4221</refnamediv> 4222<refsynopsisdiv> 4223 <title>Synopsis</title> 4224 <funcsynopsis><funcprototype> 4225 <funcdef>void <function>usb_unlink_anchored_urbs </function></funcdef> 4226 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4227 </funcprototype></funcsynopsis> 4228</refsynopsisdiv> 4229<refsect1> 4230 <title>Arguments</title> 4231 <variablelist> 4232 <varlistentry> 4233 <term><parameter>anchor</parameter></term> 4234 <listitem> 4235 <para> 4236 anchor the requests are bound to 4237 </para> 4238 </listitem> 4239 </varlistentry> 4240 </variablelist> 4241</refsect1> 4242<refsect1> 4243<title>Description</title> 4244<para> 4245 this allows all outstanding URBs to be unlinked starting 4246 from the back of the queue. This function is asynchronous. 4247 The unlinking is just triggered. It may happen after this 4248 function has returned. 4249 </para><para> 4250 4251 This routine should not be called by a driver after its disconnect 4252 method has returned. 4253</para> 4254</refsect1> 4255</refentry> 4256 4257<refentry id="API-usb-anchor-suspend-wakeups"> 4258<refentryinfo> 4259 <title>LINUX</title> 4260 <productname>Kernel Hackers Manual</productname> 4261 <date>July 2017</date> 4262</refentryinfo> 4263<refmeta> 4264 <refentrytitle><phrase>usb_anchor_suspend_wakeups</phrase></refentrytitle> 4265 <manvolnum>9</manvolnum> 4266 <refmiscinfo class="version">4.1.27</refmiscinfo> 4267</refmeta> 4268<refnamediv> 4269 <refname>usb_anchor_suspend_wakeups</refname> 4270 <refpurpose> 4271 </refpurpose> 4272</refnamediv> 4273<refsynopsisdiv> 4274 <title>Synopsis</title> 4275 <funcsynopsis><funcprototype> 4276 <funcdef>void <function>usb_anchor_suspend_wakeups </function></funcdef> 4277 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4278 </funcprototype></funcsynopsis> 4279</refsynopsisdiv> 4280<refsect1> 4281 <title>Arguments</title> 4282 <variablelist> 4283 <varlistentry> 4284 <term><parameter>anchor</parameter></term> 4285 <listitem> 4286 <para> 4287 the anchor you want to suspend wakeups on 4288 </para> 4289 </listitem> 4290 </varlistentry> 4291 </variablelist> 4292</refsect1> 4293<refsect1> 4294<title>Description</title> 4295<para> 4296 Call this to stop the last urb being unanchored from waking up any 4297 usb_wait_anchor_empty_timeout waiters. This is used in the hcd urb give- 4298 back path to delay waking up until after the completion handler has run. 4299</para> 4300</refsect1> 4301</refentry> 4302 4303<refentry id="API-usb-anchor-resume-wakeups"> 4304<refentryinfo> 4305 <title>LINUX</title> 4306 <productname>Kernel Hackers Manual</productname> 4307 <date>July 2017</date> 4308</refentryinfo> 4309<refmeta> 4310 <refentrytitle><phrase>usb_anchor_resume_wakeups</phrase></refentrytitle> 4311 <manvolnum>9</manvolnum> 4312 <refmiscinfo class="version">4.1.27</refmiscinfo> 4313</refmeta> 4314<refnamediv> 4315 <refname>usb_anchor_resume_wakeups</refname> 4316 <refpurpose> 4317 </refpurpose> 4318</refnamediv> 4319<refsynopsisdiv> 4320 <title>Synopsis</title> 4321 <funcsynopsis><funcprototype> 4322 <funcdef>void <function>usb_anchor_resume_wakeups </function></funcdef> 4323 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4324 </funcprototype></funcsynopsis> 4325</refsynopsisdiv> 4326<refsect1> 4327 <title>Arguments</title> 4328 <variablelist> 4329 <varlistentry> 4330 <term><parameter>anchor</parameter></term> 4331 <listitem> 4332 <para> 4333 the anchor you want to resume wakeups on 4334 </para> 4335 </listitem> 4336 </varlistentry> 4337 </variablelist> 4338</refsect1> 4339<refsect1> 4340<title>Description</title> 4341<para> 4342 Allow usb_wait_anchor_empty_timeout waiters to be woken up again, and 4343 wake up any current waiters if the anchor is empty. 4344</para> 4345</refsect1> 4346</refentry> 4347 4348<refentry id="API-usb-wait-anchor-empty-timeout"> 4349<refentryinfo> 4350 <title>LINUX</title> 4351 <productname>Kernel Hackers Manual</productname> 4352 <date>July 2017</date> 4353</refentryinfo> 4354<refmeta> 4355 <refentrytitle><phrase>usb_wait_anchor_empty_timeout</phrase></refentrytitle> 4356 <manvolnum>9</manvolnum> 4357 <refmiscinfo class="version">4.1.27</refmiscinfo> 4358</refmeta> 4359<refnamediv> 4360 <refname>usb_wait_anchor_empty_timeout</refname> 4361 <refpurpose> 4362 wait for an anchor to be unused 4363 </refpurpose> 4364</refnamediv> 4365<refsynopsisdiv> 4366 <title>Synopsis</title> 4367 <funcsynopsis><funcprototype> 4368 <funcdef>int <function>usb_wait_anchor_empty_timeout </function></funcdef> 4369 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4370 <paramdef>unsigned int <parameter>timeout</parameter></paramdef> 4371 </funcprototype></funcsynopsis> 4372</refsynopsisdiv> 4373<refsect1> 4374 <title>Arguments</title> 4375 <variablelist> 4376 <varlistentry> 4377 <term><parameter>anchor</parameter></term> 4378 <listitem> 4379 <para> 4380 the anchor you want to become unused 4381 </para> 4382 </listitem> 4383 </varlistentry> 4384 <varlistentry> 4385 <term><parameter>timeout</parameter></term> 4386 <listitem> 4387 <para> 4388 how long you are willing to wait in milliseconds 4389 </para> 4390 </listitem> 4391 </varlistentry> 4392 </variablelist> 4393</refsect1> 4394<refsect1> 4395<title>Description</title> 4396<para> 4397 Call this is you want to be sure all an anchor's 4398 URBs have finished 4399</para> 4400</refsect1> 4401<refsect1> 4402<title>Return</title> 4403<para> 4404 Non-zero if the anchor became unused. Zero on timeout. 4405</para> 4406</refsect1> 4407</refentry> 4408 4409<refentry id="API-usb-get-from-anchor"> 4410<refentryinfo> 4411 <title>LINUX</title> 4412 <productname>Kernel Hackers Manual</productname> 4413 <date>July 2017</date> 4414</refentryinfo> 4415<refmeta> 4416 <refentrytitle><phrase>usb_get_from_anchor</phrase></refentrytitle> 4417 <manvolnum>9</manvolnum> 4418 <refmiscinfo class="version">4.1.27</refmiscinfo> 4419</refmeta> 4420<refnamediv> 4421 <refname>usb_get_from_anchor</refname> 4422 <refpurpose> 4423 get an anchor's oldest urb 4424 </refpurpose> 4425</refnamediv> 4426<refsynopsisdiv> 4427 <title>Synopsis</title> 4428 <funcsynopsis><funcprototype> 4429 <funcdef>struct urb * <function>usb_get_from_anchor </function></funcdef> 4430 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4431 </funcprototype></funcsynopsis> 4432</refsynopsisdiv> 4433<refsect1> 4434 <title>Arguments</title> 4435 <variablelist> 4436 <varlistentry> 4437 <term><parameter>anchor</parameter></term> 4438 <listitem> 4439 <para> 4440 the anchor whose urb you want 4441 </para> 4442 </listitem> 4443 </varlistentry> 4444 </variablelist> 4445</refsect1> 4446<refsect1> 4447<title>Description</title> 4448<para> 4449 This will take the oldest urb from an anchor, 4450 unanchor and return it 4451</para> 4452</refsect1> 4453<refsect1> 4454<title>Return</title> 4455<para> 4456 The oldest urb from <parameter>anchor</parameter>, or <constant>NULL</constant> if <parameter>anchor</parameter> has no 4457 urbs associated with it. 4458</para> 4459</refsect1> 4460</refentry> 4461 4462<refentry id="API-usb-scuttle-anchored-urbs"> 4463<refentryinfo> 4464 <title>LINUX</title> 4465 <productname>Kernel Hackers Manual</productname> 4466 <date>July 2017</date> 4467</refentryinfo> 4468<refmeta> 4469 <refentrytitle><phrase>usb_scuttle_anchored_urbs</phrase></refentrytitle> 4470 <manvolnum>9</manvolnum> 4471 <refmiscinfo class="version">4.1.27</refmiscinfo> 4472</refmeta> 4473<refnamediv> 4474 <refname>usb_scuttle_anchored_urbs</refname> 4475 <refpurpose> 4476 unanchor all an anchor's urbs 4477 </refpurpose> 4478</refnamediv> 4479<refsynopsisdiv> 4480 <title>Synopsis</title> 4481 <funcsynopsis><funcprototype> 4482 <funcdef>void <function>usb_scuttle_anchored_urbs </function></funcdef> 4483 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4484 </funcprototype></funcsynopsis> 4485</refsynopsisdiv> 4486<refsect1> 4487 <title>Arguments</title> 4488 <variablelist> 4489 <varlistentry> 4490 <term><parameter>anchor</parameter></term> 4491 <listitem> 4492 <para> 4493 the anchor whose urbs you want to unanchor 4494 </para> 4495 </listitem> 4496 </varlistentry> 4497 </variablelist> 4498</refsect1> 4499<refsect1> 4500<title>Description</title> 4501<para> 4502 use this to get rid of all an anchor's urbs 4503</para> 4504</refsect1> 4505</refentry> 4506 4507<refentry id="API-usb-anchor-empty"> 4508<refentryinfo> 4509 <title>LINUX</title> 4510 <productname>Kernel Hackers Manual</productname> 4511 <date>July 2017</date> 4512</refentryinfo> 4513<refmeta> 4514 <refentrytitle><phrase>usb_anchor_empty</phrase></refentrytitle> 4515 <manvolnum>9</manvolnum> 4516 <refmiscinfo class="version">4.1.27</refmiscinfo> 4517</refmeta> 4518<refnamediv> 4519 <refname>usb_anchor_empty</refname> 4520 <refpurpose> 4521 is an anchor empty 4522 </refpurpose> 4523</refnamediv> 4524<refsynopsisdiv> 4525 <title>Synopsis</title> 4526 <funcsynopsis><funcprototype> 4527 <funcdef>int <function>usb_anchor_empty </function></funcdef> 4528 <paramdef>struct usb_anchor * <parameter>anchor</parameter></paramdef> 4529 </funcprototype></funcsynopsis> 4530</refsynopsisdiv> 4531<refsect1> 4532 <title>Arguments</title> 4533 <variablelist> 4534 <varlistentry> 4535 <term><parameter>anchor</parameter></term> 4536 <listitem> 4537 <para> 4538 the anchor you want to query 4539 </para> 4540 </listitem> 4541 </varlistentry> 4542 </variablelist> 4543</refsect1> 4544<refsect1> 4545<title>Return</title> 4546<para> 4547 1 if the anchor has no urbs associated with it. 4548</para> 4549</refsect1> 4550</refentry> 4551 4552<!-- drivers/usb/core/message.c --> 4553<refentry id="API-usb-control-msg"> 4554<refentryinfo> 4555 <title>LINUX</title> 4556 <productname>Kernel Hackers Manual</productname> 4557 <date>July 2017</date> 4558</refentryinfo> 4559<refmeta> 4560 <refentrytitle><phrase>usb_control_msg</phrase></refentrytitle> 4561 <manvolnum>9</manvolnum> 4562 <refmiscinfo class="version">4.1.27</refmiscinfo> 4563</refmeta> 4564<refnamediv> 4565 <refname>usb_control_msg</refname> 4566 <refpurpose> 4567 Builds a control urb, sends it off and waits for completion 4568 </refpurpose> 4569</refnamediv> 4570<refsynopsisdiv> 4571 <title>Synopsis</title> 4572 <funcsynopsis><funcprototype> 4573 <funcdef>int <function>usb_control_msg </function></funcdef> 4574 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 4575 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 4576 <paramdef>__u8 <parameter>request</parameter></paramdef> 4577 <paramdef>__u8 <parameter>requesttype</parameter></paramdef> 4578 <paramdef>__u16 <parameter>value</parameter></paramdef> 4579 <paramdef>__u16 <parameter>index</parameter></paramdef> 4580 <paramdef>void * <parameter>data</parameter></paramdef> 4581 <paramdef>__u16 <parameter>size</parameter></paramdef> 4582 <paramdef>int <parameter>timeout</parameter></paramdef> 4583 </funcprototype></funcsynopsis> 4584</refsynopsisdiv> 4585<refsect1> 4586 <title>Arguments</title> 4587 <variablelist> 4588 <varlistentry> 4589 <term><parameter>dev</parameter></term> 4590 <listitem> 4591 <para> 4592 pointer to the usb device to send the message to 4593 </para> 4594 </listitem> 4595 </varlistentry> 4596 <varlistentry> 4597 <term><parameter>pipe</parameter></term> 4598 <listitem> 4599 <para> 4600 endpoint <quote>pipe</quote> to send the message to 4601 </para> 4602 </listitem> 4603 </varlistentry> 4604 <varlistentry> 4605 <term><parameter>request</parameter></term> 4606 <listitem> 4607 <para> 4608 USB message request value 4609 </para> 4610 </listitem> 4611 </varlistentry> 4612 <varlistentry> 4613 <term><parameter>requesttype</parameter></term> 4614 <listitem> 4615 <para> 4616 USB message request type value 4617 </para> 4618 </listitem> 4619 </varlistentry> 4620 <varlistentry> 4621 <term><parameter>value</parameter></term> 4622 <listitem> 4623 <para> 4624 USB message value 4625 </para> 4626 </listitem> 4627 </varlistentry> 4628 <varlistentry> 4629 <term><parameter>index</parameter></term> 4630 <listitem> 4631 <para> 4632 USB message index value 4633 </para> 4634 </listitem> 4635 </varlistentry> 4636 <varlistentry> 4637 <term><parameter>data</parameter></term> 4638 <listitem> 4639 <para> 4640 pointer to the data to send 4641 </para> 4642 </listitem> 4643 </varlistentry> 4644 <varlistentry> 4645 <term><parameter>size</parameter></term> 4646 <listitem> 4647 <para> 4648 length in bytes of the data to send 4649 </para> 4650 </listitem> 4651 </varlistentry> 4652 <varlistentry> 4653 <term><parameter>timeout</parameter></term> 4654 <listitem> 4655 <para> 4656 time in msecs to wait for the message to complete before timing 4657 out (if 0 the wait is forever) 4658 </para> 4659 </listitem> 4660 </varlistentry> 4661 </variablelist> 4662</refsect1> 4663<refsect1> 4664<title>Context</title> 4665<para> 4666 !in_interrupt () 4667</para> 4668</refsect1> 4669<refsect1> 4670<title>Description</title> 4671<para> 4672 This function sends a simple control message to a specified endpoint and 4673 waits for the message to complete, or timeout. 4674 </para><para> 4675 4676 Don't use this function from within an interrupt context, like a bottom half 4677 handler. If you need an asynchronous message, or need to send a message 4678 from within interrupt context, use <function>usb_submit_urb</function>. 4679 If a thread in your driver uses this call, make sure your <function>disconnect</function> 4680 method can wait for it to complete. Since you don't have a handle on the 4681 URB used, you can't cancel the request. 4682</para> 4683</refsect1> 4684<refsect1> 4685<title>Return</title> 4686<para> 4687 If successful, the number of bytes transferred. Otherwise, a negative 4688 error number. 4689</para> 4690</refsect1> 4691</refentry> 4692 4693<refentry id="API-usb-interrupt-msg"> 4694<refentryinfo> 4695 <title>LINUX</title> 4696 <productname>Kernel Hackers Manual</productname> 4697 <date>July 2017</date> 4698</refentryinfo> 4699<refmeta> 4700 <refentrytitle><phrase>usb_interrupt_msg</phrase></refentrytitle> 4701 <manvolnum>9</manvolnum> 4702 <refmiscinfo class="version">4.1.27</refmiscinfo> 4703</refmeta> 4704<refnamediv> 4705 <refname>usb_interrupt_msg</refname> 4706 <refpurpose> 4707 Builds an interrupt urb, sends it off and waits for completion 4708 </refpurpose> 4709</refnamediv> 4710<refsynopsisdiv> 4711 <title>Synopsis</title> 4712 <funcsynopsis><funcprototype> 4713 <funcdef>int <function>usb_interrupt_msg </function></funcdef> 4714 <paramdef>struct usb_device * <parameter>usb_dev</parameter></paramdef> 4715 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 4716 <paramdef>void * <parameter>data</parameter></paramdef> 4717 <paramdef>int <parameter>len</parameter></paramdef> 4718 <paramdef>int * <parameter>actual_length</parameter></paramdef> 4719 <paramdef>int <parameter>timeout</parameter></paramdef> 4720 </funcprototype></funcsynopsis> 4721</refsynopsisdiv> 4722<refsect1> 4723 <title>Arguments</title> 4724 <variablelist> 4725 <varlistentry> 4726 <term><parameter>usb_dev</parameter></term> 4727 <listitem> 4728 <para> 4729 pointer to the usb device to send the message to 4730 </para> 4731 </listitem> 4732 </varlistentry> 4733 <varlistentry> 4734 <term><parameter>pipe</parameter></term> 4735 <listitem> 4736 <para> 4737 endpoint <quote>pipe</quote> to send the message to 4738 </para> 4739 </listitem> 4740 </varlistentry> 4741 <varlistentry> 4742 <term><parameter>data</parameter></term> 4743 <listitem> 4744 <para> 4745 pointer to the data to send 4746 </para> 4747 </listitem> 4748 </varlistentry> 4749 <varlistentry> 4750 <term><parameter>len</parameter></term> 4751 <listitem> 4752 <para> 4753 length in bytes of the data to send 4754 </para> 4755 </listitem> 4756 </varlistentry> 4757 <varlistentry> 4758 <term><parameter>actual_length</parameter></term> 4759 <listitem> 4760 <para> 4761 pointer to a location to put the actual length transferred 4762 in bytes 4763 </para> 4764 </listitem> 4765 </varlistentry> 4766 <varlistentry> 4767 <term><parameter>timeout</parameter></term> 4768 <listitem> 4769 <para> 4770 time in msecs to wait for the message to complete before 4771 timing out (if 0 the wait is forever) 4772 </para> 4773 </listitem> 4774 </varlistentry> 4775 </variablelist> 4776</refsect1> 4777<refsect1> 4778<title>Context</title> 4779<para> 4780 !in_interrupt () 4781</para> 4782</refsect1> 4783<refsect1> 4784<title>Description</title> 4785<para> 4786 This function sends a simple interrupt message to a specified endpoint and 4787 waits for the message to complete, or timeout. 4788 </para><para> 4789 4790 Don't use this function from within an interrupt context, like a bottom half 4791 handler. If you need an asynchronous message, or need to send a message 4792 from within interrupt context, use <function>usb_submit_urb</function> If a thread in your 4793 driver uses this call, make sure your <function>disconnect</function> method can wait for it to 4794 complete. Since you don't have a handle on the URB used, you can't cancel 4795 the request. 4796</para> 4797</refsect1> 4798<refsect1> 4799<title>Return</title> 4800<para> 4801 If successful, 0. Otherwise a negative error number. The number of actual 4802 bytes transferred will be stored in the <parameter>actual_length</parameter> parameter. 4803</para> 4804</refsect1> 4805</refentry> 4806 4807<refentry id="API-usb-bulk-msg"> 4808<refentryinfo> 4809 <title>LINUX</title> 4810 <productname>Kernel Hackers Manual</productname> 4811 <date>July 2017</date> 4812</refentryinfo> 4813<refmeta> 4814 <refentrytitle><phrase>usb_bulk_msg</phrase></refentrytitle> 4815 <manvolnum>9</manvolnum> 4816 <refmiscinfo class="version">4.1.27</refmiscinfo> 4817</refmeta> 4818<refnamediv> 4819 <refname>usb_bulk_msg</refname> 4820 <refpurpose> 4821 Builds a bulk urb, sends it off and waits for completion 4822 </refpurpose> 4823</refnamediv> 4824<refsynopsisdiv> 4825 <title>Synopsis</title> 4826 <funcsynopsis><funcprototype> 4827 <funcdef>int <function>usb_bulk_msg </function></funcdef> 4828 <paramdef>struct usb_device * <parameter>usb_dev</parameter></paramdef> 4829 <paramdef>unsigned int <parameter>pipe</parameter></paramdef> 4830 <paramdef>void * <parameter>data</parameter></paramdef> 4831 <paramdef>int <parameter>len</parameter></paramdef> 4832 <paramdef>int * <parameter>actual_length</parameter></paramdef> 4833 <paramdef>int <parameter>timeout</parameter></paramdef> 4834 </funcprototype></funcsynopsis> 4835</refsynopsisdiv> 4836<refsect1> 4837 <title>Arguments</title> 4838 <variablelist> 4839 <varlistentry> 4840 <term><parameter>usb_dev</parameter></term> 4841 <listitem> 4842 <para> 4843 pointer to the usb device to send the message to 4844 </para> 4845 </listitem> 4846 </varlistentry> 4847 <varlistentry> 4848 <term><parameter>pipe</parameter></term> 4849 <listitem> 4850 <para> 4851 endpoint <quote>pipe</quote> to send the message to 4852 </para> 4853 </listitem> 4854 </varlistentry> 4855 <varlistentry> 4856 <term><parameter>data</parameter></term> 4857 <listitem> 4858 <para> 4859 pointer to the data to send 4860 </para> 4861 </listitem> 4862 </varlistentry> 4863 <varlistentry> 4864 <term><parameter>len</parameter></term> 4865 <listitem> 4866 <para> 4867 length in bytes of the data to send 4868 </para> 4869 </listitem> 4870 </varlistentry> 4871 <varlistentry> 4872 <term><parameter>actual_length</parameter></term> 4873 <listitem> 4874 <para> 4875 pointer to a location to put the actual length transferred 4876 in bytes 4877 </para> 4878 </listitem> 4879 </varlistentry> 4880 <varlistentry> 4881 <term><parameter>timeout</parameter></term> 4882 <listitem> 4883 <para> 4884 time in msecs to wait for the message to complete before 4885 timing out (if 0 the wait is forever) 4886 </para> 4887 </listitem> 4888 </varlistentry> 4889 </variablelist> 4890</refsect1> 4891<refsect1> 4892<title>Context</title> 4893<para> 4894 !in_interrupt () 4895</para> 4896</refsect1> 4897<refsect1> 4898<title>Description</title> 4899<para> 4900 This function sends a simple bulk message to a specified endpoint 4901 and waits for the message to complete, or timeout. 4902 </para><para> 4903 4904 Don't use this function from within an interrupt context, like a bottom half 4905 handler. If you need an asynchronous message, or need to send a message 4906 from within interrupt context, use <function>usb_submit_urb</function> If a thread in your 4907 driver uses this call, make sure your <function>disconnect</function> method can wait for it to 4908 complete. Since you don't have a handle on the URB used, you can't cancel 4909 the request. 4910 </para><para> 4911 4912 Because there is no <function>usb_interrupt_msg</function> and no USBDEVFS_INTERRUPT ioctl, 4913 users are forced to abuse this routine by using it to submit URBs for 4914 interrupt endpoints. We will take the liberty of creating an interrupt URB 4915 (with the default interval) if the target is an interrupt endpoint. 4916</para> 4917</refsect1> 4918<refsect1> 4919<title>Return</title> 4920<para> 4921 If successful, 0. Otherwise a negative error number. The number of actual 4922 bytes transferred will be stored in the <parameter>actual_length</parameter> parameter. 4923</para> 4924</refsect1> 4925</refentry> 4926 4927<refentry id="API-usb-sg-init"> 4928<refentryinfo> 4929 <title>LINUX</title> 4930 <productname>Kernel Hackers Manual</productname> 4931 <date>July 2017</date> 4932</refentryinfo> 4933<refmeta> 4934 <refentrytitle><phrase>usb_sg_init</phrase></refentrytitle> 4935 <manvolnum>9</manvolnum> 4936 <refmiscinfo class="version">4.1.27</refmiscinfo> 4937</refmeta> 4938<refnamediv> 4939 <refname>usb_sg_init</refname> 4940 <refpurpose> 4941 initializes scatterlist-based bulk/interrupt I/O request 4942 </refpurpose> 4943</refnamediv> 4944<refsynopsisdiv> 4945 <title>Synopsis</title> 4946 <funcsynopsis><funcprototype> 4947 <funcdef>int <function>usb_sg_init </function></funcdef> 4948 <paramdef>struct usb_sg_request * <parameter>io</parameter></paramdef> 4949 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 4950 <paramdef>unsigned <parameter>pipe</parameter></paramdef> 4951 <paramdef>unsigned <parameter>period</parameter></paramdef> 4952 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 4953 <paramdef>int <parameter>nents</parameter></paramdef> 4954 <paramdef>size_t <parameter>length</parameter></paramdef> 4955 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 4956 </funcprototype></funcsynopsis> 4957</refsynopsisdiv> 4958<refsect1> 4959 <title>Arguments</title> 4960 <variablelist> 4961 <varlistentry> 4962 <term><parameter>io</parameter></term> 4963 <listitem> 4964 <para> 4965 request block being initialized. until <function>usb_sg_wait</function> returns, 4966 treat this as a pointer to an opaque block of memory, 4967 </para> 4968 </listitem> 4969 </varlistentry> 4970 <varlistentry> 4971 <term><parameter>dev</parameter></term> 4972 <listitem> 4973 <para> 4974 the usb device that will send or receive the data 4975 </para> 4976 </listitem> 4977 </varlistentry> 4978 <varlistentry> 4979 <term><parameter>pipe</parameter></term> 4980 <listitem> 4981 <para> 4982 endpoint <quote>pipe</quote> used to transfer the data 4983 </para> 4984 </listitem> 4985 </varlistentry> 4986 <varlistentry> 4987 <term><parameter>period</parameter></term> 4988 <listitem> 4989 <para> 4990 polling rate for interrupt endpoints, in frames or 4991 (for high speed endpoints) microframes; ignored for bulk 4992 </para> 4993 </listitem> 4994 </varlistentry> 4995 <varlistentry> 4996 <term><parameter>sg</parameter></term> 4997 <listitem> 4998 <para> 4999 scatterlist entries 5000 </para> 5001 </listitem> 5002 </varlistentry> 5003 <varlistentry> 5004 <term><parameter>nents</parameter></term> 5005 <listitem> 5006 <para> 5007 how many entries in the scatterlist 5008 </para> 5009 </listitem> 5010 </varlistentry> 5011 <varlistentry> 5012 <term><parameter>length</parameter></term> 5013 <listitem> 5014 <para> 5015 how many bytes to send from the scatterlist, or zero to 5016 send every byte identified in the list. 5017 </para> 5018 </listitem> 5019 </varlistentry> 5020 <varlistentry> 5021 <term><parameter>mem_flags</parameter></term> 5022 <listitem> 5023 <para> 5024 SLAB_* flags affecting memory allocations in this call 5025 </para> 5026 </listitem> 5027 </varlistentry> 5028 </variablelist> 5029</refsect1> 5030<refsect1> 5031<title>Description</title> 5032<para> 5033 This initializes a scatter/gather request, allocating resources such as 5034 I/O mappings and urb memory (except maybe memory used by USB controller 5035 drivers). 5036 </para><para> 5037 5038 The request must be issued using <function>usb_sg_wait</function>, which waits for the I/O to 5039 complete (or to be canceled) and then cleans up all resources allocated by 5040 <function>usb_sg_init</function>. 5041 </para><para> 5042 5043 The request may be canceled with <function>usb_sg_cancel</function>, either before or after 5044 <function>usb_sg_wait</function> is called. 5045</para> 5046</refsect1> 5047<refsect1> 5048<title>Return</title> 5049<para> 5050 Zero for success, else a negative errno value. 5051</para> 5052</refsect1> 5053</refentry> 5054 5055<refentry id="API-usb-sg-wait"> 5056<refentryinfo> 5057 <title>LINUX</title> 5058 <productname>Kernel Hackers Manual</productname> 5059 <date>July 2017</date> 5060</refentryinfo> 5061<refmeta> 5062 <refentrytitle><phrase>usb_sg_wait</phrase></refentrytitle> 5063 <manvolnum>9</manvolnum> 5064 <refmiscinfo class="version">4.1.27</refmiscinfo> 5065</refmeta> 5066<refnamediv> 5067 <refname>usb_sg_wait</refname> 5068 <refpurpose> 5069 synchronously execute scatter/gather request 5070 </refpurpose> 5071</refnamediv> 5072<refsynopsisdiv> 5073 <title>Synopsis</title> 5074 <funcsynopsis><funcprototype> 5075 <funcdef>void <function>usb_sg_wait </function></funcdef> 5076 <paramdef>struct usb_sg_request * <parameter>io</parameter></paramdef> 5077 </funcprototype></funcsynopsis> 5078</refsynopsisdiv> 5079<refsect1> 5080 <title>Arguments</title> 5081 <variablelist> 5082 <varlistentry> 5083 <term><parameter>io</parameter></term> 5084 <listitem> 5085 <para> 5086 request block handle, as initialized with <function>usb_sg_init</function>. 5087 some fields become accessible when this call returns. 5088 </para> 5089 </listitem> 5090 </varlistentry> 5091 </variablelist> 5092</refsect1> 5093<refsect1> 5094<title>Context</title> 5095<para> 5096 !in_interrupt () 5097</para> 5098</refsect1> 5099<refsect1> 5100<title>Description</title> 5101<para> 5102 This function blocks until the specified I/O operation completes. It 5103 leverages the grouping of the related I/O requests to get good transfer 5104 rates, by queueing the requests. At higher speeds, such queuing can 5105 significantly improve USB throughput. 5106 </para><para> 5107 5108 There are three kinds of completion for this function. 5109 (1) success, where io->status is zero. The number of io->bytes 5110 transferred is as requested. 5111 (2) error, where io->status is a negative errno value. The number 5112 of io->bytes transferred before the error is usually less 5113 than requested, and can be nonzero. 5114 (3) cancellation, a type of error with status -ECONNRESET that 5115 is initiated by <function>usb_sg_cancel</function>. 5116 </para><para> 5117 5118 When this function returns, all memory allocated through <function>usb_sg_init</function> or 5119 this call will have been freed. The request block parameter may still be 5120 passed to <function>usb_sg_cancel</function>, or it may be freed. It could also be 5121 reinitialized and then reused. 5122</para> 5123</refsect1> 5124<refsect1> 5125<title>Data Transfer Rates</title> 5126<para> 5127 </para><para> 5128 5129 Bulk transfers are valid for full or high speed endpoints. 5130 The best full speed data rate is 19 packets of 64 bytes each 5131 per frame, or 1216 bytes per millisecond. 5132 The best high speed data rate is 13 packets of 512 bytes each 5133 per microframe, or 52 KBytes per millisecond. 5134 </para><para> 5135 5136 The reason to use interrupt transfers through this API would most likely 5137 be to reserve high speed bandwidth, where up to 24 KBytes per millisecond 5138 could be transferred. That capability is less useful for low or full 5139 speed interrupt endpoints, which allow at most one packet per millisecond, 5140 of at most 8 or 64 bytes (respectively). 5141 </para><para> 5142 5143 It is not necessary to call this function to reserve bandwidth for devices 5144 under an xHCI host controller, as the bandwidth is reserved when the 5145 configuration or interface alt setting is selected. 5146</para> 5147</refsect1> 5148</refentry> 5149 5150<refentry id="API-usb-sg-cancel"> 5151<refentryinfo> 5152 <title>LINUX</title> 5153 <productname>Kernel Hackers Manual</productname> 5154 <date>July 2017</date> 5155</refentryinfo> 5156<refmeta> 5157 <refentrytitle><phrase>usb_sg_cancel</phrase></refentrytitle> 5158 <manvolnum>9</manvolnum> 5159 <refmiscinfo class="version">4.1.27</refmiscinfo> 5160</refmeta> 5161<refnamediv> 5162 <refname>usb_sg_cancel</refname> 5163 <refpurpose> 5164 stop scatter/gather i/o issued by <function>usb_sg_wait</function> 5165 </refpurpose> 5166</refnamediv> 5167<refsynopsisdiv> 5168 <title>Synopsis</title> 5169 <funcsynopsis><funcprototype> 5170 <funcdef>void <function>usb_sg_cancel </function></funcdef> 5171 <paramdef>struct usb_sg_request * <parameter>io</parameter></paramdef> 5172 </funcprototype></funcsynopsis> 5173</refsynopsisdiv> 5174<refsect1> 5175 <title>Arguments</title> 5176 <variablelist> 5177 <varlistentry> 5178 <term><parameter>io</parameter></term> 5179 <listitem> 5180 <para> 5181 request block, initialized with <function>usb_sg_init</function> 5182 </para> 5183 </listitem> 5184 </varlistentry> 5185 </variablelist> 5186</refsect1> 5187<refsect1> 5188<title>Description</title> 5189<para> 5190 This stops a request after it has been started by <function>usb_sg_wait</function>. 5191 It can also prevents one initialized by <function>usb_sg_init</function> from starting, 5192 so that call just frees resources allocated to the request. 5193</para> 5194</refsect1> 5195</refentry> 5196 5197<refentry id="API-usb-get-descriptor"> 5198<refentryinfo> 5199 <title>LINUX</title> 5200 <productname>Kernel Hackers Manual</productname> 5201 <date>July 2017</date> 5202</refentryinfo> 5203<refmeta> 5204 <refentrytitle><phrase>usb_get_descriptor</phrase></refentrytitle> 5205 <manvolnum>9</manvolnum> 5206 <refmiscinfo class="version">4.1.27</refmiscinfo> 5207</refmeta> 5208<refnamediv> 5209 <refname>usb_get_descriptor</refname> 5210 <refpurpose> 5211 issues a generic GET_DESCRIPTOR request 5212 </refpurpose> 5213</refnamediv> 5214<refsynopsisdiv> 5215 <title>Synopsis</title> 5216 <funcsynopsis><funcprototype> 5217 <funcdef>int <function>usb_get_descriptor </function></funcdef> 5218 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5219 <paramdef>unsigned char <parameter>type</parameter></paramdef> 5220 <paramdef>unsigned char <parameter>index</parameter></paramdef> 5221 <paramdef>void * <parameter>buf</parameter></paramdef> 5222 <paramdef>int <parameter>size</parameter></paramdef> 5223 </funcprototype></funcsynopsis> 5224</refsynopsisdiv> 5225<refsect1> 5226 <title>Arguments</title> 5227 <variablelist> 5228 <varlistentry> 5229 <term><parameter>dev</parameter></term> 5230 <listitem> 5231 <para> 5232 the device whose descriptor is being retrieved 5233 </para> 5234 </listitem> 5235 </varlistentry> 5236 <varlistentry> 5237 <term><parameter>type</parameter></term> 5238 <listitem> 5239 <para> 5240 the descriptor type (USB_DT_*) 5241 </para> 5242 </listitem> 5243 </varlistentry> 5244 <varlistentry> 5245 <term><parameter>index</parameter></term> 5246 <listitem> 5247 <para> 5248 the number of the descriptor 5249 </para> 5250 </listitem> 5251 </varlistentry> 5252 <varlistentry> 5253 <term><parameter>buf</parameter></term> 5254 <listitem> 5255 <para> 5256 where to put the descriptor 5257 </para> 5258 </listitem> 5259 </varlistentry> 5260 <varlistentry> 5261 <term><parameter>size</parameter></term> 5262 <listitem> 5263 <para> 5264 how big is <quote>buf</quote>? 5265 </para> 5266 </listitem> 5267 </varlistentry> 5268 </variablelist> 5269</refsect1> 5270<refsect1> 5271<title>Context</title> 5272<para> 5273 !in_interrupt () 5274</para> 5275</refsect1> 5276<refsect1> 5277<title>Description</title> 5278<para> 5279 Gets a USB descriptor. Convenience functions exist to simplify 5280 getting some types of descriptors. Use 5281 <function>usb_get_string</function> or <function>usb_string</function> for USB_DT_STRING. 5282 Device (USB_DT_DEVICE) and configuration descriptors (USB_DT_CONFIG) 5283 are part of the device structure. 5284 In addition to a number of USB-standard descriptors, some 5285 devices also use class-specific or vendor-specific descriptors. 5286 </para><para> 5287 5288 This call is synchronous, and may not be used in an interrupt context. 5289</para> 5290</refsect1> 5291<refsect1> 5292<title>Return</title> 5293<para> 5294 The number of bytes received on success, or else the status code 5295 returned by the underlying <function>usb_control_msg</function> call. 5296</para> 5297</refsect1> 5298</refentry> 5299 5300<refentry id="API-usb-string"> 5301<refentryinfo> 5302 <title>LINUX</title> 5303 <productname>Kernel Hackers Manual</productname> 5304 <date>July 2017</date> 5305</refentryinfo> 5306<refmeta> 5307 <refentrytitle><phrase>usb_string</phrase></refentrytitle> 5308 <manvolnum>9</manvolnum> 5309 <refmiscinfo class="version">4.1.27</refmiscinfo> 5310</refmeta> 5311<refnamediv> 5312 <refname>usb_string</refname> 5313 <refpurpose> 5314 returns UTF-8 version of a string descriptor 5315 </refpurpose> 5316</refnamediv> 5317<refsynopsisdiv> 5318 <title>Synopsis</title> 5319 <funcsynopsis><funcprototype> 5320 <funcdef>int <function>usb_string </function></funcdef> 5321 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5322 <paramdef>int <parameter>index</parameter></paramdef> 5323 <paramdef>char * <parameter>buf</parameter></paramdef> 5324 <paramdef>size_t <parameter>size</parameter></paramdef> 5325 </funcprototype></funcsynopsis> 5326</refsynopsisdiv> 5327<refsect1> 5328 <title>Arguments</title> 5329 <variablelist> 5330 <varlistentry> 5331 <term><parameter>dev</parameter></term> 5332 <listitem> 5333 <para> 5334 the device whose string descriptor is being retrieved 5335 </para> 5336 </listitem> 5337 </varlistentry> 5338 <varlistentry> 5339 <term><parameter>index</parameter></term> 5340 <listitem> 5341 <para> 5342 the number of the descriptor 5343 </para> 5344 </listitem> 5345 </varlistentry> 5346 <varlistentry> 5347 <term><parameter>buf</parameter></term> 5348 <listitem> 5349 <para> 5350 where to put the string 5351 </para> 5352 </listitem> 5353 </varlistentry> 5354 <varlistentry> 5355 <term><parameter>size</parameter></term> 5356 <listitem> 5357 <para> 5358 how big is <quote>buf</quote>? 5359 </para> 5360 </listitem> 5361 </varlistentry> 5362 </variablelist> 5363</refsect1> 5364<refsect1> 5365<title>Context</title> 5366<para> 5367 !in_interrupt () 5368</para> 5369</refsect1> 5370<refsect1> 5371<title>Description</title> 5372<para> 5373 This converts the UTF-16LE encoded strings returned by devices, from 5374 <function>usb_get_string_descriptor</function>, to null-terminated UTF-8 encoded ones 5375 that are more usable in most kernel contexts. Note that this function 5376 chooses strings in the first language supported by the device. 5377 </para><para> 5378 5379 This call is synchronous, and may not be used in an interrupt context. 5380</para> 5381</refsect1> 5382<refsect1> 5383<title>Return</title> 5384<para> 5385 length of the string (>= 0) or usb_control_msg status (< 0). 5386</para> 5387</refsect1> 5388</refentry> 5389 5390<refentry id="API-usb-get-status"> 5391<refentryinfo> 5392 <title>LINUX</title> 5393 <productname>Kernel Hackers Manual</productname> 5394 <date>July 2017</date> 5395</refentryinfo> 5396<refmeta> 5397 <refentrytitle><phrase>usb_get_status</phrase></refentrytitle> 5398 <manvolnum>9</manvolnum> 5399 <refmiscinfo class="version">4.1.27</refmiscinfo> 5400</refmeta> 5401<refnamediv> 5402 <refname>usb_get_status</refname> 5403 <refpurpose> 5404 issues a GET_STATUS call 5405 </refpurpose> 5406</refnamediv> 5407<refsynopsisdiv> 5408 <title>Synopsis</title> 5409 <funcsynopsis><funcprototype> 5410 <funcdef>int <function>usb_get_status </function></funcdef> 5411 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5412 <paramdef>int <parameter>type</parameter></paramdef> 5413 <paramdef>int <parameter>target</parameter></paramdef> 5414 <paramdef>void * <parameter>data</parameter></paramdef> 5415 </funcprototype></funcsynopsis> 5416</refsynopsisdiv> 5417<refsect1> 5418 <title>Arguments</title> 5419 <variablelist> 5420 <varlistentry> 5421 <term><parameter>dev</parameter></term> 5422 <listitem> 5423 <para> 5424 the device whose status is being checked 5425 </para> 5426 </listitem> 5427 </varlistentry> 5428 <varlistentry> 5429 <term><parameter>type</parameter></term> 5430 <listitem> 5431 <para> 5432 USB_RECIP_*; for device, interface, or endpoint 5433 </para> 5434 </listitem> 5435 </varlistentry> 5436 <varlistentry> 5437 <term><parameter>target</parameter></term> 5438 <listitem> 5439 <para> 5440 zero (for device), else interface or endpoint number 5441 </para> 5442 </listitem> 5443 </varlistentry> 5444 <varlistentry> 5445 <term><parameter>data</parameter></term> 5446 <listitem> 5447 <para> 5448 pointer to two bytes of bitmap data 5449 </para> 5450 </listitem> 5451 </varlistentry> 5452 </variablelist> 5453</refsect1> 5454<refsect1> 5455<title>Context</title> 5456<para> 5457 !in_interrupt () 5458</para> 5459</refsect1> 5460<refsect1> 5461<title>Description</title> 5462<para> 5463 Returns device, interface, or endpoint status. Normally only of 5464 interest to see if the device is self powered, or has enabled the 5465 remote wakeup facility; or whether a bulk or interrupt endpoint 5466 is halted (<quote>stalled</quote>). 5467 </para><para> 5468 5469 Bits in these status bitmaps are set using the SET_FEATURE request, 5470 and cleared using the CLEAR_FEATURE request. The <function>usb_clear_halt</function> 5471 function should be used to clear halt (<quote>stall</quote>) status. 5472 </para><para> 5473 5474 This call is synchronous, and may not be used in an interrupt context. 5475 </para><para> 5476 5477 Returns 0 and the status value in *<parameter>data</parameter> (in host byte order) on success, 5478 or else the status code from the underlying <function>usb_control_msg</function> call. 5479</para> 5480</refsect1> 5481</refentry> 5482 5483<refentry id="API-usb-clear-halt"> 5484<refentryinfo> 5485 <title>LINUX</title> 5486 <productname>Kernel Hackers Manual</productname> 5487 <date>July 2017</date> 5488</refentryinfo> 5489<refmeta> 5490 <refentrytitle><phrase>usb_clear_halt</phrase></refentrytitle> 5491 <manvolnum>9</manvolnum> 5492 <refmiscinfo class="version">4.1.27</refmiscinfo> 5493</refmeta> 5494<refnamediv> 5495 <refname>usb_clear_halt</refname> 5496 <refpurpose> 5497 tells device to clear endpoint halt/stall condition 5498 </refpurpose> 5499</refnamediv> 5500<refsynopsisdiv> 5501 <title>Synopsis</title> 5502 <funcsynopsis><funcprototype> 5503 <funcdef>int <function>usb_clear_halt </function></funcdef> 5504 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5505 <paramdef>int <parameter>pipe</parameter></paramdef> 5506 </funcprototype></funcsynopsis> 5507</refsynopsisdiv> 5508<refsect1> 5509 <title>Arguments</title> 5510 <variablelist> 5511 <varlistentry> 5512 <term><parameter>dev</parameter></term> 5513 <listitem> 5514 <para> 5515 device whose endpoint is halted 5516 </para> 5517 </listitem> 5518 </varlistentry> 5519 <varlistentry> 5520 <term><parameter>pipe</parameter></term> 5521 <listitem> 5522 <para> 5523 endpoint <quote>pipe</quote> being cleared 5524 </para> 5525 </listitem> 5526 </varlistentry> 5527 </variablelist> 5528</refsect1> 5529<refsect1> 5530<title>Context</title> 5531<para> 5532 !in_interrupt () 5533</para> 5534</refsect1> 5535<refsect1> 5536<title>Description</title> 5537<para> 5538 This is used to clear halt conditions for bulk and interrupt endpoints, 5539 as reported by URB completion status. Endpoints that are halted are 5540 sometimes referred to as being <quote>stalled</quote>. Such endpoints are unable 5541 to transmit or receive data until the halt status is cleared. Any URBs 5542 queued for such an endpoint should normally be unlinked by the driver 5543 before clearing the halt condition, as described in sections 5.7.5 5544 and 5.8.5 of the USB 2.0 spec. 5545 </para><para> 5546 5547 Note that control and isochronous endpoints don't halt, although control 5548 endpoints report <quote>protocol stall</quote> (for unsupported requests) using the 5549 same status code used to report a true stall. 5550 </para><para> 5551 5552 This call is synchronous, and may not be used in an interrupt context. 5553</para> 5554</refsect1> 5555<refsect1> 5556<title>Return</title> 5557<para> 5558 Zero on success, or else the status code returned by the 5559 underlying <function>usb_control_msg</function> call. 5560</para> 5561</refsect1> 5562</refentry> 5563 5564<refentry id="API-usb-reset-endpoint"> 5565<refentryinfo> 5566 <title>LINUX</title> 5567 <productname>Kernel Hackers Manual</productname> 5568 <date>July 2017</date> 5569</refentryinfo> 5570<refmeta> 5571 <refentrytitle><phrase>usb_reset_endpoint</phrase></refentrytitle> 5572 <manvolnum>9</manvolnum> 5573 <refmiscinfo class="version">4.1.27</refmiscinfo> 5574</refmeta> 5575<refnamediv> 5576 <refname>usb_reset_endpoint</refname> 5577 <refpurpose> 5578 Reset an endpoint's state. 5579 </refpurpose> 5580</refnamediv> 5581<refsynopsisdiv> 5582 <title>Synopsis</title> 5583 <funcsynopsis><funcprototype> 5584 <funcdef>void <function>usb_reset_endpoint </function></funcdef> 5585 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5586 <paramdef>unsigned int <parameter>epaddr</parameter></paramdef> 5587 </funcprototype></funcsynopsis> 5588</refsynopsisdiv> 5589<refsect1> 5590 <title>Arguments</title> 5591 <variablelist> 5592 <varlistentry> 5593 <term><parameter>dev</parameter></term> 5594 <listitem> 5595 <para> 5596 the device whose endpoint is to be reset 5597 </para> 5598 </listitem> 5599 </varlistentry> 5600 <varlistentry> 5601 <term><parameter>epaddr</parameter></term> 5602 <listitem> 5603 <para> 5604 the endpoint's address. Endpoint number for output, 5605 endpoint number + USB_DIR_IN for input 5606 </para> 5607 </listitem> 5608 </varlistentry> 5609 </variablelist> 5610</refsect1> 5611<refsect1> 5612<title>Description</title> 5613<para> 5614 Resets any host-side endpoint state such as the toggle bit, 5615 sequence number or current window. 5616</para> 5617</refsect1> 5618</refentry> 5619 5620<refentry id="API-usb-set-interface"> 5621<refentryinfo> 5622 <title>LINUX</title> 5623 <productname>Kernel Hackers Manual</productname> 5624 <date>July 2017</date> 5625</refentryinfo> 5626<refmeta> 5627 <refentrytitle><phrase>usb_set_interface</phrase></refentrytitle> 5628 <manvolnum>9</manvolnum> 5629 <refmiscinfo class="version">4.1.27</refmiscinfo> 5630</refmeta> 5631<refnamediv> 5632 <refname>usb_set_interface</refname> 5633 <refpurpose> 5634 Makes a particular alternate setting be current 5635 </refpurpose> 5636</refnamediv> 5637<refsynopsisdiv> 5638 <title>Synopsis</title> 5639 <funcsynopsis><funcprototype> 5640 <funcdef>int <function>usb_set_interface </function></funcdef> 5641 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5642 <paramdef>int <parameter>interface</parameter></paramdef> 5643 <paramdef>int <parameter>alternate</parameter></paramdef> 5644 </funcprototype></funcsynopsis> 5645</refsynopsisdiv> 5646<refsect1> 5647 <title>Arguments</title> 5648 <variablelist> 5649 <varlistentry> 5650 <term><parameter>dev</parameter></term> 5651 <listitem> 5652 <para> 5653 the device whose interface is being updated 5654 </para> 5655 </listitem> 5656 </varlistentry> 5657 <varlistentry> 5658 <term><parameter>interface</parameter></term> 5659 <listitem> 5660 <para> 5661 the interface being updated 5662 </para> 5663 </listitem> 5664 </varlistentry> 5665 <varlistentry> 5666 <term><parameter>alternate</parameter></term> 5667 <listitem> 5668 <para> 5669 the setting being chosen. 5670 </para> 5671 </listitem> 5672 </varlistentry> 5673 </variablelist> 5674</refsect1> 5675<refsect1> 5676<title>Context</title> 5677<para> 5678 !in_interrupt () 5679</para> 5680</refsect1> 5681<refsect1> 5682<title>Description</title> 5683<para> 5684 This is used to enable data transfers on interfaces that may not 5685 be enabled by default. Not all devices support such configurability. 5686 Only the driver bound to an interface may change its setting. 5687 </para><para> 5688 5689 Within any given configuration, each interface may have several 5690 alternative settings. These are often used to control levels of 5691 bandwidth consumption. For example, the default setting for a high 5692 speed interrupt endpoint may not send more than 64 bytes per microframe, 5693 while interrupt transfers of up to 3KBytes per microframe are legal. 5694 Also, isochronous endpoints may never be part of an 5695 interface's default setting. To access such bandwidth, alternate 5696 interface settings must be made current. 5697 </para><para> 5698 5699 Note that in the Linux USB subsystem, bandwidth associated with 5700 an endpoint in a given alternate setting is not reserved until an URB 5701 is submitted that needs that bandwidth. Some other operating systems 5702 allocate bandwidth early, when a configuration is chosen. 5703 </para><para> 5704 5705 This call is synchronous, and may not be used in an interrupt context. 5706 Also, drivers must not change altsettings while urbs are scheduled for 5707 endpoints in that interface; all such urbs must first be completed 5708 (perhaps forced by unlinking). 5709</para> 5710</refsect1> 5711<refsect1> 5712<title>Return</title> 5713<para> 5714 Zero on success, or else the status code returned by the 5715 underlying <function>usb_control_msg</function> call. 5716</para> 5717</refsect1> 5718</refentry> 5719 5720<refentry id="API-usb-reset-configuration"> 5721<refentryinfo> 5722 <title>LINUX</title> 5723 <productname>Kernel Hackers Manual</productname> 5724 <date>July 2017</date> 5725</refentryinfo> 5726<refmeta> 5727 <refentrytitle><phrase>usb_reset_configuration</phrase></refentrytitle> 5728 <manvolnum>9</manvolnum> 5729 <refmiscinfo class="version">4.1.27</refmiscinfo> 5730</refmeta> 5731<refnamediv> 5732 <refname>usb_reset_configuration</refname> 5733 <refpurpose> 5734 lightweight device reset 5735 </refpurpose> 5736</refnamediv> 5737<refsynopsisdiv> 5738 <title>Synopsis</title> 5739 <funcsynopsis><funcprototype> 5740 <funcdef>int <function>usb_reset_configuration </function></funcdef> 5741 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 5742 </funcprototype></funcsynopsis> 5743</refsynopsisdiv> 5744<refsect1> 5745 <title>Arguments</title> 5746 <variablelist> 5747 <varlistentry> 5748 <term><parameter>dev</parameter></term> 5749 <listitem> 5750 <para> 5751 the device whose configuration is being reset 5752 </para> 5753 </listitem> 5754 </varlistentry> 5755 </variablelist> 5756</refsect1> 5757<refsect1> 5758<title>Description</title> 5759<para> 5760 This issues a standard SET_CONFIGURATION request to the device using 5761 the current configuration. The effect is to reset most USB-related 5762 state in the device, including interface altsettings (reset to zero), 5763 endpoint halts (cleared), and endpoint state (only for bulk and interrupt 5764 endpoints). Other usbcore state is unchanged, including bindings of 5765 usb device drivers to interfaces. 5766 </para><para> 5767 5768 Because this affects multiple interfaces, avoid using this with composite 5769 (multi-interface) devices. Instead, the driver for each interface may 5770 use <function>usb_set_interface</function> on the interfaces it claims. Be careful though; 5771 some devices don't support the SET_INTERFACE request, and others won't 5772 reset all the interface state (notably endpoint state). Resetting the whole 5773 configuration would affect other drivers' interfaces. 5774 </para><para> 5775 5776 The caller must own the device lock. 5777</para> 5778</refsect1> 5779<refsect1> 5780<title>Return</title> 5781<para> 5782 Zero on success, else a negative error code. 5783</para> 5784</refsect1> 5785</refentry> 5786 5787<refentry id="API-usb-driver-set-configuration"> 5788<refentryinfo> 5789 <title>LINUX</title> 5790 <productname>Kernel Hackers Manual</productname> 5791 <date>July 2017</date> 5792</refentryinfo> 5793<refmeta> 5794 <refentrytitle><phrase>usb_driver_set_configuration</phrase></refentrytitle> 5795 <manvolnum>9</manvolnum> 5796 <refmiscinfo class="version">4.1.27</refmiscinfo> 5797</refmeta> 5798<refnamediv> 5799 <refname>usb_driver_set_configuration</refname> 5800 <refpurpose> 5801 Provide a way for drivers to change device configurations 5802 </refpurpose> 5803</refnamediv> 5804<refsynopsisdiv> 5805 <title>Synopsis</title> 5806 <funcsynopsis><funcprototype> 5807 <funcdef>int <function>usb_driver_set_configuration </function></funcdef> 5808 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 5809 <paramdef>int <parameter>config</parameter></paramdef> 5810 </funcprototype></funcsynopsis> 5811</refsynopsisdiv> 5812<refsect1> 5813 <title>Arguments</title> 5814 <variablelist> 5815 <varlistentry> 5816 <term><parameter>udev</parameter></term> 5817 <listitem> 5818 <para> 5819 the device whose configuration is being updated 5820 </para> 5821 </listitem> 5822 </varlistentry> 5823 <varlistentry> 5824 <term><parameter>config</parameter></term> 5825 <listitem> 5826 <para> 5827 the configuration being chosen. 5828 </para> 5829 </listitem> 5830 </varlistentry> 5831 </variablelist> 5832</refsect1> 5833<refsect1> 5834<title>Context</title> 5835<para> 5836 In process context, must be able to sleep 5837</para> 5838</refsect1> 5839<refsect1> 5840<title>Description</title> 5841<para> 5842 Device interface drivers are not allowed to change device configurations. 5843 This is because changing configurations will destroy the interface the 5844 driver is bound to and create new ones; it would be like a floppy-disk 5845 driver telling the computer to replace the floppy-disk drive with a 5846 tape drive! 5847 </para><para> 5848 5849 Still, in certain specialized circumstances the need may arise. This 5850 routine gets around the normal restrictions by using a work thread to 5851 submit the change-config request. 5852</para> 5853</refsect1> 5854<refsect1> 5855<title>Return</title> 5856<para> 5857 0 if the request was successfully queued, error code otherwise. 5858 The caller has no way to know whether the queued request will eventually 5859 succeed. 5860</para> 5861</refsect1> 5862</refentry> 5863 5864<!-- drivers/usb/core/file.c --> 5865<refentry id="API-usb-register-dev"> 5866<refentryinfo> 5867 <title>LINUX</title> 5868 <productname>Kernel Hackers Manual</productname> 5869 <date>July 2017</date> 5870</refentryinfo> 5871<refmeta> 5872 <refentrytitle><phrase>usb_register_dev</phrase></refentrytitle> 5873 <manvolnum>9</manvolnum> 5874 <refmiscinfo class="version">4.1.27</refmiscinfo> 5875</refmeta> 5876<refnamediv> 5877 <refname>usb_register_dev</refname> 5878 <refpurpose> 5879 register a USB device, and ask for a minor number 5880 </refpurpose> 5881</refnamediv> 5882<refsynopsisdiv> 5883 <title>Synopsis</title> 5884 <funcsynopsis><funcprototype> 5885 <funcdef>int <function>usb_register_dev </function></funcdef> 5886 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 5887 <paramdef>struct usb_class_driver * <parameter>class_driver</parameter></paramdef> 5888 </funcprototype></funcsynopsis> 5889</refsynopsisdiv> 5890<refsect1> 5891 <title>Arguments</title> 5892 <variablelist> 5893 <varlistentry> 5894 <term><parameter>intf</parameter></term> 5895 <listitem> 5896 <para> 5897 pointer to the usb_interface that is being registered 5898 </para> 5899 </listitem> 5900 </varlistentry> 5901 <varlistentry> 5902 <term><parameter>class_driver</parameter></term> 5903 <listitem> 5904 <para> 5905 pointer to the usb_class_driver for this device 5906 </para> 5907 </listitem> 5908 </varlistentry> 5909 </variablelist> 5910</refsect1> 5911<refsect1> 5912<title>Description</title> 5913<para> 5914 This should be called by all USB drivers that use the USB major number. 5915 If CONFIG_USB_DYNAMIC_MINORS is enabled, the minor number will be 5916 dynamically allocated out of the list of available ones. If it is not 5917 enabled, the minor number will be based on the next available free minor, 5918 starting at the class_driver->minor_base. 5919 </para><para> 5920 5921 This function also creates a usb class device in the sysfs tree. 5922 </para><para> 5923 5924 <function>usb_deregister_dev</function> must be called when the driver is done with 5925 the minor numbers given out by this function. 5926</para> 5927</refsect1> 5928<refsect1> 5929<title>Return</title> 5930<para> 5931 -EINVAL if something bad happens with trying to register a 5932 device, and 0 on success. 5933</para> 5934</refsect1> 5935</refentry> 5936 5937<refentry id="API-usb-deregister-dev"> 5938<refentryinfo> 5939 <title>LINUX</title> 5940 <productname>Kernel Hackers Manual</productname> 5941 <date>July 2017</date> 5942</refentryinfo> 5943<refmeta> 5944 <refentrytitle><phrase>usb_deregister_dev</phrase></refentrytitle> 5945 <manvolnum>9</manvolnum> 5946 <refmiscinfo class="version">4.1.27</refmiscinfo> 5947</refmeta> 5948<refnamediv> 5949 <refname>usb_deregister_dev</refname> 5950 <refpurpose> 5951 deregister a USB device's dynamic minor. 5952 </refpurpose> 5953</refnamediv> 5954<refsynopsisdiv> 5955 <title>Synopsis</title> 5956 <funcsynopsis><funcprototype> 5957 <funcdef>void <function>usb_deregister_dev </function></funcdef> 5958 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 5959 <paramdef>struct usb_class_driver * <parameter>class_driver</parameter></paramdef> 5960 </funcprototype></funcsynopsis> 5961</refsynopsisdiv> 5962<refsect1> 5963 <title>Arguments</title> 5964 <variablelist> 5965 <varlistentry> 5966 <term><parameter>intf</parameter></term> 5967 <listitem> 5968 <para> 5969 pointer to the usb_interface that is being deregistered 5970 </para> 5971 </listitem> 5972 </varlistentry> 5973 <varlistentry> 5974 <term><parameter>class_driver</parameter></term> 5975 <listitem> 5976 <para> 5977 pointer to the usb_class_driver for this device 5978 </para> 5979 </listitem> 5980 </varlistentry> 5981 </variablelist> 5982</refsect1> 5983<refsect1> 5984<title>Description</title> 5985<para> 5986 Used in conjunction with <function>usb_register_dev</function>. This function is called 5987 when the USB driver is finished with the minor numbers gotten from a 5988 call to <function>usb_register_dev</function> (usually when the device is disconnected 5989 from the system.) 5990 </para><para> 5991 5992 This function also removes the usb class device from the sysfs tree. 5993 </para><para> 5994 5995 This should be called by all drivers that use the USB major number. 5996</para> 5997</refsect1> 5998</refentry> 5999 6000<!-- drivers/usb/core/driver.c --> 6001<refentry id="API-usb-driver-claim-interface"> 6002<refentryinfo> 6003 <title>LINUX</title> 6004 <productname>Kernel Hackers Manual</productname> 6005 <date>July 2017</date> 6006</refentryinfo> 6007<refmeta> 6008 <refentrytitle><phrase>usb_driver_claim_interface</phrase></refentrytitle> 6009 <manvolnum>9</manvolnum> 6010 <refmiscinfo class="version">4.1.27</refmiscinfo> 6011</refmeta> 6012<refnamediv> 6013 <refname>usb_driver_claim_interface</refname> 6014 <refpurpose> 6015 bind a driver to an interface 6016 </refpurpose> 6017</refnamediv> 6018<refsynopsisdiv> 6019 <title>Synopsis</title> 6020 <funcsynopsis><funcprototype> 6021 <funcdef>int <function>usb_driver_claim_interface </function></funcdef> 6022 <paramdef>struct usb_driver * <parameter>driver</parameter></paramdef> 6023 <paramdef>struct usb_interface * <parameter>iface</parameter></paramdef> 6024 <paramdef>void * <parameter>priv</parameter></paramdef> 6025 </funcprototype></funcsynopsis> 6026</refsynopsisdiv> 6027<refsect1> 6028 <title>Arguments</title> 6029 <variablelist> 6030 <varlistentry> 6031 <term><parameter>driver</parameter></term> 6032 <listitem> 6033 <para> 6034 the driver to be bound 6035 </para> 6036 </listitem> 6037 </varlistentry> 6038 <varlistentry> 6039 <term><parameter>iface</parameter></term> 6040 <listitem> 6041 <para> 6042 the interface to which it will be bound; must be in the 6043 usb device's active configuration 6044 </para> 6045 </listitem> 6046 </varlistentry> 6047 <varlistentry> 6048 <term><parameter>priv</parameter></term> 6049 <listitem> 6050 <para> 6051 driver data associated with that interface 6052 </para> 6053 </listitem> 6054 </varlistentry> 6055 </variablelist> 6056</refsect1> 6057<refsect1> 6058<title>Description</title> 6059<para> 6060 This is used by usb device drivers that need to claim more than one 6061 interface on a device when probing (audio and acm are current examples). 6062 No device driver should directly modify internal usb_interface or 6063 usb_device structure members. 6064 </para><para> 6065 6066 Few drivers should need to use this routine, since the most natural 6067 way to bind to an interface is to return the private data from 6068 the driver's <function>probe</function> method. 6069 </para><para> 6070 6071 Callers must own the device lock, so driver <function>probe</function> entries don't need 6072 extra locking, but other call contexts may need to explicitly claim that 6073 lock. 6074</para> 6075</refsect1> 6076<refsect1> 6077<title>Return</title> 6078<para> 6079 0 on success. 6080</para> 6081</refsect1> 6082</refentry> 6083 6084<refentry id="API-usb-driver-release-interface"> 6085<refentryinfo> 6086 <title>LINUX</title> 6087 <productname>Kernel Hackers Manual</productname> 6088 <date>July 2017</date> 6089</refentryinfo> 6090<refmeta> 6091 <refentrytitle><phrase>usb_driver_release_interface</phrase></refentrytitle> 6092 <manvolnum>9</manvolnum> 6093 <refmiscinfo class="version">4.1.27</refmiscinfo> 6094</refmeta> 6095<refnamediv> 6096 <refname>usb_driver_release_interface</refname> 6097 <refpurpose> 6098 unbind a driver from an interface 6099 </refpurpose> 6100</refnamediv> 6101<refsynopsisdiv> 6102 <title>Synopsis</title> 6103 <funcsynopsis><funcprototype> 6104 <funcdef>void <function>usb_driver_release_interface </function></funcdef> 6105 <paramdef>struct usb_driver * <parameter>driver</parameter></paramdef> 6106 <paramdef>struct usb_interface * <parameter>iface</parameter></paramdef> 6107 </funcprototype></funcsynopsis> 6108</refsynopsisdiv> 6109<refsect1> 6110 <title>Arguments</title> 6111 <variablelist> 6112 <varlistentry> 6113 <term><parameter>driver</parameter></term> 6114 <listitem> 6115 <para> 6116 the driver to be unbound 6117 </para> 6118 </listitem> 6119 </varlistentry> 6120 <varlistentry> 6121 <term><parameter>iface</parameter></term> 6122 <listitem> 6123 <para> 6124 the interface from which it will be unbound 6125 </para> 6126 </listitem> 6127 </varlistentry> 6128 </variablelist> 6129</refsect1> 6130<refsect1> 6131<title>Description</title> 6132<para> 6133 This can be used by drivers to release an interface without waiting 6134 for their <function>disconnect</function> methods to be called. In typical cases this 6135 also causes the driver <function>disconnect</function> method to be called. 6136 </para><para> 6137 6138 This call is synchronous, and may not be used in an interrupt context. 6139 Callers must own the device lock, so driver <function>disconnect</function> entries don't 6140 need extra locking, but other call contexts may need to explicitly claim 6141 that lock. 6142</para> 6143</refsect1> 6144</refentry> 6145 6146<refentry id="API-usb-match-id"> 6147<refentryinfo> 6148 <title>LINUX</title> 6149 <productname>Kernel Hackers Manual</productname> 6150 <date>July 2017</date> 6151</refentryinfo> 6152<refmeta> 6153 <refentrytitle><phrase>usb_match_id</phrase></refentrytitle> 6154 <manvolnum>9</manvolnum> 6155 <refmiscinfo class="version">4.1.27</refmiscinfo> 6156</refmeta> 6157<refnamediv> 6158 <refname>usb_match_id</refname> 6159 <refpurpose> 6160 find first usb_device_id matching device or interface 6161 </refpurpose> 6162</refnamediv> 6163<refsynopsisdiv> 6164 <title>Synopsis</title> 6165 <funcsynopsis><funcprototype> 6166 <funcdef>const struct usb_device_id * <function>usb_match_id </function></funcdef> 6167 <paramdef>struct usb_interface * <parameter>interface</parameter></paramdef> 6168 <paramdef>const struct usb_device_id * <parameter>id</parameter></paramdef> 6169 </funcprototype></funcsynopsis> 6170</refsynopsisdiv> 6171<refsect1> 6172 <title>Arguments</title> 6173 <variablelist> 6174 <varlistentry> 6175 <term><parameter>interface</parameter></term> 6176 <listitem> 6177 <para> 6178 the interface of interest 6179 </para> 6180 </listitem> 6181 </varlistentry> 6182 <varlistentry> 6183 <term><parameter>id</parameter></term> 6184 <listitem> 6185 <para> 6186 array of usb_device_id structures, terminated by zero entry 6187 </para> 6188 </listitem> 6189 </varlistentry> 6190 </variablelist> 6191</refsect1> 6192<refsect1> 6193<title>Description</title> 6194<para> 6195 usb_match_id searches an array of usb_device_id's and returns 6196 the first one matching the device or interface, or null. 6197 This is used when binding (or rebinding) a driver to an interface. 6198 Most USB device drivers will use this indirectly, through the usb core, 6199 but some layered driver frameworks use it directly. 6200 These device tables are exported with MODULE_DEVICE_TABLE, through 6201 modutils, to support the driver loading functionality of USB hotplugging. 6202</para> 6203</refsect1> 6204<refsect1> 6205<title>Return</title> 6206<para> 6207 The first matching usb_device_id, or <constant>NULL</constant>. 6208</para> 6209</refsect1> 6210<refsect1> 6211<title>What Matches</title> 6212<para> 6213 </para><para> 6214 6215 The <quote>match_flags</quote> element in a usb_device_id controls which 6216 members are used. If the corresponding bit is set, the 6217 value in the device_id must match its corresponding member 6218 in the device or interface descriptor, or else the device_id 6219 does not match. 6220 </para><para> 6221 6222 <quote>driver_info</quote> is normally used only by device drivers, 6223 but you can create a wildcard <quote>matches anything</quote> usb_device_id 6224 as a driver's <quote>modules.usbmap</quote> entry if you provide an id with 6225 only a nonzero <quote>driver_info</quote> field. If you do this, the USB device 6226 driver's <function>probe</function> routine should use additional intelligence to 6227 decide whether to bind to the specified interface. 6228</para> 6229</refsect1> 6230<refsect1> 6231<title>What Makes Good usb_device_id Tables</title> 6232<para> 6233 </para><para> 6234 6235 The match algorithm is very simple, so that intelligence in 6236 driver selection must come from smart driver id records. 6237 Unless you have good reasons to use another selection policy, 6238 provide match elements only in related groups, and order match 6239 specifiers from specific to general. Use the macros provided 6240 for that purpose if you can. 6241 </para><para> 6242 6243 The most specific match specifiers use device descriptor 6244 data. These are commonly used with product-specific matches; 6245 the USB_DEVICE macro lets you provide vendor and product IDs, 6246 and you can also match against ranges of product revisions. 6247 These are widely used for devices with application or vendor 6248 specific bDeviceClass values. 6249 </para><para> 6250 6251 Matches based on device class/subclass/protocol specifications 6252 are slightly more general; use the USB_DEVICE_INFO macro, or 6253 its siblings. These are used with single-function devices 6254 where bDeviceClass doesn't specify that each interface has 6255 its own class. 6256 </para><para> 6257 6258 Matches based on interface class/subclass/protocol are the 6259 most general; they let drivers bind to any interface on a 6260 multiple-function device. Use the USB_INTERFACE_INFO 6261 macro, or its siblings, to match class-per-interface style 6262 devices (as recorded in bInterfaceClass). 6263 </para><para> 6264 6265 Note that an entry created by USB_INTERFACE_INFO won't match 6266 any interface if the device class is set to Vendor-Specific. 6267 This is deliberate; according to the USB spec the meanings of 6268 the interface class/subclass/protocol for these devices are also 6269 vendor-specific, and hence matching against a standard product 6270 class wouldn't work anyway. If you really want to use an 6271 interface-based match for such a device, create a match record 6272 that also specifies the vendor ID. (Unforunately there isn't a 6273 standard macro for creating records like this.) 6274 </para><para> 6275 6276 Within those groups, remember that not all combinations are 6277 meaningful. For example, don't give a product version range 6278 without vendor and product IDs; or specify a protocol without 6279 its associated class and subclass. 6280</para> 6281</refsect1> 6282</refentry> 6283 6284<refentry id="API-usb-register-device-driver"> 6285<refentryinfo> 6286 <title>LINUX</title> 6287 <productname>Kernel Hackers Manual</productname> 6288 <date>July 2017</date> 6289</refentryinfo> 6290<refmeta> 6291 <refentrytitle><phrase>usb_register_device_driver</phrase></refentrytitle> 6292 <manvolnum>9</manvolnum> 6293 <refmiscinfo class="version">4.1.27</refmiscinfo> 6294</refmeta> 6295<refnamediv> 6296 <refname>usb_register_device_driver</refname> 6297 <refpurpose> 6298 register a USB device (not interface) driver 6299 </refpurpose> 6300</refnamediv> 6301<refsynopsisdiv> 6302 <title>Synopsis</title> 6303 <funcsynopsis><funcprototype> 6304 <funcdef>int <function>usb_register_device_driver </function></funcdef> 6305 <paramdef>struct usb_device_driver * <parameter>new_udriver</parameter></paramdef> 6306 <paramdef>struct module * <parameter>owner</parameter></paramdef> 6307 </funcprototype></funcsynopsis> 6308</refsynopsisdiv> 6309<refsect1> 6310 <title>Arguments</title> 6311 <variablelist> 6312 <varlistentry> 6313 <term><parameter>new_udriver</parameter></term> 6314 <listitem> 6315 <para> 6316 USB operations for the device driver 6317 </para> 6318 </listitem> 6319 </varlistentry> 6320 <varlistentry> 6321 <term><parameter>owner</parameter></term> 6322 <listitem> 6323 <para> 6324 module owner of this driver. 6325 </para> 6326 </listitem> 6327 </varlistentry> 6328 </variablelist> 6329</refsect1> 6330<refsect1> 6331<title>Description</title> 6332<para> 6333 Registers a USB device driver with the USB core. The list of 6334 unattached devices will be rescanned whenever a new driver is 6335 added, allowing the new driver to attach to any recognized devices. 6336</para> 6337</refsect1> 6338<refsect1> 6339<title>Return</title> 6340<para> 6341 A negative error code on failure and 0 on success. 6342</para> 6343</refsect1> 6344</refentry> 6345 6346<refentry id="API-usb-deregister-device-driver"> 6347<refentryinfo> 6348 <title>LINUX</title> 6349 <productname>Kernel Hackers Manual</productname> 6350 <date>July 2017</date> 6351</refentryinfo> 6352<refmeta> 6353 <refentrytitle><phrase>usb_deregister_device_driver</phrase></refentrytitle> 6354 <manvolnum>9</manvolnum> 6355 <refmiscinfo class="version">4.1.27</refmiscinfo> 6356</refmeta> 6357<refnamediv> 6358 <refname>usb_deregister_device_driver</refname> 6359 <refpurpose> 6360 unregister a USB device (not interface) driver 6361 </refpurpose> 6362</refnamediv> 6363<refsynopsisdiv> 6364 <title>Synopsis</title> 6365 <funcsynopsis><funcprototype> 6366 <funcdef>void <function>usb_deregister_device_driver </function></funcdef> 6367 <paramdef>struct usb_device_driver * <parameter>udriver</parameter></paramdef> 6368 </funcprototype></funcsynopsis> 6369</refsynopsisdiv> 6370<refsect1> 6371 <title>Arguments</title> 6372 <variablelist> 6373 <varlistentry> 6374 <term><parameter>udriver</parameter></term> 6375 <listitem> 6376 <para> 6377 USB operations of the device driver to unregister 6378 </para> 6379 </listitem> 6380 </varlistentry> 6381 </variablelist> 6382</refsect1> 6383<refsect1> 6384<title>Context</title> 6385<para> 6386 must be able to sleep 6387</para> 6388</refsect1> 6389<refsect1> 6390<title>Description</title> 6391<para> 6392 Unlinks the specified driver from the internal USB driver list. 6393</para> 6394</refsect1> 6395</refentry> 6396 6397<refentry id="API-usb-register-driver"> 6398<refentryinfo> 6399 <title>LINUX</title> 6400 <productname>Kernel Hackers Manual</productname> 6401 <date>July 2017</date> 6402</refentryinfo> 6403<refmeta> 6404 <refentrytitle><phrase>usb_register_driver</phrase></refentrytitle> 6405 <manvolnum>9</manvolnum> 6406 <refmiscinfo class="version">4.1.27</refmiscinfo> 6407</refmeta> 6408<refnamediv> 6409 <refname>usb_register_driver</refname> 6410 <refpurpose> 6411 register a USB interface driver 6412 </refpurpose> 6413</refnamediv> 6414<refsynopsisdiv> 6415 <title>Synopsis</title> 6416 <funcsynopsis><funcprototype> 6417 <funcdef>int <function>usb_register_driver </function></funcdef> 6418 <paramdef>struct usb_driver * <parameter>new_driver</parameter></paramdef> 6419 <paramdef>struct module * <parameter>owner</parameter></paramdef> 6420 <paramdef>const char * <parameter>mod_name</parameter></paramdef> 6421 </funcprototype></funcsynopsis> 6422</refsynopsisdiv> 6423<refsect1> 6424 <title>Arguments</title> 6425 <variablelist> 6426 <varlistentry> 6427 <term><parameter>new_driver</parameter></term> 6428 <listitem> 6429 <para> 6430 USB operations for the interface driver 6431 </para> 6432 </listitem> 6433 </varlistentry> 6434 <varlistentry> 6435 <term><parameter>owner</parameter></term> 6436 <listitem> 6437 <para> 6438 module owner of this driver. 6439 </para> 6440 </listitem> 6441 </varlistentry> 6442 <varlistentry> 6443 <term><parameter>mod_name</parameter></term> 6444 <listitem> 6445 <para> 6446 module name string 6447 </para> 6448 </listitem> 6449 </varlistentry> 6450 </variablelist> 6451</refsect1> 6452<refsect1> 6453<title>Description</title> 6454<para> 6455 Registers a USB interface driver with the USB core. The list of 6456 unattached interfaces will be rescanned whenever a new driver is 6457 added, allowing the new driver to attach to any recognized interfaces. 6458</para> 6459</refsect1> 6460<refsect1> 6461<title>Return</title> 6462<para> 6463 A negative error code on failure and 0 on success. 6464</para> 6465</refsect1> 6466<refsect1> 6467<title>NOTE</title> 6468<para> 6469 if you want your driver to use the USB major number, you must call 6470 <function>usb_register_dev</function> to enable that functionality. This function no longer 6471 takes care of that. 6472</para> 6473</refsect1> 6474</refentry> 6475 6476<refentry id="API-usb-deregister"> 6477<refentryinfo> 6478 <title>LINUX</title> 6479 <productname>Kernel Hackers Manual</productname> 6480 <date>July 2017</date> 6481</refentryinfo> 6482<refmeta> 6483 <refentrytitle><phrase>usb_deregister</phrase></refentrytitle> 6484 <manvolnum>9</manvolnum> 6485 <refmiscinfo class="version">4.1.27</refmiscinfo> 6486</refmeta> 6487<refnamediv> 6488 <refname>usb_deregister</refname> 6489 <refpurpose> 6490 unregister a USB interface driver 6491 </refpurpose> 6492</refnamediv> 6493<refsynopsisdiv> 6494 <title>Synopsis</title> 6495 <funcsynopsis><funcprototype> 6496 <funcdef>void <function>usb_deregister </function></funcdef> 6497 <paramdef>struct usb_driver * <parameter>driver</parameter></paramdef> 6498 </funcprototype></funcsynopsis> 6499</refsynopsisdiv> 6500<refsect1> 6501 <title>Arguments</title> 6502 <variablelist> 6503 <varlistentry> 6504 <term><parameter>driver</parameter></term> 6505 <listitem> 6506 <para> 6507 USB operations of the interface driver to unregister 6508 </para> 6509 </listitem> 6510 </varlistentry> 6511 </variablelist> 6512</refsect1> 6513<refsect1> 6514<title>Context</title> 6515<para> 6516 must be able to sleep 6517</para> 6518</refsect1> 6519<refsect1> 6520<title>Description</title> 6521<para> 6522 Unlinks the specified driver from the internal USB driver list. 6523</para> 6524</refsect1> 6525<refsect1> 6526<title>NOTE</title> 6527<para> 6528 If you called <function>usb_register_dev</function>, you still need to call 6529 <function>usb_deregister_dev</function> to clean up your driver's allocated minor numbers, 6530 this * call will no longer do it for you. 6531</para> 6532</refsect1> 6533</refentry> 6534 6535<refentry id="API-usb-enable-autosuspend"> 6536<refentryinfo> 6537 <title>LINUX</title> 6538 <productname>Kernel Hackers Manual</productname> 6539 <date>July 2017</date> 6540</refentryinfo> 6541<refmeta> 6542 <refentrytitle><phrase>usb_enable_autosuspend</phrase></refentrytitle> 6543 <manvolnum>9</manvolnum> 6544 <refmiscinfo class="version">4.1.27</refmiscinfo> 6545</refmeta> 6546<refnamediv> 6547 <refname>usb_enable_autosuspend</refname> 6548 <refpurpose> 6549 allow a USB device to be autosuspended 6550 </refpurpose> 6551</refnamediv> 6552<refsynopsisdiv> 6553 <title>Synopsis</title> 6554 <funcsynopsis><funcprototype> 6555 <funcdef>void <function>usb_enable_autosuspend </function></funcdef> 6556 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 6557 </funcprototype></funcsynopsis> 6558</refsynopsisdiv> 6559<refsect1> 6560 <title>Arguments</title> 6561 <variablelist> 6562 <varlistentry> 6563 <term><parameter>udev</parameter></term> 6564 <listitem> 6565 <para> 6566 the USB device which may be autosuspended 6567 </para> 6568 </listitem> 6569 </varlistentry> 6570 </variablelist> 6571</refsect1> 6572<refsect1> 6573<title>Description</title> 6574<para> 6575 This routine allows <parameter>udev</parameter> to be autosuspended. An autosuspend won't 6576 take place until the autosuspend_delay has elapsed and all the other 6577 necessary conditions are satisfied. 6578 </para><para> 6579 6580 The caller must hold <parameter>udev</parameter>'s device lock. 6581</para> 6582</refsect1> 6583</refentry> 6584 6585<refentry id="API-usb-disable-autosuspend"> 6586<refentryinfo> 6587 <title>LINUX</title> 6588 <productname>Kernel Hackers Manual</productname> 6589 <date>July 2017</date> 6590</refentryinfo> 6591<refmeta> 6592 <refentrytitle><phrase>usb_disable_autosuspend</phrase></refentrytitle> 6593 <manvolnum>9</manvolnum> 6594 <refmiscinfo class="version">4.1.27</refmiscinfo> 6595</refmeta> 6596<refnamediv> 6597 <refname>usb_disable_autosuspend</refname> 6598 <refpurpose> 6599 prevent a USB device from being autosuspended 6600 </refpurpose> 6601</refnamediv> 6602<refsynopsisdiv> 6603 <title>Synopsis</title> 6604 <funcsynopsis><funcprototype> 6605 <funcdef>void <function>usb_disable_autosuspend </function></funcdef> 6606 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 6607 </funcprototype></funcsynopsis> 6608</refsynopsisdiv> 6609<refsect1> 6610 <title>Arguments</title> 6611 <variablelist> 6612 <varlistentry> 6613 <term><parameter>udev</parameter></term> 6614 <listitem> 6615 <para> 6616 the USB device which may not be autosuspended 6617 </para> 6618 </listitem> 6619 </varlistentry> 6620 </variablelist> 6621</refsect1> 6622<refsect1> 6623<title>Description</title> 6624<para> 6625 This routine prevents <parameter>udev</parameter> from being autosuspended and wakes it up 6626 if it is already autosuspended. 6627 </para><para> 6628 6629 The caller must hold <parameter>udev</parameter>'s device lock. 6630</para> 6631</refsect1> 6632</refentry> 6633 6634<refentry id="API-usb-autopm-put-interface"> 6635<refentryinfo> 6636 <title>LINUX</title> 6637 <productname>Kernel Hackers Manual</productname> 6638 <date>July 2017</date> 6639</refentryinfo> 6640<refmeta> 6641 <refentrytitle><phrase>usb_autopm_put_interface</phrase></refentrytitle> 6642 <manvolnum>9</manvolnum> 6643 <refmiscinfo class="version">4.1.27</refmiscinfo> 6644</refmeta> 6645<refnamediv> 6646 <refname>usb_autopm_put_interface</refname> 6647 <refpurpose> 6648 decrement a USB interface's PM-usage counter 6649 </refpurpose> 6650</refnamediv> 6651<refsynopsisdiv> 6652 <title>Synopsis</title> 6653 <funcsynopsis><funcprototype> 6654 <funcdef>void <function>usb_autopm_put_interface </function></funcdef> 6655 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6656 </funcprototype></funcsynopsis> 6657</refsynopsisdiv> 6658<refsect1> 6659 <title>Arguments</title> 6660 <variablelist> 6661 <varlistentry> 6662 <term><parameter>intf</parameter></term> 6663 <listitem> 6664 <para> 6665 the usb_interface whose counter should be decremented 6666 </para> 6667 </listitem> 6668 </varlistentry> 6669 </variablelist> 6670</refsect1> 6671<refsect1> 6672<title>Description</title> 6673<para> 6674 This routine should be called by an interface driver when it is 6675 finished using <parameter>intf</parameter> and wants to allow it to autosuspend. A typical 6676 example would be a character-device driver when its device file is 6677 closed. 6678 </para><para> 6679 6680 The routine decrements <parameter>intf</parameter>'s usage counter. When the counter reaches 6681 0, a delayed autosuspend request for <parameter>intf</parameter>'s device is attempted. The 6682 attempt may fail (see <function>autosuspend_check</function>). 6683 </para><para> 6684 6685 This routine can run only in process context. 6686</para> 6687</refsect1> 6688</refentry> 6689 6690<refentry id="API-usb-autopm-put-interface-async"> 6691<refentryinfo> 6692 <title>LINUX</title> 6693 <productname>Kernel Hackers Manual</productname> 6694 <date>July 2017</date> 6695</refentryinfo> 6696<refmeta> 6697 <refentrytitle><phrase>usb_autopm_put_interface_async</phrase></refentrytitle> 6698 <manvolnum>9</manvolnum> 6699 <refmiscinfo class="version">4.1.27</refmiscinfo> 6700</refmeta> 6701<refnamediv> 6702 <refname>usb_autopm_put_interface_async</refname> 6703 <refpurpose> 6704 decrement a USB interface's PM-usage counter 6705 </refpurpose> 6706</refnamediv> 6707<refsynopsisdiv> 6708 <title>Synopsis</title> 6709 <funcsynopsis><funcprototype> 6710 <funcdef>void <function>usb_autopm_put_interface_async </function></funcdef> 6711 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6712 </funcprototype></funcsynopsis> 6713</refsynopsisdiv> 6714<refsect1> 6715 <title>Arguments</title> 6716 <variablelist> 6717 <varlistentry> 6718 <term><parameter>intf</parameter></term> 6719 <listitem> 6720 <para> 6721 the usb_interface whose counter should be decremented 6722 </para> 6723 </listitem> 6724 </varlistentry> 6725 </variablelist> 6726</refsect1> 6727<refsect1> 6728<title>Description</title> 6729<para> 6730 This routine does much the same thing as <function>usb_autopm_put_interface</function>: 6731 It decrements <parameter>intf</parameter>'s usage counter and schedules a delayed 6732 autosuspend request if the counter is <= 0. The difference is that it 6733 does not perform any synchronization; callers should hold a private 6734 lock and handle all synchronization issues themselves. 6735 </para><para> 6736 6737 Typically a driver would call this routine during an URB's completion 6738 handler, if no more URBs were pending. 6739 </para><para> 6740 6741 This routine can run in atomic context. 6742</para> 6743</refsect1> 6744</refentry> 6745 6746<refentry id="API-usb-autopm-put-interface-no-suspend"> 6747<refentryinfo> 6748 <title>LINUX</title> 6749 <productname>Kernel Hackers Manual</productname> 6750 <date>July 2017</date> 6751</refentryinfo> 6752<refmeta> 6753 <refentrytitle><phrase>usb_autopm_put_interface_no_suspend</phrase></refentrytitle> 6754 <manvolnum>9</manvolnum> 6755 <refmiscinfo class="version">4.1.27</refmiscinfo> 6756</refmeta> 6757<refnamediv> 6758 <refname>usb_autopm_put_interface_no_suspend</refname> 6759 <refpurpose> 6760 decrement a USB interface's PM-usage counter 6761 </refpurpose> 6762</refnamediv> 6763<refsynopsisdiv> 6764 <title>Synopsis</title> 6765 <funcsynopsis><funcprototype> 6766 <funcdef>void <function>usb_autopm_put_interface_no_suspend </function></funcdef> 6767 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6768 </funcprototype></funcsynopsis> 6769</refsynopsisdiv> 6770<refsect1> 6771 <title>Arguments</title> 6772 <variablelist> 6773 <varlistentry> 6774 <term><parameter>intf</parameter></term> 6775 <listitem> 6776 <para> 6777 the usb_interface whose counter should be decremented 6778 </para> 6779 </listitem> 6780 </varlistentry> 6781 </variablelist> 6782</refsect1> 6783<refsect1> 6784<title>Description</title> 6785<para> 6786 This routine decrements <parameter>intf</parameter>'s usage counter but does not carry out an 6787 autosuspend. 6788 </para><para> 6789 6790 This routine can run in atomic context. 6791</para> 6792</refsect1> 6793</refentry> 6794 6795<refentry id="API-usb-autopm-get-interface"> 6796<refentryinfo> 6797 <title>LINUX</title> 6798 <productname>Kernel Hackers Manual</productname> 6799 <date>July 2017</date> 6800</refentryinfo> 6801<refmeta> 6802 <refentrytitle><phrase>usb_autopm_get_interface</phrase></refentrytitle> 6803 <manvolnum>9</manvolnum> 6804 <refmiscinfo class="version">4.1.27</refmiscinfo> 6805</refmeta> 6806<refnamediv> 6807 <refname>usb_autopm_get_interface</refname> 6808 <refpurpose> 6809 increment a USB interface's PM-usage counter 6810 </refpurpose> 6811</refnamediv> 6812<refsynopsisdiv> 6813 <title>Synopsis</title> 6814 <funcsynopsis><funcprototype> 6815 <funcdef>int <function>usb_autopm_get_interface </function></funcdef> 6816 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6817 </funcprototype></funcsynopsis> 6818</refsynopsisdiv> 6819<refsect1> 6820 <title>Arguments</title> 6821 <variablelist> 6822 <varlistentry> 6823 <term><parameter>intf</parameter></term> 6824 <listitem> 6825 <para> 6826 the usb_interface whose counter should be incremented 6827 </para> 6828 </listitem> 6829 </varlistentry> 6830 </variablelist> 6831</refsect1> 6832<refsect1> 6833<title>Description</title> 6834<para> 6835 This routine should be called by an interface driver when it wants to 6836 use <parameter>intf</parameter> and needs to guarantee that it is not suspended. In addition, 6837 the routine prevents <parameter>intf</parameter> from being autosuspended subsequently. (Note 6838 that this will not prevent suspend events originating in the PM core.) 6839 This prevention will persist until <function>usb_autopm_put_interface</function> is called 6840 or <parameter>intf</parameter> is unbound. A typical example would be a character-device 6841 driver when its device file is opened. 6842 </para><para> 6843 6844 <parameter>intf</parameter>'s usage counter is incremented to prevent subsequent autosuspends. 6845 However if the autoresume fails then the counter is re-decremented. 6846 </para><para> 6847 6848 This routine can run only in process context. 6849</para> 6850</refsect1> 6851<refsect1> 6852<title>Return</title> 6853<para> 6854 0 on success. 6855</para> 6856</refsect1> 6857</refentry> 6858 6859<refentry id="API-usb-autopm-get-interface-async"> 6860<refentryinfo> 6861 <title>LINUX</title> 6862 <productname>Kernel Hackers Manual</productname> 6863 <date>July 2017</date> 6864</refentryinfo> 6865<refmeta> 6866 <refentrytitle><phrase>usb_autopm_get_interface_async</phrase></refentrytitle> 6867 <manvolnum>9</manvolnum> 6868 <refmiscinfo class="version">4.1.27</refmiscinfo> 6869</refmeta> 6870<refnamediv> 6871 <refname>usb_autopm_get_interface_async</refname> 6872 <refpurpose> 6873 increment a USB interface's PM-usage counter 6874 </refpurpose> 6875</refnamediv> 6876<refsynopsisdiv> 6877 <title>Synopsis</title> 6878 <funcsynopsis><funcprototype> 6879 <funcdef>int <function>usb_autopm_get_interface_async </function></funcdef> 6880 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6881 </funcprototype></funcsynopsis> 6882</refsynopsisdiv> 6883<refsect1> 6884 <title>Arguments</title> 6885 <variablelist> 6886 <varlistentry> 6887 <term><parameter>intf</parameter></term> 6888 <listitem> 6889 <para> 6890 the usb_interface whose counter should be incremented 6891 </para> 6892 </listitem> 6893 </varlistentry> 6894 </variablelist> 6895</refsect1> 6896<refsect1> 6897<title>Description</title> 6898<para> 6899 This routine does much the same thing as 6900 <function>usb_autopm_get_interface</function>: It increments <parameter>intf</parameter>'s usage counter and 6901 queues an autoresume request if the device is suspended. The 6902 differences are that it does not perform any synchronization (callers 6903 should hold a private lock and handle all synchronization issues 6904 themselves), and it does not autoresume the device directly (it only 6905 queues a request). After a successful call, the device may not yet be 6906 resumed. 6907 </para><para> 6908 6909 This routine can run in atomic context. 6910</para> 6911</refsect1> 6912<refsect1> 6913<title>Return</title> 6914<para> 6915 0 on success. A negative error code otherwise. 6916</para> 6917</refsect1> 6918</refentry> 6919 6920<refentry id="API-usb-autopm-get-interface-no-resume"> 6921<refentryinfo> 6922 <title>LINUX</title> 6923 <productname>Kernel Hackers Manual</productname> 6924 <date>July 2017</date> 6925</refentryinfo> 6926<refmeta> 6927 <refentrytitle><phrase>usb_autopm_get_interface_no_resume</phrase></refentrytitle> 6928 <manvolnum>9</manvolnum> 6929 <refmiscinfo class="version">4.1.27</refmiscinfo> 6930</refmeta> 6931<refnamediv> 6932 <refname>usb_autopm_get_interface_no_resume</refname> 6933 <refpurpose> 6934 increment a USB interface's PM-usage counter 6935 </refpurpose> 6936</refnamediv> 6937<refsynopsisdiv> 6938 <title>Synopsis</title> 6939 <funcsynopsis><funcprototype> 6940 <funcdef>void <function>usb_autopm_get_interface_no_resume </function></funcdef> 6941 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 6942 </funcprototype></funcsynopsis> 6943</refsynopsisdiv> 6944<refsect1> 6945 <title>Arguments</title> 6946 <variablelist> 6947 <varlistentry> 6948 <term><parameter>intf</parameter></term> 6949 <listitem> 6950 <para> 6951 the usb_interface whose counter should be incremented 6952 </para> 6953 </listitem> 6954 </varlistentry> 6955 </variablelist> 6956</refsect1> 6957<refsect1> 6958<title>Description</title> 6959<para> 6960 This routine increments <parameter>intf</parameter>'s usage counter but does not carry out an 6961 autoresume. 6962 </para><para> 6963 6964 This routine can run in atomic context. 6965</para> 6966</refsect1> 6967</refentry> 6968 6969<!-- drivers/usb/core/usb.c --> 6970<refentry id="API-usb-find-alt-setting"> 6971<refentryinfo> 6972 <title>LINUX</title> 6973 <productname>Kernel Hackers Manual</productname> 6974 <date>July 2017</date> 6975</refentryinfo> 6976<refmeta> 6977 <refentrytitle><phrase>usb_find_alt_setting</phrase></refentrytitle> 6978 <manvolnum>9</manvolnum> 6979 <refmiscinfo class="version">4.1.27</refmiscinfo> 6980</refmeta> 6981<refnamediv> 6982 <refname>usb_find_alt_setting</refname> 6983 <refpurpose> 6984 Given a configuration, find the alternate setting for the given interface. 6985 </refpurpose> 6986</refnamediv> 6987<refsynopsisdiv> 6988 <title>Synopsis</title> 6989 <funcsynopsis><funcprototype> 6990 <funcdef>struct usb_host_interface * <function>usb_find_alt_setting </function></funcdef> 6991 <paramdef>struct usb_host_config * <parameter>config</parameter></paramdef> 6992 <paramdef>unsigned int <parameter>iface_num</parameter></paramdef> 6993 <paramdef>unsigned int <parameter>alt_num</parameter></paramdef> 6994 </funcprototype></funcsynopsis> 6995</refsynopsisdiv> 6996<refsect1> 6997 <title>Arguments</title> 6998 <variablelist> 6999 <varlistentry> 7000 <term><parameter>config</parameter></term> 7001 <listitem> 7002 <para> 7003 the configuration to search (not necessarily the current config). 7004 </para> 7005 </listitem> 7006 </varlistentry> 7007 <varlistentry> 7008 <term><parameter>iface_num</parameter></term> 7009 <listitem> 7010 <para> 7011 interface number to search in 7012 </para> 7013 </listitem> 7014 </varlistentry> 7015 <varlistentry> 7016 <term><parameter>alt_num</parameter></term> 7017 <listitem> 7018 <para> 7019 alternate interface setting number to search for. 7020 </para> 7021 </listitem> 7022 </varlistentry> 7023 </variablelist> 7024</refsect1> 7025<refsect1> 7026<title>Description</title> 7027<para> 7028 Search the configuration's interface cache for the given alt setting. 7029</para> 7030</refsect1> 7031<refsect1> 7032<title>Return</title> 7033<para> 7034 The alternate setting, if found. <constant>NULL</constant> otherwise. 7035</para> 7036</refsect1> 7037</refentry> 7038 7039<refentry id="API-usb-ifnum-to-if"> 7040<refentryinfo> 7041 <title>LINUX</title> 7042 <productname>Kernel Hackers Manual</productname> 7043 <date>July 2017</date> 7044</refentryinfo> 7045<refmeta> 7046 <refentrytitle><phrase>usb_ifnum_to_if</phrase></refentrytitle> 7047 <manvolnum>9</manvolnum> 7048 <refmiscinfo class="version">4.1.27</refmiscinfo> 7049</refmeta> 7050<refnamediv> 7051 <refname>usb_ifnum_to_if</refname> 7052 <refpurpose> 7053 get the interface object with a given interface number 7054 </refpurpose> 7055</refnamediv> 7056<refsynopsisdiv> 7057 <title>Synopsis</title> 7058 <funcsynopsis><funcprototype> 7059 <funcdef>struct usb_interface * <function>usb_ifnum_to_if </function></funcdef> 7060 <paramdef>const struct usb_device * <parameter>dev</parameter></paramdef> 7061 <paramdef>unsigned <parameter>ifnum</parameter></paramdef> 7062 </funcprototype></funcsynopsis> 7063</refsynopsisdiv> 7064<refsect1> 7065 <title>Arguments</title> 7066 <variablelist> 7067 <varlistentry> 7068 <term><parameter>dev</parameter></term> 7069 <listitem> 7070 <para> 7071 the device whose current configuration is considered 7072 </para> 7073 </listitem> 7074 </varlistentry> 7075 <varlistentry> 7076 <term><parameter>ifnum</parameter></term> 7077 <listitem> 7078 <para> 7079 the desired interface 7080 </para> 7081 </listitem> 7082 </varlistentry> 7083 </variablelist> 7084</refsect1> 7085<refsect1> 7086<title>Description</title> 7087<para> 7088 This walks the device descriptor for the currently active configuration 7089 to find the interface object with the particular interface number. 7090 </para><para> 7091 7092 Note that configuration descriptors are not required to assign interface 7093 numbers sequentially, so that it would be incorrect to assume that 7094 the first interface in that descriptor corresponds to interface zero. 7095 This routine helps device drivers avoid such mistakes. 7096 However, you should make sure that you do the right thing with any 7097 alternate settings available for this interfaces. 7098 </para><para> 7099 7100 Don't call this function unless you are bound to one of the interfaces 7101 on this device or you have locked the device! 7102</para> 7103</refsect1> 7104<refsect1> 7105<title>Return</title> 7106<para> 7107 A pointer to the interface that has <parameter>ifnum</parameter> as interface number, 7108 if found. <constant>NULL</constant> otherwise. 7109</para> 7110</refsect1> 7111</refentry> 7112 7113<refentry id="API-usb-altnum-to-altsetting"> 7114<refentryinfo> 7115 <title>LINUX</title> 7116 <productname>Kernel Hackers Manual</productname> 7117 <date>July 2017</date> 7118</refentryinfo> 7119<refmeta> 7120 <refentrytitle><phrase>usb_altnum_to_altsetting</phrase></refentrytitle> 7121 <manvolnum>9</manvolnum> 7122 <refmiscinfo class="version">4.1.27</refmiscinfo> 7123</refmeta> 7124<refnamediv> 7125 <refname>usb_altnum_to_altsetting</refname> 7126 <refpurpose> 7127 get the altsetting structure with a given alternate setting number. 7128 </refpurpose> 7129</refnamediv> 7130<refsynopsisdiv> 7131 <title>Synopsis</title> 7132 <funcsynopsis><funcprototype> 7133 <funcdef>struct usb_host_interface * <function>usb_altnum_to_altsetting </function></funcdef> 7134 <paramdef>const struct usb_interface * <parameter>intf</parameter></paramdef> 7135 <paramdef>unsigned int <parameter>altnum</parameter></paramdef> 7136 </funcprototype></funcsynopsis> 7137</refsynopsisdiv> 7138<refsect1> 7139 <title>Arguments</title> 7140 <variablelist> 7141 <varlistentry> 7142 <term><parameter>intf</parameter></term> 7143 <listitem> 7144 <para> 7145 the interface containing the altsetting in question 7146 </para> 7147 </listitem> 7148 </varlistentry> 7149 <varlistentry> 7150 <term><parameter>altnum</parameter></term> 7151 <listitem> 7152 <para> 7153 the desired alternate setting number 7154 </para> 7155 </listitem> 7156 </varlistentry> 7157 </variablelist> 7158</refsect1> 7159<refsect1> 7160<title>Description</title> 7161<para> 7162 This searches the altsetting array of the specified interface for 7163 an entry with the correct bAlternateSetting value. 7164 </para><para> 7165 7166 Note that altsettings need not be stored sequentially by number, so 7167 it would be incorrect to assume that the first altsetting entry in 7168 the array corresponds to altsetting zero. This routine helps device 7169 drivers avoid such mistakes. 7170 </para><para> 7171 7172 Don't call this function unless you are bound to the intf interface 7173 or you have locked the device! 7174</para> 7175</refsect1> 7176<refsect1> 7177<title>Return</title> 7178<para> 7179 A pointer to the entry of the altsetting array of <parameter>intf</parameter> that 7180 has <parameter>altnum</parameter> as the alternate setting number. <constant>NULL</constant> if not found. 7181</para> 7182</refsect1> 7183</refentry> 7184 7185<refentry id="API-usb-find-interface"> 7186<refentryinfo> 7187 <title>LINUX</title> 7188 <productname>Kernel Hackers Manual</productname> 7189 <date>July 2017</date> 7190</refentryinfo> 7191<refmeta> 7192 <refentrytitle><phrase>usb_find_interface</phrase></refentrytitle> 7193 <manvolnum>9</manvolnum> 7194 <refmiscinfo class="version">4.1.27</refmiscinfo> 7195</refmeta> 7196<refnamediv> 7197 <refname>usb_find_interface</refname> 7198 <refpurpose> 7199 find usb_interface pointer for driver and device 7200 </refpurpose> 7201</refnamediv> 7202<refsynopsisdiv> 7203 <title>Synopsis</title> 7204 <funcsynopsis><funcprototype> 7205 <funcdef>struct usb_interface * <function>usb_find_interface </function></funcdef> 7206 <paramdef>struct usb_driver * <parameter>drv</parameter></paramdef> 7207 <paramdef>int <parameter>minor</parameter></paramdef> 7208 </funcprototype></funcsynopsis> 7209</refsynopsisdiv> 7210<refsect1> 7211 <title>Arguments</title> 7212 <variablelist> 7213 <varlistentry> 7214 <term><parameter>drv</parameter></term> 7215 <listitem> 7216 <para> 7217 the driver whose current configuration is considered 7218 </para> 7219 </listitem> 7220 </varlistentry> 7221 <varlistentry> 7222 <term><parameter>minor</parameter></term> 7223 <listitem> 7224 <para> 7225 the minor number of the desired device 7226 </para> 7227 </listitem> 7228 </varlistentry> 7229 </variablelist> 7230</refsect1> 7231<refsect1> 7232<title>Description</title> 7233<para> 7234 This walks the bus device list and returns a pointer to the interface 7235 with the matching minor and driver. Note, this only works for devices 7236 that share the USB major number. 7237</para> 7238</refsect1> 7239<refsect1> 7240<title>Return</title> 7241<para> 7242 A pointer to the interface with the matching major and <parameter>minor</parameter>. 7243</para> 7244</refsect1> 7245</refentry> 7246 7247<refentry id="API-usb-for-each-dev"> 7248<refentryinfo> 7249 <title>LINUX</title> 7250 <productname>Kernel Hackers Manual</productname> 7251 <date>July 2017</date> 7252</refentryinfo> 7253<refmeta> 7254 <refentrytitle><phrase>usb_for_each_dev</phrase></refentrytitle> 7255 <manvolnum>9</manvolnum> 7256 <refmiscinfo class="version">4.1.27</refmiscinfo> 7257</refmeta> 7258<refnamediv> 7259 <refname>usb_for_each_dev</refname> 7260 <refpurpose> 7261 iterate over all USB devices in the system 7262 </refpurpose> 7263</refnamediv> 7264<refsynopsisdiv> 7265 <title>Synopsis</title> 7266 <funcsynopsis><funcprototype> 7267 <funcdef>int <function>usb_for_each_dev </function></funcdef> 7268 <paramdef>void * <parameter>data</parameter></paramdef> 7269 <paramdef>int (*<parameter>fn</parameter>) 7270 <funcparams>struct usb_device *, void *</funcparams></paramdef> 7271 </funcprototype></funcsynopsis> 7272</refsynopsisdiv> 7273<refsect1> 7274 <title>Arguments</title> 7275 <variablelist> 7276 <varlistentry> 7277 <term><parameter>data</parameter></term> 7278 <listitem> 7279 <para> 7280 data pointer that will be handed to the callback function 7281 </para> 7282 </listitem> 7283 </varlistentry> 7284 <varlistentry> 7285 <term><parameter>fn</parameter></term> 7286 <listitem> 7287 <para> 7288 callback function to be called for each USB device 7289 </para> 7290 </listitem> 7291 </varlistentry> 7292 </variablelist> 7293</refsect1> 7294<refsect1> 7295<title>Description</title> 7296<para> 7297 Iterate over all USB devices and call <parameter>fn</parameter> for each, passing it <parameter>data</parameter>. If it 7298 returns anything other than 0, we break the iteration prematurely and return 7299 that value. 7300</para> 7301</refsect1> 7302</refentry> 7303 7304<refentry id="API-usb-alloc-dev"> 7305<refentryinfo> 7306 <title>LINUX</title> 7307 <productname>Kernel Hackers Manual</productname> 7308 <date>July 2017</date> 7309</refentryinfo> 7310<refmeta> 7311 <refentrytitle><phrase>usb_alloc_dev</phrase></refentrytitle> 7312 <manvolnum>9</manvolnum> 7313 <refmiscinfo class="version">4.1.27</refmiscinfo> 7314</refmeta> 7315<refnamediv> 7316 <refname>usb_alloc_dev</refname> 7317 <refpurpose> 7318 usb device constructor (usbcore-internal) 7319 </refpurpose> 7320</refnamediv> 7321<refsynopsisdiv> 7322 <title>Synopsis</title> 7323 <funcsynopsis><funcprototype> 7324 <funcdef>struct usb_device * <function>usb_alloc_dev </function></funcdef> 7325 <paramdef>struct usb_device * <parameter>parent</parameter></paramdef> 7326 <paramdef>struct usb_bus * <parameter>bus</parameter></paramdef> 7327 <paramdef>unsigned <parameter>port1</parameter></paramdef> 7328 </funcprototype></funcsynopsis> 7329</refsynopsisdiv> 7330<refsect1> 7331 <title>Arguments</title> 7332 <variablelist> 7333 <varlistentry> 7334 <term><parameter>parent</parameter></term> 7335 <listitem> 7336 <para> 7337 hub to which device is connected; null to allocate a root hub 7338 </para> 7339 </listitem> 7340 </varlistentry> 7341 <varlistentry> 7342 <term><parameter>bus</parameter></term> 7343 <listitem> 7344 <para> 7345 bus used to access the device 7346 </para> 7347 </listitem> 7348 </varlistentry> 7349 <varlistentry> 7350 <term><parameter>port1</parameter></term> 7351 <listitem> 7352 <para> 7353 one-based index of port; ignored for root hubs 7354 </para> 7355 </listitem> 7356 </varlistentry> 7357 </variablelist> 7358</refsect1> 7359<refsect1> 7360<title>Context</title> 7361<para> 7362 !<function>in_interrupt</function> 7363</para> 7364</refsect1> 7365<refsect1> 7366<title>Description</title> 7367<para> 7368 Only hub drivers (including virtual root hub drivers for host 7369 controllers) should ever call this. 7370 </para><para> 7371 7372 This call may not be used in a non-sleeping context. 7373</para> 7374</refsect1> 7375<refsect1> 7376<title>Return</title> 7377<para> 7378 On success, a pointer to the allocated usb device. <constant>NULL</constant> on 7379 failure. 7380</para> 7381</refsect1> 7382</refentry> 7383 7384<refentry id="API-usb-get-dev"> 7385<refentryinfo> 7386 <title>LINUX</title> 7387 <productname>Kernel Hackers Manual</productname> 7388 <date>July 2017</date> 7389</refentryinfo> 7390<refmeta> 7391 <refentrytitle><phrase>usb_get_dev</phrase></refentrytitle> 7392 <manvolnum>9</manvolnum> 7393 <refmiscinfo class="version">4.1.27</refmiscinfo> 7394</refmeta> 7395<refnamediv> 7396 <refname>usb_get_dev</refname> 7397 <refpurpose> 7398 increments the reference count of the usb device structure 7399 </refpurpose> 7400</refnamediv> 7401<refsynopsisdiv> 7402 <title>Synopsis</title> 7403 <funcsynopsis><funcprototype> 7404 <funcdef>struct usb_device * <function>usb_get_dev </function></funcdef> 7405 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 7406 </funcprototype></funcsynopsis> 7407</refsynopsisdiv> 7408<refsect1> 7409 <title>Arguments</title> 7410 <variablelist> 7411 <varlistentry> 7412 <term><parameter>dev</parameter></term> 7413 <listitem> 7414 <para> 7415 the device being referenced 7416 </para> 7417 </listitem> 7418 </varlistentry> 7419 </variablelist> 7420</refsect1> 7421<refsect1> 7422<title>Description</title> 7423<para> 7424 Each live reference to a device should be refcounted. 7425 </para><para> 7426 7427 Drivers for USB interfaces should normally record such references in 7428 their <function>probe</function> methods, when they bind to an interface, and release 7429 them by calling <function>usb_put_dev</function>, in their <function>disconnect</function> methods. 7430</para> 7431</refsect1> 7432<refsect1> 7433<title>Return</title> 7434<para> 7435 A pointer to the device with the incremented reference counter. 7436</para> 7437</refsect1> 7438</refentry> 7439 7440<refentry id="API-usb-put-dev"> 7441<refentryinfo> 7442 <title>LINUX</title> 7443 <productname>Kernel Hackers Manual</productname> 7444 <date>July 2017</date> 7445</refentryinfo> 7446<refmeta> 7447 <refentrytitle><phrase>usb_put_dev</phrase></refentrytitle> 7448 <manvolnum>9</manvolnum> 7449 <refmiscinfo class="version">4.1.27</refmiscinfo> 7450</refmeta> 7451<refnamediv> 7452 <refname>usb_put_dev</refname> 7453 <refpurpose> 7454 release a use of the usb device structure 7455 </refpurpose> 7456</refnamediv> 7457<refsynopsisdiv> 7458 <title>Synopsis</title> 7459 <funcsynopsis><funcprototype> 7460 <funcdef>void <function>usb_put_dev </function></funcdef> 7461 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 7462 </funcprototype></funcsynopsis> 7463</refsynopsisdiv> 7464<refsect1> 7465 <title>Arguments</title> 7466 <variablelist> 7467 <varlistentry> 7468 <term><parameter>dev</parameter></term> 7469 <listitem> 7470 <para> 7471 device that's been disconnected 7472 </para> 7473 </listitem> 7474 </varlistentry> 7475 </variablelist> 7476</refsect1> 7477<refsect1> 7478<title>Description</title> 7479<para> 7480 Must be called when a user of a device is finished with it. When the last 7481 user of the device calls this function, the memory of the device is freed. 7482</para> 7483</refsect1> 7484</refentry> 7485 7486<refentry id="API-usb-get-intf"> 7487<refentryinfo> 7488 <title>LINUX</title> 7489 <productname>Kernel Hackers Manual</productname> 7490 <date>July 2017</date> 7491</refentryinfo> 7492<refmeta> 7493 <refentrytitle><phrase>usb_get_intf</phrase></refentrytitle> 7494 <manvolnum>9</manvolnum> 7495 <refmiscinfo class="version">4.1.27</refmiscinfo> 7496</refmeta> 7497<refnamediv> 7498 <refname>usb_get_intf</refname> 7499 <refpurpose> 7500 increments the reference count of the usb interface structure 7501 </refpurpose> 7502</refnamediv> 7503<refsynopsisdiv> 7504 <title>Synopsis</title> 7505 <funcsynopsis><funcprototype> 7506 <funcdef>struct usb_interface * <function>usb_get_intf </function></funcdef> 7507 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 7508 </funcprototype></funcsynopsis> 7509</refsynopsisdiv> 7510<refsect1> 7511 <title>Arguments</title> 7512 <variablelist> 7513 <varlistentry> 7514 <term><parameter>intf</parameter></term> 7515 <listitem> 7516 <para> 7517 the interface being referenced 7518 </para> 7519 </listitem> 7520 </varlistentry> 7521 </variablelist> 7522</refsect1> 7523<refsect1> 7524<title>Description</title> 7525<para> 7526 Each live reference to a interface must be refcounted. 7527 </para><para> 7528 7529 Drivers for USB interfaces should normally record such references in 7530 their <function>probe</function> methods, when they bind to an interface, and release 7531 them by calling <function>usb_put_intf</function>, in their <function>disconnect</function> methods. 7532</para> 7533</refsect1> 7534<refsect1> 7535<title>Return</title> 7536<para> 7537 A pointer to the interface with the incremented reference counter. 7538</para> 7539</refsect1> 7540</refentry> 7541 7542<refentry id="API-usb-put-intf"> 7543<refentryinfo> 7544 <title>LINUX</title> 7545 <productname>Kernel Hackers Manual</productname> 7546 <date>July 2017</date> 7547</refentryinfo> 7548<refmeta> 7549 <refentrytitle><phrase>usb_put_intf</phrase></refentrytitle> 7550 <manvolnum>9</manvolnum> 7551 <refmiscinfo class="version">4.1.27</refmiscinfo> 7552</refmeta> 7553<refnamediv> 7554 <refname>usb_put_intf</refname> 7555 <refpurpose> 7556 release a use of the usb interface structure 7557 </refpurpose> 7558</refnamediv> 7559<refsynopsisdiv> 7560 <title>Synopsis</title> 7561 <funcsynopsis><funcprototype> 7562 <funcdef>void <function>usb_put_intf </function></funcdef> 7563 <paramdef>struct usb_interface * <parameter>intf</parameter></paramdef> 7564 </funcprototype></funcsynopsis> 7565</refsynopsisdiv> 7566<refsect1> 7567 <title>Arguments</title> 7568 <variablelist> 7569 <varlistentry> 7570 <term><parameter>intf</parameter></term> 7571 <listitem> 7572 <para> 7573 interface that's been decremented 7574 </para> 7575 </listitem> 7576 </varlistentry> 7577 </variablelist> 7578</refsect1> 7579<refsect1> 7580<title>Description</title> 7581<para> 7582 Must be called when a user of an interface is finished with it. When the 7583 last user of the interface calls this function, the memory of the interface 7584 is freed. 7585</para> 7586</refsect1> 7587</refentry> 7588 7589<refentry id="API-usb-lock-device-for-reset"> 7590<refentryinfo> 7591 <title>LINUX</title> 7592 <productname>Kernel Hackers Manual</productname> 7593 <date>July 2017</date> 7594</refentryinfo> 7595<refmeta> 7596 <refentrytitle><phrase>usb_lock_device_for_reset</phrase></refentrytitle> 7597 <manvolnum>9</manvolnum> 7598 <refmiscinfo class="version">4.1.27</refmiscinfo> 7599</refmeta> 7600<refnamediv> 7601 <refname>usb_lock_device_for_reset</refname> 7602 <refpurpose> 7603 cautiously acquire the lock for a usb device structure 7604 </refpurpose> 7605</refnamediv> 7606<refsynopsisdiv> 7607 <title>Synopsis</title> 7608 <funcsynopsis><funcprototype> 7609 <funcdef>int <function>usb_lock_device_for_reset </function></funcdef> 7610 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 7611 <paramdef>const struct usb_interface * <parameter>iface</parameter></paramdef> 7612 </funcprototype></funcsynopsis> 7613</refsynopsisdiv> 7614<refsect1> 7615 <title>Arguments</title> 7616 <variablelist> 7617 <varlistentry> 7618 <term><parameter>udev</parameter></term> 7619 <listitem> 7620 <para> 7621 device that's being locked 7622 </para> 7623 </listitem> 7624 </varlistentry> 7625 <varlistentry> 7626 <term><parameter>iface</parameter></term> 7627 <listitem> 7628 <para> 7629 interface bound to the driver making the request (optional) 7630 </para> 7631 </listitem> 7632 </varlistentry> 7633 </variablelist> 7634</refsect1> 7635<refsect1> 7636<title>Description</title> 7637<para> 7638 Attempts to acquire the device lock, but fails if the device is 7639 NOTATTACHED or SUSPENDED, or if iface is specified and the interface 7640 is neither BINDING nor BOUND. Rather than sleeping to wait for the 7641 lock, the routine polls repeatedly. This is to prevent deadlock with 7642 disconnect; in some drivers (such as usb-storage) the <function>disconnect</function> 7643 or <function>suspend</function> method will block waiting for a device reset to complete. 7644</para> 7645</refsect1> 7646<refsect1> 7647<title>Return</title> 7648<para> 7649 A negative error code for failure, otherwise 0. 7650</para> 7651</refsect1> 7652</refentry> 7653 7654<refentry id="API-usb-get-current-frame-number"> 7655<refentryinfo> 7656 <title>LINUX</title> 7657 <productname>Kernel Hackers Manual</productname> 7658 <date>July 2017</date> 7659</refentryinfo> 7660<refmeta> 7661 <refentrytitle><phrase>usb_get_current_frame_number</phrase></refentrytitle> 7662 <manvolnum>9</manvolnum> 7663 <refmiscinfo class="version">4.1.27</refmiscinfo> 7664</refmeta> 7665<refnamediv> 7666 <refname>usb_get_current_frame_number</refname> 7667 <refpurpose> 7668 return current bus frame number 7669 </refpurpose> 7670</refnamediv> 7671<refsynopsisdiv> 7672 <title>Synopsis</title> 7673 <funcsynopsis><funcprototype> 7674 <funcdef>int <function>usb_get_current_frame_number </function></funcdef> 7675 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 7676 </funcprototype></funcsynopsis> 7677</refsynopsisdiv> 7678<refsect1> 7679 <title>Arguments</title> 7680 <variablelist> 7681 <varlistentry> 7682 <term><parameter>dev</parameter></term> 7683 <listitem> 7684 <para> 7685 the device whose bus is being queried 7686 </para> 7687 </listitem> 7688 </varlistentry> 7689 </variablelist> 7690</refsect1> 7691<refsect1> 7692<title>Return</title> 7693<para> 7694 The current frame number for the USB host controller used 7695 with the given USB device. This can be used when scheduling 7696 isochronous requests. 7697</para> 7698</refsect1> 7699<refsect1> 7700<title>Note</title> 7701<para> 7702 Different kinds of host controller have different <quote>scheduling 7703 horizons</quote>. While one type might support scheduling only 32 frames 7704 into the future, others could support scheduling up to 1024 frames 7705 into the future. 7706</para> 7707</refsect1> 7708</refentry> 7709 7710<refentry id="API-usb-alloc-coherent"> 7711<refentryinfo> 7712 <title>LINUX</title> 7713 <productname>Kernel Hackers Manual</productname> 7714 <date>July 2017</date> 7715</refentryinfo> 7716<refmeta> 7717 <refentrytitle><phrase>usb_alloc_coherent</phrase></refentrytitle> 7718 <manvolnum>9</manvolnum> 7719 <refmiscinfo class="version">4.1.27</refmiscinfo> 7720</refmeta> 7721<refnamediv> 7722 <refname>usb_alloc_coherent</refname> 7723 <refpurpose> 7724 allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP 7725 </refpurpose> 7726</refnamediv> 7727<refsynopsisdiv> 7728 <title>Synopsis</title> 7729 <funcsynopsis><funcprototype> 7730 <funcdef>void * <function>usb_alloc_coherent </function></funcdef> 7731 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 7732 <paramdef>size_t <parameter>size</parameter></paramdef> 7733 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 7734 <paramdef>dma_addr_t * <parameter>dma</parameter></paramdef> 7735 </funcprototype></funcsynopsis> 7736</refsynopsisdiv> 7737<refsect1> 7738 <title>Arguments</title> 7739 <variablelist> 7740 <varlistentry> 7741 <term><parameter>dev</parameter></term> 7742 <listitem> 7743 <para> 7744 device the buffer will be used with 7745 </para> 7746 </listitem> 7747 </varlistentry> 7748 <varlistentry> 7749 <term><parameter>size</parameter></term> 7750 <listitem> 7751 <para> 7752 requested buffer size 7753 </para> 7754 </listitem> 7755 </varlistentry> 7756 <varlistentry> 7757 <term><parameter>mem_flags</parameter></term> 7758 <listitem> 7759 <para> 7760 affect whether allocation may block 7761 </para> 7762 </listitem> 7763 </varlistentry> 7764 <varlistentry> 7765 <term><parameter>dma</parameter></term> 7766 <listitem> 7767 <para> 7768 used to return DMA address of buffer 7769 </para> 7770 </listitem> 7771 </varlistentry> 7772 </variablelist> 7773</refsect1> 7774<refsect1> 7775<title>Return</title> 7776<para> 7777 Either null (indicating no buffer could be allocated), or the 7778 cpu-space pointer to a buffer that may be used to perform DMA to the 7779 specified device. Such cpu-space buffers are returned along with the DMA 7780 address (through the pointer provided). 7781</para> 7782</refsect1> 7783<refsect1> 7784<title>Note</title> 7785<para> 7786 These buffers are used with URB_NO_xxx_DMA_MAP set in urb->transfer_flags 7787 to avoid behaviors like using <quote>DMA bounce buffers</quote>, or thrashing IOMMU 7788 hardware during URB completion/resubmit. The implementation varies between 7789 platforms, depending on details of how DMA will work to this device. 7790 Using these buffers also eliminates cacheline sharing problems on 7791 architectures where CPU caches are not DMA-coherent. On systems without 7792 bus-snooping caches, these buffers are uncached. 7793 </para><para> 7794 7795 When the buffer is no longer used, free it with <function>usb_free_coherent</function>. 7796</para> 7797</refsect1> 7798</refentry> 7799 7800<refentry id="API-usb-free-coherent"> 7801<refentryinfo> 7802 <title>LINUX</title> 7803 <productname>Kernel Hackers Manual</productname> 7804 <date>July 2017</date> 7805</refentryinfo> 7806<refmeta> 7807 <refentrytitle><phrase>usb_free_coherent</phrase></refentrytitle> 7808 <manvolnum>9</manvolnum> 7809 <refmiscinfo class="version">4.1.27</refmiscinfo> 7810</refmeta> 7811<refnamediv> 7812 <refname>usb_free_coherent</refname> 7813 <refpurpose> 7814 free memory allocated with <function>usb_alloc_coherent</function> 7815 </refpurpose> 7816</refnamediv> 7817<refsynopsisdiv> 7818 <title>Synopsis</title> 7819 <funcsynopsis><funcprototype> 7820 <funcdef>void <function>usb_free_coherent </function></funcdef> 7821 <paramdef>struct usb_device * <parameter>dev</parameter></paramdef> 7822 <paramdef>size_t <parameter>size</parameter></paramdef> 7823 <paramdef>void * <parameter>addr</parameter></paramdef> 7824 <paramdef>dma_addr_t <parameter>dma</parameter></paramdef> 7825 </funcprototype></funcsynopsis> 7826</refsynopsisdiv> 7827<refsect1> 7828 <title>Arguments</title> 7829 <variablelist> 7830 <varlistentry> 7831 <term><parameter>dev</parameter></term> 7832 <listitem> 7833 <para> 7834 device the buffer was used with 7835 </para> 7836 </listitem> 7837 </varlistentry> 7838 <varlistentry> 7839 <term><parameter>size</parameter></term> 7840 <listitem> 7841 <para> 7842 requested buffer size 7843 </para> 7844 </listitem> 7845 </varlistentry> 7846 <varlistentry> 7847 <term><parameter>addr</parameter></term> 7848 <listitem> 7849 <para> 7850 CPU address of buffer 7851 </para> 7852 </listitem> 7853 </varlistentry> 7854 <varlistentry> 7855 <term><parameter>dma</parameter></term> 7856 <listitem> 7857 <para> 7858 DMA address of buffer 7859 </para> 7860 </listitem> 7861 </varlistentry> 7862 </variablelist> 7863</refsect1> 7864<refsect1> 7865<title>Description</title> 7866<para> 7867 This reclaims an I/O buffer, letting it be reused. The memory must have 7868 been allocated using <function>usb_alloc_coherent</function>, and the parameters must match 7869 those provided in that allocation request. 7870</para> 7871</refsect1> 7872</refentry> 7873 7874<refentry id="API-usb-buffer-map"> 7875<refentryinfo> 7876 <title>LINUX</title> 7877 <productname>Kernel Hackers Manual</productname> 7878 <date>July 2017</date> 7879</refentryinfo> 7880<refmeta> 7881 <refentrytitle><phrase>usb_buffer_map</phrase></refentrytitle> 7882 <manvolnum>9</manvolnum> 7883 <refmiscinfo class="version">4.1.27</refmiscinfo> 7884</refmeta> 7885<refnamediv> 7886 <refname>usb_buffer_map</refname> 7887 <refpurpose> 7888 create DMA mapping(s) for an urb 7889 </refpurpose> 7890</refnamediv> 7891<refsynopsisdiv> 7892 <title>Synopsis</title> 7893 <funcsynopsis><funcprototype> 7894 <funcdef>struct urb * <function>usb_buffer_map </function></funcdef> 7895 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 7896 </funcprototype></funcsynopsis> 7897</refsynopsisdiv> 7898<refsect1> 7899 <title>Arguments</title> 7900 <variablelist> 7901 <varlistentry> 7902 <term><parameter>urb</parameter></term> 7903 <listitem> 7904 <para> 7905 urb whose transfer_buffer/setup_packet will be mapped 7906 </para> 7907 </listitem> 7908 </varlistentry> 7909 </variablelist> 7910</refsect1> 7911<refsect1> 7912<title>Description</title> 7913<para> 7914 URB_NO_TRANSFER_DMA_MAP is added to urb->transfer_flags if the operation 7915 succeeds. If the device is connected to this system through a non-DMA 7916 controller, this operation always succeeds. 7917 </para><para> 7918 7919 This call would normally be used for an urb which is reused, perhaps 7920 as the target of a large periodic transfer, with <function>usb_buffer_dmasync</function> 7921 calls to synchronize memory and dma state. 7922 </para><para> 7923 7924 Reverse the effect of this call with <function>usb_buffer_unmap</function>. 7925</para> 7926</refsect1> 7927<refsect1> 7928<title>Return</title> 7929<para> 7930 Either <constant>NULL</constant> (indicating no buffer could be mapped), or <parameter>urb</parameter>. 7931</para> 7932</refsect1> 7933</refentry> 7934 7935<refentry id="API-usb-buffer-dmasync"> 7936<refentryinfo> 7937 <title>LINUX</title> 7938 <productname>Kernel Hackers Manual</productname> 7939 <date>July 2017</date> 7940</refentryinfo> 7941<refmeta> 7942 <refentrytitle><phrase>usb_buffer_dmasync</phrase></refentrytitle> 7943 <manvolnum>9</manvolnum> 7944 <refmiscinfo class="version">4.1.27</refmiscinfo> 7945</refmeta> 7946<refnamediv> 7947 <refname>usb_buffer_dmasync</refname> 7948 <refpurpose> 7949 synchronize DMA and CPU view of buffer(s) 7950 </refpurpose> 7951</refnamediv> 7952<refsynopsisdiv> 7953 <title>Synopsis</title> 7954 <funcsynopsis><funcprototype> 7955 <funcdef>void <function>usb_buffer_dmasync </function></funcdef> 7956 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 7957 </funcprototype></funcsynopsis> 7958</refsynopsisdiv> 7959<refsect1> 7960 <title>Arguments</title> 7961 <variablelist> 7962 <varlistentry> 7963 <term><parameter>urb</parameter></term> 7964 <listitem> 7965 <para> 7966 urb whose transfer_buffer/setup_packet will be synchronized 7967 </para> 7968 </listitem> 7969 </varlistentry> 7970 </variablelist> 7971</refsect1> 7972</refentry> 7973 7974<refentry id="API-usb-buffer-unmap"> 7975<refentryinfo> 7976 <title>LINUX</title> 7977 <productname>Kernel Hackers Manual</productname> 7978 <date>July 2017</date> 7979</refentryinfo> 7980<refmeta> 7981 <refentrytitle><phrase>usb_buffer_unmap</phrase></refentrytitle> 7982 <manvolnum>9</manvolnum> 7983 <refmiscinfo class="version">4.1.27</refmiscinfo> 7984</refmeta> 7985<refnamediv> 7986 <refname>usb_buffer_unmap</refname> 7987 <refpurpose> 7988 free DMA mapping(s) for an urb 7989 </refpurpose> 7990</refnamediv> 7991<refsynopsisdiv> 7992 <title>Synopsis</title> 7993 <funcsynopsis><funcprototype> 7994 <funcdef>void <function>usb_buffer_unmap </function></funcdef> 7995 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 7996 </funcprototype></funcsynopsis> 7997</refsynopsisdiv> 7998<refsect1> 7999 <title>Arguments</title> 8000 <variablelist> 8001 <varlistentry> 8002 <term><parameter>urb</parameter></term> 8003 <listitem> 8004 <para> 8005 urb whose transfer_buffer will be unmapped 8006 </para> 8007 </listitem> 8008 </varlistentry> 8009 </variablelist> 8010</refsect1> 8011<refsect1> 8012<title>Description</title> 8013<para> 8014 Reverses the effect of <function>usb_buffer_map</function>. 8015</para> 8016</refsect1> 8017</refentry> 8018 8019<refentry id="API-usb-buffer-map-sg"> 8020<refentryinfo> 8021 <title>LINUX</title> 8022 <productname>Kernel Hackers Manual</productname> 8023 <date>July 2017</date> 8024</refentryinfo> 8025<refmeta> 8026 <refentrytitle><phrase>usb_buffer_map_sg</phrase></refentrytitle> 8027 <manvolnum>9</manvolnum> 8028 <refmiscinfo class="version">4.1.27</refmiscinfo> 8029</refmeta> 8030<refnamediv> 8031 <refname>usb_buffer_map_sg</refname> 8032 <refpurpose> 8033 create scatterlist DMA mapping(s) for an endpoint 8034 </refpurpose> 8035</refnamediv> 8036<refsynopsisdiv> 8037 <title>Synopsis</title> 8038 <funcsynopsis><funcprototype> 8039 <funcdef>int <function>usb_buffer_map_sg </function></funcdef> 8040 <paramdef>const struct usb_device * <parameter>dev</parameter></paramdef> 8041 <paramdef>int <parameter>is_in</parameter></paramdef> 8042 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 8043 <paramdef>int <parameter>nents</parameter></paramdef> 8044 </funcprototype></funcsynopsis> 8045</refsynopsisdiv> 8046<refsect1> 8047 <title>Arguments</title> 8048 <variablelist> 8049 <varlistentry> 8050 <term><parameter>dev</parameter></term> 8051 <listitem> 8052 <para> 8053 device to which the scatterlist will be mapped 8054 </para> 8055 </listitem> 8056 </varlistentry> 8057 <varlistentry> 8058 <term><parameter>is_in</parameter></term> 8059 <listitem> 8060 <para> 8061 mapping transfer direction 8062 </para> 8063 </listitem> 8064 </varlistentry> 8065 <varlistentry> 8066 <term><parameter>sg</parameter></term> 8067 <listitem> 8068 <para> 8069 the scatterlist to map 8070 </para> 8071 </listitem> 8072 </varlistentry> 8073 <varlistentry> 8074 <term><parameter>nents</parameter></term> 8075 <listitem> 8076 <para> 8077 the number of entries in the scatterlist 8078 </para> 8079 </listitem> 8080 </varlistentry> 8081 </variablelist> 8082</refsect1> 8083<refsect1> 8084<title>Return</title> 8085<para> 8086 Either < 0 (indicating no buffers could be mapped), or the 8087 number of DMA mapping array entries in the scatterlist. 8088</para> 8089</refsect1> 8090<refsect1> 8091<title>Note</title> 8092<para> 8093 The caller is responsible for placing the resulting DMA addresses from 8094 the scatterlist into URB transfer buffer pointers, and for setting the 8095 URB_NO_TRANSFER_DMA_MAP transfer flag in each of those URBs. 8096 </para><para> 8097 8098 Top I/O rates come from queuing URBs, instead of waiting for each one 8099 to complete before starting the next I/O. This is particularly easy 8100 to do with scatterlists. Just allocate and submit one URB for each DMA 8101 mapping entry returned, stopping on the first error or when all succeed. 8102 Better yet, use the usb_sg_*() calls, which do that (and more) for you. 8103 </para><para> 8104 8105 This call would normally be used when translating scatterlist requests, 8106 rather than <function>usb_buffer_map</function>, since on some hardware (with IOMMUs) it 8107 may be able to coalesce mappings for improved I/O efficiency. 8108 </para><para> 8109 8110 Reverse the effect of this call with <function>usb_buffer_unmap_sg</function>. 8111</para> 8112</refsect1> 8113</refentry> 8114 8115<refentry id="API-usb-buffer-dmasync-sg"> 8116<refentryinfo> 8117 <title>LINUX</title> 8118 <productname>Kernel Hackers Manual</productname> 8119 <date>July 2017</date> 8120</refentryinfo> 8121<refmeta> 8122 <refentrytitle><phrase>usb_buffer_dmasync_sg</phrase></refentrytitle> 8123 <manvolnum>9</manvolnum> 8124 <refmiscinfo class="version">4.1.27</refmiscinfo> 8125</refmeta> 8126<refnamediv> 8127 <refname>usb_buffer_dmasync_sg</refname> 8128 <refpurpose> 8129 synchronize DMA and CPU view of scatterlist buffer(s) 8130 </refpurpose> 8131</refnamediv> 8132<refsynopsisdiv> 8133 <title>Synopsis</title> 8134 <funcsynopsis><funcprototype> 8135 <funcdef>void <function>usb_buffer_dmasync_sg </function></funcdef> 8136 <paramdef>const struct usb_device * <parameter>dev</parameter></paramdef> 8137 <paramdef>int <parameter>is_in</parameter></paramdef> 8138 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 8139 <paramdef>int <parameter>n_hw_ents</parameter></paramdef> 8140 </funcprototype></funcsynopsis> 8141</refsynopsisdiv> 8142<refsect1> 8143 <title>Arguments</title> 8144 <variablelist> 8145 <varlistentry> 8146 <term><parameter>dev</parameter></term> 8147 <listitem> 8148 <para> 8149 device to which the scatterlist will be mapped 8150 </para> 8151 </listitem> 8152 </varlistentry> 8153 <varlistentry> 8154 <term><parameter>is_in</parameter></term> 8155 <listitem> 8156 <para> 8157 mapping transfer direction 8158 </para> 8159 </listitem> 8160 </varlistentry> 8161 <varlistentry> 8162 <term><parameter>sg</parameter></term> 8163 <listitem> 8164 <para> 8165 the scatterlist to synchronize 8166 </para> 8167 </listitem> 8168 </varlistentry> 8169 <varlistentry> 8170 <term><parameter>n_hw_ents</parameter></term> 8171 <listitem> 8172 <para> 8173 the positive return value from usb_buffer_map_sg 8174 </para> 8175 </listitem> 8176 </varlistentry> 8177 </variablelist> 8178</refsect1> 8179<refsect1> 8180<title>Description</title> 8181<para> 8182 Use this when you are re-using a scatterlist's data buffers for 8183 another USB request. 8184</para> 8185</refsect1> 8186</refentry> 8187 8188<refentry id="API-usb-buffer-unmap-sg"> 8189<refentryinfo> 8190 <title>LINUX</title> 8191 <productname>Kernel Hackers Manual</productname> 8192 <date>July 2017</date> 8193</refentryinfo> 8194<refmeta> 8195 <refentrytitle><phrase>usb_buffer_unmap_sg</phrase></refentrytitle> 8196 <manvolnum>9</manvolnum> 8197 <refmiscinfo class="version">4.1.27</refmiscinfo> 8198</refmeta> 8199<refnamediv> 8200 <refname>usb_buffer_unmap_sg</refname> 8201 <refpurpose> 8202 free DMA mapping(s) for a scatterlist 8203 </refpurpose> 8204</refnamediv> 8205<refsynopsisdiv> 8206 <title>Synopsis</title> 8207 <funcsynopsis><funcprototype> 8208 <funcdef>void <function>usb_buffer_unmap_sg </function></funcdef> 8209 <paramdef>const struct usb_device * <parameter>dev</parameter></paramdef> 8210 <paramdef>int <parameter>is_in</parameter></paramdef> 8211 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 8212 <paramdef>int <parameter>n_hw_ents</parameter></paramdef> 8213 </funcprototype></funcsynopsis> 8214</refsynopsisdiv> 8215<refsect1> 8216 <title>Arguments</title> 8217 <variablelist> 8218 <varlistentry> 8219 <term><parameter>dev</parameter></term> 8220 <listitem> 8221 <para> 8222 device to which the scatterlist will be mapped 8223 </para> 8224 </listitem> 8225 </varlistentry> 8226 <varlistentry> 8227 <term><parameter>is_in</parameter></term> 8228 <listitem> 8229 <para> 8230 mapping transfer direction 8231 </para> 8232 </listitem> 8233 </varlistentry> 8234 <varlistentry> 8235 <term><parameter>sg</parameter></term> 8236 <listitem> 8237 <para> 8238 the scatterlist to unmap 8239 </para> 8240 </listitem> 8241 </varlistentry> 8242 <varlistentry> 8243 <term><parameter>n_hw_ents</parameter></term> 8244 <listitem> 8245 <para> 8246 the positive return value from usb_buffer_map_sg 8247 </para> 8248 </listitem> 8249 </varlistentry> 8250 </variablelist> 8251</refsect1> 8252<refsect1> 8253<title>Description</title> 8254<para> 8255 Reverses the effect of <function>usb_buffer_map_sg</function>. 8256</para> 8257</refsect1> 8258</refentry> 8259 8260<!-- drivers/usb/core/hub.c --> 8261<refentry id="API-usb-hub-clear-tt-buffer"> 8262<refentryinfo> 8263 <title>LINUX</title> 8264 <productname>Kernel Hackers Manual</productname> 8265 <date>July 2017</date> 8266</refentryinfo> 8267<refmeta> 8268 <refentrytitle><phrase>usb_hub_clear_tt_buffer</phrase></refentrytitle> 8269 <manvolnum>9</manvolnum> 8270 <refmiscinfo class="version">4.1.27</refmiscinfo> 8271</refmeta> 8272<refnamediv> 8273 <refname>usb_hub_clear_tt_buffer</refname> 8274 <refpurpose> 8275 clear control/bulk TT state in high speed hub 8276 </refpurpose> 8277</refnamediv> 8278<refsynopsisdiv> 8279 <title>Synopsis</title> 8280 <funcsynopsis><funcprototype> 8281 <funcdef>int <function>usb_hub_clear_tt_buffer </function></funcdef> 8282 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 8283 </funcprototype></funcsynopsis> 8284</refsynopsisdiv> 8285<refsect1> 8286 <title>Arguments</title> 8287 <variablelist> 8288 <varlistentry> 8289 <term><parameter>urb</parameter></term> 8290 <listitem> 8291 <para> 8292 an URB associated with the failed or incomplete split transaction 8293 </para> 8294 </listitem> 8295 </varlistentry> 8296 </variablelist> 8297</refsect1> 8298<refsect1> 8299<title>Description</title> 8300<para> 8301 High speed HCDs use this to tell the hub driver that some split control or 8302 bulk transaction failed in a way that requires clearing internal state of 8303 a transaction translator. This is normally detected (and reported) from 8304 interrupt context. 8305 </para><para> 8306 8307 It may not be possible for that hub to handle additional full (or low) 8308 speed transactions until that state is fully cleared out. 8309</para> 8310</refsect1> 8311<refsect1> 8312<title>Return</title> 8313<para> 8314 0 if successful. A negative error code otherwise. 8315</para> 8316</refsect1> 8317</refentry> 8318 8319<refentry id="API-usb-set-device-state"> 8320<refentryinfo> 8321 <title>LINUX</title> 8322 <productname>Kernel Hackers Manual</productname> 8323 <date>July 2017</date> 8324</refentryinfo> 8325<refmeta> 8326 <refentrytitle><phrase>usb_set_device_state</phrase></refentrytitle> 8327 <manvolnum>9</manvolnum> 8328 <refmiscinfo class="version">4.1.27</refmiscinfo> 8329</refmeta> 8330<refnamediv> 8331 <refname>usb_set_device_state</refname> 8332 <refpurpose> 8333 change a device's current state (usbcore, hcds) 8334 </refpurpose> 8335</refnamediv> 8336<refsynopsisdiv> 8337 <title>Synopsis</title> 8338 <funcsynopsis><funcprototype> 8339 <funcdef>void <function>usb_set_device_state </function></funcdef> 8340 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 8341 <paramdef>enum usb_device_state <parameter>new_state</parameter></paramdef> 8342 </funcprototype></funcsynopsis> 8343</refsynopsisdiv> 8344<refsect1> 8345 <title>Arguments</title> 8346 <variablelist> 8347 <varlistentry> 8348 <term><parameter>udev</parameter></term> 8349 <listitem> 8350 <para> 8351 pointer to device whose state should be changed 8352 </para> 8353 </listitem> 8354 </varlistentry> 8355 <varlistentry> 8356 <term><parameter>new_state</parameter></term> 8357 <listitem> 8358 <para> 8359 new state value to be stored 8360 </para> 8361 </listitem> 8362 </varlistentry> 8363 </variablelist> 8364</refsect1> 8365<refsect1> 8366<title>Description</title> 8367<para> 8368 udev->state is _not_ fully protected by the device lock. Although 8369 most transitions are made only while holding the lock, the state can 8370 can change to USB_STATE_NOTATTACHED at almost any time. This 8371 is so that devices can be marked as disconnected as soon as possible, 8372 without having to wait for any semaphores to be released. As a result, 8373 all changes to any device's state must be protected by the 8374 device_state_lock spinlock. 8375 </para><para> 8376 8377 Once a device has been added to the device tree, all changes to its state 8378 should be made using this routine. The state should _not_ be set directly. 8379 </para><para> 8380 8381 If udev->state is already USB_STATE_NOTATTACHED then no change is made. 8382 Otherwise udev->state is set to new_state, and if new_state is 8383 USB_STATE_NOTATTACHED then all of udev's descendants' states are also set 8384 to USB_STATE_NOTATTACHED. 8385</para> 8386</refsect1> 8387</refentry> 8388 8389<refentry id="API-usb-root-hub-lost-power"> 8390<refentryinfo> 8391 <title>LINUX</title> 8392 <productname>Kernel Hackers Manual</productname> 8393 <date>July 2017</date> 8394</refentryinfo> 8395<refmeta> 8396 <refentrytitle><phrase>usb_root_hub_lost_power</phrase></refentrytitle> 8397 <manvolnum>9</manvolnum> 8398 <refmiscinfo class="version">4.1.27</refmiscinfo> 8399</refmeta> 8400<refnamediv> 8401 <refname>usb_root_hub_lost_power</refname> 8402 <refpurpose> 8403 called by HCD if the root hub lost Vbus power 8404 </refpurpose> 8405</refnamediv> 8406<refsynopsisdiv> 8407 <title>Synopsis</title> 8408 <funcsynopsis><funcprototype> 8409 <funcdef>void <function>usb_root_hub_lost_power </function></funcdef> 8410 <paramdef>struct usb_device * <parameter>rhdev</parameter></paramdef> 8411 </funcprototype></funcsynopsis> 8412</refsynopsisdiv> 8413<refsect1> 8414 <title>Arguments</title> 8415 <variablelist> 8416 <varlistentry> 8417 <term><parameter>rhdev</parameter></term> 8418 <listitem> 8419 <para> 8420 struct usb_device for the root hub 8421 </para> 8422 </listitem> 8423 </varlistentry> 8424 </variablelist> 8425</refsect1> 8426<refsect1> 8427<title>Description</title> 8428<para> 8429 The USB host controller driver calls this function when its root hub 8430 is resumed and Vbus power has been interrupted or the controller 8431 has been reset. The routine marks <parameter>rhdev</parameter> as having lost power. 8432 When the hub driver is resumed it will take notice and carry out 8433 power-session recovery for all the <quote>USB-PERSIST</quote>-enabled child devices; 8434 the others will be disconnected. 8435</para> 8436</refsect1> 8437</refentry> 8438 8439<refentry id="API-usb-reset-device"> 8440<refentryinfo> 8441 <title>LINUX</title> 8442 <productname>Kernel Hackers Manual</productname> 8443 <date>July 2017</date> 8444</refentryinfo> 8445<refmeta> 8446 <refentrytitle><phrase>usb_reset_device</phrase></refentrytitle> 8447 <manvolnum>9</manvolnum> 8448 <refmiscinfo class="version">4.1.27</refmiscinfo> 8449</refmeta> 8450<refnamediv> 8451 <refname>usb_reset_device</refname> 8452 <refpurpose> 8453 warn interface drivers and perform a USB port reset 8454 </refpurpose> 8455</refnamediv> 8456<refsynopsisdiv> 8457 <title>Synopsis</title> 8458 <funcsynopsis><funcprototype> 8459 <funcdef>int <function>usb_reset_device </function></funcdef> 8460 <paramdef>struct usb_device * <parameter>udev</parameter></paramdef> 8461 </funcprototype></funcsynopsis> 8462</refsynopsisdiv> 8463<refsect1> 8464 <title>Arguments</title> 8465 <variablelist> 8466 <varlistentry> 8467 <term><parameter>udev</parameter></term> 8468 <listitem> 8469 <para> 8470 device to reset (not in SUSPENDED or NOTATTACHED state) 8471 </para> 8472 </listitem> 8473 </varlistentry> 8474 </variablelist> 8475</refsect1> 8476<refsect1> 8477<title>Description</title> 8478<para> 8479 Warns all drivers bound to registered interfaces (using their pre_reset 8480 method), performs the port reset, and then lets the drivers know that 8481 the reset is over (using their post_reset method). 8482</para> 8483</refsect1> 8484<refsect1> 8485<title>Return</title> 8486<para> 8487 The same as for <function>usb_reset_and_verify_device</function>. 8488</para> 8489</refsect1> 8490<refsect1> 8491<title>Note</title> 8492<para> 8493 The caller must own the device lock. For example, it's safe to use 8494 this from a driver <function>probe</function> routine after downloading new firmware. 8495 For calls that might not occur during <function>probe</function>, drivers should lock 8496 the device using <function>usb_lock_device_for_reset</function>. 8497 </para><para> 8498 8499 If an interface is currently being probed or disconnected, we assume 8500 its driver knows how to handle resets. For all other interfaces, 8501 if the driver doesn't have pre_reset and post_reset methods then 8502 we attempt to unbind it and rebind afterward. 8503</para> 8504</refsect1> 8505</refentry> 8506 8507<refentry id="API-usb-queue-reset-device"> 8508<refentryinfo> 8509 <title>LINUX</title> 8510 <productname>Kernel Hackers Manual</productname> 8511 <date>July 2017</date> 8512</refentryinfo> 8513<refmeta> 8514 <refentrytitle><phrase>usb_queue_reset_device</phrase></refentrytitle> 8515 <manvolnum>9</manvolnum> 8516 <refmiscinfo class="version">4.1.27</refmiscinfo> 8517</refmeta> 8518<refnamediv> 8519 <refname>usb_queue_reset_device</refname> 8520 <refpurpose> 8521 Reset a USB device from an atomic context 8522 </refpurpose> 8523</refnamediv> 8524<refsynopsisdiv> 8525 <title>Synopsis</title> 8526 <funcsynopsis><funcprototype> 8527 <funcdef>void <function>usb_queue_reset_device </function></funcdef> 8528 <paramdef>struct usb_interface * <parameter>iface</parameter></paramdef> 8529 </funcprototype></funcsynopsis> 8530</refsynopsisdiv> 8531<refsect1> 8532 <title>Arguments</title> 8533 <variablelist> 8534 <varlistentry> 8535 <term><parameter>iface</parameter></term> 8536 <listitem> 8537 <para> 8538 USB interface belonging to the device to reset 8539 </para> 8540 </listitem> 8541 </varlistentry> 8542 </variablelist> 8543</refsect1> 8544<refsect1> 8545<title>Description</title> 8546<para> 8547 This function can be used to reset a USB device from an atomic 8548 context, where <function>usb_reset_device</function> won't work (as it blocks). 8549 </para><para> 8550 8551 Doing a reset via this method is functionally equivalent to calling 8552 <function>usb_reset_device</function>, except for the fact that it is delayed to a 8553 workqueue. This means that any drivers bound to other interfaces 8554 might be unbound, as well as users from usbfs in user space. 8555</para> 8556</refsect1> 8557<refsect1> 8558<title>Corner cases</title> 8559<para> 8560 </para><para> 8561 8562 - Scheduling two resets at the same time from two different drivers 8563 attached to two different interfaces of the same device is 8564 possible; depending on how the driver attached to each interface 8565 handles -><function>pre_reset</function>, the second reset might happen or not. 8566 </para><para> 8567 8568 - If the reset is delayed so long that the interface is unbound from 8569 its driver, the reset will be skipped. 8570 </para><para> 8571 8572 - This function can be called during .<function>probe</function>. It can also be called 8573 during .<function>disconnect</function>, but doing so is pointless because the reset 8574 will not occur. If you really want to reset the device during 8575 .<function>disconnect</function>, call <function>usb_reset_device</function> directly -- but watch out 8576 for nested unbinding issues! 8577</para> 8578</refsect1> 8579</refentry> 8580 8581<refentry id="API-usb-hub-find-child"> 8582<refentryinfo> 8583 <title>LINUX</title> 8584 <productname>Kernel Hackers Manual</productname> 8585 <date>July 2017</date> 8586</refentryinfo> 8587<refmeta> 8588 <refentrytitle><phrase>usb_hub_find_child</phrase></refentrytitle> 8589 <manvolnum>9</manvolnum> 8590 <refmiscinfo class="version">4.1.27</refmiscinfo> 8591</refmeta> 8592<refnamediv> 8593 <refname>usb_hub_find_child</refname> 8594 <refpurpose> 8595 Get the pointer of child device attached to the port which is specified by <parameter>port1</parameter>. 8596 </refpurpose> 8597</refnamediv> 8598<refsynopsisdiv> 8599 <title>Synopsis</title> 8600 <funcsynopsis><funcprototype> 8601 <funcdef>struct usb_device * <function>usb_hub_find_child </function></funcdef> 8602 <paramdef>struct usb_device * <parameter>hdev</parameter></paramdef> 8603 <paramdef>int <parameter>port1</parameter></paramdef> 8604 </funcprototype></funcsynopsis> 8605</refsynopsisdiv> 8606<refsect1> 8607 <title>Arguments</title> 8608 <variablelist> 8609 <varlistentry> 8610 <term><parameter>hdev</parameter></term> 8611 <listitem> 8612 <para> 8613 USB device belonging to the usb hub 8614 </para> 8615 </listitem> 8616 </varlistentry> 8617 <varlistentry> 8618 <term><parameter>port1</parameter></term> 8619 <listitem> 8620 <para> 8621 port num to indicate which port the child device 8622 is attached to. 8623 </para> 8624 </listitem> 8625 </varlistentry> 8626 </variablelist> 8627</refsect1> 8628<refsect1> 8629<title>Description</title> 8630<para> 8631 USB drivers call this function to get hub's child device 8632 pointer. 8633</para> 8634</refsect1> 8635<refsect1> 8636<title>Return</title> 8637<para> 8638 <constant>NULL</constant> if input param is invalid and 8639 child's usb_device pointer if non-NULL. 8640</para> 8641</refsect1> 8642</refentry> 8643 8644 </chapter> 8645 8646 <chapter id="hcd"><title>Host Controller APIs</title> 8647 8648 <para>These APIs are only for use by host controller drivers, 8649 most of which implement standard register interfaces such as 8650 EHCI, OHCI, or UHCI. 8651 UHCI was one of the first interfaces, designed by Intel and 8652 also used by VIA; it doesn't do much in hardware. 8653 OHCI was designed later, to have the hardware do more work 8654 (bigger transfers, tracking protocol state, and so on). 8655 EHCI was designed with USB 2.0; its design has features that 8656 resemble OHCI (hardware does much more work) as well as 8657 UHCI (some parts of ISO support, TD list processing). 8658 </para> 8659 8660 <para>There are host controllers other than the "big three", 8661 although most PCI based controllers (and a few non-PCI based 8662 ones) use one of those interfaces. 8663 Not all host controllers use DMA; some use PIO, and there 8664 is also a simulator. 8665 </para> 8666 8667 <para>The same basic APIs are available to drivers for all 8668 those controllers. 8669 For historical reasons they are in two layers: 8670 <structname>struct usb_bus</structname> is a rather thin 8671 layer that became available in the 2.2 kernels, while 8672 <structname>struct usb_hcd</structname> is a more featureful 8673 layer (available in later 2.4 kernels and in 2.5) that 8674 lets HCDs share common code, to shrink driver size 8675 and significantly reduce hcd-specific behaviors. 8676 </para> 8677 8678<!-- drivers/usb/core/hcd.c --> 8679<refentry id="API-usb-calc-bus-time"> 8680<refentryinfo> 8681 <title>LINUX</title> 8682 <productname>Kernel Hackers Manual</productname> 8683 <date>July 2017</date> 8684</refentryinfo> 8685<refmeta> 8686 <refentrytitle><phrase>usb_calc_bus_time</phrase></refentrytitle> 8687 <manvolnum>9</manvolnum> 8688 <refmiscinfo class="version">4.1.27</refmiscinfo> 8689</refmeta> 8690<refnamediv> 8691 <refname>usb_calc_bus_time</refname> 8692 <refpurpose> 8693 approximate periodic transaction time in nanoseconds 8694 </refpurpose> 8695</refnamediv> 8696<refsynopsisdiv> 8697 <title>Synopsis</title> 8698 <funcsynopsis><funcprototype> 8699 <funcdef>long <function>usb_calc_bus_time </function></funcdef> 8700 <paramdef>int <parameter>speed</parameter></paramdef> 8701 <paramdef>int <parameter>is_input</parameter></paramdef> 8702 <paramdef>int <parameter>isoc</parameter></paramdef> 8703 <paramdef>int <parameter>bytecount</parameter></paramdef> 8704 </funcprototype></funcsynopsis> 8705</refsynopsisdiv> 8706<refsect1> 8707 <title>Arguments</title> 8708 <variablelist> 8709 <varlistentry> 8710 <term><parameter>speed</parameter></term> 8711 <listitem> 8712 <para> 8713 from dev->speed; USB_SPEED_{LOW,FULL,HIGH} 8714 </para> 8715 </listitem> 8716 </varlistentry> 8717 <varlistentry> 8718 <term><parameter>is_input</parameter></term> 8719 <listitem> 8720 <para> 8721 true iff the transaction sends data to the host 8722 </para> 8723 </listitem> 8724 </varlistentry> 8725 <varlistentry> 8726 <term><parameter>isoc</parameter></term> 8727 <listitem> 8728 <para> 8729 true for isochronous transactions, false for interrupt ones 8730 </para> 8731 </listitem> 8732 </varlistentry> 8733 <varlistentry> 8734 <term><parameter>bytecount</parameter></term> 8735 <listitem> 8736 <para> 8737 how many bytes in the transaction. 8738 </para> 8739 </listitem> 8740 </varlistentry> 8741 </variablelist> 8742</refsect1> 8743<refsect1> 8744<title>Return</title> 8745<para> 8746 Approximate bus time in nanoseconds for a periodic transaction. 8747</para> 8748</refsect1> 8749<refsect1> 8750<title>Note</title> 8751<para> 8752 See USB 2.0 spec section 5.11.3; only periodic transfers need to be 8753 scheduled in software, this function is only used for such scheduling. 8754</para> 8755</refsect1> 8756</refentry> 8757 8758<refentry id="API-usb-hcd-link-urb-to-ep"> 8759<refentryinfo> 8760 <title>LINUX</title> 8761 <productname>Kernel Hackers Manual</productname> 8762 <date>July 2017</date> 8763</refentryinfo> 8764<refmeta> 8765 <refentrytitle><phrase>usb_hcd_link_urb_to_ep</phrase></refentrytitle> 8766 <manvolnum>9</manvolnum> 8767 <refmiscinfo class="version">4.1.27</refmiscinfo> 8768</refmeta> 8769<refnamediv> 8770 <refname>usb_hcd_link_urb_to_ep</refname> 8771 <refpurpose> 8772 add an URB to its endpoint queue 8773 </refpurpose> 8774</refnamediv> 8775<refsynopsisdiv> 8776 <title>Synopsis</title> 8777 <funcsynopsis><funcprototype> 8778 <funcdef>int <function>usb_hcd_link_urb_to_ep </function></funcdef> 8779 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 8780 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 8781 </funcprototype></funcsynopsis> 8782</refsynopsisdiv> 8783<refsect1> 8784 <title>Arguments</title> 8785 <variablelist> 8786 <varlistentry> 8787 <term><parameter>hcd</parameter></term> 8788 <listitem> 8789 <para> 8790 host controller to which <parameter>urb</parameter> was submitted 8791 </para> 8792 </listitem> 8793 </varlistentry> 8794 <varlistentry> 8795 <term><parameter>urb</parameter></term> 8796 <listitem> 8797 <para> 8798 URB being submitted 8799 </para> 8800 </listitem> 8801 </varlistentry> 8802 </variablelist> 8803</refsect1> 8804<refsect1> 8805<title>Description</title> 8806<para> 8807 Host controller drivers should call this routine in their <function>enqueue</function> 8808 method. The HCD's private spinlock must be held and interrupts must 8809 be disabled. The actions carried out here are required for URB 8810 submission, as well as for endpoint shutdown and for usb_kill_urb. 8811</para> 8812</refsect1> 8813<refsect1> 8814<title>Return</title> 8815<para> 8816 0 for no error, otherwise a negative error code (in which case 8817 the <function>enqueue</function> method must fail). If no error occurs but <function>enqueue</function> fails 8818 anyway, it must call <function>usb_hcd_unlink_urb_from_ep</function> before releasing 8819 the private spinlock and returning. 8820</para> 8821</refsect1> 8822</refentry> 8823 8824<refentry id="API-usb-hcd-check-unlink-urb"> 8825<refentryinfo> 8826 <title>LINUX</title> 8827 <productname>Kernel Hackers Manual</productname> 8828 <date>July 2017</date> 8829</refentryinfo> 8830<refmeta> 8831 <refentrytitle><phrase>usb_hcd_check_unlink_urb</phrase></refentrytitle> 8832 <manvolnum>9</manvolnum> 8833 <refmiscinfo class="version">4.1.27</refmiscinfo> 8834</refmeta> 8835<refnamediv> 8836 <refname>usb_hcd_check_unlink_urb</refname> 8837 <refpurpose> 8838 check whether an URB may be unlinked 8839 </refpurpose> 8840</refnamediv> 8841<refsynopsisdiv> 8842 <title>Synopsis</title> 8843 <funcsynopsis><funcprototype> 8844 <funcdef>int <function>usb_hcd_check_unlink_urb </function></funcdef> 8845 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 8846 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 8847 <paramdef>int <parameter>status</parameter></paramdef> 8848 </funcprototype></funcsynopsis> 8849</refsynopsisdiv> 8850<refsect1> 8851 <title>Arguments</title> 8852 <variablelist> 8853 <varlistentry> 8854 <term><parameter>hcd</parameter></term> 8855 <listitem> 8856 <para> 8857 host controller to which <parameter>urb</parameter> was submitted 8858 </para> 8859 </listitem> 8860 </varlistentry> 8861 <varlistentry> 8862 <term><parameter>urb</parameter></term> 8863 <listitem> 8864 <para> 8865 URB being checked for unlinkability 8866 </para> 8867 </listitem> 8868 </varlistentry> 8869 <varlistentry> 8870 <term><parameter>status</parameter></term> 8871 <listitem> 8872 <para> 8873 error code to store in <parameter>urb</parameter> if the unlink succeeds 8874 </para> 8875 </listitem> 8876 </varlistentry> 8877 </variablelist> 8878</refsect1> 8879<refsect1> 8880<title>Description</title> 8881<para> 8882 Host controller drivers should call this routine in their <function>dequeue</function> 8883 method. The HCD's private spinlock must be held and interrupts must 8884 be disabled. The actions carried out here are required for making 8885 sure than an unlink is valid. 8886</para> 8887</refsect1> 8888<refsect1> 8889<title>Return</title> 8890<para> 8891 0 for no error, otherwise a negative error code (in which case 8892 the <function>dequeue</function> method must fail). The possible error codes are: 8893 </para><para> 8894 8895 -EIDRM: <parameter>urb</parameter> was not submitted or has already completed. 8896 The completion function may not have been called yet. 8897 </para><para> 8898 8899 -EBUSY: <parameter>urb</parameter> has already been unlinked. 8900</para> 8901</refsect1> 8902</refentry> 8903 8904<refentry id="API-usb-hcd-unlink-urb-from-ep"> 8905<refentryinfo> 8906 <title>LINUX</title> 8907 <productname>Kernel Hackers Manual</productname> 8908 <date>July 2017</date> 8909</refentryinfo> 8910<refmeta> 8911 <refentrytitle><phrase>usb_hcd_unlink_urb_from_ep</phrase></refentrytitle> 8912 <manvolnum>9</manvolnum> 8913 <refmiscinfo class="version">4.1.27</refmiscinfo> 8914</refmeta> 8915<refnamediv> 8916 <refname>usb_hcd_unlink_urb_from_ep</refname> 8917 <refpurpose> 8918 remove an URB from its endpoint queue 8919 </refpurpose> 8920</refnamediv> 8921<refsynopsisdiv> 8922 <title>Synopsis</title> 8923 <funcsynopsis><funcprototype> 8924 <funcdef>void <function>usb_hcd_unlink_urb_from_ep </function></funcdef> 8925 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 8926 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 8927 </funcprototype></funcsynopsis> 8928</refsynopsisdiv> 8929<refsect1> 8930 <title>Arguments</title> 8931 <variablelist> 8932 <varlistentry> 8933 <term><parameter>hcd</parameter></term> 8934 <listitem> 8935 <para> 8936 host controller to which <parameter>urb</parameter> was submitted 8937 </para> 8938 </listitem> 8939 </varlistentry> 8940 <varlistentry> 8941 <term><parameter>urb</parameter></term> 8942 <listitem> 8943 <para> 8944 URB being unlinked 8945 </para> 8946 </listitem> 8947 </varlistentry> 8948 </variablelist> 8949</refsect1> 8950<refsect1> 8951<title>Description</title> 8952<para> 8953 Host controller drivers should call this routine before calling 8954 <function>usb_hcd_giveback_urb</function>. The HCD's private spinlock must be held and 8955 interrupts must be disabled. The actions carried out here are required 8956 for URB completion. 8957</para> 8958</refsect1> 8959</refentry> 8960 8961<refentry id="API-usb-hcd-giveback-urb"> 8962<refentryinfo> 8963 <title>LINUX</title> 8964 <productname>Kernel Hackers Manual</productname> 8965 <date>July 2017</date> 8966</refentryinfo> 8967<refmeta> 8968 <refentrytitle><phrase>usb_hcd_giveback_urb</phrase></refentrytitle> 8969 <manvolnum>9</manvolnum> 8970 <refmiscinfo class="version">4.1.27</refmiscinfo> 8971</refmeta> 8972<refnamediv> 8973 <refname>usb_hcd_giveback_urb</refname> 8974 <refpurpose> 8975 return URB from HCD to device driver 8976 </refpurpose> 8977</refnamediv> 8978<refsynopsisdiv> 8979 <title>Synopsis</title> 8980 <funcsynopsis><funcprototype> 8981 <funcdef>void <function>usb_hcd_giveback_urb </function></funcdef> 8982 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 8983 <paramdef>struct urb * <parameter>urb</parameter></paramdef> 8984 <paramdef>int <parameter>status</parameter></paramdef> 8985 </funcprototype></funcsynopsis> 8986</refsynopsisdiv> 8987<refsect1> 8988 <title>Arguments</title> 8989 <variablelist> 8990 <varlistentry> 8991 <term><parameter>hcd</parameter></term> 8992 <listitem> 8993 <para> 8994 host controller returning the URB 8995 </para> 8996 </listitem> 8997 </varlistentry> 8998 <varlistentry> 8999 <term><parameter>urb</parameter></term> 9000 <listitem> 9001 <para> 9002 urb being returned to the USB device driver. 9003 </para> 9004 </listitem> 9005 </varlistentry> 9006 <varlistentry> 9007 <term><parameter>status</parameter></term> 9008 <listitem> 9009 <para> 9010 completion status code for the URB. 9011 </para> 9012 </listitem> 9013 </varlistentry> 9014 </variablelist> 9015</refsect1> 9016<refsect1> 9017<title>Context</title> 9018<para> 9019 <function>in_interrupt</function> 9020</para> 9021</refsect1> 9022<refsect1> 9023<title>Description</title> 9024<para> 9025 This hands the URB from HCD to its USB device driver, using its 9026 completion function. The HCD has freed all per-urb resources 9027 (and is done using urb->hcpriv). It also released all HCD locks; 9028 the device driver won't cause problems if it frees, modifies, 9029 or resubmits this URB. 9030 </para><para> 9031 9032 If <parameter>urb</parameter> was unlinked, the value of <parameter>status</parameter> will be overridden by 9033 <parameter>urb</parameter>->unlinked. Erroneous short transfers are detected in case 9034 the HCD hasn't checked for them. 9035</para> 9036</refsect1> 9037</refentry> 9038 9039<refentry id="API-usb-alloc-streams"> 9040<refentryinfo> 9041 <title>LINUX</title> 9042 <productname>Kernel Hackers Manual</productname> 9043 <date>July 2017</date> 9044</refentryinfo> 9045<refmeta> 9046 <refentrytitle><phrase>usb_alloc_streams</phrase></refentrytitle> 9047 <manvolnum>9</manvolnum> 9048 <refmiscinfo class="version">4.1.27</refmiscinfo> 9049</refmeta> 9050<refnamediv> 9051 <refname>usb_alloc_streams</refname> 9052 <refpurpose> 9053 allocate bulk endpoint stream IDs. 9054 </refpurpose> 9055</refnamediv> 9056<refsynopsisdiv> 9057 <title>Synopsis</title> 9058 <funcsynopsis><funcprototype> 9059 <funcdef>int <function>usb_alloc_streams </function></funcdef> 9060 <paramdef>struct usb_interface * <parameter>interface</parameter></paramdef> 9061 <paramdef>struct usb_host_endpoint ** <parameter>eps</parameter></paramdef> 9062 <paramdef>unsigned int <parameter>num_eps</parameter></paramdef> 9063 <paramdef>unsigned int <parameter>num_streams</parameter></paramdef> 9064 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 9065 </funcprototype></funcsynopsis> 9066</refsynopsisdiv> 9067<refsect1> 9068 <title>Arguments</title> 9069 <variablelist> 9070 <varlistentry> 9071 <term><parameter>interface</parameter></term> 9072 <listitem> 9073 <para> 9074 alternate setting that includes all endpoints. 9075 </para> 9076 </listitem> 9077 </varlistentry> 9078 <varlistentry> 9079 <term><parameter>eps</parameter></term> 9080 <listitem> 9081 <para> 9082 array of endpoints that need streams. 9083 </para> 9084 </listitem> 9085 </varlistentry> 9086 <varlistentry> 9087 <term><parameter>num_eps</parameter></term> 9088 <listitem> 9089 <para> 9090 number of endpoints in the array. 9091 </para> 9092 </listitem> 9093 </varlistentry> 9094 <varlistentry> 9095 <term><parameter>num_streams</parameter></term> 9096 <listitem> 9097 <para> 9098 number of streams to allocate. 9099 </para> 9100 </listitem> 9101 </varlistentry> 9102 <varlistentry> 9103 <term><parameter>mem_flags</parameter></term> 9104 <listitem> 9105 <para> 9106 flags hcd should use to allocate memory. 9107 </para> 9108 </listitem> 9109 </varlistentry> 9110 </variablelist> 9111</refsect1> 9112<refsect1> 9113<title>Description</title> 9114<para> 9115 Sets up a group of bulk endpoints to have <parameter>num_streams</parameter> stream IDs available. 9116 Drivers may queue multiple transfers to different stream IDs, which may 9117 complete in a different order than they were queued. 9118</para> 9119</refsect1> 9120<refsect1> 9121<title>Return</title> 9122<para> 9123 On success, the number of allocated streams. On failure, a negative 9124 error code. 9125</para> 9126</refsect1> 9127</refentry> 9128 9129<refentry id="API-usb-free-streams"> 9130<refentryinfo> 9131 <title>LINUX</title> 9132 <productname>Kernel Hackers Manual</productname> 9133 <date>July 2017</date> 9134</refentryinfo> 9135<refmeta> 9136 <refentrytitle><phrase>usb_free_streams</phrase></refentrytitle> 9137 <manvolnum>9</manvolnum> 9138 <refmiscinfo class="version">4.1.27</refmiscinfo> 9139</refmeta> 9140<refnamediv> 9141 <refname>usb_free_streams</refname> 9142 <refpurpose> 9143 free bulk endpoint stream IDs. 9144 </refpurpose> 9145</refnamediv> 9146<refsynopsisdiv> 9147 <title>Synopsis</title> 9148 <funcsynopsis><funcprototype> 9149 <funcdef>int <function>usb_free_streams </function></funcdef> 9150 <paramdef>struct usb_interface * <parameter>interface</parameter></paramdef> 9151 <paramdef>struct usb_host_endpoint ** <parameter>eps</parameter></paramdef> 9152 <paramdef>unsigned int <parameter>num_eps</parameter></paramdef> 9153 <paramdef>gfp_t <parameter>mem_flags</parameter></paramdef> 9154 </funcprototype></funcsynopsis> 9155</refsynopsisdiv> 9156<refsect1> 9157 <title>Arguments</title> 9158 <variablelist> 9159 <varlistentry> 9160 <term><parameter>interface</parameter></term> 9161 <listitem> 9162 <para> 9163 alternate setting that includes all endpoints. 9164 </para> 9165 </listitem> 9166 </varlistentry> 9167 <varlistentry> 9168 <term><parameter>eps</parameter></term> 9169 <listitem> 9170 <para> 9171 array of endpoints to remove streams from. 9172 </para> 9173 </listitem> 9174 </varlistentry> 9175 <varlistentry> 9176 <term><parameter>num_eps</parameter></term> 9177 <listitem> 9178 <para> 9179 number of endpoints in the array. 9180 </para> 9181 </listitem> 9182 </varlistentry> 9183 <varlistentry> 9184 <term><parameter>mem_flags</parameter></term> 9185 <listitem> 9186 <para> 9187 flags hcd should use to allocate memory. 9188 </para> 9189 </listitem> 9190 </varlistentry> 9191 </variablelist> 9192</refsect1> 9193<refsect1> 9194<title>Description</title> 9195<para> 9196 Reverts a group of bulk endpoints back to not using stream IDs. 9197 Can fail if we are given bad arguments, or HCD is broken. 9198</para> 9199</refsect1> 9200<refsect1> 9201<title>Return</title> 9202<para> 9203 0 on success. On failure, a negative error code. 9204</para> 9205</refsect1> 9206</refentry> 9207 9208<refentry id="API-usb-hcd-resume-root-hub"> 9209<refentryinfo> 9210 <title>LINUX</title> 9211 <productname>Kernel Hackers Manual</productname> 9212 <date>July 2017</date> 9213</refentryinfo> 9214<refmeta> 9215 <refentrytitle><phrase>usb_hcd_resume_root_hub</phrase></refentrytitle> 9216 <manvolnum>9</manvolnum> 9217 <refmiscinfo class="version">4.1.27</refmiscinfo> 9218</refmeta> 9219<refnamediv> 9220 <refname>usb_hcd_resume_root_hub</refname> 9221 <refpurpose> 9222 called by HCD to resume its root hub 9223 </refpurpose> 9224</refnamediv> 9225<refsynopsisdiv> 9226 <title>Synopsis</title> 9227 <funcsynopsis><funcprototype> 9228 <funcdef>void <function>usb_hcd_resume_root_hub </function></funcdef> 9229 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9230 </funcprototype></funcsynopsis> 9231</refsynopsisdiv> 9232<refsect1> 9233 <title>Arguments</title> 9234 <variablelist> 9235 <varlistentry> 9236 <term><parameter>hcd</parameter></term> 9237 <listitem> 9238 <para> 9239 host controller for this root hub 9240 </para> 9241 </listitem> 9242 </varlistentry> 9243 </variablelist> 9244</refsect1> 9245<refsect1> 9246<title>Description</title> 9247<para> 9248 The USB host controller calls this function when its root hub is 9249 suspended (with the remote wakeup feature enabled) and a remote 9250 wakeup request is received. The routine submits a workqueue request 9251 to resume the root hub (that is, manage its downstream ports again). 9252</para> 9253</refsect1> 9254</refentry> 9255 9256<refentry id="API-usb-bus-start-enum"> 9257<refentryinfo> 9258 <title>LINUX</title> 9259 <productname>Kernel Hackers Manual</productname> 9260 <date>July 2017</date> 9261</refentryinfo> 9262<refmeta> 9263 <refentrytitle><phrase>usb_bus_start_enum</phrase></refentrytitle> 9264 <manvolnum>9</manvolnum> 9265 <refmiscinfo class="version">4.1.27</refmiscinfo> 9266</refmeta> 9267<refnamediv> 9268 <refname>usb_bus_start_enum</refname> 9269 <refpurpose> 9270 start immediate enumeration (for OTG) 9271 </refpurpose> 9272</refnamediv> 9273<refsynopsisdiv> 9274 <title>Synopsis</title> 9275 <funcsynopsis><funcprototype> 9276 <funcdef>int <function>usb_bus_start_enum </function></funcdef> 9277 <paramdef>struct usb_bus * <parameter>bus</parameter></paramdef> 9278 <paramdef>unsigned <parameter>port_num</parameter></paramdef> 9279 </funcprototype></funcsynopsis> 9280</refsynopsisdiv> 9281<refsect1> 9282 <title>Arguments</title> 9283 <variablelist> 9284 <varlistentry> 9285 <term><parameter>bus</parameter></term> 9286 <listitem> 9287 <para> 9288 the bus (must use hcd framework) 9289 </para> 9290 </listitem> 9291 </varlistentry> 9292 <varlistentry> 9293 <term><parameter>port_num</parameter></term> 9294 <listitem> 9295 <para> 9296 1-based number of port; usually bus->otg_port 9297 </para> 9298 </listitem> 9299 </varlistentry> 9300 </variablelist> 9301</refsect1> 9302<refsect1> 9303<title>Context</title> 9304<para> 9305 <function>in_interrupt</function> 9306</para> 9307</refsect1> 9308<refsect1> 9309<title>Description</title> 9310<para> 9311 Starts enumeration, with an immediate reset followed later by 9312 hub_wq identifying and possibly configuring the device. 9313 This is needed by OTG controller drivers, where it helps meet 9314 HNP protocol timing requirements for starting a port reset. 9315</para> 9316</refsect1> 9317<refsect1> 9318<title>Return</title> 9319<para> 9320 0 if successful. 9321</para> 9322</refsect1> 9323</refentry> 9324 9325<refentry id="API-usb-hcd-irq"> 9326<refentryinfo> 9327 <title>LINUX</title> 9328 <productname>Kernel Hackers Manual</productname> 9329 <date>July 2017</date> 9330</refentryinfo> 9331<refmeta> 9332 <refentrytitle><phrase>usb_hcd_irq</phrase></refentrytitle> 9333 <manvolnum>9</manvolnum> 9334 <refmiscinfo class="version">4.1.27</refmiscinfo> 9335</refmeta> 9336<refnamediv> 9337 <refname>usb_hcd_irq</refname> 9338 <refpurpose> 9339 hook IRQs to HCD framework (bus glue) 9340 </refpurpose> 9341</refnamediv> 9342<refsynopsisdiv> 9343 <title>Synopsis</title> 9344 <funcsynopsis><funcprototype> 9345 <funcdef>irqreturn_t <function>usb_hcd_irq </function></funcdef> 9346 <paramdef>int <parameter>irq</parameter></paramdef> 9347 <paramdef>void * <parameter>__hcd</parameter></paramdef> 9348 </funcprototype></funcsynopsis> 9349</refsynopsisdiv> 9350<refsect1> 9351 <title>Arguments</title> 9352 <variablelist> 9353 <varlistentry> 9354 <term><parameter>irq</parameter></term> 9355 <listitem> 9356 <para> 9357 the IRQ being raised 9358 </para> 9359 </listitem> 9360 </varlistentry> 9361 <varlistentry> 9362 <term><parameter>__hcd</parameter></term> 9363 <listitem> 9364 <para> 9365 pointer to the HCD whose IRQ is being signaled 9366 </para> 9367 </listitem> 9368 </varlistentry> 9369 </variablelist> 9370</refsect1> 9371<refsect1> 9372<title>Description</title> 9373<para> 9374 If the controller isn't HALTed, calls the driver's irq handler. 9375 Checks whether the controller is now dead. 9376</para> 9377</refsect1> 9378<refsect1> 9379<title>Return</title> 9380<para> 9381 <constant>IRQ_HANDLED</constant> if the IRQ was handled. <constant>IRQ_NONE</constant> otherwise. 9382</para> 9383</refsect1> 9384</refentry> 9385 9386<refentry id="API-usb-hc-died"> 9387<refentryinfo> 9388 <title>LINUX</title> 9389 <productname>Kernel Hackers Manual</productname> 9390 <date>July 2017</date> 9391</refentryinfo> 9392<refmeta> 9393 <refentrytitle><phrase>usb_hc_died</phrase></refentrytitle> 9394 <manvolnum>9</manvolnum> 9395 <refmiscinfo class="version">4.1.27</refmiscinfo> 9396</refmeta> 9397<refnamediv> 9398 <refname>usb_hc_died</refname> 9399 <refpurpose> 9400 report abnormal shutdown of a host controller (bus glue) 9401 </refpurpose> 9402</refnamediv> 9403<refsynopsisdiv> 9404 <title>Synopsis</title> 9405 <funcsynopsis><funcprototype> 9406 <funcdef>void <function>usb_hc_died </function></funcdef> 9407 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9408 </funcprototype></funcsynopsis> 9409</refsynopsisdiv> 9410<refsect1> 9411 <title>Arguments</title> 9412 <variablelist> 9413 <varlistentry> 9414 <term><parameter>hcd</parameter></term> 9415 <listitem> 9416 <para> 9417 pointer to the HCD representing the controller 9418 </para> 9419 </listitem> 9420 </varlistentry> 9421 </variablelist> 9422</refsect1> 9423<refsect1> 9424<title>Description</title> 9425<para> 9426 This is called by bus glue to report a USB host controller that died 9427 while operations may still have been pending. It's called automatically 9428 by the PCI glue, so only glue for non-PCI busses should need to call it. 9429 </para><para> 9430 9431 Only call this function with the primary HCD. 9432</para> 9433</refsect1> 9434</refentry> 9435 9436<refentry id="API-usb-create-shared-hcd"> 9437<refentryinfo> 9438 <title>LINUX</title> 9439 <productname>Kernel Hackers Manual</productname> 9440 <date>July 2017</date> 9441</refentryinfo> 9442<refmeta> 9443 <refentrytitle><phrase>usb_create_shared_hcd</phrase></refentrytitle> 9444 <manvolnum>9</manvolnum> 9445 <refmiscinfo class="version">4.1.27</refmiscinfo> 9446</refmeta> 9447<refnamediv> 9448 <refname>usb_create_shared_hcd</refname> 9449 <refpurpose> 9450 create and initialize an HCD structure 9451 </refpurpose> 9452</refnamediv> 9453<refsynopsisdiv> 9454 <title>Synopsis</title> 9455 <funcsynopsis><funcprototype> 9456 <funcdef>struct usb_hcd * <function>usb_create_shared_hcd </function></funcdef> 9457 <paramdef>const struct hc_driver * <parameter>driver</parameter></paramdef> 9458 <paramdef>struct device * <parameter>dev</parameter></paramdef> 9459 <paramdef>const char * <parameter>bus_name</parameter></paramdef> 9460 <paramdef>struct usb_hcd * <parameter>primary_hcd</parameter></paramdef> 9461 </funcprototype></funcsynopsis> 9462</refsynopsisdiv> 9463<refsect1> 9464 <title>Arguments</title> 9465 <variablelist> 9466 <varlistentry> 9467 <term><parameter>driver</parameter></term> 9468 <listitem> 9469 <para> 9470 HC driver that will use this hcd 9471 </para> 9472 </listitem> 9473 </varlistentry> 9474 <varlistentry> 9475 <term><parameter>dev</parameter></term> 9476 <listitem> 9477 <para> 9478 device for this HC, stored in hcd->self.controller 9479 </para> 9480 </listitem> 9481 </varlistentry> 9482 <varlistentry> 9483 <term><parameter>bus_name</parameter></term> 9484 <listitem> 9485 <para> 9486 value to store in hcd->self.bus_name 9487 </para> 9488 </listitem> 9489 </varlistentry> 9490 <varlistentry> 9491 <term><parameter>primary_hcd</parameter></term> 9492 <listitem> 9493 <para> 9494 a pointer to the usb_hcd structure that is sharing the 9495 PCI device. Only allocate certain resources for the primary HCD 9496 </para> 9497 </listitem> 9498 </varlistentry> 9499 </variablelist> 9500</refsect1> 9501<refsect1> 9502<title>Context</title> 9503<para> 9504 !<function>in_interrupt</function> 9505</para> 9506</refsect1> 9507<refsect1> 9508<title>Description</title> 9509<para> 9510 Allocate a struct usb_hcd, with extra space at the end for the 9511 HC driver's private data. Initialize the generic members of the 9512 hcd structure. 9513</para> 9514</refsect1> 9515<refsect1> 9516<title>Return</title> 9517<para> 9518 On success, a pointer to the created and initialized HCD structure. 9519 On failure (e.g. if memory is unavailable), <constant>NULL</constant>. 9520</para> 9521</refsect1> 9522</refentry> 9523 9524<refentry id="API-usb-create-hcd"> 9525<refentryinfo> 9526 <title>LINUX</title> 9527 <productname>Kernel Hackers Manual</productname> 9528 <date>July 2017</date> 9529</refentryinfo> 9530<refmeta> 9531 <refentrytitle><phrase>usb_create_hcd</phrase></refentrytitle> 9532 <manvolnum>9</manvolnum> 9533 <refmiscinfo class="version">4.1.27</refmiscinfo> 9534</refmeta> 9535<refnamediv> 9536 <refname>usb_create_hcd</refname> 9537 <refpurpose> 9538 create and initialize an HCD structure 9539 </refpurpose> 9540</refnamediv> 9541<refsynopsisdiv> 9542 <title>Synopsis</title> 9543 <funcsynopsis><funcprototype> 9544 <funcdef>struct usb_hcd * <function>usb_create_hcd </function></funcdef> 9545 <paramdef>const struct hc_driver * <parameter>driver</parameter></paramdef> 9546 <paramdef>struct device * <parameter>dev</parameter></paramdef> 9547 <paramdef>const char * <parameter>bus_name</parameter></paramdef> 9548 </funcprototype></funcsynopsis> 9549</refsynopsisdiv> 9550<refsect1> 9551 <title>Arguments</title> 9552 <variablelist> 9553 <varlistentry> 9554 <term><parameter>driver</parameter></term> 9555 <listitem> 9556 <para> 9557 HC driver that will use this hcd 9558 </para> 9559 </listitem> 9560 </varlistentry> 9561 <varlistentry> 9562 <term><parameter>dev</parameter></term> 9563 <listitem> 9564 <para> 9565 device for this HC, stored in hcd->self.controller 9566 </para> 9567 </listitem> 9568 </varlistentry> 9569 <varlistentry> 9570 <term><parameter>bus_name</parameter></term> 9571 <listitem> 9572 <para> 9573 value to store in hcd->self.bus_name 9574 </para> 9575 </listitem> 9576 </varlistentry> 9577 </variablelist> 9578</refsect1> 9579<refsect1> 9580<title>Context</title> 9581<para> 9582 !<function>in_interrupt</function> 9583</para> 9584</refsect1> 9585<refsect1> 9586<title>Description</title> 9587<para> 9588 Allocate a struct usb_hcd, with extra space at the end for the 9589 HC driver's private data. Initialize the generic members of the 9590 hcd structure. 9591</para> 9592</refsect1> 9593<refsect1> 9594<title>Return</title> 9595<para> 9596 On success, a pointer to the created and initialized HCD 9597 structure. On failure (e.g. if memory is unavailable), <constant>NULL</constant>. 9598</para> 9599</refsect1> 9600</refentry> 9601 9602<refentry id="API-usb-add-hcd"> 9603<refentryinfo> 9604 <title>LINUX</title> 9605 <productname>Kernel Hackers Manual</productname> 9606 <date>July 2017</date> 9607</refentryinfo> 9608<refmeta> 9609 <refentrytitle><phrase>usb_add_hcd</phrase></refentrytitle> 9610 <manvolnum>9</manvolnum> 9611 <refmiscinfo class="version">4.1.27</refmiscinfo> 9612</refmeta> 9613<refnamediv> 9614 <refname>usb_add_hcd</refname> 9615 <refpurpose> 9616 finish generic HCD structure initialization and register 9617 </refpurpose> 9618</refnamediv> 9619<refsynopsisdiv> 9620 <title>Synopsis</title> 9621 <funcsynopsis><funcprototype> 9622 <funcdef>int <function>usb_add_hcd </function></funcdef> 9623 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9624 <paramdef>unsigned int <parameter>irqnum</parameter></paramdef> 9625 <paramdef>unsigned long <parameter>irqflags</parameter></paramdef> 9626 </funcprototype></funcsynopsis> 9627</refsynopsisdiv> 9628<refsect1> 9629 <title>Arguments</title> 9630 <variablelist> 9631 <varlistentry> 9632 <term><parameter>hcd</parameter></term> 9633 <listitem> 9634 <para> 9635 the usb_hcd structure to initialize 9636 </para> 9637 </listitem> 9638 </varlistentry> 9639 <varlistentry> 9640 <term><parameter>irqnum</parameter></term> 9641 <listitem> 9642 <para> 9643 Interrupt line to allocate 9644 </para> 9645 </listitem> 9646 </varlistentry> 9647 <varlistentry> 9648 <term><parameter>irqflags</parameter></term> 9649 <listitem> 9650 <para> 9651 Interrupt type flags 9652 </para> 9653 </listitem> 9654 </varlistentry> 9655 </variablelist> 9656</refsect1> 9657<refsect1> 9658<title>Finish the remaining parts of generic HCD initialization</title> 9659<para> 9660 allocate the 9661 buffers of consistent memory, register the bus, request the IRQ line, 9662 and call the driver's <function>reset</function> and <function>start</function> routines. 9663</para> 9664</refsect1> 9665</refentry> 9666 9667<refentry id="API-usb-remove-hcd"> 9668<refentryinfo> 9669 <title>LINUX</title> 9670 <productname>Kernel Hackers Manual</productname> 9671 <date>July 2017</date> 9672</refentryinfo> 9673<refmeta> 9674 <refentrytitle><phrase>usb_remove_hcd</phrase></refentrytitle> 9675 <manvolnum>9</manvolnum> 9676 <refmiscinfo class="version">4.1.27</refmiscinfo> 9677</refmeta> 9678<refnamediv> 9679 <refname>usb_remove_hcd</refname> 9680 <refpurpose> 9681 shutdown processing for generic HCDs 9682 </refpurpose> 9683</refnamediv> 9684<refsynopsisdiv> 9685 <title>Synopsis</title> 9686 <funcsynopsis><funcprototype> 9687 <funcdef>void <function>usb_remove_hcd </function></funcdef> 9688 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9689 </funcprototype></funcsynopsis> 9690</refsynopsisdiv> 9691<refsect1> 9692 <title>Arguments</title> 9693 <variablelist> 9694 <varlistentry> 9695 <term><parameter>hcd</parameter></term> 9696 <listitem> 9697 <para> 9698 the usb_hcd structure to remove 9699 </para> 9700 </listitem> 9701 </varlistentry> 9702 </variablelist> 9703</refsect1> 9704<refsect1> 9705<title>Context</title> 9706<para> 9707 !<function>in_interrupt</function> 9708</para> 9709</refsect1> 9710<refsect1> 9711<title>Description</title> 9712<para> 9713 Disconnects the root hub, then reverses the effects of <function>usb_add_hcd</function>, 9714 invoking the HCD's <function>stop</function> method. 9715</para> 9716</refsect1> 9717</refentry> 9718 9719<!-- drivers/usb/core/hcd-pci.c --> 9720<refentry id="API-usb-hcd-pci-probe"> 9721<refentryinfo> 9722 <title>LINUX</title> 9723 <productname>Kernel Hackers Manual</productname> 9724 <date>July 2017</date> 9725</refentryinfo> 9726<refmeta> 9727 <refentrytitle><phrase>usb_hcd_pci_probe</phrase></refentrytitle> 9728 <manvolnum>9</manvolnum> 9729 <refmiscinfo class="version">4.1.27</refmiscinfo> 9730</refmeta> 9731<refnamediv> 9732 <refname>usb_hcd_pci_probe</refname> 9733 <refpurpose> 9734 initialize PCI-based HCDs 9735 </refpurpose> 9736</refnamediv> 9737<refsynopsisdiv> 9738 <title>Synopsis</title> 9739 <funcsynopsis><funcprototype> 9740 <funcdef>int <function>usb_hcd_pci_probe </function></funcdef> 9741 <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef> 9742 <paramdef>const struct pci_device_id * <parameter>id</parameter></paramdef> 9743 </funcprototype></funcsynopsis> 9744</refsynopsisdiv> 9745<refsect1> 9746 <title>Arguments</title> 9747 <variablelist> 9748 <varlistentry> 9749 <term><parameter>dev</parameter></term> 9750 <listitem> 9751 <para> 9752 USB Host Controller being probed 9753 </para> 9754 </listitem> 9755 </varlistentry> 9756 <varlistentry> 9757 <term><parameter>id</parameter></term> 9758 <listitem> 9759 <para> 9760 pci hotplug id connecting controller to HCD framework 9761 </para> 9762 </listitem> 9763 </varlistentry> 9764 </variablelist> 9765</refsect1> 9766<refsect1> 9767<title>Context</title> 9768<para> 9769 !<function>in_interrupt</function> 9770</para> 9771</refsect1> 9772<refsect1> 9773<title>Description</title> 9774<para> 9775 Allocates basic PCI resources for this USB host controller, and 9776 then invokes the <function>start</function> method for the HCD associated with it 9777 through the hotplug entry's driver_data. 9778 </para><para> 9779 9780 Store this function in the HCD's struct pci_driver as <function>probe</function>. 9781</para> 9782</refsect1> 9783<refsect1> 9784<title>Return</title> 9785<para> 9786 0 if successful. 9787</para> 9788</refsect1> 9789</refentry> 9790 9791<refentry id="API-usb-hcd-pci-remove"> 9792<refentryinfo> 9793 <title>LINUX</title> 9794 <productname>Kernel Hackers Manual</productname> 9795 <date>July 2017</date> 9796</refentryinfo> 9797<refmeta> 9798 <refentrytitle><phrase>usb_hcd_pci_remove</phrase></refentrytitle> 9799 <manvolnum>9</manvolnum> 9800 <refmiscinfo class="version">4.1.27</refmiscinfo> 9801</refmeta> 9802<refnamediv> 9803 <refname>usb_hcd_pci_remove</refname> 9804 <refpurpose> 9805 shutdown processing for PCI-based HCDs 9806 </refpurpose> 9807</refnamediv> 9808<refsynopsisdiv> 9809 <title>Synopsis</title> 9810 <funcsynopsis><funcprototype> 9811 <funcdef>void <function>usb_hcd_pci_remove </function></funcdef> 9812 <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef> 9813 </funcprototype></funcsynopsis> 9814</refsynopsisdiv> 9815<refsect1> 9816 <title>Arguments</title> 9817 <variablelist> 9818 <varlistentry> 9819 <term><parameter>dev</parameter></term> 9820 <listitem> 9821 <para> 9822 USB Host Controller being removed 9823 </para> 9824 </listitem> 9825 </varlistentry> 9826 </variablelist> 9827</refsect1> 9828<refsect1> 9829<title>Context</title> 9830<para> 9831 !<function>in_interrupt</function> 9832</para> 9833</refsect1> 9834<refsect1> 9835<title>Description</title> 9836<para> 9837 Reverses the effect of <function>usb_hcd_pci_probe</function>, first invoking 9838 the HCD's <function>stop</function> method. It is always called from a thread 9839 context, normally <quote>rmmod</quote>, <quote>apmd</quote>, or something similar. 9840 </para><para> 9841 9842 Store this function in the HCD's struct pci_driver as <function>remove</function>. 9843</para> 9844</refsect1> 9845</refentry> 9846 9847<refentry id="API-usb-hcd-pci-shutdown"> 9848<refentryinfo> 9849 <title>LINUX</title> 9850 <productname>Kernel Hackers Manual</productname> 9851 <date>July 2017</date> 9852</refentryinfo> 9853<refmeta> 9854 <refentrytitle><phrase>usb_hcd_pci_shutdown</phrase></refentrytitle> 9855 <manvolnum>9</manvolnum> 9856 <refmiscinfo class="version">4.1.27</refmiscinfo> 9857</refmeta> 9858<refnamediv> 9859 <refname>usb_hcd_pci_shutdown</refname> 9860 <refpurpose> 9861 shutdown host controller 9862 </refpurpose> 9863</refnamediv> 9864<refsynopsisdiv> 9865 <title>Synopsis</title> 9866 <funcsynopsis><funcprototype> 9867 <funcdef>void <function>usb_hcd_pci_shutdown </function></funcdef> 9868 <paramdef>struct pci_dev * <parameter>dev</parameter></paramdef> 9869 </funcprototype></funcsynopsis> 9870</refsynopsisdiv> 9871<refsect1> 9872 <title>Arguments</title> 9873 <variablelist> 9874 <varlistentry> 9875 <term><parameter>dev</parameter></term> 9876 <listitem> 9877 <para> 9878 USB Host Controller being shutdown 9879 </para> 9880 </listitem> 9881 </varlistentry> 9882 </variablelist> 9883</refsect1> 9884</refentry> 9885 9886<!-- drivers/usb/core/buffer.c --> 9887<refentry id="API-hcd-buffer-create"> 9888<refentryinfo> 9889 <title>LINUX</title> 9890 <productname>Kernel Hackers Manual</productname> 9891 <date>July 2017</date> 9892</refentryinfo> 9893<refmeta> 9894 <refentrytitle><phrase>hcd_buffer_create</phrase></refentrytitle> 9895 <manvolnum>9</manvolnum> 9896 <refmiscinfo class="version">4.1.27</refmiscinfo> 9897</refmeta> 9898<refnamediv> 9899 <refname>hcd_buffer_create</refname> 9900 <refpurpose> 9901 initialize buffer pools 9902 </refpurpose> 9903</refnamediv> 9904<refsynopsisdiv> 9905 <title>Synopsis</title> 9906 <funcsynopsis><funcprototype> 9907 <funcdef>int <function>hcd_buffer_create </function></funcdef> 9908 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9909 </funcprototype></funcsynopsis> 9910</refsynopsisdiv> 9911<refsect1> 9912 <title>Arguments</title> 9913 <variablelist> 9914 <varlistentry> 9915 <term><parameter>hcd</parameter></term> 9916 <listitem> 9917 <para> 9918 the bus whose buffer pools are to be initialized 9919 </para> 9920 </listitem> 9921 </varlistentry> 9922 </variablelist> 9923</refsect1> 9924<refsect1> 9925<title>Context</title> 9926<para> 9927 !<function>in_interrupt</function> 9928</para> 9929</refsect1> 9930<refsect1> 9931<title>Description</title> 9932<para> 9933 Call this as part of initializing a host controller that uses the dma 9934 memory allocators. It initializes some pools of dma-coherent memory that 9935 will be shared by all drivers using that controller. 9936 </para><para> 9937 9938 Call <function>hcd_buffer_destroy</function> to clean up after using those pools. 9939</para> 9940</refsect1> 9941<refsect1> 9942<title>Return</title> 9943<para> 9944 0 if successful. A negative errno value otherwise. 9945</para> 9946</refsect1> 9947</refentry> 9948 9949<refentry id="API-hcd-buffer-destroy"> 9950<refentryinfo> 9951 <title>LINUX</title> 9952 <productname>Kernel Hackers Manual</productname> 9953 <date>July 2017</date> 9954</refentryinfo> 9955<refmeta> 9956 <refentrytitle><phrase>hcd_buffer_destroy</phrase></refentrytitle> 9957 <manvolnum>9</manvolnum> 9958 <refmiscinfo class="version">4.1.27</refmiscinfo> 9959</refmeta> 9960<refnamediv> 9961 <refname>hcd_buffer_destroy</refname> 9962 <refpurpose> 9963 deallocate buffer pools 9964 </refpurpose> 9965</refnamediv> 9966<refsynopsisdiv> 9967 <title>Synopsis</title> 9968 <funcsynopsis><funcprototype> 9969 <funcdef>void <function>hcd_buffer_destroy </function></funcdef> 9970 <paramdef>struct usb_hcd * <parameter>hcd</parameter></paramdef> 9971 </funcprototype></funcsynopsis> 9972</refsynopsisdiv> 9973<refsect1> 9974 <title>Arguments</title> 9975 <variablelist> 9976 <varlistentry> 9977 <term><parameter>hcd</parameter></term> 9978 <listitem> 9979 <para> 9980 the bus whose buffer pools are to be destroyed 9981 </para> 9982 </listitem> 9983 </varlistentry> 9984 </variablelist> 9985</refsect1> 9986<refsect1> 9987<title>Context</title> 9988<para> 9989 !<function>in_interrupt</function> 9990</para> 9991</refsect1> 9992<refsect1> 9993<title>Description</title> 9994<para> 9995 This frees the buffer pools created by <function>hcd_buffer_create</function>. 9996</para> 9997</refsect1> 9998</refentry> 9999 10000 </chapter> 10001 10002 <chapter id="usbfs"> 10003 <title>The USB Filesystem (usbfs)</title> 10004 10005 <para>This chapter presents the Linux <emphasis>usbfs</emphasis>. 10006 You may prefer to avoid writing new kernel code for your 10007 USB driver; that's the problem that usbfs set out to solve. 10008 User mode device drivers are usually packaged as applications 10009 or libraries, and may use usbfs through some programming library 10010 that wraps it. Such libraries include 10011 <ulink url="http://libusb.sourceforge.net">libusb</ulink> 10012 for C/C++, and 10013 <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java. 10014 </para> 10015 10016 <note><title>Unfinished</title> 10017 <para>This particular documentation is incomplete, 10018 especially with respect to the asynchronous mode. 10019 As of kernel 2.5.66 the code and this (new) documentation 10020 need to be cross-reviewed. 10021 </para> 10022 </note> 10023 10024 <para>Configure usbfs into Linux kernels by enabling the 10025 <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS), 10026 and you get basic support for user mode USB device drivers. 10027 Until relatively recently it was often (confusingly) called 10028 <emphasis>usbdevfs</emphasis> although it wasn't solving what 10029 <emphasis>devfs</emphasis> was. 10030 Every USB device will appear in usbfs, regardless of whether or 10031 not it has a kernel driver. 10032 </para> 10033 10034 <sect1 id="usbfs-files"> 10035 <title>What files are in "usbfs"?</title> 10036 10037 <para>Conventionally mounted at 10038 <filename>/proc/bus/usb</filename>, usbfs 10039 features include: 10040 <itemizedlist> 10041 <listitem><para><filename>/proc/bus/usb/devices</filename> 10042 ... a text file 10043 showing each of the USB devices on known to the kernel, 10044 and their configuration descriptors. 10045 You can also poll() this to learn about new devices. 10046 </para></listitem> 10047 <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename> 10048 ... magic files 10049 exposing the each device's configuration descriptors, and 10050 supporting a series of ioctls for making device requests, 10051 including I/O to devices. (Purely for access by programs.) 10052 </para></listitem> 10053 </itemizedlist> 10054 </para> 10055 10056 <para> Each bus is given a number (BBB) based on when it was 10057 enumerated; within each bus, each device is given a similar 10058 number (DDD). 10059 Those BBB/DDD paths are not "stable" identifiers; 10060 expect them to change even if you always leave the devices 10061 plugged in to the same hub port. 10062 <emphasis>Don't even think of saving these in application 10063 configuration files.</emphasis> 10064 Stable identifiers are available, for user mode applications 10065 that want to use them. HID and networking devices expose 10066 these stable IDs, so that for example you can be sure that 10067 you told the right UPS to power down its second server. 10068 "usbfs" doesn't (yet) expose those IDs. 10069 </para> 10070 10071 </sect1> 10072 10073 <sect1 id="usbfs-fstab"> 10074 <title>Mounting and Access Control</title> 10075 10076 <para>There are a number of mount options for usbfs, which will 10077 be of most interest to you if you need to override the default 10078 access control policy. 10079 That policy is that only root may read or write device files 10080 (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read 10081 the <filename>devices</filename> 10082 or <filename>drivers</filename> files. 10083 I/O requests to the device also need the CAP_SYS_RAWIO capability, 10084 </para> 10085 10086 <para>The significance of that is that by default, all user mode 10087 device drivers need super-user privileges. 10088 You can change modes or ownership in a driver setup 10089 when the device hotplugs, or maye just start the 10090 driver right then, as a privileged server (or some activity 10091 within one). 10092 That's the most secure approach for multi-user systems, 10093 but for single user systems ("trusted" by that user) 10094 it's more convenient just to grant everyone all access 10095 (using the <emphasis>devmode=0666</emphasis> option) 10096 so the driver can start whenever it's needed. 10097 </para> 10098 10099 <para>The mount options for usbfs, usable in /etc/fstab or 10100 in command line invocations of <emphasis>mount</emphasis>, are: 10101 10102 <variablelist> 10103 <varlistentry> 10104 <term><emphasis>busgid</emphasis>=NNNNN</term> 10105 <listitem><para>Controls the GID used for the 10106 /proc/bus/usb/BBB 10107 directories. (Default: 0)</para></listitem></varlistentry> 10108 <varlistentry><term><emphasis>busmode</emphasis>=MMM</term> 10109 <listitem><para>Controls the file mode used for the 10110 /proc/bus/usb/BBB 10111 directories. (Default: 0555) 10112 </para></listitem></varlistentry> 10113 <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term> 10114 <listitem><para>Controls the UID used for the 10115 /proc/bus/usb/BBB 10116 directories. (Default: 0)</para></listitem></varlistentry> 10117 10118 <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term> 10119 <listitem><para>Controls the GID used for the 10120 /proc/bus/usb/BBB/DDD 10121 files. (Default: 0)</para></listitem></varlistentry> 10122 <varlistentry><term><emphasis>devmode</emphasis>=MMM</term> 10123 <listitem><para>Controls the file mode used for the 10124 /proc/bus/usb/BBB/DDD 10125 files. (Default: 0644)</para></listitem></varlistentry> 10126 <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term> 10127 <listitem><para>Controls the UID used for the 10128 /proc/bus/usb/BBB/DDD 10129 files. (Default: 0)</para></listitem></varlistentry> 10130 10131 <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term> 10132 <listitem><para>Controls the GID used for the 10133 /proc/bus/usb/devices and drivers files. 10134 (Default: 0)</para></listitem></varlistentry> 10135 <varlistentry><term><emphasis>listmode</emphasis>=MMM</term> 10136 <listitem><para>Controls the file mode used for the 10137 /proc/bus/usb/devices and drivers files. 10138 (Default: 0444)</para></listitem></varlistentry> 10139 <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term> 10140 <listitem><para>Controls the UID used for the 10141 /proc/bus/usb/devices and drivers files. 10142 (Default: 0)</para></listitem></varlistentry> 10143 </variablelist> 10144 10145 </para> 10146 10147 <para>Note that many Linux distributions hard-wire the mount options 10148 for usbfs in their init scripts, such as 10149 <filename>/etc/rc.d/rc.sysinit</filename>, 10150 rather than making it easy to set this per-system 10151 policy in <filename>/etc/fstab</filename>. 10152 </para> 10153 10154 </sect1> 10155 10156 <sect1 id="usbfs-devices"> 10157 <title>/proc/bus/usb/devices</title> 10158 10159 <para>This file is handy for status viewing tools in user 10160 mode, which can scan the text format and ignore most of it. 10161 More detailed device status (including class and vendor 10162 status) is available from device-specific files. 10163 For information about the current format of this file, 10164 see the 10165 <filename>Documentation/usb/proc_usb_info.txt</filename> 10166 file in your Linux kernel sources. 10167 </para> 10168 10169 <para>This file, in combination with the poll() system call, can 10170 also be used to detect when devices are added or removed: 10171<programlisting>int fd; 10172struct pollfd pfd; 10173 10174fd = open("/proc/bus/usb/devices", O_RDONLY); 10175pfd = { fd, POLLIN, 0 }; 10176for (;;) { 10177 /* The first time through, this call will return immediately. */ 10178 poll(&pfd, 1, -1); 10179 10180 /* To see what's changed, compare the file's previous and current 10181 contents or scan the filesystem. (Scanning is more precise.) */ 10182}</programlisting> 10183 Note that this behavior is intended to be used for informational 10184 and debug purposes. It would be more appropriate to use programs 10185 such as udev or HAL to initialize a device or start a user-mode 10186 helper program, for instance. 10187 </para> 10188 </sect1> 10189 10190 <sect1 id="usbfs-bbbddd"> 10191 <title>/proc/bus/usb/BBB/DDD</title> 10192 10193 <para>Use these files in one of these basic ways: 10194 </para> 10195 10196 <para><emphasis>They can be read,</emphasis> 10197 producing first the device descriptor 10198 (18 bytes) and then the descriptors for the current configuration. 10199 See the USB 2.0 spec for details about those binary data formats. 10200 You'll need to convert most multibyte values from little endian 10201 format to your native host byte order, although a few of the 10202 fields in the device descriptor (both of the BCD-encoded fields, 10203 and the vendor and product IDs) will be byteswapped for you. 10204 Note that configuration descriptors include descriptors for 10205 interfaces, altsettings, endpoints, and maybe additional 10206 class descriptors. 10207 </para> 10208 10209 <para><emphasis>Perform USB operations</emphasis> using 10210 <emphasis>ioctl()</emphasis> requests to make endpoint I/O 10211 requests (synchronously or asynchronously) or manage 10212 the device. 10213 These requests need the CAP_SYS_RAWIO capability, 10214 as well as filesystem access permissions. 10215 Only one ioctl request can be made on one of these 10216 device files at a time. 10217 This means that if you are synchronously reading an endpoint 10218 from one thread, you won't be able to write to a different 10219 endpoint from another thread until the read completes. 10220 This works for <emphasis>half duplex</emphasis> protocols, 10221 but otherwise you'd use asynchronous i/o requests. 10222 </para> 10223 10224 </sect1> 10225 10226 10227 <sect1 id="usbfs-lifecycle"> 10228 <title>Life Cycle of User Mode Drivers</title> 10229 10230 <para>Such a driver first needs to find a device file 10231 for a device it knows how to handle. 10232 Maybe it was told about it because a 10233 <filename>/sbin/hotplug</filename> event handling agent 10234 chose that driver to handle the new device. 10235 Or maybe it's an application that scans all the 10236 /proc/bus/usb device files, and ignores most devices. 10237 In either case, it should <function>read()</function> all 10238 the descriptors from the device file, 10239 and check them against what it knows how to handle. 10240 It might just reject everything except a particular 10241 vendor and product ID, or need a more complex policy. 10242 </para> 10243 10244 <para>Never assume there will only be one such device 10245 on the system at a time! 10246 If your code can't handle more than one device at 10247 a time, at least detect when there's more than one, and 10248 have your users choose which device to use. 10249 </para> 10250 10251 <para>Once your user mode driver knows what device to use, 10252 it interacts with it in either of two styles. 10253 The simple style is to make only control requests; some 10254 devices don't need more complex interactions than those. 10255 (An example might be software using vendor-specific control 10256 requests for some initialization or configuration tasks, 10257 with a kernel driver for the rest.) 10258 </para> 10259 10260 <para>More likely, you need a more complex style driver: 10261 one using non-control endpoints, reading or writing data 10262 and claiming exclusive use of an interface. 10263 <emphasis>Bulk</emphasis> transfers are easiest to use, 10264 but only their sibling <emphasis>interrupt</emphasis> transfers 10265 work with low speed devices. 10266 Both interrupt and <emphasis>isochronous</emphasis> transfers 10267 offer service guarantees because their bandwidth is reserved. 10268 Such "periodic" transfers are awkward to use through usbfs, 10269 unless you're using the asynchronous calls. However, interrupt 10270 transfers can also be used in a synchronous "one shot" style. 10271 </para> 10272 10273 <para>Your user-mode driver should never need to worry 10274 about cleaning up request state when the device is 10275 disconnected, although it should close its open file 10276 descriptors as soon as it starts seeing the ENODEV 10277 errors. 10278 </para> 10279 10280 </sect1> 10281 10282 <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title> 10283 10284 <para>To use these ioctls, you need to include the following 10285 headers in your userspace program: 10286<programlisting>#include <linux/usb.h> 10287#include <linux/usbdevice_fs.h> 10288#include <asm/byteorder.h></programlisting> 10289 The standard USB device model requests, from "Chapter 9" of 10290 the USB 2.0 specification, are automatically included from 10291 the <filename><linux/usb/ch9.h></filename> header. 10292 </para> 10293 10294 <para>Unless noted otherwise, the ioctl requests 10295 described here will 10296 update the modification time on the usbfs file to which 10297 they are applied (unless they fail). 10298 A return of zero indicates success; otherwise, a 10299 standard USB error code is returned. (These are 10300 documented in 10301 <filename>Documentation/usb/error-codes.txt</filename> 10302 in your kernel sources.) 10303 </para> 10304 10305 <para>Each of these files multiplexes access to several 10306 I/O streams, one per endpoint. 10307 Each device has one control endpoint (endpoint zero) 10308 which supports a limited RPC style RPC access. 10309 Devices are configured 10310 by hub_wq (in the kernel) setting a device-wide 10311 <emphasis>configuration</emphasis> that affects things 10312 like power consumption and basic functionality. 10313 The endpoints are part of USB <emphasis>interfaces</emphasis>, 10314 which may have <emphasis>altsettings</emphasis> 10315 affecting things like which endpoints are available. 10316 Many devices only have a single configuration and interface, 10317 so drivers for them will ignore configurations and altsettings. 10318 </para> 10319 10320 10321 <sect2 id="usbfs-mgmt"> 10322 <title>Management/Status Requests</title> 10323 10324 <para>A number of usbfs requests don't deal very directly 10325 with device I/O. 10326 They mostly relate to device management and status. 10327 These are all synchronous requests. 10328 </para> 10329 10330 <variablelist> 10331 10332 <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term> 10333 <listitem><para>This is used to force usbfs to 10334 claim a specific interface, 10335 which has not previously been claimed by usbfs or any other 10336 kernel driver. 10337 The ioctl parameter is an integer holding the number of 10338 the interface (bInterfaceNumber from descriptor). 10339 </para><para> 10340 Note that if your driver doesn't claim an interface 10341 before trying to use one of its endpoints, and no 10342 other driver has bound to it, then the interface is 10343 automatically claimed by usbfs. 10344 </para><para> 10345 This claim will be released by a RELEASEINTERFACE ioctl, 10346 or by closing the file descriptor. 10347 File modification time is not updated by this request. 10348 </para></listitem></varlistentry> 10349 10350 <varlistentry><term>USBDEVFS_CONNECTINFO</term> 10351 <listitem><para>Says whether the device is lowspeed. 10352 The ioctl parameter points to a structure like this: 10353<programlisting>struct usbdevfs_connectinfo { 10354 unsigned int devnum; 10355 unsigned char slow; 10356}; </programlisting> 10357 File modification time is not updated by this request. 10358 </para><para> 10359 <emphasis>You can't tell whether a "not slow" 10360 device is connected at high speed (480 MBit/sec) 10361 or just full speed (12 MBit/sec).</emphasis> 10362 You should know the devnum value already, 10363 it's the DDD value of the device file name. 10364 </para></listitem></varlistentry> 10365 10366 <varlistentry><term>USBDEVFS_GETDRIVER</term> 10367 <listitem><para>Returns the name of the kernel driver 10368 bound to a given interface (a string). Parameter 10369 is a pointer to this structure, which is modified: 10370<programlisting>struct usbdevfs_getdriver { 10371 unsigned int interface; 10372 char driver[USBDEVFS_MAXDRIVERNAME + 1]; 10373};</programlisting> 10374 File modification time is not updated by this request. 10375 </para></listitem></varlistentry> 10376 10377 <varlistentry><term>USBDEVFS_IOCTL</term> 10378 <listitem><para>Passes a request from userspace through 10379 to a kernel driver that has an ioctl entry in the 10380 <emphasis>struct usb_driver</emphasis> it registered. 10381<programlisting>struct usbdevfs_ioctl { 10382 int ifno; 10383 int ioctl_code; 10384 void *data; 10385}; 10386 10387/* user mode call looks like this. 10388 * 'request' becomes the driver->ioctl() 'code' parameter. 10389 * the size of 'param' is encoded in 'request', and that data 10390 * is copied to or from the driver->ioctl() 'buf' parameter. 10391 */ 10392static int 10393usbdev_ioctl (int fd, int ifno, unsigned request, void *param) 10394{ 10395 struct usbdevfs_ioctl wrapper; 10396 10397 wrapper.ifno = ifno; 10398 wrapper.ioctl_code = request; 10399 wrapper.data = param; 10400 10401 return ioctl (fd, USBDEVFS_IOCTL, &wrapper); 10402} </programlisting> 10403 File modification time is not updated by this request. 10404 </para><para> 10405 This request lets kernel drivers talk to user mode code 10406 through filesystem operations even when they don't create 10407 a character or block special device. 10408 It's also been used to do things like ask devices what 10409 device special file should be used. 10410 Two pre-defined ioctls are used 10411 to disconnect and reconnect kernel drivers, so 10412 that user mode code can completely manage binding 10413 and configuration of devices. 10414 </para></listitem></varlistentry> 10415 10416 <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term> 10417 <listitem><para>This is used to release the claim usbfs 10418 made on interface, either implicitly or because of a 10419 USBDEVFS_CLAIMINTERFACE call, before the file 10420 descriptor is closed. 10421 The ioctl parameter is an integer holding the number of 10422 the interface (bInterfaceNumber from descriptor); 10423 File modification time is not updated by this request. 10424 </para><warning><para> 10425 <emphasis>No security check is made to ensure 10426 that the task which made the claim is the one 10427 which is releasing it. 10428 This means that user mode driver may interfere 10429 other ones. </emphasis> 10430 </para></warning></listitem></varlistentry> 10431 10432 <varlistentry><term>USBDEVFS_RESETEP</term> 10433 <listitem><para>Resets the data toggle value for an endpoint 10434 (bulk or interrupt) to DATA0. 10435 The ioctl parameter is an integer endpoint number 10436 (1 to 15, as identified in the endpoint descriptor), 10437 with USB_DIR_IN added if the device's endpoint sends 10438 data to the host. 10439 </para><warning><para> 10440 <emphasis>Avoid using this request. 10441 It should probably be removed.</emphasis> 10442 Using it typically means the device and driver will lose 10443 toggle synchronization. If you really lost synchronization, 10444 you likely need to completely handshake with the device, 10445 using a request like CLEAR_HALT 10446 or SET_INTERFACE. 10447 </para></warning></listitem></varlistentry> 10448 10449 </variablelist> 10450 10451 </sect2> 10452 10453 <sect2 id="usbfs-sync"> 10454 <title>Synchronous I/O Support</title> 10455 10456 <para>Synchronous requests involve the kernel blocking 10457 until the user mode request completes, either by 10458 finishing successfully or by reporting an error. 10459 In most cases this is the simplest way to use usbfs, 10460 although as noted above it does prevent performing I/O 10461 to more than one endpoint at a time. 10462 </para> 10463 10464 <variablelist> 10465 10466 <varlistentry><term>USBDEVFS_BULK</term> 10467 <listitem><para>Issues a bulk read or write request to the 10468 device. 10469 The ioctl parameter is a pointer to this structure: 10470<programlisting>struct usbdevfs_bulktransfer { 10471 unsigned int ep; 10472 unsigned int len; 10473 unsigned int timeout; /* in milliseconds */ 10474 void *data; 10475};</programlisting> 10476 </para><para>The "ep" value identifies a 10477 bulk endpoint number (1 to 15, as identified in an endpoint 10478 descriptor), 10479 masked with USB_DIR_IN when referring to an endpoint which 10480 sends data to the host from the device. 10481 The length of the data buffer is identified by "len"; 10482 Recent kernels support requests up to about 128KBytes. 10483 <emphasis>FIXME say how read length is returned, 10484 and how short reads are handled.</emphasis>. 10485 </para></listitem></varlistentry> 10486 10487 <varlistentry><term>USBDEVFS_CLEAR_HALT</term> 10488 <listitem><para>Clears endpoint halt (stall) and 10489 resets the endpoint toggle. This is only 10490 meaningful for bulk or interrupt endpoints. 10491 The ioctl parameter is an integer endpoint number 10492 (1 to 15, as identified in an endpoint descriptor), 10493 masked with USB_DIR_IN when referring to an endpoint which 10494 sends data to the host from the device. 10495 </para><para> 10496 Use this on bulk or interrupt endpoints which have 10497 stalled, returning <emphasis>-EPIPE</emphasis> status 10498 to a data transfer request. 10499 Do not issue the control request directly, since 10500 that could invalidate the host's record of the 10501 data toggle. 10502 </para></listitem></varlistentry> 10503 10504 <varlistentry><term>USBDEVFS_CONTROL</term> 10505 <listitem><para>Issues a control request to the device. 10506 The ioctl parameter points to a structure like this: 10507<programlisting>struct usbdevfs_ctrltransfer { 10508 __u8 bRequestType; 10509 __u8 bRequest; 10510 __u16 wValue; 10511 __u16 wIndex; 10512 __u16 wLength; 10513 __u32 timeout; /* in milliseconds */ 10514 void *data; 10515};</programlisting> 10516 </para><para> 10517 The first eight bytes of this structure are the contents 10518 of the SETUP packet to be sent to the device; see the 10519 USB 2.0 specification for details. 10520 The bRequestType value is composed by combining a 10521 USB_TYPE_* value, a USB_DIR_* value, and a 10522 USB_RECIP_* value (from 10523 <emphasis><linux/usb.h></emphasis>). 10524 If wLength is nonzero, it describes the length of the data 10525 buffer, which is either written to the device 10526 (USB_DIR_OUT) or read from the device (USB_DIR_IN). 10527 </para><para> 10528 At this writing, you can't transfer more than 4 KBytes 10529 of data to or from a device; usbfs has a limit, and 10530 some host controller drivers have a limit. 10531 (That's not usually a problem.) 10532 <emphasis>Also</emphasis> there's no way to say it's 10533 not OK to get a short read back from the device. 10534 </para></listitem></varlistentry> 10535 10536 <varlistentry><term>USBDEVFS_RESET</term> 10537 <listitem><para>Does a USB level device reset. 10538 The ioctl parameter is ignored. 10539 After the reset, this rebinds all device interfaces. 10540 File modification time is not updated by this request. 10541 </para><warning><para> 10542 <emphasis>Avoid using this call</emphasis> 10543 until some usbcore bugs get fixed, 10544 since it does not fully synchronize device, interface, 10545 and driver (not just usbfs) state. 10546 </para></warning></listitem></varlistentry> 10547 10548 <varlistentry><term>USBDEVFS_SETINTERFACE</term> 10549 <listitem><para>Sets the alternate setting for an 10550 interface. The ioctl parameter is a pointer to a 10551 structure like this: 10552<programlisting>struct usbdevfs_setinterface { 10553 unsigned int interface; 10554 unsigned int altsetting; 10555}; </programlisting> 10556 File modification time is not updated by this request. 10557 </para><para> 10558 Those struct members are from some interface descriptor 10559 applying to the current configuration. 10560 The interface number is the bInterfaceNumber value, and 10561 the altsetting number is the bAlternateSetting value. 10562 (This resets each endpoint in the interface.) 10563 </para></listitem></varlistentry> 10564 10565 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term> 10566 <listitem><para>Issues the 10567 <function>usb_set_configuration</function> call 10568 for the device. 10569 The parameter is an integer holding the number of 10570 a configuration (bConfigurationValue from descriptor). 10571 File modification time is not updated by this request. 10572 </para><warning><para> 10573 <emphasis>Avoid using this call</emphasis> 10574 until some usbcore bugs get fixed, 10575 since it does not fully synchronize device, interface, 10576 and driver (not just usbfs) state. 10577 </para></warning></listitem></varlistentry> 10578 10579 </variablelist> 10580 </sect2> 10581 10582 <sect2 id="usbfs-async"> 10583 <title>Asynchronous I/O Support</title> 10584 10585 <para>As mentioned above, there are situations where it may be 10586 important to initiate concurrent operations from user mode code. 10587 This is particularly important for periodic transfers 10588 (interrupt and isochronous), but it can be used for other 10589 kinds of USB requests too. 10590 In such cases, the asynchronous requests described here 10591 are essential. Rather than submitting one request and having 10592 the kernel block until it completes, the blocking is separate. 10593 </para> 10594 10595 <para>These requests are packaged into a structure that 10596 resembles the URB used by kernel device drivers. 10597 (No POSIX Async I/O support here, sorry.) 10598 It identifies the endpoint type (USBDEVFS_URB_TYPE_*), 10599 endpoint (number, masked with USB_DIR_IN as appropriate), 10600 buffer and length, and a user "context" value serving to 10601 uniquely identify each request. 10602 (It's usually a pointer to per-request data.) 10603 Flags can modify requests (not as many as supported for 10604 kernel drivers). 10605 </para> 10606 10607 <para>Each request can specify a realtime signal number 10608 (between SIGRTMIN and SIGRTMAX, inclusive) to request a 10609 signal be sent when the request completes. 10610 </para> 10611 10612 <para>When usbfs returns these urbs, the status value 10613 is updated, and the buffer may have been modified. 10614 Except for isochronous transfers, the actual_length is 10615 updated to say how many bytes were transferred; if the 10616 USBDEVFS_URB_DISABLE_SPD flag is set 10617 ("short packets are not OK"), if fewer bytes were read 10618 than were requested then you get an error report. 10619 </para> 10620 10621<programlisting>struct usbdevfs_iso_packet_desc { 10622 unsigned int length; 10623 unsigned int actual_length; 10624 unsigned int status; 10625}; 10626 10627struct usbdevfs_urb { 10628 unsigned char type; 10629 unsigned char endpoint; 10630 int status; 10631 unsigned int flags; 10632 void *buffer; 10633 int buffer_length; 10634 int actual_length; 10635 int start_frame; 10636 int number_of_packets; 10637 int error_count; 10638 unsigned int signr; 10639 void *usercontext; 10640 struct usbdevfs_iso_packet_desc iso_frame_desc[]; 10641};</programlisting> 10642 10643 <para> For these asynchronous requests, the file modification 10644 time reflects when the request was initiated. 10645 This contrasts with their use with the synchronous requests, 10646 where it reflects when requests complete. 10647 </para> 10648 10649 <variablelist> 10650 10651 <varlistentry><term>USBDEVFS_DISCARDURB</term> 10652 <listitem><para> 10653 <emphasis>TBS</emphasis> 10654 File modification time is not updated by this request. 10655 </para><para> 10656 </para></listitem></varlistentry> 10657 10658 <varlistentry><term>USBDEVFS_DISCSIGNAL</term> 10659 <listitem><para> 10660 <emphasis>TBS</emphasis> 10661 File modification time is not updated by this request. 10662 </para><para> 10663 </para></listitem></varlistentry> 10664 10665 <varlistentry><term>USBDEVFS_REAPURB</term> 10666 <listitem><para> 10667 <emphasis>TBS</emphasis> 10668 File modification time is not updated by this request. 10669 </para><para> 10670 </para></listitem></varlistentry> 10671 10672 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term> 10673 <listitem><para> 10674 <emphasis>TBS</emphasis> 10675 File modification time is not updated by this request. 10676 </para><para> 10677 </para></listitem></varlistentry> 10678 10679 <varlistentry><term>USBDEVFS_SUBMITURB</term> 10680 <listitem><para> 10681 <emphasis>TBS</emphasis> 10682 </para><para> 10683 </para></listitem></varlistentry> 10684 10685 </variablelist> 10686 </sect2> 10687 10688 </sect1> 10689 10690 </chapter> 10691 10692</book> 10693<!-- vim:syntax=sgml:sw=4 10694--> 10695