Building4.2BSDUNIX†SystemswithConfig June,1983 SamuelJ.Leffler ComputerSystemsResearchGroup DepartmentofElectricalEngineeringandComputerScience UniversityofCalifornia,Berkeley Berkeley,California94720 (415)642-7780 ABSTRACT Thisdocumentdescribestheuseofconfig(8)toconfigureandcreate bootable4.2BSDsystemimages.Itdiscussesthestructureofsystemconfigurationfilesandhowtoconfiguresystemswithnon-standardhardwareconfigura-tions.Sectionsdescribingthepreferredwaytoaddnewcodetothesystemand howthesystem’sautoconfigurationprocessoperatesareincluded.Anappendix containsasummaryoftherulesusedbythesystemincalculatingthesizeofsystemdatastructures,andalsoindicatessomeofthestandardsystemsizelimitations(andhowtochangethem). †UNIXisaTrademarkofBellLaboratories. July27,1983 BuildingSystemsWithConfig Introduction 1.INTRODUCTION Configisatoolusedinbuilding4.2BSDsystemimages.Ittakesafiledescribingasystem’s tunableparametersandhardwaresupport,andgeneratesacollectionoffileswhicharethenused tobuildacopyofUNIXappropriatetothatconfiguration.Configsimplifiessystemmaintenance byisolatingsystemdependenciesinasingle,easytounderstand,file. Thisdocumentdescribesthecontentandformatofsystemconfigurationfilesandtherules whichmustbefollowedwhencreatingthesefiles.Exampleconfigurationfilesareconstructedand discussed. Latersectionssuggestguidelinestobeusedinmodifyingsystemsourceandexplainsomeof theinnerworkingsoftheautoconfigurationprocess.AppendixDsummarizestherulesusedin calculatingthemostimportantsystemdatastructuresandindicatessomeinherentsystemdata structuresizelimitations(andhowtogoaboutmodifyingthem). July27,1983 BuildingSystemsWithConfig ConfigurationFileContents 2.CONFIGURATIONFILECONTENTS Asystemconfigurationmustincludeatleastthefollowingpiecesofinformation: •machinetype •cputype •systemidentification •timezone •maximumnumberofusers •locationoftherootfilesystem •availablehardware Configallowsmultiplesystemimagestobegeneratedfromasingleconfigurationdescription.Eachsystemimageisconfiguredforidenticalhardware,butmayhavedifferentlocationsfor therootfilesystemand,possibly,othersystemdevices. 0.1.Machinetype ThemachinetypeindicatesifthesystemisgoingtooperateonaDECVAX-11computer, orsomeothermachineonwhich4.2BSDoperates.Themachinetypeisusedtolocatecertain datafileswhicharemachinespecificand,also,toselectrulesusedinconstructingtheresultant configurationfiles. 0.2.Cputype Thecputypeindicateswhich,ofpossiblymany,cpu’sthesystemistooperateon.For example,ifthesystemisbeingconfiguredforaVAX-11,itcouldberunningonaVAX-11/780, VAX-11/750,orVAX-11/730.Specifyingmorethanonecputypeimpliesthesystemshouldbe configuredtorunonallthecpu’sspecified.Forsometypesofmachinesthisisnotpossibleand configwillprintadiagnosticindicatingsuch. 0.3.Systemidentification Thesystemidentificationisamonikerattachedtothesystem,andoftenthemachineon whichthesystemistorun.Forexample,atBerkeleywehavemachinesnamedErnie(Co-VAX), Kim(No-VAX),andsoon.ThesystemidentifierselectedisusedtocreateaglobalC‘‘#define’’ whichmaybeusedtoisolatesystemdependentpiecesofcodeinthekernel.Forexample,Ernie’s Variandriverusedtobespecialcasedbecauseitsinterruptvectorswerewiredtogether.Thecode inthedriverwhichunderstoodhowtohandlethisnon-standardhardwareconfigurationwascon-ditionallycompiledinonlyifthesystemwasforErnie. Thesystemidentifier‘‘GENERIC’’isgiventoasystemwhichwillrunonanycpuofaparticularmachinetype;itshouldnototherwisebeusedforasystemidentifier. 0.4.Timezone Thetimezoneinwhichthesystemistorunisusedtodefinetheinformationreturnedbythe gettimeofday(2)systemcall.ThisvalueisspecifiedasthenumberofhourseastorwestofGMT. NegativenumbersindicateavalueeastofGMT.Thetimezonespecificationmayalsoindicatethe typeofdaylightsavingstimerulestobeapplied. 0.5.Maximumnumberofusers Thesystemallocatesmanysystemdatastructuresatboottimebasedonthemaximum numberofusersthesystemwillsupport.Thisnumberisnormallybetween8and40,depending onthehardwareandexpectedjobmix.Therulesusedtocalculatesystemdatastructuresare discussedinAppendixD. July27,1983 BuildingSystemsWithConfig-3-ConfigurationFileContents 0.6.Rootfilesystemlocation Whenthesystembootsitmustknowthelocationoftherootofthefilesystemtree.This locationandthepart(s)ofthedisk(s)tobeusedforpagingandswappingmustbespecifiedin ordertocreateacompleteconfigurationdescription.Configusesmanyrulestocalculatedefault locationsfortheseitems;thesearedescribedinAppendixB. Whenagenericsystemisconfigured,therootfilesystemisleftundefineduntilthesystemis booted.Inthiscase,therootfilesystemneednotbespecified,onlythatthesystemisageneric system. 0.7.Hardwaredevices Whenthesystembootsitgoesthroughanautoconfigurationphase.Duringthisperiod,the systemsearchesforallthosehardwaredeviceswhichthesystembuilderhasindicatedmightbe present.Thisprobingsequencerequirescertainpiecesofinformationsuchasregisteraddresses, businterconnects,etc.Asystem’shardwaremaybeconfiguredinaveryflexiblemannerorbe specifiedwithoutanyflexibilitywhatsoever.Mostpeopledonotconfigurehardwaredevicesinto thesystemunlesstheyarecurrentlypresentonthemachine,expectthemtobepresentinthe nearfuture,oraresimplyguardingagainstahardwarefailuresomewhereelseatthesite(itis oftenwisetoconfigureinextradisksincaseanemergencyrequiresmovingoneoffamachine whichhashardwareproblems). Thespecificationofhardwaredevicesusuallyoccupiesthemajorityoftheconfigurationfile. Assuch,alargeportionofthisdocumentwillbespentunderstandingit.Section6.3containsa descriptionoftheautoconfigurationprocess,asitappliestothoseplanningtowrite,ormodify existing,devicedrivers. 0.8.Optionalitems Otherthanthemandatorypiecesofinformationdescribedabove,itisalsopossibleto includevariousoptionalsystemfacilities.Forexample,4.2BSDcanbeconfiguredtosupport binarycompatibilityforprogramsbuiltunder4.1BSD.Also,optionalsupportisprovidedfordisk quotasandtracingtheperformanceofthevirtualmemorysubsystem.Anyoptionalfacilitiesto beconfiguredintothesystemarespecifiedintheconfigurationfile.Theresultantfilesgenerated byconfigwillautomaticallyincludethenecessarypiecesofthesystem. July27,1983 BuildingSystemsWithConfig SystemBuildingProcess 3.SYSTEMBUILDINGPROCESS Inthissectionweconsiderthestepsnecessarytobuildabootablesystemimage.We assumethesystemsourceislocatedinthe‘‘/sys’’directoryandthat,initially,thesystemisbeing configuredfromsourcecode. Undernormalcircumstancesthereare5stepsinbuildingasystem. 1)Createaconfigurationfileforthesystem. 2)Makeadirectoryforthesystemtobeconstructedin. 3)Runconfigontheconfigurationfiletogeneratethefilesrequiredtocompileandloadthesystemimage. 4)Constructthesourcecodeinterdependencyrulesfortheconfiguredsystem. 5)Compileandloadthesystemwithmake(1). Steps1and2areusuallydoneonlyonce.Whenasystemconfigurationchangesitusually sufficestojustrunconfigonthemodifiedconfigurationfile,rebuildthesourcecodedependencies, andremakethesystem.Sometimes,however,configurationdependenciesmaynotbenoticedin whichcaseitisnecessarytocleanouttherelocatableobjectfilessavedinthesystem’sdirectory; thiswillbediscussedlater. 3.1.Creatingaconfigurationfile Configurationfilesnormallyresideinthedirectory‘‘/sys/conf’’.Aconfigurationfileismost easilyconstructedbycopyinganexistingconfigurationfileandmodifyingit.The4.2BSDdistributioncontainsanumberofconfigurationfilesformachinesatBerkeley,onemaybesuitableor, inworstcase,youmaytakethegenericconfigurationfileandeditthat. Theconfigurationfilemusthavethesamenameasthedirectoryinwhichtheconfiguredsystemistobebuilt.Further,configassumesthisdirectoryislocatedintheparentdirectoryofthe directoryinwhichitisrun.Forexample,thegenericsystemhasaconfigurationfile ‘‘/sys/conf/GENERIC’’andanaccompanyingdirectorynamed‘‘/sys/GENERIC’’.Ingeneralitis unwisetomoveyourconfigurationdirectoriesoutof‘‘/sys’’asmostofthesystemcodeandthe filescreatedbyconfigusepathnamesoftheform‘‘../’’.Ifyouarerunningoutofspaceonthefile systemwheretheconfigurationdirectoriesarelocatedthereisamechanismforsharingrelocatable objectfilesbetweensystems;thisisdescribedlater. Whenbuildingyourconfigurationfile,besuretoincludetheitemsdescribedinsection2. Inparticular,themachinetype,cputype,timezone,systemidentifier,maximumusers,androot devicemustbespecified.Thespecificationofthehardwarepresentmaytakeabitofwork;particularlyifyourhardwareisconfiguredatnon-standardplaces(e.g.deviceregisterslocatedat funnyplacesordevicesnotsupportedbythesystem).Section4ofthisdocumentgivesadetailed descriptionoftheconfigurationfilesyntax,section5explainssomesampleconfigurationfiles,and section6discusseshowtoaddnewdevicestothesystem.Ifthedevicestobeconfiguredarenot alreadydescribedinoneoftheexistingconfigurationfilesyoushouldcheckthemanualpagesin section4oftheUNIXProgrammersManual.Foreachsupporteddevice,themanualpagesynopsisentrygivesasampleconfigurationline. Oncetheconfigurationfileiscomplete,runitthroughconfigandlookforanyerrors.Never tryanduseasystemwhichconfighascomplainedabout;theresultsareunpredictable.Forthe mostpart,config’serrordiagnosticsareselfexplanatory.Itmaybethecasethatthelinenumbersgivenwiththeerrormessagesareoffbyone. Asuccessfulrunofconfigonyourconfigurationfilewillgenerateanumberoffilesinthe configurationdirectory.Thesefilesare: •Afiletobeusedbymake(1)incompilingandloadingthesystem. July27,1983 BuildingSystemsWithConfig-5-SystemBuildingProcess •Onefileforeachpossiblesystemimageforyourmachinewhichdescribeswhereswapping,the rootfilesystem,andothermiscellaneoussystemdevicesarelocated. •Acollectionofheaderfiles,oneperpossibledevicethesystemsupports,whichdefinethehardwareconfigured. •Afilecontainingthei/oconfigurationtablesusedbythesystemduringitsautoconfiguration phase. •Anassemblylanguagefileofinterruptvectorswhichconnectinterruptsfromyourmachine’s externalbusestothemainsystempathforhandlinginterrupts. Unlessyouhavereasontodoubtconfig,orarecurioushowthesystem’sautoconfiguration schemeworks,youshouldneverhavetolookatanyofthesefiles. 3.2.Constructingsourcecodedependencies Whenconfigisdonegeneratingthefilesneededtocompileandlinkyoursystemitwillterminatewithamessageoftheform‘‘Don’tforgettorunmakedepend’’.Thisisareminderthat youshouldchangeovertotheconfigurationdirectoryforthesystemjustconfiguredandtype ‘‘makedepend’’tobuildtherulesusedbymaketorecognizeinterdependenciesinthesystem sourcecode.Thiswillinsurethatanychangestoapieceofthesystemsourcecodewillresultin thepropermodulesbeingrecompiledthenexttimemakeisrun. Thisstepisparticularlyimportantifyoursitemakeschangestothesystemincludefiles. Therulesgeneratedspecifywhichsourcecodefilesaredependentonwhichincludefiles.Without theserules,makewillnotrecognizewhenitmustrebuildmodulesduetoasystemheaderfile beingmodified.Notethatdependencyrulescreatedbythissteponlyreflectdirectlyincluded files.Thatis,iffile‘‘a’’includesanotherfile‘‘b’’,whichincludesyetanother,say‘‘c’’,andthen ‘‘c’’ismodified,makewillnotrecognizethat‘‘a’’shouldberecompiled.Itisbesttokeepinclude filedependenciesonlyoneleveldeep. 3.3.Buildingthesystem Themakefileconstructedbyconfigshouldallowanewsystemtoberebuiltbysimplytyping ‘‘makeimage-name’’.Forexample,ifyouhavenamedyourbootablesystemimage‘‘vmunix’’, then‘‘makevmunix’’willgenerateabootableimagenamed‘‘vmunix’’.Alternatesystemimage namesareusedwhentherootfilesystemlocationand/orswappingconfigurationisdoneinmore thanoneway.Themakefilewhichconfigcreateshasentrypointsforeachsystemimagedefined intheconfigurationfile.Thus,ifyouhaveconfigured‘‘vmunix’’tobeasystemwiththerootfile systemonan‘‘hp’’deviceand‘‘hkvmunix’’tobeasystemwiththerootfilesystemonan‘‘hk’’ device,then‘‘makevmunixhkvmunix’’willgeneratebinaryimagesforeach. Notethatthenameofabootableimageisdifferentfromthesystemidentifier.Allbootable imagesareconfiguredforthesamesystem;onlytheinformationabouttherootfilesystemand pagingdevicesdiffer.(Thisisdescribedinmoredetailinsection4.) Thelaststepinthesystembuildingprocessistorearrangecertaincommonlyusedsymbols inthesymboltableofthesystemimage;themakefilegeneratedbyconfigdoesthisautomatically foryou.Thisisadvantageousforprogramssuchasps(1)andvmstat(1),whichrunmuchfaster whenthesymbolstheyneedarelocatedatthefrontofthesymboltable.Rememberalsothat manyprogramsexpectthecurrentlyexecutingsystemtobenamed‘‘/vmunix’’.Ifyouinstalla newsystemandnameitsomethingotherthan‘‘/vmunix’’,manyprogramsarelikelytogive strangeresults. 3.4.Sharingobjectmodules Ifyouhavemanysystemswhichareallbuiltonasinglemachinethereareatleasttwo approachestosavingtimeinbuildingsystemimages.Thebestwayistohaveasinglesystem imagewhichisrunonallmachines.Thisisattractivesinceitminimizesdiskspaceusedandtime requiredtorebuildsystemsaftermakingchanges.However,itisoftenthecasethatoneormore systemswillrequireaseparatelyconfiguredsystemimage.Thismaybeduetolimitedmemory July27,1983 BuildingSystemsWithConfig-6-SystemBuildingProcess (buildingasystemwithmanyunuseddevicedriverscanbeexpensive),ortoconfigurationrequirements(onemachinemaybeadevelopmentmachinewherediskquotasarenotneeded,while anotherisaproductionmachinewheretheyare),etc.Inthesecasesitispossibleforcommon systemstosharerelocatableobjectmoduleswhicharenotconfigurationdependent;mostofthe moduleinthedirectory‘‘/sys/sys’’areofthissort. Toshareobjectmodules,agenericsystemshouldbebuilt.Then,foreachsystemconfigure thesystemasbefore,butbeforerecompilingandlinkingthesystem,type‘‘makelinks’’.Thiswill causethesystemtobesearchedforsourcemoduleswhicharesafetosharebetweensystemsand generatesymboliclinksinthecurrentdirectorytotheappropriateobjectmodulesinthedirectory ‘‘../GENERIC’’.Ashellscript,‘‘makelinks’’isgeneratedwiththisrequestandmaybecheckedfor correctness.Thefile‘‘/sys/conf/defines’’containsalistofsymbolswhichwebelievearesafeto ignorewhencheckingthesourcecodeformoduleswhichmaybeshared.Notethatthislist includesthedefinitionsusedtoconditionallycompileinthevirtualmemorytracingfacilities,and thetracepointsupportusedonlyrarely(evenatBerkeley).Itmaybenecessarytomodifythis filetoreflectlocalneeds.Notefurther,thatasdescribedpreviously,interdependencieswhichare notdirectlyvisibleinthesourcecodearenotcaught.Thismeansthatifyouplaceper-system dependenciesinanincludefile,theywillnotberecognizedandthesharedcodemaybeselectedin anunexpectedfashion. 3.5.Buildingprofiledsystems Itissimpletoconfigureasystemwhichwillautomaticallycollectprofilinginformationasit operates.Theprofilingdatamaybecollectedwithkgmon(8)andprocessedwithgprof(1)to obtaininformationregardingthesystem’soperation.Profiledsystemsmaintainhistogramsofthe programcounteraswellasthenumberofinvocationsofeachroutine.Thegprof(1)commandwill alsogenerateadynamiccallgraphoftheexecutingsystemandpropagatetimespentineachroutinealongthearcsofthecallgraph(consultthegprofdocumentationforelaboration).Theprogramcountersamplingcanbedrivenbythesystemclock,orifyouhaveanalternaterealtime clockthiscanbeused.Thelatterishighlyrecommendedasuseofthesystemclockwillresultin statisticalanomaliesandtimespentintheclockroutinewillnotbeaccuratelyaccountedfor. Toconfigureaprofiledsystem,the−−poptionshouldbesuppliedtoconfig.Aprofiledsystemisabout5-10%largerinitstextspaceduetothecallstocountthesubroutineinvocations. Whenthesystemexecutes,theprofilingdataisstoredinabufferwhichis1.2timesthesizeofthe textspace.Theoverheadforrunningaprofiledsystemvaries;undernormalloadweseeanywhere from5-25%ofthesystemtimespentintheprofilingcode. Notethatsystemsconfiguredforprofilingshouldnotbesharedasdescribedaboveunlessall theothersharedsystemsarealsotobeprofiled. July27,1983 BuildingSystemsWithConfig ConfigurationFileSyntax 4.CONFIGURATIONFILESYNTAX Inthissectionweconsiderthespecificrulesusedinwritingaconfigurationfile.Acomplete grammarfortheinputlanguagecanbefoundinAppendixAandmaybeofuseifyoushould haveproblemswithsyntaxerrors. Aconfigurationfileisbrokenupintothreelogicalpieces: •configurationparametersglobaltoallsystemimagesspecifiedintheconfigurationfile, •parametersspecifictoeachsystemimagetobegenerated,and •devicespecifications. 4.1.Globalconfigurationparameters Theglobalconfigurationparametersarethetypeofmachine,cputypes,options,timezone, systemidentifier,andmaximumusers.Eachisspecifiedwithaseparatelineintheconfiguration file. machinetype Thesystemistorunonthemachinetypespecified.Nomorethanonemachinetypecan appearintheconfigurationfile.Legalvaluesarevaxandsun. cpu‘‘type’’ Thissystemistorunonthecputypespecified.Morethanonecputypespecificationcan appearinaconfigurationfile.LegaltypesforavaxmachineareVAX780,VAX750,and VAX730. optionsoptionlist Compilethelistedoptionalcodeintothesystem.Optionsinthislistareseparatedbycommas.Possibleoptionsarelistedatthetopofthegenericmakefile.Alineoftheform ‘‘optionsFUNNY,HAHA’’generatesglobal‘‘#define’’s−DFUNNY−DHAHAintheresultantmakefile.Anoptionmaybegivenavaluebyfollowingitsnamewith‘‘=’’,thenthe valueenclosedin(double)quotes.Noneofthestandardoptionsusesuchavalue.Thefollowingoptionsarecurrentlyinuse:COMPAT(includecodeforcompatiblitywith4.1BSD binaries),INET(Internetcommunicationprotocols),PUP(supportforaPUPrawinterface),andQUOTA(enablediskquotas).Thereareadditionaloptionswhichareassociated withcertainperipheraldevices;thosearelistedintheSynopsissectionofthemanualpage forthedevice. timezonenumber[dst[number]] Specifiesthetimezoneyouarein.Thisismeasuredinthenumberofhoursyourtimezoneis westofGMT.ESTis5hourswestofGMT,PSTis8.Negativenumbersindicatehours eastofGMT.Ifyouspecifydst,thesystemwilloperateunderdaylightsavingstime.An optionalintegerorfloatingpointnumbermaybeincludedtospecifyaparticulardaylight savingtimecorrectionalgorithm;thedefaultvalueis1,indicatingtheUnitedStates.Other valuesare:2(Australianstyle),3(WesternEuropean),4(MiddleEuropean),and5(Eastern European).Seegettimeofday(2)andctime(3)formoreinformation. identname Thissystemistobeknownasname.ThisisusuallyacutenamelikeERNIE(shortfor ErnieCo-Vax)orVAXWELL(forVaxwellSmart). maxusersnumber Themaximumexpectednumberofsimultaneouslyactiveuseronthissystemisnumber. Thisnumberisusedtosizeseveralsystemdatastructures. 4.2.Systemimageparameters Multiplebootableimagesmaybespecifiedinasingleconfigurationfile.Thesystemswill havethesameglobalconfigurationparametersanddevices,butthelocationoftherootfilesystem July27,1983 BuildingSystemsWithConfig-8-ConfigurationFileSyntax andothersystemspecificdevicesmaybedifferent.Asystemimageisspecifiedwitha‘‘config’’ line: configsysnameconfig-clauses Thesysnamefieldisthenamegiventotheloadedsystemimage;almosteveryonenamestheir standardsystemimage‘‘vmunix’’.Theconfigurationclausesareoneormorespecificationsindicatingwheretherootfilesystemislocated,howmanypagingdevicesthereareandwherethey go.Thedeviceusedbythesystemtoprocessargumentlistsduringexecve(2)callsmayalsobe specified,thoughinpracticethisisalmostalwaysselectedbyconfigusingoneofitsrulesfor selectingdefaultlocationsforsystemdevices. Aconfigurationclauseisoneofthefollowing root[on]root-device swap[on]swap-device[andswap-device] dumps[on]dump-device args[on]arg-device (the‘‘on’’isoptional.)Multipleconfigurationclausesareseparatedbywhitespace;configallows specificationstobecontinuedacrossmultiplelinesbybeginningthecontinuationlinewithatab character.The‘‘root’’clausespecifieswheretherootfilesystemislocated,the‘‘swap’’clause indicatesswappingandpagingarea(s),the‘‘dumps’’clausecanbeusedtoforcesystemdumpsto betakenonaparticulardevice,andthe‘‘args’’clausecanbeusedtospecifythatargumentlist processingforexecveshouldbedoneonaparticulardisk. Thedevicenamessuppliedintheclausesmaybefullyspecifiedasadevice,unit,andfile systempartition;orunderspecifiedinwhichcaseconfigwillusebuiltinrulestoselectdefaultunit numbersandfilesystempartitions.Thedefaultingrulesareabitcomplicatedastheyaredependentontheoverallsystemconfiguration.Forexample,theswapareaneednotbespecifiedatall iftherootdeviceisspecified;inthiscasetheswapareaisplacedinthe‘‘b’’partitionofthesame diskwheretherootfilesystemislocated.AppendixBcontainsacompletelistofthedefaulting rulesusedinselectingsystemconfigurationdevices. Thedevicenamesaretranslatedtotheappropriatemajorandminordevicenumbersona per-machinebasis.Afile,‘‘/sys/conf/devices.machine’’(where‘‘machine’’isthemachinetype specifiedintheconfigurationfile),isusedtomapadevicenametoitsmajorblockdevicenumber. Theminordevicenumberiscalculatedusingthestandarddiskpartitioningrules:onunit0,partition‘‘a’’isminordevice0,partition‘‘b’’isminordevice1,andsoon;forunitsotherthan0,add8 timestheunitnumbertogettheminordevice. Ifthedefaultmappingofdevicenametomajor/minordevicenumberisincorrectforyour configuration,itcanbereplacedbyanexplicitspecificationofthemajor/minordevice.Thisis donebysubstituting majorxminory wherethedevicenamewouldnormallybefound.Forexample, configvmunixrootonmajor99minor1 Normally,theareasconfiguredforswapspacearesizedbythesystematboottime.Ifa non-standardpartitionsizeistobeusedforoneormoreswapareas,thiscanalsobespecified. Todothis,thedevicenamespecifiedforaswapareashouldhavea‘‘size’’specificationappended. Forexample, configvmunixrootonhp0swaponhp0bsize1200 wouldforceswappingtobedoneinpartition‘‘b’’of‘‘hp0’’andtheswappartitionsizewouldbe setto1200sectors.Aswapareasizedlargerthantheassociateddiskpartitionistrimmedtothe partitionsize. Tocreateagenericconfiguration,onlytheclause‘‘swapgeneric’’shouldbespecified;any extraclauseswillcauseanerror. July27,1983 BuildingSystemsWithConfig-9-ConfigurationFileSyntax 4.3.Devicespecifications Eachdeviceattachedtoamachinemustbespecifiedtoconfigsothatthesystemgenerated willknowtoprobeforitduringtheautoconfigurationprocesscarriedoutatboottime.Hardware specifiedintheconfigurationneednotactuallybepresentonthemachinewherethegenerated systemistoberun.Onlythehardwareactuallyfoundatboottimewillbeusedbythesystem. Thespecificationofhardwaredevicesintheconfigurationfileparallelstheinterconnection hierarchyofthemachinetobeconfigured.OntheVAX,thismeansaconfigurationfilemustindicatewhatMASSBUSandUNIBUSadaptersarepresent,andtowhichnexitheymightbeconnected*.Similarly,devicesandcontrollersmustbeindicatedaspossiblybeingconnectedtoone ormoreadapters.Adevicedescriptionmayprovideacompletedefinitionofthepossibleconfigurationparametersoritmayleavecertainparametersundefinedandmakethesystemprobeforall thepossiblevalues.Thelatterallowsasingledeviceconfigurationlisttomatchmanypossible physicalconfigurations.Forexample,adiskmaybeindicatedaspresentatUNIBUSadapter0, oratanyUNIBUSadapterwhichthesystemlocatesatboottime.Thelatterscheme,termed wildcarding,allowsmoreflexibilityinthephysicalconfigurationofasystem;ifadiskmustbe movedaroundforsomereason,thesystemwillstilllocateitatthealternatelocation. Adevicespecificationtakesoneofthefollowingforms: masterdevice-namedevice-info controllerdevice-namedevice-info[interrupt-spec] devicedevice-namedevice-infointerrupt-spec diskdevice-namedevice-info tapedevice-namedevice-info A‘‘master’’isaMASSBUStapecontroller;a‘‘controller’’isadiskcontroller,aUNIBUStapecontroller,aMASSBUSadapter,oraUNIBUSadapter.A‘‘device’’isanautonomousdevicewhich connectsdirectlytoaUNIBUSadapter(asopposedtosomethinglikeadiskwhichconnects throughadiskcontroller).‘‘Disk’’and‘‘tape’’identifydiskdrivesandtapedrivesconnectedtoa ‘‘controller’’or‘‘master’’. Thedevice-nameisoneofthestandarddevicenames,asindicatedinsection4oftheUNIX ProgrammersManual,concatenatedwiththelogicalunitnumbertobeassignedthedevice(the logicalunitnumbermaybedifferentthanthephysicalunitnumberindicatedonthefrontofsomethinglikeadisk;thelogicalunitnumberisusedtorefertotheUNIXdevice,notthephysicalunit number).Forexample,‘‘hp0’’islogicalunit0ofaMASSBUSstoragedevice,eventhoughit mightbephysicalunit3onMASSBUSadapter1. Thedevice-infoclausespecifieshowthehardwareisconnectedintheinterconnectionhierar-chy.OntheVAX,UNIBUSandMASSBUSadaptersareconnectedtotheinternalsystembus throughanexus.Thus,oneofthefollowingspecificationswouldbeused: controllermba0atnexusx controlleruba0atnexusx Totieacontrollertoaspecificnexus,‘‘x’’wouldbesuppliedasthenumberofthatnexus;otherwise‘‘x’’maybespecifiedas‘‘?’’,inwhichcasethesystemwillprobeallnexipresentlookingfor thespecifiedcontroller. TheremaininginterconnectionsontheVAXare: •acontrollermaybeconnectedtoanothercontroller(e.g.adiskcontrollerattachedtoa UNIBUSadapter), •amasterisalwaysattachedtoacontroller(aMASSBUSadaptor), •atapeisalwaysattachedtoamaster(forMASSBUStapedrives), •adiskisalwaysattachedtoacontroller,and *WhileVAX-11/750’sandVAX-11/730donotactuallyhavenexi,thesystemtreatsthemashaving simulatednexitosimplifydeviceconfiguration. July27,1983 BuildingSystemsWithConfig-10-ConfigurationFileSyntax •devicesarealwaysattachedtocontrollers(e.g.UNIBUScontrollersattachedtoUNIBUS adapters). Thefollowinglinesgiveanexampleofeachoftheseinterconnections: controllerhk0atuba0... masterht0atmba0... tapetu0atht0... diskrk1athk0... devicedz0atuba0... Anypieceofhardwarewhichmaybeconnectedtoaspecificcontrollermayalsobewildcarded acrossmultiplecontrollers. Thefinalpieceofinformationneededbythesystemtoconfiguredevicesissomeindication ofwhereorhowadevicewillinterrupt.Fortapesanddisks,simplyspecifyingtheslaveordrive numberissufficienttolocatethecontrolstatusregisterforthedevice.Forcontrollers,thecontrol statusregistermustbegivenexplicitly,aswellhowmanyinterruptvectorsareusedandthe namesoftheroutinestowhichtheyshouldbebound.Thustheexamplelinesgivenabovemight becompletedas: controllerhk0atuba0csr0177440vectorrkintr masterht0atmba0drive0 tapetu0atht0slave0 diskrk1athk0drive1 devicedz0atuba0csr0160100vectordzrintdzxint Certaindevicedriversrequireextrainformationpassedtothematboottimetotailortheir operationtotheactualhardwarepresent.Thelineprinterdriver,forexample,needstoknowhow manycolumnsarepresentoneachnon-standardlineprinter(i.e.alineprinterwithotherthan80 columns).Thedriversfortheterminalmultiplexorsneedtoknowwhichlinesareattachedto modemlinessothatnoonewillbeallowedtousethemunlessaconnectionispresent.Forthis reason,onelastparametermaybespecifiedtoadevice,aflagsfield.Ithasthesyntax flagsnumber andisusuallyplacedafterthecsrspecification.Thenumberispasseddirectlytotheassociated driver.Themanualpagesinsection4shouldbeconsultedtodeterminehoweachdriverusesthis value(ifatall).Communicationsinterfacedriverscommonlyusetheflagstoindicatewhether modemcontrolsignalsareinuse. TheexactsyntaxforeachspecificdeviceisgivenintheSynopsissectionofitsmanualpage insection4ofthemanual. 4.4.Pseudo-devices Anumberofdriversandsoftwaresubsystemsaretreatedlikedevicedriverswithoutany associatedhardware.Toincludeanyofthesepieces,a‘‘pseudo-device’’specificationmustbeused. Aspecificationforapseudodevicetakestheform pseudo-devicedevice-name[howmany] Examplesofpseudodevicesarebk,theBerknetlinediscipline,pty,thepseudoterminal driver(wheretheoptionalhowmanyvalueindicatesthenumberofpseudoterminalstoconfigure, 32default),andinet,theDARPAInternetprotocols(onemustalsospecifyINETinthe ‘‘options’’).Otherpseudodevicesforthenetworkincludeloop,thesoftwareloopbackinterface, imp(requiredwhenaCSSorACCimpisconfigured),andether(usedbytheAddressResolutionProtocolon10Mb/secethernets).Moreinformationonconfiguringeachofthesecanalsobe foundinsection4ofthemanual. July27,1983 BuildingSystemsWithConfig SampleConfigurationFiles 5.SAMPLECONFIGURATIONFILES InthissectionwewillconsiderhowtoconfigureasampleVAX-11/780systemonwhichthe hardwarecanbereconfiguredtoguardagainstvarioushardwaremishaps.Wethenstudythe rulesneededtoconfigureaVAX-11/750toruninanetworkingenvironment. 5.1.VAX-11/780System OurVAX-11/780isconfiguredwithhardwarerecommendedinthedocument‘‘HintsonCon-figuringaVAXfor4.2BSD’’(thisisoneofthehigh-endconfigurations).Table1liststheperti-nenthardwaretobeconfigured. ItemVendorConnectionNameReference cpuDECVAX780 MASSBUScontrollerEmulexnexus?mba0hp(4) diskFujitsumba0hp0 diskFujitsumba0hp1 MASSBUScontrollerEmulexnexus?mba1 diskFujitsumba1hp2 diskFujitsumba1hp3 UNIBUSadapterDECnexus? tapecontrollerEmulexuba0tm0tm(4) tapedriveKennedytm0te0 tapedriveKennedytm0te1 terminalmultiplexorEmulexuba0dh0dh(4) terminalmultiplexorEmulexuba0dh1 terminalmultiplexorEmulexuba0dh2 Table1.VAX-11/780Hardwaresupport. WewillcallthismachineANSELandconstructaconfigurationfileonestepatatime. Thefirststepistofillintheglobalconfigurationparameters.ThemachineisaVAX,sothe machinetypeis‘‘vax’’.Wewillassumethissystemwillrunonlyonthisoneprocessor,sothecpu typeis‘‘VAX780’’.Theoptionsareemptysincethisisgoingtobea‘‘vanilla’’VAX.Thesystem identifier,asmentionedbefore,is‘‘ANSEL’’andthemaximumnumberofusersweplantosupportisabout40.Thusthebeginningoftheconfigurationfilelookslikethis: # #ANSELVAX(apictureperfectmachine) # machinevax cpuVAX780 timezone8dst identANSEL maxusers40 Tothiswemustthenaddthespecificationsforthreesystemimages.Thefirstwillbeour standardsystemwiththerooton‘‘hp0’’andswappingonthesamedriveastheroot.Thesecond willhavetherootfilesysteminthesamelocation,butswapspaceinterleavedamongdriveson eachcontroller.Finally,thethirdwillbeagenericsystem,toallowustobootoffanyofthefour diskdrives. July27,1983 BuildingSystemsWithConfig-12-SampleConfigurationFiles configvmunixrootonhp0 confighpvmunixrootonhp0swaponhp0andhp2 configgenvmunixswapgeneric Finally,thehardwaremustbespecified.Letusfirstjusttrytranscribingtheinformation fromTable1. controllermba0atnexus? diskhp0atmba0disk0 diskhp1atmba0disk1 controllermba1atnexus? diskhp2atmba1disk2 diskhp3atmba1disk3 controlleruba0atnexus? controllertm0atuba0csr0172520vectortmintr tapete0attm0drive0 tapete1attm0drive1 devicedh0atuba0csr0160020vectordhrintdhxint devicedm0atuba0csr0170500vectordmintr devicedh1atuba0csr0160040vectordhrintdhxint devicedh2atuba0csr0160060vectordhrintdhxint (Oh,Iforgottomentiononepaneloftheterminalmultiplexorhasmodemcontrol,thusthe ‘‘dm0’’device.) Thiswillsuffice,butleavesuswithlittleflexibility.Supposeourfirstdiskcontrollerwereto break.Wewouldliketorecablethedrivesnormallyonthesecondcontrollersothatallourdisks couldstillbeusedwithoutreconfiguringthesystem.TodothiswewildcardtheMASSBUS adapterconnectionsandalsotheslavenumbers.Further,wewildcardtheUNIBUSadapterconnectionsincasewedecidesometimeinthefuturetopurchaseanotheradaptertooffloadthesingleUNIBUSwecurrentlyhave.Thereviseddevicespecificationswouldthenbe: controllermba0atnexus? diskhp0atmba?disk? diskhp1atmba?disk? controllermba1atnexus? diskhp2atmba?disk? diskhp3atmba?disk? controlleruba0atnexus? controllertm0atuba?csr0172520vectortmintr tapete0attm0drive0 tapete1attm0drive1 devicedh0atuba?csr0160020vectordhrintdhxint devicedm0atuba?csr0170500vectordmintr devicedh1atuba?csr0160040vectordhrintdhxint devicedh2atuba?csr0160060vectordhrintdhxint ThecompletedconfigurationfileforANSELisshowninAppendixC. 5.2.VAX-11/750withnetworksupport OurVAX-11/750systemwillbelocatedontwo10Mb/sEthernetlocalareanetworksand alsotheDARPAInternet.ThesystemwillhaveaMASSBUSdrivefortherootfilesystemand twoUNIBUSdrives.Pagingisinterleavedamongallthreedrives.Wehavesoldourstandard DECterminalmultiplexorssincethismachinewillbeaccessedsolelythroughthenetwork.This machineisnotintendedtohavealargeusercommunity,itdoesnothaveagreatdealofmemory. Firsttheglobalparameters: July27,1983 BuildingSystemsWithConfig-13-SampleConfigurationFiles # #UCBVAX(Gatewaytotheworld) # machinevax cpu"VAX780" cpu"VAX750" identUCBVAX timezone8dst maxusers32 optionsINET ThemultiplecputypesallowustoreplaceUCBVAXwithamorepowerfulcpuwithout reconfiguringthesystem.Thevalueof32givenforthemaximumnumberofusersisdonetoforce thesystemdatastructurestobeover-allocated.Thatisdesirableonthismachinebecause,while itisnotexpectedtosupportmanyusers,itisexpectedtoperformagreatdealofwork.Upping thisvalueresultsinalargerdiskbuffercachethanwouldnormallybeallocatedifthetruenumber ofusersweregiven.The‘‘INET’’indicatesweplantousetheDARPAstandardInternetprotocolsonthismachine. Thesystemimagesanddisksareconfiguredinnext. configvmunixrootonhpswaponhpandrk0andrk1 configupvmunixrootonup confighkvmunixrootonhkswaponrk0andrk1 controllermba0atnexus? controlleruba0atnexus? diskhp0atmba?drive0 diskhp1atmba?drive1 controllersc0atuba?csr0176700vectorupintr diskup0atsc0drive0 diskup1atsc0drive1 controllerhk0atuba?csr0177440vectorrkintr diskrk0athk0drive0 diskrk1athk0drive1 UCBVAXrequiresheavyinterleavingofitspagingareatokeepupwithallthemailtrafficit handles.Thelimitingfactoronthissystem’sperformanceisusuallythenumberofdiskarms,as opposedtomemoryorcpucycles.TheextraUNIBUScontroller,‘‘sc0’’,isincasetheMASSBUS controllerbreaksandasparecontrollermustbeinstalled(mostofouroldUNIBUScontrollers havebeenreplacedwiththenewerMASSBUScontrollers,sowehaveanumberofthesearoundas spares). Finally,weaddinthenetworksupport.TheInternetprotocolsrequirean‘‘inet’’pseudodeviceinadditiontotheglobal‘‘INET’’optionspecifiedabove.Pseudoterminalsareneededto allowuserstologinacrossthenetwork(remembertheonlyhardwiredterminalistheconsole). TheconnectiontotheInternetisthroughanIMP,thisrequiresyetanotherpseudo-device(in additiontotheactualhardwaredeviceusedbytheIMPsoftware).And,finally,therearethetwo Ethernetdevices.Theseuseaspecialprotocol,theAddressResolutionProtocol(ARP),tomap betweenInternetandEthernetaddresses.Thus,yetanotherpseudo-deviceisneeded.Theaddi-tionaldevicespecificationsareshowbelow. July27,1983 BuildingSystemsWithConfig-14-SampleConfigurationFiles pseudo-deviceinet pseudo-devicepty #softwareloopbackdevicefortesting pseudo-deviceloop pseudo-deviceimp deviceacc0atuba?csr0167600vectoraccrintaccxint pseudo-deviceether deviceec0atuba?csr0164330vectorecrinteccollideecxint deviceil0atuba?csr0164000vectorilrintilcint ThecompletedconfigurationfileforUCBVAXisshowninAppendixC. 5.3.Miscellaneouscomments Itshouldbenotedintheseexamplesthatneithersystemwasconfiguredtousediskquotas orthe4.1BSDcompatibilitymode.Tousetheseoptionalfacilities,andothers,wewouldprobably cleanoutourcurrentconfiguration,reconfigurethesystem,thenrecompileandrelinkthesystem image(s).Thiscould,ofcourse,beavoidedbyfiguringoutwhichrelocatableobjectfilesare affectedbythereconfiguration,thenreconfiguringandrecompilingonlythosefilesaffectedbythe configurationchange.Thistechniqueshouldbeusedcarefully. July27,1983 BuildingSystemsWithConfig AddingNewDevices 6.ADDINGNEWSYSTEMSOFTWARE Thissectionisnotforthenovice,itdescribessomeoftheinnerworkingsoftheconfigurationprocessaswellasthepertinentpartsofthesystemautoconfigurationprocess.Itisintended togivethosepeoplewhointendtoinstallnewdevicedriversand/orothersystemfacilitiessufficientinformationtodosointhemannerwhichwillallowotherstoeasilysharethechanges. Thissectionisbrokenintofourparts: •generalguidelinestobefollowedinmodifyingsystemcode, •howtoaddadevicedriverto4.2BSD, •howUNIBUSdevicedriversareautoconfiguredunder4.2BSDontheVAX,and •howtoaddnon-standardsystemfacilitiesto4.2BSD. 6.1.Modifyingsystemcode Ifyouwishtomakesite-specificmodificationstothesystemitisbesttobracketthemwith #ifdefSITENAME ... #endif toallowyoursourcetobeeasilydistributedtoothers,andalsotosimplifydiff(1)listings.Ifyou choosenottouseasourcecodecontrolsystem(e.g.SCCS,RCS),andperhapsevenifyoudo,itis recommendedthatyousavetheoldcodewithsomethingoftheform: #ifndefSITENAME ... #endif Wetrytoisolateoursite-dependentcodeinindividualfileswhichmaybeconfiguredwithpseudo-devicespecifications. Indicatemachinespecificcodewith‘‘#ifdefvax’’.4.2BSDhasundergoneextensiveworkto makeitextremelyportabletomachineswithsimilararchitectures−youmaysomedayfindyourselftryingtouseasinglecopyofthesourcecodeonmultiplemachines. Uselintperiodicallyifyoumakechangestothesystem.The4.2BSDreleasehasonlyone lineoflintinit.Itisverysimpletolintthekernel.UsetheLINTconfigurationfile,designedto pullinasmuchofthekernelsourcecodeaspossible,inthefollowingmanner. $cd/sys/conf $mkdir../LINT $configLINT $cd../LINT $makedepend $makeassym.s $make−klint>linterrs2>&1& (orforusersofcsh(1)) %make−k>&linterrs Thistakesabout45minutesonalightlyloadedVAX-11/750,butiswellworthit. 6.2.Addingdevicedriversto4.2BSD Thei/osystemandconfighavebeendesignedtoeasilyallownewdevicesupporttobe added.Asdescribedin‘‘InstallingandOperating4.2BSDontheVAX’’,thesystemsourcedirectoriesareorganizedasfollows: July27,1983 BuildingSystemsWithConfig-16- AddingNewDevices /sys/hmachineindependentincludefiles /sys/sysmachineindependentsystemsourcefiles /sys/confsiteconfigurationfilesandbasictemplates /sys/netnetworkindependent,butnetworkrelatedcode /sys/netinetDARPAInternetcode /sys/netimpIMPsupportcode /sys/netpupPUP-1supportcode /sys/vaxVAXspecificmainlinecode /sys/vaxifVAXnetworkinterfacecode /sys/vaxmbaVAXMASSBUSdevicedriversandrelatedcode /sys/vaxubaVAXUNIBUSdevicedriversandrelatedcode ExistingblockandcharacterdevicedriversfortheVAXresidein‘‘/sys/vax’’, ‘‘/sys/vaxmba’’,and‘‘/sys/vaxuba’’.Networkinterfacedriversresidein‘‘/sys/vaxif’’.Anynew devicedriversshouldbeplacedintheappropriatesourcecodedirectoryandnamedsoasnotto conflictwithexistingdevices.Normally,definitionsforthingslikedeviceregistersareplacedina separatefileinthesamedirectory.Forexample,the‘‘dh’’devicedriverisnamed‘‘dh.c’’andits associatedincludefileisnamed‘‘dhreg.h’’. Oncethesourceforthedevicedriverhasbeenplacedinadirectory,thefile ‘‘/sys/conf/files.machine’’,andpossibly‘‘/sys/conf/devices.machine’’shouldbemodified.Thefiles filesintheconfdirectorycontainalineforeachsourceorbinary-onlyfileinthesystem.Those fileswhicharemachineindependentarelocatedin‘‘/sys/conf/files’’whilemachinespecificfilesare in‘‘/sys/conf/files.machine’’.The‘‘devices.machine’’fileisusedtomapdevicenamestomajor blockdevicenumbers.Ifthedevicedriverbeingaddedprovidessupportforanewdiskyouwill wanttomodifythisfile(theformatisobvious). Theformatofthefilesfilehasgrownsomewhatcomplexovertime.Entriesarenormallyof theform vaxuba/foo.coptionalfoodevice-driver wherethekeywordoptionalindicatesthattocompilethe‘‘foo’’driverintothesystemitmustbe specifiedintheconfigurationfile.Ifinsteadthedriverisspecifiedasstandard,thefilewillbe loadednomatterwhatconfigurationisrequested.Thisisnotnormallydonewithdevicedrivers. Thefactthatthefileisspecifiedasadevice-driverresults,ontheVAX,inthecompilationinclud-inga−−ioptionfortheCoptimizer.Thisisrequiredwhenpointerreferencesaremadetomemory locationsintheVAXi/oaddressspace. Asidefromincludingthedriverinthefilesfile,itmustalsobeaddedtothedeviceconfigurationtables.Thesearelocatedin‘‘/sys/vax/conf.c’’,orsimilarformachinesotherthanthe VAX.Ifyoudon’tunderstandwhattoaddtothisfile,youshouldstudyanentryforanexisting driver.Rememberthatthepositionintheblockdevicetablespecifieswhatthemajorblock devicenumberis,thisisneededinthe‘‘devices.machine’’fileifthedeviceisadisk. Withtheconfigurationinformationinplace,yourconfigurationfileappropriatelymodified, andasystemreconfiguredandrebootedyoushouldincorporatetheshellcommandsneededto installthespecialfilesinthefilesystemtothefile‘‘/dev/MAKEDEV’’or ‘‘/dev/MAKEDEV.local’’.Thisisdiscussedinthedocument‘‘InstallingandOperating4.2BSD ontheVAX’’. 6.3.AutoconfigurationontheVAX 4.2BSD(and4.1BSD)requirealldevicedriverstoconformtoasetofruleswhichallowthe systemto: 1)supportmultipleUNIBUSandMASSBUSadapters, 2)supportsystemconfigurationatboottime,and July27,1983 BuildingSystemsWithConfig-17- AddingNewDevices 3)manageresourcessoasnottocrashwhendevicesrequestresourceswhichareunavailable. Inaddition,devicessuchastheRK07whichrequireeveryoneelsetogetofftheUNIBUSwhen theyarerunningneedcooperationfromotherDMAdevicesiftheyaretowork.Sinceitis unlikelythatyouwillbewritingadevicedriverforaMASSBUSdevice,thissectionisdevoted exclusivelytodescribingthei/osystemandautoconfigurationprocessasitappliestoUNIBUS devices. EachUNIBUSonaVAXhasasetofresources: •496mapregisterswhichareusedtoconvertfromthe18bitUNIBUSaddressesintothe muchlargerVAXaddressspace. •Somenumberofbuffereddatapaths(3onan11/750,15onan11/780,0onan11/730) whichareusedbyhighspeeddevicestotransferdatausingfewerbuscycles. ThereisastructureoftypestructubahdinthesystemperUNIBUSadapterusedtomanage theseresources.Thisstructurealsocontainsalinkedlistwheredeviceswaitingforresourcesto completeDMAUNIBUSactivityhaverequestswaiting. TherearethreecentralstructuresinthewritingofdriversforUNIBUScontrollers;devices whichdonotdoDMAi/ocanoftenuseonlytwoofthesestructures.Thestructuresarestruct ubactlr,theUNIBUScontrollerstructure,structubadevicetheUNIBUSdevicestructure,and structubadriver,theUNIBUSdriverstructure.Theubactlrandubadevicestructuresarein one-to-onecorrespondencewiththedefinitionsofcontrollersanddevicesinthesystemconfigura-tion.Eachdriverhasastructubadriverstructurespecifyinganinternalinterfacetotherestof thesystem. Thusaspecification controllersc0atuba0csr0176700vectorupintr wouldcauseastructubactlrtobedeclaredandinitializedinthefileioconf.cforthesystemconfiguredfromthisdescription.Similarlyspecifying diskup0atsc0drive0 woulddeclarearelatedubadeviceinthesamefile.Theup.cdriverwhichimplementsthisdriver specifiesinitsdeclarations: intupprobe(),upslave(),upattach(),updgo(),upintr(); structubactlr*upminfo[NSC]; structubadevice*updinfo[NUP]; ushortupstd[]={0776700,0774400,0776300,0}; structubadriverscdriver= {upprobe,upslave,upattach,updgo,upstd,"up",updinfo,"sc",upminfo}; initializingtheubadriverstructure.Thedriverwillsupportsomenumberofcontrollersnamed sc0,sc1,etc,andsomenumberofdrivesnamedup0,up1,etc.wherethedrivesmaybeonanyof thecontrollers(thatisthereisasinglelinearnamespacefordevices,separatefromthecontrollers.) Wenowexplainthefieldsinthevariousstructures.Itmayhelptolookatacopyofvaxuba/ubareg.h,h/ubavar.handdriverssuchasup.canddz.cwhilereadingthedescriptionsofthe variousstructurefields. ubadriverstructure Oneofthesestructuresexistsperdriver.Itisinitializedinthedriverandcontainsfunctions usedbytheconfigurationprogramandbytheUNIBUSresourceroutines.Thefieldsofthestructureare: udprobe Aroutinewhichisgivenacaddrtaddressasargumentandshouldcauseaninterrupton thedevicewhosecontrol-statusregisterisatthataddressinvirtualmemory.Itmaybethe July27,1983 BuildingSystemsWithConfig-18- AddingNewDevices casethatthedevicedoesnotexist,sotheproberoutineshouldusedelays(viathe DELAY(n)macrowhichdelaysfornmicroseconds)ratherthanwaitingforspecificeventsto occur.Theroutinemustnotdeclareitsargumentasaregisterparameter,butmust declare registerintbr,cvec; aslocalvariables.Atboottimethesystemtakesspecialmeasuresthatthesevariablesare ‘‘value-result’’parameters.ThebristheIPLofthedevicewhenitinterrupts,andthecvec istheinterruptvectoraddressontheUNIBUS.Theseregistersareactuallyfilledininthe interrupthandlerwhenaninterruptoccurs. Asanexample,hereistheup.cproberoutine: upprobe(reg) caddrtreg; { registerintbr,cvec; #ifdeflint br=0;cvec=br;br=cvec; #endif ((structupdevice*)reg)->upcs1=UPIE|UPRDY; DELAY(10); ((structupdevice*)reg)->upcs1=0; return(sizeof(structupdevice)); } Thedefinitionsforlintservetoindicatetoitthatthebrandcvecvariablesarevalue-result. ThestatementshereinterruptenablethedeviceandwritethereadybitUPRDY.The10 microseconddelayinsuresthattheinterruptenablewillnotbecanceledbeforetheinterrupt canbeposted.Thereturnof‘‘sizeof(structupdevice)’’hereindicatesthattheproberoutineissatisfiedthatthedeviceispresent(thevaluereturnedisnotcurrentlyused,but futureplansdictateyoushouldreturntheamountofspaceinthedevice’sregisterbank).A proberoutinemayusethefunction‘‘badaddr’’toseeifcertainotheraddressesareaccessible ontheUNIBUS(withoutgeneratingamachinecheck),orlookatthecontentsoflocations wherecertainregistersshouldbe.Iftheregisterscontentsarenotacceptableorthe addressesdon’trespond,theproberoutinecanreturn0andthedevicewillnotbeconsideredtobethere. OneotherthingtonoteisthattheactionofdifferentVAXenwhenillegaladdressesare accessedontheUNIBUSmaydiffer.Someofthemachinesmaygeneratemachinechecks andsomemaycauseUNIBUSerrors.Suchconsiderationsarehandledbytheconfiguration programandthedriverwriterneednotbeconcernedwiththem. Itisalsopossibletowriteaverysimpleproberoutineforaone-of-a-kinddeviceifprobingis difficultorimpossible.Sucharoutinewouldincludestatementsoftheform: br=0x15; cvec=0200; forinstance,todeclarethatthedeviceranatUNIBUSbr5andinterruptedthroughvector 0200ontheUNIBUS.ThecurrentUDA-50driverdoessomethingsimilartothisbecause thedeviceissodifficulttoforceaninterruptonthatithardlyseemsworthwhile. udslave Thisroutineiscalledwithaubadevicestructure(yettobedescribed)andtheaddressof thedevicecontroller.Itshoulddeterminewhetheraparticularslavedeviceofacontrolleris present,returning1ifitisand0ifitisnot.Asanexamplehereistheslaveroutinefor up.c. July27,1983 BuildingSystemsWithConfig-19- AddingNewDevices upslave(ui,reg) structubadevice*ui; caddrtreg; { registerstructupdevice*upaddr=(structupdevice*)reg; upaddr->upcs1=0;/*conservative*/ upaddr->upcs2=ui->uislave; if(upaddr->upcs2&UPCS2NED){ upaddr->upcs1=UPDCLR|UPGO; return(0); } return(1); } Herethecodefetchestheslave(diskunit)numberfromtheuislavefieldoftheubadevice structure,andseesifthecontrollerrespondsthatthatisanon-existentdriver(NED).Ifthe driveadriveclearisissuedtocleanthestateofthecontroller,and0isreturnedindicating thattheslaveisnotthere.Otherwisea1isreturned. udattach Theattachroutineiscalledaftertheautoconfigurecodeandthedriverconcurthata peripheralexistsattachedtoacontroller.Thisistheroutinewhereinternaldriverstate abouttheperipheralcanbeinitialized.Hereistheattachroutinefromtheup.cdriver: upattach(ui) registerstructubadevice*ui; { registerstructupdevice*upaddr; if(upwstart==0){ timeout(upwatch,(caddrt)0,hz); upwstart++; } if(ui->uidk>=0) dkmspw[ui->uidk]=.0000020345; upip[ui->uictlr][ui->uislave]=ui; upsoftc[ui->uictlr].scndrive++; ui->uitype=upmaptype(ui); } Theattachroutinehereperformsanumberoffunctions.Thefirsttimeanydriveis attachedtothecontrolleritstartsthetimeoutroutinewhichwatchesthediskdrivesto makesurethatinterruptsaren’tlost.Italsoinitializes,fordeviceswhichhavebeen assignediostatnumbers(whenui->uidk>=0),thetransferrateofthedeviceinthearray dkmspw,thefractionofasecondittakestotransfer16bitword.Ittheninitializesan invertingpointerinthearrayupipwhichwillbeusedlatertodetermine,foraparticularup controllerandslavenumber,thecorrespondingubadevice.Itincrementsthecountofthe numberofdevicesonthiscontroller,sothatsearchcommandscanlaterbeavoidedifthe countisexactly1.Itthenattemptstodeciphertheactualtypeofdriveattachedtothe controllerinacontroller-specificway.OntheEMULEXSC-21itmayaskforthenumberof tracksonthedeviceandusethistodecidewhatthedrivetypeis.Thedrivetypeisusedto setupdiskpartitionmappingtablesandotherdevicespecificinformation. uddgo IstheroutinewhichiscalledbytheUNIBUSresourcemanagementroutineswhenanoperationisreadytobestarted(becausetherequiredresourceshavebeenallocated).The July27,1983 BuildingSystemsWithConfig-20- AddingNewDevices routineinup.cis: updgo(um) structubactlr*um; { registerstructupdevice*upaddr=(structupdevice*)um->umaddr; upaddr->upba=um->umubinfo; upaddr->upcs1=um->umcmd|((um->umubinfo>>8)&0x300); } ThisroutineusesthefieldumubinfooftheubactlrstructurewhichiswheretheUNIBUS routinesstoretheUNIBUSmapallocationinformation.Inparticluar,thelow18bitsofthis wordgivetheUNIBUSaddressassignedtothetransfer.Theassignmenttoupbainthego routineplacesthelow16bitsoftheUNIBUSaddressinthediskUNIBUSaddressregister. Thenextassignmentplacesthediskoperationcommandandtheextended(high2)address bitsinthedevicecontrol-statusregister,startingthei/ooperation.Thefieldumcmdwas initializedwiththecommandtobestuffedhereinthedrivercodeitselfbeforethecallto theubagoroutinewhicheventuallyresultedinthecalltoupdgo. udaddr AretheconventionaladdressesforthedevicecontrolregistersinUNIBUSspace.Thisinformationisusedbythesystemtolookforinstancesofthedevicesupportedbythedriver. Whenthesystemprobesforthedeviceitfirstchecksforacontrol-statusregisterlocatedat theaddressindicatedintheconfigurationfile(ifsupplied),thenusesthelistofconventional addressespointedtobeudaddr. uddname Isthenameofadevicesupportedbythiscontroller;thusthedisksonaSC-21controllerare calledup0,up1,etc.Thatisbecausethisfieldcontainsup. uddinfo Isanarrayofbackpointerstotheubadevicestructuresforeachdeviceattachedtothecontroller.Eachdriverdefinesasetofcontrollersandasetofdevices.Thedeviceaddress spaceisalwaysone-dimensional,sothatthepresenceofextracontrollersmaybemasked away(e.g.bypatternmatching)totakeadvantageofhardwareredundancy.Thisfieldis filledinbytheconfigurationprogram,andusedbythedriver. udmname Thenameofacontroller,e.g.scfortheup.cdriver.ThefirstSC-21iscalledsc0,etc. udminfo Thebackpointerarraytothestructuresforthecontrollers. udxclu Ifnon-zerospecifiesthatthecontrollerrequiresexclusiveuseoftheUNIBUSwhenitisrun-ning.Thisisnon-zerocurrentlyonlyfortheRK611controllerfortheRK07diskstomap aroundahardwareproblem.Itcouldalsobeusedif6250bpitapedrivesaretobeusedon theUNIBUStoinsurethattheygetthebandwidththattheyneed(basicallythewhole bus). ubactlrstructure Oneofthesestructuresexistsper-controller.ThefieldslinkthecontrollertoitsUNIBUS adapterandcontainthestateinformationaboutthedevicesonthecontroller.Thefieldsare: umdriver Apointertothestructubadeviceforthisdriver,whichhasfieldsasdefinedabove. umctlr Thecontrollernumberforthiscontroller,e.g.the0insc0. July27,1983 BuildingSystemsWithConfig-21- AddingNewDevices umalive Setto1ifthecontrollerisconsideredalive;currently,alwayssetforanystructureencounteredduringnormaloperation.Thatis,thedriverwillhaveahandleonaubactlrstructure onlyiftheconfigurationroutinessetthisfieldtoa1andentereditintothedrivertables. umintr Theinterruptvectorroutinesforthisdevice.Thesearegeneratedbyconfigandthisfieldis initializedintheioconf.cfile. umhd Aback-pointertotheUNIBUSadaptertowhichthiscontrollerisattached. umcmd Aplaceforthedrivertostorethecommandwhichistobegiventothedevicebeforecalling theroutineubagowiththedevicesubadevicestructure.Thisinformationisthenretrieved whenthedevicegoroutineiscalledandstuffedinthedevicecontrolstatusregistertostart thei/ooperation. umubinfo InformationabouttheUNIBUSresourcesallocatedtothedevice.Thisisnormallyonly usedindevicedrivergoroutine(asupdgoabove)andoccasionallyinexceptionalcondition handlingsuchasECCcorrection. umtab Thisbufferstructureisaplacewherethedriverhangsthedevicestructureswhichareready totransfer.Eachdriverallocatesabufstructureforeachdevice(e.g.updtabintheup.c driver)forthispurpose.Youcanthinkofthisstructureasadevice-control-block,andthe bufstructureslinkedtoitastheunit-control-blocks.Thecodefordealingwiththisstruc-tureisstylized;seetherk.corup.cdriverforthedetails.Iftheubagoroutineistobeused, thestructureattachedtothisbufstructuremustbe: •Achainofbufstructuresforeachwaitingdeviceonthiscontroller. •Oneachwaitingbufstructureanotherbufstructurewhichistheonecontainingthe parametersofthei/ooperation. ubadevicestructure OneofthesestructuresexistforeachdeviceattachedtoaUNIBUScontroller.Devices whicharenotattachedtocontrollersorwhichperformnobuffereddatapathDMAi/omayhave onlyadevicestructure.Thusdzanddhdeviceshaveonlyubadevicestructures.Thefieldsare: uidriver Apointertothestructubadriverstructureforthisdevicetype. uiunit Theunitnumberofthisdevice,e.g.0inup0,or1indh1. uictlr Thenumberofthecontrolleronwhichthisdeviceisattached,or−1ifthisdeviceisnoton acontroller. uiubanum ThenumberoftheUNIBUSonwhichthisdeviceisattached. uislave Theslavenumberofthisdeviceonthecontrollerwhichitisattachedto,or−1ifthedevice isnotaslave.Thusadiskwhichwasunit2onaSC-21wouldhaveuislave2;itmightor mightnotbeup2,thatdependsonthesystemconfigurationspecification. uiintr Theinterruptvectorentriesforthisdevice,copiedintotheUNIBUSinterruptvectorat boottime.Thevaluesofthesefieldsarefilledinbyconfigtosmallcodesegmentswhichit generatesinthefileubglue.s. July27,1983 BuildingSystemsWithConfig-22- AddingNewDevices uiaddr Thecontrol-statusregisteraddressofthisdevice. uidk Theiostatnumberassignedtothisdevice.Numbersareassignedtodisksonly,andare smallpositiveintegerswhichindexthevariousdk*arraysin<sys/dk.h>. uiflags Theoptional‘‘flagsxxx’’parameterfromtheconfigurationspecificationwascopiedtothis field,tobeinterpretedbythedriver.Ifflagswasnotspecified,thenthisfieldwillcontaina 0. uialive Thedeviceisreallythere.Presentlysetto1whenadeviceisdeterminedtobealive,and left1. uitype Thedevicetype,tobeusedbythedriverinternally. uiphysaddr Thephysicalmemoryaddressofthedevicecontrol-statusregister.Thisisusedinthe devicedumproutinestypically. uimi Astructubactlrpointertothecontroller(ifany)onwhichthisdeviceresides. uihd AstructubahdpointertotheUNIBUSonwhichthisdeviceresides. UNIBUSresourcemanagementroutines UNIBUSdriversaresupportedbyacollectionofutilityroutineswhichmanageUNIBUS resources.IfadriverattemptstobypasstheUNIBUSroutines,otherdriversmaynotoperate properly.Themajorroutinesare:uballoctoallocateUNIBUSresources,ubarelsetoreleasepreviouslyallocatedresources,andubagotoinitiateDMA.WhenallocatingUNIBUSresourcesyou mayrequestthatyou NEEDBDP ifyouneedabuffereddatapath, HAVEBDP ifyoualreadyhaveabuffereddatapathandjustwantnewmappingregisters(andaccessto theUNIBUS),and CANTWAIT ifyouarecalling(potentially)frominterruptlevel Ifthepresentationheredoesnotanswerallthequestionsyoumayhave,consultthefile /sys/vaxuba/uba.c Autoconfigurationrequirements Basicallyallyouhavetodoiswriteaudprobeandaudattachroutineforthecontroller.It sufficestohaveaudproberoutinewhichjustinitializesbrandcvec,andaudattachroutine whichdoesnothing.Makingthedevicefullyconfigurablerequires,ofcourse,morework,butis worthitifyouexpectthedevicetobeincommonusageandwanttoshareitwithothers. Ifyoumanagedtocreatealltheneededhooks,thenmakesureyouincludethenecessary headerfiles;theonesincludedbyvaxuba/ct.carenearlyminimal.Orderisimportanthere,don’t besurprisedatundefinedstructurecomplaintsifyouordertheincludeswrongly.Finallyifyou getthedeviceconfiguredin,youcantrybootstrappingandseeifconfigurationmessagesprintout aboutyourdevice.Itisagoodideatohavesomemessagesintheproberoutinesothatyoucan seethatyouaregettingcalledandwhatisgoingon.Ifyoudonotgetcalled,thenyouprobably havethecontrol-statusregisteraddresswronginyoursystemconfiguration.Theautoconfigure July27,1983 BuildingSystemsWithConfig-23- AddingNewDevices codenoticesthatthedevicedoesn’texistinthiscaseandyouwillnevergetcalled. Assumingthatyourproberoutineworksandyoumanagetogenerateaninterrupt,thenyou arebasicallybacktowhereyouwouldhavebeenunderolderversionsofUNIX.Justbesureto usetheuictlrfieldoftheubadevicestructurestoaddressthedevice;compilinginfunnyconstantswillmakeyourdriveronlyworkontheCPUtypeyouhave(780,750,or730). Otherbadthingsthatmighthappenwhileyouaresettinguptheconfigurationstuff: •Youget‘‘nexuszerovector’’errorsfromthesystem.Thiswillhappenifyoucauseadeviceto interrupt,buttakeawaytheinterruptenablesofastthattheUNIBUSadaptercancelsthe interruptandconfusestheprocessor.Thebestthingtodoittoputamodestdelayinthe probecodebetweentheinstructionswhichshouldcauseandinterruptandtheclearingofthe interruptenable.(Youshouldclearinterruptenablebeforeyouleavetheproberoutinesothe devicedoesn’tinterruptmoreandconfusethesystemwhileitisconfiguringotherdevices.) •Thedevicerefusestointerruptorinterruptswitha‘‘zerovector’’.Thistypicallyindicatesa problemwiththehardwareor,fordeviceswhichemulateotherdevices,thattheemulationis incomplete.Devicesmayfailtopresentinterruptvectorsbecausetheyhaveconfiguration switchessetwrong,orbecausetheyarebeingaccessedininappropriateways.Incomplete emulationcancause‘‘maintenancemode’’featurestonotworkproperly,andthesefeaturesare oftenneededtoforcedeviceinterrupts. 6.4.Addingnon-standardsystemfacilities Thissectionconsiderstheworkneededtoaugmentconfig’sdatabasefilesfornon-standard systemfacilities. Asfarasconfigisconcernednon-standardfacilitiesmayfallintotwocategories.Config understandsthatcertainfilesareusedespeciallyforkernelprofiling.Thesefilesareindicatedin thefilesfileswithaprofiling-routinekeyword.Forexample,thecurrentprofilingsubroutinesare sequesteredoffinaseparatefilewiththefollowingentry: sys/subrmcount.coptionalprofiling-routine Theprofiling-routinekeywordforcesconfigtonotcompilethesourcefilewiththe−−pgoption. Thesecondkeywordwhichcanbeofuseistheconfig-dependentkeyword.Thiscausesconfig tocompiletheindicatedmodulewiththeglobalconfigurationparameters.Thisallowscertain modules,suchasmachdep.ctosizesystemdatastructuresbasedonthemaximumnumberof usersconfiguredforthesystem. July27,1983 BuildingSystemsWithConfig ConfigurationFileGrammar APPENDIXA.CONFIGURATIONFILEGRAMMAR Thefollowinggrammarisacompressedformoftheactualyacc(1)grammarusedbyconfig toparseconfigurationfiles.Terminalsymbolsareshownallinuppercase,literalsareemboldened;optionalclausesareenclosedinbrackets,‘‘[’’and‘‘]’’;zeroormoreinstantiationsare denotedwith‘‘*’’. Configuration::=[Spec;]* Spec::=Configspec |Devicespec |trace |/*lambda*/ /*configurationspecifications*/ Configspec::=machineID |cpuID |optionsOptlist |identID |Systemspec |timezone[−−]NUMBER[dst[NUMBER]] |timezone[−−]FPNUMBER[dst[NUMBER]] |maxusersNUMBER /*systemconfigurationspecifications*/ Systemspec::=configIDSystemparameter[Systemparameter]* Systemparameter::=swapspec|rootspec|dumpspec|argspec swapspec::=swap[on]swapdev[andswapdev]* swapdev::=devspec[sizeNUMBER] rootspec::=root[on]devspec dumpspec::=dumps[on]devspec argspec::=args[on]devspec devspec::=devname|majorminor majorminor::=majorNUMBERminorNUMBER devname::=ID[NUMBER[ID]] /*optionspecifications*/ Optlist::=Option[,Option]* Option::=ID[=Optvalue] July27,1983 BuildingSystemsWithConfig-25-ConfigurationFileGrammar Optvalue::=ID|NUMBER /*devicespecifications*/ Devicespec::=deviceDevnameDevinfoIntspec |masterDevnameDevinfo |diskDevnameDevinfo |tapeDevnameDevinfo |controllerDevnameDevinfo[Intspec] |pseudo-deviceDev[NUMBER] Devname::=DevNUMBER Dev::=uba|mba|ID Devinfo::=Coninfo[Info]* Coninfo::=atDevNUMBER |atnexusNUMBER Info::=csrNUMBER |driveNUMBER |slaveNUMBER |flagsNUMBER Intspec::=vectorID[ID]* |priorityNUMBER LexicalConventions Theterminalsymbolsarelooselydefinedas: ID Oneormorealphabetics,eitherupperorlowercase,andunderscore,‘‘’’. NUMBER ApproximatelytheClanguagespecificationforanintegernumber.Thatis,aleading‘‘0x’’ indicatesahexadecimalvalue,aleading‘‘0’’indicatesanoctalvalue,otherwisethenumber isexpectedtobeadecimalvalue.Hexadecimalnumbersmayuseeitherupperorlowercase alphabetics. FPNUMBER Afloatingpointnumberwithoutexponent.Thatisanumberoftheform‘‘nnn.ddd’’,where thefractionalcomponentisoptional. Inspecialinstancesaquestionmark,‘‘?’’,canbesubstitutedfora‘‘NUMBER’’token.Thisis usedtoeffectwildcardingindeviceinterconnectionspecifications. Commentsinconfigurationfilesareindicatedbya‘‘#’’characteratthebeginningoftheline;the remainderofthelineisdiscarded. Aspecificationisinterpretedasacontinuationofthepreviouslineifthefirstcharacteroftheline istab. July27,1983 BuildingSystemsWithConfig DeviceDefaultingRules APPENDIXB.RULESFORDEFAULTINGSYSTEMDEVICES Whenconfigprocessesa‘‘config’’rulewhichdoesnotfullyspecifythelocationoftheroot filesystem,pagingarea(s),deviceforsystemdumps,anddeviceforargumentlistprocessingit appliesasetofrulestodefinethosevaluesleftunspecified.Thefollowinglistofrulesareusedin defaultingsystemdevices. 1)Ifarootdeviceisnotspecified,theswapspecificationmustindicatea‘‘generic’’systemisto bebuilt. 2)Iftherootdevicedoesnotspecifyaunitnumber,itdefaultstounit0. 3)Iftherootdevicedoesnotincludeapartitionspecification,itdefaultstothe‘‘a’’partition. 4)Ifnoswapareaisspecified,itdefaultstothe‘‘b’’partitionoftherootdevice. 5)Ifnodeviceisspecifiedforprocessingargumentlists,thefirstswappartitionisselected. 6)Ifnodeviceischosenforsystemdumps,thefirstswappartitionisselected(seebelowtofind outwheredumpsareplacedwithinthepartition). Thefollowingtablesummarizesthedefaultpartitionsselectedwhenadevicespecificationis incomplete,e.g.‘‘hp0’’. TypePartition root‘‘a’’ swap‘‘b’’ args‘‘b’’ dumps‘‘b’’ Multipleswap/pagingareas Whenmultipleswappartitionsarespecified,thesystemtreatsthefirstspecifiedasa‘‘primary’’swapareawhichisalwaysused.Theremainingpartitionsaretheninterleavedintothe pagingsystematthetimeaswapon(2)systemcallismade.Thisisnormallydoneatboottime withacalltoswapon(8)fromthe/etc/rcfile. Systemdumps Systemdumpsareautomaticallytakenafterasystemcrash,providedthedevicedriverfor the‘‘dumps’’devicesupportsthis.Thedumpcontainsthecontentsofmemory,butnottheswap areas.Normallythedumpdeviceisadiskinwhichcasetheinformationiscopiedtoalocation nearthebackofthepartition.Thedumpisplacedinthebackofthepartitionbecausetheprimaryswapanddumpdevicearecommonlythesamedeviceandthisallowsthesystemtobe rebootedwithoutimmediatelyoverwritingthesavedinformation.Whenadumphasoccurred, thesystemvariabledumpsizeissettoanon-zerovalueindicatingthesize(inbytes)ofthedump. Thesavecore(8)programthencopiestheinformationfromthedumppartitiontoafileina ‘‘crash’’directoryandalsomakesacopyofthesystemwhichwasrunningatthetimeofthecrash (usually‘‘/vmunix’’).Theoffsettothesystemdumpisdefinedinthesystemvariabledumplo(a sectoroffsetfromthefrontofthedumppartition).Thesavecoreprogramoperatesbyreadingthe contentsofdumplo,dumpdev,anddumpmagicfrom/dev/kmem,thencomparingthevalueof dumpmagicreadfrom/dev/kmemtothatlocatedincorrespondinglocationinthedumpareaof thedumppartition.Ifamatchisfound,savecoreassumesacrashoccurredandreadsdumpsize fromthedumpareaofthedumppartition.Thisvalueisthenusedincopyingthesystemdump. Refertosavecore(8)formoreinformationaboutitsoperation. Thevaluedumploiscalculatedtobe dumpdev-size−DUMPDEV July27,1983 BuildingSystemsWithConfig-27-DeviceDefaultingRules wheredumpdev-sizeisthesizeofthediskpartitionwheresystemdumpsaretobeplaced,and DUMPDEVis10Megabytes.Ifthediskpartitionisnotlargeenoughtoholda10Megabyte dump,dumploissetto0(thefrontofthepartition).Forsiteswithmorethan10Megabytesof memorythedefinitionofDUMPDEVin/sys/vax/autoconf.cwillhavetobechanged. July27,1983 BuildingSystemsWithConfig SampleConfigFiles APPENDIXC.SAMPLECONFIGURATIONFILES Thefollowingconfigurationfilesaredevelopedinsection5;theyareincludedhereforcompleteness. # #ANSELVAX(apictureperfectmachine) # machinevax cpuVAX780 timezone8dst identANSEL maxusers40 configvmunixrootonhp0 confighpvmunixrootonhp0swaponhp0andhp2 configgenvmunixswapgeneric controllermba0atnexus? diskhp0atmba?disk? diskhp1atmba?disk? controllermba1atnexus? diskhp2atmba?disk? diskhp3atmba?disk? controlleruba0atnexus? controllertm0atuba?csr0172520vectortmintr tapete0attm0drive0 tapete1attm0drive1 devicedh0atuba?csr0160020vectordhrintdhxint devicedm0atuba?csr0170500vectordmintr devicedh1atuba?csr0160040vectordhrintdhxint devicedh2atuba?csr0160060vectordhrintdhxint July27,1983 BuildingSystemsWithConfig-29- SampleConfigFiles # #UCBVAX-Gatewaytotheworld # machinevax cpu"VAX780" cpu"VAX750" identUCBVAX timezone8dst maxusers32 optionsINET configvmunixrootonhpswaponhpandrk0andrk1 configupvmunixrootonup confighkvmunixrootonhkswaponrk0andrk1 controllermba0atnexus? controlleruba0atnexus? diskhp0atmba?drive0 diskhp1atmba?drive1 controllersc0atuba?csr0176700vectorupintr diskup0atsc0drive0 diskup1atsc0drive1 controllerhk0atuba?csr0177440vectorrkintr diskrk0athk0drive0 diskrk1athk0drive1 pseudo-deviceinet pseudo-devicepty #softwareloopbackdevicefortesting pseudo-deviceloop pseudo-deviceimp deviceacc0atuba?csr0167600vectoraccrintaccxint pseudo-deviceether deviceec0atuba?csr0164330vectorecrinteccollideecxint deviceil0atuba?csr0164000vectorilrintilcint July27,1983 BuildingSystemsWithConfig DataStructureSizingRules APPENDIXD.VAXKERNELDATASTRUCTURESIZINGRULES Certainsystemdatastructuresaresizedatcompiletimeaccordingtothemaximumnumber ofsimultaneoususersexpected,whileothersarecalculatedatboottimebasedonthephysical resourcespresent;e.g.memory.Thisappendixlistsbothsetsofrulesandalsoincludessomehints onchangingbuilt-inlimitationsoncertaindatastructures. Compiletimerules Thefile/sys/conf/param.ccontainsthedefinitionsofalmostalldatastructuressizedat compiletime.Thisfileiscopiedintothedirectoryofeachconfiguredsystemtoallowconfiguration-dependentrulesandvaluestobemaintained.Therulesimpliedbyitscontentsaresumma-rizedbelow(hereMAXUSERSreferstothevaluedefinedintheconfigurationfileinthe ‘‘maxusers’’rule). nproc Themaximumnumberofprocesseswhichmayberunningatanytime.Itisdefinedtobe 20+8*MAXUSERSandreferredtoinothercalculationsasNPROC. ntext Themaximumnumberofactivesharedtextsegments.Definedas24+MAXUSERS+ NETSLOP,whereNETSLOPis20whentheInternetprotocolsareconfiguredinthesystem and0otherwise.Theaddedsizeforsupportingthenetworkistotakeintoaccountthe numerousserverprocesseswhicharelikelytoexist. ninode Themaximumnumberoffilesinthefilesystemwhichmaybeactiveatanytime.This includesfilesinusebyusers,aswellasdirectoryfilesbeingreadorwrittenbythesystem andfilesassociatedwithboundsocketsintheUNIXipcdomain.Thisisdefinedas (NPROC+16+MAXUSERS)+32. nfile Thenumberof‘‘filetable’’structures.Onefiletablestructureisusedforeachopen, unshared,filedescriptor.Multiplefiledescriptorsmayreferenceasinglefiletableentry whentheyarecreatedthroughadupcall,orastheresultofafork.Thisisdefinedtobe 16*(NPROC+16+MAXUSERS)/10+32+2*NETSLOP whereNETSLOPisdefinedasforntext. ncallout Thenumberof‘‘callout’’structures.Onecalloutstructureisusedperinternalsystemevent handledwithatimeout.Timeoutsareusedforterminaldelays,watchdogroutinesindevice drivers,protocoltimeoutprocessing,etc.Thisisdefinedas16+NPROC. nclist Thenumberof‘‘c-list’’structures.C-liststructuresareusedinterminali/o.Thisisdefined as100+16*MAXUSERS. nmbclusters Themaximumnumberofpageswhichmaybeallocatedbythenetwork.Thisisdefinedas 256(aquartermegabyteofmemory)in/sys/h/mbuf.h.Inpractice,thenetworkrarelyuses thismuchmemory.Itstartsoffbyallocating64kilobytesofmemory,thenrequestingmore asrequired.Thisvaluerepresentsanupperbound. nquota Thenumberof‘‘quota’’structuresallocated.Quotastructuresarepresentonlywhendisc quotasareconfiguredinthesystem.Onequotastructureiskeptperuser.Thisisdefined tobe(MAXUSERS*9)/7+3. July27,1983 BuildingSystemsWithConfig-31-DataStructureSizingRules ndquot Thenumberof‘‘dquot’’structuresallocated.Dquotstructuresarepresentonlywhendisc quotasareconfiguredinthesystem.Onedquotstructureisrequiredperuser,peractivefile systemquota.Thatis,whenausermanipulatesafileonafilesystemonwhichquotasare enabled,theinformationregardingtheuser’squotasonthatfilesystemmustbein-core. Thisinformationiscached,sothatnotallinformationmustbepresentin-coreallthetime. Thisisdefinedas(MAXUSERS*NMOUNT)/4+NPROC,whereNMOUNTisthemaximumnumberofmountablefilesystems. Inadditiontotheabovevalues,thesystempagetables(usedtomapvirtualmemoryinthekernel’saddressspace)aresizedatcompiletimebytheSYSPTSIZEdefinitioninthefile /sys/vax/param.h.Thisisdefinedtobe20+MAXUSERSpagesofpagetables.Itsdefinition affectsthesizeofmanydatastructuresallocatedatboottimebecauseitconstrainstheamountof virtualmemorywhichmaybeaddressedbytherunningsystem.Thisisoftenthelimitingfactor inthesizeofthebuffercache. Run-timecalculations Themostimportantdatastructuressizedatrun-timearethoseusedinthebuffercache. Allocationisdonebyswipingphysicalmemory(andtheassociatedvirtualmemory)immediately afterthesystemhasbeenstartedup;lookinthefile/sys/vax/machdep.c.Theamountofphysicalmemorywhichmaybeallocatedtothebuffercacheisconstrainedbythesizeofthesystem pagetables,amongotherthings.Whilethesystemmaycalculatealargeamountofmemoryto beallocatedtothebuffercache,ifthesystempagetableistoosmalltomapthisphysicalmemory intothevirtualaddressspaceofthesystem,onlyasmuchascanbemappedwillbeused. Thebuffercacheiscomprisedofanumberof‘‘bufferheaders’’andapoolofpagesattached totheseheaders.Bufferheadersaredividedintotwocategories:thoseusedforswappingandpaging,andthoseusedfornormalfilei/o.Thesystemtriestoallocate10%ofavailablephysical memoryforthebuffercache(whereavailabledoesnotcountthatspaceoccupiedbythesystem’s textanddatasegments).Ifthisresultsinfewerthan16pagesofmemoryallocated,then16 pagesareallocated.Thisvalueiskeptintheinitializedvariablebufpagessothatitmaybe patchedinthebinaryimage(toallowtuningwithoutrecompilingthesystem).Asufficient numberoffilei/obufferheadersarethenallocatedtoalloweachtohold2pageseach,andhalfas manyswapi/obufferheadersarethenallocated.Thenumberofswapi/obufferheadersisconstrainedtobenomorethan256. Systemsizelimitations Asdistributed,thesumofthevirtualsizesofthecore-residentprocessesislimitedto64M bytes.Thesizeofthetext,anddatasegmentsofasingleprocessarecurrentlylimitedto6M byteseach,andthestacksegmentsizeislimitedto512Kbytesasasoft,user-changeablelimit, andmaybeincreasedto6Mwiththesetrlimit(2)systemcall.Iftheseareinsufficient,theycan beincreasedbychangingtheconstantsMAXTSIZ,MAXDSIZandMAXSSIZinthefile /sys/vax/vmparam.h,whilechangingthedefinitionsin/sys/h/dmap.hand/sys/h/text.h.You mustbecarefulindoingthisthatyouhaveadequatepagingspace.Asnormallyconfigured,the systemhasonly16Mbytesperpagingarea.Thebestwaytogetmorespaceistoprovidemultiple,therebyinterleaved,pagingareas. Toincreasetheamountofresidentvirtualspacepossible,youcanaltertheconstant USRPTSIZE(in/sys/vax/vmparam.h).Toallow128megabytesofresidentvirtualspaceone wouldchangethe8toa16. Becausethefilesystemblocknumbersarestoredinpagetablepgblknoentries,themaximumsizeofafilesystemislimitedto2ˆ 191024byteblocks.Thusnofilesystemcanbelarger than512Mbytes. Thecountofmountablefilesystemsislimitedto15.Thisshouldbesufficient.Ifyouhave manydisksitmakessensetomakesomeofthemsinglefilesystems,andthepagingareasdon’t July27,1983 BuildingSystemsWithConfig-32-DataStructureSizingRules countinthistotal.Toincreasethisitwillbenecessarytochangethecore-map/sys/h/cmap.h sincethereisa4bitfieldusedhere.Thesizeofthecore-mapwillthenexpandto16bytesper 1024bytepage.(Don’tforgettochangeMSWAPXandNMOUNTin/sys/h/param.halso.) ThemaximumvalueNOFILE(openfilesperprocesslimit)canberaisedtois30becauseof abitfieldinthepagetableentryin/sys/machine/pte.h. July27,1983