Porting Newlib

4/17/12
Howto: Porting newlib
Services and Modeling for Embedded Software Development
Howto: Porting n w i elb

A Simple Guide
JeremyBennett Embecosm
ApplicationNote9.Issue1 July2010 Copyright2010EmbecosmLimited Thedocumententitled"Howto:Portingnewlib"byJeremyBennettofEmbecosmislicensedunderaCreative CommonsAttribution2.0UK:England&WalesLicense.SeetheLegalNoticefordetails.
Table of Contents 1.Introduction 1.1.TargetAudience 1.2.Examples 1.3.Furtherinformation 1.4.AboutEmbecosmApplicationNotes 2.n w i withintheGNUToolChain elb 2.1.TheUnifiedSourceTree 2.1.1.IncorporatingN w i withintheToolChainBuild elb 3.Overviewofn w i elb 3.1.Therelationshipbetweenl b l s andn w i igos elb 3.2.TheCNamespaceandReentrantFunctions 3.3.AddinganewTargettoN w i elb 3.3.1.Extendingc n i u e h s foraNewTarget ofgr.ot 4.Modifyingn w i elb 4.1.TheMachineDirectory 4.1.1.UpdatingtheMainMachineDirectoryConfigurationfiles 4.1.2.Implementingthes t m andl n j p ejp o g m functions. 4.1.3.UpdatingtheTargetSpecificMachineDirectoryConfigurationfiles 4.2.ChangingHeaders 4.2.1.IEEEFloatingPoint 4.2.2.s t m BufferSize ejp 4.2.3.MiscellaneousSystemDefinitions 4.2.4.OverridingOtherHeaderFiles 5.Modifyingl b l s igos 5.1.ThePlatformDirectory 5.1.1.EnsuringthePlatformDirectoryisConfigured
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 1/41
4/17/12
5.2.TheCRuntimeInitialization,c t . r0o 5.2.1.Exceptionvectorsetup 5.2.2.The_ t r FunctionandStackInitialization sat 5.2.3.CacheInitialization 5.2.4.ClearingBSS 5.2.5.ConstructorandDestructorHandling 5.2.6.CInitializationFunctions 5.2.7.Invokingthemainprogram 5.3.StandardSystemCallImplementations 5.3.1.ErrorHandling 5.3.2.TheGlobalEnvironment,e v r n nio 5.3.3.Exitaprogram,_ x t ei 5.3.4.Closingafile,c o e ls 5.3.5.TransferControltoaNewProcess,e e v xce 5.3.6.Createanewprocess,f r ok 5.3.7.ProvidetheStatusofanOpenFile,f t t sa 5.3.8.GettheCurrentProcessID,g t i epd 5.3.9.DeterminetheNatureofaStream,i a t sty 5.3.10.SendaSignal,k l il 5.3.11.Renameanexistingfile,l n ik 5.3.12.SetPositioninaFile,l e k se 5.3.13.Openafile,o e pn 5.3.14.ReadfromaFile,r a ed 5.3.15.AllocatemoreHeap,s r bk 5.3.16.StatusofaFile(byName),s a tt 5.3.17.ProvideProcessTimingInformation,t m s ie 5.3.18.RemoveaFile'sDirectoryEntry,u l n nik 5.3.19.WaitforaChildProcess,w i at 5.3.20.WritetoaFile,w i e rt 5.4.ReentrantSystemCallImplementations 5.5.BSPConfigurationandMakefile 5.5.1.c n i u e i fortheBSP ofgr.n 5.5.2.M k f l . n a e i e i fortheBSP 5.6.TheDefaultBSP,l b o y inss 6.Configuring,BuildingandInstallingN w i andL b l s elb igos 6.1.ConfiguringN w i andL b l s elb igos 6.2.BuildingN w i andL b l s elb igos 6.3.TestingN w i andL b l s elb igos 6.4.InstallingN w i andL b l s elb igos 7.ModifyingtheGNUToolChain 7.1.PuttingN w i inaCustomLocation elb 7.2.ChangestoGCC 7.2.1.AddingMachineSpecificOptionsforN w i elb 7.2.2.UpdatingSpecDefinitions 7.3.ChangestotheGNULinker 8.TestingN w i andL b l s elb igos 8.1.TestingN w i elb 8.1.1.CheckingPhysicalHardware 8.2.TestingL b l s igos 9.SummaryChecklist Glossary References
Chapter 1. Introduction
4/17/12

N w i isaClibraryintendedforuseonembeddedsystems.Itisaconglomerationofseverallibraryparts,allunderfreesoftware elb
licensesthatmakethemeasilyusableonembeddedproducts.
1.1. Target Audience

Portingn w i isnotdifficult,butadviceforthebeginneristhinontheground.Thisapplicationnoteisintendedforsoftware elb engineersportingn w i forthefirsttime. elb Thedetailofallthestepsneededarecoveredhere,andhavebeentestedusingn w i versions1.17.0and1.18.0withthe elb OpenRISC1000. Forthosewhoalreadyhavesomeexperience,theentireportingprocessissummarizedinthefinalchapter,withlinksbacktothe maindocument(seeChapter9).It'sausefulchecklistwhencarryingoutanewport.
1.2. Examples
Thisapplicationnoteincludesexamplesfromtheportofn w i totheOpenRISC1000architecture,originallybyChrisBower, elb thenofImperialCollege,London,andsubsequentlyextensivelyupdatedbyJeremyBennettofEmbecosm. TheexamplesaretwoBoardSupportPackages(BSP)forusewiththeOpenRISC1000architecturalsimulatorOr1ksimbythe sametwoauthors. AtthetimeofwritingtheOpenRISC1000implementationisnotpartofthemainn w i distribution.Itcanbedownloadedfrom elb OpenCores(www.opencores.org).
1.3. Further information

Themainsourceofinformationisthen w i website(sourceware.org/newlib).ThisincludesaFAQ,whichhasbriefinstructions elb onportingn w i anddocumentationforl b [1]andl b ,thetwolibrariesmakingupn w i .Thel b documentationis elb ic im elb ic particularlyuseful,becauseitliststhesystemcallswhichmustbeimplementedbyanynewport,includingminimal implementations. Then w i R A M isanothersourceofinformation.Keyheaderfileswithinthesourcealsocontainusefulcommenting,notably elb EDE i e f . andr e t h eeph en.. Thereisalsoamailinglist,< e l b s u c w r . r > n w i @ o r e a e o g wherequestionscanbeasked,ornewportssubmitted. Thisapplicationnotedoesnotcoverthedetailoftestingn w i onphysicalhardware.ThatsubjectiswellcoveredbyDanKegel's elb Crosstoolproject[2]. Thisapplicationnotehasdrawnheavilyonthesesources,andtheauthorwouldliketothanktheprovidersofthatoriginal information.
1.4. About Embecosm Application Notes

Embecosmisaconsultancyspecializinginhardwaremodelingandopensourcetoolchainsfortheembeddedmarket.Ifwecanever beofhelp,pleasegetintouchat< a e @ m e o m c m . slsebcs.o> Aspartofitscommitmenttotheopensourcecommunity,Embecosmpublishesaseriesoffreeandopensourceapplicationnotes, designedtohelpworkingengineerswithpracticalproblems. Feedbackisalwayswelcome,whichshouldbesentto< n o e b c s . o > if@meomcm.
Chapter 2. n w i within the GNU Tool Chain elb

N w i isintendedforusewiththeGNUtoolchain.Ifn w i isincludedwithinthebuildoftheGNUtoolchain,thenallthe elb elb
librarieswillbebuiltandinstalledinthecorrectplacestobefoundbyGCC
2.1. The Unified Source Tree

Thethreeseparatepackages,b n t l ,GCCandGDBarealltakenfromacommonsourcetree.GCCandGDBbothusemany iuis librariesfromb n t l .Itisconvenienttoreassemblethatsourcetreeandmakeasinglebuildofallthetoolstogether. iuis
4/17/12
Theeasiestwaytoachievethisistolinkallthetopleveldirectoriesineachpackageintoasingleunifieddirectory,leavingoutany duplicatedfilesordirectories. Thefollowingbashscriptwilltakeunpackeddistributionsofb n t l GCCandGDBandlinkthemintoasingledirectory,s c . iuis rw
#/i/ah !bnbs cmoetdr=bntl-.85 gc422gb68 opnn_is'iuis21.0 c-.. d-.' uiidscsc nfe_r=rw c $uiidsc d {nfe_r} inr_it" . CS.v" goels=. . V sn frsci i $cmoetdr} o rdr n {opnn_is d o eh "opnn:$rdr co Cmoet sci" cs sci ae rdr i n / |[-az:\/* * AZ-][\]) ; ; * ) sci=./{rdr" rdr".$sci} ; ; ea sc fls`s- $sci} ie=l a {rdr` frfi $fls o n {ie} d o fud on= frii $inr_it o n {goels} d o i ["f ="i ] f $" $" te hn fudys on=e f i dn oe i [- "{on} ] f z $fud" te hn eh "f co $ .lne" .ikd l - $sci}$ . n s {rdr/f f i dn oe inr_it"{goels}$fls" goels=$inr_it {ie} dn oe c . d .
Theentiretoolchaincanthenbeconfiguredandbuiltinaseparatedirectory.Thec n i u e o f g r scriptunderstandstopassontoplevel argumentstosubsidiaryconfigurationscripts.ForexampletoconfiguretobuildaConlytoolchainforthe32bitOpenRISC1000 architecturetobeinstalledin/ p / r 2 e f o t o 3 - l ,thefollowingwouldbeappropriate.
mdrbid ki ul c bid d ul ./r/ofgr -tre=r2ef-eal-agae= -pei=oto3-l .sccniue -agto3-l -nbelnugsc -rfx/p/r2ef c . d .
Eachtoolcanbebuiltwithitsownspecifictargetwithinthatbuilddirectory
c bid d ul mk albidalbntl algsall algcalgb ae l-ul l-iuis l-a l-d l-c l-d c . d .
Note Theinitialmaketarget,a l b i d l - u l isusedtobuildsomeofthebaselinelibrariesandtoolsused throughoutthetoolchain. Similarlythetoolscanbeinstalledusingthefollowing:

4/17/12

c bid d ul mk isalbidisalbntl isalgsisall isalgc\ ae ntl-ul ntl-iuis ntl-a ntl-d ntl-c isalgb ntl-d c . d .
2.1.1. Incorporating
N w i within elb
the Tool Chain Build
N w i canbelinkedintotheunifiedsourcedirectoryinthesamefashion.Allthatisneededistoaddn w i tothecomponent elb elb
directoriesinthelinkingscript.
#/i/ah !bnbs cmoetdr=bntl-.85 gc422nwi-.80gb68 opnn_is'iuis21.0 c-.. elb11. d-.' uiidscsc nfe_r=rw .. .
Theconfigurationcommandshouldalsospecifythatthisisabuildusingn w i elb
mdrbid ki ul c bid d ul ./r/ofgr -tre=r2ef-eal-agae= -wt-elb\ .sccniue -agto3-l -nbelnugsc -ihnwi -pei=oto3-l -rfx/p/r2ef c . d .
Twonewtargetsareneededforn w i ,onetobuildn w i itself,andonetobuildanyboardsupportpackagesusingl b l s (see elb elb igos Chapter3foranexplanationofhowl b l s isusedwithn w i ). igos elb
c bid d ul mk albidalbntl algsall algcaltre-elb\ ae l-ul l-iuis l-a l-d l-c l-agtnwi altre-igosalgb l-agtlbls l-d c . d .
Similarlyadditionaltargetsareneededforinstallation.
c bid d ul mk isalbidisalbntl isalgsisall isalgc\ ae ntl-ul ntl-iuis ntl-a ntl-d ntl-c isaltre-elbisaltre-igosisalgb ntl-agtnwi ntl-agtlbls ntl-d c . d .
Chapter 3. Overview of n w i elb 3.1. The relationship between l b l s and n w i igos elb
N w i isnowdividedintotwoparts.Themainn w i directorycontainsthebulkofthecodeforthetwomainlibraries,l b and elb elb ic l b ,togetherwithanyarchitecturespecificcodeforparticulartargets. im
Thel b l s directorycontainscodespecifictoparticularplatformsonwhichthelibrarywillbeused,generallyreferredtoasthe igos BoardSupportPackage(BSP).AnyparticulartargetarchitecturemayhavemultipleBSPs,forexamplefordifferenthardware platforms,forasimulatoretc. Thetargetarchitecturespecificcodewithinthen w i directorymaybeverymodestpossiblyaslittleasanimplementationof elb s t m andaspecificationoftheIEEEfloatingpointformattouse. ejp Theboardsupportpackageismorecomplex.Itrequiresanimplementationofeighteensystemcallsandthedefinitionofone globaldatastructure,althoughtheimplementationofsomeofthosesystemcallsmaybecompletelytrivial. Note TheseparationofBSPimplementationintol b l s isrelativelyrecent.Consequentlythesource igos treecontainsanumberofoldertargetimplementationswheretheBSPisentirelywithinn w i . elb
4/17/12
Whenlookingforexamples,besuretochooseanarchitecturewhichhasbeenimplementedthrough l b l s .TheOpenRISC1000implementationisonesucharchitecture. igos
3.2. The C Namespace and Reentrant Functions

TheBSPimplementsthesystemcallsfunctionslikec o e w i e l s , r t etc.ItispossiblefortheBSPtoimplementthesedirectly,but thesewillthenbedefinedinthemainCnamespace.Itisperfectlypermissiblefortheusertoreplacethesefunctions,andtheuser versionstakeprecedence,whichrequiressomecareatlinktime.
N w i allowstheimplementerinsteadtoprovidenamespacecleanversionsofthesefunctionsbyprefixingthemwithan elb underscore.N w i willensurethatthesystemcallsmaptothesenamespacecleanversion(i.e.acalltoc o e elb l s becomesacallto _ l s )unlesstheuserhasreimplementedthatfunctionthemselves. coe
Areentrantfunctionmaybesafelycalledfromasecondthread,whileafirstthreadofcontrolisexecuting.Ingeneralafunction thatmodifiesnostaticorglobalstate,willbereentrant. Manysystemcallsaretriviallyreentrant.Howeverforsomecalls,reentrancyisnoteasytoprovideautomatically,soreentrant versionsareprovided.Thusforc o e l s ,thereisthereentrantversionc o e r l s _ .Thereentrantversionstakeanextraargument,a reentrancystructure,whichcanbeusedtoensurecorrectbehavior,byprovidingperthreadversionsofglobaldatastructures. Itisworthnotingthatuseoftheglobalerrorvalue,e r o r n isacommonsourceofnonreentrancy.Thestandardreentrancy structureincludesanentryforaperthreadvalueofe r o rn. Formanysystems,theissueofreentrancydoesnotarise.Ifthereisonlyeveronethreadofcontrol,orifseparatethreadshave theirownaddressspacethereisnoproblem. Howeverit'sworthrememberingthatevenabaremetalsystemmayencounterissueswithreentrancyifeventhandlersare allowedtousethesystemcalls.
N w i givesconsiderableflexibility,particularlywherenamespacecleanversionsofthebasicsystemcallsareimplemented.The elb implementercanchoosetoprovideimplementationsofthereentrantversionsofthefunctions.Alternativelyn w i canprovide elb
reentrancyatthelibrarylevel,butmappingthecallsdownthesystemcalls,whicharenotthemselvesreentrant.Thislastcanoften proveapracticalsolutiontotheproblem.
3.3. Adding a new Target to N w i elb

Addinganewarchitectureton w i requiresthefollowingsteps. elb 1. 2. 3. Provideamachinespecificdirectorywithinthen w i directoryforarchitecturespecificcode,notablythes t m elb ejp implementation. ProvideaplatformdirectoryforBSPimplementation(s)withinthel b l s directory.Thecodeimplementing igos systemscallsforeachBSPisplacedinthisdirectory. Updatethec n i u e h s fileinthen w i directorytopointtothemachineandplatformdirectoriesforthe ofgr.ot elb newtarget.
c n i u e h s for ofgr.ot
3.3.1. Extending
a New Target
Thec n i u e h s fileneedschangesintwoplaces,toidentifythearchitecturespecificmachinedirectoryandtheplatform ofgr.ot directoryforBSPimplementations. Themachinenameisspecifiedinac s switchonthe$ h s _ p } ae { o t c u earlyoninthefile.Addanewc s entrydefiningm c i e t p ae ahn_ye forthearchitecture.ThusforOpenRISC100032bitarchitecturewehave:
o3) r2 mciedro3 ahn_i=r2 ; ;
Thisspecifiesthatthemachinespecificcodeforthisarchitecturewillbefoundinthedirectoryn w i / i c m c i e o 3 . elblb/ahn/r2 Theplatformdirectoryanddetailsarespecifiedinasubsequentc s switchon$ h s } ae { o t (i.e.thefulltriplet,notjusttheCPUtype). Forthe32bitOpenRISC1000wehavethefollowing.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
6/41
4/17/12
o3--) r2** ssaldrssal ycl_i=ycls ; ;
Thisisthesimplestoption,specifyingthattheBSPsforallOpenRISC100032bittargetswillimplementnamespacecleansystem calls,andrelyonn w i tomapreentrantcallsdowntothem.ThedirectorynamefortheBSPimplementationswillmatchthatof elb themachinedirectory,butwithinthel b l s directory.SoforOpenRISC100032bittargetstheBSPimplementationsarein igos lbls/r2 igoso3. TherearefourcommonalternativesforspecifyinghowtheBSPwillbeimplemented. 1. Theimplementerdefinesreentrantnamespacecleanversionsofthesystemcalls.Inthiscase,s s a l d r y c l _ i isset tos s a l asabove,butinaddition,- R E T A T S S A L _ R V D D ycls D E N R N _ Y C L S P O I E isaddedton w i _ f a s e l b c l g in c n i u e h s .FortheOpenRISC100032bittargetwecouldhavedonethiswith: ofgr.ot
o3--) r2** ssaldrssal ycl_i=ycls nwi_fas"{elbclg}-RETATSSAL_RVDD elbclg=$nwi_fas DENRN_YCLSPOIE" ; ;
Forconvenience,stubversionsofthereentrantfunctionsmaybefoundinthel b / e n directory.Thesearein icret factthefunctionsusedifthereentrantsystemcallsarenotprovided,andmaptothenonreentrantversions. 2. Theimplementerdefinesnonreentrant,butnamespacecleanversionsofthesystemcalls.Thisistheapproachwe haveusedwiththeOpenRISC1000andalltheimplementerneedstodointhiscaseistosets s a l d r y c l _ i to s s a l inc n i u e h s .n w i willmapreentrantcallsdowntothenonreentrantversions. ycls ofgr.ot elb Theimplementerdefinesnonreentrant,regularversionsofthesystemcalls(i.e.c o e l s ratherthan_ l s ).The coe librarywillbeneitherreentrant,notnamespaceclean,butwillwork.Inthiscase,- M S I G S S A L N M S D I S N _ Y C L _ A E is addedton w i _ f a s c n i u e h s .FortheOpenRISC1000wecouldhavedonethiswith: e l b c l g in o f g r . o t
3.
o3--) r2** nwi_fas"{elbclg}-MSIGSSALNMS elbclg=$nwi_fas DISN_YCL_AE" ; ;
Noteinparticularthats s a l d r y c l _ i isnotdefinedinthiscase. 4. Theimplementerdefinesnonreentrant,regularversionsofthesystemcalls(i.e.c o e l s ratherthan_ l s ).The coe reentrantsystemcallsaremappedontothesefunctions.Thelibrarywillnotbenamespaceclean,butwilloffer reentrancyatthelibrarylevel.Inthiscase,- M S I G S S A L N M S D I S N _ Y C L _ A E and- R E T A T S S A L _ R V D D D E N R N _ Y C L S P O I E are bothaddedton w i _ f a s c n i u e h s .FortheOpenRISC1000wecouldhavedonethiswith: e l b c l g in o f g r . o t
o3--) r2** nwi_fas"{elbclg}-MSIGSSALNMS elbclg=$nwi_fas DISN_YCL_AE" nwi_fas"{elbclg}-RETATSSAL_RVDD elbclg=$nwi_fas DENRN_YCLSPOIE" ; ;
Noteinparticularthats s a l d r y c l _ i isnotdefinedinthiscase.
Chapter 4. Modifying n w i elb

Changesthatdependonthearchitecture,andnottheparticularplatformbeingused,aremadeinthen w i directory.These elb comprisechangestostandardheadersandcustomcodeforthearchitecture.
4.1. The Machine Directory

Withinthen w i directory,machinespecificcodeisplacedinatargetspecificdirectory,l b / a h n / r h elb icmcieac. Theonlycodethathastobethereistheimplementationofs t m andl n j p ejp o g m ,sincetheimplementationofthesetwofunctions invariablyrequirestargetspecificmachinecode.Howeveranyothertargetspecificcodemayalsobeplacedhere.
4/17/12
4.1.1. Updating the Main Machine Directory Configuration files

ThemachinedirectoryusesGNUautoconfandautomakeforconfiguration.Thereisaconfigurationtemplatefile(c n i u e i ) ofgr.n andMakefiletemplate(M k f l . m a e i e a )inthemainmachinedirectory(l b / a h n withinthen w i directory). icmcie elb
c n i u e a containsac s statementconfiguringthetargetspecificsubdirectories.Thismustbeupdatedtoconfigurethe ofgr.c ae
subdirectoryforthenewtarget.ThusfortheOpenRISC1000wehavethefollowing.
i ts - "{ahn_i};te f et n $mciedr" hn cs $mciedr i ae {ahn_i} n a9)A_OFGSBISa9); 2k CCNI_UDR(2k ; am A_OFGSBISam ; r) CCNI_UDR(r) ; <te mcie ntson ohr ahns o hw> nc7)A_OFGSBISnc7); ev0 CCNI_UDR(ev0 ; o3)A_OFGSBISo3); r2 CCNI_UDR(r2 ; pwrc A_OFGSBISpwrc ; oep) CCNI_UDR(oep) ; <te mcie ntson ohr ahns o hw> xtry6 A_OFGSBISxtry6 ; som1) CCNI_UDR(som1) ; zk A_OFGSBISzk ; 8) CCNI_UDR(8) ; ea; sc f i
Mkfl.m a e i e a isstandardandwillnotneedtobechanged.Havingchangedtheconfigurationtemplate,theconfigurationfile, cniue o f g r ,willneedtoberegenerated.Thisonlyrequiresrunningautoconf
atcn uoof
SinceM k f l . m a e i e a hasnotbeenchangedthereisnoneedtorunautomake
4.1.2. Implementing the
s t m and l n j pfunctions. ejp ogm
s t m andl n j p ejp o g m areapairofCfunctionfacilitatingcrossproceduretransferofcontrol.Typicallytheyareusedtoallow
resumptionofexecutionataknowngoodpointafteranerror. Bothtakeasfirstargumentabuffer,whichisusedtoholdthemachinestateatthejumpdestination.Whens t m iscalledit ejp populatesthatbufferwiththecurrentlocationstate(whichincludesstackandframepointersandthereturnaddressforthecallto s t m ,andreturnszero. ejp

lnjp o g m takesabufferpreviouslypopulatedbys t m .Italsotakesa(nonzero)secondargument,whichwillultimatelybethe ejp resultofthefunctioncall.l n j p o g m restoresthemachinestatefromthebuffer.Itthenjumpstothereturnaddressithasjust restored,passingitssecondargumentastheresult.Thatreturnaddressisthereturnaddressfromtheoriginalcalltos t m ,so ejp theeffectwillbeasifs t m hasjustreturnedwithanonzeroargument. ejp s t m andl n j p ejp o g m aretypicallyusedinatoplevelfunctioninthefollowingway.
#nld <ejph icue stm.> .. . jpbf bf m_u u; i ( = stm (u) f 0 = ejp bf) { nra poesn psigi bf oml rcsig asn n u } es le { errhnln cd ro adig oe } .. .
Duringnormalprocessingifanerrorisfound,thestateheldinb f u canbeusedtoreturncontrolbacktothetoplevelusing lnjp ogm.

4/17/12
#nld <ejph icue stm.> .. . i (ro dtce) f err eetd { lnjp(u,1; ogm bf ) } .. .
Theprogramwillbehaveasthoughtheoriginalcalltos t m hadjustreturnedwithresult1. ejp ItwillbeappreciatedthatthisisbehaviorthatcannotusuallybewritteninC.TheOpenRISC1000implementationisgivenasan example.Thisprocessorhas32registers,r throughr 1 0 3 ,eachof32bits.r isalwaystiedtozero,soneednotbesaved.r 1 0 1 isthe functionresultregister,whichisalwayssetbys t m andl n j p ejp o g m ,soalsoneednotbesaved.Inadditionweshouldsaveand restorethemachine's32bitsupervisionregister,whichholdsthebranchflag. Thusweneedthebuffertobe3132bitwordslong.Thisisdefinedinthes t m header(seeSection4.2.2). ejp IntheApplicationBinaryInterface(ABI)fortheOpenRISC1000,functionargumentsarepassedinregistersr throughr and 3 8 thefunctionreturnaddressisinr . 9 Whendefiningthesetwofunctions,inassembler,beawareofanyprefixconventionsusedbytheCcompiler.Itiscommonfor symbolsdefinedinCtohaveanunderscoreprepended(thisisthecasefortheOpenRISC1000).Thusinthiscasetheassembler shoulddefine_ e j p s t m and_ o g m . lnjp Thisistheimplementationofs t m . ejp
.lbl_ejp goa stm _ejp stm: ls .w 4r)r (3,1 ls .w 8r)r (3,2 ls .w 1(3,3 2r)r ls .w 1(3,4 6r)r ls .w 2(3,5 0r)r ls .w 2(3,6 4r)r ls .w 2(3,7 8r)r ls .w 3(3,8 2r)r ls .w 3(3,9 6r)r ls .w 4(3,1 0r)r0 ls .w 4(3,1 4r)r2 ls .w 4(3,1 8r)r3 ls .w 5(3,1 2r)r4 ls .w 5(3,1 6r)r5 ls .w 6(3,1 0r)r6 ls .w 6(3,1 4r)r7 ls .w 6(3,1 8r)r8 ls .w 7(3,1 2r)r9 ls .w 7(3,2 6r)r0 ls .w 8(3,2 0r)r1 ls .w 8(3,2 4r)r2 ls .w 8(3,2 8r)r3 ls .w 9(3,2 2r)r4 ls .w 9(3,2 6r)r5 ls .w 10r)r6 0(3,2 ls .w 14r)r7 0(3,2 ls .w 18r)r8 0(3,2 ls .w 12r)r9 1(3,2 ls .w 16r)r0 1(3,3 ls .w 10r)r1 2(3,3 lj .r r 9 lad r1r, .di 1,00
/ So 0svdfrfa i ftr * * lt ae o lg n uue /
/ Si r1* * kp 1 /
/ Zr rsl * * eo eut /
Inthissimplifiedimplementation,thestatusflagsarenotsavedthatisapotentialfutureenhancement.Allthegeneralregisters, withtheexceptionofr (alwayszero)andr 1 0 1 (resultregister)aresavedinthebuffer,which,beingthefirstargument,ispointed tobyr . 3 Finallytheresultregister,r 1 1 issettozeroandthefunctionreturnsusingr (theOpenRISC1000hasdelayedbranches,sothe 9 settingofr 1 1 isplacedafterthebranchtoreturn.). Theimplementationofl n j p o g m isslightlymorecomplex,sincethesecondargumentwillbereturnedastheeffectiveresultfrom s t m ,unlessthesecondargumentiszeroinwhichcase1isused. ejp Theresultmustbedealtwithfirstandplacedintheresultregister,r 1 1 ,becausethesecondargument,inr willbesubsequently 4
4/17/12
overwrittenwhenthemachinestateisrestored.Similarlywemustensurethatr ,whichholdsthefirstargumentpointingtothe 3 restorebuffermustitselfbethelastregisterrestored.
.lbl_ogm goa lnjp _ogm: lnjp / Sr ottertr vle* * ot u h eun au / lsn r,0 .fe 4r lb .f 1 f lnp .o lj . 2 f lad r1r, .di 1,01 1 : 2 : lad r1r, .di 1,40 / 1a rsl * * s eut / / vla rsl * * a s eut /
/ Rsoealteohrrgses laigr t ls.* * etr l h te eitr, evn 3 o at / llz r110r) .w 3,2(3 llz r016r) .w 3,1(3 llz r912r) .w 2,1(3 llz r818r) .w 2,0(3 llz r714r) .w 2,0(3 llz r610r) .w 2,0(3 llz r59(3 .w 2,6r) llz r49(3 .w 2,2r) llz r38(3 .w 2,8r) llz r28(3 .w 2,4r) llz r18(3 .w 2,0r) llz r07(3 .w 2,6r) llz r97(3 .w 1,2r) llz r86(3 .w 1,8r) llz r76(3 .w 1,4r) llz r66(3 .w 1,0r) llz r55(3 .w 1,6r) llz r45(3 .w 1,2r) llz r34(3 .w 1,8r) llz r24(3 .w 1,4r) llz r04(3 .w 1,0r) / Oi r1* * mt 1 / llz r,6r) .w 93(3 llz r,2r) .w 83(3 llz r,8r) .w 72(3 llz r,4r) .w 62(3 llz r,0r) .w 52(3 llz r,6r) .w 41(3 llz r,(3 .w 28r) / Si r * * kp 3 / llz r,(3 .w 14r) / So 0svdfrfa i ftr * * lt ae o lg n uue / llz r,2r) .w 31(3 / Nwsf * * o ae / / Rsl i arayi r1 Hvn rsoe r,i wl apa a * eut s led n 1. aig etrd 9 t il per s tog w hv rtre fo teerircl t _ejp Te huh e ae eund rm h ale al o stm. h nnzr rsl gvsi aa tog.* o-eo eut ie t wy huh / lj .r r 9 lnp .o
Thereturnaddress,stackpointerandframepointerhavingbeenrestored,thereturnfromthefunction,willplacetheexecution pointimmediatelyaftertheoriginalcalltos t m . ejp Thefollowingisasimpletestprogram,whichcanbeusedtoverifythats t m andl n j p ejp o g m areworkingcorrectly.
#nld <ejph icue stm.> #nld <ti.> icue sdoh vi od tsi (m_u ev ett jpbf n, it n pe_e) rvrs { it rs=( = pe_e)?pe_e :pe_e +1 n e 0 = rvrs rvrs rvrs ; pit (Ln jmigwt rsl %\" rs; rnf "og upn ih eut dn, e) lnjp(n,rs; ogm ev e) } / tsi ( * * ett ) /
it n mi (n an it ag, rc ca *rv] hr ag[) { jpbf ev m_u n; it rs=stm (n) n e ejp ev; pit (rs=0%8\" rs; rnf "e x0xn, e)
10/41
4/17/12
i (e >1 f rs ) { rtr 0 eun ; } tsi (n,rs; ett ev e) rtr 26 eun 5; } / mi ( * * an ) /
/ W sol nvratal gthr * * e hud ee culy e ee /
4.1.3. Updating the Target Specific Machine Directory Configuration files

c n i u e i andM k f l . m ofgr.n a e i e a filesalsobeneededforthetargetspecificdirectory(i.e.l b / a h n / a g t i c m c i e t r e withinthen w i elb
directory).Thesearegenerallyquitestandard,andtheeasiestapproachistocopytheversionsusedforthefr30architecture. Modernpracticeistousethefilenamec n i u e a ratherthanc n i u e i ,buteitherwillbeacceptedbyautoconf. ofgr.c ofgr.n

Mkfl.m a e i e a shouldbemodifiedifnecessarytospecifythesourcefiles(forexamples t m . andl n j p S ejpS o g m . ).Morecomplex implementationsmayrequiremodificationstoc n i u e i aswell. ofgr.n
ForexampletheOpenRISC1000machinedirectory(l b / a h n / r 2 i c m c i e o 3 withinthen w i directory)containsthefollowing. elb
ATMK_PIN =cgu UOAEOTOS yns ICUE =$NWI_FAS $COSCLG)$TRE_FAS NLDS (ELBCLG) (RS_FAS (AGTCLG) A_CSLG =$ICUE) MCAFAS (NLDS nis_IRRE =lba ontLBAIS i. lbaSUCS=lnjpSstm. i__ORE ogm. ejpS lbaCAFAS$A_CSLG) i__CSLG=(MCAFAS lbaCLG=(MCLG) i__FAS$A_FAS ALCLAFAS=- ./.. - ./../. COA_MLG I ../. I ../.. CNI_TTSDPNECE =$nwi_aei)cniuehs OFGSAU_EEDNIS (elbbsdr/ofgr.ot
Afteranychangesitwillbenecessarytorunautoconfand/orautomaketogeneratenewversionsofc n i u e o f g r andM k f l . n aeiei. autoconfrequiresanumberofn w i specificmacros.Thesecanbegeneratedfromthemainn w i includefile(a i c u e m )by elb elb cnld.4 runningaclocal.Thefullsetofcommandswouldbe.
alcl- ./.. coa I ../. atcn uoof atmk -cgu Mkfl uoae -yns aeie
aclocalonlyneedtoberunthefirsttimethedirectoryiscreated,orwhenmovingthedirectorytoanewreleaseofn w i . elb autoconfneedonlyberuneachtimec n i u e i (orc n i u e a )ischanged.automakeneedonlyberuneachtimeM k f l . m ofgr.n ofgr.c aeiea ischanged.
4.2. Changing Headers

Therearetwoplaces,whereheaderdefinitionsmustbemodifiedforanewtargetarchitecture:thespecificationoftheIEEE floatingpointformatused,andthespecificationofthes t m buffersize. ejp
4.2.1. IEEE Floating Point

Thefloatingpointformatisspecifiedwithinthen w i directoryinl b / n l d / a h n / e e p h elb i c i c u e m c i e i e f . .DetailsofhowtheIEEE754 formatisimplemented,andvariationsfromthestandard,arespecifiedbydefininganumberofCmacros.
_IE_I_NIN _EEBGEDA
Definethismacroifthefloatingpointformatisbigendian. Caution
11/41
4/17/12
One,andonlyoneof_ I E _ I _ N I N _ E E B G E D A and_ I E _ I T E E D A mustbe _EELTL_NIN defined.
_IE_ITEEDA _EELTL_NIN
Definethismacroifthefloatingpointformatislittleendian. Caution One,andonlyoneof_ I E _ I T E E D A and_ I E _ I _ N I N _EELTL_NIN _ E E B G E D A mustbe defined.
_IE_YE_ITEEDA _EEBTSLTL_NIN
Definethismacroinadditionto_ I E _ I _ N I N _ E E B G E D A ,wherethewordsofamultiwordIEEEfloatingpointnumber areinbigendianorder,butthebyteswithineachwordareinlittleendianorder.

_OBEI_2IS DUL_S3BT
Definethisifdoubleprecisionfloatingpointisrepresentedusingthe32bitIEEErepresentation.
_LA_R FOTAG
Floatingpointargumentsareusuallypromotedtodoublewhenpassedasarguments.Ifthisisnotthecase,then thismacroshouldbedefinedtothetypeactuallyusedtopassfloatingpointarguments.
_L_AGS_XOETI_OML FTLRETEPNN_SNRA
DefinethisifthefloatingpointformatusesthelargestexponentforfinitenumbersratherthanNaNand infinities.SuchaformatcannotrepresentNaNsorinfinities,butit'sF T M X L _ A istwicethestandardIEEEvalue.

_L_ODNRAS FTN_EOML
DefinethisifthefloatingpointformatdoesnotsupportIEEEdenormalizednumbers.Inthiscase,everyfloating pointnumberwithazeroexponentistreatedasazerorepresentation. Caution Twoofthesemacros(_ L _ A G S _ X O E T I _ O M L F T L R E T E P N N _ S N R A and_ L _ O D N R A S F T N _ E O M L )specifydeviations fromIEEE754.Thesemacrosonlyworkwithsingleprecisionfloatingpointandmaynotwork correctlyifhardwarefloatingpointsupportisused(enabledbyconfiguringwith- e a l - e l b -nbenwih-p w f ). Formosttargetsitissufficienttodefinejustoneof_ I E _ I _ N I N _ I E _ I T E E D A .Thedefinitionsshouldalwaysbe _ E E B G E D A or _ E E L T L _ N I N surroundedbyaconditional,sotheyareonlyusedwhenthetargetarchitectureisselected.ForexampletheOpenRISC1000is bigendian,soweaddthefollowingtotheheaderfile.
#fdfnd_o3_) i eie(_r2_ #eie_IE_I_NIN dfn _EEBGEDA #ni edf
4.2.2.
s t m Buffer ejp
Size
Theimplementationofs t m andl n j p ejp o g m madeuseofabuffertoholdthemachinestate.Thesizeofthatbufferisarchitecture dependentandspecifiedwithinthen w i directoryinl b / n l d / a h n / e j p h elb icicuemciestm.. Theheaderspecifiesthenumberofentriesinthebufferandthesizeofeachentry(asaCtype).SofortheOpenRISC1000weuse thefollowing.
#fdfnd_o3_) i eie(_r2_ / Eog saefralrg ecp r adr1adtesau rgse * * nuh pc o l es xet 0 n 1 n h tts eitr / #eie_BE 3 dfn JLN 1 #eie_BYEusge ln dfn JTP nind og #ni edf
12/41
4/17/12
Asbefore,thedefinitioniswithinaconditional,soitisonlyusedwhenthetargetistheOpenRISC100032bitarchitecture. Thetypejmp_bufusedwiths t m andl n j p ejp o g m isthendefinedas:
tpdf_BYEjpbf_BE] yee JTP m_u[JLN;
4.2.3. Miscellaneous System Definitions

Varioussystemwideconstantsarespecifiedwithinthen w i directoryinl b / n l d / y / o f g h elb icicuesscni.. Veryoftenthesystemdefaultvaluesarequitesufficient(thisisthecasefortheOpenRISC1000).Howevertargetspecific overridesofthesevaluescanbeprovidedattheendofthisfile.Thisfileisincludedinallothersourcefiles,socanbeusedto redefineanyoftheconstantsusedinthesystem.Theexistingfilegivesnumerousexamplesfromdifferentmachines. Caution AnumberoftheconstantsdefinedheremirrorthoseinGCC'sl m t . file.Theyshouldbekept iish consistent.
4.2.4. Overriding Other Header Files

Ifotherheadersmustbeoverridden(notusuallynecessarywithasimpleport),thenthenewversionscanbeplacedin lb/ahn/rhmcie i c m c i e a c / a h n withinthen w i directory.Theseheaderfileswillbeusedinpreferencetothoseinthestandard elb distribution'sm c i e a h n headerdirectory.
Chapter 5. Modifying l b l s igos

Anytargetarchitecturemayneedmultipleimplementations,suitedtodifferentplatformsonwhichthecodemayrun.The connectionbetweenthelibraryandaspecificplatformisknownasaBoardSupportPackage(BSP).Inrecentversionsofn w i , elb BSPsareseparatedoutintotheirownlibrary,l b l s ,thesourceforwhichisinthetoplevell b l s directory. igos igos Forn w i theBSPwithinl b l s comprisesanimplementationoftheCruntimeinitialization,c t . ,adefinitionofoneglobal elb igos r0o datastructure,andimplementationofeighteensystemcallsforeachplatform. Note
l b l s isarelativelynewadditionton w i .SomeolderportsstillhavetheBSPcodewithinthe igos elb n w i directory. elb
5.1. The Platform Directory

Adirectoryiscreatedinthel b l s directorycorrespondingtothemachinedirectorycreatedinthen w i / i c m c i e igos elblb/ahn directory(seeChapter4). ThisdirectorywillholdthesourcecodefortheCruntimeinitialization(c t . )andforthesystemcallsforeachBSP r0o
5.1.1. Ensuring the Platform Directory is Configured

c n i u e i withinthel b l s directoryincludesac s statementconfiguringthetargetforeachtargetplatform.Thisshould ofgr.n igos ae
beextendedtoaddthenewplatformdirectory.TheOpenRISC100032bittargetrequiresthefollowingchange.
cs "{agt"i ae $tre} n i[46]6*ef |i[46]6*cf* [35]8--l* [35]8--of) A_OFGSBIS[36) CCNI_UDR(i8] ; ; m2--) 3r** A_OFGSBIS[3r) CCNI_UDR(m2] ; ; <te tresntson Ohr agt o hw> su*ef p--l) A_OFGSBIS[p] CCNI_UDR(su) cni_etut=as ofgtssiefle
13/41
4/17/12

cni_inssfle ofglboy=as ; ; o3--) r2** A_OFGSBISo3) CCNI_UDR(r2 ; ; i20--) q00** A_OFGSBIS[q00) CCNI_UDR(i20] ; ; ea sc
Aftermakingthischangethec n i u e o f g r fileshouldberegeneratedbyrunningautoconf.
5.2. The C Runtime Initialization, c t . r0o

TheCRuntimesystemmustcarryoutthefollowingtasks. Setupthetargetplatforminaconsistentstate.Forexamplesettingupappropriateexceptionvectors. Initializethestackandframepointers InvoketheCconstructorinitializationandensuredestructorsarecalledonexit. Carryoutanyfurtherplatformspecificinitialization. CalltheCm i function. an ExitwiththereturncodesuppliediftheCm i functioneverterminates. an Thecodeisinvariablyassembler,althoughitmaycallouttoCfunctions,andisbestillustratedbyexamplefromthe OpenRISC1000.ThisisaBSPdesignedforusewithafastarchitecturalsimulator.Itcomesintwovariants,oneprovidingjust standardoutputtotheconsole,theotherimplementingasimulatedUARTwithbothstandardinputandstandardoutput.The c t . iscommontobothBSPsandfoundinc t . . r00 r0S
5.2.1. Exception vector setup

Thefirstrequirementistopopulatetheexceptionvectors.TheOpenRISC1000usesmemoryfrom0 0 0 1 f forexception x to x f f vectors,withvectorsplaced0 1 0 x 0 bytesapart.Thusaresetexceptionwilljumpto0 1 0 x 0 ,abuserrorexceptionto0 2 0 x 0 andsoon. InthissimpleBSP,thevastmajorityofexceptionsarenotsupported.Iftheyarereceived,theyprintout(usingp i t ) rnf identificationoftheexceptionandtheaddresswhichcausedittothesimulatorconsole,andthenexit.Weprovideamacroforthat assemblycode,sinceitwillbereusedmanytimes.
#eieUHNLDECPINsr dfn NADE_XETO(t) lad r,1-0 .di 1r,2 ls .w 1(1,2 6r)r lad r,12 .di 2r,0 ls .w 1(1,9 2r)r lmvir,i.ft .oh 3h(Lm) loi r,3l(Lm) .r 3r,o.ft ls .w 0r)r (1,3 lmvir,isr .oh 4h(t) loi r,4l(t) .r 4r,osr ls .w 4r)r (1,4 lmsrr,0SREC_AE .fp 5r,P_PRBS ljl _rnf .a pit ls .w 8r)r (1,5 loi .r ljl .a lnp .o lre .f r,00ff 3r,xff _xt ei
/ Sadr poou * * tnad rlge /
/ pit fra srn * * rnf omt tig / / Nm o ecpin* * ae f xeto / / Suc o teitrut* * ore f h nerp /
/ FiueR * * alr C /
\ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \ ; \
/ Nvreeue w hp * * ee xctd e oe /
Thecalltop i t isexpectedtouseastandardformatstring(atthelabel. f t rnf L m )whichrequirestwootherarguments,an identificationstring(labeledbytheparameters tothemacro)andtheprogramcounterwheretheexceptionoccurred(loaded t fromSpecialPurposeRegisterS R E C _ A E P _ P R B S ).Returnfromexceptionisprovidedasaformality,althoughthecalltoe i means xt thatweshouldneverexecuteit. NotethatcompiledCfunctionshavetheirnamesprependedbyunderscoreontheOpenRISC1000.Itisthesenamesthatmustbe
4/17/12
usedfromtheassemblercode. Theformatandidentificationstringsarereadonlydata.
.eto .oaa scin rdt .ft .tig"nade % ecpina ades%8\" Lm: srn Uhnld s xeto t drs 0pn .20 .tig"u err L0: srn bs ro" .30 .tig"aapg fut L0: srn dt ae al" .40 .tig"ntuto pg fut L0: srn isrcin ae al" .50 .tig"ie" L0: srn tmr .60 .tig"lgmn" L0: srn ainet .70 .tig"lea isrcin L0: srn ilgl ntuto" .80 .tig"xenlitrut L0: srn etra nerp" .90 .tig"aaTB L0: srn dt L" .a0 .tig"ntuto TB L0: srn isrcin L" .b0 .tig"ag" L0: srn rne .c0 .tig"ycl" L0: srn ssal .d0 .tig"laigpit L0: srn fotn on" .e0 .tig"rp L0: srn ta" .f0 .tig"neie 0f0 L0: srn udfnd x0" .10:.tig"neie 010" L00 srn udfnd x00 .10:.tig"neie 010" L10 srn udfnd x10 .10:.tig"neie 010" L20 srn udfnd x20 .10:.tig"neie 010" L30 srn udfnd x30 .10:.tig"neie 010" L40 srn udfnd x40 .10:.tig"neie 010" L50 srn udfnd x50 .10:.tig"neie 010" L60 srn udfnd x60 .10:.tig"neie 010" L70 srn udfnd x70 .10:.tig"neie 010" L80 srn udfnd x80 .10:.tig"neie 010" L90 srn udfnd x90 .10:.tig"neie 010" La0 srn udfnd xa0 .10:.tig"neie 010" Lb0 srn udfnd xb0 .10:.tig"neie 010" Lc0 srn udfnd xc0 .10:.tig"neie 010" Ld0 srn udfnd xd0 .10:.tig"neie 010" Le0 srn udfnd xe0 .10:.tig"neie 010" Lf0 srn udfnd xf0
Thefirstexecutablecodeisfortheexceptionvectors.Thesemustgofirstinmemory,soareplacedintheirownsection,. e t r . vcos Thelinker/loaderwillensurethisthiscodeisplacedfirstinmemory(seeSection7.3). Theresetvectorjustjumpstothestartcode.Thecodeistoolargetositwithinthe0 1 0 x 0 bytesofanexceptionvectorentry,andis placedinthemaintextspace,infunction_ t r . sat
.eto .etr,a" scin vcos"x / 010 RSTecpin* * x0: EE xeto / .r og 010 x0 _ee: rst / Jm t pormiiilsto cd * * up o rga ntaiain oe / lmvir,i_tr) .oh 2h(sat loi r,2l(sat .r 2r,o_tr) lj .r r 2 lnp .o
Thesecondvector,ataddress0 2 0 x 0 isthebuserrorexceptionvector.Innormaluse,likeallotherexceptionsititcausesexitand usestheU H N L D E C P I N N A D E _ X E T O macro. Howeverduringstartup,thecodetriesdeliberatelytowriteoutofmemory,todeterminetheendofmemory,whichwilltrigger thisbusexception.Forthisasimpleexceptionhandler,whichjustskipstheoffendinginstructionisrequired. Thesolutionistoplacethiscodefirst,followedbytheunhandledexceptioncode.Oncetheendofmemoryhasbeenlocated,the initialcodecanbeoverwrittenbyl n p . o opcodes,sotheexceptionwilldropthroughtotheU H N L D E C P O N N A D E _ X E T O code.
.r og 020 x0 _uer bsr: lmsrr4r,P_PRBS .fp 2,0SREC_AE lad r4r44 .di 2,2, lmsrr,2,P_PRBS .tp 0r4SREC_AE lre .f _uersd bsr_t: UHNLDECPIN(L0) NADE_XETO .20
/ Rtr oeisrcino * * eun n ntuto n /
Noeffortismadetosavetheregister(r 4 2 )thatisusedinthehandler.Thestartupcodetestingforendofmemorymustnotuse
4/17/12
thisregister. Thenextexception,datapagefault,atlocation0x300,likeallotherexceptionsisunhandled.
.r og 030 x0 UHNLDECPIN(L0) NADE_XETO .30
5.2.2. The
_ t r Function sat
and Stack Initialization
TheOpenRISC1000ABIusesafallingstack.Thelinkerwillplacecodeandstaticdataatthebottomofmemory(startingwiththe exceptionvectors).Theheapthenstartsimmediatelyafterthis,whilethestackgrowsdownfromtheendofmemory. Thelinkerwillsupplytheaddressforthestartofheap(itisintheglobalvariablee d n ).Howeverwemustfindthestacklocationby tryingtowritetomemoryabovetheheaptodeterminetheendofmemory.Ratherthanwritetoeverylocation,thecodeassumes memoryisamultipleof64KB,andtrieswritingtothelastwordofeach64KBblockabovee d n untilthevaluereadbackfails. Thisfailurewilltriggerabuserrorexception,whichmustbehandled(seeSection5.2.1).Theaddressusedforthestartofthestack (whichisalsothelastwordofmemory)isstoredinagloballocation,_ t c (whichCwillrecognizeass a k sak t c ).
.eto .aa scin dt .lbl_tc goa sak _tc:.pc 40 sak sae ,
_ t r isdeclaredsoitlookslikeaCfunction.GDBknowsthat_ t r isspecial,andthiswillensurethatbacktracesdonotwind sat sat backfurtherthanm i .Itislocatedinordinarytextspace,sowillbeplacedwithothercodebythelinker/loader. an
.eto .et scin tx .lbl_tr goa sat .ye _tr,fnto tp sat@ucin _tr: sat
Thefirstmemorylocationtotestisfoundbyroundingthee d n locationdowntoamultipleof64KB,thentakingthelastwordof the64KBabovethat.0 a a a a isusedasthetestwordtowritetomemoryandreadback. xaaaa
lmvir0h(n) .oh 3,ied loi r0r0l(n) .r 3,3,oed lsl r0r01 .ri 3,3,6 lsl r0r01 .li 3,3,6 lad r8r, .di 2,01 lsl r8r81 .li 2,2,6 lad r0r0r8 .d 3,3,2 lad r0r0.di 3,3,4 lmvir60aa .oh 2,xaa loi r6r60aa .r 2,2,xaa
/ Ruddw t 6K budr * * on on o 4B onay / / Cntn 6K i rgse * * osat 4B n eitr /
/ S oewr isd nx 6K?* * P n od nie et 4B / / Ts ptent soei mmr * * et atr o tr n eoy /
Each64KBblockistestedbywritingthetestvalueandreadingbacktoseeifitmatches.
.3 L: ls .w llz .w lse .fq lbf .n lnp .o lj . lad .d .4 L: 0r0,2 (3)r6 r40r0 2,(3) r4r6 2,2 .4 L .3 L r0r0r8 3,3,2
/ Ty6K hge * * r 4B ihr /
Thepreviousvalueisthenthelocationtouseforendofstack,andshouldbestoredinthe_ t c location. sak
16/41
4/17/12

lsb r0r0r8 .u 3,3,2 lmvir6h(sak .oh 2,i_tc) loi r6r6l(sak .r 2,2,o_tc) ls .w 0r6,3 (2)r0 / Peiu vlewswne * * rvos au a atd /
Thestackpointer(r )andframepointer(r )canbeinitializedwiththisvalue. 1 2
lad .d lad .d
r,3,0 1r0r r,3,0 2r0r
Havingdeterminedtheendofmemory,thereisnoneedtohandlebuserrorssilently.Thewordsofcodebetween_ u e r b s r and _uersd b s r _ t canbereplacedbyl n p .o.
lmvir0h(bsr) .oh 3,i_uer loi r0r0l(bsr) .r 3,3,o_uer lmvir8h(bsr_t) .oh 2,i_uersd loi r8r8l(bsr_t) .r 2,2,o_uersd lmvir6010 .oh 2,x50 / lnp0* * .o / loi r6r6000 .r 2,2,x00 .5 L: lse r8r0 .fq 2,3 lb .f .6 L lnp .o ls .w 0r0,2 (3)r6 lj . .5 L lad r0r04 .di 3,3, .6 L: / Pthteisrcin* * ac h ntuto / / Nx isrcin* * et ntuto /
Note Itisessentialthatthiscodeisbeforeanydataorinstructioncacheisinitialized.Otherwisemore complexstepswouldberequiredtoenforcedatawritebackandinvalidateanyinstructioncache entry.
5.2.3. Cache Initialization

TheOpenRISC1000hasoptionalinstructionanddatacaches.Ifthesearedeclared(intheo 1 s m b a d h r k i - o r . header),thenthey mustbeenabledbysettingtheappropriatebitinthesupervisionregister. Thisisanexampleofmachinespecificinitialization.
/ Cceiiilsto.Eal I ado D * * ah ntaiain nbe C n/r C / .fI_NBE| D_NBE i CEAL | CEAL lmsrr0r,P_R .fp 1,0SRS .fI_NBE i CEAL loi r0r0SRS_C .r 1,1,P_RIE .ni edf .fD_NBE i CEAL loi r0r0SRS_C .r 1,1,P_RDE .ni edf lmsrr,1,P_R .tp 0r0SRS lnp .o / Fuhteppln.* * ls h ieie / lnp .o lnp .o lnp .o lnp .o .ni edf
5.2.4. Clearing BSS

BSSistheareaofmemoryusedtoholdstaticvariableswhichmustbeinitializedtozero.Itsstartandendaredefinedbytwo variablesfromthelinker/loader,_ b s s a t _ s _ t r ande d n respectively.
lmvir8h(_s_tr) .oh 2,i_bssat loi r8r8l(_s_tr) .r 2,2,o_bssat
17/41
4/17/12
lmvir0h(n) .oh 3,ied loi r0r0l(n) .r 3,3,oed .1 L: ls .w ()r8,0 0(2)r lslur8r0 .ft 2,3 lb .f .1 L lad r8r84 .di 2,2,
5.2.5. Constructor and Destructor Handling

GCCmayrequireconstructorstobeinitializedatstartupanddestructorstobecalledonexit.ThisbehavioriscapturedintheGCC functions_ d _ l b l c o s _ o g o a _ t r and_ d _ l b l d o s _ o g o a _ t r .Thereissomecomplexityassociatedwiththisfunctionality,sincetheremay beseparatelistsforthemaincodeandsharedlibrariesthataredynamicallyloaded. Itisusualtowrapthisfunctionalityintwofunctions,i i andf n ,whichareplacedintheirownsections,. n t nt ii i i and. i i f n .The .nt i i sectionisloadedbeforeallothertextsectionsandthe. i i f n sectionafterallothertextsections. Thestartupcodeshouldcalli i tohandleanyconstructors. nt
ljl .a lnp .o
ii nt
Thef n functionispassedtothelibraryfunction_ t x t ii a e i toensureitiscalledonanormalexit.
lmvir,ifn) .oh 3h(ii ljl _txt .a aei loi r,3l(ii .r 3r,ofn)
/ Dlyso * * ea lt /
5.2.6. C Initialization Functions

NowthattheCinfrastructureissetup,itisappropriatetocallanyCfunctionsthatareusedduringinitialization.Inthe OpenRISC1000casethisisafunctiontoinitializeaUART.OnlyoneversionofthelibraryactuallyhasaUART.Howeveritis easiesttosubstituteadummyversionoftheinitializationfunctionintheversionofthelibrarywithoutaUART,ratherthan makingthisfunctionconditional.
ljl .a lnp .o
_ur_nt _atii
5.2.7. Invoking the main program

Thefinalstageistocallthemainprogram.Inthissimpleimplementationthereisnomechanismtopassargumentsor environmentstom i ,sotheargumentsa g ,a g ande v r ,r andr )aresetto0 N L andN L respectively. an rc rv n (in 3 4 5 , U L UL
lo .r lo .r ljl .a lo .r
r,0r 3r,0 r,0r 4r,0 _an mi r,0r 5r,0
/ Dlyso * * ea lt /
Ifthemainprogramreturns,itsresult(heldinr 1 1 ontheOpenRISC1000)willbeareturncodefromtheprogram,whichwepass tothee i . xt
ljl _xt .a ei lad r,1, .di 3r10
/ Dlyso * * ea lt /
e i shouldnotreturn,butjustincase,wecanputtheprocessorinatightloopatthisstage,inordertoensureconsistent xt
behavior.
.2 L:
18/41
4/17/12
lj . lnp .o .2 L
5.3. Standard System Call Implementations

Thesimplestwaytoprovideaboardsupportpackageistoimplementthe18systemcallsinnonreentrantfashion.Formanybare metalimplementationsthisissufficient. ThesimplestpossibleBSPsupportsjustoutputtostandardoutputandnoninput.Wegivetheminimalimplementationforsucha system. Whereappropriate,wealsoshowtheOpenRISC1000implementationasapracticalexample. Thissectionduplicatesmuchoftheinformationfoundinthen w i l b documentation[1].Itisincludedhereforcompleteness. elb ic
5.3.1. Error Handling

Manyfunctionssetanerrorcodeonfailureintheglobalvariable,e r o rn. Thereisaslightcomplicationwithn w i ,becausee r o elb r n isnotimplementedasavariable,butamacro(thismakelifeeasierfor reentrantfunctions). Thesolutionforstandardsystemcallimplementations,whichmustreturnanerrorcodeistoundefinethemacroandusethe externalvariableinstead.Attheheadofsuchfunctionsusethefollowing.
#nld <rn.> icue eroh #ne ero udf rn etr itero xen n rn;
Note
ero r n isaglobalvariable,sochangingitwillimmediatelymakeafunctionnonreentrant.
5.3.2. The Global Environment,
evrn nio
Theglobalvariable,e v r n n i o mustpointtoanullterminatedlistofenvironmentvariablenamevaluepairs. Foraminimalimplementationitissufficienttouseanemptylistasfollows.
ca *_n[]={0} hr _ev1 ; ca *evrn=_ev hr *nio _n;
5.3.3. Exit a program,
_xt ei
Exitaprogramwithoutanycleanup. TheOpenRISC1000simplementationmakesuseofthel n p . o opcode.Thisopcodetakesa16bitimmediateoperand.Functionally theoperandhasnoeffectontheprocessoritself.Howeverasimulatorcaninspecttheoperandtoprovideadditionalbehavior externaltothemachine. WhenexecutingonOr1ksim,l n p 1 . o causesatidyexitofthesimulator,usingthevalueinr asthereturncode. 3
vi od _xt(n r) ei it c { rgse it t am(r" =r; eitr n 1 s "3) c amvltl (\lnpt0 ::""(O_XT,""(1) s oaie "t.o\%" K NPEI) r t); wie() hl 1 { } } / _xt( * * ei ) /
19/41
4/17/12
Notetheuseofv l t l .Otherwisethereisastrongpossibilityofanoptimizingcompilerrecognizingthatthisopcodedoes oaie nothing(wearerelyingonasimulationsideeffect)andremovingit. Caution Thenameofthisfunctionisalreadynamespaceclean.Ifanamespacecleanimplementationofthe systemcallshasbeenspecifiedinc n i u e h s (seeSection3.3.1),thenthisfunctionisstillnamed ofgr.ot _xt e i ,not_ e i . _xt
5.3.4. Closing a file,
coe ls
Foranamespacecleanfunction,implement_ l s ,otherwiseimplementc o e coe l s .Thedetailedimplementationwilldependonthe filehandlingfunctionalityavailable. Intheminimalimplementation,thisfunctionalwaysfails,sincethereisonlystandardoutput,whichisnotavalidfiletoclose.This implementationissufficientfortheOpenRISC1000.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _ls (n coe it fl) ie { ero=EAF rn BD; rtr -; eun 1 } / _ls ( * * coe ) / / Awy fis* * las al /
5.3.5. Transfer Control to a New Process,
eev xce
Foranamespacecleanfunction,implement_ x c e e e v ,otherwiseimplemente e v .Theimplementationofthisfunctionalitywillbe xce tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Aminimalimplementation,suchasthatforbaremetalcoding,onlyoffersasingleuserthreadofcontrol.Itisthusimpossibleto startanewprocess,sothisfunctionalwaysfails.
#nld <rn.> icue eroh #ne ero udf rn; etr it ero xen n rn; it n _xce(hr *ae eev ca nm, ca *ag, hr *rv ca *ev hr *n) { ero=EOE; rn NMM rtr -; eun 1 } / _xce( * * eev ) /
/ Awy fis* * las al /
Thechoiceofe r o r n issomewhatarbitrary.Howevernovaluefor"noprocessesavailable"isprovided,andE O E istheclosestin NMM meaningtothis.
5.3.6. Create a new process,
fr ok
Foranamespacecleanfunction,implement_ o k f r ,otherwiseimplementf r .Theimplementationofthisfunctionalitywillbe ok tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Aminimalimplementation,suchasthatforbaremetalcoding,onlyoffersasingleuserthreadofcontrol.Itisthusimpossibleto startanewprocess,sothisfunctionalwaysfails.
#nld <rn.> icue eroh #ne ero udf rn
20/41
4/17/12
etr it ero xen n rn; it n _ok( fr ) { ero=EGI; rn AAN rtr -; eun 1 } / _ok( * * fr ) /
Thechoiceofe r o r n isagainsomewhatarbitrary.Howevernovaluefor"noprocessesavailable"isprovided,andE G I isthe AAN closestinmeaningtothis.
5.3.7. Provide the Status of an Open File,
ftt sa
Foranamespacecleanfunction,implement_ s a ,otherwiseimplementf t t ftt s a .Thedetailedimplementationwilldependonthe filehandlingfunctionalityavailable. Aminimalimplementationshouldassumethatallfilesarecharacterspecialdevicesandpopulatethestatusdatastructure accordingly.
#nld <y/tth icue sssa.> it n _sa (n ftt it fl, ie src sa *t tut tt s) { s-s_oe=SICR t>tmd _FH; rtr 0 eun ; } / _sa ( * * ftt ) /
TheOpenRISC1000implementationrequirestwoversionsofthis,onefortheBSPusingtheconsoleforoutputandoneforthe BSPusingaUARTandsupportingbothstandardinputandstandardoutput. WithoutaUART,theimplementationstillchecksthatthefiledescriptorisoneofthetwothataresupported,andotherwise returnsanerror.
#nld <rn.> icue eroh #nld <y/tth icue sssa.> #nld <nsdh icue uit.> #ne ero udf rn etr it ero xen n rn; it n _sa (n ftt it fl, ie src sa *t tut tt s) { i (SDU_IEO= fl)| (TERFLN = fl) f (TOTFLN = ie | SDR_IEO = ie) { s-s_oe=SICR t>tmd _FH; rtr 0 eun ; } es le { ero=EAF rn BD; rtr -; eun 1 } } / _sa ( * * ftt ) /
TheimplementationwhenaUARTisavailableisalmostidentical,exceptthatS D N F L N isalsoanacceptablefileforwhich TI_IEO statuscanbeprovided.
5.3.8. Get the Current Process ID,
gti epd
Foranamespacecleanfunction,implement_ e p d g t i ,otherwiseimplementg t i .Theimplementationofthisfunctionalitywillbe epd tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Foraminimalimplementation,withnoprocesses,thiscanjustreturnaconstant.Itisperhapssafertoreturnoneratherthanzero, toavoidissuewithsoftwarethatbelievesprocesszeroissomethingspecial.

4/17/12
it n _epd( gti ) { rtr 1 eun ; } / _epd( * * gti ) /
/ Sces* * ucs /
5.3.9. Determine the Nature of a Stream,
iat sty
Foranamespacecleanfunction,implement_ s t y i a t ,otherwiseimplementi a t .Thedetailedimplementationwilldependonthe sty filehandlingfunctionalityavailable. Thisspecificallycheckswhetherastreamisaterminal.Theminimalimplementationonlyhasthesingleoutputstream,whichisto theconsole,soalwaysreturns1.
it n _sty(n iat it { rtr 1 eun ; }
fl) ie
/ _sty( * * iat ) /
Caution Contrarytothestandardl b documentation,thisappliestoanystream,notjustoutputstreams. ic TheOpenRISC1000versiongivesalittlemoredetail,settinge r o r n ifthestreamisnotstandardoutput,standarderroror(forthe UARTversionoftheBSP)standardinput.
#nld <rn.> icue eroh #nld <nsdh icue uit.> #ne ERO udf RN etr it ero xen n rn; it n _sty(n iat it fl) ie { i (fl = SDU_IEO | (ie= SDR_IEO) f (ie = TOTFLN) | fl = TERFLN) { rtr 1 eun ; } es le { ero=EAF rn BD; rtr -; eun 1 } } / _sty( * * iat ) /
TheUARTversionisalmostidentical,butalsosucceedsforstandardinput.
5.3.10. Send a Signal,
kl il
Foranamespacecleanfunction,implement_ i l k l ,otherwiseimplementk l .Theimplementationofthisfunctionalitywillbe il tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Aminimalimplementationhasnoconceptofeithersignals,norofprocessestoreceivethosesignals.Sothisfunctionshould alwaysfailwithanappropriatevalueine r o rn.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _il(n pd kl it i, it sg n i) { ero=ENA; rn IVL
22/41
4/17/12
rtr -; eun 1 } / _il( * * kl ) /

5.3.11. Rename an existing file,
ln ik
Foranamespacecleanfunction,implement_ i k l n ,otherwiseimplementl n .Thedetailedimplementationwilldependonthefile ik handlingfunctionalityavailable. Aminimalimplementationhasnofilesystem,sothisfunctionmustalwaysfail,withanappropriatevaluesetine r o rn.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _ik(hr*l, ln ca od ca *e) hr nw { ero=ELN; rn MIK rtr -; eun 1 } / _ik( * * ln ) /
5.3.12. Set Position in a File,
lek se
Foranamespacecleanfunction,implement_ s e ,otherwiseimplementl e k lek s e .Thedetailedimplementationwilldependonthe filehandlingfunctionalityavailable. Aminimalimplementationhasnofilesystem,sothisfunctioncanreturn0,indicatingthattheonlystream(standardoutput)is positionedatthestartoffile.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _se (n lek it fl, ie it ofe, n fst it wec) n hne { rtr 0 eun ; } / _se ( * * lek ) /
TheOpenRISC1000versionisalittlemoredetailed,returningzeroonlyifthestreamisstandardoutput,standarderroror(for theUARTversionoftheBSP)standardinput.Otherwise1isreturnedandanappropriateerrorcodesetine r o rn.
#nld <rn.> icue eroh #nld <nsdh icue uit.> #ne ero udf rn etr it ero xen n rn; it n _se (n lek it fl, ie it ofe, n fst it wec) n hne { i (SDU_IEO= fl)| (TERFLN = fl) f (TOTFLN = ie | SDR_IEO = ie) { rtr 0 eun ; } es le { ero=EAF rn BD; rtr (og -; eun ln) 1 } } / _se ( * * lek ) /
23/41
4/17/12
TheUARTversionisalmostidentical,butalsosucceedsforstandardinput.
5.3.13. Open a file,
oe pn
Foranamespacecleanfunction,implement_ p n o e ,otherwiseimplemento e .Thedetailedimplementationwilldependonthefile pn handlingfunctionalityavailable. Aminimalimplementationhasnofilesystem,sothisfunctionmustalwaysfail,withanappropriateerrorcodesetine r o rn.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _pn(os ca *ae oe cnt hr nm, it n fas lg, it n md) oe { ero=EOY; rn NSS rtr -; eun 1 } / _pn( * * oe ) /
5.3.14. Read from a File,
ra ed
Foranamespacecleanfunction,implement_ e d r a ,otherwiseimplementr a .Thedetailedimplementationwilldependonthefile ed handlingfunctionalityavailable. Aminimalimplementationhasnofilesystem.Ratherthanfailing,thisfunctionreturns0,indicatingendoffile.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _ed(n ra it fl, ie ca *t, hr pr it ln n e) { rtr 0 eun ; } / _ed( * * ra ) /
/ EF* * O /
TheOpenRISC1000BSPwithoutaUARTisverysimilartotheminimalimplementation,butchecksthatthestreamisstandard inputbeforereturning0.Forallotherstreamsitreturnsanerror.
#nld <rn.> icue eroh #nld <nsdh icue uit.> #ne ero udf rn etr it ero xen n rn; it n _ed(n ra it fl, ie ca *t, hr pr it ln n e) { i (TI_IEO= fl) f SDNFLN = ie { rtr 0 eun ; } es le { ero=EAF rn BD; rtr -; eun 1 } } / _ed( * * ra ) /
/ EF* * O /
TheOpenRISC1000BSPwithaUARTismorecomplex.Inthiscase,ifthestreamisstandardinput,acharacterisread(and optionallyechoed)fromtheUART.
4/17/12
#nld <rn.> icue eroh #nld <nsdh icue uit.> #ne ero udf rn etr it ero xen n rn; it n _ed(n ra it fl, ie ca *u, hr bf it ln n e) { i (TI_IEO= fl) f SDNFLN = ie { it i n ;
fr( =0 i<ln i+ o i ; e; +) { bfi =_atgt (; u[] ur_ec ) #fe UR_UOEH idf ATAT_CO _atpt (u[]; ur_uc bfi) #ni edf / Rtr prilbfe i w gtEL* * eun ata ufr f e e O / i (\'= bfi) f 'n = u[] { rtr i eun ; } } rtr i eun ; } es le { ero=EAF rn BD; rtr -; eun 1 } } / _ed( * * ra ) / / Fle tebfe * * ild h ufr /
Caution TheOr1ksimUARTimplementationonlyreturnsdatawhencarriagereturnishit,ratherthanas eachcharacterbecomesavailable,whichcanleadtosomeunexpectedbehavior.
5.3.15. Allocate more Heap,
sr bk
Foranamespacecleanfunction,implement_ b k s r ,otherwiseimplements r .Thisisonefunctionforwhichthereisnodefault bk minimalimplementation.Itisimportantthatitisimplementedwhereverpossible,sincem l o dependsonit,andinturnmany alc otherfunctionsdependonm l o .Inthisapplicationnote,theOpenRISC1000implementationisusedasanexample. alc Asnotedearlier(Section5.2.2),theheapontheOpenRISC1000growsupfromtheendofloadedprogramspace,andthestack growsdownfromthetopofmemory.Thelinkerdefinesthesymbol_ n ,whichwillbethestartoftheheap,whilsttheCruntime ed initializationplacestheaddressofthelastworkinmemoryintheglobalvariable_ t c . sak Caution
_ n isasymboldefinedbythelinker,notavariable,soitisitsaddressthatmustbeused,notits ed
value. WithinaCprogramthesetwovariablesarereferredtowithouttheirleadingunderscoretheCcompilerprependsallvariable nameswithunderscore.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; #eieSAKBFE 656 dfn TC_UFR 53 / Rsre saksaei bts * * eevd tc pc n ye. /
vi * od _bk(n nye) sr it bts { / Smo dfndb lne mp* * ybl eie y ikr a / etr it ed xen n n; / sato fe mmr (ssmo)* * tr f re eoy a ybl / / Vlestb ct. * * au e y r0S / etr vi *tc; xen od sak / edo fe mmr * * n f re eoy /
25/41
4/17/12

/ Tesaial hl peiu edo teha,wt isiiilzto.* * h ttcly ed rvos n f h ep ih t ntaiain / sai vi *eppr=(od*&n; ttc od ha_t vi )ed / Peiu ed* * rvos n / i (sak-(eppr+nye) >SAKBFE ) f (tc ha_t bts) TC_UFR { vi *ae =ha_t; od bs eppr ha_t eppr + nye; = bts rtr bs; eun ae } es le { ero=EOE; rn NMM rtr (od* -; eun vi ) 1 } } / _bk( * * sr ) /
Theprogramalwaystriestokeepaminimumof65,536(216)bytesspareforthestack. Note Thisimplementationdefines_ b k s r asreturningtypevoid*.Thestandardnewlibdocumentationuses returntypecaddr_t,whichisdefinedinu i t . .Theauthorbelievesthatvoid*isnowthe nsdh recommendedreturntypeforthisfunction. Important

s r hastoreturnthepreviousendoftheheap,whosevalueisheldinthestaticvariable,h a _ t . bk eppr
Theproblemisthatthisnowmakesthefunctionnonreentrant.Ifthefunctionwereinterrupted aftertheassignmenttob s ,butbeforethefollowingassignmenttoh a _ t ,andtheinterrupt ae eppr routineitselfalsocalleds r ,thentheheapwouldbecomecorrupted. bk Forsimplesystems,itwouldbesufficienttoavoidusingthisfunctionininterruptserviceroutines. Howevertheproblemthenknowingwhichfunctionsmightcallm l o andhences r ,soeffectively alc bk alllibraryfunctionsmustbeavoided. Theproblemcannotevenbecompletelyavoidedbyusingreentrantfunctions(seeSection5.4),since justprovidingaperthreaddatastructuredoesnothelp.Theendofheapisasingleglobalvalue.The onlyfullsolutionistosurroundtheupdateoftheglobalvariablebyasemaphore,andfailingthe allocationiftheregionisblocked(wecannotwait,ordeadlockwouldresult).
5.3.16. Status of a File (by Name),
sa tt
Foranamespacecleanfunction,implement_ t t s a ,otherwiseimplements a .Thedetailedimplementationwilldependonthefile tt handlingfunctionalityavailable. Aminimalimplementationshouldassumethatallfilesarecharacterspecialdevicesandpopulatethestatusdatastructure accordingly.
#nld <y/tth icue sssa.> it n _tt(hr sa ca *ie fl, src sa *t tut tt s) { s-s_oe=SICR t>tmd _FH; rtr 0 eun ; } / _tt( * * sa ) /
TheOpenRISC1000implementationtakesastricterviewofthis.Sincenonamedfilesaresupported,thisfunctionalwaysfails.
#nld <rn.> icue eroh #nld <y/tth icue sssa.> #ne ero udf rn etr it ero xen n rn; it n _tt(hr sa ca *ie fl, src sa *t tut tt s)
26/41
4/17/12
{ ero=ECE; rn ACS rtr -; eun 1 } / _tt( * * sa ) /
5.3.17. Provide Process Timing Information,
tms ie
Foranamespacecleanfunction,implement_ i e ,otherwiseimplementt m s tms i e .Theimplementationofthisfunctionalitywillbe tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Aminimalimplementationneednotofferanytiminginformation,soshouldalwaysfailwithanappropriatevalueine r o rn.
#nld <rn.> icue eroh #nld <y/ie.> icue sstmsh #ne ero udf rn etr it ero xen n rn; it n _ie (tutts*u) tms src m bf { ero=ECE; rn ACS rtr -; eun 1 } / _ie ( * * tms ) /
5.3.18. Remove a File's Directory Entry,
uln nik
Foranamespacecleanfunction,implement_ n i k u l n ,otherwiseimplementu l n .Thedetailedimplementationwilldependonthe nik filehandlingfunctionalityavailable. Aminimalimplementationhasnofilesystem,sothisfunctionshouldalwaysfail,settinganappropriatevalueine r o rn.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _nik(hr*ae uln ca nm) { ero=EON; rn NET rtr -; eun 1 } / _nik( * * uln ) /
5.3.19. Wait for a Child Process,
wi at
Foranamespacecleanfunction,implement_ a t w i ,otherwiseimplementw i .Theimplementationofthisfunctionalitywillbe at tightlyboundtoanyoperatinginfrastructureforhandlingmultipleprocesses. Aminimalimplementationhasonlyoneprocess,socanwaitfornootherprocessandshouldalwaysfailwithanappropriatevalue ine r o rn.
#nld <rn.> icue eroh #ne ero udf rn etr it ero xen n rn; it n _at(n *tts wi it sau) { ero=EHL; rn CID rtr -; eun 1 } / _at( * * wi ) /
5.3.20. Write to a File,
wie rt
27/41
4/17/12
Foranamespacecleanfunction,implement_ r t ,otherwiseimplementw i e wie r t .Thedetailedimplementationwilldependonthe filehandlingfunctionalityavailable. Aminimalimplementationonlysupportswritingtostandardoutput.Thecoreoftheimplementationis:
it n _rt (n wie it fl, ie ca *u, hr bf it nye) n bts { iti n ; / Otu caatra a tm * * upt hrce t t ie / fr( =0 i<nye;i+ o i ; bts +) { otye(u[]; ubt bfi) } rtr nye; eun bts } / _rt ( * * wie ) /
Thefunctiono t y e u b t mustusethefunctionalityofthetargetplatformtowriteasinglecharactertostandardoutput.Forexample copyingthecharactertoaseriallinefordisplay.Therecanbenostandardimplementationofthisfunction. FortheOpenRISC1000twoversionsareneededonefortheBSPwithoutaUARTonefortheBSPwithaUART. WithoutaUARTtheimplementationusesthel n p . o opcodewithaparameter,aswiththeimplementationof_ x t e i (Section5.3.3). Inthiscasetheparameter4willcausethesimulatortoprintoutthevalueinregisterr asanASCIIcharacter. 3
#nld "rki-or." icue o1smbadh sai vi ttc od otye(hr c ubt ca ) { rgse ca t am(r" =c eitr hr 1 s "3) ; amvltl (\lnpt0 ::""(O_UC,""(1) s oaie "t.o\%" K NPPT) r t); } / otye( * * ubt ) /
Wealsouseastricterimplementationofthemainw i e r t function,onlypermittingawriteifthestandardoutputorstandarderror streamisspecified.
#nld <rn.> icue eroh #nld <nsdh icue uit.> #ne ero udf rn etr it ero xen n rn; it n _rt (n wie it fl, ie ca *u, hr bf it nye) n bts { iti n ; / W ol hnl sdu adsdr * * e ny ade tot n ter / i (fl ! SDU_IEO & (ie! SDR_IEO) f (ie = TOTFLN) & fl = TERFLN) { ero=EAF rn BD; rtr -; eun 1 } / Otu caatra a tm * * upt hrce t t ie / fr( =0 i<nye;i+ o i ; bts +) { otye(u[]; ubt bfi) } rtr nye; eun bts } / _rt ( * * wie ) /
FortheBSPsupportingaUART,allthatisneededistochangetheo t y e u b t functiontousetheroutinestodrivetheUART
4/17/12
sai vi ttc od otye(hr c ubt ca ) { _atpt () ur_uc c; } / otye( * * ubt ) /
TheUARTsupportroutinesareprovidedseparately,drivingtheinterfaceviaitsmemorymappedregisters.
5.4. Reentrant System Call Implementations

Reentrancyisachievedbyprovidingaglobalreentrancystructure,struct_reentforeachthreadofcontrol,whichholdsthread specificversionsofglobaldatastructures,suchase r o rn. Forafullyreentrantsystem,theBSPshouldimplementthereentrantversionsofthesystemcalls,havingdefined s s a l d r s s a l andadded- R E T A T S S A L _ R V D D ton w i _ f a s c n i u e h s (seeSection3.3.1). ycl_i=ycls DENRN_YCLSPOIE" e l b c l g in o f g r . o t 16ofthesystemcallshavereentrantversions,whichtakethesuffix_ andarepassedanadditionalfirstargument,whichisa r pointertothereentrancystructure,structreentforthethreadofcontrol.Thus_ l s isreplacedby_ l s _ .Thereentrant coe coer functionsare_ l s _ ,_ x c e r _ c t _ ,_ o k r _ s a _ ,_ e p d r _ i k r _ s e _ ,_ p n r _ e d r _ b k r _ t t r c o e r e e v _ , f n l r f r _ , f t t r g t i _ , l n _ , l e k r o e _ , r a _ , s r _ , s a _ , _ i e _ ,_ n i k r _ a t r t m s r u l n _ , w i _ and_ r t _ . wier Twosystemcallsdonotneedreentrantversions,_ i l k l and_ x t e i ,whichareprovidedaswithnonreentrantversions. Formanyofthereentrantfunctions,thebehaviorisalmostidenticaltothatofthenonreentrantversions,beyondensuringthe threadspecificversionofe r o r n inthereentrancystructureisused.Templateversionscanbefoundinthel b / e n directory icret underthen w i directory. elb Therearetwowaysinwhichtheendusercanbesupportedwiththesereentrancyfunctions.Inthefirstitisuptotheuserto manageperthreadreentrancydatastructuresandtocallthereentrantfunctionsexplicitly. Howeverthemorepowerfulsolutionisforthesystemtomanagethereentrancystructureitself.Theendusercancallthestandard functions,andtheywillbemappedtoreentrantcalls,passinginareentrancystructureforthethread. Forthisapproachtobeused,- _ D N M C R E T _ D _ Y A I _ E N _ mustbeaddedton w i _ f a s e l b c l g andtheBSPmustdefinethefunction _ g t e n ,toreturnthereentrancystructureforthecurrentthread. _eret
5.5. BSP Configuration and Make file;

ThereislittledocumentationfortheconfigurationandmakefilesfortheBSPs.Thegeneralguidelineistocopythebaseline versionsofthesefilesinthedefaultplatformlibrary,l b o y ,whichisbasedontheminimalimplementationsdescribedin inss Section5.3. ThisapplicationnoteusestheconfigurationandmakefilesfortheOpenRISC1000toillustratethekeyprinciples. BuildingtheBSPonlyusesautoconfandautoheader,butnotautomake.Sothereisac n i u e i (orc n i u e a )and ofgr.n ofgr.c Mkfl.n a e i e i ,butnoM k f l . m a e i e a .Aftermakinganychangesitisimportanttorunautoconfandautoheadertoregeneratethe cniue o f g r scriptandheaderfiles.Itwillalsoneedaa l c l m togivethelocalmacrodefinitions,whichcanberegeneratedfrom coa.4 themainl b l s a i c u e m usingaclocal.Thecommandneededare: igos cnld.4
alcl- . coa I . athae uoedr atcn uoof
aclocalneedonlyberunthefirsttimethedirectoryiscreated.autoheaderisonlyneedediftheBSPneedsconfiguration parametersfromthesysteminalocalc n i . file. ofgh
5.5.1.
c n i u e i for ofgr.n
the BSP
Thec n i u e i fortheOpenRISC1000iscloselybasedontheversioninl b o y . ofgr.n inss Theinitialdeclarationsjustneedmodifyingtochangethenameofthepackage.
A_RRQ25) CPEE(.9
29/41
4/17/12
A_NTlbr2a020 CII(io3.,..) A_OFGHAE(ofgh CCNI_EDRcni.)
Thereisthencodetoprintawarningiftheuserhasaskedforsharedlibrarysupport(notavailable)andtolocatetheauxiliary toolsforautoconf. ThescriptmakesuseofA _ A O I A _ Y T M C C N N C L S S E todeterminethesystemtypeandsetappropriatevariables.Thisisnowobsolete, andisreplacedbyA _ A O I A _ A G T C C N N C L T R E intheOpenRISC1000version.Theinstalledprogramnamesmaybechanged(for exampleby- p e i ),soweneedA _ R _ R G A andwelocatetheinstallprogram. -rfx CAGPORM
A_AOIA_AGT CCNNCLTRE A_R_RGA CAGPORM A_RGISAL CPO_NTL
TheassumptionismadethatweareusingGNUld,sowedefineH V _ N _ D A E G U L .Thescriptinl b o y doesthisinanobsoleteway, inss whichisfixedintheOpenRISC1000script.
A_EIEHV_N_D 1 [sn GUl] CDFN(AEGUL, , Uig N d)
ThestandardscriptteststhecanonicaltargetnametodetermineifthisisanELFtarget.ForOpenRISC1000thisisalwaysthe case,sothetestcanbereplacedbyasimpledeclaration.
A_EIEHV_L,1 [sn EFfra] CDFN(AEEF , Uig L omt)
Thescriptinl b o y thentestsforthepresenceofvariousfeatures.MostofthosearenotrelevanttoOpenRISC1000socanbe inss leftout.Howeverwedoneedtodeterminewhatthesymbolprefixis.Wecouldjustdefinethisasbeing'_',butinsteadweletthe scriptworkitout,usingthestandardscript'scode.
A_AH_HC(frsmo pei] lb_yblpei,[n CCCECEK[o ybl rfx, icsmo_rfx dl ct>cnts. <\O a ofetc <EF fo( {} o ) EF O lb_yblpei=oe icsmo_rfxnn i A_R_OMN($C-c - cnts. - -|frp"$o">/e/ul) f CTYCMAD[{Cc} S ofetc o ge \fo dvnl]; te hn lb_yblpei=$ icsmo_rfx'' es le i A_R_OMN($C-c - cnts. - -|frp"fo >/e/ul) f CTYCMAD[{Cc} S ofetc o ge _o" dvnl]; te hn lb_yblpei= icsmo_rfx_ f i f i r - cnts*] m f ofet ) i ts $icsmo_rfx! nn;te f et lb_yblpei = oe hn A_EIEUQOE(_YBLPEI,"lb_yblpei" [yblpei] CDFN_NUTD_SMO_RFX $icsmo_rfx, smo rfx) es le A_EIE_SMO_RFX ",[yblpei] CDFN(_YBLPEI, " smo rfx) f i
Thecodetodefinethevarioushosttoolsusedisstandard.Howeveritwillexpecttofindana l c l m fileinthedirectory.This coa.4 canberegenerated,orsimplycopiedfromthel b o y directory.Thevariableh s _ a e i e f a referstostandardmake inss otmkfl_rg scriptdefininghowcompilationiscarriedoutforthevarioussourcefiles. FinallythenewM k f l canbegeneratedinasuitablyinitializedenvironment. aeie
A_OFGFLSMkfl, CCNI_IE(aeie a_ieMkfl .$lbls_odr/ofgm.n cfl=aeie {igostpi}cni-li, sci={rdr rdr$sci} tre={agt agt$tre} wt_utsbi={ihmliudr ihmliudr$wt_utsbi} a_ofgr_rs"{ccniueag}-eal-utlb ccniueag=$a_ofgr_rs -nbemlii" CNI_HL={OFGSEL/i/h OFGSEL$CNI_HL-bns} lbls_odr$lbls_odr igostpi={igostpi} )
30/41
4/17/12
A_UPT COTU
5.5.2.
M k f l . nfor aeiei
the BSP
ThefirstpartofM k f l . n a e i e i isjusttransferringvaluesfromc n i u e o f g r andisusedunchanged.Thefirstpotentialvariationisin multilibhandling.IfyourGCCimplementsmultilibs,thenthatmayneedtobemirroredintheBSPimplementation.Ifnot,then thereisnoneedtosetM L I O U T D andM L I L A tot u andtheselinescanberemoved. UTCEN re TheM k f l . n l b o y includesanoptiontousenewversionsoftheloaderandassembler.Howeverformost a e i e i in i n s s implementations,theplaintoolisallthatisneeded,sosimpletransferoftheconfiguredvaluesissufficient.
C =@C C C@ A =@S S A@ A =@R R A@ L =@D D L@ RNI =@ALB ALB RNI@
Themaintoolswillalreadyhavebeentransformedtotakeaccountofanyprefix(forexampleusingor32elfgccratherthangcc). Howeverthishasnotbeendoneforobjdumpandobjcopy,sothesearetransformedhere. ThisisthepointatwhichwedefinetheBSPstobebuilt.AnycustomflagsforthecompilationcanbeaddedtoC L G here. FAS
CLG =FAS g
WespecifytheCstartupfile(s)andBSP(s)tobebuilt.
CT R0 =ct. r0o BP S =lbr2a io3. BPUR =lbr2ata S_AT io3ur. OTUS =$CT)$BP $BPUR) UPT (R0 (S) (S_AT
Important ItisimportanttodefineO T U S U P T .Thisisthecompletesetofprogramsandlibrariesbeingbuilt.Itis usedinthec e n l a andi s a l n t l targets. ForeachBSPwespecifytheobjectfilesfromwhichitisbuilt.FortheplainOpenRISC1000BSPwehave:
OJ =_xto BS ei. \ coeo ls. \ evrno nio. \ eev. xceo \ fr. oko \ ftto sa. \ gti. epdo \ iat. styo \ kl. ilo \ ln. iko \ leko se. \ oe. pno \ ra. edo \ sr. bko \ sa. tto \ tmso ie. \ ur-um. \ atdmyo uln. niko \ wi. ato \ wieo rt.
FortheBSPwithUARTsupportweusemanyofthesamefiles,butalsohavesomedifferentfiles.
UR_BS=_xto ATOJ ei. coeo ls. evrno nio.
\ \ \
31/41
4/17/12
eev. xceo \ fr. oko \ fttur. \ sa-ato gti. epdo \ iat-ato\ styur. kl. ilo \ ln. iko \ lekur. \ se-ato oe. pno \ ra-ato \ edur. sr. bko \ sa. tto \ tmso ie. \ ur. ato \ uln. niko \ wi. ato \ wieur. rt-ato
Atthispoint,theversionofM k f l . n l b o y specifiesexplicitlytherulesforcompilingobjectfilesfromCandassembler a e i e i in i n s s source.Howeveritisbettertoincorporateastandardsetofrules,usingtheh s _ a e i e f a referencefromtheconfiguration. otmkfl_rg
@otmkfl_rg hs_aeiefa@
ThisisthepointatwhichtospecifythefirstmakeruletocreatetheCruntimestartupfilesandBSPs.
al $CT}$BP $BPUR} l: {R0 {S} {S_AT
Theobjectfiles(includingc t . )willbebuiltautomatically,butweneedrulestobuildthelibrariesfromthem. r0o
$BP:$OJ) (S) (BS $A}$AFAS $ $OJ) {R {RLG} @ (BS $RNI}$ {ALB @ $BPUR) $UR_BS (S_AT: (ATOJ) $A}$AFAS $ $UR_BS {R {RLG} @ (ATOJ) $RNI}$ {ALB @
TheremainderofM k f l . n a e i e i isstandard.Itprovidesrulestocleanthebuilddirectory,toinstallthegeneratedBSP(s)andCstart upfile(s),andrulestoensurec n i u e o f g r andM k f l areregeneratedwhennecessary. aeie Therealsohookstocreate,cleanandinstallanydocumentation(asinfofiles),whichareemptybydefault. Veryoftentheserulesaresufficient,solongasalltheentitiescreatedhavebeenlistedinO T U S U P T .Theyshouldbemodifiedif necessary.
5.6. The Default BSP, l b o y inss

N w i alsobuildsadefaultBSPl b o y . .Thiscanbeusedwiththe- n s s elb inssa l o y flag,andprovidesaconvenientwayoftestingthat
codewilllinkcorrectlyintheabsenceofafullBSP Thecodecanbefoundinthel b o y subdirectoryofthemainl b l s directory. inss igos Forcompleteness,theconfigurationtemplatefile,c n i u e i ,inthisdirectoryshouldbeupdatedforanynewtargetthatis ofgr.n definingnamespacecleanversionsofthefunctions.Eachsuchsystemisselectedusingac s statement.Thenewentryforthe ae OpenRISC1000isasfollows.
o3--) r2** ; ;
Havingupdatedtheconfigurationtemplate,runautoconftoregeneratethec n i u e o f g r scriptfile.
Chapter 6. Configuring, Building and Installing N w i and L b l s elb igos

4/17/12
Havingmadeallthechangesitisnottimetoconfigure,buildandinstallthesystem.Theexamplesinthischapterforthe OpenRISC1000assumeaunifiedsourcetreeins c andabuilddirectory,b d o 3 ,withtheinstallationdirectoryprefix rw l-r2 /p/r2efnw oto3-l-e.
6.1. Configuring N w i and L b l s elb igos

N w i isconfiguredasfollows. elb
c bdo3 d l-r2 ./rwcniue-tre=r2ef-wt-elb-pei=oto3-l-e .sc/ofgr -agto3-l -ihnwi -rfx/p/r2efnw
Note OtheroptionsmaybeneededonthecommandlineifotherGNUtoolsarebeingbuilt.Howeverthese aretheoptionsrelevantton w i elb
6.2. Building N w i and L b l s elb igos

Thesystemisbuiltusingmakefromwithintheb d o 3 directory. l-r2
mk altre-elb ae l-agtnwi mk altre-igos ae l-agtlbls
6.3. Testing N w i and L b l s elb igos

Testingn w i andl b l s requiresfurtherconfiguration.Thedetailsarediscussedlaterinthisapplicationnote(seeChapter8). elb igos Fornowthisstepcanbeskipped.
6.4. Installing N w i and L b l s elb igos

Thesystemisinstalledusingmakefromwithintheb d o 3 directory. l-r2
mk isaltre-elb ae ntl-agtnwi mk isaltre-igos ae ntl-agtlbls
Chapter 7. Modifying the GNU Tool Chain 7.1. Putting N w i in a Custom Location elb
Normallyn w i willbeinstalledinastandardplacewiththerestofthetoolchain.Itsheaderswillgointhei c u e elb n l d directory withinthetargetspecificinstallationdirectory.TheCruntimestartupfile,then w i librariesthemselvesandBSPlibrarieswill elb gointhel b i directorywithinthetargetspecificinstallationdirectory. ThisarrangementensuresthatGCCwillpickuptheheadersandlibrariesautomaticallyandinthecorrectsequence. Howeverifn w i isnottheonlyClibrary,thenthismaybeinconvenient.ForexampletheOpenRISC1000usuallyusesu l b , elb Cic andonlyusesn w i whenregressiontestingtheGNUtoolchain. elb Thesolutionistomovethen w i headersandlibrariestoacustomlocationandmodifyGCCtosearchtherewhenn w i isbeing elb elb used(seeSection7.2). Thisisachievedwithasimplescriptattheendofbuildandinstall.ForexamplewiththeOpenRISC1000thefollowingcommand willsuffice,wheretheprefixusedfortheentiretoolchainbuildisin$ i s a l d r . {ntl_i}
mdr- $isaldr/r2efnwi ki p {ntl_i}o3-l/elb r -f$isaldr/r2efnwi-nld m r {ntl_i}o3-l/elbicue m $isaldr/r2eficue$isaldr/r2efnwi-nld v {ntl_i}o3-l/nld {ntl_i}o3-l/elbicue m $isaldr/r2eflb*a$isaldr/r2efnwi v {ntl_i}o3-l/i/. {ntl_i}o3-l/elb
33/41
4/17/12

m $isaldr/r2eflbct. $isaldr/r2efnwi v {ntl_i}o3-l/i/r0o {ntl_i}o3-l/elb
7.2. Changes to GCC

IngeneralGCCwillworkwithn w i withnochange.AllthatisneededistoincludetheBSPlibraryonthecommandline. elb HoweveritisconvenienttomodifyGCCsothatitpicksuptheBSPautomatically.Thisisparticularlyusefulwhenn w i hasbeen elb installedinacustomlocation(seeSection7.1). ThisisachievedbyaddingmachinespecificoptionstoGCC,andmodifyingtheSpecdefinitionstopickupthen w i librarieswhen elb therelevantoptionisineffect. Alltherelevantfilesarefoundintheg c c n i / a g t c / o f g t r e directoryofGCC.Forthe32bitOpenRISC1000thisisg c c n i / r 2 c/ofgo3.
7.2.1. Adding Machine Specific Options for
Nwi elb
Machinespecificoptionsaredescribedinthet r e . p file.Byconventionmachinespecificoptionsbeginwith'm'. agtot FortheOpenRISC1000wedefinetwooptions,- o 3 - e l b m r 2 n w i and- o 3 - e l b u r fortheplainandUARTenabledversions mr2nwi-at oftheBSPrespectively. Foreachoptionweprovideitsnameononeline,anyparametersonsubsequentlinesandafinallineofdescription.Inthiscasethe onlyparameteristosaythattheparametercanonlyappearinitspositiveform(i.e.- m o o 3 - e l b - n - r 2 n w i isnotpermitted).
mr2nwi o3-elb Tre RjcNgtv agt eeteaie Ln wt teO3 nwi lbay ik ih h R2 elb irr mr2nwi-at o3-elbur Tre RjcNgtv agt eeteaie Ln wt teO3 nwi UR lbay ik ih h R2 elb AT irr
Theseparameterscanthenbeusedelsewhere.
7.2.2. Updating Spec Definitions

GCCcallsanumberofsubsidiaryprograms(thecompileritself,theassembler,thelinkeretc).Theargumentstothesearebuiltup fromtheparametrizedstrings,knownasSpecstrings. Thisapplicationnotecannotdescribethehugerangeofpossibleparameters.Howeverwewilluseoneexampletoshowwhatis possible.Thechangesareallmadetothedefinitionsofthestringsint r e . .InthecaseoftheOpenRISC1000thisiso 3 . . agth r2h Weneedtomakefourchanges. 1. 2. 3. 4. WeneedtotelltheCpreprocessortolookforheadersintherelocatednewliblibrarydirectory. WeneedtotellthelinkertopickupthenewlibCruntimestartupfile. Weneedtotellthelinkerwheretofindthen w i libraries. elb WeneedtotellthelinkertoincludetheBSPlibraryintherightplace.
The Target Specific Installation Directory Allofthesechangeswillrequireknowingthelocationofthetargetspecificinstallationdirectory.UnfortunatelythereisnoSpec parametergivingthis.HoweverwecanconstructitfromtwodefinitionsavailablewhencompilingGCC.S A D R _ X C P E I is TNADEE_RFX thedirectorywheretheGCCexecutableswillbefound.Twodirectoriesupfromthatwillbethemainprefixdirectory.Thetarget machineisspecifiedinD F U T T R E _ A H N .Soconcatenatingthethreestringsyieldsthetargetspecificdirectory. EAL_AGTMCIE
SADR_XCPEI "./."DFUTTRE_AHN TNADEE_RFX /../ EAL_AGTMCIE
Thenewlibheadersareinthesubdirectoryn w i - n l d andtheCruntimestartupandlibrariesinn w i . elbicue elb

4/17/12
Wedefineanewstring,T R E _ R F X A G T P E I basedontheconcatenation.
#eieCN_I(i1 dr)dr "./."dr dfn OCDRdr, i2 i1 /../ i2 #eieTRE_RFXCN_I (TNADEE_RFX DFUTTRE_AHN) dfn AGTPEI OCDR SADR_XCPEI, EAL_AGTMCIE
DefinedconstantscannotbeuseddirectlyinSpecstrings,butwecanmakethemavailablebydefiningthemacroE T A S E S XR_PC.
#eieETASES dfn XR_PC {"agtpei" TRE_RFX} tre_rfx, AGTPEI
TheSpecstringt r e _ r f x a g t p e i isnowavailabletobeusedinotherSpecstrings.
Specifying the header directory. AdditionalargumentstotheCpreprocessoraredefinedinC P S E .Then w i headerdirectoryshouldwesearchedafterany P_PC elb userspecifiedheaderdirectories(from- arguments)andaftertheGCCsystemheaders.Soitisspecifiedusingthe- d r f e I iiatr option.
#ne CPSE udf P_PC #eieCPSE "{o3-elb:iiatr%tre_rfx/elbicue" dfn P_PC %mr2nwi*-drfe (agtpei)nwi-nld}
Thisspecifiesthatanyoptionbeginning- o 3 - e l b m r 2 n w i shouldbereplacedbythestring- d r f e followedbythen w i iiatr elb icde n l u subdirectoryofthet r e _ r f x a g t p e i directory. Sosoforexample,ifwebuildtheOpenRISC1000GCCwith- p e i = o t o 3 - l - e ,wewouldhaveS A D R _ X C P E I -rfx/p/r2efnw TNADEE_RFX setto/ p / r 2 e f n w l b g c o t o 3 - l - e / i / c andD F U T T R E _ A H N settoo 3 - l .TheSpecvariablet r e _ r f x EAL_AGTMCIE r2ef a g t p e i wouldtherefore be/ p / r 2 e f n w l b g c . / . o 3 - l andthustheCpreprocessorwouldhavethefollowingaddedtoitsoptionlist. oto3-l-e/i/c/../r2ef
-drfe /p/r2efnwlbgc./.o3-l/elbicue iiatr oto3-l-e/i/c/../r2efnwi-nld"
Thissubstitutiononlyoccurswhen- o 3 - e l b - o 3 - e l b u r isspecified,whichisexactlythebehaviordesired. m r 2 n w i or m r 2 n w i - a t Note Ifn w i isnotrelocatedasdescribedinSection7.1,thentheheaderswillbeinastandardlocation, elb whichGCCwillsearchanyway,sothereisnoneedtodefineC P S E . P_PC
Specifying the C Start up File

c t . shouldbethefirstobjectfileorlibraryspecifiedtothelinker.ThisiscoveredbyS A T I E S E . r0o TRFL_PC
Thisstringalreadyhasapartialdefinition,tolookforc t . inastandardplace,andtoincludethec t n t o r0o r i i . filefromastandard place.
#ne SATIESE udf TRFL_PC #eieSATIESE "{sae:r0sctntos" dfn TRFL_PC %!hrdct% rii.%}
Solongas- h r d s a e isnotspecifiedasanoption,thislooksforc t . andc t n t o r0o r i i . instandarddirectoriesandsubstitutesthem onthecommandline(thesuffix% indicatesthattheprecedingfileshouldbesearchedforinstandarddirectories,anditsname s expandedtoincludethedirectoryname). Thisneedschangingtoindicatethatif- o 3 - e l b - o 3 - e l b u r isspecified,thenc t . shouldbetakenfromthe m r 2 n w i or m r 2 n w i - a t r0o newlibdirectory.
#eieSATIESE \ dfn TRFL_PC "{sae:{o3-elb:(agtpei)nwi/r0o \ %!hrd%mr2nwi*%tre_rfx/elbct.} %!o3-elb:r0os ctntos" {mr2nwi*ct.%} rii.%}
35/41
4/17/12
Notethatwemustalsoincludethecasethatwhenneitherofthen w i optionsisspecified,thenc t . willbesearchedforin elb r0o standarddirectories. Note Ifn w i isnotrelocatedasdescribedinSection7.1,thenc t . willbeinastandardlocation,which elb r0o GCCwillsearchanyway,sothereisnoneedtomodifyS A T I E S E . TRFL_PC
Specifying the N w i library location elb Weneedtotellthelinkerwheretolookforn w i libraries.Thisisachievedinasimilarmannertothesearchfortheheaders,but elb usingthe- optionandL N _ P C L IKSE.
#ne LN_PC udf IKSE #eieLN_PC"{o3-elb:L(agtpei)nwi} dfn IKSE %mr2nwi*-%tre_rfx/elb"
Note Ifn w i isnotrelocatedasdescribedinSection7.1,thenthen w i librarieswillbeinastandard elb elb locationsearchedbyGCC,sothereisnoneedtospecifyL N _ P C IKSE.
Adding a BSP to the link line. ThelibrariessearchedbyGCCarebydefaultspecifiedtobe- g c - c - g c l c l l c ,withvariantsifprofilingisbeingused.WhenaBSP isused,itmustbesearchedafterl b ,butthatcanleavereferencesunresolved,sol b mustbesearchedagainafterward. ic ic Thesequenceoflibrariestobesearchedbetweenthetwosearchesofl b c isgiveninL B S E .Italreadyhasadefinition. igc I_PC
#eieLBSE "{p%!g-c}{:l_}{g-cp dfn I_PC %!:{p:l}%p-cp%p:l_}
Thisspecifiesavariantlibrarywhenprofilingisinplace.n w i doesnotofferprofilingsupport,butitdoeshaveadebugging elb versionofthelibrary(l b ). ig
#ne LBSE udf I_PC #eieLBSE "{mr2nwi*%!:{p:l}%p-cp%p:l_} \ dfn I_PC %!o3-elb:{p%!g-c}{:l_}{g-cp} %mr2nwi:{g-c-o3 -c {o3-elb%!:l lr2 l} \ %g-g-o3 -g} {:l lr2 l} \ %mr2nwi-at%!:l -o3ur -c {o3-elbur:{g-c lr2at l} \ %g-g-o3ur -g} {:l lr2at l}"
ThisensuresthatthecorrectBSPlibrarywillbeused,accordingthetheoptionselected,andthatif- isspecifiedonthecommand g line,thedebuggingversionoftheClibrary(l b )willbeusedinstead. ig Evenifthen w i isnotrelocatedasdescribedinSection7.1,thenthisSpecchangeisrequiredinordertoensurethecorrect elb librariesarepickedup.
7.3. Changes to the GNU Linker

Ingeneralchangestothelinkerarenotneeded.InsteadtheBSPshouldmakeuseofinformationprovidedbythestandardlinker. Forexampleinthedefinitionofs r (seeSection5.3.15)thecodeusesthe_ n symboldefinedbythelinkerattheendofthe bk ed loadedimagetobethestartoftheheap.
Chapter 8. Testing N w i and L b l s elb igos

N w i andl b l s bothcomewithDejaGnutestinfrastructures,althoughasnotedinSection8.2,thel b l s infrastructureis elb igos igos
nonfunctional.
4/17/12
Thetotalnumberoftestsismodest(24testsinrelease1.18.0).InpracticemuchofthetestingisachievedthroughtheGCCtest suite(40,000+tests)andtheGDBtestsuite(5,000+tests).
8.1. Testing N w i elb

Likealltools,n w i canbetestedwithaDejaGnutestsuite.DejaGnumustbeinstalledonthetestmachine. elb IfyoualreadyhavetestingsetupforothertoolsintheGNUtoolchainonyourtarget,thenyoucanskiptheremainderofthis section,andjusttestn w i fromthebuilddirectorywiththefollowing. elb
c bdo3 d l-r2 mk cektre-elb ae hc-agtnwi
Ifthisisthefirsttimeyouhavetriedtesting,thenyou'llneedtosetupyoursystemappropriately.Oncethisisdone,youwillbe abletotestalltheGNUtoolchaincomponents. Thetestsrequireatargetonwhichtorunthetests.Thiscanbeaphysicalmachine,oritcanbeasimulatorforthetarget architecture. Thedetailsofthetargetareprovidedinanexpectboardconfigurationfile.ThisisreferencedfromtheDejaGnuglobal configurationfile.TheenvironmentvariableD J G U E A N shouldpointtotheglobalconfigurationfile. FortheOpenRISC1000,theglobalconfigurationfileisins t . x andasubdirectory,b a d containso 3 - i . x ,whichisthe ieep ors r2smep boardconfigurationfilefortheOpenRISCsimulatortarget. Thes t . x filehastwofunctions.First,itmustaddtheb a d directorytothelistofboarddirectoriestosearch.Secondly,it ieep ors mustensurethatthetargettripletnameismappedtothenameoftheboardconfigurationfile. Thiss t . x filecanbereusedforcheckingothertargetsintheGNUtoolchain,whichmayhaveadifferenttestsuitehierarchy. ieep Wecannotthereforejustreferencetheb a d directoryrelativetothetestdirectory.Allweknowisthatitwillbeinoneofthe ors directoriesabove,andthereisnootherboardsdirectoryinthehierarchy,soweaddallthepossibledirectories.Notelegant,but effective.
#aesr w lo i tergtpaefrtebaddsrpinfls Mk ue e ok n h ih lc o h or ecito ie i !if eit bad_i]{ f [no xss orsdr stbad_i { e orsdr } } #Cuewyo fnigtebad drcoy rd a f idn h ors ietr lpedbad_i "{olro_i}./ors apn orsdr $to_otdr/.bad" lpedbad_i "{olro_i}./.bad" apn orsdr $to_otdr/../ors lpedbad_i "{olro_i}./../ors apn orsdr $to_otdr/../.bad" lpedbad_i "{olro_i}./../.bad" apn orsdr $to_otdr/../../ors goa tre_it lbl agtls cs "tre_rpe"i { ae $agttilt n {"r2*ef }{ o3--l" sttre_it{"r2sm } e agtls o3-i" } }
Withintheb a d directory,theboardconfigurationfile,o 3 - i . f givesallthedetailsrequiredfortheconfiguration. ors r2smcg Thetoolchainssupportedbythisboardarespecifiedfirst.InthecaseoftheOpenRISC1000,onlyoneissupported.
stbadif tre_ntl {r2ef e_or_no agtisal o3-l}
Wethenneedtoloadsomegenericroutines,andthegenericboardconfiguration.
la_eei_ofg"i" odgnrccni sm la_aebaddsrpin"ai-i" odbs_or_ecito bscsm
Thedefaultsettingsassumethataprogramisexecutedonthetargetbyacommandnamedrun,builtinatargetspecific subdirectoryofthetoplevels m i directory.InthecaseoftheOpenRISC1000thisdirectorywouldbes m o 3 . i/r2

4/17/12
Ataminimum,runtakesasargumentanexecutabletorun,andreturnstheexitcodefromthatexecutableasitsresult. Thes m i directoryisusuallydistributedaspartofGDB.SimulatorsmaybederivedfromCGENspecificationsofthearchitecture,or byintegratingthirdpartysimulators.ThelatteristhecasefortheOpenRISC1000. Thedefaultsettingsforatargetareobtainedusingthes t p s m e u _ i procedure.
stpsmo3 eu_i r2
Theremainderofthefileisusedtoconfigurevariationsonthedefaultsettings.Thisisdoneusingthes t b a d i f procedure. e_or_no TheOpenRISC1000simulatorneedsanadditionalargument,whichisaconfigurationfileforthesimulator.Weknowthatfilewill beinthel b l s targetdirectoryandnameds m c g igos i . f .Wecanusethel o f r f l proceduretosearchupfromthecurrent oko_ie sourcedirectorytolocatethefile.
stcgfl [oko_ie$sci}lbls/r2smcg e f_ie lofrfl {rdr igoso3/i.f] stbadif smotos"a\- $cgfl}" e_or_no i,pin - "f {f_ie\"
Anumberofhelpfulproceduresmakeiteasytolocatepartsofthetoolchainandtheirdefaultarguments.FortheOpenRISC1000 wemakeonechange,whichistospecify- o 3 - e l b m r 2 n w i forthelinkerflags,sothatthen w i BSPwillbeused. elb
poesmlii_pin " rcs_utlbotos " stbadif cmie "fn_c] e_or_no oplr [idgc" stbadif clg "lbls_nld_lg][elbicuefas" e_or_no fas [igosicuefas nwi_nld_lg] stbadif lfas"lbls_ikfas -o3-elb[elbln_lg] e_or_no dlg [igosln_lg] mr2nwi nwi_ikfas" stbadif lsrp " e_or_no dcit "
Notalltargetshavethesamefunctionality,andtheremainingoptionsspecifythoselimitations.Thisisagenericboard specification,sosomeoftheseapplytotestingcomponentsotherthann w i .Thelimitationsspecifiedwillmeanthatsometests, elb whichareinappropriatedonotrun. FortheOpenRISC1000wespecifythatthesimulatorisfast,thatprogramsitrunscannotbepassedarguments,thatitdoesnot supportsignals(fortestingGDB)andthatthemaximumstacksizeis64KB(fortestingGCC).
stbadif so_iuao 0 e_or_no lwsmltr stbadif nag 1 e_or_no ors stbadif gbnsgas 1 e_or_no d,oinl stbadif gcsaksz 656 e_or_no c,tc_ie 53
WecannowsetD J G U E A N topointtotheglobalconfigurationdirectory,changetothebuilddirectoryandrunthemakecommandto checknewlib.
epr DJGU`w`st.x xot EAN=pd/ieep c bdo3 d l-r2 mk cektre-elb ae hc-agtnwi
ThegoodthingisthatthissetupisgenericacrossalltheGNUtoolchain,soalltheothertoolscanbecheckedinthesameway.
8.1.1. Checking Physical Hardware

Thesametechniquecanbeusedtorunthetestsagainstphysicalhardwareratherthanasimulator.Thesetupoftheboard configurationisrathermorecomplicated,withconsiderablevariationfordifferentarrangements. Thedetailisbeyondthescopeofthisapplicationnote,butiswelldescribedinDanKegel'sCrosstoolproject[2].
8.2. Testing L b l s igos

Inprinciple,havingsetupn w i testing,testingl b l s shouldbeassimpleas: elb igos
4/17/12

c bdo3 d l-r2 mk cektre-igos ae hc-agtlbls
Unfortunately,thecurrentn w i release(atthetimeofwriting1.18.0)doesnotimplementtestingforl b l s .Thet s s i e elb igos etut subdirectoryexists,butthecodetoconfigureitiscurrentlycommentedoutinc n i u e i . ofgr.n Itshouldnotbedifficulttobuildtheinfrastructure.Howeverasnotedatthestartofthischapter,testingofn w i andl b l s is elb igos asmuchachievedthroughGCCandGDBtestingasthroughthemodestnumberoftestswithinn w i elb
Chapter 9. Summary Checklist

Thissummarycanbeusedasachecklistwhencreatinganewportofn w i .Theconfigurationandbuildstepsaretypically elb encapsulatedinasimpleshellscript,whichbuilds,testsandinstallstheentireGNUtoolchainaswellasn w i andl b l s elb igos Throughoutthischecklist,thenewtargetarchitectureisreferredtoast r e .Itisrecommendedn w i andl b l s arebuiltas agt elb igos partofaunifiedsourcetreeincludingthen w i distribution(seeSection2.1). elb 1. Editn w i / o f g r . o t e l b c n i u e h s addingentriesforthenewtarget(Section3.3). Decidewhethertoimplementreentrantornonreentrantsystemcallsandwhethertouse namespacecleansystemcallnames(Section3.2). 2. Addan w i machinesubdirectoryforthenewtarget,n w i / i c m c i e t r e (Section4.1). elb elblb/ahn/agt Modifyc n i u e i inn w i / i c m c i e ofgr.n e l b l b / a h n toconfigurethenewtargetsubdirectoryandrun autoconfinn w i / i c m c i e e l b l b / a h n toregeneratethec n i u e o f g r script(Section4.1.1). 3. Implements t m andl n j p ejp o g m inthetargetspecificmachinedirectory,n w i / i c m c i e t r e elblb/ahn/agt (Section4.1.2). CopyandmodifyM k f l . m a e i e a andc n i u e i fromthefr30directoryandrunaclocal,autoconf ofgr.n andautomakeinn w i / i c m c i e t r e toregeneratethec n i u e elblb/ahn/agt o f g r scriptandMakefile template.(Section4.1.3). 4. Modifyn w i headerfiles(Section4.2). elb Addentriesinn w i / i c i c u e i e f . (Section4.2.1) elblb/nld/eepc Addentryininn w i / i c i c u e s t m . (Section4.2.2) elblb/nld/ejpc Addentriesinn w i / i c i c u e s s c n i . (Section4.2.3). elblb/nld/y/ofgh Optionallyaddothercustomheadersinn w i / i c m c i e t r e / a h n (Section4.2.4). elblb/ahn/agtmcie 5. Addal b l s platformdirectory,l b l s / a g t igos i g o s t r e (Section5.1). Modifyl b l s / o f g r . n i g o s c n i u e i toconfiguretheplatformsubdirectoryandrunautoconfinthe l b l s directorytoregeneratethec n i u e igos o f g r script(Section5.1.1). 6. ImplementtheBoardSupportPackage(s)forthetarget(Chapter5). ImplementtheCRuntimestartup,c t . foreachBSP(Section5.2). r0o Implementtheenvironmentglobalvariableand18systemcallfunctionsforeachBSPfollowing theconventionnamespaceandreentrancyconventionsspecifiedinn w i / o f g r . o t elbcniuehs (Section5.3andSection5.4). Createl b l s / a g t M k f l . n i g o s t r e / a e i e i andl b l s / a g t c n i u e a ,basedontheversions igostre/ofgr.c inthel b l s / i n s s i g o s l b o y directoryandrunaclocalandautoconfinl b l s / a g t igostre (Section5.5).
4/17/12
7. 8.
Ifnecessaryupdatel b l s / i n s s c n i u e i toindicatethetargetisusingnamespacecleansystemcalls igoslboy/ofgr.n andrunautoconfinl b l s / i n s s i g o s l b o y (Section5.6). ModifyGCCforn w i (Section7.2). elb Optionallyaddtargetspecificoption(s)tospecifyn w i BSP(s)(Section7.2.1). elb Optionallyspecifythelocationofn w i headers,theBSPCruntimestartupfileandthenewlib elb libraries,iftheyhavebeenmovedfromtheirstandardlocationsand/ornames(Section7.2.2) Specifythel b l s BSPlibrarytobelinked,ensuringm l o andf e arelinkedinifrequired igos alc re (thesectioncalledAddingaBSPtothelinkline.).
9. 10.
Ensurethelinkerscriptsaresuitableforusewithn w i (Section7.3). elb Configureandbuildn w i andl b l s (Chapter6). elb igos Optionallymovethen w i headerdirectory,libraries,CstartupandBSP(s)toacustom elb location(Section7.1). RebuildGCC Rebuildldifanylinkerscriptshavebeenchanged.
11. 12.
Testn w i (Section8.1). elb Installn w i andl b l s (Chapter6). elb igos ReinstallGCC Reinstallldifanylinkerscriptshavebeenchanged.
Youshouldnowhaveaworkingn w i implementationintegratedwithinyourGNUtoolchain. elb
Glossary
ApplicationBinaryInterface(ABI) Thedefinitionofhowregistersareusedduringfunctioncallandreturnforaparticulararchitecture. bigendian Amultibytenumberrepresentation,inwhichthemostsignificantbyteisplacedfirst(i.e.atthelowestaddress)inmemory. Seealsolittleendian BoardSupportPackage(BSP) Thelowlevelinterfacebetweenanoperatingsystemorlibraryandtheunderlyingphysicalplatform. BlockStatedbySymbol(BSS) Universallyknownbyitsacronym(thefullnameisahistoricalrelic),thisreferstoanareaofstorageusedforholdingstatic variablesandinitializedtozero. littleendian Amultibytenumberrepresentation,inwhichtheleastsignificantbyteisplacedfirst(i.e.atthelowestaddress)inmemory. Seealsobigendian reentrant Afunctionwhichisreentrantmaybesafelycalledfromanotherthreadofcontrolwhileaninitialthread'sflowofcontrolis stillwithinthefunction.
4/17/12
Ingeneralafunctionwillbereentrantifitchangesnostaticstate. specialpurposeregister(SPR) Asetofupto21632bitregistersusedtoholdadditionalinformationcontrollingtheoperationoftheOpenRISC1000 supervisionregister AnOpenRISC1000specialpurposeregisterholdinginformationaboutthemostrecenttestresult,whethertheprocessoris insupervisormode,andwhethercertainfunctions(cacheetc)areenabled. Seealsospecialpurposeregister
References
[1]TheRedHatN w i CLibraryAvailableatsourceware.org/newlib/libc.html. elb [2]TheCrosstoolProject,DanKegel.Availableatwww.kegel.com/crosstool.
41/41

Porting Newlib

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Porting Newlib

Загружено:

Авторское право:

Доступные форматы

4/17/12

Howto: Porting newlib

Services and Modeling for Embedded Software Development

Howto: Porting n w i elb

ApplicationNote9.Issue1 July2010 Copyright2010EmbecosmLimited Thedocumententitled"Howto:Portingnewlib"byJeremyBennettofEmbecosmislicensedunderaCreative CommonsAttribution2.0UK:England&WalesLicense.SeetheLegalNoticefordetails.

Howto: Porting newlib

Howto: Porting newlib

1.1. Target Audience

1.3. Further information

1.4. About Embecosm Application Notes

Chapter 2. n w i within the GNU Tool Chain elb

2.1. The Unified Source Tree

Howto: Porting newlib

Theeasiestwaytoachievethisistolinkallthetopleveldirectoriesineachpackageintoasingleunifieddirectory,leavingoutany duplicatedfilesordirectories. Thefollowingbashscriptwilltakeunpackeddistributionsofb n t l GCCandGDBandlinkthemintoasingledirectory,s c . iuis rw

mdrbid ki ul c bid d ul ./r/ofgr -tre=r2ef-eal-agae= -pei=oto3-l .sccniue -agto3-l -nbelnugsc -rfx/p/r2ef c . d .

Note Theinitialmaketarget,a l b i d l - u l isusedtobuildsomeofthebaselinelibrariesandtoolsused throughoutthetoolchain. Similarlythetoolscanbeinstalledusingthefollowing:

Howto: Porting newlib

the Tool Chain Build

N w i canbelinkedintotheunifiedsourcedirectoryinthesamefashion.Allthatisneededistoaddn w i tothecomponent elb elb

Howto: Porting newlib

Whenlookingforexamples,besuretochooseanarchitecturewhichhasbeenimplementedthrough l b l s .TheOpenRISC1000implementationisonesucharchitecture. igos

3.2. The C Namespace and Reentrant Functions

3.3. Adding a new Target to N w i elb

o3) r2 mciedro3 ahn_i=r2 ; ;

Thisspecifiesthatthemachinespecificcodeforthisarchitecturewillbefoundinthedirectoryn w i / i c m c i e o 3 . elblb/ahn/r2 Theplatformdirectoryanddetailsarespecifiedinasubsequentc s switchon$ h s } ae { o t (i.e.thefulltriplet,notjusttheCPUtype). Forthe32bitOpenRISC1000wehavethefollowing.

Howto: Porting newlib

o3--) r2** ssaldrssal ycl_i=ycls nwi_fas"{elbclg}-RETATSSAL_RVDD elbclg=$nwi_fas DENRN_YCLSPOIE" ; ;

o3--) r2** nwi_fas"{elbclg}-MSIGSSALNMS elbclg=$nwi_fas DISN_YCL_AE" ; ;

o3--) r2** nwi_fas"{elbclg}-MSIGSSALNMS elbclg=$nwi_fas DISN_YCL_AE" nwi_fas"{elbclg}-RETATSSAL_RVDD elbclg=$nwi_fas DENRN_YCLSPOIE" ; ;

Chapter 4. Modifying n w i elb

4.1. The Machine Directory

Howto: Porting newlib

4.1.1. Updating the Main Machine Directory Configuration files

Mkfl.m a e i e a isstandardandwillnotneedtobechanged.Havingchangedtheconfigurationtemplate,theconfigurationfile, cniue o f g r ,willneedtoberegenerated.Thisonlyrequiresrunningautoconf

4.1.2. Implementing the

s t m and l n j pfunctions. ejp ogm

s t m andl n j p ejp o g m areapairofCfunctionfacilitatingcrossproceduretransferofcontrol.Typicallytheyareusedtoallow

Duringnormalprocessingifanerrorisfound,thestateheldinb f u canbeusedtoreturncontrolbacktothetoplevelusing lnjp ogm.

Howto: Porting newlib

/ So 0svdfrfa i ftr * * lt ae o lg n uue /

Howto: Porting newlib

overwrittenwhenthemachinestateisrestored.Similarlywemustensurethatr ,whichholdsthefirstargumentpointingtothe 3 restorebuffermustitselfbethelastregisterrestored.

Thereturnaddress,stackpointerandframepointerhavingbeenrestored,thereturnfromthefunction,willplacetheexecution pointimmediatelyaftertheoriginalcalltos t m . ejp Thefollowingisasimpletestprogram,whichcanbeusedtoverifythats t m andl n j p ejp o g m areworkingcorrectly.

Howto: Porting newlib

/ W sol nvratal gthr * * e hud ee culy e ee /

4.1.3. Updating the Target Specific Machine Directory Configuration files

directory).Thesearegenerallyquitestandard,andtheeasiestapproachistocopytheversionsusedforthefr30architecture. Modernpracticeistousethefilenamec n i u e a ratherthanc n i u e i ,buteitherwillbeacceptedbyautoconf. ofgr.c ofgr.n

ForexampletheOpenRISC1000machinedirectory(l b / a h n / r 2 i c m c i e o 3 withinthen w i directory)containsthefollowing. elb

aclocalonlyneedtoberunthefirsttimethedirectoryiscreated,orwhenmovingthedirectorytoanewreleaseofn w i . elb autoconfneedonlyberuneachtimec n i u e i (orc n i u e a )ischanged.automakeneedonlyberuneachtimeM k f l . m ofgr.n ofgr.c aeiea ischanged.

4.2. Changing Headers

4.2.1. IEEE Floating Point

Howto: Porting newlib

One,andonlyoneof_ I E _ I _ N I N _ E E B G E D A and_ I E _ I T E E D A mustbe _EELTL_NIN defined.

Definethismacroifthefloatingpointformatislittleendian. Caution One,andonlyoneof_ I E _ I T E E D A and_ I E _ I _ N I N _EELTL_NIN _ E E B G E D A mustbe defined.

Definethismacroinadditionto_ I E _ I _ N I N _ E E B G E D A ,wherethewordsofamultiwordIEEEfloatingpointnumber areinbigendianorder,butthebyteswithineachwordareinlittleendianorder.

DefinethisifthefloatingpointformatusesthelargestexponentforfinitenumbersratherthanNaNand infinities.SuchaformatcannotrepresentNaNsorinfinities,butit'sF T M X L _ A istwicethestandardIEEEvalue.

#fdfnd_o3_) i eie(_r2_ #eie_IE_I_NIN dfn _EEBGEDA #ni edf

Howto: Porting newlib

Asbefore,thedefinitioniswithinaconditional,soitisonlyusedwhenthetargetistheOpenRISC100032bitarchitecture. Thetypejmp_bufusedwiths t m andl n j p ejp o g m isthendefinedas:

tpdf_BYEjpbf_BE] yee JTP m_u[JLN;

4.2.3. Miscellaneous System Definitions

4.2.4. Overriding Other Header Files

Chapter 5. Modifying l b l s igos

5.1. The Platform Directory

ca _n[]={0} hr _ev1 ; ca evrn=_ev hr *nio _n;