Académique Documents
Professionnel Documents
Culture Documents
JeremyBennett Embecosm
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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 2/41
4/17/12
licensesthatmakethemeasilyusableonembeddedproducts.
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).
librarieswillbebuiltandinstalledinthecorrectplacestobefoundbyGCC
4/17/12
#/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 .
Eachtoolcanbebuiltwithitsownspecifictargetwithinthatbuilddirectory
c bid d ul mk albidalbntl algsall algcalgb ae l-ul l-iuis l-a l-d l-c l-d c . d .
4/17/12
2.1.1. Incorporating
N w i within 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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 5/41
4/17/12
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.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:
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
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.
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
Noteinparticularthats s a l d r y c l _ i isnotdefinedinthiscase.
4/17/12
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
atcn uoof
SinceM k f l . m a e i e a hasnotbeenchangedthereisnoneedtorunautomake
#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 } .. .
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
/ 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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 9/41
4/17/12
.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
#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)
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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 ) /
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
Definethismacroifthefloatingpointformatisbigendian. Caution
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
11/41
4/17/12
_IE_ITEEDA _EELTL_NIN
_IE_YE_ITEEDA _EEBTSLTL_NIN
Definethisifdoubleprecisionfloatingpointisrepresentedusingthe32bitIEEErepresentation.
_LA_R FOTAG
Floatingpointargumentsareusuallypromotedtodoublewhenpassedasarguments.Ifthisisnotthecase,then thismacroshouldbedefinedtothetypeactuallyusedtopassfloatingpointarguments.
_L_AGS_XOETI_OML FTLRETEPNN_SNRA
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.
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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
12/41
4/17/12
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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
13/41
4/17/12
Aftermakingthischangethec n i u e o f g r fileshouldberegeneratedbyrunningautoconf.
#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
/ 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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 14/41
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
.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
Noeffortismadetosavetheregister(r 4 2 )thatisusedinthehandler.Thestartupcodetestingforendofmemorymustnotuse
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 15/41
4/17/12
thisregister. Thenextexception,datapagefault,atlocation0x300,likeallotherexceptionsisunhandled.
5.2.2. The
_ t r Function sat
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 .et scin tx .lbl_tr goa sat .ye _tr,fnto tp sat@ucin _tr: sat
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
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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
16/41
4/17/12
lad .d lad .d
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 /
/ 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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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,
ljl .a lnp .o
ii nt
/ Dlyso * * ea lt /
ljl .a lnp .o
_ur_nt _atii
lo .r lo .r ljl .a lo .r
/ Dlyso * * ea lt /
/ Dlyso * * ea lt /
e i shouldnotreturn,butjustincase,wecanputtheprocessorinatightloopatthisstage,inordertoensureconsistent xt
behavior.
.2 L:
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
18/41
4/17/12
lj . lnp .o .2 L
#nld <rn.> icue eroh #ne ero udf rn etr itero xen n rn;
Note
ero r n isaglobalvariable,sochangingitwillimmediatelymakeafunctionnonreentrant.
evrn nio
_xt ei
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 ) /
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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
coe ls
#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 /
eev xce
#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 ) /
fr ok
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
20/41
4/17/12
etr it ero xen n rn; it n _ok( fr ) { ero=EGI; rn AAN rtr -; eun 1 } / _ok( * * fr ) /
ftt sa
#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 ) /
#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 ) /
gti epd
4/17/12
it n _epd( gti ) { rtr 1 eun ; } / _epd( * * gti ) /
/ Sces* * ucs /
iat sty
fl) ie
/ _sty( * * iat ) /
#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.
kl il
#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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
22/41
4/17/12
rtr -; eun 1 } / _il( * * kl ) /
ln ik
#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 ) /
lek se
#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 ) /
#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 ) /
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
23/41
4/17/12
TheUARTversionisalmostidentical,butalsosucceedsforstandardinput.
oe pn
#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 ) /
ra ed
#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.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 24/41
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 /
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
#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 /
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
25/41
4/17/12
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).
sa tt
#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)
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
26/41
4/17/12
{ ero=ECE; rn ACS rtr -; eun 1 } / _tt( * * sa ) /
tms ie
#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 ) /
uln nik
#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 ) /
wi at
#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 ) /
wie rt
27/41
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
4/17/12
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 ) /
#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 ) /
#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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 28/41
4/17/12
sai vi ttc od otye(hr c ubt ca ) { _atpt () ur_uc c; } / otye( * * ubt ) /
TheUARTsupportroutinesareprovidedseparately,drivingtheinterfaceviaitsmemorymappedregisters.
5.5.1.
c n i u e i for ofgr.n
the BSP
A_RRQ25) CPEE(.9
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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
ThestandardscriptteststhecanonicaltargetnametodetermineifthisisanELFtarget.ForOpenRISC1000thisisalwaysthe case,sothetestcanbereplacedbyasimpledeclaration.
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} )
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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.
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
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.
\ \ \
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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
@otmkfl_rg hs_aeiefa@
ThisisthepointatwhichtospecifythefirstmakeruletocreatetheCruntimestartupfilesandBSPs.
$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.
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.
4/17/12
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
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
33/41
4/17/12
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.
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
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.
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
#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.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
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.
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
#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}"
nonfunctional.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 36/41
4/17/12
Thetotalnumberoftestsismodest(24testsinrelease1.18.0).InpracticemuchofthetestingisachievedthroughtheGCCtest suite(40,000+tests)andtheGDBtestsuite(5,000+tests).
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" } }
Wethenneedtoloadsomegenericroutines,andthegenericboardconfiguration.
4/17/12
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\"
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 "
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
ThegoodthingisthatthissetupisgenericacrossalltheGNUtoolchain,soalltheothertoolscanbecheckedinthesameway.
4/17/12
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
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.
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.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html 40/41
4/17/12
References
[1]TheRedHatN w i CLibraryAvailableatsourceware.org/newlib/libc.html. elb [2]TheCrosstoolProject,DanKegel.Availableatwww.kegel.com/crosstool.
www.embecosm.com/appnotes/ean9/ean9howtonewlib1.0.html
41/41