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&[Link].

Table of Contents [Link] [Link] [Link] [Link] [Link] 2.n w i withintheGNUToolChain elb [Link] [Link] w i withintheToolChainBuild elb [Link] w i elb [Link] b l s andn w i igos elb [Link] [Link] w i elb [Link] n i u e h s foraNewTarget [Link] [Link] w i elb [Link] [Link] [Link] t m andl n j p ejp o g m functions. [Link] [Link] [Link] 4.2.2.s t m BufferSize ejp [Link] [Link] [Link] b l s igos [Link] [Link]
[Link]/appnotes/ean9/[Link] 1/41

4/17/12

Howto: Porting newlib

[Link],c t . r0o [Link] 5.2.2.The_ t r FunctionandStackInitialization sat [Link] [Link] [Link] [Link] [Link] [Link] [Link] [Link],e v r n nio [Link],_ x t ei [Link],c o e ls [Link],e e v xce [Link],f r ok [Link],f t t sa [Link],g t i epd [Link],i a t sty [Link],k l il [Link],l n ik [Link],l e k se [Link],o e pn [Link],r a ed [Link],s r bk [Link](byName),s a tt [Link],t m s ie [Link]'sDirectoryEntry,u l n nik [Link],w i at [Link],w i e rt [Link] [Link] 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 [Link],l b o y inss [Link],BuildingandInstallingN w i andL b l s elb igos [Link] w i andL b l s elb igos [Link] w i andL b l s elb igos [Link] w i andL b l s elb igos [Link] w i andL b l s elb igos [Link] [Link] w i inaCustomLocation elb [Link] [Link] w i elb [Link] [Link] [Link] w i andL b l s elb igos [Link] w i elb [Link] [Link] b l s igos [Link] Glossary References

Chapter 1. Introduction
[Link]/appnotes/ean9/[Link] 2/41

4/17/12

Howto: Porting newlib

N w i [Link],allunderfreesoftware elb

licensesthatmakethemeasilyusableonembeddedproducts.

1.1. Target Audience

Portingn w i isnotdifficult,[Link] 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 [Link] elb OpenCores([Link]).

1.3. Further information

Themainsourceofinformationisthen w i website([Link]/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 [Link],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 [Link]'s elb Crosstoolproject[2]. Thisapplicationnotehasdrawnheavilyonthesesources,andtheauthorwouldliketothanktheprovidersofthatoriginal information.

1.4. About Embecosm Application Notes

[Link] 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 [Link] w i isincludedwithinthebuildoftheGNUtoolchain,thenallthe elb elb

librarieswillbebuiltandinstalledinthecorrectplacestobefoundbyGCC

2.1. The Unified Source Tree

Thethreeseparatepackages,b n t l ,[Link] iuis librariesfromb n t l .Itisconvenienttoreassemblethatsourcetreeandmakeasinglebuildofallthetoolstogether. iuis
[Link]/appnotes/ean9/[Link] 3/41

4/17/12

Howto: Porting newlib

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 .

[Link] 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:

[Link]/appnotes/ean9/[Link] 4/41

4/17/12

Howto: Porting newlib

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 [Link] 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 [Link] 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 [Link] globaldatastructure,althoughtheimplementationofsomeofthosesystemcallsmaybecompletelytrivial. Note TheseparationofBSPimplementationintol b l s [Link] igos treecontainsanumberofoldertargetimplementationswheretheBSPisentirelywithinn w i . elb
[Link]/appnotes/ean9/[Link] 5/41

4/17/12

Howto: Porting newlib

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 [Link],but [Link],andtheuser versionstakeprecedence,whichrequiressomecareatlinktime.
N w i allowstheimplementerinsteadtoprovidenamespacecleanversionsofthesefunctionsbyprefixingthemwithan elb underscore.N w i willensurethatthesystemcallsmaptothesenamespacecleanversion([Link] o e elb l s becomesacallto _ l s )unlesstheuserhasreimplementedthatfunctionthemselves. coe

Areentrantfunctionmaybesafelycalledfromasecondthread,[Link] thatmodifiesnostaticorglobalstate,willbereentrant. [Link],reentrancyisnoteasytoprovideautomatically,soreentrant [Link] o e l s ,thereisthereentrantversionc o e r l s _ .Thereentrantversionstakeanextraargument,a reentrancystructure,whichcanbeusedtoensurecorrectbehavior,byprovidingperthreadversionsofglobaldatastructures. Itisworthnotingthatuseoftheglobalerrorvalue,e r o r n [Link] structureincludesanentryforaperthreadvalueofe r o rn. Formanysystems,[Link],orifseparatethreadshave theirownaddressspacethereisnoproblem. Howeverit'sworthrememberingthatevenabaremetalsystemmayencounterissueswithreentrancyifeventhandlersare allowedtousethesystemcalls.
N w i givesconsiderableflexibility,[Link] elb [Link] w i canprovide elb

reentrancyatthelibrarylevel,butmappingthecallsdownthesystemcalls,[Link] 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 [Link] igos systemscallsforeachBSPisplacedinthisdirectory. Updatethec n i u e h s fileinthen w i directorytopointtothemachineandplatformdirectoriesforthe [Link] elb newtarget.
c n i u e h s for [Link]

3.3.1. Extending

a New Target

Thec n i u e h s fileneedschangesintwoplaces,toidentifythearchitecturespecificmachinedirectoryandtheplatform [Link] directoryforBSPimplementations. Themachinenameisspecifiedinac s switchonthe$ h s _ p } ae { o t c u [Link] 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 ([Link],notjusttheCPUtype). Forthe32bitOpenRISC1000wehavethefollowing.

[Link]/appnotes/ean9/[Link]

6/41

4/17/12
o3--) r2** ssaldrssal ycl_i=ycls ; ;

Howto: Porting newlib

Thisisthesimplestoption,specifyingthattheBSPsforallOpenRISC100032bittargetswillimplementnamespacecleansystem calls,andrelyonn w i [Link] elb themachinedirectory,butwithinthel b l s directory.SoforOpenRISC100032bittargetstheBSPimplementationsarein igos lbls/r2 igoso3. TherearefourcommonalternativesforspecifyinghowtheBSPwillbeimplemented. 1. [Link],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: [Link]

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

Forconvenience,stubversionsofthereentrantfunctionsmaybefoundinthel b / e n [Link] icret factthefunctionsusedifthereentrantsystemcallsarenotprovided,andmaptothenonreentrantversions. 2. Theimplementerdefinesnonreentrant,[Link] 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 [Link] elb Theimplementerdefinesnonreentrant,regularversionsofthesystemcalls(i.e.c o e l s ratherthan_ l s ).The coe librarywillbeneitherreentrant,notnamespaceclean,[Link],- 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 [Link],butwilloffer [Link],- 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 [Link] 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 [Link].
[Link]/appnotes/ean9/[Link] 7/41

4/17/12

Howto: Porting newlib

4.1.1. Updating the Main Machine Directory Configuration files

[Link](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 [Link] 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 [Link],theconfigurationfile, cniue o f g r ,[Link]

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 [Link]

resumptionofexecutionataknowngoodpointafteranerror. Bothtakeasfirstargumentabuffer,[Link] 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 [Link] restored,[Link] 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.

[Link]/appnotes/ean9/[Link] 8/41

4/17/12
#nld <ejph icue stm.> .. . i (ro dtce) f err eetd { lnjp(u,1; ogm bf ) } .. .

Howto: Porting newlib

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 ,[Link] restorethemachine's32bitsupervisionregister,whichholdsthebranchflag. [Link] t m header(seeSection4.2.2). ejp IntheApplicationBinaryInterface(ABI)fortheOpenRISC1000,functionargumentsarepassedinregistersr throughr and 3 8 thefunctionreturnaddressisinr . 9 Whendefiningthesetwofunctions,inassembler,[Link] 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,[Link], 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
[Link]/appnotes/ean9/[Link] 9/41

4/17/12

Howto: Porting newlib

[Link] ,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)

[Link]/appnotes/ean9/[Link]

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 ) /

Howto: Porting newlib

/ 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/[Link]

Afteranychangesitwillbenecessarytorunautoconfand/orautomaketogeneratenewversionsofc n i u e o f g r andM k f l . n aeiei. autoconfrequiresanumberofn w i [Link] w i includefile(a i c u e m )by elb elb cnld.4 [Link].

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 )[Link] 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

[Link]/appnotes/ean9/[Link]

11/41

4/17/12

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.

_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

[Link],then thismacroshouldbedefinedtothetypeactuallyusedtopassfloatingpointarguments.
_L_AGS_XOETI_OML FTLRETEPNN_SNRA

DefinethisifthefloatingpointformatusesthelargestexponentforfinitenumbersratherthanNaNand [Link],butit'sF T M X L _ A istwicethestandardIEEEvalue.

_L_ODNRAS FTN_EOML

[Link],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 [Link] 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 [Link] 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

[Link]/appnotes/ean9/[Link]

12/41

4/17/12

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

Varioussystemwideconstantsarespecifiedwithinthen w i directoryinl b / n l d / y / o f g h elb icicuesscni.. Veryoftenthesystemdefaultvaluesarequitesufficient(thisisthecasefortheOpenRISC1000).Howevertargetspecific [Link],socanbeusedto [Link]. Caution AnumberoftheconstantsdefinedheremirrorthoseinGCC'sl m t . [Link] 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 [Link] elb distribution'sm c i e a h n headerdirectory.

Chapter 5. Modifying l b l s igos

Anytargetarchitecturemayneedmultipleimplementations,[Link] 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 [Link] 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

[Link]/appnotes/ean9/[Link]

13/41

4/17/12

Howto: Porting newlib

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. [Link]. Initializethestackandframepointers InvoketheCconstructorinitializationandensuredestructorsarecalledonexit. Carryoutanyfurtherplatformspecificinitialization. CalltheCm i function. an ExitwiththereturncodesuppliediftheCm i functioneverterminates. an Thecodeisinvariablyassembler,althoughitmaycallouttoCfunctions,andisbestillustratedbyexamplefromthe [Link],oneprovidingjust standardoutputtotheconsole,[Link] 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,[Link],theyprintout(usingp i t ) rnf identificationoftheexceptionandtheaddresswhichcausedittothesimulatorconsole,[Link] 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,[Link] .oh 3h(Lm) loi r,3l(Lm) .r 3r,[Link] 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. [Link]
[Link]/appnotes/ean9/[Link] 14/41

4/17/12

Howto: Porting newlib

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

[Link],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 [Link],likeallotherexceptionsititcausesexitand usestheU H N L D E C P I N N A D E _ X E T O macro. Howeverduringstartup,thecodetriesdeliberatelytowriteoutofmemory,todeterminetheendofmemory,whichwilltrigger [Link],whichjustskipstheoffendinginstructionisrequired. Thesolutionistoplacethiscodefirst,[Link],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 )[Link]
[Link]/appnotes/ean9/[Link] 15/41

4/17/12

Howto: Porting newlib

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

[Link](startingwiththe exceptionvectors).Theheapthenstartsimmediatelyafterthis,whilethestackgrowsdownfromtheendofmemory. Thelinkerwillsupplytheaddressforthestartofheap(itisintheglobalvariablee d n ).Howeverwemustfindthestacklocationby [Link],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 [Link] 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

[Link]/appnotes/ean9/[Link]

16/41

4/17/12

Howto: Porting newlib

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 [Link] complexstepswouldberequiredtoenforcedatawritebackandinvalidateanyinstructioncache entry.

5.2.3. Cache Initialization

[Link](intheo 1 s m b a d h r k i - o r . header),thenthey mustbeenabledbysettingtheappropriatebitinthesupervisionregister. Thisisanexampleofmachinespecificinitialization.

/ [Link] 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

[Link] 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

[Link]/appnotes/ean9/[Link]

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,

Howto: Porting newlib

5.2.5. Constructor and Destructor Handling

[Link] 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,[Link] [Link] easiesttosubstituteadummyversionoftheinitializationfunctionintheversionofthelibrarywithoutaUART,ratherthan makingthisfunctionconditional.

ljl .a lnp .o

_ur_nt _atii

5.2.7. Invoking the main program

[Link] 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:

[Link]/appnotes/ean9/[Link]

18/41

4/17/12
lj . lnp .o .2 L

Howto: Porting newlib

5.3. Standard System Call Implementations

[Link] metalimplementationsthisissufficient. [Link] 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 [Link].

#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 [Link] [Link] 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 ) /

[Link]/appnotes/ean9/[Link]

19/41

4/17/12

Howto: Porting newlib

Notetheuseofv l t l .Otherwisethereisastrongpossibilityofanoptimizingcompilerrecognizingthatthisopcodedoes oaie nothing(wearerelyingonasimulationsideeffect)andremovingit. Caution [Link] systemcallshasbeenspecifiedinc n i u e h s (seeSection3.3.1),thenthisfunctionisstillnamed [Link] _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,[Link] 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,[Link] 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 [Link]"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,[Link] startanewprocess,sothisfunctionalwaysfails.

#nld <rn.> icue eroh #ne ero udf rn

[Link]/appnotes/ean9/[Link]

20/41

4/17/12
etr it ero xen n rn; it n _ok( fr ) { ero=EGI; rn AAN rtr -; eun 1 } / _ok( * * fr ) /

Howto: Porting newlib

/ Awy fis* * las al /

Thechoiceofe r o r n [Link]"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,[Link], toavoidissuewithsoftwarethatbelievesprocesszeroissomethingspecial.

[Link]/appnotes/ean9/[Link] 21/41

4/17/12
it n _epd( gti ) { rtr 1 eun ; } / _epd( * * gti ) /

Howto: Porting newlib

/ 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. [Link],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,[Link] 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

[Link]/appnotes/ean9/[Link]

22/41

4/17/12
rtr -; eun 1 } / _il( * * kl ) /

Howto: Porting newlib

/ Awy fis* * las al /

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 ) /

/ Awy fis* * las al /

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 ) /

[Link]/appnotes/ean9/[Link]

23/41

4/17/12

Howto: Porting newlib

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 ) /

/ Awy fis* * las al /

5.3.14. Read from a File,

ra ed

Foranamespacecleanfunction,implement_ e d r a ,otherwiseimplementr a .Thedetailedimplementationwilldependonthefile ed handlingfunctionalityavailable. [Link],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 [Link].

#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 /

[Link],ifthestreamisstandardinput,acharacterisread(and optionallyechoed)fromtheUART.
[Link]/appnotes/ean9/[Link] 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 ;

Howto: Porting newlib

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 [Link],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 /

[Link]/appnotes/ean9/[Link]

25/41

4/17/12

Howto: Porting newlib

/ 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

[Link] 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 [Link] 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 ) /

[Link],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)

[Link]/appnotes/ean9/[Link]

26/41

4/17/12
{ ero=ECE; rn ACS rtr -; eun 1 } / _tt( * * sa ) /

Howto: Porting newlib

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 ) /

/ Awy fis* * las al /

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 ) /

/ Awy fis* * las al /

5.3.20. Write to a File,

wie rt
27/41

[Link]/appnotes/ean9/[Link]

4/17/12

Howto: Porting newlib

Foranamespacecleanfunction,implement_ r t ,otherwiseimplementw i e wie r t .Thedetailedimplementationwilldependonthe filehandlingfunctionalityavailable. [Link]:

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 [Link] [Link]. 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
[Link]/appnotes/ean9/[Link] 28/41

4/17/12
sai vi ttc od otye(hr c ubt ca ) { _atpt () ur_uc c; } / otye( * * ubt ) /

Howto: Porting newlib

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 [Link] b / e n directory icret underthen w i directory. elb [Link] manageperthreadreentrancydatastructuresandtocallthereentrantfunctionsexplicitly. [Link] 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;

[Link] versionsofthesefilesinthedefaultplatformlibrary,l b o y ,whichisbasedontheminimalimplementationsdescribedin inss Section5.3. ThisapplicationnoteusestheconfigurationandmakefilesfortheOpenRISC1000toillustratethekeyprinciples. BuildingtheBSPonlyusesautoconfandautoheader,[Link] 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 [Link] l c l m togivethelocalmacrodefinitions,whichcanberegeneratedfrom coa.4 themainl b l s a i c u e m [Link]: igos cnld.4

alcl- . coa I . athae uoedr atcn uoof

[Link] 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

[Link]/appnotes/ean9/[Link]

29/41

4/17/12
A_NTlbr2a020 CII(io3.,..) A_OFGHAE(ofgh CCNI_EDRcni.)

Howto: Porting newlib

Thereisthencodetoprintawarningiftheuserhasaskedforsharedlibrarysupport(notavailable)andtolocatetheauxiliary toolsforautoconf. ThescriptmakesuseofA _ A O I A _ Y T M C C N N C L S S E [Link], andisreplacedbyA _ A O I A _ A G T C C N N C L T R E [Link](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 [Link]'_',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

[Link] l c l m [Link] coa.4 canberegenerated,orsimplycopiedfromthel b o y [Link] 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} )

[Link]/appnotes/ean9/[Link]

30/41

4/17/12
A_UPT COTU

Howto: Porting newlib

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 [Link] [Link],[Link],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 [Link] 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. [Link] 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 .[Link] 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.

\ \ \

[Link]/appnotes/ean9/[Link]

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

Howto: Porting newlib

Atthispoint,theversionofM k f l . n l b o y specifiesexplicitlytherulesforcompilingobjectfilesfromCandassembler a e i e i in i n s s [Link],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 [Link],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 [Link] s [Link] 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

[Link]/appnotes/ean9/[Link] 32/41

4/17/12

Howto: Porting newlib

Havingmadeallthechangesitisnottimetoconfigure,[Link] 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 [Link] 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 [Link](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 [Link] c u e elb n l d directory [Link],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

[Link]/appnotes/ean9/[Link]

33/41

4/17/12

Howto: Porting newlib

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 [Link]. elb [Link] 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 [Link]'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,[Link] 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. [Link] [Link] r e . .InthecaseoftheOpenRISC1000thisiso 3 . . agth r2h Weneedtomakefourchanges. 1. 2. 3. 4. WeneedtotelltheCpreprocessortolookforheadersintherelocatednewliblibrarydirectory. WeneedtotellthelinkertopickupthenewlibCruntimestartupfile. Weneedtotellthelinkerwheretofindthen w i libraries. elb WeneedtotellthelinkertoincludetheBSPlibraryintherightplace.

The Target Specific Installation Directory [Link] [Link].S A D R _ X C P E I is TNADEE_RFX [Link] 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

[Link]/appnotes/ean9/[Link] 34/41

4/17/12

Howto: Porting newlib

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)[Link]- 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 . [Link] 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.%}

[Link]/appnotes/ean9/[Link]

35/41

4/17/12

Howto: Porting newlib

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 [Link],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 ,[Link] 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

[Link]. 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.
[Link]/appnotes/ean9/[Link] 36/41

4/17/12

Howto: Porting newlib

Thetotalnumberoftestsismodest(24testsinrelease1.18.0).InpracticemuchofthetestingisachievedthroughtheGCCtest suite(40,000+tests)andtheGDBtestsuite(5,000+tests).

8.1. Testing N w i elb

Likealltools,n w i [Link]. elb IfyoualreadyhavetestingsetupforothertoolsintheGNUtoolchainonyourtarget,thenyoucanskiptheremainderofthis section,andjusttestn w i fromthebuilddirectorywiththefollowing. elb

c bdo3 d l-r2 mk cektre-elb ae hc-agtnwi

Ifthisisthefirsttimeyouhavetriedtesting,thenyou'[Link],youwillbe abletotestalltheGNUtoolchaincomponents. [Link],oritcanbeasimulatorforthetarget architecture. [Link] [Link] 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 [Link],itmustaddtheb a d [Link],it ieep ors mustensurethatthetargettripletnameismappedtothenameoftheboardconfigurationfile. Thiss t . x filecanbereusedforcheckingothertargetsintheGNUtoolchain,whichmayhaveadifferenttestsuitehierarchy. ieep Wecannotthereforejustreferencetheb a d [Link] ors directoriesabove,andthereisnootherboardsdirectoryinthehierarchy,[Link],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

[Link]/appnotes/ean9/[Link] 37/41

4/17/12

Howto: Porting newlib

Ataminimum,runtakesasargumentanexecutabletorun,andreturnstheexitcodefromthatexecutableasitsresult. Thes m i [Link],or byintegratingthirdpartysimulators.ThelatteristhecasefortheOpenRISC1000. Thedefaultsettingsforatargetareobtainedusingthes t p s m e u _ i procedure.

stpsmo3 eu_i r2

[Link] t b a d i f procedure. e_or_no TheOpenRISC1000simulatorneedsanadditionalargument,[Link] 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,[Link] 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

[Link] 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
[Link]/appnotes/ean9/[Link] 38/41

4/17/12

Howto: Porting newlib

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 [Link],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).
[Link]/appnotes/ean9/[Link] 39/41

4/17/12

Howto: Porting newlib

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([Link])inmemory. Seealsolittleendian BoardSupportPackage(BSP) Thelowlevelinterfacebetweenanoperatingsystemorlibraryandtheunderlyingphysicalplatform. BlockStatedbySymbol(BSS) Universallyknownbyitsacronym(thefullnameisahistoricalrelic),thisreferstoanareaofstorageusedforholdingstatic variablesandinitializedtozero. littleendian Amultibytenumberrepresentation,inwhichtheleastsignificantbyteisplacedfirst([Link])inmemory. Seealsobigendian reentrant Afunctionwhichisreentrantmaybesafelycalledfromanotherthreadofcontrolwhileaninitialthread'sflowofcontrolis stillwithinthefunction.
[Link]/appnotes/ean9/[Link] 40/41

4/17/12

Howto: Porting newlib

Ingeneralafunctionwillbereentrantifitchangesnostaticstate. specialpurposeregister(SPR) Asetofupto21632bitregistersusedtoholdadditionalinformationcontrollingtheoperationoftheOpenRISC1000 supervisionregister AnOpenRISC1000specialpurposeregisterholdinginformationaboutthemostrecenttestresult,whethertheprocessoris insupervisormode,andwhethercertainfunctions(cacheetc)areenabled. Seealsospecialpurposeregister

References
[1]TheRedHatN w i [Link]/newlib/[Link]. elb [2]TheCrosstoolProject,[Link]/crosstool.

[Link]/appnotes/ean9/[Link]

41/41