OpenWrtDevelopmentGuide TaoJin
[email protected] TaoJin
[email protected] WirelessNetworksLab,CCIS,NEU February13,2012
OverviewofOpenWrtBuildRootEnvironment OpenWrtBuildrootenvir OpenWrtBuildrootenvironmentisa onmentisacollectiono collectionofMakefiles, fMakefiles,patchesand patchesandscripts,whi scripts,which ch generatesthecross-compilationtoolchain,downloadsLinuxkernel,generatesarootfilesystem, manages3rdpartypackages,etc.Thecross-compilationtoolchainusesuClibc.WithOpenWrt Buildroot,developerscancompilethecustomfirmwareimageforsupportedhardware/ architectures.PleaseNOTEthatintheOpenWrtBuildrootsourcetree,thereisnoLinuxkernel oranysourcecodetarballsofthe3 rdpartypackages.Thec partypackages.Thecollectionof ollectionofMakefilesdet Makefilesdeterminesthe erminesthe versionofLinuxkerne versionofLinuxkerneltodownload, ltodownload,andtheve andtheversionofth rsionofthepackaget epackagetarballtodown arballtodownloadand loadand compiledintotheimage.Figure1showsthestructureoftheOpenWrtBuildrootsourcetree.
BuildRoot RootDir
toolchain
tools
bin
build_dir
include
scripts
staging_dir
target
dl
package
feeds
Figure 1. OpenWrt Buildroot Source Tree (The folders in the second lines are generated during compilation). •
tools–containsallthebuildinstructionstofetchtheimagebuildingtools
•
toolchain-containsallthebuildinstructionstofetchthekernelheaders,theClibrary,the
bin-utils,thecompileritselfandthedebugger.Ifyouaddacompletelynewarchitecture, youwouldaddaconfigurati youwouldaddaconfigurationfortheC onfortheClibraryhe libraryhere. re. •
target-buildinstructionforfirmwareimagegeneratingprocessandforthekernelbuilding
process;compileskernel process;compileskernelandfirmwareim andfirmwareimageutiliti ageutilities,buildsf es,buildsfirmwareimage irmwareimage,generat ,generate e ImageGenerator(formercalledImageBuilder) •
–theOpenWrtMakefilesandpatche sandpatchesforallthe sforallthemainpackage mainpackages.TheOpen s.TheOpenWrt Wrt package–theOpenWrtMakefile Makefilehasitsownsyntax Makefilehasitsownsyntax,different ,differentfromthe fromtheconventional conventionalMakefileof MakefileofLinuxmaket Linuxmaketool. ool.
TheOpenWrtMakefiledefinesthemetainformationofthepackage,wheretodownload thepackage,howtocompile,wheretoinstalledthecompiledbinaries,etc.See Howto BuildOpenWrtApplicationPackageformoredetail. •
include -
•
scripts –perlscriptsthatdoestheOpenWrtpackagemanagement
•
dl-Wheretheuser-spacepackagetarballswillbedownloaded
•
build_dir –wherealluser-spacetoolswillbecross-compiled
•
staging_dir –wherethecross-compilationtoolswillbeinstalled
•
feeds –
•
bin –wherethefirmwareimagewillbegeneratedandallthe.ipkpackagefileswillbe
generated Simplyspeaking,oncetheOpenWrtbuildroothasbeenproperlyconfigured,e.g.thetarget platformandarchitectureisspecified,user-spacepackagesselected,etc.,theOpenWrt Buildrootwilldotheimagebuildingthroughthefollowingsteps(oncetheconfigurationisdone): 1. Downloadthecross-compilationtools,kernelheaders,etc.and 2. Setupthestagingdirectory(staging_dir/).Thisiswherethecross-compilationtoolchainwill beinstalled.Ifyouwanttousethesamecross-compilationtoolchainforotherpurposes, suchascompilingthird-partyapplications,youcanfindthecross-compilertoolsinthis directory,andthenusearch-linux-gcctocompileyourapplication. 3. Createthedownloaddirectory(dl/bydefault).Thisiswherethetarballswillbedownloaded. 4. Createthebuilddirectory(build_dir/).Thisiswherealluser-spacetoolswhilebecompiled. 5. Createthetargetdirectory(build_dir/target-arch/rootbydefault)andthetargetfilesystem skeleton.Thisdirectorywillcontainthefinalrootfilesystem. 6. Installtheuser-spacepackagestotherootfilesystemandcompressthewholerootfile systemwithproperformat.Theresultfirmwareimageisgeneratedinbin/
HowtoBuildOpenWRTFirmware(Step-by-StepTutorial)
NOTE:Theroutervendorsmaychangetheirhardwaredesignslightlyeveryonceawhile,evenforthesameproduct. Forexample,BuffaloWZR-HP-G300NHrouterhasthreedifferentmodels,WZR-HP-G300NH,WZR-HP-G301NHand WZR-HP-G300NH2.OpenWRTtrunkcodebaseisfrequentlyupdatedtoaddsupportforthenewlyidentified hardwaremodels.Thisstep-by-stepguideismadebasedonOpenWRTtrunkrevision30368,forBuffaloWZR-HPG300NH2model.
1. CheckoutOpenWrtBuildrootsourcetreefromthesvnserver.Revision30368istheone thatisverifiedtofunctionproperlyonthismodel. $svnco–r30368svn://svn.openwrt.org/openwrt/trunk/
ifyouwanttocheckoutthelatesttrunkcode,run $svncosvn://svn.openwrt.org/openwrt/trunk/ OpenWRThasdifferentbranchesandtrunkcode,butatthemomentofwriting,WZR-HPG300NH2modelisonlysupportedintrunk.Forotherbranches,check https://dev.openwrt.org/wiki/GetSource formoredetail. 2. $cdtrunk 3. Updatepackagelistbyrunning $./scripts/feedsupdate ThiscommandwilldownloadthelatestpackagelistfromOpenWRTserver,andbuildindices locallyin./feeds.In./feeds/packagesareincludedallavailablepackagesandtheir correspondingMakefile's 4. Installallpackageinfotoconfigfileforlatermakeoperation $makepackage/symlinks Thisstepwillinstallsymboliclinksforallpackagesdownloadedinthepreviousstep at./package/feeds/.Ifyoucheckthefilesinthatfolder,youwillfindouttheyareall symboliclinksdirectingto./feeds/packages/.Inthisway,“makemenuconfig”commandcan findallavailablepackagesandshowtheminthemenuconfiginterface.NOTE:withoutthis step,youcannotseeallavailablepackagesinnextstep 5. Customizeyourbuildconfiguration,alsothiswillcheckthedependenciesandavailabilityof requiredtools $makemenuconfig
Figure 2. OpenWrt make menuconfig window
Severalthingsyouhavetospecify:
•
TargetSystem:thechipsetarchitectureofyourtargethardware.WZR-HP-G300NH usesAR71xxserieschipset.See http://wiki.openwrt.org/toh/buffalo/wzr-hpg300nh2fordetailaboutthehardwarespecofthisrouter.
•
TargetProfile:thetargethardwaremodel.Theimagebuildingprocessmaybuild somehardware-dependentconfigfilesintotheimage.E.g.WZR-HP-G300NH2 requiresspecificEthernetswitchdriverspecifiedinthenetworkconfigfile
•
TargetImages:Mosthardwaresneedsquashfsfilesystem.
Figure 2. OpenWrt make menuconfig window
6. Startbuildingprocess $makeworld Ifyouwanttoseedetailedcompilationoutput,add“V=99”attheendofthemake command
HowtoFlashtheImagetoBuffaloWZR-HP-G300NH2 Differentmodelsmayrequiredifferentflashingprocess,whichalldependsonthebootloader implementation.WewilldescribetheflashingprocessforBuffaloWZR-HP-G300NH2.Asforthe flashingmethodsforotherOpenWRTcompatiblemodels,youcanprobablyfindthatinthe OpenWRTofficialwikisiteortheOpenWrtforum(http://openwrt.org ) WZR-HP-G300NH2hasau-bootbootloader,whichimplementstheboot_waitfunction.When therouterispoweredon,beforethebootloaderstartsloadingtheactualfirmwareimage,it waitsfor4second(bydefault)duringwhichthebootloaderhasabasicEthernetnetworkstack andTFTPserverinitializedandlistensforanewfirmwareimagetobepushedviaTFTP. Step1.PreparetheFirmwareImageforWZR-HP-G300NH2
Preparethefirmwareimagefollowingtheaboveinstruction.Thiswouldgenerateasetofbin filesunderbin/ar71xx/.TheimagesthatarecompatiblewithWZR-HP-G300NH2are -
openwrt-ar71xx-generic-wzr-hp-g300nh2-squashfs-sysupgrade.bin
-
openwrt-ar71xx-generic-wzr-hp-g300nh2-squashfs-tftp.bin
ThesecondimageistheonethatshouldbeusedwithTFTPmethod,becausethisimagehasa 32-byteheaderwhichisrequiredbytheu-boottoidentifythehardwaremodel.Withoutproper header,u-bootwillnotaccepttheimage.Forthefirsttimeflashing,i.e.flashingtherouter fromthefactoryfirmwaretoOpenWRT,youhavetousetheTFTPflashingmethod.Theother oneopenwrt-ar71xx-generic-wzr-hp-g300nh2-squashfs-sysupgrade.binisusedtoflashthe router,whentherouterisalreadyrunningOpenWRT. Step2.FlashWZR-HP-G300NH2
1. Disconnectthepoweroftherouter 2. ConnectyourPCtooneoftheLANportsoftherouter 3. setyourPCwithstaticIP192.168.11.xx,b/ctheubootbootloaderuse192.168.11.1staticIP atboottime. 4. setstaticarpentryonthePC. $arp-s192.168.11.102:aa:bb:cc:dd:1a NOTE:theu-bootbootloaderusesthisfixedMACaddressonboottime.Aftertherouteris upandrunning,itwillusedifferentMACaddresses. 5. DisableanyfirewallonyourPC.OnLinux,itis $iptables-F 6. Gotothefolderthatsavesthetftpimagefile,openwrt-ar71xx-generic-wzr-hp-g300nh2squashfs-tftp.bin.Runthefollowingcommand: $tftp192.168.11.1 >binary >rexmt1 >timeout60 >trace >putopenwrt-ar71xx-generic-wzr-hp-g300nh2-squashfs-tftp.bin 7. Powerontherouter 8. waitfor5seconds,therouterwillenterboot_waitstage.Inthetftpconsolefromstep6, youshouldseedatabeingtransferredtotherouterviaTFTP. 9. waitforanother3minsfortheroutertofinishtheflashingprocess. 10. Afterrouterreboots,thePCshouldgetanIPfromtherouter192.168.1.x.Bydefault,there isnorootpasswordsetontherouter,andthesshisdisabled.Youcantelnetto192.168.1.1 tosettherootpassword.Oncerootpasswordisset,thesshisenabledautomatically. NOTE:OnceWZR-HP-G300NH2isflashedproperlyandrunsOpenWRT,wecanupgradethe
firmwarewiththesysupgradetool.SysupgradetoolisauserspacetoolbuiltintotheOpenWrt firmware.Incasetherouterisbricked,youcanusetheTFTPmethodtoreflashtherouterwith goodimage.Seehttp://wiki.openwrt.org/doc/howto/generic.sysupgradefordetailabout sysupgradetool.
HowtoBuildOpenWrtUser-SpacePackage(Step-by-StepTutorial) Similarto.debpackageinDebiansystem,OpenWrtcompresseseachuser-spacepackageas a.ipkfile,whichcontainsthebinaries,configfilesandtheinstructionofinstallingthepackageto therootfilesystem. OpenWrtbuildrootprovidesaSDKpackage,whichisastripped-offbulidroot,whichincludes necessarytoolchainandheaderfilestocross-compileuser-spaceprograms. TherearetwooptionstogetOpenWRTSDK: -
Downloadpre-compiledSDKfromhttp://downloads.openwrt.org/.NotethattheSDK versionshouldbecompatiblewiththeversionofthefirmware.
-
BuildyourownSDKtarballbyselectingtheSDKoptioninmakemenuconfigwindowas showninFigure2.TheSDK.tar.bz2fileisgeneratedinbin/ar71xxdirectory
AfterobtainingtheSDKtarballineitherway,uncompresstheSDKtoanypath,anditisreadyto use. Next,wewillexplainhowtocreateauser-spacehelloworldpackagestepbystep.Inthis example,wedownloadtheprecompiledSDKfromOpenWRTwebsite. OverviewofOpenWRTPackage
Weuse
todenotethetopdirectoryoftheOpenWRTbuildrootsourcetree checkedoutwithsvn.The/packageisthesubdirectorywherealltheOpenWRT packagesaresaved.AtypicalOpenWRTuserspacepackage,e.g.helloworld,lookslikethis. /helloworld/Makefile /helloworld/patches/ TheMakefileisNOTthetermyouarefamiliarwithabouttheGNUMaketool.Instead,the MakefileisanOpenWRTpackageMakefile,withtotallydifferentsyntax.TheOpenWRT MakefiledefinestheinstructionsofbuildingaOpenWRTpackage,includingwheretodownload thesourcecode,howtocompile,whichpathinthefirmwareshouldthecompiledbinarybe installed,etc.AtypicalOpenWRTpackagedirectoryhasNOsourcefolder.Downloadingthe sourcetarballfromproperURLisgenerallythefirststepofbuildingOpenWRTpackage.The URLtodownloadthesourcetarballisdefinedintheOpenWRTMakefile.E.g. PKG_SOURCE:=helloworld.tar.gz PKG_SOURCE_URL:=http://www.example.com/ PKG_MD5SUM:=e06c222e186f7cc013fd272d023710cb TheabovethreelinesdefinedinhelloworldOpenWRTMakefilemeans,download helloworld.tar.gzfromhttp://www.example.com/helloworld.tar.gzTheMD5SUMisusedto
verifytheintegrityofthedownloadedpackage.Generally,thehelloworld.tar.gzwillbe downloadedto/dl/subdirectory.Thetarballisthenuncompressedto /build_dir/helloworld,whichactuallycontainsallthesourcefilesforcompilation. Analternativesimplifiedapproachistostorethesourcefilesinthesamepackagedirectory. /helloworld/Makefile /helloworld/patches/ /helloworld/src/ /helloworld/src/helloworld.c /helloworld/src/Makefile Inthiscase,obviouslythereisnoneedtodownloadanytarballfromtheweb,becauseallthe sourcefilesarepresentinthesameOpenWRTpackagedirectory.NOTEthat /helloworld/src/MakefileisthegenericGNUMakefile. Thepatchessubdirectoryisoptionalandtypicallycontainsbugfixesoroptimizationstoreduce thesizeoftheexecutable. OpenWRTBuildPackageMakefileSyntax
TheOpenWRTBuildPackageMakefiledefinesasetofvariablestoinstructtheOpenWRT BuildrootorSDKtocompilethepackage.HerearethelistofBuildPackagevariablesanddefines. PKG_*definesthevariablesrelatedtopackageinformation,suchaswheretodownloadand versioninformation. •
PKG_NAME-Thenameofthepackage,asseenviamenuconfigandipkg
•
PKG_VERSION-Theupstreamversionnumberthatwe'redownloading
•
PKG_RELEASE-TheversionofthispackageMakefile
•
PKG_BUILD_DIR-Wheretocompilethepackage
•
PKG_SOURCE-Thefilenameoftheoriginalsources
•
PKG_SOURCE_URL-Wheretodownloadthesourcesfrom
•
PKG_MD5SUM-Achecksumtovalidatethedownload
•
PKG_CAT-Howtodecompressthesources(zcat,bzcat,unzip)
•
PKG_BUILD_DEPENDS-Packagesthatneedtobebuiltbeforethispackage,butarenot requiredatruntime.UsesthesamesyntaxasDEPENDSbelow.
Package/*describesthepackage,themenuconfigandipkgentries. •
SECTION-Thetypeofpackage(currentlyunused)
•
CATEGORY-Whichmenuitappearsinmenuconfig
•
TITLE-Ashortdescriptionofthepackage
•
DESCRIPTION-(deprecated)Alongdescriptionofthepackage
•
URL-Wheretofindtheoriginalsoftware
•
MAINTAINER-(optional)Whotocontactconcerningthepackage
•
DEPENDS-(optional)Whichpackagesmustbebuilt/installedbeforethispackage
•
conffiles-(optional)Alistofconfigfilesinstalledbythispackage,onefileperline.
Build/*definessomeinstructionsrelatedtopackagebuilding •
Build/Prepare-(optional)Asetofcommandstounpackandpatchthesources.You maysafelyleavethisundefined.
•
Build/Configure-(optional)Youcanleavethisundefinedifthesourcedoesn'tuse configureorhasanormalconfigscript,otherwiseyoucanputyourowncommands hereoruse"$(callBuild/Configure/Default,)"asabovetopassinadditionalarguments forastandardconfigurescript.
•
Build/Compile-(optional)Howtocompilethesource;inmostcasesyoushouldleave thisundefined.
•
Package/install-Asetofcommandstocopyfilesoutofthecompiledsourceandinto theipkg,whichisrepresentedbythe$(1)directory.
•
Package/preinst-Theactualtextofthescriptwhichistobeexecutedbefore installation.Dontforgettoincludethe#!/bin/sh.Ifyouneedtoabortinstallationhave thescriptreturnfalse.
•
Package/postinst-Theactualtextofthescriptwhichistobeexecutedafterinstallation. Dontforgettoincludethe#!/bin/sh.
•
Package/prerm-Theactualtextofthescriptwhichistobeexecutedbeforeremoval. Dontforgettoincludethe#!/bin/sh.Ifyouneedtoabortremovalhavethescriptreturn false.
•
Package/postrm-Theactualtextofthescriptwhichistobeexecutedafterremoval. Dontforgettoincludethe#!/bin/sh.
Hereisastep-by-stepguideofbuildinghelloworldpackagewithOpenWRTSDK. YoucanfindtheOpenWRTwikipageforSDKhere (http://wiki.openwrt.org/doc/howto/obtain.firmware.sdk)
1. DownloadtheSDKfromhttp://downloads.openwrt.org/backfire/10.03.1rc5/ar71xx/OpenWrt-SDK-ar71xx-for-Linux-i686-gcc-4.3.3+cs_uClibc-0.9.30.1.tar.bz2 NOTE:Forsomereason,theSDKpackagebuiltwithOpenWRTbackfire10.0.1-rc5is buggy,andcannotfunctionproperly.ToobtainaworkingSDK,youcancheckoutthe trunkcodeofbuildrootsourcetreefrom svncosvn://svn.openwrt.org/openwrt/trunk/ andbuildtheSDKfollowingthestep-by-stepguideintheprevioussection.
2. Uncompressthepackagetoopenwrt-sdk $tarxvjfOpenWrt-SDK-ar71xx-for-Linux-i686-gcc-4.3.3+cs_uClibc-0.9.30.1.tar.bz2 $mvOpenWrt-SDK-ar71xx-for-Linux-i686-gcc-4.3.3+cs_uClibc-0.9.30.1openwrt-sdk
3. CreateafoldernamedhelloworldintheSDK/packagesubdirectory $mkdiropenwrt-sdk/package/helloworld
4. Edithelloworld.candsaveitinopenwrt-sdk/package/helloworld/src #include intmain() { printf(“helloworld\n” return0; } 5. EditGNUMakefileandsaveitinopenwrt-sdk/package/helloworld/src CC=gcc FLAG=-Wall helloworld: $(CC)$(FLAG)helloworld.c-ohelloworld 6. EdittheOpenWRTBuildPackageMakefileandsaveitinopenwrt-sdk/package/helloworld/ HereisasamplehelloworldMakefile ############################################## #OpenWrtMakefileforhelloworldprogram # # #Mostofthevariablesusedherearedefinedin #theincludedirectivesbelow.Wejustneedto #specifyabasicdescriptionofthepackage, #wheretobuildourprogram,wheretofind #thesourcefiles,andwheretoinstallthe #compiledprogramontherouter. # #Beverycarefulofspacinginthisfile. #Indentsshouldbetabs,notspaces,and #thereshouldbenotrailingwhitespacein #linesthatarenotcommented. # ############################################## include$(TOPDIR)/rules.mk #Nameandreleasenumberofthispackage PKG_NAME:=helloworld PKG_RELEASE:=1 #Thisspecifiesthedirectorywherewe'regoingtobuildtheprogram.
#Therootbuilddirectory,$(BUILD_DIR),isbydefaultthebuild_mipsel #directoryinyourOpenWrtSDKdirectory PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME) include$(INCLUDE_DIR)/package.mk #Specifypackageinformationforthisprogram. #Thevariablesdefinedhereshouldbeselfexplanatory. #IfyouarerunningKamikaze,deletetheDESCRIPTION #variablebelowanduncommenttheKamikazedefine #directiveforthedescriptionbelow definePackage/helloworld SECTION:=utils CATEGORY:=Utilities TITLE:=Helloworld Program endef
#UncommentportionbelowforKamikazeanddeleteDESCRIPTIONvariableabove definePackage/helloworld/description a sample OpenWRT helloworld program endef #Specifywhatneedstobedonetoprepareforbuildingthepackage. #Inourcase,weneedtocopythesourcefilestothebuilddirectory. #ThisisNOTthedefault.ThedefaultusesthePKG_SOURCE_URLandthe #PKG_SOURCEwhichisnotdefinedheretodownloadthesourcefromtheweb. #Inordertojustbuildasimpleprogramthatwehavejustwritten,itis #mucheasiertodoitthisway. defineBuild/Prepare mkdir -p $(PKG_BUILD_DIR) $(CP) ./src/* $(PKG_BUILD_DIR)/ #Sincewehostthesourcefolderinthesame OpenWRTpackagefolder,wecopyeverythinginsourcefolderto$(PKG_BUILD_DIR)/ endef #Specifywhereandhowtoinstalltheprogram.Sinceweonlyhaveonefile, #thehelloworldexecutable,installitbycopyingittothe/bindirectoryon #therouter.The$(1)variablerepresentstherootdirectoryontherouterrunning #OpenWrt.The$(INSTALL_DIR)variablecontainsacommandtopreparetheinstall #directoryifitdoesnotalreadyexist.Likewise$(INSTALL_BIN)containsthe #commandtocopythebinaryfilefromitscurrentlocation(inourcasethebuild #directory)totheinstalldirectory. definePackage/helloworld/install $(INSTALL_DIR) $(1)/usr/sbin #copythehelloworldbinaryto/usr/binofOpenWRT $(INSTALL_BIN)$(PKG_BUILD_DIR)/helloworld$(1)/usr/sbin/ endef
#Thislineexecutesthenecessarycommandstocompileourprogram. #Theabovedefinedirectivesspecifyalltheinformationneeded,butthis #linecallsBuildPackagewhichinturnactuallyusesthisinformationto #buildapackage. $(eval$(callBuildPackage,helloworld)) 5. Buildhelloworldpackage $makepackage/hellworld-compileV=99
Thiscross-compilesthehelloworldandgenerateshelloworld.ipkinopenwrtsdk/bin/ar71xx 6. Copythehelloworld.ipktothetmpdirectoryonrouter $scphelloworld.ipkroot@:/tmp/
7. Installhelloworld $opkginstall/tmp/helloworld.ipk
8. Verifyhelloworldisproperlyinstalledunder/usr/bin $whichhelloworld /usr/bin/helloworld
9. Tryhelloworld $helloworld helloworld $
Formoredetailedinstruction,pleasereferto http://wiki.openwrt.org/doc/howto/obtain.firmware.sdkand http://wiki.openwrt.org/doc/devel/packages
References: 1. OpenWrtBuildroot–TechnicalReference( http://wiki.openwrt.org/doc/techref/buildroot) 2. OpenWrtBuildrootDocumentation(http://downloads.openwrt.org/docs/buildrootdocumentation.html) 3. WZR-HP-G301NHHardwareInfo( http://wiki.openwrt.org/toh/buffalo/wzr-hpg300h?s%5B%5D=table&s%5B%5D=hardware ) 4. CreatingOpenWrtPackages(http://wiki.openwrt.org/doc/devel/packages ) 5. UsingOpenWrtSDK(http://wiki.openwrt.org/doc/howto/obtain.firmware.sdk)