The Linux-USB Host Side API

150 Pages·2009·1.2 MB·English

The Linux-USB Host Side API
TheLinux-USBHostSideAPI
Thisdocumentationisfreesoftware;youcanredistributeitand/ormodifyitunderthetermsoftheGNUGeneralPublicLicenseaspublishedby
theFreeSoftwareFoundation;eitherversion2oftheLicense,or(atyouroption)anylaterversion.
Thisprogramisdistributedinthehopethatitwillbeuseful,butWITHOUTANYWARRANTY;withouteventheimpliedwarrantyof
MERCHANTABILITYorFITNESSFORAPARTICULARPURPOSE.SeetheGNUGeneralPublicLicenseformoredetails.
YoushouldhavereceivedacopyoftheGNUGeneralPublicLicensealongwiththisprogram;ifnot,writetotheFreeSoftwareFoundation,Inc.,
59TemplePlace,Suite330,Boston,MA02111-1307USA
FormoredetailsseethefileCOPYINGinthesourcedistributionofLinux.
Table of Contents
1.IntroductiontoUSBonLinux..............................................................................................................1
2.USBHost-SideAPIModel....................................................................................................................2
3.USB-StandardTypes.............................................................................................................................4
structusb_ctrlrequest.........................................................................................................................4
4.Host-SideDataTypesandMacros.......................................................................................................6
structusb_host_endpoint....................................................................................................................6
structusb_interface............................................................................................................................7
structusb_interface_cache...............................................................................................................10
structusb_host_config......................................................................................................................11
structusb_device..............................................................................................................................12
usb_interface_claimed......................................................................................................................17
usb_make_path.................................................................................................................................18
usb_endpoint_num...........................................................................................................................19
usb_endpoint_type...........................................................................................................................20
usb_endpoint_dir_in.........................................................................................................................21
usb_endpoint_dir_out.......................................................................................................................21
usb_endpoint_xfer_bulk...................................................................................................................22
usb_endpoint_xfer_control..............................................................................................................23
usb_endpoint_xfer_int.....................................................................................................................24
usb_endpoint_xfer_isoc...................................................................................................................24
usb_endpoint_is_bulk_in.................................................................................................................25
usb_endpoint_is_bulk_out...............................................................................................................26
usb_endpoint_is_int_in....................................................................................................................26
usb_endpoint_is_int_out..................................................................................................................27
usb_endpoint_is_isoc_in..................................................................................................................28
usb_endpoint_is_isoc_out................................................................................................................28
USB_DEVICE.................................................................................................................................29
USB_DEVICE_VER.......................................................................................................................30
USB_DEVICE_INTERFACE_PROTOCOL...................................................................................30
USB_DEVICE_INFO......................................................................................................................31
USB_INTERFACE_INFO...............................................................................................................32
USB_DEVICE_AND_INTERFACE_INFO....................................................................................33
structusbdrv_wrap...........................................................................................................................34
structusb_driver...............................................................................................................................35
structusb_device_driver...................................................................................................................37
structusb_class_driver.....................................................................................................................38
structurb..........................................................................................................................................39
usb_fill_control_urb.........................................................................................................................44
usb_fill_bulk_urb.............................................................................................................................45
usb_fill_int_urb................................................................................................................................46
usb_urb_dir_in.................................................................................................................................48
usb_urb_dir_out...............................................................................................................................48
structusb_sg_request.......................................................................................................................49
iii
5.USBCoreAPIs.....................................................................................................................................51
usb_init_urb.....................................................................................................................................51
usb_alloc_urb...................................................................................................................................52
usb_free_urb.....................................................................................................................................53
usb_get_urb......................................................................................................................................53
usb_anchor_urb................................................................................................................................54
usb_unanchor_urb............................................................................................................................55
usb_submit_urb................................................................................................................................56
usb_unlink_urb.................................................................................................................................58
usb_kill_urb.....................................................................................................................................60
usb_poison_urb................................................................................................................................61
usb_kill_anchored_urbs...................................................................................................................62
usb_poison_anchored_urbs..............................................................................................................63
usb_unpoison_anchored_urbs..........................................................................................................64
usb_unlink_anchored_urbs..............................................................................................................64
usb_wait_anchor_empty_timeout....................................................................................................65
usb_get_from_anchor.......................................................................................................................66
usb_scuttle_anchored_urbs..............................................................................................................67
usb_anchor_empty...........................................................................................................................67
usb_control_msg..............................................................................................................................68
usb_interrupt_msg............................................................................................................................69
usb_bulk_msg..................................................................................................................................71
usb_sg_init.......................................................................................................................................72
usb_sg_wait......................................................................................................................................74
usb_sg_cancel..................................................................................................................................75
usb_get_descriptor...........................................................................................................................76
usb_string.........................................................................................................................................77
usb_get_status..................................................................................................................................78
usb_clear_halt..................................................................................................................................80
usb_set_interface..............................................................................................................................81
usb_reset_configuration...................................................................................................................82
usb_driver_set_configuration...........................................................................................................83
usb_register_dev...............................................................................................................................84
usb_deregister_dev...........................................................................................................................85
usb_driver_claim_interface..............................................................................................................86
usb_driver_release_interface............................................................................................................87
usb_match_id...................................................................................................................................88
usb_register_device_driver..............................................................................................................90
usb_deregister_device_driver...........................................................................................................91
usb_register_driver...........................................................................................................................91
usb_deregister..................................................................................................................................92
usb_autopm_put_interface...............................................................................................................93
usb_autopm_put_interface_async....................................................................................................95
usb_autopm_get_interface...............................................................................................................95
usb_autopm_get_interface_async....................................................................................................97
usb_autopm_set_interface................................................................................................................97
usb_ifnum_to_if...............................................................................................................................98
usb_altnum_to_altsetting.................................................................................................................99
iv
usb_find_interface..........................................................................................................................100
usb_get_dev....................................................................................................................................101
usb_put_dev...................................................................................................................................102
usb_get_intf....................................................................................................................................103
usb_put_intf...................................................................................................................................103
usb_lock_device_for_reset.............................................................................................................104
usb_get_current_frame_number....................................................................................................105
usb_buffer_alloc.............................................................................................................................106
usb_buffer_free..............................................................................................................................107
usb_buffer_map..............................................................................................................................108
usb_buffer_dmasync......................................................................................................................109
usb_buffer_unmap..........................................................................................................................109
usb_buffer_map_sg........................................................................................................................110
usb_buffer_dmasync_sg.................................................................................................................111
usb_buffer_unmap_sg....................................................................................................................112
usb_hub_tt_clear_buffer.................................................................................................................113
usb_root_hub_lost_power..............................................................................................................114
usb_reset_device............................................................................................................................115
usb_queue_reset_device.................................................................................................................116
6.HostControllerAPIs.........................................................................................................................118
usb_calc_bus_time.........................................................................................................................118
usb_hcd_link_urb_to_ep................................................................................................................119
usb_hcd_check_unlink_urb...........................................................................................................120
usb_hcd_unlink_urb_from_ep.......................................................................................................121
usb_hcd_giveback_urb...................................................................................................................122
usb_hcd_resume_root_hub............................................................................................................123
usb_bus_start_enum.......................................................................................................................123
usb_hc_died...................................................................................................................................124
usb_create_hcd...............................................................................................................................125
usb_add_hcd...................................................................................................................................126
usb_remove_hcd............................................................................................................................127
usb_hcd_pci_probe........................................................................................................................128
usb_hcd_pci_remove......................................................................................................................129
usb_hcd_pci_suspend.....................................................................................................................130
usb_hcd_pci_resume......................................................................................................................130
usb_hcd_pci_shutdown..................................................................................................................131
hcd_buffer_create...........................................................................................................................132
hcd_buffer_destroy.........................................................................................................................133
7.TheUSBFilesystem(usbfs)..............................................................................................................134
7.1.Whatfilesarein"usbfs"?........................................................................................................134
7.2.MountingandAccessControl.................................................................................................134
7.3./proc/bus/usb/devices..............................................................................................................135
7.4./proc/bus/usb/BBB/DDD........................................................................................................136
7.5.LifeCycleofUserModeDrivers............................................................................................136
7.6.Theioctl()Requests................................................................................................................137
7.6.1.Management/StatusRequests.....................................................................................138
7.6.2.SynchronousI/OSupport...........................................................................................140
v
7.6.3.AsynchronousI/OSupport.........................................................................................142
vi
Chapter 1. Introduction to USB on Linux
AUniversalSerialBus(USB)isusedtoconnectahost,suchasaPCorworkstation,toanumberof
peripheraldevices.USBusesatreestructure,withthehostastheroot(thesystem’smaster),hubsas
interiornodes,andperipheralsasleaves(andslaves).ModernPCssupportseveralsuchtreesofUSB
devices,usuallyoneUSB2.0tree(480Mbit/seceach)withafewUSB1.1trees(12Mbit/seceach)that
areusedwhenyouconnectaUSB1.1devicedirectlytothemachine’s"roothub".
Thatmaster/slaveasymmetrywasdesigned-inforanumberofreasons,onebeingeaseofuse.Itisnot
physicallypossibletoassemble(legal)USBcablesincorrectly:allupstream"tothehost"connectorsare
therectangulartype(matchingthesocketsonroothubs),andalldownstreamconnectorsarethesquarish
type(ortheyarebuiltintotheperipheral).Also,thehostsoftwaredoesn’tneedtodealwithdistributed
auto-configurationsincethepre-designatedmasternodemanagesallthat.Andfinally,attheelectrical
level,busprotocoloverheadisreducedbyeliminatingarbitrationandmovingschedulingintothehost
software.
USB1.0wasannouncedinJanuary1996andwasrevisedasUSB1.1(withimprovementsinhub
specificationandsupportforinterrupt-outtransfers)inSeptember1998.USB2.0wasreleasedinApril
2000,addinghigh-speedtransfersandtransaction-translatinghubs(usedforUSB1.1and1.0backward
compatibility).
KerneldevelopersaddedUSBsupporttoLinuxearlyinthe2.2kernelseries,shortlybefore2.3
developmentforked.Updatesfrom2.3wereregularlyfoldedbackinto2.2releases,whichimproved
reliabilityandbrought/sbin/hotplugsupportaswellmoredrivers.Suchimprovementswere
continuedinthe2.5kernelseries,wheretheyaddedUSB2.0support,improvedperformance,andmade
thehostcontrollerdrivers(HCDs)moreconsistent.TheyalsosimplifiedtheAPI(tomakebugsless
likely)andaddedinternal"kerneldoc"documentation.
LinuxcanruninsideUSBdevicesaswellasonthehoststhatcontrolthedevices.ButUSBdevice
driversrunninginsidethoseperipheralsdon’tdothesamethingsastheonesrunninginsidehosts,so
they’vebeengivenadifferentname:gadgetdrivers.Thisdocumentdoesnotcovergadgetdrivers.
1
Chapter 2. USB Host-Side API Model
Host-sidedriversforUSBdevicestalktothe"usbcore"APIs.Therearetwo.Oneisintendedfor
general-purposedrivers(exposedthroughdriverframeworks),andtheotherisfordriversthatarepartof
thecore.Suchcoredriversincludethehubdriver(whichmanagestreesofUSBdevices)andseveral
differentkindsofhostcontrollerdrivers,whichcontrolindividualbusses.
ThedevicemodelseenbyUSBdriversisrelativelycomplex.
• USBsupportsfourkindsofdatatransfers(control,bulk,interrupt,andisochronous).Twoofthem
(controlandbulk)usebandwidthasit’savailable,whiletheothertwo(interruptandisochronous)are
scheduledtoprovideguaranteedbandwidth.
• Thedevicedescriptionmodelincludesoneormore"configurations"perdevice,onlyoneofwhichis
activeatatime.Devicesthatarecapableofhigh-speedoperationmustalsosupportfull-speed
configurations,alongwithawaytoaskaboutthe"otherspeed"configurationswhichmightbeused.
• Configurationshaveoneormore"interfaces",eachofwhichmayhave"alternatesettings".Interfaces
maybestandardizedbyUSB"Class"specifications,ormaybespecifictoavendorordevice.
USBdevicedriversactuallybindtointerfaces,notdevices.Thinkofthemas"interfacedrivers",
thoughyoumaynotseemanydeviceswherethedistinctionisimportant.MostUSBdevicesare
simple,withonlyoneconfiguration,oneinterface,andonealternatesetting.
• Interfaceshaveoneormore"endpoints",eachofwhichsupportsonetypeanddirectionofdata
transfersuchas"bulkout"or"interruptin".Theentireconfigurationmayhaveuptosixteenendpoints
ineachdirection,allocatedasneededamongalltheinterfaces.
• DatatransferonUSBispacketized;eachendpointhasamaximumpacketsize.Driversmustoftenbe
awareofconventionssuchasflaggingtheendofbulktransfersusing"short"(includingzerolength)
packets.
• TheLinuxUSBAPIsupportssynchronouscallsforcontrolandbulkmessages.Italsosupports
asynchnouscallsforallkindsofdatatransfer,usingrequeststructurescalled"URBs"(USBRequest
Blocks).
Accordingly,theUSBCoreAPIexposedtodevicedriverscoversquitealotofterritory.You’llprobably
needtoconsulttheUSB2.0specification,availableonlinefromwww.usb.orgatnocost,aswellasclass
ordevicespecifications.
Theonlyhost-sidedriversthatactuallytouchhardware(reading/writingregisters,handlingIRQs,andso
on)aretheHCDs.Intheory,allHCDsprovidethesamefunctionalitythroughthesameAPI.Inpractice,
that’sbecomingmoretrueonthe2.5kernels,buttherearestilldifferencesthatcropupespeciallywith
faulthandling.Differentcontrollersdon’tnecessarilyreportthesameaspectsoffailures,andrecovery
fromfaults(includingsoftware-inducedoneslikeunlinkinganURB)isn’tyetfullyconsistent.Device
driverauthorsshouldmakeapointofdoingdisconnecttesting(whilethedeviceisactive)witheach
differenthostcontrollerdriver,tomakesuredriversdon’thavebugsoftheirownaswellastomakesure
2
Chapter2.USBHost-SideAPIModel
theyaren’trelyingonsomeHCD-specificbehavior.(YouwillneedexternalUSB1.1and/orUSB2.0
hubstoperformallthosetests.)
3
Chapter 3. USB-Standard Types
In<linux/usb/ch9.h>youwillfindtheUSBdatatypesdefinedinchapter9oftheUSBspecification.
ThesedatatypesareusedthroughoutUSB,andinAPIsincludingthishostsideAPI,gadgetAPIs,and
usbfs.
struct usb_ctrlrequest
LINUX
KernelHackersManualApril2009
Name
struct usb_ctrlrequest—SETUPdataforaUSBdevicecontrolrequest
Synopsis
struct usb_ctrlrequest {
__u8 bRequestType;
__u8 bRequest;
__le16 wValue;
__le16 wIndex;
__le16 wLength;
};
Members
bRequestType
matchestheUSBbmRequestTypefield
bRequest
matchestheUSBbRequestfield
wValue
matchestheUSBwValuefield(le16byteorder)
wIndex
matchestheUSBwIndexfield(le16byteorder)
4