Video4Linux2_en

TheVideo4Linux2API:anintroduction[PostedOctober11,2006bycorbet]YoureditorhasrecentlyhadtheopportunitytowriteaLinuxdriverforacameradevice-thecamerawhichwillbepackagedwiththeOneLaptopPerChildsystem,inparticular.ThisdriverworkswiththeinternalkernelAPIdesignedforsuchpurposes:theVideo4Linux2API.Intheprocessofwritingthiscode,youreditormadetheshockingdiscoverythat,infact,thisAPIisnotparticularlywelldocumented-thoughtheuser-spacesideis,instead,quitewelldocumentedindeed.Inanattempttoremedythesituationsomewhat,LWNwill,overthecomingmonths,publishaseriesofarticlesdescribinghowtowritedriversfortheV4L2interface.V4L2hasalonghistory-thefirstgleamcameintoBillDirks'seyebackaroundAugustof1998.Developmentproceededforyears,andtheV4L2APIwasfinallymergedintothemainlineinNovember,2002,when2.5.46wasreleased.Tothisday,however,quiteafewLinuxdriversdonotsupportthenewerAPI;theconversionprocessisanongoingtask.Meanwhile,theV4L2APIcontinuestoevolve,withsomemajorchangesbeingmadein2.6.18.ApplicationswhichworkwithV4L2remainrelativelyscarce.V4L2isdesignedtosupportawidevarietyofdevices,onlysomeofwhicharetrulyvideoinnature:Thevideocaptureinterfacegrabsvideodatafromatunerorcameradevice.Formany,videocapturewillbetheprimaryapplicationforV4L2.Sinceyoureditor'sexperienceisstrongestinthisarea,thisserieswilltendtoemphasizethecaptureAPI,butthereismoretoV4L2thanthat.Thevideooutputinterfaceallowsapplicationstodriveperipheralswhichcanprovidevideoimages-perhapsintheformofatelevisionsignal-outsideofthecomputer.Avariantofthecaptureinterfacecanbefoundinthevideooverlayinterface,whosejobistofacilitatethedirectdisplayofvideodatafromacapturedevice.Videodatamovesdirectlyfromthecapturedevicetothedisplay,withoutpassingthroughthesystem'sCPU.TheVBIinterfacesprovideaccesstodatatransmittedduringthevideoblankinginterval.Therearetwoofthem,therawandslicedinterfaces,whichdifferintheamountofprocessingoftheVBIdataperformedinhardware.TheradiointerfaceprovidesaccesstoaudiostreamsfromAMandFMtunerdevices.Othertypesofdevicesarepossible.TheV4L2APIhassomestubsforcodecandeffectdevices,bothofwhichperformtransformationsonvideodatastreams.Thoseareashavenotyetbeencompletelyspecified,however,muchlessimplemented.TherearealsotheteletextandradiodatasysteminterfacescurrentlyimplementedintheolderV4L1API;thosehavenotbeenmovedtoV4L2andtheredonotappeartobeanyimmediateplanstodoso.Videodevicesdifferfrommanyothersinthevastnumberofwaysinwhichtheycanbeconfigured.Asaresult,muchofaV4L2driverimplementscodewhichenablesapplicationstodiscoveragivendevice'scapabilitiesandtoconfigurethatdevicetooperateinthedesiredmanner.TheV4L2APIdefinesseveraldozencallbacksfortheconfigurationofparametersliketunerfrequencies,windowingandcropping,framerates,videocompression,imageparameters(brightness,contrast,...),videostandards,videoformats,etc.Muchofthisserieswillbedevotedtolookingathowthisconfigurationprocesshappens.Then,thereisthesmalltaskofactuallyperformingI/Oatvideoratesinanefficientmanner.TheV4L2APIdefinesthreedifferentwaysofmovingvideodatabetweenuserspaceandtheperipheral,someofwhichcanbeonthecomplexside.SeparatearticleswilllookatvideoI/Oandthevideo-buflayerwhichhasbeenprovidedtohandlecommontasks.Subsequentarticleswillappeareveryfewweeks,andwillbeaddedtothelistbelow:Part2:registrationandopen()Part3:Basicioctl()handlingPart4:InputsandOutputsPart5a:ColorsandformatsPart5b:FormatnegotiationPart6a:BasicframeI/OPart6b:StreamingI/OPart7:ControlsVideo4Linux2part2:registrationandopen()[PostedOctober18,2006bycorbet]TheLWN.netVideo4Linux2APIseries.ThisisthesecondarticleintheLWNseriesonwritingdriversfortheVideo4Linux2kernelinterface;thosewhohavenotyetseentheintroductoryarticlemaywishtostartthere.ThisinstallmentwilllookattheoverallstructureofaVideo4Linuxdriverandthedeviceregistrationprocess.Beforestarting,itisworthnotingthattherearetworesourceswhichwillproveinvaluableforanybodyworkingwithvideodrivers:TheV4L2APISpecification.ThisdocumentcoverstheAPIfromtheuser-spacepointofview,but,toagreatextent,V4L2driversimplementthatAPIdirectly.Somostofthestructuresarethesame,andthesemanticsoftheV4L2callsareclearlylaidout.Printacopy(considercuttingouttheFreeDocumentationLicensetexttosavetrees)andkeepitsomewherewithineasyreach.Thevividriverfoundinthekernelsourceasdrivers/media/video/vivi.c.Itisavirtualdriver,inthatitgeneratestestpatternsanddoesnotactuallyinterfacetoanyhardware.Assuch,itservesasarelativelyclearillustrationofhowV4L2driversshouldbewritten.Tostart,everyV4L2drivermustincludetherequisiteheaderfile:#includelinux/videodev2.hMuchoftheneededinformationisthere.Whendiggingthroughtheheadersasadriverauthor,however,you'llalsowanttohavealookatinclude/media/v4l2-dev.h,whichdefinesmanyofthestructuresyou'llbeworkingwith.AvideodriverwillprobablyhavesectionswhichdealwiththePCIorUSBbus(forexample);we'llnotspendmuchtimeonthatpartofthedriverhere.Thereisoftenaninternali2cinterface,whichwillbeexaminedlateroninthisarticleseries.Then,thereistheinterfacetotheV4L2subsystem.Thatinterfaceisbuiltaroundstructvideo_device,whichrepresentsaV4L2device