software development plan - fermilab · software development plan 1. introduction this software...

Software DevelopmentPlan

Laboratory

SSCL-N-865June1994DistributionCategory:400

D. Gurd

U,

Cj

SuperconductingSuper Collider

SSCL-N-865


D. Gurd

SuperconductingSuperCollider Laboratory*

2550BeckleymeadeAve.Dallas,TX 75237,USA

June1994

*Operatedby the UniversitiesResearchAssociation,Inc., for theU.S. Departmentof EnergyunderContractNo. DE-AC3S-89ER40486.

Plan

Contents

1. Introduction.1.1. ProjectOverview .

1.1.1. TheEPICSSystem1.1.2. SSCSpecificApplications

1.2. ProjectDeliverables1.2.1. SystemDeliverables1.2.2. ApplicationDeliverables

1.3. Evolution of theSoftwareDevelopment1.4. ReferenceMaterials1.5. Definitions andAcronyms

2. ProjectOrganization

2.1. ProcessModel2.2. OrganizationalStructure

3. ManagerialProcess3.1. ManagementObjectivesandPriorities3.2. RiskManagement3.3. Monitoring andControllingtheDevelopmentProcess.

3.3.1. ApplicationSoftwareReviews3.3.2. SystemSoftwareReviews

3.4. StaffingPlan

4. TechnicalProcess4.1. Methods,Tools andTechniques

4.1.1. DevelopmentTools4.1.1 SoftwareRepository4.1.3. SystemDevelopmentArea4.1.4.. Application DevelopmentArea4.1.5. SoftwareTest Area

4.2. SoftwareDocumentation4.2.1. SoftwareRequirementsSpecification4.2.2. SoftwareTest Plans

4.3. ProjectSupportFunctions4.3.1. DevelopmentSystemAdministration4.3.2. ConfigurationManagement

5. Work Packages,ScheduleandBudget

Appendix A SystemModification RequestForm

33445S7788

.9

10

12121315151617

1717

1818192325252626272727

30

30

-1-

SoftwareDevelopmentPlan

TheSuperconductingSuperCollider Laboratoryis operatedby theUniversitiesResearchAssociation,Inc., for theUnitedStatesDepartmentof EnergyunderContractNumberDEACO2-89ER40486.

This DocumentwasprintedAugust 11, 1993; It was createdJuly 9,1993andwaslastmodified August11,1993.

It contains32 Pages.

RevisionLog:

Revisedby Date

Doug Murray Aug 1993

>

a>

1

Cl

-2-


1. Introduction

This SoftwareDevelopmentPlan SDP describesthe softwaredevelopmentprocessfor ControlSystemSoftwareat the SuperconductingSuperCollider LaboratorySSCL.

The Control SystemSoftwarewill be developedusing EPICS,theExperimentalPhysicsand Industrial Control System,whichcontainsa setof software"tools" for l3uilding control systems.

Accordingly, two separatedevelopmenteffortswill takeplace; oneto extendEPICS, ensuringthat it canbekeptgenericandusefulforany control systemdevelopment,andsecondto developapplications using EPICS, whichwill be specific to the 55C1. Developerswill build a control systemapplicationusing EPICS in much thesamewaythatanaccountantbuildsan"application"using aspreadsheetprogram.

1.1. ProjectOverview

This projectincludessoftwareto controlequipmentin the LinearAcceleratorLINAC, the Low, Medium and High EnergyBoostersJIB, MED andFlED,the Collider itself, andvarioustestbeams.

The projectcanbe considered as havingtwo parts,asmentionedabove. Specificationdocumentsareorganizedinto a specificationtree,overwhich thesetwo developmenteffortsaremapped.

The following figure showsthe organizationof documentsat Level3B andLevel 4. For our purposes,Level 3D documentsdescribeaglobal control system,having featurescommonto all acceleratorcontrol systemsEPICS; this documentrefers to the highlightedareas. Control systemsat Level 4 deal with problemswhich arespecificto aparticularacceleratortheapplications,or with changesor extensionsto genericsystemsoftware.

1. The termapplicationwill hereafterrefer to theSSCspedficsoftwaredeveloped usingEpics. This includesmany aspecisof a specificdevelopment,including control or monitoring algorithms, sequencesto accommodatedifferentmodesof operation, andthedisplayscreensthroughwhich operators interactwith them.

Level3b

Level 4

>

a

aC-

Figure 1. SpecificationLevels for SSCContrnl Systems

CI

-3- Introduction


Level 5 not shown dealswith specific componentswithin eachsubsystem.

Additional SDPdocumentsmaybewrittenastheprojectprogresses.Such documentswould addresssituationswhich areuniqueto aparticularacceleratoror subsystem,which arenot addressedin thisdocument. Additional pianswould referbackto this documentforinformation commonto all developmentefforts.

The res4ewprocessfor Control Systemsoftwarein generalisdescribedunderMonitoring and Controlling the DevelopmentProcesson page15.

1.1.1. The EPICSSystem

EPICSwasdevelopedatLos AlamosandArgonneNationalLaboratories2,and was intendedfor useas a tool set to build ControlSystems.Sinceit alreadyexists,our goal involves extendingEPICSto meetour needs,and enhancingit, making it easierto developcontrolsystemapplications.Theschedulefor thiswork is describedunderWork Packages,ScheduleandBudgeton page30, andis insomepart dependentupon theschedulefor applicationdevelopment.

Requirementsfor thesetoolsaredocumentedin theGlobalAccelerator Control SystemRequirementsdocument,listed underReferenceMaterialson page8.

EPICSwas designedto addressseveralrequirementswhich arecommonto acceleratorcontrol systems. A morecompletedescription of EPICScanbefound in "ExperimentalPhysicsandIndustrialControl SystemEPICSTechnicalNote", listedunderReferenceMaterialson page8.

1.1.2. SSCSvec’ii c 44pplications

Applications arebuilt using tools which EPICSprovides. Ideally,

a thesetools shouldbe useful to technicians,engineersand non-programmersin general,andshouldnot requirean intimateknowl

>.‘ edgeof EPICS. Thetools arethemselvesconsideredto be deliverablesfrom EPICSdevelopment,andaredescribedunderSystemDeliverableson page5.

At leasttwo broadcategoriesof applicationscanbeidentified:

1. Operatorapplications,usedin a controlroomsetting,whichpresentsasystemor componentat a high level;

2. ProducedunderU.S.GovernmentContractsW-740S-ENG-36at Los Alamosand W-31-109-ENG-38at Argonne.

Introduction -4 -


2. Engineeringapplicationsusedin a Laboratoryenvironment, or in the field duringperiodsof maintenance.Theyoffer accessto diagnosticfeaturesof the systemandallowmoreelaboratetesting.

In additionto EPICS tools, someapplicationdeveloperswill makeuseof otherpiecesof softwareastheprojectprogresses.This mightinclude,but is not limited to, softwareavailablefor the X WindowSystem,availablecommerciallyor freely distributed,as well asdevelopmentaids,suchaslanguagesensitiveeditors,debuggersandvariousotherCASE tools.TheVxWorks real-timekernel3is theplatform uponwhich certainpartsof applicationswill operate.

Detailsof applicationscheduleswill be presentedin thesubsequentsystemspedficationdocuments,asacceleratorsandsubsystemsaredesigned.

1.2. ProjectDeliverables

Deliverablesalsofall into oneof two categories,systemor application. Systemdeliverablesincludessoftwarerequiredto developapplications. Application deliverablesrefer to applicationsdevelopedfor spedficacceleratorsor subsystems.

1.2.1. SystemDeliverables

Severaltools in the EPICSsystemshallbe deliveredto applicationdevelopersat theoutsetof theproject. Thesetoolscurrently existandarein use.

First, thereexist toolswhichdo not requirethedeveloperto developcodein the traditional programmingsense. Referto ReferenceMaterialson page8 for furtherdocumentation:

dct theDatabaseConfigurationTool is usedto definemostof thefunctionality of theapplication,by allowing the developerto describe >"both dataand processingin termsof recordsin* a simpledatabase.Furtherfunctionalitycanbe addedwith snc,CA andtheC programminglanguage,asdetailedbelow, a

edd a tool usedto build thedisplayscreens,throughwhichusersinteractwith theacceleratoror subsystem.It is an editor in the sensethatdeveloperscan createor modify theoperator’sview of the equipment. The developerselectsgraphicitemsfrom apalettewhich arethenplacedat variouslocationson the screen,which might includerepresentationsof meters,gaugesor dials which would be familiarto theusercommunity.

dm a displaymanagerprogram,which displaysthe screensbuilt withedd,andensuresthatscreenitemsareconnectedto actualmeasurementsor controlsvaluesin thefield.

3. VxWorks is a trademark of Wind RiverSystems,Inc.

-5 - Introduction


alh a tool for display, confirmation,acknowledgmentandrecordingofalarmconditions,asconfiguredby thedeveloperof theapplication.

ar theArchiver is usedto recordmeasurementsat variousintervals,asconfiguredby thedeveloperof theapplication.This tool is only usedfor capturingandstoring data,soils namemight bemisleading.

air atool to reporton datawhichhasbeenrecordedby thearchiver.Thedevelopercanconfigurethetool to displaydatain a varietyof graphical formats.

Other tools will be delivered to applicationdevelopers,whichrequirecoding in the moretraditionalsenseof programming:

snc is theStateNotationCompilerwhichallowsdevelopersto programstatetransitionswhicharerequiredin theirapplications.Oftenusedfor implementingvariousmodesof equipmentor systems,this toolunderstandsSNL, a statenotationlanguagewhich caninteractwithsimpledatabaserecordsdevelopedwith dctseeabove.

CA refers to ChannelAccess,which is a communicationsmechanismwithin EPICS. Programmersusingthe C programminglanguagecanmakeuseof the channelaccesssubroutinelibrary to retrieveor setvaluesin theacceleratororsubsystem.This is typicallyusedonly forspecializedapplicationswhich cannotbe handledby thegenerictoolsedd,dm,or snc.

Other tools will be developedfor the applicationsdeveloper,topresentEPICSasamoreintegratedenvironmentAlthough notnitical, thesetoolsaddressself-imposedrequirements4concerningeaseof use, automaticdocumentgenerationdesigndrawings,forinstanceandconfigurationmanagement.Thesetools include,butarenotlimited to:

fbed a functionblockeditor,whichprovidesthedeveloperwith a graphictool with which to visualizetheprocessingrequiredin their applica

>1

lion. It can takethe placeof dct.

statem astatemachineeditor,whichprovidesthedeveloperwith agraphictool with whichto visualizethe statesandtransitionsbetweenthem,

a requiredin their applications. It can takethe placeof sncandtheSNL which it understands.

alconf a configurationtool for the alarmhandlerwhichallows a developero to determinegraphicallyhow alarmswill be handledif acknowl3 edgmentis requiredfor certainalarms,etc..

arconf a configurationtool for thearchivingmechanism,which allows thedeveloperto specifydetailsof datacaptureandrecording.

4. Refer to ManagementObjectives andPriorities on page12 for more information.

Introduction -6 -

* SoftwareDevelopmentPlan

arview a graphictool throughwhich previouslyacquiredmeasurementscan be viewed. While very similar to arr, this tool understandsamoreelaboratedatamanagementschemeusing a commercialdatabase. The developerwould make useof a configurationmodetorelievetheoperatorof understandingdetails.

epics a graphicwindow basedprogramthroughwhich thedevelopergainsaccessto the EPICStoolsandtheirdevelopmentenvironment.It is alsousedto startapplications,andnavigatethroughapplicationspecificdirectorieson controlsystemcomputers.

Enhancementsto EPICSwill beneeded.Theseinclude:

CA changingtheChannelAccessmechanismwill be requiredfor EPICSto accommodatea ControlSystemof thescalerequiredfor the SSC.In fact, the communicationschemewhich EPICSuseswill requireasubstantialchangeof design.

alh changingthe alarmhandlingmechanismso that a daemonis constantlyrunning,waiting for alarmconditionsto change.

datahandling the mechanismthroughwhich EPICS savesmeasureddata,andthroughwhich it configuresfront-endcomputersmustbe extendedto accommodatetheconfigurationmanagementstrategyin the lattercase

1.2.2. ApplicationDeliverables

Applicationsfor eachacceleratoror subsystemareconsidereddeliverables,for whichdescriptionsandscheduleswill bedocumentedinsubsequentspecificationdocumentsrefer to ProjectOverviewonpage3.

1.3. Evolution of the Software DevelopmentPlan

The completeplan for developingsoftwareultimatelyincludesthisso calledLevel 3B documentandany acceleratorspecificSDPssocalled Level 4; refer to Project Overview on page3 which might beproducedin the future. aWith this in mind, anyadditional Level 4 SDP documentswould be >developedaseachsetof applicationsis specified. With respecttoEPICSitself, our developmentstrategymaychangeasexperienceis 0gainedwith applicationdevelopment.This isconsidereda minimal Urisk, consideringthatthecoreof EPICSalreadyexists. Referto Risk E-MManagementon page 13.

Suggestionsfor changesto thisplanshallbe submittedto the Soft-wareGroupLeaderSGL,whois responsiblefor updatesanddistri-bution of theSDPto theEPICSsoftwareengineers,andapplication

CJ

- 7 - Introduction


developers.Suggestionsfor changesto subsequentLevel 4 SDPsshall be submittedto the applicationengineerresponsiblefor thecorrespondingproject.

1.4. ReferenceMaterials

The foilowing documentsarerelatedto thisSDP, andareavailablefrom thedocumentationmanagerin theSSC ControlsDepartment:

* EngineeringManagementPlanEMP SSCDocumentEl0-000029

* GlobalAcceleratorControlSystemRequirementsGACS* SoftwareRequirementsSpecificationsSRS

* SoftwareTestPlansSTP* SoftwareStyleManual

* ExperimentalPhysicsandIndustrialControlSystemEPICSTechnicalNoteAT-8:SYS:89-005

* EPICSDC User’sGuideApril 4, 1991* GettingStartedwith EPICSDCT April 1991* EPICSIOC AddressSpecificationTechnicalNoteAT-8:IOC:88-02* EPICSState Notation Language and Run-time SequencerUser’s

GuideVersion 1.7 ganuary7, 1992

* ObjectOrientedRequirementsAnalysisandLogical Design,DonaldG.lRresmith

* SCCSUser’sGuide

* MakeUser’sGuide

1.5. Definitionsand Acronyms

ANL ArgonneNationalLaboratory- - ARR AcceleratorReadinessReview

AT!’ AcceptanceTestPlan

z ATPR AcceptanceTestPlanReview

0 CA Configuration AdministratorCDR Critical DesignReview

CM ConfigurationManagement

0 CSPM ControlSystemProgrammingManualo EM!’ EngineeringManagementPlan

EMU EmittanceMeasurementUnitct.1 GACS Global AcceleratorControl System

IOC InputOutputControllerLANL Los AlamosNationalLaboratory

LBL LawrenceBerkeleyLaboratoryMPO MemorandumPurchaseOrder

OPI OperatorInterfacePDR PreliminaryDesignReview

Introduction -8-


PDRR PreliminaryDesignRequirementsReviewPMO Project ManagementOffice

QA Quality AssuranceRE Radio Frequency

SAR SafetyAnalysisReportSCCS Source CodeControlSystemSDP Software DevelopmentPlanSGL Software Group LeaderSMR SoftwareModificationRequestSOW Statement Of Work

SR Software RepositorySRS Software RequirementsSpecificationSSC SuperconductingSuper CoffiderSSR Software SpecificationReview

2. Project Organization

The AcceleratorSystemsDivision consistsof severalDepartmentsinvolved in theControl Systemdevelopmenteffort. This involvement ranges from developmentof devicespecific software withinthe system,to specific engineering applications seeSSCSpecificApplicationson page4.

2.1. ProcessModel

The processby whichdevelopmentwill proceedis dictatedby twofactors, specificallyhow requirements for applications aregeneratedandmet,andthenhow requirementsfor EPICS aregeneratedandmet.

EPICS already exists,and was designedto meet commonrequirements for generic control systems,gainedthroughyearsof experiencewith differentacceleratorsandprocesscontrolsystemsreferto >EPICS Technical Note, listed under ReferenceMaterials on page8.EPICSshallchangeor be extendedif the tools it provides arenot ‘Cadequate for developingthe required applications refer to Risk 0Managementon page 13. To someextent, further requirements

>..

shall begeneratedfrom application developersas they learn what is Q..required for their applications. Test plans and quality assurance

Q

issuesfor EPICS will be addressedseparatelyfrom thoseof the appli- Ucations. Refer to Monitoring and Controlling the DevelopmentProcesson page 15 for more information.

Applications: The Project ManagementOffice PMO will be the primary sourceof requirements for the acceleratorsand subsystems.Requirementsfor control systemapplications will follow from these, and thedesignand implementationof theseapplications will be the responsibility of specific developmentteams,asmentionedunder Organizational Structureon page 10.

-9 - Project Organization


Applicationsshallbedevelopedby theseteams,accordingto guidelinesdiscussedunderthesectionApplicationDevelopmentAreaonpage23. Reviewsshallbe held asworkprogresses;refer to Application SoftwareReviewson page15 for moreinformation.

Testingwill beperformedon componentsasdevelopmentproceeds,and is outlinedunderSoftwareTestPlanson page26.

Whensuccessfullytested,theapplication,includingdisplayscreens,processingdatabaserecordsand any othercomponentsshall beregisteredinto theConfigurationManagementmechanism,asoutlinedunderConfigurationManagementon page27. Subsequentmodificationor extensionoftheapplicationsrequireaSystemModificationRequest.

Systems: Changesor enhancementsto EPICSshall be solicitedthroughaSystem Modification Request,as described under Configuration Management on page 27. Once approved, the change will beimplemented,with appropriate design,andtested.

Figure 2. The Control SystemSoftwareDevelopmentProcess

>1 Different groups participate in the DevelopmentProcess. TheApplication Developersand EPICS Programmers, as depicted inFigure 3., correspondto theApplications and SystemsGroups,respectively,asshownin Figure4.

SystemsEngineeringandQuality AssuranceGroups within the SSC

0shallbe involvedin requirementsanalysisandreviewsastheproject

o proceeds.Two separatesetsof requirementsand reviews,correspondingto Applications andSystemsworlç areshownin Figure3.

2.2. Organizational. Structure

The Software Group is responsiblefor the EPICS systemsoftwareand manyof the applications. This group is containedwithin theControls Department,andis shown in Figure 4. Tasksare assignedto teamsunderSystemsorApplications.

1

Project Organization -10-


Project Management

I ApplicationDevelopers fr-Y’ JEPICS Projammers I

Figure 3. Participantsin the SoftwareDevelopmentProcess.

Figure4. Organizationfor SoftwareDevelopmentwithin theControlsDepartment.

The ControlsDepartmentis responsiblefor integrating the efforts ofother Departments within the Accelerator SystemsDivision, asshownin Figure 5. TheSystemsEngineeringandQualityAssurancefunctionsareperformedby separategroupswithin ASD. Anotherseparategroupwithin ASD is responsiblefor administrationofdevelopmentcomputers and software, to the specificationsof thedevelopers.

The ControlsDepartmentis alsoresponsiblefor integrationeffortsfrom otherDivisionswithin theSSC,including the Machine Simulation Group andvariousdetectorgroups. Note that the GlobalMachine Safety SystemsGroup within ASD is responsiblefor acompletelyseparateanddistinctsystem,butthestateof thatsystemmustbe availableto theControl Systemfor display andinterlockpurposes.

u-i

RequirementsandReviews

SystemsEngineeringK

1 QualityAssurance]

Requirementsand Reviews

Software

Database

jSystems I Applicj

I IIToolsi lothersi

CommunicationsI [Real-time I

ProcessControl

BeamInstrumentation

0

03

-11- Project Organization


I AcceleratorSystems

BeamInstrumentation Controls Cryogenics

Eneeth1 r Global MachineSafety

FigureS. Organization of theAccelerarSystemsDivision.

Softwareefforts are alsoengagedfrom other Laboratories,throughmemorandumpurchaseorders MPO. Initiation of suchagreements, formal statementsof work SOW and monthly progressreportingshallbecarriedout accordingto existingSSCpolides.

3. ManagerialProcess

The Control Systemfor the SSC representsa major, complex software project. Prioritieshave been established,andrisks have beenidentified.

3.1. ManagementObjectivesandPriorities

The ControlSystemSoftwareGroup mustbe bothsystemdevelopers with a research and systemdesignattitude, but alsoaserviceorientedorganization,whichmustensurethat accelerator operatorshaveall of theapplicationsavailablefor controlling theSSC.

Given theseobjectives,priority shall be given to thoseaspectsofdevelopmentrelatedto servingtheacceleratoroperationsstaff. Thisincludesreliablesoftwarefor acceleratorspecificfunctions,accurateand availabledocumentationandwell definedproceduresforproblemresolution.

Beyondthat,highestpriority shallbe given to thosedevelopmenteffortswhicharedirectly tied to acceleratorschedules.Specifically,applicationsdevelopedwith EPICS tools takepriority over enhancementsto EPICSitself, unlessthoseenhancementsaredeemedcriticalto theapplicationoperationby theSGL.

I MechanicalEngineering I RE

0

3

u-i

ManagerialProcess -12-


3.2. RiskManagement

Applications: Developmentof applicationswill haverisks,baseduponissuesrelating to the acceleratoror subsystemin which they will be used. ASafetyAnalysisReportSAR, preparedfor eachacceleratorsystemor subsystem,shall identify areasof risk for variousapplications.

Test plansshall be outlined in AcceptanceTest Plan ReviewsATPR, which will addressall of theproblemsassociatedwith testing applicationsfor specificacceleratorsystems. Referto SoftwareTestAreaon page25 for moreinformation.

Schedulesfor theseapplicationswill containcritical path items,whichwill bedeterminedandpresentedaspartof regularControlsGroup reviews.Work-aroundalternativeswill be determinedandscheduledto be presentedasbackupplans.

It is expectedthattherisksinherentin applicationsdevelopmentwifibe morenumerousandmorecritical thanrisks from the EPICSsoftware; EPICS hasbeentestedin severaloften very diversesituations, andthe majority of our developmenteffort lies in the useofEPICSto build applications. Other riskscan,nonethelessbeidentified andassociatedwith usingEPICS.

Configuration: ProperConfigurationManagementCM is essentialto thesuccessofthis project; hundredsof peoplecouldpotentiallyhaveaccesstoapplicationsourcefiles display templates,configurationdatabasetemplates,etc.,andto theEPICSsourcecodeaswell. This issuerepresentsgreatrisk if theimplementationis not adheredto; theimplementationis describedunderConfigurationManagementon page27.

EPICSproblems: EPICS was developedwith very generalrequirementsin mind,basedprimarily on previousexperienceof theengineers.Thereis arisk thattheirworkwill not scaleto meettheneedsof theSSC,orthatapplicationdevelopersmay haverequirementswhich theexistingEPICStools cannotmeet.

The physicaldistancesbetweencomponentsin theSSC, andtheirnumberspresentproblemswhichareunique. Thecommunications 0systemmustaccommodatemuchgreateramountsof dataandlarger

>..distancesthandid previoussystems.Accordingly, EPICSmustbechangedto makeeffectiveuseofthatsystem.The riskspresentedby Qsucha changeareminimized however,becauseof adherenceto ucommunicationsstandardsin hardwareand software; ideally,changesto a layerof communicationssoftwareshouldbe transparentto EPICS,sothatno changeswill berequired. If changesto the ‘cr4systemareindeedrequired,they will be localizedandminimal.

Changesto EPICS: Enhancementsto EPICSwffl berequired,andrisks aregreaterthanthoseassociatedwith othersoftwareprojects. It is oftenmuchmoredifficult to modify codedevelopedby otherengineers,usingdiffer-entdevelopmentplansandstyleguidelines,thanto developthesys

-13 - Managerial Process


tern in a consistentway from thebeginning. A strongconfigurationmanagementandquality assuranceschemeis essentialto minimizetheserisks.

EPICScollaboration: Several Laboratories in the UnitedStatesareworking togethertodevelopextensionsto EPICS. This includesLos Alamos NationalLaboratoryLANL, ArgonneNationalLaboratoryANL, LawrenceBerkeleyLaboratories,andtheSSC. Benefits from thiscollaborationaregreat,butthereis a risk thatchangesto existingsoftware,or eventhe directionof EPICSin thefuture,may not meetongoingrequirementsattheSSC. We havetheoptionof leavingthecollaborationatany time, shouldoursituationwarrantit.

EPICSdependencies:EPICSimposescertainrestrictionson thetypesof hardwarewhichcanbe used. Currently, computers from SUN Microsystemsmust beused,with their versionof the UNIX operatingsystem. VxWorks isrequiredasa real-timekernel, which imposesfurther restrictionsupon processorarchitecturesandtypes. Thereis a risk that futuredevelopmentwill be dependentupon actionsof thesevendors,andthatadvancesin technologyfrom othervendorswill notbeavailableto us.

Stepsarebeing takento overcometheserisks; planshavebeenproposedto producesoftware,or modify existingsoftware,to makeit POSIX compliant5. We aremaking useof otherstandards,suchasMotif on the X-window systemfor userinterfacedisplaysandgraphics,so that asmany vendors as possiblecanbe considered.

Outdated technologies: Technologyused in all aspectsof developmentare susceptibleto becomingoutdated. There is no risk in beingoutdated,otherthanthe technicalsupportandenhancementsto that technologymightfall off in thefuture. Whileattemptingto developsoftwarebasedonstandards,andpuffing effort into ensuringportability acrossplatforms,it is in our best intereststo considernew technologiesastheybecomeavailable. EPICS was developedusing currently acceptedtools andlanguagessuchas C andyacc for example,butnew developmentscould makeuseof C++ or otherobject orientedtechnologies,which arelikely to be muchmorepopularbettersupported

0 and more widely usedin the future.

SDPChanges: Changesto theSDPwill occurover the lifetime of theproject;we donot associateahigh levelof risk with thesechanges,becauserequire-

0 ments analysisand developmentdetailswill be determinedastheU project proceeds. This SDP documentis the cornerstone of a com

plete developmentplan, and the developmentof accelerator specificapplications will be documentedas their requirements are madelcnown. Refer to Evolution of the SoftwareDevelopmentPlan onpage 7.

5. whendetails of the POSIX standard,includingreal-timeextensions,arewelldefined.


* SoftwareDevelopmentPlan

3.3. Monitoring andControllingthe DevelopmentProcess

The EPICS softwarewill be extendedas applicationdependentrequirementsbecomeknown. The reviewprocessis outlinedbelow.Applicationssoftwarewill be reviewedwhenthe associatedaccelerator or subsystemis reviewed.

3.3.1. Appikrion SoftwareReviews

FormalReviews: Reviewsfor applicationsoftwareshallbe integratedwith reviewsfortheircorrespondingsubsystemsor accelerators,whicharedescribedin the SSC EngineeringManagementPlan EMP. To summarize,they include:

* PreliminaryDesignRequirementsReviewPDRR

* PreliminaryDesignReviewPDR

* Critical DesignReviewCDR* AcceptanceTestPlanReviewATPR* AcceleratorReadinessReviewARR

SystemsEngineeringshallsupportall activitiesassociatedwith theseapplicationsreviews including preparingdocuments,takingminutesandrecordingactionitem assignmentsduringthemeeting.SystemsEngineeringdistributes theminuteswithin ten daysfollowing the meeting,andtracksactionitems.

Componentsof applicationsshallbetestedseparately,to asgreatanextentaspossible.Thereshallnotbeanindependentacceptancetestplan ATP for applicationsoftware,sincethe applicationsaresodoselytied to hardwarecomponents.The ATPs shall testsoftwareand hardwarein an integratedfashion,and ATPRSshall be schedtiled to reviewtheacceptabilityof both,workingtogether.

Certainapplicationsmight be developedwhich aregenericin >..nature,and canbe "copied"6as similar subsystemsor hardware 4componentsareinstalled. Smaller, informal test reviews of these Zspecificapplicationsmaybe justified,to ensurethattheywill indeed 0besuitablefor similarsubsystems.

>..l

Informal Reviews: The SoftwareGroup will alsohold regularinformal reviews for alloperatorapplications7. Thesearereferredto as in-processreviews 0IPRs and will be scheduledby the responsibleapplicationsengi- Uneer,on amonthlybasis. Suchreviewsshall deal with oneor moreof the following topics,having informationspecific to that applica- 44

lion, andgleanedfrom theengineeringnotebooksreferto SoftwareRequirementsSpecificationon page26:

6. the applicationmightbe, moreappropriately,multiply instantiated.7. Reviewswill be heldonly for thoseEngineeringApplicationswhich will beusedin a Control Room. Referto SSCSpecificApplicationson page4.

- 15 - Managerial Process


* OperatorInteractions:a review of operator’sdisplayscreens,andhow theoperatorsinteractwith them.

* HardwareChannels:a review of known channelswhichcome from, or go to, hardwaremodules,and a list of allknownmodules.

* Data andProcessing:a review of EPICSdatabaserecords,how they arelinked andthe processvariablenames.

* ModesandTransitions:a reviewof systemstatesandtransitionsusingSNL.

* ComponentTests:a reviewof majortestsperformedonthesoftware,both independentof, and integratedwith, hardwarecomponents.

Theseinformalreviewswill providethebasisfor theformal reviewsmentionedabove,andshallbeattendedby applicationsdevelopers,membersof the quality assuranceorganizationand systemengineers. Representativesfrom PMO will be askedto attend,sothatchangerequestscanbe approved.

Weekly statusreportsfrom applicationdevelopmentteamswifi besubmittedto theSGL, who will makethem publiclyaccessible.

3.3.2. System Software Reviews

Reviewof EPICS relatedwork will be lessfrequentbecausethesystemalreadyexists. Futuredevelopments,including enhancementsto existingcode,shall bereviewedaccordingto the formatdescribedin ObjectOrientedRequirementsAnalysisand Logical Design:A SoftwareEngineeringApproach.8 Specifically,Chapter9 of thatbookis entitled DevelopmentCyclesandMajor Reviews,anddescribeshow reviewscanbestaccommodatemoderndevelopmentmethodologies. It makesreferenceto DOD-STD-2167A.

Requirementsfor enhancementsto or extensionsof EPICS oftenoriginatewith applicationdevelopers,but may also be generatedfrom within the teamof programmerswho are responsibleformakingthosechanges.In anycase,theSGL maydecideif aSoftwareSpecificationReviewSSRis warranted.

Onereasonfor insistingon requirementsbeforeany workbegins,isto ensurethatall engineersunderstandthatextrafunctionality is notwanted. Referredto as creepingfunctionality, engineersoftenimplement the requiredfeaturesand decidethat additional featuresareeasilyadded.

5. Donald G. Firesmith,Object Oriented RequirementsAnalysis and Logical Design: A SoftwareEngineeringApproach,JohnWiley & Sons, Inc., 1993. ISBN 0-471-57807-X.



The extent to which requirementsareuncierstoodanddocumentedbeforeanywork beginsshall bedeterminedby theSGL. If requirementsare completelyunderstoodbeforehand,additionalfunctionality orotherfeaturesshallbedocumentedandsubmittedto theSGLfor approval.

In anycase,regularll’Rs will beheld,andscheduledby the responsible engineerat intervalsno longer than30 working dayswithoutapprovalof theSCL.

Weekly statusreports from systemdevelopmentteamswill besubmittedto theSGL, who will makethem publicly accessible.

3.4. StaffingPlan

Eachof theteamsin theSoftwareGroup,depictedin Figure4., shallhavebetween3 and7 members,including a TeamLeader, for theduration of the project. Additional applicationteamsmay berequiredasthe projectcontinues. Additional teamsof technicianswill be requiredfor systemadministrationandmaintenancefunctions, asacceleratorsbecomeoperational.

4. TechnicalProcess

Requirementsfor applicationswill originateprimarily from withinthe PMO.

Requirementsfor thetoolsusedto build thoseapplicationswill comefrom applicationdevelopersandmembersof theSoftwareGroup.

An overviewof theproject organizationand how it relatesto thisprocess,aswell astheDevelopmentProcessitself is containedin theSectionentitledProcessModelon page9.

4.1. Methods,Tools andTechniques

Developmentof applicationssoftware,aswell asenhancementsor Zextensionsto EPICS software,shall take placeon workstations 0runningthe UNIX operatingsystem,specificallycomputersfrom >..SUN Microsystemsasdictatedby theEPICSsystem. This SDPwill Q..changeasnewprocessortypesaremadeusable.9 0Singleboardcomputers1°C computersin theEPICScontext,shallincludeany processorsupportedby the VxWorks real-timekernel,andauthorizedby theSoftwareGroupLeaderSGL.

99. Referto RisicManagementon page13.

- 17- TechnicalProcess


4.1.1. DevelopmentTools

The toolsusedfor applicationsdevelopmentincludeall of thedeliverableswhich EPICSwifi provide; refer to the list underSystemDeliverableson page5. Additional tools might be identifiedastextualeditorsor documentationaids,describedbelow.

Enhancementsto theEPICSsystemitself will bemadewith a varietyof tools,dependenton what was usedinitially, to maintainconsistency,but alsoon contemporarystandardsauthorizedby the SGL.

Currently, thesetools includecompilersanddebuggersfor the "C"and"C++" programminglanguage,theyacccompilercompiler andlex a tool for lexical analysisof input tokensto compilers.Assemblylanguagewill beusedonly with approvalof theSGL,andthenonly on real-timesystems.

Specificeditors will not be requiredfor coding, althoughallprogrammerscurrentlyuse "vi" or "emacs"or tools baseduponthem. FrameMakershallbeusedto producedocumentationreferto SoftwareDocumentationon page25,andXmosaicshallbeusedto assistin on-line documentation.Autoplan shall be usedfortrackingschedules.s

Documentationfor thissoftwareis availablefrom theSGL.

41.2. Software.Repositorg

The softwarerepositorySR containsthe softwarematerialsincluding sourcecode,objectcodeandothersoftwaredocumentation. The SR providestheproject’sprimary meansfor exercisingconfigurationcontrolover thesoftwareand relateddocumentationduringdevelopmentandrelease,asdescribedunderConfigurationManagementon page27.

> The currentversionsof documentation,sourcecodeandotherfilesarealwaysavailablein therepositoryarea.Developmenttakesplacewhenprogrammersor applicationdeveloperscheckfiles out of thesystemvia theCM mechanism,into theirown developmentareas.

>-i After work is complete,including testing,the files areregisteredbackinto thehierarchyby theConfigurationAdministratorCA.

C-

Cs

TechnicalProcess -18-


The SRshallexiston a UNIX file system,andshall beaccessiblefromasinglelocation,asshownin Figure6. This locationshallbespecifiablewith the samepathnameon any developmentcomputer. It isassumedthat the readeris familiar with theconceptsof files anddirectoriesusedin modemcomputersystems.

Figure6. DirectoryStructurefor Control SystemSoftwarein the RepositoryArea.

Within thetopmostcontrol systemdirectory shall exist subdirectories for applicationsand theEPICS software. Separatesubdirectories shall exist for documentationdoc, to allow easy retrieval ofdocuments,andfor schedulesschedule,to allowaccessto theprojectschedulewith respectto controls.

An importantaspectof theUNIX file systemis the ability to have"symbolic links" to a file or directory. This is essentiallyapointerwhich itself appearsasan entryin the file system; usingthem, filesor directoriesmightseemto exist in severallocations,ideally wherepeoplewould expectto find them. Physically,thereis only onecopyof the "target", andit’s actuallocationmight notbeimportant. Thedocumentationsubdirectoryis an example,in that it containssymboliclinks to thedocumentationfiles locatedelsewhere.

This hierarchyshall be writable only by the useraccountnamed"controls",asdescribedunderConfigurationManagementonpage27. Thedocumentationdoc files shallbe accessiblefor readingbyanyotheruseraccount

The SRalsocontainsaseparateintegrationandbuild area,which isa protectedrepositoryof codeandtext files thathavebeenreleasedby thedevelopers,buthasnotbeenintegratedor releasedto theusercommunity. ZAs softwareis releasedinto theSR area,theCA compilesand linkstheminto executablesoftware.Thebuild is thenreleasedto thesoft- >4

waretestareafor testing.

4.1.3. SystemDevelopmentAmt U

Systemsoftwaredevelopmentwill takeplaceunder the loginaccountof individual programmers.Routine login procedures "

requiring a usernameandpasswordprovide accesscontrol to theprogrammer’sown work area.Weekly backupsof all ifies will bemaintainedin orderto preventlossof data.

CS

-19- TechnicalProcess


Each programmershall haveoneor moresubdirectoriesundertheirown computeraccountwith a structuresimilar to that of thesystem’s,asshownin Figure7. EPICSdocumentationrefers to thisarea as a "shadow directory". Programmersshall "checkout" filesfor editingor perusal,then inform theConfigurationAdministratorCA whenwork is doneandtested,andfiles needto be integratedback into the system. For more information, refer to theFigureentitled Layoutof a DevelopmentArea using SCCSon page29.

The SystemDevelopmentarearefersto thishierarchyof directoriesbeneath any given programmer’s account, usually on their owndevelopmentworkstationcomputer. Accordingly, only asubsetofthe systemdirectoriesmay exist thereat any giventime, dependingon the developmentwork taking place. Typically, a programmerwill haveadirectory"skeleton"havinga structuresimilar to that oftheSRarea,butonly thosefiles relatedto his currentworkwill existthere. Many of thosefiles will exist as symboliclinks, since actualcopiesarerequiredonly whenediting is beingperformedon them.

Figure7. SoftwareRepositoryshowingStructureof a SystemDevelopmentArea.

Thesesubdirectorieshavewell definedcontents:

epics/include a directorycontainingall of the "include" files usedby partsof thesoftware.Includefiles containcommondefinitionsusedin differentpiecesof sourcecode,andarenamedwith a trailing ".h" extension.Specifically, include files which must be includedby morethanasingle library or programmustappearhere;all includefiles used

Z only in asingle programor library canbe located in thecorrespond-C ing sourcecodedirectory. Includefiles at this level aretherefore

usedprimarily within EPICSsourcecode.epics/src adirectorycontainingall sourcecodeunderseparatesubdirectories.

UTheconstituentfiles shouldnot existin thisdirectory,but in thesubdirectoriesdescribedbelowit. EachsubdirectoryshallhaveaMake-file, containingrequiredtargets,andthisdirectoryitself will containaMalcefilewhichwill descendto theappropriatesubdirectoriesand"make" eachof themin turn.

Crj



epics/src/lib a directorycontainingsourcecodewhich constitutesa library notshownin Figure9.. Ideally, thedirectorywill be namedfor specificfunctions,so severallibraries might exist in a single project. Forexample,onemight be called "src/libca", referring to a library forEPICSChannelAccess.

epics/src/lib/Test adirectorynot shownin Figure9. whichcontainstestprogramsforlibraries. As an example,srcllibcalTestwould containprogramswhichmakeuseof thechannelaccessroutinesin thechannelaccesslibrary. TheMakefilesfound in thesetestdirectoriesshall link theirprogr’amswith libraries in the directory immediatelyabove,andnotthenormallyinstalledlibrariesfor theproject. Thereshall alsoexista file namedREADME which describesthe informal test procedures.

epics/src/progadirectorycontainingsourcecodefor all EPICSprograms.Thewordog refersto somespecific EPICStool, suchasalh, arr, andothersrefer to SystemDeliverableson page5. Note that include filesendingin ".h" may appearin thesedirectoriesonly if it’s contentsarecompletelylocalized,neverto beusedby othersoftware. Sourcecodefor UNIX andVxWorks platformsshallbe containedin subdirectoriesto this one,whenrequired.

epics/src/prog/TestThis is adirectorynot shownin Figure9. containingtestroutinesfor programscontainedin thedirectoryhrunediatelyaboveit ogin this example. TheTestdirectoryshall includeany files usedfortestingthe correspondingsoftwarein its’ parentdirectory. Forexample,testdatageneratorsmightbeusedfor devicedriver testinguntil hardwareis availableand tested,or EPICSdatabaserecordsandalarmconfigurationfiles might bestoredthere,with which theAlarm Handieralh would be tested. Makefilesshall bepresentineachof theseTest subdirectories,along with a file namedREADMEwhichdescribestheinformal testprocedures.

epics/etc a directorycontainingadministrativeifies, suchasgenericstartupfiles, whichprogramsor librarieswould makeuseof. This includessuchthingsaslistsof trustedusersor hosts,defaultoptionsto useonprogramor library startup,suchas"rc" ifies which takeeffect if nosuchfiles appearin loginor currentdirectories. CIt may alsocontainexecutableifies or links to themfor concernsof >differentarchitectures,usedfor administrativepurposes,or for pro-gramswhichnormalsystemuserswould not typically use. C

epics/lb adirectorycontainingthe library archive,or ".a" ifies. This might Uactuallybe a symbolic link, pointing to a directorycontainingtheappropriatelibrariesfor aparticularmachinearchitecture.

epics/bin a directorycontainingthe executablefiles which developerswould Ztypically use.The directorymight actuallybeasymboliclink, point-ing to a directorycontainingtheappropriateexecutableimagesfor aparticularmachinearchitecture.

i-i

-21 - TechnicalProcess


epics/mana directorycontainingTJNDstylemanualpages,for eachprogramorlibrary routineor setof relatedroutinesin thesrcdirectories.Thesearemeantto beconcisereferencepages,usedby otherprogrammers.

Thereshall be a subdirectoryfor eachsectionof the manualwhichhasbeenwritten for this project; a subdirectorynamedmani willappearfor user-initiatedcommands.Onenamedman3would existfor subroutines,andso forth. Seethe standardUNIX manualsfor amoredetaileddescription,or look under/usr/manon theUNIX systemfor examples.

epics/doc a directory containingany other documentation,with appropriatesuffixesindicatingthetoolused;a ".fm" indicatesa FrameMakerformat document. User manualsfor EPICStools will be here,alongwith requirementsdocumentsandcertainhardwaredocumentation.

Eachsubdirectoryunderthesrc directoryshallbe "self contained",in that it canexist independently.Containingsymboliclinks to files,or actualcopiesof files checkedout for editting,eachof thesesubdirectoriesshallcontaina Makefile, as requiredby the UNIX "make"utility; makeis aprogramwhichunderstandshowtobuild software,basedon thecontentsof the configurationfile Makefile, and isspecific to agiven pieceof software. The Makefile itself is alwaysstoredwith thesourcecodeor documentation,andis kept underversioncontrol, asdescribedunderConfigurationManagementonpage27.

Makefile Setup EachMakefilemustbenamed"Makefile", andmusthavethefollowing targetsandfunctionsdefined10in additionto thetargetsfor eachprogramor library

all causeseachprogramor test programto be compiled,or eachlibrary to be constructed.

install causeseachprogramto becompiled,theninstalledin thebin directory,or eachlibrary to becompiledandconstructed,theninstalledin

>1thelb directory.

clean causesextraneousfiles to be removed,suchascore files, temporaryoutputor debuggingmessagefiles, or testoutputfiles.

deandeancausesall generatedusuallynon-sourcecodeifies to be removed.Itmightalso removesourcecodewhich is generatedby an intermediatestep in thebuild process. This includesall object .0 ifies, lint

U .ln files, archive.a files andexecutable.

lint causeslint to berun on "C" sourcecode.

print causesalisting of sourcecodeto beprinted.

depend causesa new Makefile to be generated,which will accommodatechangesto all "include" files, andrecompileor relink codeaccord-ingly.

10. For more informationon make,refer to the Make User’s Manual,asdisf ibutedwith UNIX.

TechnicalProcess -22 -


4.1.4. Application DevelopmentArea

Developmentof applicationsshall takeplaceunderthelogin accountof individual developers. As with systemprogrammers,routinelogin proceduresrequiring a usernameand passwordprovideaccesscontrolto thedeveloper’sown work area.

Theapplicationdeveloper’sworkareawill besetup in thesamewaya systemprogrammer’sdevelopmentarea,as describedunderSystemDevelopmentAreaon page19.

Oneimportantdifferenceis obviouswhenoneconsidersthenumberof accelerator-specificapplicationsrequiredfor the entireproject.Specifically, a developerwifi not havean empty"skeleton" of theentire applicationhierarchy,in which applicationsaredeveloped.Typically, a developerwill have asingle directorycalled "applications", in whichcurrentprojectsarecontained. Thecompletehierarchywill exist in theSRarea,in a formatshownin Figure8.

controls

Figure8. SoftwareRrnpositoryshowing5ucure of ApplicationDevelopmentArea

Notethat eachsubdirectorybeneaththe applicationslevel shallcontainapplicationssoftwarefor eachaccelerator.The genericsubdirectoryis an exception,andwill be describedbelow. Eachacceleratordirectoryshallhaveasubtreebeneathit, brokendownbysector,thensystemandso forth. In fact, theremight be up to sixlevels in eachsubtree,as eachacceleratoris divided into smallerseparatepieces. Conceptually,everylevel in eachsubtreecould benamed,asshownin Figure9.

At anygivenlevelof thishierarchy,two typesof subdirectoriesshallexist; directoriesfor the next lower level of applications,anddirectoriesfor theapplicationsthemselves,whichbelongatthis level.

As an example,consideran emittancemeasurementunit EMUwhichcontainsascanningwire monitor. A steppingmotor is usedto positionthe wires. Severalapplicationscouldexist for this EMU.

At thelowestlevel of detail,anapplicationcould existwhichallowsa technicianto test all aspectsof thesteppingmotor asan individualpieceof equipment.The files usedin thisapplicationwould exist atthe componentlevel of the hierarchy,with a separatesubdirectorylabelleddoc, containingall of therelevantdocumentation.

lINAC Q 5 Q uider jest Beani jeneric

>

0

0U

Cr

- 23 - TechnicalProcess


Accelerator, a

Sectors .

Systems a

Subsystems a

Devices a

Components a

Figure9. ApplicationSoftware Levelsas theyappearin the SoftwareRepository

Anotherapplicationcould exist at thedirectoryabove it, whichallows integrationof themotor with otherpiecesof equipmentwithin the EMU. Such an applicationwould allow an operatortointeractwith theEMU asasingledevice,andmightnot allow accessto themotordirectly. For instance,a start buttonwould sendthemotors throughsomepre-definedpaces,transparentto theoperator. Again, a subdirectorytitled doc would containassociatedinformationaboutthatapplication.

At eachhigherlevel, applicationswould performmoregeneralfunctions,suchaschangesto modesof asubsystem,or even"turn on" anacceleratorto producebeamwith certaincharacteristics.

One importantaspectto this structureis thatapplications,or justpiecesof them,canbereusedasequipmentis addedto theaccelerators. This might meancopyingexisting applicationfiles into newsubdirectoriesasequipmentis added. Ideally, this would be donewith a mechanismlike symboliclinks, so thatbug fixes or enhancementswould bedonein a singlelocation,andwould beeffectiveforall equipmentofthesametype,regardlessof it’s subdirectory.Copying thefiles outrightmuststill be anoption,sinceit is likely that certain specific piecesof equipmentmight haveslightly differentapplicationsfrom the othersof that type. In anycase,a repositoryshallexist for all genericcomponentapplications,so thatdeveloperscansimply copyor link files to start theirwork. This repositoryiscalledgeneric,andis locatedimmediatelybeneaththeapplicationsdirectory,on thesamelevel asacceleratorapplications,asshowninFigure8.

Sincethisstructureexistsbelowthe SoftwareRepository,it is underCM control, as describedunderConfigurationManagementonpage27. Application developerswould build their developmentareabasedon thisdirectorystructure.

eachlevel of applicationswill alsocontaina "doe

subdirectory...

Multiple Instances

TechnicalProcess - 24 -


4.1.5. SoftwareThst Area

Thereshall be separatetest areasfor EPICS systemsoftwareandapplications.

ApplicationTests: The first kind of testing for applicationsinvolves basiccomponenttesting. This shall beperformedfrom within the developmentareaof the developer’scomputeraccount,asdescribedunderApplication DevelopmentArea on page23. Acceleratorspecifichardwaremodules associatedwith eachstepof theapplicationshall be availablein a laboratoryarea,in which thedevelopershallhaveaccesstotheir computeraccountandall requiredifies. Such testingshall becarriedout by thedeveloper.

Furthertestingof applicationsshallbe performedin a separateTestStandarea,whichpresentsanenvironmentcloserto thatof anoperationalcontrolsystemcomputer. The developer’sown accounttheapplicationdevelopmentareashall not be accessible;suchtestingshallbe performedafter thecomponenttestingmentionedabove,with accessto thesameacceleratorspecifichardwaremodules. Thistestingis performedby someoneother thanthe developer,suchasamemberof theQuality Assuranceorganization.

Detailsof both proceduresshallbe outlined in theAcceptanceTestPlanfor the correspondingsystemor subsystem.

SystemTests: Changesor enhancementsto EPICSshallbe testedin the develop-merit area,within thedeveloper’sown workingaccount.A standardsetof testapplicationsshallbeused,basedonthepartofthesystemwhich was changed. The programmershall performthispreliminary testindependently.

Furthertestingshall be carried out by someoneother than theprogrammer,in a separateteststandarea. A suiteof applicationswhichtest all aspectsof theEPICSsoftwareshallbeusedin the test.,whichshouldbeattendedby a memberof theQA organization. At >-no time shall applicationtestsbe performedconcurrentlywith thesystemtests,using thesamesystemsoftware; the teststandareashall have thesystemdevelopmentareadirectly accessibleto it, Qensuringthatany applicationstestingis completelyseparate.

4.2. SoftwareDocumentation oU

A User’sManualshallexist for eachpieceof softwareaccessibleto auser; basically,anyprogramwhich displays information to, oracceptsinput from, apersonshallbedocumentedasto it’s use.

A Programmer’sManualshall exist for all librarieswhich areaccessibleto programmers;eachsubroutine,functionor methodshallbedescribedaccordingto the format of UNIX programmer’smanualpages.



4.2.1. SoftwareRequirementsSpecification

Requirementsfor systemsandsubsystemsat Level 3B and Level 4refer to Figure1. shallbe documentedin SoftwareRequirementSpecificationsSRS asoutlinedin theEngineeringManagementPlan.

Softwareat Level 5 shall haveanSRS and simpledesigndocumentcombinedin anEngineeringNotebook,whichshallbeproducedbyeachdeveloperasworkproceeds.Thenotebookitself will beadocumentconsistingof all of the constituentnotebooksfrom all of thedevelopers,gatheredat regularintervalsaswork proceeds.

Notebooksshall exist ascomputerifies, storedin a format selectedby thedeveloperascii or FrameMaker,for example,andshalladhereasmuchaspossibleto thefollowing outline:

1. GeneralDescription2. Requirements

2.1. Functional2.1.1. Inputs2.1.2. Processing2.1.3. Outputs

2.2. Performance2.3. Constraints

3. Analysis3.1. Designoptions3.2. RiskAssessment

4. Design4.1. Computertargets4.2. GrafsetCharts4.3. RecordLayouts4.4. CustomCodeLayouts

5. lCD5.1. DataDictionary

6. Test Plans>-l 7. Notes

Z Eachdeveloper’snotebookshallbe consideredduring theinformal

a reviewsfor that applicationasdescribedunderApplication Software Reviewson page15, or during in-processreviews for EPICSwork, asdescribedunderSystemSoftwareReviewson page16.

8 4.2.2. SoftwareTest Plans

Control Systemapplicationsare closelytied to the acceleratorsystemsandcomponentswhichtheycontrolandmonitor. Accordingly, mostof theapplicationstestingshalloccurwithin AcceptanceTestPlans,which alsotesthardwareandothersystemrelatedissues,suchasoperatingmodes.Thesetestplansandtheirproceduresmayreferback to this SDPdocument,making referenceto basictestprocedures.

1



Piecesof applicationscan be testedindependently,but all applications shallgo throughat leasttwo teststages;first, to testtheapplicationasan independentcomponentfrom within the developmentarea,andsecond,to testtheapplicationwhile otherdevelopedapplicationsareworking concurrently. This would occurin a laboratorytest stand,typical of an operatingcontrol systemenvironmentwithout accessto the developmentarea. Testingof systemsoftwarechangeswould be performedin asimilar fashion.

Further descriptionof basictest proceduresis containedin thesectionentitled SoftwareTestAreaon page25.

4.3. ProjectSupportFunctions

Supportfunctions arecarriedout by membersof various teamswithin theControlsSoftwareGroup. A notableexceptionis theadministrationof developmentcomputersfor the developmentteams.

4.3.2. DevelopmentSystemAdministration

Applicationsand EPICSsystemwork shall be performedon engineeringworkstations. Developmenttools andotherutilities shallexiston oneor more centralfile servers,and be accessibleto thedevelopmentcomputers.

Theadministrationof theseworkstationsinclude day-to-daytaskssuchas making backupcopiesof the work, installing new orupgradedsoftware,andmaintainingperipheraldevices,suchasprinters.

Theadministrativefunctionsfor thedevelopmentworkstationsshallbe carriedoutby acomputersupportgroupwithin the SSC,whichis outsideof theControlsDepartment.

>

43.2. ConfigurationManagement

Theconfigurationmanagementprocessshallbe applied to applica- 0tionsandsystemdevelopmentefforts. >.l

For systemsoftware,this includesEPICS softwaresourcecode, asystemlevel technicaldocumentation,utility control ifies Make- Ufiles, for instance,andotherdocumentswhich thedeveloperdeemsrelevantto thesystem.

With respectto applications,CM shall applyto EPICSrecord databasefiles, screenlayout files, SNL files; basicallyall files whichgointo making an applicationwork. Additionally, all technicaldocumentsshallbeunderCM control,aswell asSRS documents,suchastheifies whichconstitutesthedeveloper’snotebook.11. Refer to SoftwareRequirementsSpedficationon page26.



Procedure: Thedevelopmentprocess,whichincludesCM activities, is describedunderProcessModelon page9. Thestructureof theCM controlledareais describedunderSoftwareRepositoryon page18.

The CM processincludesa Configuration AdministratorCA whoshall reportto theSoftwareGroup Leader. The CA shallmaintainalist of programmers,both internal and externalto the SoftwareGroup,who areallowedto checkout copiesof files. Separatelistsmay exist for different files. The commandswhich wifi be usedtoactuallyretrievethecopiesdetermineif thosecopiesaremeantto beeditedor not althoughcopiescanbe checkedout, andthe systemtracksall actions,only theCA cancheckthefiles backinto thesystemandbuild anotherrelease.Layoutof thesefiles is discussedbelow,andin UNIX referencemanuals.

Version Control: Thesoftwareusedto manageversioncontrol shall bebasedon theSourceCodeControl SystemSCCS,asdistributedwith the UNIXoperatingsystem. Both systemsandapplicationsfiles shallcomeunderSCCScontrol.

Whena systemprogrammercreatesa developmentareaseepage19,he is actuallycreatinglinks to the files, so theyappearto existinhisowndevelopmentarea.This structureis describedin moredetailunderSoftwareRepositoryon page18, butbasicallyeachdevelopmentareashallhaveasubdirectoryto it, calledSCCS.

Eachof theSCCSsubdirectoriesis actuallya symboliclink to acorrespondingdirectory entry in a centralEPICSlocation. This allowsadministrativeinformationto bekeptwith themasterversionsof thesoftware,without appearingin the actualproject directories.Thiswill includesuchthingsas a ifie containinga list of developerstowhom electronicmail will be sentafter versionsarechangedandproperly remade.The setupandmaintenanceof theselinks anddirectoriesis doneby a setof programsusedby thedevelopersandprojectadministrators.

An exampleis shownin Figure10. TheAlarm Handleralh sourcecodeappearsto exist in thedevelopmentarea,but is actuallyjust a

0 link to theoriginal unchangeableifie. If thedeveloperneedsto malcechangesto that file, the file is actually checkedout of SCCSandcopiedto the developmentarea,wherechangesaremade.

0 This structurealso allows separatebackupcopiesof the currentU versionsandthemastercodeto bekept,andgivesacommonareafor

statisticsto be collected.It alsoallows a separateareato be main-tamedfor systemdistribution, in caseswhen a setof distributiontapesneedsto bebuilt.

12. Programmersmay existwithin otherDepartmentsat the SSC,but shall stillbe responsiblefor reviewsanddocumentation,asif theywerein the Group.

TechnicalProcess -28 -


Repository Developer

Figure 10. Layoutof a DevelopmentAreausing SCCS

ChangeRequests:

RequestTracking:

This directorystructurealsoallowsdevelopersto maintainaprivateimageof thesourcecode,commondefinition ifies anddocumentation in alocal area.Only ifies whichneedto beeditedwill becopiedout of thecentral projectdirectories,and all otherfiles shall besymbolic links.

This mechanismalso accommodatescompilation of codefordifferent machinearchitectures.Eachsuchdirectory needonlycontainsymbolic links backto theappropriatesourcecode,but theobjectfiles ".0" andresultingexecutableifies wifi exist locally.

The directorylayout for applicationcode is very similar to thesystemsoftwarelayout, althoughtheactualdirectorystructureismore complexbecauseof the numerousapplicationsthat will exist.ThedirectorystructureisoutlinedunderApplicationDevelopmentAreaon page23.

Eachextensionor enhancementto controlsystemsoftware,whetherrelatingto aproblemor anenhancement,shallbedescribedin aSystem Modification Requestform, describingthereasonfor thework,who is requestingit, andotherinformation. A copyof theSMR formappears underthe Appendix SystemModification RequestFormon page30.

Recordsof all SMR forms shallbe keptelectronically,in a database.Requestsshallbe submittedelectronicallyor on paper,but wifi ultimately be enteredinto the database.Softwareshall track theprogressof the request,andensurethat nothing "falls betweenthecracks".

The procedurestarts when the form is submitted. All SMR formsdealingwith issuesrelatingto acceleratorcontrolsshallbesubmittedto the ControlsDepartment.

M files...

0

0U

cf-i



TheSGL shall revieweachrequest,evenif generatedfrom within theControlsDepartment,andassignit to an engineeringteam13. Thereshall be regularweekly reviewsof all outstandingSMR requests.The SMR shall be usedfor hardware,communicationand evenproceduralissuesin thecontrol system,aswell assoftware.

An analystis assignedto the request,andshall suggestworkaroundsolutions to the requestorif warranted,mark a priority for thisproblemor change,basedon their experiencewith thatparticularcomponent,andrecommendthataparticularactionbetaken.

An engineermaythenbeassignedto resolvetheproblem. Theoriginal requestorof thechangeshall be notified whenthe issueshavebeenresolved,andthechangehasbeenmade,or if an analysthasdecidedagainstmakingthemodification. it is quite possiblethattheanalystandengineerassignedto resolvethe issuesare the sameperson.

5. Work Packages,ScheduleandBudget

Schedulesandbudgetdetailswill be donein accordancewith theSSC ProjectManagementCostandScheduleSystem,andthe SSCIntegratedProjectSchedules.

Internalschedulesshallbemaintained,whichcontaindetailsof teamgoals.Most scheduleitemsdealingwith applicationsshallbe tiedtospecific acceleratormilestones.Scheduleitems dealingwith EPICSsystemrelatedwork shallbe tied to theapplicationsmilestoneswhenappropriate.

Projectschedulesshall be maintainedwithin theControlsDepartmentusing Autoplansoftware. Teamleaderswifi have accesstotheirown schedules,andall teamsmemberswill have theabifity toperusethescheduledatabase.

Appendix A SystemModification RequestForm

0 Thefollowing pagesdepictinformationon thefront andbacksideofanSME form attheSSC. Thefront pageis filled outby therequestor,while the backsideis filled outasthe modification is made,or theo problemresolved.

UF.

13. Recall thatthe teammightactuallybe in a differentdepartment.

WorkPackages,Scheduleand Budget -30 -

SSCLaboratory

* ACCELERATOR CONTROL SYSTEM

SYSTEM MODIFICATION REQUEST

Please submit as much information as possible, but do not fii in the other side of this page.

Modification Name: Please amer a concise name to ioentify the modfication

fFlJJedlnbyControlsDept.

is modification related to:C Hardware System

0 Documentation 0 Software fl Uncertain

Type of Change: : improvement

0 Resolution of Problem 0 Enhancementdiscrepancy/ correction new reqiirement

Requestor: Phone: E-mail: DIvision/Department:

System:UNACE

lIES0ColliderD

Location: IMude Sub-system name, Room or area name, rack or console number

Component Name: Coninand, program name, hardware module, inckjde version n4mber acplicabie

Priority: Signature:

DLow DHch QCriticai

Symptoms: Clied all that apply; supply errer measagea and additional ten beio’ause addilonal aheeta. if reqjlredo documentation missing 0 incorrect behavior 0 operation never returns

o documentation wrong 0 unfriendly behavior 0 calculation is wrong0 system crashes Q inconsistent behavior o occurs randomlyo data was lost message unclear or wrong 0 occurs in certain operating modeso data was incorrect 0 display is incorrect 0 system is unresponsive

Impact: Descdbe actMtiea which this proolem affects if not corrected

Describe options or workaround solutions: Is there any way to contirsie urnt the modifIcation is made?

Suggested Action: can you suggest a sokJUon?

SMA VersIon 1.1-08-05-93

C>.

0C-F.

Cr

-31 - WorkPackages,Scheduleand Budget

>1

z0>

0

U

F.

tJj

SSCLaboratoryACCELERATOR CONTROL SYSTEM

SYSTEM MODIFICATION REQUESTPlease fill out other side of this form first

This side of form to be filled out as problem is resolved.

AnalysisSMR Number:P11194 In by Controls Darn.

Analyzed by: Phone: E-mail: Department: Date Received:

Response Priority: Can you suggest additional workarounds:

Resolve IMMEDIATELY 0

Important;putatheadofqueue .. ._____.... -. -

Place in normal queue 0

Low priority: use workaround Q Recommended Action:iowest priority; iast thing to fix Q

Wilt not be resolvedincludereasons .-...--- --- --- ...-..-...--....-----.. .... ..----

gsse.iveanestimate

forthismodificationDo you foresee problems In testing?

...

initial Version: New Version:

ResolutionResolved by: Phone: EmaiI: Department: Date Received:

Briefly describe the action taken:Code change required 0 Documentation change required 0 Duplicate SMR 0 Specification change 0

Design change required 0 No change made give reasons 0 User mistake 0 Not reproducibie 0

SMA Version 1.1-08-05-93

Date Modified: Date Tested: Date Requestor Notified:

WorkPackages,ScheduleandBudget -32 -

APPENDIX

Three Level RequirementsSpecificationsand

Software Notebooks

1,0 Introduction

ASD requires a procedure for documenting software development which willserve the needsof software developers,their managers, and those charged with oversightof the software developmentprocess,in this casethe ASD QA group. The goal here is tosuggesta minimalist approach, having as few documents as possible,attempting toeliminate redundancy, and emphasizingflexibility in the faceofevolving requirements.The brief discussionbelow applies to the software developmentsof theControlsDepartment, but should be applicable to the work of other departments as well.

The approach usedand the nature of the documentsrequired will relate to thenature of the project itself, and to the level of the specificationwith which it is associated.

2.0 Software DeveloumentPlan.

There is a need for only two software developmentplans or one plan with twopartswhich should cover all of the software to be developedin theControls Department:

* The Plan for developmentof application software under EPICS "UsingEPICS", and;

* The Plan for developingmodifications andenhancementsto EPICS "ChangingEPICS".

To first order, all of the softwaredescribed below falls in one of thesetwocategories,and should be able to refer to the appropriate SDP. Of course, if casesarisewhere a different or modified plan is required, such a plan would be developedfor thatproject.

3.0 Level 3. PMO Specifications

In accordancewith the revised specification tree attached,there will be a GlobalAccelerator SystemsSpecification, at Level 3A, anda Global Accelerator ControlSystem Specification at Level 3B. Both of thesespecificationsand their associatedreviewsare the responsibility of PMO. The Controls Department will be consultedwithrespectto the GACS 3B spec. The Controls Department may be askedto contributepresentationsat the Level 3 reviews where appropriate, but will not be required to submitdocumentation other than copiesof transparencies.

The GACS 3B specification will call out the specificationsand reviewsto be heldat Level 4, which are describedbelow.

4.0 Level 4: ASD Specifications

Justasin the caseof the individual MachineSpecificationTrees,controlsystemspecificationsandreviewsat Level 4 are theresponsibilitythe ASD ControlsDepartment. As indicatedon theaccompanyingspecificationtree, therewill be twoglobal reviewsand specificationdocuments,aswell asonespecificationandseriesofreviewsfor eachMachine. The two Level 4 Global specificationsrelateto ProcessControland to BeamControl. Themachinespecificationsand reviewstracedown fromthe MachineLevel 3 specificationsaswell asfrom theGlobalLevel 3B specifications.

4.1 Global Snecifications

TheGlobal Level 4 BeamControlSpecificationwill be madeup of threeparts: aSystemSpecification,a SystemSoftwareSRS anda GlobalApplicationSoftwareSRS.Thesewill be derivedfrom thealreadyexistingdraft specificationpreparedby Rolf andheretoforthoughtof asa 3B specification.

4.1.1 Global SystemSpecification

TheGlobal SystemSpecificationwill includespecificationfor all themajorsystemhardwarecomponents.This includes:

* Front End Systemsand Standards* Global InterfaceDefinition for

- MagnetSystemsRampMagnetsCorrectionMagnetsPulsedMagnetsDC Magnets

- RF Systems- BI systems

BPMsBLMsothers

- Abort System- Timing System

* Communications* CentralandSectorHeadfacilities* ControlRoom* GlobalAithitecture

At this level, only globally estimateddataratesandvolumesshouldbe specified.The main requirementat this level is to build in sufficientflexibility and capacityto meetspecificrequirementsastheygrow and change.

Thereis no softwarecomponentto this specification.

4.1.2 Global Application SoftwareSRS

TheGlobalApplicationSoftwareSRSwill describethoseapplicationswhichapply to all machines,andwhich areor shouldbe inherentto EPICS. Theseinclude:

* RemoteControland Display* Alarm Manager* Saveand Restore* Archiver* Sequencer

We should not write more than we haveto. Forexample,becauseEPICSalreadyimplementsmanyof theseapplications,referencescanbe madeto theEPICSdocumentationwhereappropriateandadequate,with emphasisbeing placedonrequirementsnot met by EPICS,andrequirementsfor necessarychangesor additionstoEPICS. Necessarychangesto any of theseglobal applicationswill be definedassystemsoftwareprojects,listed in this specification,and supportedby a softwarenotebookasdescribedbelow.

4.1.3 GlobalSystemSoftwareSRS

TheGlobal SystemSoftwareSRSwill describeall thosechanges,improvements,etc to EPICSwhich arerequiredto adaptEPICSto theSSCenvironment.This will include,for instance:

* Nameserversoftware,namecachingsoftware* Changesto adaptEPICSto Ti communications* Changesto theAPI, changesto ChannelAccess* MBS MessageBroadcastandtiming supportsoftware

TheGlobal SystemSoftwareSRSwill alsoinclude off line tools suchasfordatabaseediting andgraphicalprogramming.

All of theseprojectsshouldbe identifiedand listed in the Level4 GlobalSystemSoftwareSRS, and eachof them will be supportedby a notebookat Level 5 Seebelow.

4.2 MachineSpecifications

In additionto theGlobal specifications,therewill be a Level 4 specificationforeachMachine: LINAC probablytoo late for this one,LEB, MEB, HEB, Collider, TestBeams. Eachof thesewill includethe relevanttransferline whateverthatmaybe at thetime.

In general,the machinespecificationswill refer to theglobal systemandsoftwarespecifications.Theimplementationof the globalsystemspecificationspecific to theindividual machinewill be described.Herethe detailedplacementof cratesandracksand theidentificationof their contentswill be given. No mentionof global architectureneed be given,exceptto identify the interface,and any differencesor specialfeaturesthatarerequiredfor theparticularmachine.

In general,no SRS will be requiredfor an individual machineat Level 4. For theglobal applications,referenceshould be madeto the global applicationsoftwareSRS.For example, if the genericarchiverspecifiedin theglobalSRS will do just fine for theMEB, then it will suffice to sayso. Howeverfor eachmachinespecifics,suchas for thearchivernumbersand ratesof pointsto be archived,will be given.

In addition, for eachmachinea numberof machinespecificapplicationswill berequired. Thesewill includecommissioningprogramssuchasthe24 which havebeenidentified for the LEB by Wienands,BourianoffandBork andsimplerscreensfordisplay andcontrol ofequipment,subsystems,etc. Eachof theseapplicationsshould belisted in the Level 4 MachineSpecification. This list will correspondone-to-onewith thesoftwarenotebooksto be developedatLevel 5, anddescribedbelow.

5.0 Level 5. SoftwareNotebooks

This is the level whereactualsoftwaremodulesor specific applicationswill bedefined. Here a "living" softwareproject notebookor folder will be maintained. Themodel will be theCEBAF approach.Forexample,the front pageis verygeneral- "writesoftwaresupportroutinesfor theCCL vacuumsystem." The notebookkeepsup atraceablerecordasthespecificsare discussed,agreed,andmodified. It is this notebookthat would be reviewableby QA.

Thenotebookapproachwill alsobe appliedfor modificationsor enhancementstoEPICS. Examplesmight be "modify ChannelAccessfor Nameserverandcacheing,"or"add graphicaldatabaseeditor," etc.

Thenotebookwill containat leastthe following:

* Title Page. Brief oneor two linesdescriptionof theproject,asdescribedabove. Eachnotebookshouldrefer back to the level 4 SRSin which it is calledout.

* Tableof Contents.Mostnotebookswould includemostor all of thesectionslisted below.

* Sign-off page. Indicateswho is requiredto sign off on whatpartsof thenotebooks. eg who mustsign off on therequirementsnormally customer,developer,developer’ssupervisor,who on the lCD section,who on thetestplans,etc. This pageshould be auditedfor appropriatenessof sign-offauthoritiesidentified.

* SDPSection. Normally a line will be sufficient, referencingtheapplicableSDP.Otherwiseany specialdevelopmentpractceswill be recordedhere.

* RequirementsSection. Herethe requirementsare listed in asmuch detail aspossible. This sectionwill be recognizedasthe requiredSRS. Requirementsandchangesto them during the developmentandcommissioningcycle aresignedoff asrequiredon thesign-off page. Oneacceptableway ofpresentingrequirementswould beto include sketchesof operatorscreenswhereappropriate.Requirementscould beauditedfor ambiguityor incompletenessor inconsistencies.

* TestPlan Section. As the requirementsevolve,a testplan will be developedinthis sectionwhich testseachof thespecifiedrequirements.For small systems,a systemtest harwareand softwaretogetherwill be appropriate.Wheresuitable,separatesoftware testplansmay be required. Testplanswould be auditedfor traceabilitytorequirements.

* lCD Section. Here is whereonewould keepsignallists, interfacespecs,etc.Referencecouldbe madeto applicablehardwaremodule documentationwhereappropriate. ICDs would be auditedfor completeness.

* ConfigurationSection. Here would be kept recordsof all files, wheretheyare,etc. ConfigurationManagementof thesefiles would be by SCCSor equivalent,ascalledout in the relevantSDP. This sectionwould be auditedfor conformanceto the SDPsoftwareconfigurationplan.

* Designnotes. Herewould be keptnoteson the evolving design,listings,charts,etc. Auditablefor completeness.

* DeveloperLog. Herethe developerwould keepa personalrecordof activities,progress,problems,brilliant ideas,attaboysandahshits. Normally this would be theonlynon-auditablepart of the notebook.

Thenotebookcanbe kept in whateverway seemsmostconvenientto thedeveloper,includingelectronically. Howevera paperversionmusteventuallyexistsothat it can be signed-offasrequired. I expecta typical quality audit would involvecheckingthe first pageto seewho is supposedto sign what,andthenverifying that thecorrectsignatureshavebeenobtained.Eachpageor sectionof a completednotebookwould requirea QA signature. I imaginethe paperversionof thenotebookbeingkept ina threering binder.

software development plan - fermilab · software development plan 1. introduction this software...

Documents