1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 2. USB Host-Side API Model</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="The Linux-USB Host Side API"><link rel="up" href="index.html" title="The Linux-USB Host Side API"><link rel="prev" href="intro.html" title="Chapter 1. Introduction to USB on Linux"><link rel="next" href="types.html" title="Chapter 3. USB-Standard Types"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. USB Host-Side API Model</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="types.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="host"></a>Chapter 2. USB Host-Side API Model</h1></div></div></div><p>Host-side drivers for USB devices talk to the "usbcore" APIs. 2 There are two. One is intended for 3 <span class="emphasis"><em>general-purpose</em></span> drivers (exposed through 4 driver frameworks), and the other is for drivers that are 5 <span class="emphasis"><em>part of the core</em></span>. 6 Such core drivers include the <span class="emphasis"><em>hub</em></span> driver 7 (which manages trees of USB devices) and several different kinds 8 of <span class="emphasis"><em>host controller drivers</em></span>, 9 which control individual busses. 10 </p><p>The device model seen by USB drivers is relatively complex. 11 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>USB supports four kinds of data transfers 12 (control, bulk, interrupt, and isochronous). Two of them (control 13 and bulk) use bandwidth as it's available, 14 while the other two (interrupt and isochronous) 15 are scheduled to provide guaranteed bandwidth. 16 </p></li><li class="listitem"><p>The device description model includes one or more 17 "configurations" per device, only one of which is active at a time. 18 Devices that are capable of high-speed operation must also support 19 full-speed configurations, along with a way to ask about the 20 "other speed" configurations which might be used. 21 </p></li><li class="listitem"><p>Configurations have one or more "interfaces", each 22 of which may have "alternate settings". Interfaces may be 23 standardized by USB "Class" specifications, or may be specific to 24 a vendor or device.</p><p>USB device drivers actually bind to interfaces, not devices. 25 Think of them as "interface drivers", though you 26 may not see many devices where the distinction is important. 27 <span class="emphasis"><em>Most USB devices are simple, with only one configuration, 28 one interface, and one alternate setting.</em></span> 29 </p></li><li class="listitem"><p>Interfaces have one or more "endpoints", each of 30 which supports one type and direction of data transfer such as 31 "bulk out" or "interrupt in". The entire configuration may have 32 up to sixteen endpoints in each direction, allocated as needed 33 among all the interfaces. 34 </p></li><li class="listitem"><p>Data transfer on USB is packetized; each endpoint 35 has a maximum packet size. 36 Drivers must often be aware of conventions such as flagging the end 37 of bulk transfers using "short" (including zero length) packets. 38 </p></li><li class="listitem"><p>The Linux USB API supports synchronous calls for 39 control and bulk messages. 40 It also supports asynchronous calls for all kinds of data transfer, 41 using request structures called "URBs" (USB Request Blocks). 42 </p></li></ul></div><p>Accordingly, the USB Core API exposed to device drivers 43 covers quite a lot of territory. You'll probably need to consult 44 the USB 2.0 specification, available online from www.usb.org at 45 no cost, as well as class or device specifications. 46 </p><p>The only host-side drivers that actually touch hardware 47 (reading/writing registers, handling IRQs, and so on) are the HCDs. 48 In theory, all HCDs provide the same functionality through the same 49 API. In practice, that's becoming more true on the 2.5 kernels, 50 but there are still differences that crop up especially with 51 fault handling. Different controllers don't necessarily report 52 the same aspects of failures, and recovery from faults (including 53 software-induced ones like unlinking an URB) isn't yet fully 54 consistent. 55 Device driver authors should make a point of doing disconnect 56 testing (while the device is active) with each different host 57 controller driver, to make sure drivers don't have bugs of 58 their own as well as to make sure they aren't relying on some 59 HCD-specific behavior. 60 (You will need external USB 1.1 and/or 61 USB 2.0 hubs to perform all those tests.) 62 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="types.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction to USB on Linux </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. USB-Standard Types</td></tr></table></div></body></html> 63