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="USB-Gadget-API"> 6 <bookinfo> 7 <title>USB Gadget API for Linux</title> 8 <date>20 August 2004</date> 9 <edition>20 August 2004</edition> 10 11 <legalnotice> 12 <para> 13 This documentation is free software; you can redistribute 14 it and/or modify it under the terms of the GNU General Public 15 License as published by the Free Software Foundation; either 16 version 2 of the License, or (at your option) any later 17 version. 18 </para> 19 20 <para> 21 This program is distributed in the hope that it will be 22 useful, but WITHOUT ANY WARRANTY; without even the implied 23 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 24 See the GNU General Public License for more details. 25 </para> 26 27 <para> 28 You should have received a copy of the GNU General Public 29 License along with this program; if not, write to the Free 30 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 31 MA 02111-1307 USA 32 </para> 33 34 <para> 35 For more details see the file COPYING in the source 36 distribution of Linux. 37 </para> 38 </legalnotice> 39 <copyright> 40 <year>2003-2004</year> 41 <holder>David Brownell</holder> 42 </copyright> 43 44 <author> 45 <firstname>David</firstname> 46 <surname>Brownell</surname> 47 <affiliation> 48 <address><email>dbrownell@users.sourceforge.net</email></address> 49 </affiliation> 50 </author> 51 </bookinfo> 52 53<toc></toc> 54 55<chapter id="intro"><title>Introduction</title> 56 57<para>This document presents a Linux-USB "Gadget" 58kernel mode 59API, for use within peripherals and other USB devices 60that embed Linux. 61It provides an overview of the API structure, 62and shows how that fits into a system development project. 63This is the first such API released on Linux to address 64a number of important problems, including: </para> 65 66<itemizedlist> 67 <listitem><para>Supports USB 2.0, for high speed devices which 68 can stream data at several dozen megabytes per second. 69 </para></listitem> 70 <listitem><para>Handles devices with dozens of endpoints just as 71 well as ones with just two fixed-function ones. Gadget drivers 72 can be written so they're easy to port to new hardware. 73 </para></listitem> 74 <listitem><para>Flexible enough to expose more complex USB device 75 capabilities such as multiple configurations, multiple interfaces, 76 composite devices, 77 and alternate interface settings. 78 </para></listitem> 79 <listitem><para>USB "On-The-Go" (OTG) support, in conjunction 80 with updates to the Linux-USB host side. 81 </para></listitem> 82 <listitem><para>Sharing data structures and API models with the 83 Linux-USB host side API. This helps the OTG support, and 84 looks forward to more-symmetric frameworks (where the same 85 I/O model is used by both host and device side drivers). 86 </para></listitem> 87 <listitem><para>Minimalist, so it's easier to support new device 88 controller hardware. I/O processing doesn't imply large 89 demands for memory or CPU resources. 90 </para></listitem> 91</itemizedlist> 92 93 94<para>Most Linux developers will not be able to use this API, since they 95have USB "host" hardware in a PC, workstation, or server. 96Linux users with embedded systems are more likely to 97have USB peripheral hardware. 98To distinguish drivers running inside such hardware from the 99more familiar Linux "USB device drivers", 100which are host side proxies for the real USB devices, 101a different term is used: 102the drivers inside the peripherals are "USB gadget drivers". 103In USB protocol interactions, the device driver is the master 104(or "client driver") 105and the gadget driver is the slave (or "function driver"). 106</para> 107 108<para>The gadget API resembles the host side Linux-USB API in that both 109use queues of request objects to package I/O buffers, and those requests 110may be submitted or canceled. 111They share common definitions for the standard USB 112<emphasis>Chapter 9</emphasis> messages, structures, and constants. 113Also, both APIs bind and unbind drivers to devices. 114The APIs differ in detail, since the host side's current 115URB framework exposes a number of implementation details 116and assumptions that are inappropriate for a gadget API. 117While the model for control transfers and configuration 118management is necessarily different (one side is a hardware-neutral master, 119the other is a hardware-aware slave), the endpoint I/0 API used here 120should also be usable for an overhead-reduced host side API. 121</para> 122 123</chapter> 124 125<chapter id="structure"><title>Structure of Gadget Drivers</title> 126 127<para>A system running inside a USB peripheral 128normally has at least three layers inside the kernel to handle 129USB protocol processing, and may have additional layers in 130user space code. 131The "gadget" API is used by the middle layer to interact 132with the lowest level (which directly handles hardware). 133</para> 134 135<para>In Linux, from the bottom up, these layers are: 136</para> 137 138<variablelist> 139 140 <varlistentry> 141 <term><emphasis>USB Controller Driver</emphasis></term> 142 143 <listitem> 144 <para>This is the lowest software level. 145 It is the only layer that talks to hardware, 146 through registers, fifos, dma, irqs, and the like. 147 The <filename><linux/usb/gadget.h></filename> API abstracts 148 the peripheral controller endpoint hardware. 149 That hardware is exposed through endpoint objects, which accept 150 streams of IN/OUT buffers, and through callbacks that interact 151 with gadget drivers. 152 Since normal USB devices only have one upstream 153 port, they only have one of these drivers. 154 The controller driver can support any number of different 155 gadget drivers, but only one of them can be used at a time. 156 </para> 157 158 <para>Examples of such controller hardware include 159 the PCI-based NetChip 2280 USB 2.0 high speed controller, 160 the SA-11x0 or PXA-25x UDC (found within many PDAs), 161 and a variety of other products. 162 </para> 163 164 </listitem></varlistentry> 165 166 <varlistentry> 167 <term><emphasis>Gadget Driver</emphasis></term> 168 169 <listitem> 170 <para>The lower boundary of this driver implements hardware-neutral 171 USB functions, using calls to the controller driver. 172 Because such hardware varies widely in capabilities and restrictions, 173 and is used in embedded environments where space is at a premium, 174 the gadget driver is often configured at compile time 175 to work with endpoints supported by one particular controller. 176 Gadget drivers may be portable to several different controllers, 177 using conditional compilation. 178 (Recent kernels substantially simplify the work involved in 179 supporting new hardware, by <emphasis>autoconfiguring</emphasis> 180 endpoints automatically for many bulk-oriented drivers.) 181 Gadget driver responsibilities include: 182 </para> 183 <itemizedlist> 184 <listitem><para>handling setup requests (ep0 protocol responses) 185 possibly including class-specific functionality 186 </para></listitem> 187 <listitem><para>returning configuration and string descriptors 188 </para></listitem> 189 <listitem><para>(re)setting configurations and interface 190 altsettings, including enabling and configuring endpoints 191 </para></listitem> 192 <listitem><para>handling life cycle events, such as managing 193 bindings to hardware, 194 USB suspend/resume, remote wakeup, 195 and disconnection from the USB host. 196 </para></listitem> 197 <listitem><para>managing IN and OUT transfers on all currently 198 enabled endpoints 199 </para></listitem> 200 </itemizedlist> 201 202 <para> 203 Such drivers may be modules of proprietary code, although 204 that approach is discouraged in the Linux community. 205 </para> 206 </listitem></varlistentry> 207 208 <varlistentry> 209 <term><emphasis>Upper Level</emphasis></term> 210 211 <listitem> 212 <para>Most gadget drivers have an upper boundary that connects 213 to some Linux driver or framework in Linux. 214 Through that boundary flows the data which the gadget driver 215 produces and/or consumes through protocol transfers over USB. 216 Examples include: 217 </para> 218 <itemizedlist> 219 <listitem><para>user mode code, using generic (gadgetfs) 220 or application specific files in 221 <filename>/dev</filename> 222 </para></listitem> 223 <listitem><para>networking subsystem (for network gadgets, 224 like the CDC Ethernet Model gadget driver) 225 </para></listitem> 226 <listitem><para>data capture drivers, perhaps video4Linux or 227 a scanner driver; or test and measurement hardware. 228 </para></listitem> 229 <listitem><para>input subsystem (for HID gadgets) 230 </para></listitem> 231 <listitem><para>sound subsystem (for audio gadgets) 232 </para></listitem> 233 <listitem><para>file system (for PTP gadgets) 234 </para></listitem> 235 <listitem><para>block i/o subsystem (for usb-storage gadgets) 236 </para></listitem> 237 <listitem><para>... and more </para></listitem> 238 </itemizedlist> 239 </listitem></varlistentry> 240 241 <varlistentry> 242 <term><emphasis>Additional Layers</emphasis></term> 243 244 <listitem> 245 <para>Other layers may exist. 246 These could include kernel layers, such as network protocol stacks, 247 as well as user mode applications building on standard POSIX 248 system call APIs such as 249 <emphasis>open()</emphasis>, <emphasis>close()</emphasis>, 250 <emphasis>read()</emphasis> and <emphasis>write()</emphasis>. 251 On newer systems, POSIX Async I/O calls may be an option. 252 Such user mode code will not necessarily be subject to 253 the GNU General Public License (GPL). 254 </para> 255 </listitem></varlistentry> 256 257 258</variablelist> 259 260<para>OTG-capable systems will also need to include a standard Linux-USB 261host side stack, 262with <emphasis>usbcore</emphasis>, 263one or more <emphasis>Host Controller Drivers</emphasis> (HCDs), 264<emphasis>USB Device Drivers</emphasis> to support 265the OTG "Targeted Peripheral List", 266and so forth. 267There will also be an <emphasis>OTG Controller Driver</emphasis>, 268which is visible to gadget and device driver developers only indirectly. 269That helps the host and device side USB controllers implement the 270two new OTG protocols (HNP and SRP). 271Roles switch (host to peripheral, or vice versa) using HNP 272during USB suspend processing, and SRP can be viewed as a 273more battery-friendly kind of device wakeup protocol. 274</para> 275 276<para>Over time, reusable utilities are evolving to help make some 277gadget driver tasks simpler. 278For example, building configuration descriptors from vectors of 279descriptors for the configurations interfaces and endpoints is 280now automated, and many drivers now use autoconfiguration to 281choose hardware endpoints and initialize their descriptors. 282 283A potential example of particular interest 284is code implementing standard USB-IF protocols for 285HID, networking, storage, or audio classes. 286Some developers are interested in KDB or KGDB hooks, to let 287target hardware be remotely debugged. 288Most such USB protocol code doesn't need to be hardware-specific, 289any more than network protocols like X11, HTTP, or NFS are. 290Such gadget-side interface drivers should eventually be combined, 291to implement composite devices. 292</para> 293 294</chapter> 295 296 297<chapter id="api"><title>Kernel Mode Gadget API</title> 298 299<para>Gadget drivers declare themselves through a 300<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for 301most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>. 302The response to a set_configuration usually involves 303enabling one or more of the <emphasis>struct usb_ep</emphasis> objects 304exposed by the gadget, and submitting one or more 305<emphasis>struct usb_request</emphasis> buffers to transfer data. 306Understand those four data types, and their operations, and 307you will understand how this API works. 308</para> 309 310<note><title>Incomplete Data Type Descriptions</title> 311 312<para>This documentation was prepared using the standard Linux 313kernel <filename>docproc</filename> tool, which turns text 314and in-code comments into SGML DocBook and then into usable 315formats such as HTML or PDF. 316Other than the "Chapter 9" data types, most of the significant 317data types and functions are described here. 318</para> 319 320<para>However, docproc does not understand all the C constructs 321that are used, so some relevant information is likely omitted from 322what you are reading. 323One example of such information is endpoint autoconfiguration. 324You'll have to read the header file, and use example source 325code (such as that for "Gadget Zero"), to fully understand the API. 326</para> 327 328<para>The part of the API implementing some basic 329driver capabilities is specific to the version of the 330Linux kernel that's in use. 331The 2.6 kernel includes a <emphasis>driver model</emphasis> 332framework that has no analogue on earlier kernels; 333so those parts of the gadget API are not fully portable. 334(They are implemented on 2.4 kernels, but in a different way.) 335The driver model state is another part of this API that is 336ignored by the kerneldoc tools. 337</para> 338</note> 339 340<para>The core API does not expose 341every possible hardware feature, only the most widely available ones. 342There are significant hardware features, such as device-to-device DMA 343(without temporary storage in a memory buffer) 344that would be added using hardware-specific APIs. 345</para> 346 347<para>This API allows drivers to use conditional compilation to handle 348endpoint capabilities of different hardware, but doesn't require that. 349Hardware tends to have arbitrary restrictions, relating to 350transfer types, addressing, packet sizes, buffering, and availability. 351As a rule, such differences only matter for "endpoint zero" logic 352that handles device configuration and management. 353The API supports limited run-time 354detection of capabilities, through naming conventions for endpoints. 355Many drivers will be able to at least partially autoconfigure 356themselves. 357In particular, driver init sections will often have endpoint 358autoconfiguration logic that scans the hardware's list of endpoints 359to find ones matching the driver requirements 360(relying on those conventions), to eliminate some of the most 361common reasons for conditional compilation. 362</para> 363 364<para>Like the Linux-USB host side API, this API exposes 365the "chunky" nature of USB messages: I/O requests are in terms 366of one or more "packets", and packet boundaries are visible to drivers. 367Compared to RS-232 serial protocols, USB resembles 368synchronous protocols like HDLC 369(N bytes per frame, multipoint addressing, host as the primary 370station and devices as secondary stations) 371more than asynchronous ones 372(tty style: 8 data bits per frame, no parity, one stop bit). 373So for example the controller drivers won't buffer 374two single byte writes into a single two-byte USB IN packet, 375although gadget drivers may do so when they implement 376protocols where packet boundaries (and "short packets") 377are not significant. 378</para> 379 380<sect1 id="lifecycle"><title>Driver Life Cycle</title> 381 382<para>Gadget drivers make endpoint I/O requests to hardware without 383needing to know many details of the hardware, but driver 384setup/configuration code needs to handle some differences. 385Use the API like this: 386</para> 387 388<orderedlist numeration='arabic'> 389 390<listitem><para>Register a driver for the particular device side 391usb controller hardware, 392such as the net2280 on PCI (USB 2.0), 393sa11x0 or pxa25x as found in Linux PDAs, 394and so on. 395At this point the device is logically in the USB ch9 initial state 396("attached"), drawing no power and not usable 397(since it does not yet support enumeration). 398Any host should not see the device, since it's not 399activated the data line pullup used by the host to 400detect a device, even if VBUS power is available. 401</para></listitem> 402 403<listitem><para>Register a gadget driver that implements some higher level 404device function. That will then bind() to a usb_gadget, which 405activates the data line pullup sometime after detecting VBUS. 406</para></listitem> 407 408<listitem><para>The hardware driver can now start enumerating. 409The steps it handles are to accept USB power and set_address requests. 410Other steps are handled by the gadget driver. 411If the gadget driver module is unloaded before the host starts to 412enumerate, steps before step 7 are skipped. 413</para></listitem> 414 415<listitem><para>The gadget driver's setup() call returns usb descriptors, 416based both on what the bus interface hardware provides and on the 417functionality being implemented. 418That can involve alternate settings or configurations, 419unless the hardware prevents such operation. 420For OTG devices, each configuration descriptor includes 421an OTG descriptor. 422</para></listitem> 423 424<listitem><para>The gadget driver handles the last step of enumeration, 425when the USB host issues a set_configuration call. 426It enables all endpoints used in that configuration, 427with all interfaces in their default settings. 428That involves using a list of the hardware's endpoints, enabling each 429endpoint according to its descriptor. 430It may also involve using <function>usb_gadget_vbus_draw</function> 431to let more power be drawn from VBUS, as allowed by that configuration. 432For OTG devices, setting a configuration may also involve reporting 433HNP capabilities through a user interface. 434</para></listitem> 435 436<listitem><para>Do real work and perform data transfers, possibly involving 437changes to interface settings or switching to new configurations, until the 438device is disconnect()ed from the host. 439Queue any number of transfer requests to each endpoint. 440It may be suspended and resumed several times before being disconnected. 441On disconnect, the drivers go back to step 3 (above). 442</para></listitem> 443 444<listitem><para>When the gadget driver module is being unloaded, 445the driver unbind() callback is issued. That lets the controller 446driver be unloaded. 447</para></listitem> 448 449</orderedlist> 450 451<para>Drivers will normally be arranged so that just loading the 452gadget driver module (or statically linking it into a Linux kernel) 453allows the peripheral device to be enumerated, but some drivers 454will defer enumeration until some higher level component (like 455a user mode daemon) enables it. 456Note that at this lowest level there are no policies about how 457ep0 configuration logic is implemented, 458except that it should obey USB specifications. 459Such issues are in the domain of gadget drivers, 460including knowing about implementation constraints 461imposed by some USB controllers 462or understanding that composite devices might happen to 463be built by integrating reusable components. 464</para> 465 466<para>Note that the lifecycle above can be slightly different 467for OTG devices. 468Other than providing an additional OTG descriptor in each 469configuration, only the HNP-related differences are particularly 470visible to driver code. 471They involve reporting requirements during the SET_CONFIGURATION 472request, and the option to invoke HNP during some suspend callbacks. 473Also, SRP changes the semantics of 474<function>usb_gadget_wakeup</function> 475slightly. 476</para> 477 478</sect1> 479 480<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title> 481 482<para>Gadget drivers 483rely on common USB structures and constants 484defined in the 485<filename><linux/usb/ch9.h></filename> 486header file, which is standard in Linux 2.6 kernels. 487These are the same types and constants used by host 488side drivers (and usbcore). 489</para> 490 491<!-- include/linux/usb/ch9.h --> 492<refentry id="API-usb-speed-string"> 493<refentryinfo> 494 <title>LINUX</title> 495 <productname>Kernel Hackers Manual</productname> 496 <date>July 2017</date> 497</refentryinfo> 498<refmeta> 499 <refentrytitle><phrase>usb_speed_string</phrase></refentrytitle> 500 <manvolnum>9</manvolnum> 501 <refmiscinfo class="version">4.1.27</refmiscinfo> 502</refmeta> 503<refnamediv> 504 <refname>usb_speed_string</refname> 505 <refpurpose> 506 Returns human readable-name of the speed. 507 </refpurpose> 508</refnamediv> 509<refsynopsisdiv> 510 <title>Synopsis</title> 511 <funcsynopsis><funcprototype> 512 <funcdef>const char * <function>usb_speed_string </function></funcdef> 513 <paramdef>enum usb_device_speed <parameter>speed</parameter></paramdef> 514 </funcprototype></funcsynopsis> 515</refsynopsisdiv> 516<refsect1> 517 <title>Arguments</title> 518 <variablelist> 519 <varlistentry> 520 <term><parameter>speed</parameter></term> 521 <listitem> 522 <para> 523 The speed to return human-readable name for. If it's not 524 any of the speeds defined in usb_device_speed enum, string for 525 USB_SPEED_UNKNOWN will be returned. 526 </para> 527 </listitem> 528 </varlistentry> 529 </variablelist> 530</refsect1> 531</refentry> 532 533<refentry id="API-usb-state-string"> 534<refentryinfo> 535 <title>LINUX</title> 536 <productname>Kernel Hackers Manual</productname> 537 <date>July 2017</date> 538</refentryinfo> 539<refmeta> 540 <refentrytitle><phrase>usb_state_string</phrase></refentrytitle> 541 <manvolnum>9</manvolnum> 542 <refmiscinfo class="version">4.1.27</refmiscinfo> 543</refmeta> 544<refnamediv> 545 <refname>usb_state_string</refname> 546 <refpurpose> 547 Returns human readable name for the state. 548 </refpurpose> 549</refnamediv> 550<refsynopsisdiv> 551 <title>Synopsis</title> 552 <funcsynopsis><funcprototype> 553 <funcdef>const char * <function>usb_state_string </function></funcdef> 554 <paramdef>enum usb_device_state <parameter>state</parameter></paramdef> 555 </funcprototype></funcsynopsis> 556</refsynopsisdiv> 557<refsect1> 558 <title>Arguments</title> 559 <variablelist> 560 <varlistentry> 561 <term><parameter>state</parameter></term> 562 <listitem> 563 <para> 564 The state to return a human-readable name for. If it's not 565 any of the states devices in usb_device_state_string enum, 566 the string UNKNOWN will be returned. 567 </para> 568 </listitem> 569 </varlistentry> 570 </variablelist> 571</refsect1> 572</refentry> 573 574</sect1> 575 576<sect1 id="core"><title>Core Objects and Methods</title> 577 578<para>These are declared in 579<filename><linux/usb/gadget.h></filename>, 580and are used by gadget drivers to interact with 581USB peripheral controller drivers. 582</para> 583 584 <!-- yeech, this is ugly in nsgmls PDF output. 585 586 the PDF bookmark and refentry output nesting is wrong, 587 and the member/argument documentation indents ugly. 588 589 plus something (docproc?) adds whitespace before the 590 descriptive paragraph text, so it can't line up right 591 unless the explanations are trivial. 592 --> 593 594<!-- include/linux/usb/gadget.h --> 595<refentry id="API-struct-usb-request"> 596<refentryinfo> 597 <title>LINUX</title> 598 <productname>Kernel Hackers Manual</productname> 599 <date>July 2017</date> 600</refentryinfo> 601<refmeta> 602 <refentrytitle><phrase>struct usb_request</phrase></refentrytitle> 603 <manvolnum>9</manvolnum> 604 <refmiscinfo class="version">4.1.27</refmiscinfo> 605</refmeta> 606<refnamediv> 607 <refname>struct usb_request</refname> 608 <refpurpose> 609 describes one i/o request 610 </refpurpose> 611</refnamediv> 612<refsynopsisdiv> 613 <title>Synopsis</title> 614 <programlisting> 615struct usb_request { 616 void * buf; 617 unsigned length; 618 dma_addr_t dma; 619 struct scatterlist * sg; 620 unsigned num_sgs; 621 unsigned num_mapped_sgs; 622 unsigned stream_id:16; 623 unsigned no_interrupt:1; 624 unsigned zero:1; 625 unsigned short_not_ok:1; 626 void (* complete) (struct usb_ep *ep,struct usb_request *req); 627 void * context; 628 struct list_head list; 629 int status; 630 unsigned actual; 631}; </programlisting> 632</refsynopsisdiv> 633 <refsect1> 634 <title>Members</title> 635 <variablelist> 636 <varlistentry> <term>buf</term> 637 <listitem><para> 638Buffer used for data. Always provide this; some controllers 639only use PIO, or don't use DMA for some endpoints. 640 </para></listitem> 641 </varlistentry> 642 <varlistentry> <term>length</term> 643 <listitem><para> 644Length of that data 645 </para></listitem> 646 </varlistentry> 647 <varlistentry> <term>dma</term> 648 <listitem><para> 649DMA address corresponding to 'buf'. If you don't set this 650field, and the usb controller needs one, it is responsible 651for mapping and unmapping the buffer. 652 </para></listitem> 653 </varlistentry> 654 <varlistentry> <term>sg</term> 655 <listitem><para> 656a scatterlist for SG-capable controllers. 657 </para></listitem> 658 </varlistentry> 659 <varlistentry> <term>num_sgs</term> 660 <listitem><para> 661number of SG entries 662 </para></listitem> 663 </varlistentry> 664 <varlistentry> <term>num_mapped_sgs</term> 665 <listitem><para> 666number of SG entries mapped to DMA (internal) 667 </para></listitem> 668 </varlistentry> 669 <varlistentry> <term>stream_id</term> 670 <listitem><para> 671The stream id, when USB3.0 bulk streams are being used 672 </para></listitem> 673 </varlistentry> 674 <varlistentry> <term>no_interrupt</term> 675 <listitem><para> 676If true, hints that no completion irq is needed. 677Helpful sometimes with deep request queues that are handled 678directly by DMA controllers. 679 </para></listitem> 680 </varlistentry> 681 <varlistentry> <term>zero</term> 682 <listitem><para> 683If true, when writing data, makes the last packet be <quote>short</quote> 684by adding a zero length packet as needed; 685 </para></listitem> 686 </varlistentry> 687 <varlistentry> <term>short_not_ok</term> 688 <listitem><para> 689When reading data, makes short packets be 690treated as errors (queue stops advancing till cleanup). 691 </para></listitem> 692 </varlistentry> 693 <varlistentry> <term>complete</term> 694 <listitem><para> 695Function called when request completes, so this request and 696its buffer may be re-used. The function will always be called with 697interrupts disabled, and it must not sleep. 698Reads terminate with a short packet, or when the buffer fills, 699whichever comes first. When writes terminate, some data bytes 700will usually still be in flight (often in a hardware fifo). 701Errors (for reads or writes) stop the queue from advancing 702until the completion function returns, so that any transfers 703invalidated by the error may first be dequeued. 704 </para></listitem> 705 </varlistentry> 706 <varlistentry> <term>context</term> 707 <listitem><para> 708For use by the completion callback 709 </para></listitem> 710 </varlistentry> 711 <varlistentry> <term>list</term> 712 <listitem><para> 713For use by the gadget driver. 714 </para></listitem> 715 </varlistentry> 716 <varlistentry> <term>status</term> 717 <listitem><para> 718Reports completion code, zero or a negative errno. 719Normally, faults block the transfer queue from advancing until 720the completion callback returns. 721Code <quote>-ESHUTDOWN</quote> indicates completion caused by device disconnect, 722or when the driver disabled the endpoint. 723 </para></listitem> 724 </varlistentry> 725 <varlistentry> <term>actual</term> 726 <listitem><para> 727Reports bytes transferred to/from the buffer. For reads (OUT 728transfers) this may be less than the requested length. If the 729short_not_ok flag is set, short reads are treated as errors 730even when status otherwise indicates successful completion. 731Note that for writes (IN transfers) some data bytes may still 732reside in a device-side FIFO when the request is reported as 733complete. 734 </para></listitem> 735 </varlistentry> 736 </variablelist> 737 </refsect1> 738<refsect1> 739<title>Description</title> 740<para> 741 These are allocated/freed through the endpoint they're used with. The 742 hardware's driver can add extra per-request data to the memory it returns, 743 which often avoids separate memory allocations (potential failures), 744 later when the request is queued. 745 </para><para> 746 747 Request flags affect request handling, such as whether a zero length 748 packet is written (the <quote>zero</quote> flag), whether a short read should be 749 treated as an error (blocking request queue advance, the <quote>short_not_ok</quote> 750 flag), or hinting that an interrupt is not required (the <quote>no_interrupt</quote> 751 flag, for use with deep request queues). 752 </para><para> 753 754 Bulk endpoints can use any size buffers, and can also be used for interrupt 755 transfers. interrupt-only endpoints can be much less functional. 756</para> 757</refsect1> 758<refsect1> 759<title>NOTE</title> 760<para> 761 this is analogous to 'struct urb' on the host side, except that 762 it's thinner and promotes more pre-allocation. 763</para> 764</refsect1> 765</refentry> 766 767<refentry id="API-struct-usb-ep"> 768<refentryinfo> 769 <title>LINUX</title> 770 <productname>Kernel Hackers Manual</productname> 771 <date>July 2017</date> 772</refentryinfo> 773<refmeta> 774 <refentrytitle><phrase>struct usb_ep</phrase></refentrytitle> 775 <manvolnum>9</manvolnum> 776 <refmiscinfo class="version">4.1.27</refmiscinfo> 777</refmeta> 778<refnamediv> 779 <refname>struct usb_ep</refname> 780 <refpurpose> 781 device side representation of USB endpoint 782 </refpurpose> 783</refnamediv> 784<refsynopsisdiv> 785 <title>Synopsis</title> 786 <programlisting> 787struct usb_ep { 788 void * driver_data; 789 const char * name; 790 const struct usb_ep_ops * ops; 791 struct list_head ep_list; 792 unsigned maxpacket:16; 793 unsigned maxpacket_limit:16; 794 unsigned max_streams:16; 795 unsigned mult:2; 796 unsigned maxburst:5; 797 u8 address; 798 const struct usb_endpoint_descriptor * desc; 799 const struct usb_ss_ep_comp_descriptor * comp_desc; 800}; </programlisting> 801</refsynopsisdiv> 802 <refsect1> 803 <title>Members</title> 804 <variablelist> 805 <varlistentry> <term>driver_data</term> 806 <listitem><para> 807 for use by the gadget driver. 808 </para></listitem> 809 </varlistentry> 810 <varlistentry> <term>name</term> 811 <listitem><para> 812 identifier for the endpoint, such as <quote>ep-a</quote> or <quote>ep9in-bulk</quote> 813 </para></listitem> 814 </varlistentry> 815 <varlistentry> <term>ops</term> 816 <listitem><para> 817 Function pointers used to access hardware-specific operations. 818 </para></listitem> 819 </varlistentry> 820 <varlistentry> <term>ep_list</term> 821 <listitem><para> 822 the gadget's ep_list holds all of its endpoints 823 </para></listitem> 824 </varlistentry> 825 <varlistentry> <term>maxpacket</term> 826 <listitem><para> 827 The maximum packet size used on this endpoint. The initial 828 value can sometimes be reduced (hardware allowing), according to 829 the endpoint descriptor used to configure the endpoint. 830 </para></listitem> 831 </varlistentry> 832 <varlistentry> <term>maxpacket_limit</term> 833 <listitem><para> 834 The maximum packet size value which can be handled by this 835 endpoint. It's set once by UDC driver when endpoint is initialized, and 836 should not be changed. Should not be confused with maxpacket. 837 </para></listitem> 838 </varlistentry> 839 <varlistentry> <term>max_streams</term> 840 <listitem><para> 841 The maximum number of streams supported 842 by this EP (0 - 16, actual number is 2^n) 843 </para></listitem> 844 </varlistentry> 845 <varlistentry> <term>mult</term> 846 <listitem><para> 847 multiplier, 'mult' value for SS Isoc EPs 848 </para></listitem> 849 </varlistentry> 850 <varlistentry> <term>maxburst</term> 851 <listitem><para> 852 the maximum number of bursts supported by this EP (for usb3) 853 </para></listitem> 854 </varlistentry> 855 <varlistentry> <term>address</term> 856 <listitem><para> 857 used to identify the endpoint when finding descriptor that 858 matches connection speed 859 </para></listitem> 860 </varlistentry> 861 <varlistentry> <term>desc</term> 862 <listitem><para> 863 endpoint descriptor. This pointer is set before the endpoint is 864 enabled and remains valid until the endpoint is disabled. 865 </para></listitem> 866 </varlistentry> 867 <varlistentry> <term>comp_desc</term> 868 <listitem><para> 869 In case of SuperSpeed support, this is the endpoint companion 870 descriptor that is used to configure the endpoint 871 </para></listitem> 872 </varlistentry> 873 </variablelist> 874 </refsect1> 875<refsect1> 876<title>Description</title> 877<para> 878 the bus controller driver lists all the general purpose endpoints in 879 gadget->ep_list. the control endpoint (gadget->ep0) is not in that list, 880 and is accessed only in response to a driver <function>setup</function> callback. 881</para> 882</refsect1> 883</refentry> 884 885<refentry id="API-usb-ep-set-maxpacket-limit"> 886<refentryinfo> 887 <title>LINUX</title> 888 <productname>Kernel Hackers Manual</productname> 889 <date>July 2017</date> 890</refentryinfo> 891<refmeta> 892 <refentrytitle><phrase>usb_ep_set_maxpacket_limit</phrase></refentrytitle> 893 <manvolnum>9</manvolnum> 894 <refmiscinfo class="version">4.1.27</refmiscinfo> 895</refmeta> 896<refnamediv> 897 <refname>usb_ep_set_maxpacket_limit</refname> 898 <refpurpose> 899 set maximum packet size limit for endpoint 900 </refpurpose> 901</refnamediv> 902<refsynopsisdiv> 903 <title>Synopsis</title> 904 <funcsynopsis><funcprototype> 905 <funcdef>void <function>usb_ep_set_maxpacket_limit </function></funcdef> 906 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 907 <paramdef>unsigned <parameter>maxpacket_limit</parameter></paramdef> 908 </funcprototype></funcsynopsis> 909</refsynopsisdiv> 910<refsect1> 911 <title>Arguments</title> 912 <variablelist> 913 <varlistentry> 914 <term><parameter>ep</parameter></term> 915 <listitem> 916 <para> 917 the endpoint being configured 918 </para> 919 </listitem> 920 </varlistentry> 921 <varlistentry> 922 <term><parameter>maxpacket_limit</parameter></term> 923 <listitem> 924 <para> 925 value of maximum packet size limit 926 </para> 927 </listitem> 928 </varlistentry> 929 </variablelist> 930</refsect1> 931<refsect1> 932<title>Description</title> 933<para> 934 This function should be used only in UDC drivers to initialize endpoint 935 (usually in probe function). 936</para> 937</refsect1> 938</refentry> 939 940<refentry id="API-usb-ep-enable"> 941<refentryinfo> 942 <title>LINUX</title> 943 <productname>Kernel Hackers Manual</productname> 944 <date>July 2017</date> 945</refentryinfo> 946<refmeta> 947 <refentrytitle><phrase>usb_ep_enable</phrase></refentrytitle> 948 <manvolnum>9</manvolnum> 949 <refmiscinfo class="version">4.1.27</refmiscinfo> 950</refmeta> 951<refnamediv> 952 <refname>usb_ep_enable</refname> 953 <refpurpose> 954 configure endpoint, making it usable 955 </refpurpose> 956</refnamediv> 957<refsynopsisdiv> 958 <title>Synopsis</title> 959 <funcsynopsis><funcprototype> 960 <funcdef>int <function>usb_ep_enable </function></funcdef> 961 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 962 </funcprototype></funcsynopsis> 963</refsynopsisdiv> 964<refsect1> 965 <title>Arguments</title> 966 <variablelist> 967 <varlistentry> 968 <term><parameter>ep</parameter></term> 969 <listitem> 970 <para> 971 the endpoint being configured. may not be the endpoint named <quote>ep0</quote>. 972 drivers discover endpoints through the ep_list of a usb_gadget. 973 </para> 974 </listitem> 975 </varlistentry> 976 </variablelist> 977</refsect1> 978<refsect1> 979<title>Description</title> 980<para> 981 When configurations are set, or when interface settings change, the driver 982 will enable or disable the relevant endpoints. while it is enabled, an 983 endpoint may be used for i/o until the driver receives a <function>disconnect</function> from 984 the host or until the endpoint is disabled. 985 </para><para> 986 987 the ep0 implementation (which calls this routine) must ensure that the 988 hardware capabilities of each endpoint match the descriptor provided 989 for it. for example, an endpoint named <quote>ep2in-bulk</quote> would be usable 990 for interrupt transfers as well as bulk, but it likely couldn't be used 991 for iso transfers or for endpoint 14. some endpoints are fully 992 configurable, with more generic names like <quote>ep-a</quote>. (remember that for 993 USB, <quote>in</quote> means <quote>towards the USB master</quote>.) 994 </para><para> 995 996 returns zero, or a negative error code. 997</para> 998</refsect1> 999</refentry> 1000 1001<refentry id="API-usb-ep-disable"> 1002<refentryinfo> 1003 <title>LINUX</title> 1004 <productname>Kernel Hackers Manual</productname> 1005 <date>July 2017</date> 1006</refentryinfo> 1007<refmeta> 1008 <refentrytitle><phrase>usb_ep_disable</phrase></refentrytitle> 1009 <manvolnum>9</manvolnum> 1010 <refmiscinfo class="version">4.1.27</refmiscinfo> 1011</refmeta> 1012<refnamediv> 1013 <refname>usb_ep_disable</refname> 1014 <refpurpose> 1015 endpoint is no longer usable 1016 </refpurpose> 1017</refnamediv> 1018<refsynopsisdiv> 1019 <title>Synopsis</title> 1020 <funcsynopsis><funcprototype> 1021 <funcdef>int <function>usb_ep_disable </function></funcdef> 1022 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1023 </funcprototype></funcsynopsis> 1024</refsynopsisdiv> 1025<refsect1> 1026 <title>Arguments</title> 1027 <variablelist> 1028 <varlistentry> 1029 <term><parameter>ep</parameter></term> 1030 <listitem> 1031 <para> 1032 the endpoint being unconfigured. may not be the endpoint named <quote>ep0</quote>. 1033 </para> 1034 </listitem> 1035 </varlistentry> 1036 </variablelist> 1037</refsect1> 1038<refsect1> 1039<title>Description</title> 1040<para> 1041 no other task may be using this endpoint when this is called. 1042 any pending and uncompleted requests will complete with status 1043 indicating disconnect (-ESHUTDOWN) before this call returns. 1044 gadget drivers must call <function>usb_ep_enable</function> again before queueing 1045 requests to the endpoint. 1046 </para><para> 1047 1048 returns zero, or a negative error code. 1049</para> 1050</refsect1> 1051</refentry> 1052 1053<refentry id="API-usb-ep-alloc-request"> 1054<refentryinfo> 1055 <title>LINUX</title> 1056 <productname>Kernel Hackers Manual</productname> 1057 <date>July 2017</date> 1058</refentryinfo> 1059<refmeta> 1060 <refentrytitle><phrase>usb_ep_alloc_request</phrase></refentrytitle> 1061 <manvolnum>9</manvolnum> 1062 <refmiscinfo class="version">4.1.27</refmiscinfo> 1063</refmeta> 1064<refnamediv> 1065 <refname>usb_ep_alloc_request</refname> 1066 <refpurpose> 1067 allocate a request object to use with this endpoint 1068 </refpurpose> 1069</refnamediv> 1070<refsynopsisdiv> 1071 <title>Synopsis</title> 1072 <funcsynopsis><funcprototype> 1073 <funcdef>struct usb_request * <function>usb_ep_alloc_request </function></funcdef> 1074 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1075 <paramdef>gfp_t <parameter>gfp_flags</parameter></paramdef> 1076 </funcprototype></funcsynopsis> 1077</refsynopsisdiv> 1078<refsect1> 1079 <title>Arguments</title> 1080 <variablelist> 1081 <varlistentry> 1082 <term><parameter>ep</parameter></term> 1083 <listitem> 1084 <para> 1085 the endpoint to be used with with the request 1086 </para> 1087 </listitem> 1088 </varlistentry> 1089 <varlistentry> 1090 <term><parameter>gfp_flags</parameter></term> 1091 <listitem> 1092 <para> 1093 GFP_* flags to use 1094 </para> 1095 </listitem> 1096 </varlistentry> 1097 </variablelist> 1098</refsect1> 1099<refsect1> 1100<title>Description</title> 1101<para> 1102 Request objects must be allocated with this call, since they normally 1103 need controller-specific setup and may even need endpoint-specific 1104 resources such as allocation of DMA descriptors. 1105 Requests may be submitted with <function>usb_ep_queue</function>, and receive a single 1106 completion callback. Free requests with <function>usb_ep_free_request</function>, when 1107 they are no longer needed. 1108 </para><para> 1109 1110 Returns the request, or null if one could not be allocated. 1111</para> 1112</refsect1> 1113</refentry> 1114 1115<refentry id="API-usb-ep-free-request"> 1116<refentryinfo> 1117 <title>LINUX</title> 1118 <productname>Kernel Hackers Manual</productname> 1119 <date>July 2017</date> 1120</refentryinfo> 1121<refmeta> 1122 <refentrytitle><phrase>usb_ep_free_request</phrase></refentrytitle> 1123 <manvolnum>9</manvolnum> 1124 <refmiscinfo class="version">4.1.27</refmiscinfo> 1125</refmeta> 1126<refnamediv> 1127 <refname>usb_ep_free_request</refname> 1128 <refpurpose> 1129 frees a request object 1130 </refpurpose> 1131</refnamediv> 1132<refsynopsisdiv> 1133 <title>Synopsis</title> 1134 <funcsynopsis><funcprototype> 1135 <funcdef>void <function>usb_ep_free_request </function></funcdef> 1136 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1137 <paramdef>struct usb_request * <parameter>req</parameter></paramdef> 1138 </funcprototype></funcsynopsis> 1139</refsynopsisdiv> 1140<refsect1> 1141 <title>Arguments</title> 1142 <variablelist> 1143 <varlistentry> 1144 <term><parameter>ep</parameter></term> 1145 <listitem> 1146 <para> 1147 the endpoint associated with the request 1148 </para> 1149 </listitem> 1150 </varlistentry> 1151 <varlistentry> 1152 <term><parameter>req</parameter></term> 1153 <listitem> 1154 <para> 1155 the request being freed 1156 </para> 1157 </listitem> 1158 </varlistentry> 1159 </variablelist> 1160</refsect1> 1161<refsect1> 1162<title>Description</title> 1163<para> 1164 Reverses the effect of <function>usb_ep_alloc_request</function>. 1165 Caller guarantees the request is not queued, and that it will 1166 no longer be requeued (or otherwise used). 1167</para> 1168</refsect1> 1169</refentry> 1170 1171<refentry id="API-usb-ep-queue"> 1172<refentryinfo> 1173 <title>LINUX</title> 1174 <productname>Kernel Hackers Manual</productname> 1175 <date>July 2017</date> 1176</refentryinfo> 1177<refmeta> 1178 <refentrytitle><phrase>usb_ep_queue</phrase></refentrytitle> 1179 <manvolnum>9</manvolnum> 1180 <refmiscinfo class="version">4.1.27</refmiscinfo> 1181</refmeta> 1182<refnamediv> 1183 <refname>usb_ep_queue</refname> 1184 <refpurpose> 1185 queues (submits) an I/O request to an endpoint. 1186 </refpurpose> 1187</refnamediv> 1188<refsynopsisdiv> 1189 <title>Synopsis</title> 1190 <funcsynopsis><funcprototype> 1191 <funcdef>int <function>usb_ep_queue </function></funcdef> 1192 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1193 <paramdef>struct usb_request * <parameter>req</parameter></paramdef> 1194 <paramdef>gfp_t <parameter>gfp_flags</parameter></paramdef> 1195 </funcprototype></funcsynopsis> 1196</refsynopsisdiv> 1197<refsect1> 1198 <title>Arguments</title> 1199 <variablelist> 1200 <varlistentry> 1201 <term><parameter>ep</parameter></term> 1202 <listitem> 1203 <para> 1204 the endpoint associated with the request 1205 </para> 1206 </listitem> 1207 </varlistentry> 1208 <varlistentry> 1209 <term><parameter>req</parameter></term> 1210 <listitem> 1211 <para> 1212 the request being submitted 1213 </para> 1214 </listitem> 1215 </varlistentry> 1216 <varlistentry> 1217 <term><parameter>gfp_flags</parameter></term> 1218 <listitem> 1219 <para> 1220 GFP_* flags to use in case the lower level driver couldn't 1221 pre-allocate all necessary memory with the request. 1222 </para> 1223 </listitem> 1224 </varlistentry> 1225 </variablelist> 1226</refsect1> 1227<refsect1> 1228<title>Description</title> 1229<para> 1230 This tells the device controller to perform the specified request through 1231 that endpoint (reading or writing a buffer). When the request completes, 1232 including being canceled by <function>usb_ep_dequeue</function>, the request's completion 1233 routine is called to return the request to the driver. Any endpoint 1234 (except control endpoints like ep0) may have more than one transfer 1235 request queued; they complete in FIFO order. Once a gadget driver 1236 submits a request, that request may not be examined or modified until it 1237 is given back to that driver through the completion callback. 1238 </para><para> 1239 1240 Each request is turned into one or more packets. The controller driver 1241 never merges adjacent requests into the same packet. OUT transfers 1242 will sometimes use data that's already buffered in the hardware. 1243 Drivers can rely on the fact that the first byte of the request's buffer 1244 always corresponds to the first byte of some USB packet, for both 1245 IN and OUT transfers. 1246 </para><para> 1247 1248 Bulk endpoints can queue any amount of data; the transfer is packetized 1249 automatically. The last packet will be short if the request doesn't fill it 1250 out completely. Zero length packets (ZLPs) should be avoided in portable 1251 protocols since not all usb hardware can successfully handle zero length 1252 packets. (ZLPs may be explicitly written, and may be implicitly written if 1253 the request 'zero' flag is set.) Bulk endpoints may also be used 1254 for interrupt transfers; but the reverse is not true, and some endpoints 1255 won't support every interrupt transfer. (Such as 768 byte packets.) 1256 </para><para> 1257 1258 Interrupt-only endpoints are less functional than bulk endpoints, for 1259 example by not supporting queueing or not handling buffers that are 1260 larger than the endpoint's maxpacket size. They may also treat data 1261 toggle differently. 1262 </para><para> 1263 1264 Control endpoints ... after getting a <function>setup</function> callback, the driver queues 1265 one response (even if it would be zero length). That enables the 1266 status ack, after transferring data as specified in the response. Setup 1267 functions may return negative error codes to generate protocol stalls. 1268 (Note that some USB device controllers disallow protocol stall responses 1269 in some cases.) When control responses are deferred (the response is 1270 written after the setup callback returns), then <function>usb_ep_set_halt</function> may be 1271 used on ep0 to trigger protocol stalls. Depending on the controller, 1272 it may not be possible to trigger a status-stage protocol stall when the 1273 data stage is over, that is, from within the response's completion 1274 routine. 1275 </para><para> 1276 1277 For periodic endpoints, like interrupt or isochronous ones, the usb host 1278 arranges to poll once per interval, and the gadget driver usually will 1279 have queued some data to transfer at that time. 1280 </para><para> 1281 1282 Returns zero, or a negative error code. Endpoints that are not enabled 1283 report errors; errors will also be 1284 reported when the usb peripheral is disconnected. 1285</para> 1286</refsect1> 1287</refentry> 1288 1289<refentry id="API-usb-ep-dequeue"> 1290<refentryinfo> 1291 <title>LINUX</title> 1292 <productname>Kernel Hackers Manual</productname> 1293 <date>July 2017</date> 1294</refentryinfo> 1295<refmeta> 1296 <refentrytitle><phrase>usb_ep_dequeue</phrase></refentrytitle> 1297 <manvolnum>9</manvolnum> 1298 <refmiscinfo class="version">4.1.27</refmiscinfo> 1299</refmeta> 1300<refnamediv> 1301 <refname>usb_ep_dequeue</refname> 1302 <refpurpose> 1303 dequeues (cancels, unlinks) an I/O request from an endpoint 1304 </refpurpose> 1305</refnamediv> 1306<refsynopsisdiv> 1307 <title>Synopsis</title> 1308 <funcsynopsis><funcprototype> 1309 <funcdef>int <function>usb_ep_dequeue </function></funcdef> 1310 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1311 <paramdef>struct usb_request * <parameter>req</parameter></paramdef> 1312 </funcprototype></funcsynopsis> 1313</refsynopsisdiv> 1314<refsect1> 1315 <title>Arguments</title> 1316 <variablelist> 1317 <varlistentry> 1318 <term><parameter>ep</parameter></term> 1319 <listitem> 1320 <para> 1321 the endpoint associated with the request 1322 </para> 1323 </listitem> 1324 </varlistentry> 1325 <varlistentry> 1326 <term><parameter>req</parameter></term> 1327 <listitem> 1328 <para> 1329 the request being canceled 1330 </para> 1331 </listitem> 1332 </varlistentry> 1333 </variablelist> 1334</refsect1> 1335<refsect1> 1336<title>Description</title> 1337<para> 1338 If the request is still active on the endpoint, it is dequeued and its 1339 completion routine is called (with status -ECONNRESET); else a negative 1340 error code is returned. This is guaranteed to happen before the call to 1341 <function>usb_ep_dequeue</function> returns. 1342 </para><para> 1343 1344 Note that some hardware can't clear out write fifos (to unlink the request 1345 at the head of the queue) except as part of disconnecting from usb. Such 1346 restrictions prevent drivers from supporting configuration changes, 1347 even to configuration zero (a <quote>chapter 9</quote> requirement). 1348</para> 1349</refsect1> 1350</refentry> 1351 1352<refentry id="API-usb-ep-set-halt"> 1353<refentryinfo> 1354 <title>LINUX</title> 1355 <productname>Kernel Hackers Manual</productname> 1356 <date>July 2017</date> 1357</refentryinfo> 1358<refmeta> 1359 <refentrytitle><phrase>usb_ep_set_halt</phrase></refentrytitle> 1360 <manvolnum>9</manvolnum> 1361 <refmiscinfo class="version">4.1.27</refmiscinfo> 1362</refmeta> 1363<refnamediv> 1364 <refname>usb_ep_set_halt</refname> 1365 <refpurpose> 1366 sets the endpoint halt feature. 1367 </refpurpose> 1368</refnamediv> 1369<refsynopsisdiv> 1370 <title>Synopsis</title> 1371 <funcsynopsis><funcprototype> 1372 <funcdef>int <function>usb_ep_set_halt </function></funcdef> 1373 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1374 </funcprototype></funcsynopsis> 1375</refsynopsisdiv> 1376<refsect1> 1377 <title>Arguments</title> 1378 <variablelist> 1379 <varlistentry> 1380 <term><parameter>ep</parameter></term> 1381 <listitem> 1382 <para> 1383 the non-isochronous endpoint being stalled 1384 </para> 1385 </listitem> 1386 </varlistentry> 1387 </variablelist> 1388</refsect1> 1389<refsect1> 1390<title>Description</title> 1391<para> 1392 Use this to stall an endpoint, perhaps as an error report. 1393 Except for control endpoints, 1394 the endpoint stays halted (will not stream any data) until the host 1395 clears this feature; drivers may need to empty the endpoint's request 1396 queue first, to make sure no inappropriate transfers happen. 1397 </para><para> 1398 1399 Note that while an endpoint CLEAR_FEATURE will be invisible to the 1400 gadget driver, a SET_INTERFACE will not be. To reset endpoints for the 1401 current altsetting, see <function>usb_ep_clear_halt</function>. When switching altsettings, 1402 it's simplest to use <function>usb_ep_enable</function> or <function>usb_ep_disable</function> for the endpoints. 1403 </para><para> 1404 1405 Returns zero, or a negative error code. On success, this call sets 1406 underlying hardware state that blocks data transfers. 1407 Attempts to halt IN endpoints will fail (returning -EAGAIN) if any 1408 transfer requests are still queued, or if the controller hardware 1409 (usually a FIFO) still holds bytes that the host hasn't collected. 1410</para> 1411</refsect1> 1412</refentry> 1413 1414<refentry id="API-usb-ep-clear-halt"> 1415<refentryinfo> 1416 <title>LINUX</title> 1417 <productname>Kernel Hackers Manual</productname> 1418 <date>July 2017</date> 1419</refentryinfo> 1420<refmeta> 1421 <refentrytitle><phrase>usb_ep_clear_halt</phrase></refentrytitle> 1422 <manvolnum>9</manvolnum> 1423 <refmiscinfo class="version">4.1.27</refmiscinfo> 1424</refmeta> 1425<refnamediv> 1426 <refname>usb_ep_clear_halt</refname> 1427 <refpurpose> 1428 clears endpoint halt, and resets toggle 1429 </refpurpose> 1430</refnamediv> 1431<refsynopsisdiv> 1432 <title>Synopsis</title> 1433 <funcsynopsis><funcprototype> 1434 <funcdef>int <function>usb_ep_clear_halt </function></funcdef> 1435 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1436 </funcprototype></funcsynopsis> 1437</refsynopsisdiv> 1438<refsect1> 1439 <title>Arguments</title> 1440 <variablelist> 1441 <varlistentry> 1442 <term><parameter>ep</parameter></term> 1443 <listitem> 1444 <para> 1445 the bulk or interrupt endpoint being reset 1446 </para> 1447 </listitem> 1448 </varlistentry> 1449 </variablelist> 1450</refsect1> 1451<refsect1> 1452<title>Description</title> 1453<para> 1454 Use this when responding to the standard usb <quote>set interface</quote> request, 1455 for endpoints that aren't reconfigured, after clearing any other state 1456 in the endpoint's i/o queue. 1457 </para><para> 1458 1459 Returns zero, or a negative error code. On success, this call clears 1460 the underlying hardware state reflecting endpoint halt and data toggle. 1461 Note that some hardware can't support this request (like pxa2xx_udc), 1462 and accordingly can't correctly implement interface altsettings. 1463</para> 1464</refsect1> 1465</refentry> 1466 1467<refentry id="API-usb-ep-set-wedge"> 1468<refentryinfo> 1469 <title>LINUX</title> 1470 <productname>Kernel Hackers Manual</productname> 1471 <date>July 2017</date> 1472</refentryinfo> 1473<refmeta> 1474 <refentrytitle><phrase>usb_ep_set_wedge</phrase></refentrytitle> 1475 <manvolnum>9</manvolnum> 1476 <refmiscinfo class="version">4.1.27</refmiscinfo> 1477</refmeta> 1478<refnamediv> 1479 <refname>usb_ep_set_wedge</refname> 1480 <refpurpose> 1481 sets the halt feature and ignores clear requests 1482 </refpurpose> 1483</refnamediv> 1484<refsynopsisdiv> 1485 <title>Synopsis</title> 1486 <funcsynopsis><funcprototype> 1487 <funcdef>int <function>usb_ep_set_wedge </function></funcdef> 1488 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1489 </funcprototype></funcsynopsis> 1490</refsynopsisdiv> 1491<refsect1> 1492 <title>Arguments</title> 1493 <variablelist> 1494 <varlistentry> 1495 <term><parameter>ep</parameter></term> 1496 <listitem> 1497 <para> 1498 the endpoint being wedged 1499 </para> 1500 </listitem> 1501 </varlistentry> 1502 </variablelist> 1503</refsect1> 1504<refsect1> 1505<title>Description</title> 1506<para> 1507 Use this to stall an endpoint and ignore CLEAR_FEATURE(HALT_ENDPOINT) 1508 requests. If the gadget driver clears the halt status, it will 1509 automatically unwedge the endpoint. 1510 </para><para> 1511 1512 Returns zero on success, else negative errno. 1513</para> 1514</refsect1> 1515</refentry> 1516 1517<refentry id="API-usb-ep-fifo-status"> 1518<refentryinfo> 1519 <title>LINUX</title> 1520 <productname>Kernel Hackers Manual</productname> 1521 <date>July 2017</date> 1522</refentryinfo> 1523<refmeta> 1524 <refentrytitle><phrase>usb_ep_fifo_status</phrase></refentrytitle> 1525 <manvolnum>9</manvolnum> 1526 <refmiscinfo class="version">4.1.27</refmiscinfo> 1527</refmeta> 1528<refnamediv> 1529 <refname>usb_ep_fifo_status</refname> 1530 <refpurpose> 1531 returns number of bytes in fifo, or error 1532 </refpurpose> 1533</refnamediv> 1534<refsynopsisdiv> 1535 <title>Synopsis</title> 1536 <funcsynopsis><funcprototype> 1537 <funcdef>int <function>usb_ep_fifo_status </function></funcdef> 1538 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1539 </funcprototype></funcsynopsis> 1540</refsynopsisdiv> 1541<refsect1> 1542 <title>Arguments</title> 1543 <variablelist> 1544 <varlistentry> 1545 <term><parameter>ep</parameter></term> 1546 <listitem> 1547 <para> 1548 the endpoint whose fifo status is being checked. 1549 </para> 1550 </listitem> 1551 </varlistentry> 1552 </variablelist> 1553</refsect1> 1554<refsect1> 1555<title>Description</title> 1556<para> 1557 FIFO endpoints may have <quote>unclaimed data</quote> in them in certain cases, 1558 such as after aborted transfers. Hosts may not have collected all 1559 the IN data written by the gadget driver (and reported by a request 1560 completion). The gadget driver may not have collected all the data 1561 written OUT to it by the host. Drivers that need precise handling for 1562 fault reporting or recovery may need to use this call. 1563 </para><para> 1564 1565 This returns the number of such bytes in the fifo, or a negative 1566 errno if the endpoint doesn't use a FIFO or doesn't support such 1567 precise handling. 1568</para> 1569</refsect1> 1570</refentry> 1571 1572<refentry id="API-usb-ep-fifo-flush"> 1573<refentryinfo> 1574 <title>LINUX</title> 1575 <productname>Kernel Hackers Manual</productname> 1576 <date>July 2017</date> 1577</refentryinfo> 1578<refmeta> 1579 <refentrytitle><phrase>usb_ep_fifo_flush</phrase></refentrytitle> 1580 <manvolnum>9</manvolnum> 1581 <refmiscinfo class="version">4.1.27</refmiscinfo> 1582</refmeta> 1583<refnamediv> 1584 <refname>usb_ep_fifo_flush</refname> 1585 <refpurpose> 1586 flushes contents of a fifo 1587 </refpurpose> 1588</refnamediv> 1589<refsynopsisdiv> 1590 <title>Synopsis</title> 1591 <funcsynopsis><funcprototype> 1592 <funcdef>void <function>usb_ep_fifo_flush </function></funcdef> 1593 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1594 </funcprototype></funcsynopsis> 1595</refsynopsisdiv> 1596<refsect1> 1597 <title>Arguments</title> 1598 <variablelist> 1599 <varlistentry> 1600 <term><parameter>ep</parameter></term> 1601 <listitem> 1602 <para> 1603 the endpoint whose fifo is being flushed. 1604 </para> 1605 </listitem> 1606 </varlistentry> 1607 </variablelist> 1608</refsect1> 1609<refsect1> 1610<title>Description</title> 1611<para> 1612 This call may be used to flush the <quote>unclaimed data</quote> that may exist in 1613 an endpoint fifo after abnormal transaction terminations. The call 1614 must never be used except when endpoint is not being used for any 1615 protocol translation. 1616</para> 1617</refsect1> 1618</refentry> 1619 1620<refentry id="API-struct-usb-gadget"> 1621<refentryinfo> 1622 <title>LINUX</title> 1623 <productname>Kernel Hackers Manual</productname> 1624 <date>July 2017</date> 1625</refentryinfo> 1626<refmeta> 1627 <refentrytitle><phrase>struct usb_gadget</phrase></refentrytitle> 1628 <manvolnum>9</manvolnum> 1629 <refmiscinfo class="version">4.1.27</refmiscinfo> 1630</refmeta> 1631<refnamediv> 1632 <refname>struct usb_gadget</refname> 1633 <refpurpose> 1634 represents a usb slave device 1635 </refpurpose> 1636</refnamediv> 1637<refsynopsisdiv> 1638 <title>Synopsis</title> 1639 <programlisting> 1640struct usb_gadget { 1641 struct work_struct work; 1642 struct usb_udc * udc; 1643 const struct usb_gadget_ops * ops; 1644 struct usb_ep * ep0; 1645 struct list_head ep_list; 1646 enum usb_device_speed speed; 1647 enum usb_device_speed max_speed; 1648 enum usb_device_state state; 1649 const char * name; 1650 struct device dev; 1651 unsigned out_epnum; 1652 unsigned in_epnum; 1653 unsigned sg_supported:1; 1654 unsigned is_otg:1; 1655 unsigned is_a_peripheral:1; 1656 unsigned b_hnp_enable:1; 1657 unsigned a_hnp_support:1; 1658 unsigned a_alt_hnp_support:1; 1659 unsigned quirk_ep_out_aligned_size:1; 1660 unsigned is_selfpowered:1; 1661}; </programlisting> 1662</refsynopsisdiv> 1663 <refsect1> 1664 <title>Members</title> 1665 <variablelist> 1666 <varlistentry> <term>work</term> 1667 <listitem><para> 1668 (internal use) Workqueue to be used for <function>sysfs_notify</function> 1669 </para></listitem> 1670 </varlistentry> 1671 <varlistentry> <term>udc</term> 1672 <listitem><para> 1673 struct usb_udc pointer for this gadget 1674 </para></listitem> 1675 </varlistentry> 1676 <varlistentry> <term>ops</term> 1677 <listitem><para> 1678 Function pointers used to access hardware-specific operations. 1679 </para></listitem> 1680 </varlistentry> 1681 <varlistentry> <term>ep0</term> 1682 <listitem><para> 1683 Endpoint zero, used when reading or writing responses to 1684 driver <function>setup</function> requests 1685 </para></listitem> 1686 </varlistentry> 1687 <varlistentry> <term>ep_list</term> 1688 <listitem><para> 1689 List of other endpoints supported by the device. 1690 </para></listitem> 1691 </varlistentry> 1692 <varlistentry> <term>speed</term> 1693 <listitem><para> 1694 Speed of current connection to USB host. 1695 </para></listitem> 1696 </varlistentry> 1697 <varlistentry> <term>max_speed</term> 1698 <listitem><para> 1699 Maximal speed the UDC can handle. UDC must support this 1700 and all slower speeds. 1701 </para></listitem> 1702 </varlistentry> 1703 <varlistentry> <term>state</term> 1704 <listitem><para> 1705 the state we are now (attached, suspended, configured, etc) 1706 </para></listitem> 1707 </varlistentry> 1708 <varlistentry> <term>name</term> 1709 <listitem><para> 1710 Identifies the controller hardware type. Used in diagnostics 1711 and sometimes configuration. 1712 </para></listitem> 1713 </varlistentry> 1714 <varlistentry> <term>dev</term> 1715 <listitem><para> 1716 Driver model state for this abstract device. 1717 </para></listitem> 1718 </varlistentry> 1719 <varlistentry> <term>out_epnum</term> 1720 <listitem><para> 1721 last used out ep number 1722 </para></listitem> 1723 </varlistentry> 1724 <varlistentry> <term>in_epnum</term> 1725 <listitem><para> 1726 last used in ep number 1727 </para></listitem> 1728 </varlistentry> 1729 <varlistentry> <term>sg_supported</term> 1730 <listitem><para> 1731 true if we can handle scatter-gather 1732 </para></listitem> 1733 </varlistentry> 1734 <varlistentry> <term>is_otg</term> 1735 <listitem><para> 1736 True if the USB device port uses a Mini-AB jack, so that the 1737 gadget driver must provide a USB OTG descriptor. 1738 </para></listitem> 1739 </varlistentry> 1740 <varlistentry> <term>is_a_peripheral</term> 1741 <listitem><para> 1742 False unless is_otg, the <quote>A</quote> end of a USB cable 1743 is in the Mini-AB jack, and HNP has been used to switch roles 1744 so that the <quote>A</quote> device currently acts as A-Peripheral, not A-Host. 1745 </para></listitem> 1746 </varlistentry> 1747 <varlistentry> <term>b_hnp_enable</term> 1748 <listitem><para> 1749 OTG device feature flag, indicating that the A-Host 1750 enabled HNP support. 1751 </para></listitem> 1752 </varlistentry> 1753 <varlistentry> <term>a_hnp_support</term> 1754 <listitem><para> 1755 OTG device feature flag, indicating that the A-Host 1756 supports HNP at this port. 1757 </para></listitem> 1758 </varlistentry> 1759 <varlistentry> <term>a_alt_hnp_support</term> 1760 <listitem><para> 1761 OTG device feature flag, indicating that the A-Host 1762 only supports HNP on a different root port. 1763 </para></listitem> 1764 </varlistentry> 1765 <varlistentry> <term>quirk_ep_out_aligned_size</term> 1766 <listitem><para> 1767 epout requires buffer size to be aligned to 1768 MaxPacketSize. 1769 </para></listitem> 1770 </varlistentry> 1771 <varlistentry> <term>is_selfpowered</term> 1772 <listitem><para> 1773 if the gadget is self-powered. 1774 </para></listitem> 1775 </varlistentry> 1776 </variablelist> 1777 </refsect1> 1778<refsect1> 1779<title>Description</title> 1780<para> 1781 Gadgets have a mostly-portable <quote>gadget driver</quote> implementing device 1782 functions, handling all usb configurations and interfaces. Gadget 1783 drivers talk to hardware-specific code indirectly, through ops vectors. 1784 That insulates the gadget driver from hardware details, and packages 1785 the hardware endpoints through generic i/o queues. The <quote>usb_gadget</quote> 1786 and <quote>usb_ep</quote> interfaces provide that insulation from the hardware. 1787 </para><para> 1788 1789 Except for the driver data, all fields in this structure are 1790 read-only to the gadget driver. That driver data is part of the 1791 <quote>driver model</quote> infrastructure in 2.6 (and later) kernels, and for 1792 earlier systems is grouped in a similar structure that's not known 1793 to the rest of the kernel. 1794 </para><para> 1795 1796 Values of the three OTG device feature flags are updated before the 1797 <function>setup</function> call corresponding to USB_REQ_SET_CONFIGURATION, and before 1798 driver <function>suspend</function> calls. They are valid only when is_otg, and when the 1799 device is acting as a B-Peripheral (so is_a_peripheral is false). 1800</para> 1801</refsect1> 1802</refentry> 1803 1804<refentry id="API-usb-ep-align-maybe"> 1805<refentryinfo> 1806 <title>LINUX</title> 1807 <productname>Kernel Hackers Manual</productname> 1808 <date>July 2017</date> 1809</refentryinfo> 1810<refmeta> 1811 <refentrytitle><phrase>usb_ep_align_maybe</phrase></refentrytitle> 1812 <manvolnum>9</manvolnum> 1813 <refmiscinfo class="version">4.1.27</refmiscinfo> 1814</refmeta> 1815<refnamediv> 1816 <refname>usb_ep_align_maybe</refname> 1817 <refpurpose> 1818 returns <parameter>len</parameter> aligned to ep's maxpacketsize if gadget requires quirk_ep_out_aligned_size, otherwise reguens len. 1819 </refpurpose> 1820</refnamediv> 1821<refsynopsisdiv> 1822 <title>Synopsis</title> 1823 <funcsynopsis><funcprototype> 1824 <funcdef>size_t <function>usb_ep_align_maybe </function></funcdef> 1825 <paramdef>struct usb_gadget * <parameter>g</parameter></paramdef> 1826 <paramdef>struct usb_ep * <parameter>ep</parameter></paramdef> 1827 <paramdef>size_t <parameter>len</parameter></paramdef> 1828 </funcprototype></funcsynopsis> 1829</refsynopsisdiv> 1830<refsect1> 1831 <title>Arguments</title> 1832 <variablelist> 1833 <varlistentry> 1834 <term><parameter>g</parameter></term> 1835 <listitem> 1836 <para> 1837 controller to check for quirk 1838 </para> 1839 </listitem> 1840 </varlistentry> 1841 <varlistentry> 1842 <term><parameter>ep</parameter></term> 1843 <listitem> 1844 <para> 1845 the endpoint whose maxpacketsize is used to align <parameter>len</parameter> 1846 </para> 1847 </listitem> 1848 </varlistentry> 1849 <varlistentry> 1850 <term><parameter>len</parameter></term> 1851 <listitem> 1852 <para> 1853 buffer size's length to align to <parameter>ep</parameter>'s maxpacketsize 1854 </para> 1855 </listitem> 1856 </varlistentry> 1857 </variablelist> 1858</refsect1> 1859<refsect1> 1860<title>Description</title> 1861<para> 1862 This helper is used in case it's required for any reason to check and maybe 1863 align buffer's size to an ep's maxpacketsize. 1864</para> 1865</refsect1> 1866</refentry> 1867 1868<refentry id="API-gadget-is-dualspeed"> 1869<refentryinfo> 1870 <title>LINUX</title> 1871 <productname>Kernel Hackers Manual</productname> 1872 <date>July 2017</date> 1873</refentryinfo> 1874<refmeta> 1875 <refentrytitle><phrase>gadget_is_dualspeed</phrase></refentrytitle> 1876 <manvolnum>9</manvolnum> 1877 <refmiscinfo class="version">4.1.27</refmiscinfo> 1878</refmeta> 1879<refnamediv> 1880 <refname>gadget_is_dualspeed</refname> 1881 <refpurpose> 1882 return true iff the hardware handles high speed 1883 </refpurpose> 1884</refnamediv> 1885<refsynopsisdiv> 1886 <title>Synopsis</title> 1887 <funcsynopsis><funcprototype> 1888 <funcdef>int <function>gadget_is_dualspeed </function></funcdef> 1889 <paramdef>struct usb_gadget * <parameter>g</parameter></paramdef> 1890 </funcprototype></funcsynopsis> 1891</refsynopsisdiv> 1892<refsect1> 1893 <title>Arguments</title> 1894 <variablelist> 1895 <varlistentry> 1896 <term><parameter>g</parameter></term> 1897 <listitem> 1898 <para> 1899 controller that might support both high and full speeds 1900 </para> 1901 </listitem> 1902 </varlistentry> 1903 </variablelist> 1904</refsect1> 1905</refentry> 1906 1907<refentry id="API-gadget-is-superspeed"> 1908<refentryinfo> 1909 <title>LINUX</title> 1910 <productname>Kernel Hackers Manual</productname> 1911 <date>July 2017</date> 1912</refentryinfo> 1913<refmeta> 1914 <refentrytitle><phrase>gadget_is_superspeed</phrase></refentrytitle> 1915 <manvolnum>9</manvolnum> 1916 <refmiscinfo class="version">4.1.27</refmiscinfo> 1917</refmeta> 1918<refnamediv> 1919 <refname>gadget_is_superspeed</refname> 1920 <refpurpose> 1921 return true if the hardware handles superspeed 1922 </refpurpose> 1923</refnamediv> 1924<refsynopsisdiv> 1925 <title>Synopsis</title> 1926 <funcsynopsis><funcprototype> 1927 <funcdef>int <function>gadget_is_superspeed </function></funcdef> 1928 <paramdef>struct usb_gadget * <parameter>g</parameter></paramdef> 1929 </funcprototype></funcsynopsis> 1930</refsynopsisdiv> 1931<refsect1> 1932 <title>Arguments</title> 1933 <variablelist> 1934 <varlistentry> 1935 <term><parameter>g</parameter></term> 1936 <listitem> 1937 <para> 1938 controller that might support superspeed 1939 </para> 1940 </listitem> 1941 </varlistentry> 1942 </variablelist> 1943</refsect1> 1944</refentry> 1945 1946<refentry id="API-gadget-is-otg"> 1947<refentryinfo> 1948 <title>LINUX</title> 1949 <productname>Kernel Hackers Manual</productname> 1950 <date>July 2017</date> 1951</refentryinfo> 1952<refmeta> 1953 <refentrytitle><phrase>gadget_is_otg</phrase></refentrytitle> 1954 <manvolnum>9</manvolnum> 1955 <refmiscinfo class="version">4.1.27</refmiscinfo> 1956</refmeta> 1957<refnamediv> 1958 <refname>gadget_is_otg</refname> 1959 <refpurpose> 1960 return true iff the hardware is OTG-ready 1961 </refpurpose> 1962</refnamediv> 1963<refsynopsisdiv> 1964 <title>Synopsis</title> 1965 <funcsynopsis><funcprototype> 1966 <funcdef>int <function>gadget_is_otg </function></funcdef> 1967 <paramdef>struct usb_gadget * <parameter>g</parameter></paramdef> 1968 </funcprototype></funcsynopsis> 1969</refsynopsisdiv> 1970<refsect1> 1971 <title>Arguments</title> 1972 <variablelist> 1973 <varlistentry> 1974 <term><parameter>g</parameter></term> 1975 <listitem> 1976 <para> 1977 controller that might have a Mini-AB connector 1978 </para> 1979 </listitem> 1980 </varlistentry> 1981 </variablelist> 1982</refsect1> 1983<refsect1> 1984<title>Description</title> 1985<para> 1986 This is a runtime test, since kernels with a USB-OTG stack sometimes 1987 run on boards which only have a Mini-B (or Mini-A) connector. 1988</para> 1989</refsect1> 1990</refentry> 1991 1992<refentry id="API-usb-gadget-frame-number"> 1993<refentryinfo> 1994 <title>LINUX</title> 1995 <productname>Kernel Hackers Manual</productname> 1996 <date>July 2017</date> 1997</refentryinfo> 1998<refmeta> 1999 <refentrytitle><phrase>usb_gadget_frame_number</phrase></refentrytitle> 2000 <manvolnum>9</manvolnum> 2001 <refmiscinfo class="version">4.1.27</refmiscinfo> 2002</refmeta> 2003<refnamediv> 2004 <refname>usb_gadget_frame_number</refname> 2005 <refpurpose> 2006 returns the current frame number 2007 </refpurpose> 2008</refnamediv> 2009<refsynopsisdiv> 2010 <title>Synopsis</title> 2011 <funcsynopsis><funcprototype> 2012 <funcdef>int <function>usb_gadget_frame_number </function></funcdef> 2013 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2014 </funcprototype></funcsynopsis> 2015</refsynopsisdiv> 2016<refsect1> 2017 <title>Arguments</title> 2018 <variablelist> 2019 <varlistentry> 2020 <term><parameter>gadget</parameter></term> 2021 <listitem> 2022 <para> 2023 controller that reports the frame number 2024 </para> 2025 </listitem> 2026 </varlistentry> 2027 </variablelist> 2028</refsect1> 2029<refsect1> 2030<title>Description</title> 2031<para> 2032 Returns the usb frame number, normally eleven bits from a SOF packet, 2033 or negative errno if this device doesn't support this capability. 2034</para> 2035</refsect1> 2036</refentry> 2037 2038<refentry id="API-usb-gadget-wakeup"> 2039<refentryinfo> 2040 <title>LINUX</title> 2041 <productname>Kernel Hackers Manual</productname> 2042 <date>July 2017</date> 2043</refentryinfo> 2044<refmeta> 2045 <refentrytitle><phrase>usb_gadget_wakeup</phrase></refentrytitle> 2046 <manvolnum>9</manvolnum> 2047 <refmiscinfo class="version">4.1.27</refmiscinfo> 2048</refmeta> 2049<refnamediv> 2050 <refname>usb_gadget_wakeup</refname> 2051 <refpurpose> 2052 tries to wake up the host connected to this gadget 2053 </refpurpose> 2054</refnamediv> 2055<refsynopsisdiv> 2056 <title>Synopsis</title> 2057 <funcsynopsis><funcprototype> 2058 <funcdef>int <function>usb_gadget_wakeup </function></funcdef> 2059 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2060 </funcprototype></funcsynopsis> 2061</refsynopsisdiv> 2062<refsect1> 2063 <title>Arguments</title> 2064 <variablelist> 2065 <varlistentry> 2066 <term><parameter>gadget</parameter></term> 2067 <listitem> 2068 <para> 2069 controller used to wake up the host 2070 </para> 2071 </listitem> 2072 </varlistentry> 2073 </variablelist> 2074</refsect1> 2075<refsect1> 2076<title>Description</title> 2077<para> 2078 Returns zero on success, else negative error code if the hardware 2079 doesn't support such attempts, or its support has not been enabled 2080 by the usb host. Drivers must return device descriptors that report 2081 their ability to support this, or hosts won't enable it. 2082 </para><para> 2083 2084 This may also try to use SRP to wake the host and start enumeration, 2085 even if OTG isn't otherwise in use. OTG devices may also start 2086 remote wakeup even when hosts don't explicitly enable it. 2087</para> 2088</refsect1> 2089</refentry> 2090 2091<refentry id="API-usb-gadget-set-selfpowered"> 2092<refentryinfo> 2093 <title>LINUX</title> 2094 <productname>Kernel Hackers Manual</productname> 2095 <date>July 2017</date> 2096</refentryinfo> 2097<refmeta> 2098 <refentrytitle><phrase>usb_gadget_set_selfpowered</phrase></refentrytitle> 2099 <manvolnum>9</manvolnum> 2100 <refmiscinfo class="version">4.1.27</refmiscinfo> 2101</refmeta> 2102<refnamediv> 2103 <refname>usb_gadget_set_selfpowered</refname> 2104 <refpurpose> 2105 sets the device selfpowered feature. 2106 </refpurpose> 2107</refnamediv> 2108<refsynopsisdiv> 2109 <title>Synopsis</title> 2110 <funcsynopsis><funcprototype> 2111 <funcdef>int <function>usb_gadget_set_selfpowered </function></funcdef> 2112 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2113 </funcprototype></funcsynopsis> 2114</refsynopsisdiv> 2115<refsect1> 2116 <title>Arguments</title> 2117 <variablelist> 2118 <varlistentry> 2119 <term><parameter>gadget</parameter></term> 2120 <listitem> 2121 <para> 2122 the device being declared as self-powered 2123 </para> 2124 </listitem> 2125 </varlistentry> 2126 </variablelist> 2127</refsect1> 2128<refsect1> 2129<title>Description</title> 2130<para> 2131 this affects the device status reported by the hardware driver 2132 to reflect that it now has a local power supply. 2133 </para><para> 2134 2135 returns zero on success, else negative errno. 2136</para> 2137</refsect1> 2138</refentry> 2139 2140<refentry id="API-usb-gadget-clear-selfpowered"> 2141<refentryinfo> 2142 <title>LINUX</title> 2143 <productname>Kernel Hackers Manual</productname> 2144 <date>July 2017</date> 2145</refentryinfo> 2146<refmeta> 2147 <refentrytitle><phrase>usb_gadget_clear_selfpowered</phrase></refentrytitle> 2148 <manvolnum>9</manvolnum> 2149 <refmiscinfo class="version">4.1.27</refmiscinfo> 2150</refmeta> 2151<refnamediv> 2152 <refname>usb_gadget_clear_selfpowered</refname> 2153 <refpurpose> 2154 clear the device selfpowered feature. 2155 </refpurpose> 2156</refnamediv> 2157<refsynopsisdiv> 2158 <title>Synopsis</title> 2159 <funcsynopsis><funcprototype> 2160 <funcdef>int <function>usb_gadget_clear_selfpowered </function></funcdef> 2161 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2162 </funcprototype></funcsynopsis> 2163</refsynopsisdiv> 2164<refsect1> 2165 <title>Arguments</title> 2166 <variablelist> 2167 <varlistentry> 2168 <term><parameter>gadget</parameter></term> 2169 <listitem> 2170 <para> 2171 the device being declared as bus-powered 2172 </para> 2173 </listitem> 2174 </varlistentry> 2175 </variablelist> 2176</refsect1> 2177<refsect1> 2178<title>Description</title> 2179<para> 2180 this affects the device status reported by the hardware driver. 2181 some hardware may not support bus-powered operation, in which 2182 case this feature's value can never change. 2183 </para><para> 2184 2185 returns zero on success, else negative errno. 2186</para> 2187</refsect1> 2188</refentry> 2189 2190<refentry id="API-usb-gadget-vbus-connect"> 2191<refentryinfo> 2192 <title>LINUX</title> 2193 <productname>Kernel Hackers Manual</productname> 2194 <date>July 2017</date> 2195</refentryinfo> 2196<refmeta> 2197 <refentrytitle><phrase>usb_gadget_vbus_connect</phrase></refentrytitle> 2198 <manvolnum>9</manvolnum> 2199 <refmiscinfo class="version">4.1.27</refmiscinfo> 2200</refmeta> 2201<refnamediv> 2202 <refname>usb_gadget_vbus_connect</refname> 2203 <refpurpose> 2204 Notify controller that VBUS is powered 2205 </refpurpose> 2206</refnamediv> 2207<refsynopsisdiv> 2208 <title>Synopsis</title> 2209 <funcsynopsis><funcprototype> 2210 <funcdef>int <function>usb_gadget_vbus_connect </function></funcdef> 2211 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2212 </funcprototype></funcsynopsis> 2213</refsynopsisdiv> 2214<refsect1> 2215 <title>Arguments</title> 2216 <variablelist> 2217 <varlistentry> 2218 <term><parameter>gadget</parameter></term> 2219 <listitem> 2220 <para> 2221 The device which now has VBUS power. 2222 </para> 2223 </listitem> 2224 </varlistentry> 2225 </variablelist> 2226</refsect1> 2227<refsect1> 2228<title>Context</title> 2229<para> 2230 can sleep 2231</para> 2232</refsect1> 2233<refsect1> 2234<title>Description</title> 2235<para> 2236 This call is used by a driver for an external transceiver (or GPIO) 2237 that detects a VBUS power session starting. Common responses include 2238 resuming the controller, activating the D+ (or D-) pullup to let the 2239 host detect that a USB device is attached, and starting to draw power 2240 (8mA or possibly more, especially after SET_CONFIGURATION). 2241 </para><para> 2242 2243 Returns zero on success, else negative errno. 2244</para> 2245</refsect1> 2246</refentry> 2247 2248<refentry id="API-usb-gadget-vbus-draw"> 2249<refentryinfo> 2250 <title>LINUX</title> 2251 <productname>Kernel Hackers Manual</productname> 2252 <date>July 2017</date> 2253</refentryinfo> 2254<refmeta> 2255 <refentrytitle><phrase>usb_gadget_vbus_draw</phrase></refentrytitle> 2256 <manvolnum>9</manvolnum> 2257 <refmiscinfo class="version">4.1.27</refmiscinfo> 2258</refmeta> 2259<refnamediv> 2260 <refname>usb_gadget_vbus_draw</refname> 2261 <refpurpose> 2262 constrain controller's VBUS power usage 2263 </refpurpose> 2264</refnamediv> 2265<refsynopsisdiv> 2266 <title>Synopsis</title> 2267 <funcsynopsis><funcprototype> 2268 <funcdef>int <function>usb_gadget_vbus_draw </function></funcdef> 2269 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2270 <paramdef>unsigned <parameter>mA</parameter></paramdef> 2271 </funcprototype></funcsynopsis> 2272</refsynopsisdiv> 2273<refsect1> 2274 <title>Arguments</title> 2275 <variablelist> 2276 <varlistentry> 2277 <term><parameter>gadget</parameter></term> 2278 <listitem> 2279 <para> 2280 The device whose VBUS usage is being described 2281 </para> 2282 </listitem> 2283 </varlistentry> 2284 <varlistentry> 2285 <term><parameter>mA</parameter></term> 2286 <listitem> 2287 <para> 2288 How much current to draw, in milliAmperes. This should be twice 2289 the value listed in the configuration descriptor bMaxPower field. 2290 </para> 2291 </listitem> 2292 </varlistentry> 2293 </variablelist> 2294</refsect1> 2295<refsect1> 2296<title>Description</title> 2297<para> 2298 This call is used by gadget drivers during SET_CONFIGURATION calls, 2299 reporting how much power the device may consume. For example, this 2300 could affect how quickly batteries are recharged. 2301 </para><para> 2302 2303 Returns zero on success, else negative errno. 2304</para> 2305</refsect1> 2306</refentry> 2307 2308<refentry id="API-usb-gadget-vbus-disconnect"> 2309<refentryinfo> 2310 <title>LINUX</title> 2311 <productname>Kernel Hackers Manual</productname> 2312 <date>July 2017</date> 2313</refentryinfo> 2314<refmeta> 2315 <refentrytitle><phrase>usb_gadget_vbus_disconnect</phrase></refentrytitle> 2316 <manvolnum>9</manvolnum> 2317 <refmiscinfo class="version">4.1.27</refmiscinfo> 2318</refmeta> 2319<refnamediv> 2320 <refname>usb_gadget_vbus_disconnect</refname> 2321 <refpurpose> 2322 notify controller about VBUS session end 2323 </refpurpose> 2324</refnamediv> 2325<refsynopsisdiv> 2326 <title>Synopsis</title> 2327 <funcsynopsis><funcprototype> 2328 <funcdef>int <function>usb_gadget_vbus_disconnect </function></funcdef> 2329 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2330 </funcprototype></funcsynopsis> 2331</refsynopsisdiv> 2332<refsect1> 2333 <title>Arguments</title> 2334 <variablelist> 2335 <varlistentry> 2336 <term><parameter>gadget</parameter></term> 2337 <listitem> 2338 <para> 2339 the device whose VBUS supply is being described 2340 </para> 2341 </listitem> 2342 </varlistentry> 2343 </variablelist> 2344</refsect1> 2345<refsect1> 2346<title>Context</title> 2347<para> 2348 can sleep 2349</para> 2350</refsect1> 2351<refsect1> 2352<title>Description</title> 2353<para> 2354 This call is used by a driver for an external transceiver (or GPIO) 2355 that detects a VBUS power session ending. Common responses include 2356 reversing everything done in <function>usb_gadget_vbus_connect</function>. 2357 </para><para> 2358 2359 Returns zero on success, else negative errno. 2360</para> 2361</refsect1> 2362</refentry> 2363 2364<refentry id="API-usb-gadget-connect"> 2365<refentryinfo> 2366 <title>LINUX</title> 2367 <productname>Kernel Hackers Manual</productname> 2368 <date>July 2017</date> 2369</refentryinfo> 2370<refmeta> 2371 <refentrytitle><phrase>usb_gadget_connect</phrase></refentrytitle> 2372 <manvolnum>9</manvolnum> 2373 <refmiscinfo class="version">4.1.27</refmiscinfo> 2374</refmeta> 2375<refnamediv> 2376 <refname>usb_gadget_connect</refname> 2377 <refpurpose> 2378 software-controlled connect to USB host 2379 </refpurpose> 2380</refnamediv> 2381<refsynopsisdiv> 2382 <title>Synopsis</title> 2383 <funcsynopsis><funcprototype> 2384 <funcdef>int <function>usb_gadget_connect </function></funcdef> 2385 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2386 </funcprototype></funcsynopsis> 2387</refsynopsisdiv> 2388<refsect1> 2389 <title>Arguments</title> 2390 <variablelist> 2391 <varlistentry> 2392 <term><parameter>gadget</parameter></term> 2393 <listitem> 2394 <para> 2395 the peripheral being connected 2396 </para> 2397 </listitem> 2398 </varlistentry> 2399 </variablelist> 2400</refsect1> 2401<refsect1> 2402<title>Description</title> 2403<para> 2404 Enables the D+ (or potentially D-) pullup. The host will start 2405 enumerating this gadget when the pullup is active and a VBUS session 2406 is active (the link is powered). This pullup is always enabled unless 2407 <function>usb_gadget_disconnect</function> has been used to disable it. 2408 </para><para> 2409 2410 Returns zero on success, else negative errno. 2411</para> 2412</refsect1> 2413</refentry> 2414 2415<refentry id="API-usb-gadget-disconnect"> 2416<refentryinfo> 2417 <title>LINUX</title> 2418 <productname>Kernel Hackers Manual</productname> 2419 <date>July 2017</date> 2420</refentryinfo> 2421<refmeta> 2422 <refentrytitle><phrase>usb_gadget_disconnect</phrase></refentrytitle> 2423 <manvolnum>9</manvolnum> 2424 <refmiscinfo class="version">4.1.27</refmiscinfo> 2425</refmeta> 2426<refnamediv> 2427 <refname>usb_gadget_disconnect</refname> 2428 <refpurpose> 2429 software-controlled disconnect from USB host 2430 </refpurpose> 2431</refnamediv> 2432<refsynopsisdiv> 2433 <title>Synopsis</title> 2434 <funcsynopsis><funcprototype> 2435 <funcdef>int <function>usb_gadget_disconnect </function></funcdef> 2436 <paramdef>struct usb_gadget * <parameter>gadget</parameter></paramdef> 2437 </funcprototype></funcsynopsis> 2438</refsynopsisdiv> 2439<refsect1> 2440 <title>Arguments</title> 2441 <variablelist> 2442 <varlistentry> 2443 <term><parameter>gadget</parameter></term> 2444 <listitem> 2445 <para> 2446 the peripheral being disconnected 2447 </para> 2448 </listitem> 2449 </varlistentry> 2450 </variablelist> 2451</refsect1> 2452<refsect1> 2453<title>Description</title> 2454<para> 2455 Disables the D+ (or potentially D-) pullup, which the host may see 2456 as a disconnect (when a VBUS session is active). Not all systems 2457 support software pullup controls. 2458 </para><para> 2459 2460 This routine may be used during the gadget driver <function>bind</function> call to prevent 2461 the peripheral from ever being visible to the USB host, unless later 2462 <function>usb_gadget_connect</function> is called. For example, user mode components may 2463 need to be activated before the system can talk to hosts. 2464 </para><para> 2465 2466 Returns zero on success, else negative errno. 2467</para> 2468</refsect1> 2469</refentry> 2470 2471<refentry id="API-struct-usb-gadget-driver"> 2472<refentryinfo> 2473 <title>LINUX</title> 2474 <productname>Kernel Hackers Manual</productname> 2475 <date>July 2017</date> 2476</refentryinfo> 2477<refmeta> 2478 <refentrytitle><phrase>struct usb_gadget_driver</phrase></refentrytitle> 2479 <manvolnum>9</manvolnum> 2480 <refmiscinfo class="version">4.1.27</refmiscinfo> 2481</refmeta> 2482<refnamediv> 2483 <refname>struct usb_gadget_driver</refname> 2484 <refpurpose> 2485 driver for usb 'slave' devices 2486 </refpurpose> 2487</refnamediv> 2488<refsynopsisdiv> 2489 <title>Synopsis</title> 2490 <programlisting> 2491struct usb_gadget_driver { 2492 char * function; 2493 enum usb_device_speed max_speed; 2494 int (* bind) (struct usb_gadget *gadget,struct usb_gadget_driver *driver); 2495 void (* unbind) (struct usb_gadget *); 2496 int (* setup) (struct usb_gadget *,const struct usb_ctrlrequest *); 2497 void (* disconnect) (struct usb_gadget *); 2498 void (* suspend) (struct usb_gadget *); 2499 void (* resume) (struct usb_gadget *); 2500 void (* reset) (struct usb_gadget *); 2501 struct device_driver driver; 2502}; </programlisting> 2503</refsynopsisdiv> 2504 <refsect1> 2505 <title>Members</title> 2506 <variablelist> 2507 <varlistentry> <term>function</term> 2508 <listitem><para> 2509 String describing the gadget's function 2510 </para></listitem> 2511 </varlistentry> 2512 <varlistentry> <term>max_speed</term> 2513 <listitem><para> 2514 Highest speed the driver handles. 2515 </para></listitem> 2516 </varlistentry> 2517 <varlistentry> <term>bind</term> 2518 <listitem><para> 2519 the driver's bind callback 2520 </para></listitem> 2521 </varlistentry> 2522 <varlistentry> <term>unbind</term> 2523 <listitem><para> 2524 Invoked when the driver is unbound from a gadget, 2525 usually from rmmod (after a disconnect is reported). 2526 Called in a context that permits sleeping. 2527 </para></listitem> 2528 </varlistentry> 2529 <varlistentry> <term>setup</term> 2530 <listitem><para> 2531 Invoked for ep0 control requests that aren't handled by 2532 the hardware level driver. Most calls must be handled by 2533 the gadget driver, including descriptor and configuration 2534 management. The 16 bit members of the setup data are in 2535 USB byte order. Called in_interrupt; this may not sleep. Driver 2536 queues a response to ep0, or returns negative to stall. 2537 </para></listitem> 2538 </varlistentry> 2539 <varlistentry> <term>disconnect</term> 2540 <listitem><para> 2541 Invoked after all transfers have been stopped, 2542 when the host is disconnected. May be called in_interrupt; this 2543 may not sleep. Some devices can't detect disconnect, so this might 2544 not be called except as part of controller shutdown. 2545 </para></listitem> 2546 </varlistentry> 2547 <varlistentry> <term>suspend</term> 2548 <listitem><para> 2549 Invoked on USB suspend. May be called in_interrupt. 2550 </para></listitem> 2551 </varlistentry> 2552 <varlistentry> <term>resume</term> 2553 <listitem><para> 2554 Invoked on USB resume. May be called in_interrupt. 2555 </para></listitem> 2556 </varlistentry> 2557 <varlistentry> <term>reset</term> 2558 <listitem><para> 2559 Invoked on USB bus reset. It is mandatory for all gadget drivers 2560 and should be called in_interrupt. 2561 </para></listitem> 2562 </varlistentry> 2563 <varlistentry> <term>driver</term> 2564 <listitem><para> 2565 Driver model state for this driver. 2566 </para></listitem> 2567 </varlistentry> 2568 </variablelist> 2569 </refsect1> 2570<refsect1> 2571<title>Description</title> 2572<para> 2573 Devices are disabled till a gadget driver successfully <function>bind</function>s, which 2574 means the driver will handle <function>setup</function> requests needed to enumerate (and 2575 meet <quote>chapter 9</quote> requirements) then do some useful work. 2576 </para><para> 2577 2578 If gadget->is_otg is true, the gadget driver must provide an OTG 2579 descriptor during enumeration, or else fail the <function>bind</function> call. In such 2580 cases, no USB traffic may flow until both <function>bind</function> returns without 2581 having called <function>usb_gadget_disconnect</function>, and the USB host stack has 2582 initialized. 2583 </para><para> 2584 2585 Drivers use hardware-specific knowledge to configure the usb hardware. 2586 endpoint addressing is only one of several hardware characteristics that 2587 are in descriptors the ep0 implementation returns from <function>setup</function> calls. 2588 </para><para> 2589 2590 Except for ep0 implementation, most driver code shouldn't need change to 2591 run on top of different usb controllers. It'll use endpoints set up by 2592 that ep0 implementation. 2593 </para><para> 2594 2595 The usb controller driver handles a few standard usb requests. Those 2596 include set_address, and feature flags for devices, interfaces, and 2597 endpoints (the get_status, set_feature, and clear_feature requests). 2598 </para><para> 2599 2600 Accordingly, the driver's <function>setup</function> callback must always implement all 2601 get_descriptor requests, returning at least a device descriptor and 2602 a configuration descriptor. Drivers must make sure the endpoint 2603 descriptors match any hardware constraints. Some hardware also constrains 2604 other descriptors. (The pxa250 allows only configurations 1, 2, or 3). 2605 </para><para> 2606 2607 The driver's <function>setup</function> callback must also implement set_configuration, 2608 and should also implement set_interface, get_configuration, and 2609 get_interface. Setting a configuration (or interface) is where 2610 endpoints should be activated or (config 0) shut down. 2611 </para><para> 2612 2613 (Note that only the default control endpoint is supported. Neither 2614 hosts nor devices generally support control traffic except to ep0.) 2615 </para><para> 2616 2617 Most devices will ignore USB suspend/resume operations, and so will 2618 not provide those callbacks. However, some may need to change modes 2619 when the host is not longer directing those activities. For example, 2620 local controls (buttons, dials, etc) may need to be re-enabled since 2621 the (remote) host can't do that any longer; or an error state might 2622 be cleared, to make the device behave identically whether or not 2623 power is maintained. 2624</para> 2625</refsect1> 2626</refentry> 2627 2628<refentry id="API-usb-gadget-probe-driver"> 2629<refentryinfo> 2630 <title>LINUX</title> 2631 <productname>Kernel Hackers Manual</productname> 2632 <date>July 2017</date> 2633</refentryinfo> 2634<refmeta> 2635 <refentrytitle><phrase>usb_gadget_probe_driver</phrase></refentrytitle> 2636 <manvolnum>9</manvolnum> 2637 <refmiscinfo class="version">4.1.27</refmiscinfo> 2638</refmeta> 2639<refnamediv> 2640 <refname>usb_gadget_probe_driver</refname> 2641 <refpurpose> 2642 probe a gadget driver 2643 </refpurpose> 2644</refnamediv> 2645<refsynopsisdiv> 2646 <title>Synopsis</title> 2647 <funcsynopsis><funcprototype> 2648 <funcdef>int <function>usb_gadget_probe_driver </function></funcdef> 2649 <paramdef>struct usb_gadget_driver * <parameter>driver</parameter></paramdef> 2650 </funcprototype></funcsynopsis> 2651</refsynopsisdiv> 2652<refsect1> 2653 <title>Arguments</title> 2654 <variablelist> 2655 <varlistentry> 2656 <term><parameter>driver</parameter></term> 2657 <listitem> 2658 <para> 2659 the driver being registered 2660 </para> 2661 </listitem> 2662 </varlistentry> 2663 </variablelist> 2664</refsect1> 2665<refsect1> 2666<title>Context</title> 2667<para> 2668 can sleep 2669</para> 2670</refsect1> 2671<refsect1> 2672<title>Description</title> 2673<para> 2674 Call this in your gadget driver's module initialization function, 2675 to tell the underlying usb controller driver about your driver. 2676 The @<function>bind</function> function will be called to bind it to a gadget before this 2677 registration call returns. It's expected that the @<function>bind</function> function will 2678 be in init sections. 2679</para> 2680</refsect1> 2681</refentry> 2682 2683<refentry id="API-usb-gadget-unregister-driver"> 2684<refentryinfo> 2685 <title>LINUX</title> 2686 <productname>Kernel Hackers Manual</productname> 2687 <date>July 2017</date> 2688</refentryinfo> 2689<refmeta> 2690 <refentrytitle><phrase>usb_gadget_unregister_driver</phrase></refentrytitle> 2691 <manvolnum>9</manvolnum> 2692 <refmiscinfo class="version">4.1.27</refmiscinfo> 2693</refmeta> 2694<refnamediv> 2695 <refname>usb_gadget_unregister_driver</refname> 2696 <refpurpose> 2697 unregister a gadget driver 2698 </refpurpose> 2699</refnamediv> 2700<refsynopsisdiv> 2701 <title>Synopsis</title> 2702 <funcsynopsis><funcprototype> 2703 <funcdef>int <function>usb_gadget_unregister_driver </function></funcdef> 2704 <paramdef>struct usb_gadget_driver * <parameter>driver</parameter></paramdef> 2705 </funcprototype></funcsynopsis> 2706</refsynopsisdiv> 2707<refsect1> 2708 <title>Arguments</title> 2709 <variablelist> 2710 <varlistentry> 2711 <term><parameter>driver</parameter></term> 2712 <listitem> 2713 <para> 2714 the driver being unregistered 2715 </para> 2716 </listitem> 2717 </varlistentry> 2718 </variablelist> 2719</refsect1> 2720<refsect1> 2721<title>Context</title> 2722<para> 2723 can sleep 2724</para> 2725</refsect1> 2726<refsect1> 2727<title>Description</title> 2728<para> 2729 Call this in your gadget driver's module cleanup function, 2730 to tell the underlying usb controller that your driver is 2731 going away. If the controller is connected to a USB host, 2732 it will first <function>disconnect</function>. The driver is also requested 2733 to <function>unbind</function> and clean up any device state, before this procedure 2734 finally returns. It's expected that the <function>unbind</function> functions 2735 will in in exit sections, so may not be linked in some kernels. 2736</para> 2737</refsect1> 2738</refentry> 2739 2740<refentry id="API-struct-usb-string"> 2741<refentryinfo> 2742 <title>LINUX</title> 2743 <productname>Kernel Hackers Manual</productname> 2744 <date>July 2017</date> 2745</refentryinfo> 2746<refmeta> 2747 <refentrytitle><phrase>struct usb_string</phrase></refentrytitle> 2748 <manvolnum>9</manvolnum> 2749 <refmiscinfo class="version">4.1.27</refmiscinfo> 2750</refmeta> 2751<refnamediv> 2752 <refname>struct usb_string</refname> 2753 <refpurpose> 2754 wraps a C string and its USB id 2755 </refpurpose> 2756</refnamediv> 2757<refsynopsisdiv> 2758 <title>Synopsis</title> 2759 <programlisting> 2760struct usb_string { 2761 u8 id; 2762 const char * s; 2763}; </programlisting> 2764</refsynopsisdiv> 2765 <refsect1> 2766 <title>Members</title> 2767 <variablelist> 2768 <varlistentry> <term>id</term> 2769 <listitem><para> 2770 the (nonzero) ID for this string 2771 </para></listitem> 2772 </varlistentry> 2773 <varlistentry> <term>s</term> 2774 <listitem><para> 2775 the string, in UTF-8 encoding 2776 </para></listitem> 2777 </varlistentry> 2778 </variablelist> 2779 </refsect1> 2780<refsect1> 2781<title>Description</title> 2782<para> 2783 If you're using <function>usb_gadget_get_string</function>, use this to wrap a string 2784 together with its ID. 2785</para> 2786</refsect1> 2787</refentry> 2788 2789<refentry id="API-struct-usb-gadget-strings"> 2790<refentryinfo> 2791 <title>LINUX</title> 2792 <productname>Kernel Hackers Manual</productname> 2793 <date>July 2017</date> 2794</refentryinfo> 2795<refmeta> 2796 <refentrytitle><phrase>struct usb_gadget_strings</phrase></refentrytitle> 2797 <manvolnum>9</manvolnum> 2798 <refmiscinfo class="version">4.1.27</refmiscinfo> 2799</refmeta> 2800<refnamediv> 2801 <refname>struct usb_gadget_strings</refname> 2802 <refpurpose> 2803 a set of USB strings in a given language 2804 </refpurpose> 2805</refnamediv> 2806<refsynopsisdiv> 2807 <title>Synopsis</title> 2808 <programlisting> 2809struct usb_gadget_strings { 2810 u16 language; 2811 struct usb_string * strings; 2812}; </programlisting> 2813</refsynopsisdiv> 2814 <refsect1> 2815 <title>Members</title> 2816 <variablelist> 2817 <varlistentry> <term>language</term> 2818 <listitem><para> 2819 identifies the strings' language (0x0409 for en-us) 2820 </para></listitem> 2821 </varlistentry> 2822 <varlistentry> <term>strings</term> 2823 <listitem><para> 2824 array of strings with their ids 2825 </para></listitem> 2826 </varlistentry> 2827 </variablelist> 2828 </refsect1> 2829<refsect1> 2830<title>Description</title> 2831<para> 2832 If you're using <function>usb_gadget_get_string</function>, use this to wrap all the 2833 strings for a given language. 2834</para> 2835</refsect1> 2836</refentry> 2837 2838<refentry id="API-usb-free-descriptors"> 2839<refentryinfo> 2840 <title>LINUX</title> 2841 <productname>Kernel Hackers Manual</productname> 2842 <date>July 2017</date> 2843</refentryinfo> 2844<refmeta> 2845 <refentrytitle><phrase>usb_free_descriptors</phrase></refentrytitle> 2846 <manvolnum>9</manvolnum> 2847 <refmiscinfo class="version">4.1.27</refmiscinfo> 2848</refmeta> 2849<refnamediv> 2850 <refname>usb_free_descriptors</refname> 2851 <refpurpose> 2852 free descriptors returned by <function>usb_copy_descriptors</function> 2853 </refpurpose> 2854</refnamediv> 2855<refsynopsisdiv> 2856 <title>Synopsis</title> 2857 <funcsynopsis><funcprototype> 2858 <funcdef>void <function>usb_free_descriptors </function></funcdef> 2859 <paramdef>struct usb_descriptor_header ** <parameter>v</parameter></paramdef> 2860 </funcprototype></funcsynopsis> 2861</refsynopsisdiv> 2862<refsect1> 2863 <title>Arguments</title> 2864 <variablelist> 2865 <varlistentry> 2866 <term><parameter>v</parameter></term> 2867 <listitem> 2868 <para> 2869 vector of descriptors 2870 </para> 2871 </listitem> 2872 </varlistentry> 2873 </variablelist> 2874</refsect1> 2875</refentry> 2876 2877</sect1> 2878 2879<sect1 id="utils"><title>Optional Utilities</title> 2880 2881<para>The core API is sufficient for writing a USB Gadget Driver, 2882but some optional utilities are provided to simplify common tasks. 2883These utilities include endpoint autoconfiguration. 2884</para> 2885 2886<!-- drivers/usb/gadget/usbstring.c --> 2887<refentry id="API-usb-gadget-get-string"> 2888<refentryinfo> 2889 <title>LINUX</title> 2890 <productname>Kernel Hackers Manual</productname> 2891 <date>July 2017</date> 2892</refentryinfo> 2893<refmeta> 2894 <refentrytitle><phrase>usb_gadget_get_string</phrase></refentrytitle> 2895 <manvolnum>9</manvolnum> 2896 <refmiscinfo class="version">4.1.27</refmiscinfo> 2897</refmeta> 2898<refnamediv> 2899 <refname>usb_gadget_get_string</refname> 2900 <refpurpose> 2901 fill out a string descriptor 2902 </refpurpose> 2903</refnamediv> 2904<refsynopsisdiv> 2905 <title>Synopsis</title> 2906 <funcsynopsis><funcprototype> 2907 <funcdef>int <function>usb_gadget_get_string </function></funcdef> 2908 <paramdef>struct usb_gadget_strings * <parameter>table</parameter></paramdef> 2909 <paramdef>int <parameter>id</parameter></paramdef> 2910 <paramdef>u8 * <parameter>buf</parameter></paramdef> 2911 </funcprototype></funcsynopsis> 2912</refsynopsisdiv> 2913<refsect1> 2914 <title>Arguments</title> 2915 <variablelist> 2916 <varlistentry> 2917 <term><parameter>table</parameter></term> 2918 <listitem> 2919 <para> 2920 of c strings encoded using UTF-8 2921 </para> 2922 </listitem> 2923 </varlistentry> 2924 <varlistentry> 2925 <term><parameter>id</parameter></term> 2926 <listitem> 2927 <para> 2928 string id, from low byte of wValue in get string descriptor 2929 </para> 2930 </listitem> 2931 </varlistentry> 2932 <varlistentry> 2933 <term><parameter>buf</parameter></term> 2934 <listitem> 2935 <para> 2936 at least 256 bytes, must be 16-bit aligned 2937 </para> 2938 </listitem> 2939 </varlistentry> 2940 </variablelist> 2941</refsect1> 2942<refsect1> 2943<title>Description</title> 2944<para> 2945 Finds the UTF-8 string matching the ID, and converts it into a 2946 string descriptor in utf16-le. 2947 Returns length of descriptor (always even) or negative errno 2948 </para><para> 2949 2950 If your driver needs stings in multiple languages, you'll probably 2951 <quote>switch (wIndex) { ... }</quote> in your ep0 string descriptor logic, 2952 using this routine after choosing which set of UTF-8 strings to use. 2953 Note that US-ASCII is a strict subset of UTF-8; any string bytes with 2954 the eighth bit set will be multibyte UTF-8 characters, not ISO-8859/1 2955 characters (which are also widely used in C strings). 2956</para> 2957</refsect1> 2958</refentry> 2959 2960<!-- drivers/usb/gadget/config.c --> 2961<refentry id="API-usb-descriptor-fillbuf"> 2962<refentryinfo> 2963 <title>LINUX</title> 2964 <productname>Kernel Hackers Manual</productname> 2965 <date>July 2017</date> 2966</refentryinfo> 2967<refmeta> 2968 <refentrytitle><phrase>usb_descriptor_fillbuf</phrase></refentrytitle> 2969 <manvolnum>9</manvolnum> 2970 <refmiscinfo class="version">4.1.27</refmiscinfo> 2971</refmeta> 2972<refnamediv> 2973 <refname>usb_descriptor_fillbuf</refname> 2974 <refpurpose> 2975 fill buffer with descriptors 2976 </refpurpose> 2977</refnamediv> 2978<refsynopsisdiv> 2979 <title>Synopsis</title> 2980 <funcsynopsis><funcprototype> 2981 <funcdef>int <function>usb_descriptor_fillbuf </function></funcdef> 2982 <paramdef>void * <parameter>buf</parameter></paramdef> 2983 <paramdef>unsigned <parameter>buflen</parameter></paramdef> 2984 <paramdef>const struct usb_descriptor_header ** <parameter>src</parameter></paramdef> 2985 </funcprototype></funcsynopsis> 2986</refsynopsisdiv> 2987<refsect1> 2988 <title>Arguments</title> 2989 <variablelist> 2990 <varlistentry> 2991 <term><parameter>buf</parameter></term> 2992 <listitem> 2993 <para> 2994 Buffer to be filled 2995 </para> 2996 </listitem> 2997 </varlistentry> 2998 <varlistentry> 2999 <term><parameter>buflen</parameter></term> 3000 <listitem> 3001 <para> 3002 Size of buf 3003 </para> 3004 </listitem> 3005 </varlistentry> 3006 <varlistentry> 3007 <term><parameter>src</parameter></term> 3008 <listitem> 3009 <para> 3010 Array of descriptor pointers, terminated by null pointer. 3011 </para> 3012 </listitem> 3013 </varlistentry> 3014 </variablelist> 3015</refsect1> 3016<refsect1> 3017<title>Description</title> 3018<para> 3019 Copies descriptors into the buffer, returning the length or a 3020 negative error code if they can't all be copied. Useful when 3021 assembling descriptors for an associated set of interfaces used 3022 as part of configuring a composite device; or in other cases where 3023 sets of descriptors need to be marshaled. 3024</para> 3025</refsect1> 3026</refentry> 3027 3028<refentry id="API-usb-gadget-config-buf"> 3029<refentryinfo> 3030 <title>LINUX</title> 3031 <productname>Kernel Hackers Manual</productname> 3032 <date>July 2017</date> 3033</refentryinfo> 3034<refmeta> 3035 <refentrytitle><phrase>usb_gadget_config_buf</phrase></refentrytitle> 3036 <manvolnum>9</manvolnum> 3037 <refmiscinfo class="version">4.1.27</refmiscinfo> 3038</refmeta> 3039<refnamediv> 3040 <refname>usb_gadget_config_buf</refname> 3041 <refpurpose> 3042 builts a complete configuration descriptor 3043 </refpurpose> 3044</refnamediv> 3045<refsynopsisdiv> 3046 <title>Synopsis</title> 3047 <funcsynopsis><funcprototype> 3048 <funcdef>int <function>usb_gadget_config_buf </function></funcdef> 3049 <paramdef>const struct usb_config_descriptor * <parameter>config</parameter></paramdef> 3050 <paramdef>void * <parameter>buf</parameter></paramdef> 3051 <paramdef>unsigned <parameter>length</parameter></paramdef> 3052 <paramdef>const struct usb_descriptor_header ** <parameter>desc</parameter></paramdef> 3053 </funcprototype></funcsynopsis> 3054</refsynopsisdiv> 3055<refsect1> 3056 <title>Arguments</title> 3057 <variablelist> 3058 <varlistentry> 3059 <term><parameter>config</parameter></term> 3060 <listitem> 3061 <para> 3062 Header for the descriptor, including characteristics such 3063 as power requirements and number of interfaces. 3064 </para> 3065 </listitem> 3066 </varlistentry> 3067 <varlistentry> 3068 <term><parameter>buf</parameter></term> 3069 <listitem> 3070 <para> 3071 Buffer for the resulting configuration descriptor. 3072 </para> 3073 </listitem> 3074 </varlistentry> 3075 <varlistentry> 3076 <term><parameter>length</parameter></term> 3077 <listitem> 3078 <para> 3079 Length of buffer. If this is not big enough to hold the 3080 entire configuration descriptor, an error code will be returned. 3081 </para> 3082 </listitem> 3083 </varlistentry> 3084 <varlistentry> 3085 <term><parameter>desc</parameter></term> 3086 <listitem> 3087 <para> 3088 Null-terminated vector of pointers to the descriptors (interface, 3089 endpoint, etc) defining all functions in this device configuration. 3090 </para> 3091 </listitem> 3092 </varlistentry> 3093 </variablelist> 3094</refsect1> 3095<refsect1> 3096<title>Description</title> 3097<para> 3098 This copies descriptors into the response buffer, building a descriptor 3099 for that configuration. It returns the buffer length or a negative 3100 status code. The config.wTotalLength field is set to match the length 3101 of the result, but other descriptor fields (including power usage and 3102 interface count) must be set by the caller. 3103 </para><para> 3104 3105 Gadget drivers could use this when constructing a config descriptor 3106 in response to USB_REQ_GET_DESCRIPTOR. They will need to patch the 3107 resulting bDescriptorType value if USB_DT_OTHER_SPEED_CONFIG is needed. 3108</para> 3109</refsect1> 3110</refentry> 3111 3112<refentry id="API-usb-copy-descriptors"> 3113<refentryinfo> 3114 <title>LINUX</title> 3115 <productname>Kernel Hackers Manual</productname> 3116 <date>July 2017</date> 3117</refentryinfo> 3118<refmeta> 3119 <refentrytitle><phrase>usb_copy_descriptors</phrase></refentrytitle> 3120 <manvolnum>9</manvolnum> 3121 <refmiscinfo class="version">4.1.27</refmiscinfo> 3122</refmeta> 3123<refnamediv> 3124 <refname>usb_copy_descriptors</refname> 3125 <refpurpose> 3126 copy a vector of USB descriptors 3127 </refpurpose> 3128</refnamediv> 3129<refsynopsisdiv> 3130 <title>Synopsis</title> 3131 <funcsynopsis><funcprototype> 3132 <funcdef>struct usb_descriptor_header ** <function>usb_copy_descriptors </function></funcdef> 3133 <paramdef>struct usb_descriptor_header ** <parameter>src</parameter></paramdef> 3134 </funcprototype></funcsynopsis> 3135</refsynopsisdiv> 3136<refsect1> 3137 <title>Arguments</title> 3138 <variablelist> 3139 <varlistentry> 3140 <term><parameter>src</parameter></term> 3141 <listitem> 3142 <para> 3143 null-terminated vector to copy 3144 </para> 3145 </listitem> 3146 </varlistentry> 3147 </variablelist> 3148</refsect1> 3149<refsect1> 3150<title>Context</title> 3151<para> 3152 initialization code, which may sleep 3153</para> 3154</refsect1> 3155<refsect1> 3156<title>Description</title> 3157<para> 3158 This makes a copy of a vector of USB descriptors. Its primary use 3159 is to support usb_function objects which can have multiple copies, 3160 each needing different descriptors. Functions may have static 3161 tables of descriptors, which are used as templates and customized 3162 with identifiers (for interfaces, strings, endpoints, and more) 3163 as needed by a given function instance. 3164</para> 3165</refsect1> 3166</refentry> 3167 3168<!-- !Edrivers/usb/gadget/epautoconf.c --> 3169</sect1> 3170 3171<sect1 id="composite"><title>Composite Device Framework</title> 3172 3173<para>The core API is sufficient for writing drivers for composite 3174USB devices (with more than one function in a given configuration), 3175and also multi-configuration devices (also more than one function, 3176but not necessarily sharing a given configuration). 3177There is however an optional framework which makes it easier to 3178reuse and combine functions. 3179</para> 3180 3181<para>Devices using this framework provide a <emphasis>struct 3182usb_composite_driver</emphasis>, which in turn provides one or 3183more <emphasis>struct usb_configuration</emphasis> instances. 3184Each such configuration includes at least one 3185<emphasis>struct usb_function</emphasis>, which packages a user 3186visible role such as "network link" or "mass storage device". 3187Management functions may also exist, such as "Device Firmware 3188Upgrade". 3189</para> 3190 3191<!-- include/linux/usb/composite.h --> 3192<refentry id="API-struct-usb-os-desc-ext-prop"> 3193<refentryinfo> 3194 <title>LINUX</title> 3195 <productname>Kernel Hackers Manual</productname> 3196 <date>July 2017</date> 3197</refentryinfo> 3198<refmeta> 3199 <refentrytitle><phrase>struct usb_os_desc_ext_prop</phrase></refentrytitle> 3200 <manvolnum>9</manvolnum> 3201 <refmiscinfo class="version">4.1.27</refmiscinfo> 3202</refmeta> 3203<refnamediv> 3204 <refname>struct usb_os_desc_ext_prop</refname> 3205 <refpurpose> 3206 describes one <quote>Extended Property</quote> 3207 </refpurpose> 3208</refnamediv> 3209<refsynopsisdiv> 3210 <title>Synopsis</title> 3211 <programlisting> 3212struct usb_os_desc_ext_prop { 3213 struct list_head entry; 3214 u8 type; 3215 int name_len; 3216 char * name; 3217 int data_len; 3218 char * data; 3219 struct config_item item; 3220}; </programlisting> 3221</refsynopsisdiv> 3222 <refsect1> 3223 <title>Members</title> 3224 <variablelist> 3225 <varlistentry> <term>entry</term> 3226 <listitem><para> 3227used to keep a list of extended properties 3228 </para></listitem> 3229 </varlistentry> 3230 <varlistentry> <term>type</term> 3231 <listitem><para> 3232Extended Property type 3233 </para></listitem> 3234 </varlistentry> 3235 <varlistentry> <term>name_len</term> 3236 <listitem><para> 3237Extended Property unicode name length, including terminating '\0' 3238 </para></listitem> 3239 </varlistentry> 3240 <varlistentry> <term>name</term> 3241 <listitem><para> 3242Extended Property name 3243 </para></listitem> 3244 </varlistentry> 3245 <varlistentry> <term>data_len</term> 3246 <listitem><para> 3247Length of Extended Property blob (for unicode store double len) 3248 </para></listitem> 3249 </varlistentry> 3250 <varlistentry> <term>data</term> 3251 <listitem><para> 3252Extended Property blob 3253 </para></listitem> 3254 </varlistentry> 3255 <varlistentry> <term>item</term> 3256 <listitem><para> 3257Represents this Extended Property in configfs 3258 </para></listitem> 3259 </varlistentry> 3260 </variablelist> 3261 </refsect1> 3262</refentry> 3263 3264<refentry id="API-struct-usb-os-desc"> 3265<refentryinfo> 3266 <title>LINUX</title> 3267 <productname>Kernel Hackers Manual</productname> 3268 <date>July 2017</date> 3269</refentryinfo> 3270<refmeta> 3271 <refentrytitle><phrase>struct usb_os_desc</phrase></refentrytitle> 3272 <manvolnum>9</manvolnum> 3273 <refmiscinfo class="version">4.1.27</refmiscinfo> 3274</refmeta> 3275<refnamediv> 3276 <refname>struct usb_os_desc</refname> 3277 <refpurpose> 3278 describes OS descriptors associated with one interface 3279 </refpurpose> 3280</refnamediv> 3281<refsynopsisdiv> 3282 <title>Synopsis</title> 3283 <programlisting> 3284struct usb_os_desc { 3285 char * ext_compat_id; 3286 struct list_head ext_prop; 3287 int ext_prop_len; 3288 int ext_prop_count; 3289 struct mutex * opts_mutex; 3290 struct config_group group; 3291 struct module * owner; 3292}; </programlisting> 3293</refsynopsisdiv> 3294 <refsect1> 3295 <title>Members</title> 3296 <variablelist> 3297 <varlistentry> <term>ext_compat_id</term> 3298 <listitem><para> 3299 16 bytes of <quote>Compatible ID</quote> and <quote>Subcompatible ID</quote> 3300 </para></listitem> 3301 </varlistentry> 3302 <varlistentry> <term>ext_prop</term> 3303 <listitem><para> 3304 Extended Properties list 3305 </para></listitem> 3306 </varlistentry> 3307 <varlistentry> <term>ext_prop_len</term> 3308 <listitem><para> 3309 Total length of Extended Properties blobs 3310 </para></listitem> 3311 </varlistentry> 3312 <varlistentry> <term>ext_prop_count</term> 3313 <listitem><para> 3314 Number of Extended Properties 3315 </para></listitem> 3316 </varlistentry> 3317 <varlistentry> <term>opts_mutex</term> 3318 <listitem><para> 3319 Optional mutex protecting config data of a usb_function_instance 3320 </para></listitem> 3321 </varlistentry> 3322 <varlistentry> <term>group</term> 3323 <listitem><para> 3324 Represents OS descriptors associated with an interface in configfs 3325 </para></listitem> 3326 </varlistentry> 3327 <varlistentry> <term>owner</term> 3328 <listitem><para> 3329 Module associated with this OS descriptor 3330 </para></listitem> 3331 </varlistentry> 3332 </variablelist> 3333 </refsect1> 3334</refentry> 3335 3336<refentry id="API-struct-usb-os-desc-table"> 3337<refentryinfo> 3338 <title>LINUX</title> 3339 <productname>Kernel Hackers Manual</productname> 3340 <date>July 2017</date> 3341</refentryinfo> 3342<refmeta> 3343 <refentrytitle><phrase>struct usb_os_desc_table</phrase></refentrytitle> 3344 <manvolnum>9</manvolnum> 3345 <refmiscinfo class="version">4.1.27</refmiscinfo> 3346</refmeta> 3347<refnamediv> 3348 <refname>struct usb_os_desc_table</refname> 3349 <refpurpose> 3350 describes OS descriptors associated with one interface of a usb_function 3351 </refpurpose> 3352</refnamediv> 3353<refsynopsisdiv> 3354 <title>Synopsis</title> 3355 <programlisting> 3356struct usb_os_desc_table { 3357 int if_id; 3358 struct usb_os_desc * os_desc; 3359}; </programlisting> 3360</refsynopsisdiv> 3361 <refsect1> 3362 <title>Members</title> 3363 <variablelist> 3364 <varlistentry> <term>if_id</term> 3365 <listitem><para> 3366 Interface id 3367 </para></listitem> 3368 </varlistentry> 3369 <varlistentry> <term>os_desc</term> 3370 <listitem><para> 3371 "Extended Compatibility ID<quote> and </quote>Extended Properties" of the 3372 interface 3373 </para></listitem> 3374 </varlistentry> 3375 </variablelist> 3376 </refsect1> 3377<refsect1> 3378<title>Description</title> 3379<para> 3380 Each interface can have at most one <quote>Extended Compatibility ID</quote> and a 3381 number of <quote>Extended Properties</quote>. 3382</para> 3383</refsect1> 3384</refentry> 3385 3386<refentry id="API-struct-usb-function"> 3387<refentryinfo> 3388 <title>LINUX</title> 3389 <productname>Kernel Hackers Manual</productname> 3390 <date>July 2017</date> 3391</refentryinfo> 3392<refmeta> 3393 <refentrytitle><phrase>struct usb_function</phrase></refentrytitle> 3394 <manvolnum>9</manvolnum> 3395 <refmiscinfo class="version">4.1.27</refmiscinfo> 3396</refmeta> 3397<refnamediv> 3398 <refname>struct usb_function</refname> 3399 <refpurpose> 3400 describes one function of a configuration 3401 </refpurpose> 3402</refnamediv> 3403<refsynopsisdiv> 3404 <title>Synopsis</title> 3405 <programlisting> 3406struct usb_function { 3407 const char * name; 3408 struct usb_gadget_strings ** strings; 3409 struct usb_descriptor_header ** fs_descriptors; 3410 struct usb_descriptor_header ** hs_descriptors; 3411 struct usb_descriptor_header ** ss_descriptors; 3412 struct usb_configuration * config; 3413 struct usb_os_desc_table * os_desc_table; 3414 unsigned os_desc_n; 3415 int (* bind) (struct usb_configuration *,struct usb_function *); 3416 void (* unbind) (struct usb_configuration *,struct usb_function *); 3417 void (* free_func) (struct usb_function *f); 3418 struct module * mod; 3419 int (* set_alt) (struct usb_function *,unsigned interface, unsigned alt); 3420 int (* get_alt) (struct usb_function *,unsigned interface); 3421 void (* disable) (struct usb_function *); 3422 int (* setup) (struct usb_function *,const struct usb_ctrlrequest *); 3423 bool (* req_match) (struct usb_function *,const struct usb_ctrlrequest *); 3424 void (* suspend) (struct usb_function *); 3425 void (* resume) (struct usb_function *); 3426 int (* get_status) (struct usb_function *); 3427 int (* func_suspend) (struct usb_function *,u8 suspend_opt); 3428}; </programlisting> 3429</refsynopsisdiv> 3430 <refsect1> 3431 <title>Members</title> 3432 <variablelist> 3433 <varlistentry> <term>name</term> 3434 <listitem><para> 3435 For diagnostics, identifies the function. 3436 </para></listitem> 3437 </varlistentry> 3438 <varlistentry> <term>strings</term> 3439 <listitem><para> 3440 tables of strings, keyed by identifiers assigned during <function>bind</function> 3441 and by language IDs provided in control requests 3442 </para></listitem> 3443 </varlistentry> 3444 <varlistentry> <term>fs_descriptors</term> 3445 <listitem><para> 3446 Table of full (or low) speed descriptors, using interface and 3447 string identifiers assigned during @<function>bind</function>. If this pointer is null, 3448 the function will not be available at full speed (or at low speed). 3449 </para></listitem> 3450 </varlistentry> 3451 <varlistentry> <term>hs_descriptors</term> 3452 <listitem><para> 3453 Table of high speed descriptors, using interface and 3454 string identifiers assigned during @<function>bind</function>. If this pointer is null, 3455 the function will not be available at high speed. 3456 </para></listitem> 3457 </varlistentry> 3458 <varlistentry> <term>ss_descriptors</term> 3459 <listitem><para> 3460 Table of super speed descriptors, using interface and 3461 string identifiers assigned during @<function>bind</function>. If this 3462 pointer is null after initiation, the function will not 3463 be available at super speed. 3464 </para></listitem> 3465 </varlistentry> 3466 <varlistentry> <term>config</term> 3467 <listitem><para> 3468 assigned when @<function>usb_add_function</function> is called; this is the 3469 configuration with which this function is associated. 3470 </para></listitem> 3471 </varlistentry> 3472 <varlistentry> <term>os_desc_table</term> 3473 <listitem><para> 3474 Table of (interface id, os descriptors) pairs. The function 3475 can expose more than one interface. If an interface is a member of 3476 an IAD, only the first interface of IAD has its entry in the table. 3477 </para></listitem> 3478 </varlistentry> 3479 <varlistentry> <term>os_desc_n</term> 3480 <listitem><para> 3481 Number of entries in os_desc_table 3482 </para></listitem> 3483 </varlistentry> 3484 <varlistentry> <term>bind</term> 3485 <listitem><para> 3486 Before the gadget can register, all of its functions <function>bind</function> to the 3487 available resources including string and interface identifiers used 3488 in interface or class descriptors; endpoints; I/O buffers; and so on. 3489 </para></listitem> 3490 </varlistentry> 3491 <varlistentry> <term>unbind</term> 3492 <listitem><para> 3493 Reverses <parameter>bind</parameter>; called as a side effect of unregistering the 3494 driver which added this function. 3495 </para></listitem> 3496 </varlistentry> 3497 <varlistentry> <term>free_func</term> 3498 <listitem><para> 3499 free the struct usb_function. 3500 </para></listitem> 3501 </varlistentry> 3502 <varlistentry> <term>mod</term> 3503 <listitem><para> 3504 (internal) points to the module that created this structure. 3505 </para></listitem> 3506 </varlistentry> 3507 <varlistentry> <term>set_alt</term> 3508 <listitem><para> 3509 (REQUIRED) Reconfigures altsettings; function drivers may 3510 initialize usb_ep.driver data at this time (when it is used). 3511 Note that setting an interface to its current altsetting resets 3512 interface state, and that all interfaces have a disabled state. 3513 </para></listitem> 3514 </varlistentry> 3515 <varlistentry> <term>get_alt</term> 3516 <listitem><para> 3517 Returns the active altsetting. If this is not provided, 3518 then only altsetting zero is supported. 3519 </para></listitem> 3520 </varlistentry> 3521 <varlistentry> <term>disable</term> 3522 <listitem><para> 3523 (REQUIRED) Indicates the function should be disabled. Reasons 3524 include host resetting or reconfiguring the gadget, and disconnection. 3525 </para></listitem> 3526 </varlistentry> 3527 <varlistentry> <term>setup</term> 3528 <listitem><para> 3529 Used for interface-specific control requests. 3530 </para></listitem> 3531 </varlistentry> 3532 <varlistentry> <term>req_match</term> 3533 <listitem><para> 3534 Tests if a given class request can be handled by this function. 3535 </para></listitem> 3536 </varlistentry> 3537 <varlistentry> <term>suspend</term> 3538 <listitem><para> 3539 Notifies functions when the host stops sending USB traffic. 3540 </para></listitem> 3541 </varlistentry> 3542 <varlistentry> <term>resume</term> 3543 <listitem><para> 3544 Notifies functions when the host restarts USB traffic. 3545 </para></listitem> 3546 </varlistentry> 3547 <varlistentry> <term>get_status</term> 3548 <listitem><para> 3549 Returns function status as a reply to 3550 <function>GetStatus</function> request when the recipient is Interface. 3551 </para></listitem> 3552 </varlistentry> 3553 <varlistentry> <term>func_suspend</term> 3554 <listitem><para> 3555 callback to be called when 3556 SetFeature(FUNCTION_SUSPEND) is reseived 3557 </para></listitem> 3558 </varlistentry> 3559 </variablelist> 3560 </refsect1> 3561<refsect1> 3562<title>Description</title> 3563<para> 3564 A single USB function uses one or more interfaces, and should in most 3565 cases support operation at both full and high speeds. Each function is 3566 associated by @<function>usb_add_function</function> with a one configuration; that function 3567 causes @<function>bind</function> to be called so resources can be allocated as part of 3568 setting up a gadget driver. Those resources include endpoints, which 3569 should be allocated using @<function>usb_ep_autoconfig</function>. 3570 </para><para> 3571 3572 To support dual speed operation, a function driver provides descriptors 3573 for both high and full speed operation. Except in rare cases that don't 3574 involve bulk endpoints, each speed needs different endpoint descriptors. 3575 </para><para> 3576 3577 Function drivers choose their own strategies for managing instance data. 3578 The simplest strategy just declares it "static', which means the function 3579 can only be activated once. If the function needs to be exposed in more 3580 than one configuration at a given speed, it needs to support multiple 3581 usb_function structures (one for each configuration). 3582 </para><para> 3583 3584 A more complex strategy might encapsulate a <parameter>usb_function</parameter> structure inside 3585 a driver-specific instance structure to allows multiple activations. An 3586 example of multiple activations might be a CDC ACM function that supports 3587 two or more distinct instances within the same configuration, providing 3588 several independent logical data links to a USB host. 3589</para> 3590</refsect1> 3591</refentry> 3592 3593<refentry id="API-struct-usb-configuration"> 3594<refentryinfo> 3595 <title>LINUX</title> 3596 <productname>Kernel Hackers Manual</productname> 3597 <date>July 2017</date> 3598</refentryinfo> 3599<refmeta> 3600 <refentrytitle><phrase>struct usb_configuration</phrase></refentrytitle> 3601 <manvolnum>9</manvolnum> 3602 <refmiscinfo class="version">4.1.27</refmiscinfo> 3603</refmeta> 3604<refnamediv> 3605 <refname>struct usb_configuration</refname> 3606 <refpurpose> 3607 represents one gadget configuration 3608 </refpurpose> 3609</refnamediv> 3610<refsynopsisdiv> 3611 <title>Synopsis</title> 3612 <programlisting> 3613struct usb_configuration { 3614 const char * label; 3615 struct usb_gadget_strings ** strings; 3616 const struct usb_descriptor_header ** descriptors; 3617 void (* unbind) (struct usb_configuration *); 3618 int (* setup) (struct usb_configuration *,const struct usb_ctrlrequest *); 3619 u8 bConfigurationValue; 3620 u8 iConfiguration; 3621 u8 bmAttributes; 3622 u16 MaxPower; 3623 struct usb_composite_dev * cdev; 3624}; </programlisting> 3625</refsynopsisdiv> 3626 <refsect1> 3627 <title>Members</title> 3628 <variablelist> 3629 <varlistentry> <term>label</term> 3630 <listitem><para> 3631 For diagnostics, describes the configuration. 3632 </para></listitem> 3633 </varlistentry> 3634 <varlistentry> <term>strings</term> 3635 <listitem><para> 3636 Tables of strings, keyed by identifiers assigned during @<function>bind</function> 3637 and by language IDs provided in control requests. 3638 </para></listitem> 3639 </varlistentry> 3640 <varlistentry> <term>descriptors</term> 3641 <listitem><para> 3642 Table of descriptors preceding all function descriptors. 3643 Examples include OTG and vendor-specific descriptors. 3644 </para></listitem> 3645 </varlistentry> 3646 <varlistentry> <term>unbind</term> 3647 <listitem><para> 3648 Reverses <parameter>bind</parameter>; called as a side effect of unregistering the 3649 driver which added this configuration. 3650 </para></listitem> 3651 </varlistentry> 3652 <varlistentry> <term>setup</term> 3653 <listitem><para> 3654 Used to delegate control requests that aren't handled by standard 3655 device infrastructure or directed at a specific interface. 3656 </para></listitem> 3657 </varlistentry> 3658 <varlistentry> <term>bConfigurationValue</term> 3659 <listitem><para> 3660 Copied into configuration descriptor. 3661 </para></listitem> 3662 </varlistentry> 3663 <varlistentry> <term>iConfiguration</term> 3664 <listitem><para> 3665 Copied into configuration descriptor. 3666 </para></listitem> 3667 </varlistentry> 3668 <varlistentry> <term>bmAttributes</term> 3669 <listitem><para> 3670 Copied into configuration descriptor. 3671 </para></listitem> 3672 </varlistentry> 3673 <varlistentry> <term>MaxPower</term> 3674 <listitem><para> 3675 Power consumtion in mA. Used to compute bMaxPower in the 3676 configuration descriptor after considering the bus speed. 3677 </para></listitem> 3678 </varlistentry> 3679 <varlistentry> <term>cdev</term> 3680 <listitem><para> 3681 assigned by @<function>usb_add_config</function> before calling @<function>bind</function>; this is 3682 the device associated with this configuration. 3683 </para></listitem> 3684 </varlistentry> 3685 </variablelist> 3686 </refsect1> 3687<refsect1> 3688<title>Description</title> 3689<para> 3690 Configurations are building blocks for gadget drivers structured around 3691 function drivers. Simple USB gadgets require only one function and one 3692 configuration, and handle dual-speed hardware by always providing the same 3693 functionality. Slightly more complex gadgets may have more than one 3694 single-function configuration at a given speed; or have configurations 3695 that only work at one speed. 3696 </para><para> 3697 3698 Composite devices are, by definition, ones with configurations which 3699 include more than one function. 3700 </para><para> 3701 3702 The lifecycle of a usb_configuration includes allocation, initialization 3703 of the fields described above, and calling @<function>usb_add_config</function> to set up 3704 internal data and bind it to a specific device. The configuration's 3705 @<function>bind</function> method is then used to initialize all the functions and then 3706 call @<function>usb_add_function</function> for them. 3707 </para><para> 3708 3709 Those functions would normally be independent of each other, but that's 3710 not mandatory. CDC WMC devices are an example where functions often 3711 depend on other functions, with some functions subsidiary to others. 3712 Such interdependency may be managed in any way, so long as all of the 3713 descriptors complete by the time the composite driver returns from 3714 its <function>bind</function> routine. 3715</para> 3716</refsect1> 3717</refentry> 3718 3719<refentry id="API-struct-usb-composite-driver"> 3720<refentryinfo> 3721 <title>LINUX</title> 3722 <productname>Kernel Hackers Manual</productname> 3723 <date>July 2017</date> 3724</refentryinfo> 3725<refmeta> 3726 <refentrytitle><phrase>struct usb_composite_driver</phrase></refentrytitle> 3727 <manvolnum>9</manvolnum> 3728 <refmiscinfo class="version">4.1.27</refmiscinfo> 3729</refmeta> 3730<refnamediv> 3731 <refname>struct usb_composite_driver</refname> 3732 <refpurpose> 3733 groups configurations into a gadget 3734 </refpurpose> 3735</refnamediv> 3736<refsynopsisdiv> 3737 <title>Synopsis</title> 3738 <programlisting> 3739struct usb_composite_driver { 3740 const char * name; 3741 const struct usb_device_descriptor * dev; 3742 struct usb_gadget_strings ** strings; 3743 enum usb_device_speed max_speed; 3744 unsigned needs_serial:1; 3745 int (* bind) (struct usb_composite_dev *cdev); 3746 int (* unbind) (struct usb_composite_dev *); 3747 void (* disconnect) (struct usb_composite_dev *); 3748 void (* suspend) (struct usb_composite_dev *); 3749 void (* resume) (struct usb_composite_dev *); 3750 struct usb_gadget_driver gadget_driver; 3751}; </programlisting> 3752</refsynopsisdiv> 3753 <refsect1> 3754 <title>Members</title> 3755 <variablelist> 3756 <varlistentry> <term>name</term> 3757 <listitem><para> 3758 For diagnostics, identifies the driver. 3759 </para></listitem> 3760 </varlistentry> 3761 <varlistentry> <term>dev</term> 3762 <listitem><para> 3763 Template descriptor for the device, including default device 3764 identifiers. 3765 </para></listitem> 3766 </varlistentry> 3767 <varlistentry> <term>strings</term> 3768 <listitem><para> 3769 tables of strings, keyed by identifiers assigned during <parameter>bind</parameter> 3770 and language IDs provided in control requests. Note: The first entries 3771 are predefined. The first entry that may be used is 3772 USB_GADGET_FIRST_AVAIL_IDX 3773 </para></listitem> 3774 </varlistentry> 3775 <varlistentry> <term>max_speed</term> 3776 <listitem><para> 3777 Highest speed the driver supports. 3778 </para></listitem> 3779 </varlistentry> 3780 <varlistentry> <term>needs_serial</term> 3781 <listitem><para> 3782 set to 1 if the gadget needs userspace to provide 3783 a serial number. If one is not provided, warning will be printed. 3784 </para></listitem> 3785 </varlistentry> 3786 <varlistentry> <term>bind</term> 3787 <listitem><para> 3788 (REQUIRED) Used to allocate resources that are shared across the 3789 whole device, such as string IDs, and add its configurations using 3790 @<function>usb_add_config</function>. This may fail by returning a negative errno 3791 value; it should return zero on successful initialization. 3792 </para></listitem> 3793 </varlistentry> 3794 <varlistentry> <term>unbind</term> 3795 <listitem><para> 3796 Reverses <parameter>bind</parameter>; called as a side effect of unregistering 3797 this driver. 3798 </para></listitem> 3799 </varlistentry> 3800 <varlistentry> <term>disconnect</term> 3801 <listitem><para> 3802 optional driver disconnect method 3803 </para></listitem> 3804 </varlistentry> 3805 <varlistentry> <term>suspend</term> 3806 <listitem><para> 3807 Notifies when the host stops sending USB traffic, 3808 after function notifications 3809 </para></listitem> 3810 </varlistentry> 3811 <varlistentry> <term>resume</term> 3812 <listitem><para> 3813 Notifies configuration when the host restarts USB traffic, 3814 before function notifications 3815 </para></listitem> 3816 </varlistentry> 3817 <varlistentry> <term>gadget_driver</term> 3818 <listitem><para> 3819 Gadget driver controlling this driver 3820 </para></listitem> 3821 </varlistentry> 3822 </variablelist> 3823 </refsect1> 3824<refsect1> 3825<title>Description</title> 3826<para> 3827 Devices default to reporting self powered operation. Devices which rely 3828 on bus powered operation should report this in their <parameter>bind</parameter> method. 3829 </para><para> 3830 3831 Before returning from <parameter>bind</parameter>, various fields in the template descriptor 3832 may be overridden. These include the idVendor/idProduct/bcdDevice values 3833 normally to bind the appropriate host side driver, and the three strings 3834 (iManufacturer, iProduct, iSerialNumber) normally used to provide user 3835 meaningful device identifiers. (The strings will not be defined unless 3836 they are defined in <parameter>dev</parameter> and <parameter>strings</parameter>.) The correct ep0 maxpacket size 3837 is also reported, as defined by the underlying controller driver. 3838</para> 3839</refsect1> 3840</refentry> 3841 3842<refentry id="API-module-usb-composite-driver"> 3843<refentryinfo> 3844 <title>LINUX</title> 3845 <productname>Kernel Hackers Manual</productname> 3846 <date>July 2017</date> 3847</refentryinfo> 3848<refmeta> 3849 <refentrytitle><phrase>module_usb_composite_driver</phrase></refentrytitle> 3850 <manvolnum>9</manvolnum> 3851 <refmiscinfo class="version">4.1.27</refmiscinfo> 3852</refmeta> 3853<refnamediv> 3854 <refname>module_usb_composite_driver</refname> 3855 <refpurpose> 3856 Helper macro for registering a USB gadget composite driver 3857 </refpurpose> 3858</refnamediv> 3859<refsynopsisdiv> 3860 <title>Synopsis</title> 3861 <funcsynopsis><funcprototype> 3862 <funcdef> <function>module_usb_composite_driver </function></funcdef> 3863 <paramdef> <parameter>__usb_composite_driver</parameter></paramdef> 3864 </funcprototype></funcsynopsis> 3865</refsynopsisdiv> 3866<refsect1> 3867 <title>Arguments</title> 3868 <variablelist> 3869 <varlistentry> 3870 <term><parameter>__usb_composite_driver</parameter></term> 3871 <listitem> 3872 <para> 3873 usb_composite_driver struct 3874 </para> 3875 </listitem> 3876 </varlistentry> 3877 </variablelist> 3878</refsect1> 3879<refsect1> 3880<title>Description</title> 3881<para> 3882 Helper macro for USB gadget composite drivers which do not do anything 3883 special in module init/exit. This eliminates a lot of boilerplate. Each 3884 module may only use this macro once, and calling it replaces <function>module_init</function> 3885 and <function>module_exit</function> 3886</para> 3887</refsect1> 3888</refentry> 3889 3890<refentry id="API-struct-usb-composite-dev"> 3891<refentryinfo> 3892 <title>LINUX</title> 3893 <productname>Kernel Hackers Manual</productname> 3894 <date>July 2017</date> 3895</refentryinfo> 3896<refmeta> 3897 <refentrytitle><phrase>struct usb_composite_dev</phrase></refentrytitle> 3898 <manvolnum>9</manvolnum> 3899 <refmiscinfo class="version">4.1.27</refmiscinfo> 3900</refmeta> 3901<refnamediv> 3902 <refname>struct usb_composite_dev</refname> 3903 <refpurpose> 3904 represents one composite usb gadget 3905 </refpurpose> 3906</refnamediv> 3907<refsynopsisdiv> 3908 <title>Synopsis</title> 3909 <programlisting> 3910struct usb_composite_dev { 3911 struct usb_gadget * gadget; 3912 struct usb_request * req; 3913 struct usb_request * os_desc_req; 3914 struct usb_configuration * config; 3915 u8 qw_sign[OS_STRING_QW_SIGN_LEN]; 3916 u8 b_vendor_code; 3917 struct usb_configuration * os_desc_config; 3918 unsigned int use_os_string:1; 3919}; </programlisting> 3920</refsynopsisdiv> 3921 <refsect1> 3922 <title>Members</title> 3923 <variablelist> 3924 <varlistentry> <term>gadget</term> 3925 <listitem><para> 3926 read-only, abstracts the gadget's usb peripheral controller 3927 </para></listitem> 3928 </varlistentry> 3929 <varlistentry> <term>req</term> 3930 <listitem><para> 3931 used for control responses; buffer is pre-allocated 3932 </para></listitem> 3933 </varlistentry> 3934 <varlistentry> <term>os_desc_req</term> 3935 <listitem><para> 3936 used for OS descriptors responses; buffer is pre-allocated 3937 </para></listitem> 3938 </varlistentry> 3939 <varlistentry> <term>config</term> 3940 <listitem><para> 3941 the currently active configuration 3942 </para></listitem> 3943 </varlistentry> 3944 <varlistentry> <term>qw_sign[OS_STRING_QW_SIGN_LEN]</term> 3945 <listitem><para> 3946 qwSignature part of the OS string 3947 </para></listitem> 3948 </varlistentry> 3949 <varlistentry> <term>b_vendor_code</term> 3950 <listitem><para> 3951 bMS_VendorCode part of the OS string 3952 </para></listitem> 3953 </varlistentry> 3954 <varlistentry> <term>os_desc_config</term> 3955 <listitem><para> 3956 the configuration to be used with OS descriptors 3957 </para></listitem> 3958 </varlistentry> 3959 <varlistentry> <term>use_os_string</term> 3960 <listitem><para> 3961 false by default, interested gadgets set it 3962 </para></listitem> 3963 </varlistentry> 3964 </variablelist> 3965 </refsect1> 3966<refsect1> 3967<title>Description</title> 3968<para> 3969 One of these devices is allocated and initialized before the 3970 associated device driver's <function>bind</function> is called. 3971</para> 3972</refsect1> 3973<refsect1> 3974<title>OPEN ISSUE</title> 3975<para> 3976 it appears that some WUSB devices will need to be 3977 built by combining a normal (wired) gadget with a wireless one. 3978 This revision of the gadget framework should probably try to make 3979 sure doing that won't hurt too much. 3980</para> 3981</refsect1> 3982<refsect1> 3983<title>One notion for how to handle Wireless USB devices involves</title> 3984<para> 3985 (a) a second gadget here, discovery mechanism TBD, but likely 3986 needing separate <quote>register/unregister WUSB gadget</quote> calls; 3987 (b) updates to usb_gadget to include flags <quote>is it wireless</quote>, 3988 <quote>is it wired</quote>, plus (presumably in a wrapper structure) 3989 bandgroup and PHY info; 3990 (c) presumably a wireless_ep wrapping a usb_ep, and reporting 3991 wireless-specific parameters like maxburst and maxsequence; 3992 (d) configurations that are specific to wireless links; 3993 (e) function drivers that understand wireless configs and will 3994 support wireless for (additional) function instances; 3995 (f) a function to support association setup (like CBAF), not 3996 necessarily requiring a wireless adapter; 3997 (g) composite device setup that can create one or more wireless 3998 configs, including appropriate association setup support; 3999 (h) more, TBD. 4000</para> 4001</refsect1> 4002</refentry> 4003 4004<!-- drivers/usb/gadget/composite.c --> 4005<refentry id="API-config-ep-by-speed"> 4006<refentryinfo> 4007 <title>LINUX</title> 4008 <productname>Kernel Hackers Manual</productname> 4009 <date>July 2017</date> 4010</refentryinfo> 4011<refmeta> 4012 <refentrytitle><phrase>config_ep_by_speed</phrase></refentrytitle> 4013 <manvolnum>9</manvolnum> 4014 <refmiscinfo class="version">4.1.27</refmiscinfo> 4015</refmeta> 4016<refnamediv> 4017 <refname>config_ep_by_speed</refname> 4018 <refpurpose> 4019 configures the given endpoint according to gadget speed. 4020 </refpurpose> 4021</refnamediv> 4022<refsynopsisdiv> 4023 <title>Synopsis</title> 4024 <funcsynopsis><funcprototype> 4025 <funcdef>int <function>config_ep_by_speed </function></funcdef> 4026 <paramdef>struct usb_gadget * <parameter>g</parameter></paramdef> 4027 <paramdef>struct usb_function * <parameter>f</parameter></paramdef> 4028 <paramdef>struct usb_ep * <parameter>_ep</parameter></paramdef> 4029 </funcprototype></funcsynopsis> 4030</refsynopsisdiv> 4031<refsect1> 4032 <title>Arguments</title> 4033 <variablelist> 4034 <varlistentry> 4035 <term><parameter>g</parameter></term> 4036 <listitem> 4037 <para> 4038 pointer to the gadget 4039 </para> 4040 </listitem> 4041 </varlistentry> 4042 <varlistentry> 4043 <term><parameter>f</parameter></term> 4044 <listitem> 4045 <para> 4046 usb function 4047 </para> 4048 </listitem> 4049 </varlistentry> 4050 <varlistentry> 4051 <term><parameter>_ep</parameter></term> 4052 <listitem> 4053 <para> 4054 the endpoint to configure 4055 </para> 4056 </listitem> 4057 </varlistentry> 4058 </variablelist> 4059</refsect1> 4060<refsect1> 4061<title>Return</title> 4062<para> 4063 error code, 0 on success 4064 </para><para> 4065 4066 This function chooses the right descriptors for a given 4067 endpoint according to gadget speed and saves it in the 4068 endpoint desc field. If the endpoint already has a descriptor 4069 assigned to it - overwrites it with currently corresponding 4070 descriptor. The endpoint maxpacket field is updated according 4071 to the chosen descriptor. 4072</para> 4073</refsect1> 4074<refsect1> 4075<title>Note</title> 4076<para> 4077 the supplied function should hold all the descriptors 4078 for supported speeds 4079</para> 4080</refsect1> 4081</refentry> 4082 4083<refentry id="API-usb-add-function"> 4084<refentryinfo> 4085 <title>LINUX</title> 4086 <productname>Kernel Hackers Manual</productname> 4087 <date>July 2017</date> 4088</refentryinfo> 4089<refmeta> 4090 <refentrytitle><phrase>usb_add_function</phrase></refentrytitle> 4091 <manvolnum>9</manvolnum> 4092 <refmiscinfo class="version">4.1.27</refmiscinfo> 4093</refmeta> 4094<refnamediv> 4095 <refname>usb_add_function</refname> 4096 <refpurpose> 4097 add a function to a configuration 4098 </refpurpose> 4099</refnamediv> 4100<refsynopsisdiv> 4101 <title>Synopsis</title> 4102 <funcsynopsis><funcprototype> 4103 <funcdef>int <function>usb_add_function </function></funcdef> 4104 <paramdef>struct usb_configuration * <parameter>config</parameter></paramdef> 4105 <paramdef>struct usb_function * <parameter>function</parameter></paramdef> 4106 </funcprototype></funcsynopsis> 4107</refsynopsisdiv> 4108<refsect1> 4109 <title>Arguments</title> 4110 <variablelist> 4111 <varlistentry> 4112 <term><parameter>config</parameter></term> 4113 <listitem> 4114 <para> 4115 the configuration 4116 </para> 4117 </listitem> 4118 </varlistentry> 4119 <varlistentry> 4120 <term><parameter>function</parameter></term> 4121 <listitem> 4122 <para> 4123 the function being added 4124 </para> 4125 </listitem> 4126 </varlistentry> 4127 </variablelist> 4128</refsect1> 4129<refsect1> 4130<title>Context</title> 4131<para> 4132 single threaded during gadget setup 4133</para> 4134</refsect1> 4135<refsect1> 4136<title>Description</title> 4137<para> 4138 After initialization, each configuration must have one or more 4139 functions added to it. Adding a function involves calling its <parameter>bind</parameter>() 4140 method to allocate resources such as interface and string identifiers 4141 and endpoints. 4142 </para><para> 4143 4144 This function returns the value of the function's <function>bind</function>, which is 4145 zero for success else a negative errno value. 4146</para> 4147</refsect1> 4148</refentry> 4149 4150<refentry id="API-usb-function-deactivate"> 4151<refentryinfo> 4152 <title>LINUX</title> 4153 <productname>Kernel Hackers Manual</productname> 4154 <date>July 2017</date> 4155</refentryinfo> 4156<refmeta> 4157 <refentrytitle><phrase>usb_function_deactivate</phrase></refentrytitle> 4158 <manvolnum>9</manvolnum> 4159 <refmiscinfo class="version">4.1.27</refmiscinfo> 4160</refmeta> 4161<refnamediv> 4162 <refname>usb_function_deactivate</refname> 4163 <refpurpose> 4164 prevent function and gadget enumeration 4165 </refpurpose> 4166</refnamediv> 4167<refsynopsisdiv> 4168 <title>Synopsis</title> 4169 <funcsynopsis><funcprototype> 4170 <funcdef>int <function>usb_function_deactivate </function></funcdef> 4171 <paramdef>struct usb_function * <parameter>function</parameter></paramdef> 4172 </funcprototype></funcsynopsis> 4173</refsynopsisdiv> 4174<refsect1> 4175 <title>Arguments</title> 4176 <variablelist> 4177 <varlistentry> 4178 <term><parameter>function</parameter></term> 4179 <listitem> 4180 <para> 4181 the function that isn't yet ready to respond 4182 </para> 4183 </listitem> 4184 </varlistentry> 4185 </variablelist> 4186</refsect1> 4187<refsect1> 4188<title>Description</title> 4189<para> 4190 Blocks response of the gadget driver to host enumeration by 4191 preventing the data line pullup from being activated. This is 4192 normally called during <parameter>bind</parameter>() processing to change from the 4193 initial <quote>ready to respond</quote> state, or when a required resource 4194 becomes available. 4195 </para><para> 4196 4197 For example, drivers that serve as a passthrough to a userspace 4198 daemon can block enumeration unless that daemon (such as an OBEX, 4199 MTP, or print server) is ready to handle host requests. 4200 </para><para> 4201 4202 Not all systems support software control of their USB peripheral 4203 data pullups. 4204 </para><para> 4205 4206 Returns zero on success, else negative errno. 4207</para> 4208</refsect1> 4209</refentry> 4210 4211<refentry id="API-usb-function-activate"> 4212<refentryinfo> 4213 <title>LINUX</title> 4214 <productname>Kernel Hackers Manual</productname> 4215 <date>July 2017</date> 4216</refentryinfo> 4217<refmeta> 4218 <refentrytitle><phrase>usb_function_activate</phrase></refentrytitle> 4219 <manvolnum>9</manvolnum> 4220 <refmiscinfo class="version">4.1.27</refmiscinfo> 4221</refmeta> 4222<refnamediv> 4223 <refname>usb_function_activate</refname> 4224 <refpurpose> 4225 allow function and gadget enumeration 4226 </refpurpose> 4227</refnamediv> 4228<refsynopsisdiv> 4229 <title>Synopsis</title> 4230 <funcsynopsis><funcprototype> 4231 <funcdef>int <function>usb_function_activate </function></funcdef> 4232 <paramdef>struct usb_function * <parameter>function</parameter></paramdef> 4233 </funcprototype></funcsynopsis> 4234</refsynopsisdiv> 4235<refsect1> 4236 <title>Arguments</title> 4237 <variablelist> 4238 <varlistentry> 4239 <term><parameter>function</parameter></term> 4240 <listitem> 4241 <para> 4242 function on which <function>usb_function_activate</function> was called 4243 </para> 4244 </listitem> 4245 </varlistentry> 4246 </variablelist> 4247</refsect1> 4248<refsect1> 4249<title>Description</title> 4250<para> 4251 Reverses effect of <function>usb_function_deactivate</function>. If no more functions 4252 are delaying their activation, the gadget driver will respond to 4253 host enumeration procedures. 4254 </para><para> 4255 4256 Returns zero on success, else negative errno. 4257</para> 4258</refsect1> 4259</refentry> 4260 4261<refentry id="API-usb-interface-id"> 4262<refentryinfo> 4263 <title>LINUX</title> 4264 <productname>Kernel Hackers Manual</productname> 4265 <date>July 2017</date> 4266</refentryinfo> 4267<refmeta> 4268 <refentrytitle><phrase>usb_interface_id</phrase></refentrytitle> 4269 <manvolnum>9</manvolnum> 4270 <refmiscinfo class="version">4.1.27</refmiscinfo> 4271</refmeta> 4272<refnamediv> 4273 <refname>usb_interface_id</refname> 4274 <refpurpose> 4275 allocate an unused interface ID 4276 </refpurpose> 4277</refnamediv> 4278<refsynopsisdiv> 4279 <title>Synopsis</title> 4280 <funcsynopsis><funcprototype> 4281 <funcdef>int <function>usb_interface_id </function></funcdef> 4282 <paramdef>struct usb_configuration * <parameter>config</parameter></paramdef> 4283 <paramdef>struct usb_function * <parameter>function</parameter></paramdef> 4284 </funcprototype></funcsynopsis> 4285</refsynopsisdiv> 4286<refsect1> 4287 <title>Arguments</title> 4288 <variablelist> 4289 <varlistentry> 4290 <term><parameter>config</parameter></term> 4291 <listitem> 4292 <para> 4293 configuration associated with the interface 4294 </para> 4295 </listitem> 4296 </varlistentry> 4297 <varlistentry> 4298 <term><parameter>function</parameter></term> 4299 <listitem> 4300 <para> 4301 function handling the interface 4302 </para> 4303 </listitem> 4304 </varlistentry> 4305 </variablelist> 4306</refsect1> 4307<refsect1> 4308<title>Context</title> 4309<para> 4310 single threaded during gadget setup 4311</para> 4312</refsect1> 4313<refsect1> 4314<title>Description</title> 4315<para> 4316 <function>usb_interface_id</function> is called from usb_function.<function>bind</function> callbacks to 4317 allocate new interface IDs. The function driver will then store that 4318 ID in interface, association, CDC union, and other descriptors. It 4319 will also handle any control requests targeted at that interface, 4320 particularly changing its altsetting via <function>set_alt</function>. There may 4321 also be class-specific or vendor-specific requests to handle. 4322 </para><para> 4323 4324 All interface identifier should be allocated using this routine, to 4325 ensure that for example different functions don't wrongly assign 4326 different meanings to the same identifier. Note that since interface 4327 identifiers are configuration-specific, functions used in more than 4328 one configuration (or more than once in a given configuration) need 4329 multiple versions of the relevant descriptors. 4330 </para><para> 4331 4332 Returns the interface ID which was allocated; or -ENODEV if no 4333 more interface IDs can be allocated. 4334</para> 4335</refsect1> 4336</refentry> 4337 4338<refentry id="API-usb-add-config"> 4339<refentryinfo> 4340 <title>LINUX</title> 4341 <productname>Kernel Hackers Manual</productname> 4342 <date>July 2017</date> 4343</refentryinfo> 4344<refmeta> 4345 <refentrytitle><phrase>usb_add_config</phrase></refentrytitle> 4346 <manvolnum>9</manvolnum> 4347 <refmiscinfo class="version">4.1.27</refmiscinfo> 4348</refmeta> 4349<refnamediv> 4350 <refname>usb_add_config</refname> 4351 <refpurpose> 4352 add a configuration to a device. 4353 </refpurpose> 4354</refnamediv> 4355<refsynopsisdiv> 4356 <title>Synopsis</title> 4357 <funcsynopsis><funcprototype> 4358 <funcdef>int <function>usb_add_config </function></funcdef> 4359 <paramdef>struct usb_composite_dev * <parameter>cdev</parameter></paramdef> 4360 <paramdef>struct usb_configuration * <parameter>config</parameter></paramdef> 4361 <paramdef>int (*<parameter>bind</parameter>) 4362 <funcparams>struct usb_configuration *</funcparams></paramdef> 4363 </funcprototype></funcsynopsis> 4364</refsynopsisdiv> 4365<refsect1> 4366 <title>Arguments</title> 4367 <variablelist> 4368 <varlistentry> 4369 <term><parameter>cdev</parameter></term> 4370 <listitem> 4371 <para> 4372 wraps the USB gadget 4373 </para> 4374 </listitem> 4375 </varlistentry> 4376 <varlistentry> 4377 <term><parameter>config</parameter></term> 4378 <listitem> 4379 <para> 4380 the configuration, with bConfigurationValue assigned 4381 </para> 4382 </listitem> 4383 </varlistentry> 4384 <varlistentry> 4385 <term><parameter>bind</parameter></term> 4386 <listitem> 4387 <para> 4388 the configuration's bind function 4389 </para> 4390 </listitem> 4391 </varlistentry> 4392 </variablelist> 4393</refsect1> 4394<refsect1> 4395<title>Context</title> 4396<para> 4397 single threaded during gadget setup 4398</para> 4399</refsect1> 4400<refsect1> 4401<title>Description</title> 4402<para> 4403 One of the main tasks of a composite <parameter>bind</parameter>() routine is to 4404 add each of the configurations it supports, using this routine. 4405 </para><para> 4406 4407 This function returns the value of the configuration's <parameter>bind</parameter>(), which 4408 is zero for success else a negative errno value. Binding configurations 4409 assigns global resources including string IDs, and per-configuration 4410 resources such as interface IDs and endpoints. 4411</para> 4412</refsect1> 4413</refentry> 4414 4415<refentry id="API-usb-string-id"> 4416<refentryinfo> 4417 <title>LINUX</title> 4418 <productname>Kernel Hackers Manual</productname> 4419 <date>July 2017</date> 4420</refentryinfo> 4421<refmeta> 4422 <refentrytitle><phrase>usb_string_id</phrase></refentrytitle> 4423 <manvolnum>9</manvolnum> 4424 <refmiscinfo class="version">4.1.27</refmiscinfo> 4425</refmeta> 4426<refnamediv> 4427 <refname>usb_string_id</refname> 4428 <refpurpose> 4429 allocate an unused string ID 4430 </refpurpose> 4431</refnamediv> 4432<refsynopsisdiv> 4433 <title>Synopsis</title> 4434 <funcsynopsis><funcprototype> 4435 <funcdef>int <function>usb_string_id </function></funcdef> 4436 <paramdef>struct usb_composite_dev * <parameter>cdev</parameter></paramdef> 4437 </funcprototype></funcsynopsis> 4438</refsynopsisdiv> 4439<refsect1> 4440 <title>Arguments</title> 4441 <variablelist> 4442 <varlistentry> 4443 <term><parameter>cdev</parameter></term> 4444 <listitem> 4445 <para> 4446 the device whose string descriptor IDs are being allocated 4447 </para> 4448 </listitem> 4449 </varlistentry> 4450 </variablelist> 4451</refsect1> 4452<refsect1> 4453<title>Context</title> 4454<para> 4455 single threaded during gadget setup 4456</para> 4457</refsect1> 4458<refsect1> 4459<title>Description</title> 4460<para> 4461 <parameter>usb_string_id</parameter>() is called from <function>bind</function> callbacks to allocate 4462 string IDs. Drivers for functions, configurations, or gadgets will 4463 then store that ID in the appropriate descriptors and string table. 4464 </para><para> 4465 4466 All string identifier should be allocated using this, 4467 <parameter>usb_string_ids_tab</parameter>() or <parameter>usb_string_ids_n</parameter>() routine, to ensure 4468 that for example different functions don't wrongly assign different 4469 meanings to the same identifier. 4470</para> 4471</refsect1> 4472</refentry> 4473 4474<refentry id="API-usb-string-ids-tab"> 4475<refentryinfo> 4476 <title>LINUX</title> 4477 <productname>Kernel Hackers Manual</productname> 4478 <date>July 2017</date> 4479</refentryinfo> 4480<refmeta> 4481 <refentrytitle><phrase>usb_string_ids_tab</phrase></refentrytitle> 4482 <manvolnum>9</manvolnum> 4483 <refmiscinfo class="version">4.1.27</refmiscinfo> 4484</refmeta> 4485<refnamediv> 4486 <refname>usb_string_ids_tab</refname> 4487 <refpurpose> 4488 allocate unused string IDs in batch 4489 </refpurpose> 4490</refnamediv> 4491<refsynopsisdiv> 4492 <title>Synopsis</title> 4493 <funcsynopsis><funcprototype> 4494 <funcdef>int <function>usb_string_ids_tab </function></funcdef> 4495 <paramdef>struct usb_composite_dev * <parameter>cdev</parameter></paramdef> 4496 <paramdef>struct usb_string * <parameter>str</parameter></paramdef> 4497 </funcprototype></funcsynopsis> 4498</refsynopsisdiv> 4499<refsect1> 4500 <title>Arguments</title> 4501 <variablelist> 4502 <varlistentry> 4503 <term><parameter>cdev</parameter></term> 4504 <listitem> 4505 <para> 4506 the device whose string descriptor IDs are being allocated 4507 </para> 4508 </listitem> 4509 </varlistentry> 4510 <varlistentry> 4511 <term><parameter>str</parameter></term> 4512 <listitem> 4513 <para> 4514 an array of usb_string objects to assign numbers to 4515 </para> 4516 </listitem> 4517 </varlistentry> 4518 </variablelist> 4519</refsect1> 4520<refsect1> 4521<title>Context</title> 4522<para> 4523 single threaded during gadget setup 4524</para> 4525</refsect1> 4526<refsect1> 4527<title>Description</title> 4528<para> 4529 <parameter>usb_string_ids</parameter>() is called from <function>bind</function> callbacks to allocate 4530 string IDs. Drivers for functions, configurations, or gadgets will 4531 then copy IDs from the string table to the appropriate descriptors 4532 and string table for other languages. 4533 </para><para> 4534 4535 All string identifier should be allocated using this, 4536 <parameter>usb_string_id</parameter>() or <parameter>usb_string_ids_n</parameter>() routine, to ensure that for 4537 example different functions don't wrongly assign different meanings 4538 to the same identifier. 4539</para> 4540</refsect1> 4541</refentry> 4542 4543<refentry id="API-usb-gstrings-attach"> 4544<refentryinfo> 4545 <title>LINUX</title> 4546 <productname>Kernel Hackers Manual</productname> 4547 <date>July 2017</date> 4548</refentryinfo> 4549<refmeta> 4550 <refentrytitle><phrase>usb_gstrings_attach</phrase></refentrytitle> 4551 <manvolnum>9</manvolnum> 4552 <refmiscinfo class="version">4.1.27</refmiscinfo> 4553</refmeta> 4554<refnamediv> 4555 <refname>usb_gstrings_attach</refname> 4556 <refpurpose> 4557 attach gadget strings to a cdev and assign ids 4558 </refpurpose> 4559</refnamediv> 4560<refsynopsisdiv> 4561 <title>Synopsis</title> 4562 <funcsynopsis><funcprototype> 4563 <funcdef>struct usb_string * <function>usb_gstrings_attach </function></funcdef> 4564 <paramdef>struct usb_composite_dev * <parameter>cdev</parameter></paramdef> 4565 <paramdef>struct usb_gadget_strings ** <parameter>sp</parameter></paramdef> 4566 <paramdef>unsigned <parameter>n_strings</parameter></paramdef> 4567 </funcprototype></funcsynopsis> 4568</refsynopsisdiv> 4569<refsect1> 4570 <title>Arguments</title> 4571 <variablelist> 4572 <varlistentry> 4573 <term><parameter>cdev</parameter></term> 4574 <listitem> 4575 <para> 4576 the device whose string descriptor IDs are being allocated 4577 and attached. 4578 </para> 4579 </listitem> 4580 </varlistentry> 4581 <varlistentry> 4582 <term><parameter>sp</parameter></term> 4583 <listitem> 4584 <para> 4585 an array of usb_gadget_strings to attach. 4586 </para> 4587 </listitem> 4588 </varlistentry> 4589 <varlistentry> 4590 <term><parameter>n_strings</parameter></term> 4591 <listitem> 4592 <para> 4593 number of entries in each usb_strings array (sp[]->strings) 4594 </para> 4595 </listitem> 4596 </varlistentry> 4597 </variablelist> 4598</refsect1> 4599<refsect1> 4600<title>Description</title> 4601<para> 4602 This function will create a deep copy of usb_gadget_strings and usb_string 4603 and attach it to the cdev. The actual string (usb_string.s) will not be 4604 copied but only a referenced will be made. The struct usb_gadget_strings 4605 array may contain multiple languages and should be NULL terminated. 4606 The ->language pointer of each struct usb_gadget_strings has to contain the 4607 same amount of entries. 4608</para> 4609</refsect1> 4610<refsect1> 4611<title>For instance</title> 4612<para> 4613 sp[0] is en-US, sp[1] is es-ES. It is expected that the first 4614 usb_string entry of es-ES contains the translation of the first usb_string 4615 entry of en-US. Therefore both entries become the same id assign. 4616</para> 4617</refsect1> 4618</refentry> 4619 4620<refentry id="API-usb-string-ids-n"> 4621<refentryinfo> 4622 <title>LINUX</title> 4623 <productname>Kernel Hackers Manual</productname> 4624 <date>July 2017</date> 4625</refentryinfo> 4626<refmeta> 4627 <refentrytitle><phrase>usb_string_ids_n</phrase></refentrytitle> 4628 <manvolnum>9</manvolnum> 4629 <refmiscinfo class="version">4.1.27</refmiscinfo> 4630</refmeta> 4631<refnamediv> 4632 <refname>usb_string_ids_n</refname> 4633 <refpurpose> 4634 allocate unused string IDs in batch 4635 </refpurpose> 4636</refnamediv> 4637<refsynopsisdiv> 4638 <title>Synopsis</title> 4639 <funcsynopsis><funcprototype> 4640 <funcdef>int <function>usb_string_ids_n </function></funcdef> 4641 <paramdef>struct usb_composite_dev * <parameter>c</parameter></paramdef> 4642 <paramdef>unsigned <parameter>n</parameter></paramdef> 4643 </funcprototype></funcsynopsis> 4644</refsynopsisdiv> 4645<refsect1> 4646 <title>Arguments</title> 4647 <variablelist> 4648 <varlistentry> 4649 <term><parameter>c</parameter></term> 4650 <listitem> 4651 <para> 4652 the device whose string descriptor IDs are being allocated 4653 </para> 4654 </listitem> 4655 </varlistentry> 4656 <varlistentry> 4657 <term><parameter>n</parameter></term> 4658 <listitem> 4659 <para> 4660 number of string IDs to allocate 4661 </para> 4662 </listitem> 4663 </varlistentry> 4664 </variablelist> 4665</refsect1> 4666<refsect1> 4667<title>Context</title> 4668<para> 4669 single threaded during gadget setup 4670</para> 4671</refsect1> 4672<refsect1> 4673<title>Description</title> 4674<para> 4675 Returns the first requested ID. This ID and next <parameter>n</parameter>-1 IDs are now 4676 valid IDs. At least provided that <parameter>n</parameter> is non-zero because if it 4677 is, returns last requested ID which is now very useful information. 4678 </para><para> 4679 4680 <parameter>usb_string_ids_n</parameter>() is called from <function>bind</function> callbacks to allocate 4681 string IDs. Drivers for functions, configurations, or gadgets will 4682 then store that ID in the appropriate descriptors and string table. 4683 </para><para> 4684 4685 All string identifier should be allocated using this, 4686 <parameter>usb_string_id</parameter>() or <parameter>usb_string_ids_n</parameter>() routine, to ensure that for 4687 example different functions don't wrongly assign different meanings 4688 to the same identifier. 4689</para> 4690</refsect1> 4691</refentry> 4692 4693<refentry id="API-usb-composite-probe"> 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_composite_probe</phrase></refentrytitle> 4701 <manvolnum>9</manvolnum> 4702 <refmiscinfo class="version">4.1.27</refmiscinfo> 4703</refmeta> 4704<refnamediv> 4705 <refname>usb_composite_probe</refname> 4706 <refpurpose> 4707 register a composite driver 4708 </refpurpose> 4709</refnamediv> 4710<refsynopsisdiv> 4711 <title>Synopsis</title> 4712 <funcsynopsis><funcprototype> 4713 <funcdef>int <function>usb_composite_probe </function></funcdef> 4714 <paramdef>struct usb_composite_driver * <parameter>driver</parameter></paramdef> 4715 </funcprototype></funcsynopsis> 4716</refsynopsisdiv> 4717<refsect1> 4718 <title>Arguments</title> 4719 <variablelist> 4720 <varlistentry> 4721 <term><parameter>driver</parameter></term> 4722 <listitem> 4723 <para> 4724 the driver to register 4725 </para> 4726 </listitem> 4727 </varlistentry> 4728 </variablelist> 4729</refsect1> 4730<refsect1> 4731<title>Context</title> 4732<para> 4733 single threaded during gadget setup 4734</para> 4735</refsect1> 4736<refsect1> 4737<title>Description</title> 4738<para> 4739 This function is used to register drivers using the composite driver 4740 framework. The return value is zero, or a negative errno value. 4741 Those values normally come from the driver's <parameter>bind</parameter> method, which does 4742 all the work of setting up the driver to match the hardware. 4743 </para><para> 4744 4745 On successful return, the gadget is ready to respond to requests from 4746 the host, unless one of its components invokes <function>usb_gadget_disconnect</function> 4747 while it was binding. That would usually be done in order to wait for 4748 some userspace participation. 4749</para> 4750</refsect1> 4751</refentry> 4752 4753<refentry id="API-usb-composite-unregister"> 4754<refentryinfo> 4755 <title>LINUX</title> 4756 <productname>Kernel Hackers Manual</productname> 4757 <date>July 2017</date> 4758</refentryinfo> 4759<refmeta> 4760 <refentrytitle><phrase>usb_composite_unregister</phrase></refentrytitle> 4761 <manvolnum>9</manvolnum> 4762 <refmiscinfo class="version">4.1.27</refmiscinfo> 4763</refmeta> 4764<refnamediv> 4765 <refname>usb_composite_unregister</refname> 4766 <refpurpose> 4767 unregister a composite driver 4768 </refpurpose> 4769</refnamediv> 4770<refsynopsisdiv> 4771 <title>Synopsis</title> 4772 <funcsynopsis><funcprototype> 4773 <funcdef>void <function>usb_composite_unregister </function></funcdef> 4774 <paramdef>struct usb_composite_driver * <parameter>driver</parameter></paramdef> 4775 </funcprototype></funcsynopsis> 4776</refsynopsisdiv> 4777<refsect1> 4778 <title>Arguments</title> 4779 <variablelist> 4780 <varlistentry> 4781 <term><parameter>driver</parameter></term> 4782 <listitem> 4783 <para> 4784 the driver to unregister 4785 </para> 4786 </listitem> 4787 </varlistentry> 4788 </variablelist> 4789</refsect1> 4790<refsect1> 4791<title>Description</title> 4792<para> 4793 This function is used to unregister drivers using the composite 4794 driver framework. 4795</para> 4796</refsect1> 4797</refentry> 4798 4799<refentry id="API-usb-composite-setup-continue"> 4800<refentryinfo> 4801 <title>LINUX</title> 4802 <productname>Kernel Hackers Manual</productname> 4803 <date>July 2017</date> 4804</refentryinfo> 4805<refmeta> 4806 <refentrytitle><phrase>usb_composite_setup_continue</phrase></refentrytitle> 4807 <manvolnum>9</manvolnum> 4808 <refmiscinfo class="version">4.1.27</refmiscinfo> 4809</refmeta> 4810<refnamediv> 4811 <refname>usb_composite_setup_continue</refname> 4812 <refpurpose> 4813 Continue with the control transfer 4814 </refpurpose> 4815</refnamediv> 4816<refsynopsisdiv> 4817 <title>Synopsis</title> 4818 <funcsynopsis><funcprototype> 4819 <funcdef>void <function>usb_composite_setup_continue </function></funcdef> 4820 <paramdef>struct usb_composite_dev * <parameter>cdev</parameter></paramdef> 4821 </funcprototype></funcsynopsis> 4822</refsynopsisdiv> 4823<refsect1> 4824 <title>Arguments</title> 4825 <variablelist> 4826 <varlistentry> 4827 <term><parameter>cdev</parameter></term> 4828 <listitem> 4829 <para> 4830 the composite device who's control transfer was kept waiting 4831 </para> 4832 </listitem> 4833 </varlistentry> 4834 </variablelist> 4835</refsect1> 4836<refsect1> 4837<title>Description</title> 4838<para> 4839 This function must be called by the USB function driver to continue 4840 with the control transfer's data/status stage in case it had requested to 4841 delay the data/status stages. A USB function's setup handler (e.g. <function>set_alt</function>) 4842 can request the composite framework to delay the setup request's data/status 4843 stages by returning USB_GADGET_DELAYED_STATUS. 4844</para> 4845</refsect1> 4846</refentry> 4847 4848 4849</sect1> 4850 4851<sect1 id="functions"><title>Composite Device Functions</title> 4852 4853<para>At this writing, a few of the current gadget drivers have 4854been converted to this framework. 4855Near-term plans include converting all of them, except for "gadgetfs". 4856</para> 4857 4858<!-- drivers/usb/gadget/function/f_acm.c --> 4859<refentry> 4860 <refnamediv> 4861 <refname> 4862 .//drivers/usb/gadget/function/f_acm.c 4863 </refname> 4864 <refpurpose> 4865 Document generation inconsistency 4866 </refpurpose> 4867 </refnamediv> 4868 <refsect1> 4869 <title> 4870 Oops 4871 </title> 4872 <warning> 4873 <para> 4874 The template for this document tried to insert 4875 the structured comment from the file 4876 <filename>.//drivers/usb/gadget/function/f_acm.c</filename> at this point, 4877 but none was found. 4878 This dummy section is inserted to allow 4879 generation to continue. 4880 </para> 4881 </warning> 4882 </refsect1> 4883</refentry> 4884<!-- drivers/usb/gadget/function/f_ecm.c --> 4885<refentry> 4886 <refnamediv> 4887 <refname> 4888 .//drivers/usb/gadget/function/f_ecm.c 4889 </refname> 4890 <refpurpose> 4891 Document generation inconsistency 4892 </refpurpose> 4893 </refnamediv> 4894 <refsect1> 4895 <title> 4896 Oops 4897 </title> 4898 <warning> 4899 <para> 4900 The template for this document tried to insert 4901 the structured comment from the file 4902 <filename>.//drivers/usb/gadget/function/f_ecm.c</filename> at this point, 4903 but none was found. 4904 This dummy section is inserted to allow 4905 generation to continue. 4906 </para> 4907 </warning> 4908 </refsect1> 4909</refentry> 4910<!-- drivers/usb/gadget/function/f_subset.c --> 4911<refentry> 4912 <refnamediv> 4913 <refname> 4914 .//drivers/usb/gadget/function/f_subset.c 4915 </refname> 4916 <refpurpose> 4917 Document generation inconsistency 4918 </refpurpose> 4919 </refnamediv> 4920 <refsect1> 4921 <title> 4922 Oops 4923 </title> 4924 <warning> 4925 <para> 4926 The template for this document tried to insert 4927 the structured comment from the file 4928 <filename>.//drivers/usb/gadget/function/f_subset.c</filename> at this point, 4929 but none was found. 4930 This dummy section is inserted to allow 4931 generation to continue. 4932 </para> 4933 </warning> 4934 </refsect1> 4935</refentry> 4936<!-- drivers/usb/gadget/function/f_obex.c --> 4937<refentry> 4938 <refnamediv> 4939 <refname> 4940 .//drivers/usb/gadget/function/f_obex.c 4941 </refname> 4942 <refpurpose> 4943 Document generation inconsistency 4944 </refpurpose> 4945 </refnamediv> 4946 <refsect1> 4947 <title> 4948 Oops 4949 </title> 4950 <warning> 4951 <para> 4952 The template for this document tried to insert 4953 the structured comment from the file 4954 <filename>.//drivers/usb/gadget/function/f_obex.c</filename> at this point, 4955 but none was found. 4956 This dummy section is inserted to allow 4957 generation to continue. 4958 </para> 4959 </warning> 4960 </refsect1> 4961</refentry> 4962<!-- drivers/usb/gadget/function/f_serial.c --> 4963<refentry> 4964 <refnamediv> 4965 <refname> 4966 .//drivers/usb/gadget/function/f_serial.c 4967 </refname> 4968 <refpurpose> 4969 Document generation inconsistency 4970 </refpurpose> 4971 </refnamediv> 4972 <refsect1> 4973 <title> 4974 Oops 4975 </title> 4976 <warning> 4977 <para> 4978 The template for this document tried to insert 4979 the structured comment from the file 4980 <filename>.//drivers/usb/gadget/function/f_serial.c</filename> at this point, 4981 but none was found. 4982 This dummy section is inserted to allow 4983 generation to continue. 4984 </para> 4985 </warning> 4986 </refsect1> 4987</refentry> 4988 4989</sect1> 4990 4991 4992</chapter> 4993 4994<chapter id="controllers"><title>Peripheral Controller Drivers</title> 4995 4996<para>The first hardware supporting this API was the NetChip 2280 4997controller, which supports USB 2.0 high speed and is based on PCI. 4998This is the <filename>net2280</filename> driver module. 4999The driver supports Linux kernel versions 2.4 and 2.6; 5000contact NetChip Technologies for development boards and product 5001information. 5002</para> 5003 5004<para>Other hardware working in the "gadget" framework includes: 5005Intel's PXA 25x and IXP42x series processors 5006(<filename>pxa2xx_udc</filename>), 5007Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>), 5008Renesas SH7705/7727 (<filename>sh_udc</filename>), 5009MediaQ 11xx (<filename>mq11xx_udc</filename>), 5010Hynix HMS30C7202 (<filename>h7202_udc</filename>), 5011National 9303/4 (<filename>n9604_udc</filename>), 5012Texas Instruments OMAP (<filename>omap_udc</filename>), 5013Sharp LH7A40x (<filename>lh7a40x_udc</filename>), 5014and more. 5015Most of those are full speed controllers. 5016</para> 5017 5018<para>At this writing, there are people at work on drivers in 5019this framework for several other USB device controllers, 5020with plans to make many of them be widely available. 5021</para> 5022 5023<!-- !Edrivers/usb/gadget/net2280.c --> 5024 5025<para>A partial USB simulator, 5026the <filename>dummy_hcd</filename> driver, is available. 5027It can act like a net2280, a pxa25x, or an sa11x0 in terms 5028of available endpoints and device speeds; and it simulates 5029control, bulk, and to some extent interrupt transfers. 5030That lets you develop some parts of a gadget driver on a normal PC, 5031without any special hardware, and perhaps with the assistance 5032of tools such as GDB running with User Mode Linux. 5033At least one person has expressed interest in adapting that 5034approach, hooking it up to a simulator for a microcontroller. 5035Such simulators can help debug subsystems where the runtime hardware 5036is unfriendly to software development, or is not yet available. 5037</para> 5038 5039<para>Support for other controllers is expected to be developed 5040and contributed 5041over time, as this driver framework evolves. 5042</para> 5043 5044</chapter> 5045 5046<chapter id="gadget"><title>Gadget Drivers</title> 5047 5048<para>In addition to <emphasis>Gadget Zero</emphasis> 5049(used primarily for testing and development with drivers 5050for usb controller hardware), other gadget drivers exist. 5051</para> 5052 5053<para>There's an <emphasis>ethernet</emphasis> gadget 5054driver, which implements one of the most useful 5055<emphasis>Communications Device Class</emphasis> (CDC) models. 5056One of the standards for cable modem interoperability even 5057specifies the use of this ethernet model as one of two 5058mandatory options. 5059Gadgets using this code look to a USB host as if they're 5060an Ethernet adapter. 5061It provides access to a network where the gadget's CPU is one host, 5062which could easily be bridging, routing, or firewalling 5063access to other networks. 5064Since some hardware can't fully implement the CDC Ethernet 5065requirements, this driver also implements a "good parts only" 5066subset of CDC Ethernet. 5067(That subset doesn't advertise itself as CDC Ethernet, 5068to avoid creating problems.) 5069</para> 5070 5071<para>Support for Microsoft's <emphasis>RNDIS</emphasis> 5072protocol has been contributed by Pengutronix and Auerswald GmbH. 5073This is like CDC Ethernet, but it runs on more slightly USB hardware 5074(but less than the CDC subset). 5075However, its main claim to fame is being able to connect directly to 5076recent versions of Windows, using drivers that Microsoft bundles 5077and supports, making it much simpler to network with Windows. 5078</para> 5079 5080<para>There is also support for user mode gadget drivers, 5081using <emphasis>gadgetfs</emphasis>. 5082This provides a <emphasis>User Mode API</emphasis> that presents 5083each endpoint as a single file descriptor. I/O is done using 5084normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls. 5085Familiar tools like GDB and pthreads can be used to 5086develop and debug user mode drivers, so that once a robust 5087controller driver is available many applications for it 5088won't require new kernel mode software. 5089Linux 2.6 <emphasis>Async I/O (AIO)</emphasis> 5090support is available, so that user mode software 5091can stream data with only slightly more overhead 5092than a kernel driver. 5093</para> 5094 5095<para>There's a USB Mass Storage class driver, which provides 5096a different solution for interoperability with systems such 5097as MS-Windows and MacOS. 5098That <emphasis>Mass Storage</emphasis> driver uses a 5099file or block device as backing store for a drive, 5100like the <filename>loop</filename> driver. 5101The USB host uses the BBB, CB, or CBI versions of the mass 5102storage class specification, using transparent SCSI commands 5103to access the data from the backing store. 5104</para> 5105 5106<para>There's a "serial line" driver, useful for TTY style 5107operation over USB. 5108The latest version of that driver supports CDC ACM style 5109operation, like a USB modem, and so on most hardware it can 5110interoperate easily with MS-Windows. 5111One interesting use of that driver is in boot firmware (like a BIOS), 5112which can sometimes use that model with very small systems without 5113real serial lines. 5114</para> 5115 5116<para>Support for other kinds of gadget is expected to 5117be developed and contributed 5118over time, as this driver framework evolves. 5119</para> 5120 5121</chapter> 5122 5123<chapter id="otg"><title>USB On-The-GO (OTG)</title> 5124 5125<para>USB OTG support on Linux 2.6 was initially developed 5126by Texas Instruments for 5127<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx 5128series processors. 5129Other OTG systems should work in similar ways, but the 5130hardware level details could be very different. 5131</para> 5132 5133<para>Systems need specialized hardware support to implement OTG, 5134notably including a special <emphasis>Mini-AB</emphasis> jack 5135and associated transceiver to support <emphasis>Dual-Role</emphasis> 5136operation: 5137they can act either as a host, using the standard 5138Linux-USB host side driver stack, 5139or as a peripheral, using this "gadget" framework. 5140To do that, the system software relies on small additions 5141to those programming interfaces, 5142and on a new internal component (here called an "OTG Controller") 5143affecting which driver stack connects to the OTG port. 5144In each role, the system can re-use the existing pool of 5145hardware-neutral drivers, layered on top of the controller 5146driver interfaces (<emphasis>usb_bus</emphasis> or 5147<emphasis>usb_gadget</emphasis>). 5148Such drivers need at most minor changes, and most of the calls 5149added to support OTG can also benefit non-OTG products. 5150</para> 5151 5152<itemizedlist> 5153 <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis> 5154 flag, and use it to determine whether or not to include 5155 an OTG descriptor in each of their configurations. 5156 </para></listitem> 5157 <listitem><para>Gadget drivers may need changes to support the 5158 two new OTG protocols, exposed in new gadget attributes 5159 such as <emphasis>b_hnp_enable</emphasis> flag. 5160 HNP support should be reported through a user interface 5161 (two LEDs could suffice), and is triggered in some cases 5162 when the host suspends the peripheral. 5163 SRP support can be user-initiated just like remote wakeup, 5164 probably by pressing the same button. 5165 </para></listitem> 5166 <listitem><para>On the host side, USB device drivers need 5167 to be taught to trigger HNP at appropriate moments, using 5168 <function>usb_suspend_device()</function>. 5169 That also conserves battery power, which is useful even 5170 for non-OTG configurations. 5171 </para></listitem> 5172 <listitem><para>Also on the host side, a driver must support the 5173 OTG "Targeted Peripheral List". That's just a whitelist, 5174 used to reject peripherals not supported with a given 5175 Linux OTG host. 5176 <emphasis>This whitelist is product-specific; 5177 each product must modify <filename>otg_whitelist.h</filename> 5178 to match its interoperability specification. 5179 </emphasis> 5180 </para> 5181 <para>Non-OTG Linux hosts, like PCs and workstations, 5182 normally have some solution for adding drivers, so that 5183 peripherals that aren't recognized can eventually be supported. 5184 That approach is unreasonable for consumer products that may 5185 never have their firmware upgraded, and where it's usually 5186 unrealistic to expect traditional PC/workstation/server kinds 5187 of support model to work. 5188 For example, it's often impractical to change device firmware 5189 once the product has been distributed, so driver bugs can't 5190 normally be fixed if they're found after shipment. 5191 </para></listitem> 5192</itemizedlist> 5193 5194<para> 5195Additional changes are needed below those hardware-neutral 5196<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis> 5197driver interfaces; those aren't discussed here in any detail. 5198Those affect the hardware-specific code for each USB Host or Peripheral 5199controller, and how the HCD initializes (since OTG can be active only 5200on a single port). 5201They also involve what may be called an <emphasis>OTG Controller 5202Driver</emphasis>, managing the OTG transceiver and the OTG state 5203machine logic as well as much of the root hub behavior for the 5204OTG port. 5205The OTG controller driver needs to activate and deactivate USB 5206controllers depending on the relevant device role. 5207Some related changes were needed inside usbcore, so that it 5208can identify OTG-capable devices and respond appropriately 5209to HNP or SRP protocols. 5210</para> 5211 5212</chapter> 5213 5214</book> 5215<!-- 5216 vim:syntax=sgml:sw=4 5217--> 5218