Programming Guide for Linux USB Device Drivers

ProgrammingGuideforLinuxUSBDeviceDrivers(c)2000byDetlefFliegl,deti@fliegl.de:usbdoc.tex,v1.322000/12/2518:36:26detiExp$Thisdocumentcanbefoundon://usb.cs.tum.edu/download/usbdocThisdocumentmaynotbepublished,printedorusedinexcerptswithoutexplicitpermissionoftheauthor.11PrefaceThedevelopmentoftheLinuxUSBsubsystemstartedin1997andinthemean-timeitwasredesignedmanytimes.ThisimpliedvariouschangesofitsinternalstructureanditsAPItoo.Soitisevenhardforexperienceddevicedriverde-veloperstokeepuptodatewithallongoingdiscussionsandcurrentchanges.ThisdocumentshouldgivedetailedinformationaboutthecurrentstateoftheUSBsubsystemanditsAPIforUSBdevicedrivers.ThefirstsectionwilldealwiththebasicsofUSBdevices.Youwilllearnaboutdifferenttypesofdevicesandtheirproperties.GoingintodetailyouwillseehowUSBdevicescommunicateonthebus.ThesecondsectiongivesanoverviewoftheLinuxUSBsubsystem[2]andthedevicedriverframework.ThentheAPIanditsdatastructureswillbeexplainedstepbystep.ThelastsectionofthisdocumentcontainsareferenceofallAPIcallsandtheirreturncodes.CONTENTS2Contents1TheUniversalSerialBus41.1HostControllers...........................41.2USBDevicesandTransferCharacteristics.............41.2.1Hubs..............................51.2.2DataFlowTypes.......................51.3EnumerationandDeviceDescriptors................61.3.1StandardDescriptors....................71.3.2DeviceClasses........................81.3.3HumanInterfaceDevices(HID)...............81.4USBDeviceDrivers.........................92TheLinuxUSBSubsystem102.1TheUSBDeviceDriverFramework.................102.1.1FrameworkDataStructures.................112.1.2FrameworkEntryPoints...................122.1.3FrameworkFunctions....................132.2ConfiguringUSBDevices......................142.2.1DescriptorDataStructures.................142.2.2StandardDeviceRequests.................162.3USBTransfers............................172.3.1TransferDataStructures&Macros.............172.3.2URBFunctions........................232.3.3URBMacros.........................242.3.4CompatibilityWrappers...................242.4Examples...............................253Reference263.1ErrorCodes..............................263.1.1Errorcodesreturnedbyusbsubmiturb..........263.1.2URBErrorCodes.......................263.1.3ErrorCodesreturnedbyUSBCoreFunctions.......27LISTOFFIGURES3ListofFigures1USBTopology............................52USBDescriptorHierarchy......................73USBCoreAPILayers........................104usbdriverstructure..........................115Asimpleprobefunction.......................126Asimpledisconnectfunction....................137URBStructure............................188Asimplecompletionhandler....................201THEUNIVERSALSERIALBUS41TheUniversalSerialBusIn1994anallianceoffourindustrialpartners(Compaq,Intel,MicrosoftandNEC)startedtospecifytheUniversalSerialBus(USB).Thebuswasoriginallydesignedwiththeseintentions:ConnectionofthePCtothetelephoneEase-of-usePortexpansionThespecification(version1.0)wasfirstreleasedinjanuary1996andthelatestofficialversion1.1wasreleasedinseptember1998[4].Thedocumentisstillunderdevelopmentandaversion2.0wasannouncedin1999.Moreinformationandallspecificationpaperscanbefoundin[1].TheUSBisstrictlyhierarchicalanditiscontrolledbyonehost.Thehostusesamaster/slaveprotocoltocommunicatewithattachedUSBdevices.Thismeansthateverykindofcommunicationisinitiatedbythehostanddevicescannotestablishanydirectconnectiontootherdevices.ThisseemstobeadrawbackincomparisontootherbusarchitecturesbutitisnotbecausetheUSBwasdesignedasacompromiseofcostsandperformance.Themaster/slaveprotocolsolvesimplicitlyproblemslikecollisionavoidanceordistributedbusarbitration.ThecurrentimplementationoftheUSBallows127devicestobeconnectedatthesametimeandthecommunicationbandwidthislimitedto12Mbit/s.1.1HostControllersTodaytheUSBhostcontrollerisintegratedonmostmotherboardchipsets.OlderboardswhicharenotequippedwithsuchacontrollercanbeupgradedbyPCIcardswithsuchhostcontrollers.AllthesecontrollersarecompatiblewitheithertheOpenHostControllerInterface(OHCIbyCompaq,MicrosoftandNationalSemiconductor)ortheUniversalHostControllerInterface(UHCIbyIntel[7])standard.BothtypeshavethesamecapabilitiesandUSBdevicesdonothavetocareaboutthehostcontroller.BasicallythehardwareofUHCIissimplerandthereforeitneedsamorecomplexdevicedriver,whichcouldcauseslightlymoreCPUload.1.2USBDevicesandTransferCharacteristicsTherearedifferenttypesofUSBdevicesastheycanbeusedfordifferentpurposes.Firstadevicecanbeselfpowered,buspoweredorboth.TheUSBcanprovideapowersupplyupto500mAforitsdevices.Ifthereareonlybuspowereddevicesonthebusthemaximumpowerdissipationcouldbeexceededandthereforeselfpowereddevicesexist.Theyneedtohavetheirownpowersupply.Devicesthatsupportbothpowertypescanswitchtoselfpoweredmodewhenattachinganexternalpowersupply.1THEUNIVERSALSERIALBUS5DeviceDeviceUSBHostControllerVirtualRootHubDeviceHubHubDeviceDeviceUpstreamDownstreamFigure1:USBTopologyEventhemaximumcommunicat