native api tour rev c

Download Native API Tour Rev C

Post on 08-Nov-2014

46 views

Category:

Documents

1 download

Embed Size (px)

TRANSCRIPT

A Tour of the Native API Purpose of this documentThisdocumentisaimedatprovidingageneralviewofthenativeAPIwhichcomeswith Xenomai.Newcomersshouldfinddesigninformationdescribingthelogicbehindthis interface.ThisdocumentshouldbeausefulcomplementtotheAPIreferencemanual.

What is this API for?SinceXenomaiisintrinsicallyAPIagnostic,itcanrunvariouskindsofinterface flavours,forinstanceVxWorks,pSOS+,uITRONorVRTXlikeemulators,mimicking thesetraditionalRTOSAPIs,usuallyforportinglegacyapplications.Butyoumaynot necessarilywanttobuildyourbrandnewapplicationoverthoseemulatorsbecause compatibilitywithsuchinterfacesisnotanissue;incontrast,youmayjustwanttousea programminginterfacewhichleveragesallthecapabilitiesoftheunderlyingrealtime core,andmakesfulluseofitshighintegrationlevelwiththeGNU/Linuxenvironment. Tothisend,Xenomaibringstwopossibilities:arealtimeextensionofthestandard POSIXAPI,anditsownAPIofchoiceanyapplicationcanuse,whichissemantically closertotheinterfacesprovidedbytraditional(nonPOSIX)RTOS.Thelatterinterfaceis simplycalledthenativeAPI,todifferentiatefromtheothers,whichhavebeendefined outsideoftheXenomairealm.

API characteristicsSinceXenomaiisaboutprovidingastableanddeveloperfriendlyrealtimesystemina GNU/Linuxenvironment,thenativeAPIfollowstheseguidelines:

AcompactAPIThenativeAPIisreasonablycompact,hopefullystillprovidingacomfortable programmingenvironment,inlessthanahundredofdistinctservices.

OrthogonalityCarehasbeentakentoavoidmultiplevariationsofsemanticallyandfunctionallyclose services,thatwouldendupbeingonlydifferentiatedbyvaryingnamesordetailsintheir respectiveprototype. Therationalebehindsuchdesignchoiceisplainsimple:wefeelthattheleveloffreedom broughttotheapplicationdeveloperbyanAPIdoesnotdependonthenumberof availablesystemcalls,butonthecapacitysheisgiventoidentify,pickandcombinethe existingservicesinanonambiguousandreliablefashion.Forthisreason,thoseservices mustbeorthogonal,alwayshaveastraightforwardpurpose,andrelyonrocksolidbasic NativeAPITourRevC03/20/06

mechanismsindependentfromthegeneralflavourorwindowdressingexposedbythe API.

ContextindependenceEvenifthepreferredexecutionenvironmentforXenomaiapplicationsisuserspace context,theremightstillbeafewcaseswhererunningsomeoftherealtimecode embodiedintokernelmodulesisrequired,especiallywithlegacysystemsorverylow endplatformswithunderperformingMMUhardware.Forthisreason,Xenomai'snative APIprovidesthesamesetofrealtimeservicesinaseamlessmannertoapplication regardlessoftheirexecutionspace.Additionally,someapplicationsmayneedrealtime activitiesinbothspacestocooperate,thereforeaspecialcarehasbeentakentoallowthe lattertoworkontheexactsamesetofAPIobjects.

SeamlesstopologyWhatanapparentlycomplexdefinitionforarathersimpleidea!Itjustmeansthatifwe wanttobeabletousethesamesystemcallforperforminganactionwithoutbothering aboutthelocation(e.g.theexecutionspace)ofthetargetobject(e.g.atask,asemaphore etc.),weneedtohidethenittygrittydetailsofhowtoreachsuchobjectintosome opaque,normalizedandshareableobjectidentifier. Tothisend,eachcategoryofservicesinXenomai'snativeAPIdefinesauniform descriptortypetorepresenttheobjectsitmanages,whichcanbeusedeitherinkernelor userspacecontextsindifferently.Forinstance,ataskwillalwaysberepresentedbya RT_TASKdescriptor,amessagequeuebyaRT_QUEUEdescriptor,andasemaphoreby aRT_SEMdescriptor,regardlessoftheexecutionspacefromwhichtheyareused.Such descriptorscanbetransparentlysharedbetweenexecutionspaces,sothatservicescanbe calledforobjectswhichhavebeencreatedfromtheoppositespace;e.g.asemaphore createdbyauserspaceapplicationcanbepostedbyarealtimeinterrupthandlerin kernelspaceandconversely. Then,weneedtoprovideameantoapplicationsforfindingthosedescriptorsona systemwidebasis,preferablyusingafreeformsymbolicnameasthesearchkey,since manipulatingabstractinformationiseasierthanworkingwithcryptictokens.Xenomai's answertothisisaunifiedregistry,whichallowsallcategoriesofrealtimeservicesto indexeachobjecttheycreateonauniquesymbolicsearchkeydefinedbytheapplication, andconversely,providestheapplicationameantoretrievetheunifieddescriptor associatedwithanyregisteredobjectuponrequest. Bythetimethoselinesarewritten,thenativeAPIisnotnetworkdistributable.Thissaid, youwilllikelyseehowthecombinationoftheunifieddescriptorscheme,anextended registryinterfacedwithanetworknameservice,andrealtimenetworklayerssuchas RTNetwillbeabletoprovidewellintegratedandrobustmultinodecapabilitiesto Xenomai'snativeAPI. NativeAPITourRevC03/20/06

NativeAPITourRevC03/20/06

The design of the native APIArchitectureAkeycharacteristicofthenativeAPIstandsinthefactthatitisanoptionalpartofthe Xenomaisystem,justlikeanyotherrealtimewindowdressinginterfacealsoavailable (e.g.VxWorks,pSOS+,VRTXoruITRON).Likeeachoftheseinterfaces,itisbasedon thesamerealtimenanokernel(akathenucleus)underlyingXenomai,whichprovidesa setofgenericRTOSservicesonecanspecializetobuilditsAPIflavourofchoice.The figurebelowillustratessuchlayeredapproach:

syscallinterface

Native POSIX VxWorks pSOS uITRON VRTX

Realtimenucleus HAL AdeosUserspaceapplications KernelbasedapplicationsAsthefigureaboveshows,thenativeXenomaiinterfacehasnospecialprivileges comparedtoothers,andisentirelybasedonthegenericcore'spublicinterfacefora simplereason:thisistheonlywaytomakesurethatsignificantoptimizationsandbug fixesoccurringinthecoreareimmediatelyinheritedbytheouterAPIs,withoutany additionalrisksofregression.Moreover,theservicesprovidedbytherealtimenucleus endupbeingironedbymultipleclientAPIsexercisingitinvariousways,which increasestheoverallrobustnessofthewholesystem.

CallingthenativeAPIThenativeAPIservicesareimplementedbyakernelmodulenamedxeno_nativeinthe standardXenomaidistribution.Theseservicescanbecalledeitherdirectlyfromkernel NativeAPITourRevC03/20/06

spaceusingintermodulefunctioncalls,orfromuserspacecontext,throughaninterface library(libnative.so)issuingthepropersystemcalls,whichendsuprunningtheactual serviceprovidedbythekernelmodule.

CategoriesofservicesXenomai'snativeAPIdefinessixmajorcategoriesofservices.Eachcategorydefinesa setofsystemcalls,mostofwhichbeingavailableseamlesslyinbothkernelanduser spaceexecutioncontexts.

Taskmanagement.Thiscategorydefinesthesetofservicesrelatedtotask schedulingandgeneralmanagement.Anapplicationneedsthesesystemcallsto createtasksandcontroltheirbehaviour.Allofthesebasicservicesarealways builtinthenativeAPImodule,regardlessofthecurrentconfiguration.Thenative APIusesofanincreasingpriorityscalefortasks,whichiscompatiblewiththe POSIXscalefortheSCHED_FIFOschedulingclasssupportedbyLinux,i.e.1is thelowesteffectiveprioritylevelfornativeXenomaitasks,and99isthehighest. Timingservices.Thiscategorygroupsallsystemcallswhicharerelatedtothe systemtimermanagementandqueries.Thisgroupalsoprovidesforgeneral watchdogtimerscalledAlarms. Synchronizationsupport.Sincetasksneedtosynchronizetheiroperationstowork properly,thenativeAPIprovidesseveralsynchronizationobjectswhichcanbe usedforthispurpose:

Countingsemaphores, Mutexes, Conditionvariables, Eventflaggroups.

Messagingandcommunication.Thiscategoryimplementsseveralwaysof exchangingbulksofdatabetweenrealtimetasks,orbetweenrealtimeactivities inkernelspaceandregularLinuxprocessesinuserspace:

Intertasksynchronousmessagepassingsupport, Messagequeues,whichcanspanthekernel/userspaceboundary, Memoryheaps,whichcanalsospanthekernel/userspaceboundary, Messagepipes,forexchangingdatabetweenrealtimetasksandregular Linuxprocesses.

DeviceI/Ohandling.SincehandlingexternalI/Oisoneoftheleastwelldefined areasinRTOSdesign,thenativeAPIonlyfocusesonprovidingsimple mechanismsfordealingwithinterrupts,andaccessingdeviceI/Omemoryfrom NativeAPITourRevC03/20/06

userspacecontext.Usersseekingacompleteframeworkforbuildingrealtime devicedriversshouldrefertotheRTDMinterfaceavailablewithXenomai instead.

Registrysupport.Thiscategoryofservicesisoneofthecornerstonesofthe nativeAPI,since,asdescribedearlier,itbringsafundamentalfeaturewithrespect toprovidingaseamlessaccesstosystemcallsfromdifferentexecutionspaces.

Categoriesaremadeofoneormoresubsetsofcloselyrelatedservices,andmostofthese subsetsareoptional;inotherwords,theycanbeselectedforinclusionornotinthe nativeAPImodule,dependingonyourconfiguration(e.g.yourapplicationmayneed semaphoresbutnotconditionvariables). Moreover,itispossibletodisabletheentiresupportfortheuserspaceexecutioncontext, intheseldomcaseswhereallrealtimeactivitiesareembodiedintokernelmodules. Themainideahereistoprovideenoughconfigurationflexibilitytoembeddedsetups.

LinkingagainstthenativeAPIXenomaiprovidesthexenoconfigscript,whichsendsbackvariousinformationupon request,likethevalidcompilationandlinkflagstopasstotheGCCtoolchainwhen buildingapplicationsforvariousexecutioncontexts(i.e.kernel,userspace,simulation), andthisscriptshouldbequeriedthesamewayforgettingtheproperargumentsinorder tocompileandlinkanapplicationagainstthenativeAPI. Forinstance,atrivialMakefileforcompilingasimpleuserspaceprogramnamed myapp.cwhichusesthenativeAPIwouldlooklikethis:prefix := $(shell xeno-config --prefix) ifeq ($(prefix),) $(error Please add /bin to your PATH variable) endif CFLAGS := $(shell xeno-config --xeno-cflags) LDFLAGS := -lnative $(shell xeno-config --xeno-ldflags) myapp: myapp.c $(CC) -o $@ $< $(CFLAGS) $(LDFLAGS)

Mixable execution modesXenomaiallowsrealtimetasksembodiedintouserspaceprogramstoeitherexecutein theXenomaidomain,orintotheLinuxdomainwithoutincurringthepotential perturbationsinducedbytheasynchronousLinuxkernelactivities,mainlybymeanofthe appropriatemanagementofaninterruptshield.Intheformercase,therealtimetasksare saidtoruninprimaryexecutionmode,whilstinthelattercase,thosetasksaresaidtorun NativeAPITourRevC03/20/06

insecondaryexecutionmode.Byconvention,realtimetasksembodiedintokernel modulesalwaysruninprimarymode,sincethereisnowayforthemtocallregularLinux kernelservicesdirectly. WhenrunningintotheXe

View more >