The videobuf2 API.docx
- 文档编号:15720400
- 上传时间:2023-07-07
- 格式:DOCX
- 页数:13
- 大小:29.87KB
The videobuf2 API.docx
《The videobuf2 API.docx》由会员分享,可在线阅读,更多相关《The videobuf2 API.docx(13页珍藏版)》请在冰点文库上搜索。
Thevideobuf2API
Thevideobuf2API
ByJonathanCorbet
June14,2011
Video4Linux2driversarechargedwiththetaskofacquiringvideodatafromasensor(viasomesortofDMAcontroller,usually)andtransferringthosevideoframestouserspace.Theamountofdatabeingmovedmakesperformanceaconsideration;tothatend,V4L2hasdefinedasomewhatcomplexAPItohandlestreamingdata.ImplementingthisAPIaddsacertainamountofcomplexitytoV4L2drivers,butmuchofthatcomplexityisthesamefromonedrivertothenext.Tomakelifeeasierfordriverwriters(andtheirusers),the"videobuf"subsystemwascreatedtohandlemanyofthedetailsofstreamingI/Obuffermanagement.LWNdocumentedvideobuftowardtheendof2009;aversionofthatarticlealsofounditswayintothekernel'sdocumentationdirectory.
ThisistheLinuxkernelwe'retalkingabout,though,so2009isancienthistory.Thevideobufinterfacehassincebeensupersededbyvideobuf2,which,whileclearlyinspiredbytheoriginal,hasadifferentwayofdoingthings.Sothisarticlewillbeanattempttogetcaughtupwiththecurrentstateoftheart-aneffortwhichwillcertainlyinspirethecreationofvideobuf3inthenearfuture.
Whyvideobuf2?
Theoriginalvideobufworkedwell,butitturnedouttobeinflexibleinanumberofways.TheAPIvariedconsiderablydependingonwhichtypeofbufferwasinuse,andtherewasnorealwayfordriverstoaddtheirownspecificmemorymanagementneeds.Videobuf2hascreatedamoreconsistentAPIwhichallowsformorecustomizationinthedriversthemselves.
Buffers
Liketheoriginalvideobuf,videobuf2implementsthreebasictypesofbuffers.Vmallocbuffersareallocatedwithvmalloc(),andarethusvirtuallycontiguousinkernelspace;driversworkingwiththesebuffersalmostinvariablyendupcopyingthedataonceasitpassesthroughthesystem.ContiguousDMAbuffersarephysicallycontiguousinmemory,usuallybecausethehardwarecannotperformDMAtoanyothertypeofbuffer.S/GDMAbuffersarescatteredthroughmemory;theyarethewaytogoifthehardwarecandoscatter/gatherDMA.
Dependingonthetypeofbufferbeingused,thedriverwillneedtoincludeoneofthefollowingheaderfiles:
#include
#include
#include
Onenicedifferencewithvideobuf2isthatadrivercanbewrittentosupportmorethanonemodeifneedbe.Theaboveincludefilesdonotconflictwitheachother,andthevideobuf2interfaceisnearlythesameforallthreemodes.
Abufferforavideoframeisrepresentedbystructvb2_buffer,definedin
(1)thedriverhastotellvideobuf2whattherealsizeofthestructureis,and
(2)thevb2_bufferinstancemustbethefirstfieldinthedriver'sstructure.Youreditormayjustpostapatchtofixthatinthenearfuture.
Avideobuf2drivermustcreateasetofcallbackstogivetothevideobuf2subsystem,fiveofwhicharespecifictothemanagementofbuffers;theyfunctioninasimilar(butnotidentical)mannertothevideobufversions.Thesecallbacksare:
int(*buf_init)(structvb2_buffer*vb);
int(*buf_prepare)(structvb2_buffer*vb);
void(*buf_queue)(structvb2_buffer*vb);
int(*buf_finish)(structvb2_buffer*vb);
void(*buf_cleanup)(structvb2_buffer*vb);
Videobuf2willcallbuf_init()foreachnewbufferafterithasbeenallocated;thedrivercanthenperformanyadditionalinitializationthatneedstobedone.Returningafailurecodewillabortthesetupofthebufferqueue.
Thebuf_prepare()callbackisinvokedwhenuserspacequeuesthebuffer(i.e.inresponsetoaVIDIOC_QBUFoperation);itshoulddoanypreparationwhichmightberequiredbeforethebufferisusedforI/O.buf_queue(),instead,iscalledtopassactualownershipofthebuffertothedriver,indicatingthatit'stimetoactuallystartI/Oonit.
buf_finish()willbecalledjustbeforethebufferispassedbacktouserspace.Onemightquestiontheneedforthiscallback;thedriveralreadyknowswhenabufferhasanewframeforuserspaceand,indeed,musttellvideobuf2aboutit.OnepossibleansweristhatthecompletionofI/Otothebufferisoftenhandledininterruptcontext,whilebuf_finish()willbecalledinprocesscontext.
Finally,buf_cleanup()iscalledjustbeforeabufferisfreedsothatthedrivercandoanyadditionalcleanupworkrequired.
Othervideobuf2callbacks
Intheoriginalvideobuf,theonlycallbacksprovidedbythedriverhadtodowithbuffermanagement.Withvideobuf2,thereareafewothers,startingwith:
int(*queue_setup)(structvb2_queue*q,unsignedint*num_buffers,
unsignedint*num_planes,unsignedlongsizes[],
void*alloc_ctxs[]);
Thisfunction,calledinresponsetoaVIDIOC_REQBUFSioctl()operation,allowsthedrivertoinfluencehowthebufferqueueissetup.Thevb2_queuestructuredescribesthequeueasawhole;we'llseemoreaboutitshortly.Thenum_buffersargumentisthenumberofbuffersrequestedbytheapplication;thedrivercanmodifyitifneeded.num_planescontainsthenumberofdistinctvideoplanesneededtoholdaframe;forpackedformats,itwillbeone,butitwillbelargerifplanarformatsareinuse(seethisarticleformoreinformationonformats).Thesizesarrayshouldcontainthesize(inbytes)ofeachplane.
Thealloc_ctxsfieldcontainsthe"allocationcontext"foreachplane;itiscurrentlyonlyusedbythecontiguousDMAmode.DriverswhichusecontiguousDMAshouldcall:
void*vb2_dma_contig_init_ctx(structdevice*dev)
togetthatcontext;itneedstoberememberedandpassedtovb2_dma_contig_cleanup_ctx()whenthedrivershutsdown.
Therearetwocallbackswhichtellthedriverwhentostartandstopacquiringvideodata:
int(*start_streaming)(structvb2_queue*q);
int(*stop_streaming)(structvb2_queue*q);
Videobuf2willcallstart_streaming()wheneveruserspacewantstostartgrabbingdata.ThatmayhappeninresponsetoaVIDIOC_STREAMONioctl(),butthevideobuf2implementationoftheread()systemcallcanalsouseit.Acalltostop_streaming()willbemadewhenuserspacenolongerwantsdata;thiscallbackshouldnotreturnuntilDMAhasbeenstopped.It'sworthnotingthat,afterthestop_streaming()call,videobuf2willgrabbackallbufferspassedtothedriver;thedrivershouldforgetanyreferencesitmayhavetothosebuffers.
Locking
Thefinaltwocallbacksdeserveasectionoftheirown.Thelockingmodelusedforvideobuf2isnotdocumentedallthatwell;fromwhatyoureditorhasbeenabletogather,therulesaremostlylikethefollowing.Thedriverneedsalock(probablyamutex)whichgovernsaccesstothedeviceasawhole.Then:
∙Callsthatthedrivermakesdirectlyintovideobuf2shouldbemadewiththedevicelockheld.
∙Callbackstothedriverfromvideobuf2shouldassumethatthelockhasalreadybeentaken.Forexample,astart_streaming()callwillresultfromauser-spacerequesttoacquiredatawhichwillhavenecessarilypassedthroughthedriverbeforevideobuf2getsinvolved,so,bythetimestart_streaming()iscalled,thedevicelockwillbeheld.
Withthatcontext,oneneedstoconsideronelittleproblem:
auser-spaceinvocationofVIDIOC_DQBUF,meanttogetabufferfullofdatafromthekernel,mayblockwaitingforabuffertobecomeavailable.That,inturn,maynothappenuntiluserspace(perhapsinadifferentthread)handsabufferbacktothekernelwithVIDIOC_QBUF.Ifthefirstcallblockswiththelockheld,theapplicationwillendupwaitingforaverylongtime.Forthissituation,videobuf2providestwomorecallbacks:
void(*wait_prepare)(structvb2_queue*q);
void(*wait_finish)(structvb2_queue*q);
BeforeaVIDIOC_DQBUFoperationblockstowaitforabuffer,itwillcallwait_prepare()toreleasethedevicelock;onceitstopswaiting,acalltowait_finish()willreacquirethelock.Itmighthavebeenbettertocallthemrelease_lock()andreacquire_lock(),butsoitgoes.
Queuesetup
Withalloftheaboveinplace,thedrivercanintroduceitselftovideobuf2.Thefirststepistofillinavb2_opsstructurewithallofthecallbacksdescribedabove:
staticconststructvb2_opsmy_special_callbacks={
.queue_setup=my_special_queue_setup,
/*...*/
};
Then,tosetupavideobuf2queue(normallydoneeitheratdeviceregistrationordeviceopentime),thedrivershouldallocateavb2_queuestructure:
structvb2_queue{
enumv4l2_buf_typetype;
unsignedintio_modes;
unsignedintio_flags;
conststructvb2_ops*ops;
conststructvb2_mem_ops*mem_ops;
void*drv_priv;
unsignedintbuf_struct_size;
/*Lotsofprivatestuffomitted*/
};
Thestructureshouldbezeroed,andtheabovefieldsfilledin.typeisthebuffertype,usuallyV4L2_BUF_TYPE_VIDEO_CAPTURE.io_modesisabitmaskdescribingwhattypesofbufferscanbehandled:
∙VB2_MMAP:
buffersallocatedwithinthekernelandaccessedviammap();vmallocandcontiguousDMAbufferswillusuallybeofthistype.
∙VB2_USERPTR:
buffersallocatedinuserspace.Normally,onlydeviceswhichcandoscatter/gatherI/Ocandealwithuser-spacebuffers.Interestingly,videobuf2supportscontiguousbuffersallocatedbyuserspace;theonlywaytogetthose,though,istousesomesortof
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- The videobuf2 API
![提示](https://static.bingdoc.com/images/bang_tan.gif)