How-To: Poor Man's (d, m, w) Path to Device Access

Introduction

This How-To is not even a how-to. Instead, it is just a collection of stuff required to develop and deploy stuff within the old GSI control system using device access.

For the official documentation have a look in the respective frontend wikis

• start here - 'GSI Control System' means 'Old Control System using Device Access'
• Das Kochbuch - slightly out of date, but good for newbies
• building stuff with maven - try to work 'the maven way' as much as possible!

UNIPZ
This how-to gives examples for the use case of the UNILAC Pulszentrale for White Rabbit, where scuxl4711 is the frontend of the development system.

GIT
Have a look here for Device Access related things. Authentication is done by username / password or via ssh public / private key. Managing access to git is a bit cumbersome. Basicially it boils down to the following:

• you are member of a group withing ACC
• that group must be added to the relevant GIT repo; this must be done by the 'project owner'
• this must be done for every GIT repo, where you need access to
• how-to
  • find out which repo you need
  • ask INN (Christoph?), who is the project owner
  • ask the project owner to add your group to the repo
  • if it does not work, ask INN to verify access rights
  • I (db) just managed write access using ssh public / private key; I did not manage using username and password
  • see here

Prerequisites

• Access to ACC git (requires ACC account, ask INN)
• Access to Device Access GIT repositories (requires role for each repo, propably you need to ask the frontend group)
• Access to ASL6 cluster (requires ACC account); ASL6 has been converted to a virtual machine (asl735).
• Access to Device Access frontends (write access recommended for testing your stuff, ask frontend group)
• Access to Nexus (only required for mvn deploy ; for access rights checkout this Wiki)

Maven

The whole process of building and stuff is maven based. Maven just uses git as a source code control tool. Don't try to use git directly except for cloning the repository. When building something, maven first downloads lots of stuff (dependencies) from the nexus repository and stores them in a local repository cache ~/.m2.

There is a detailed how-to describing the use of maven at the FEE group. My favorite maven commands are

   * mvn versions:use-latest-releases // update all other (non-framework) dependencies to the latest versions
   * mvn dependency:tree              // checks dependencies
   * mvn clean                        // clean stuff
   * mvn install                      // builds stuff and puts it to your local repository cache '~/.m2'

How-To: Rebuilding Things with Maven

As a typical caveat it might happen, that one of your dependencies does not exist in the nexus repository, it can't be downloaded and hence does not exist in your local repository cache ~/.m2. One possibility is asking the maintainer of that dependency to properly build and upload it to the nexus repository. Another option is re-building an artifact. Here is an unofficial recipe.

Clone the git repository of the component and have a look at the git commits. Example

* ff2fc0b (HEAD, origin/master, origin/HEAD, master) some correctionsprepare for next development iteration  // this is the commit starting the NEXT release cycle: 10.01.11-SNAPSHOT
* b73964c (tag: 10.01.10) some correctionsprepare release 10.01.10                                           // this is the commit for the current release: 10.01.10
* 88610ac some corrections
* ...

In case you depend on version 10.01.10 checkout the relevant git commit (here: b73964c) and build the component by the command mvn clean install .

Device Access and Folders on ASL

Device Access is a framework providing lots of stuff. Implementing your own device just requires to implement User Service Routines (USRs).

Equipment Model (EQM)
Each equipment model has its own repository. This is where coding and building of the device is done. 'pzud' belongs to the equipment model 'eqmodel_pz'.

Example: https://git.acc.gsi.de/devacc/eqmodel_pz/pzud for UNIPZ with White Rabbit.

Development is done on the ASL 6 cluster. I (db) have chosen to clone the GIT repo 'eqmodel_pz' to a local folder 'DEVACC'.

Example: /home/bel/USER/lnx/DEVACC/eqmodel_pz/pzud

Frontend Computer (FEC) - Folder for Building
Each frontend has its own repository. This is where building of the frontend is done. The result of a build is a 'zip file'

Example: https://git.acc.gsi.de/devacc/fec_scuxl4711

If cloning the GIT repo to a local folder 'DEVACC', the result is

Example: /home/bel/USER/lnx/DEVACC/fec_scuxl4711

Configure Setup
This is mainly done via maven xml files (see 'maven' below). These files are used for versioning, configuration, dependencies of FECs and EQMs. Use a text editor. There are no specific tools.

Frontend Computer (FEC) - Folder for Rollout
A folder on the ASL6/7 cluster. Each Frontend has its own folder. A symbolic link points to the 'zip file' of the frontend. The zip file is built using the tool chain, see below.

Example: /common/export/devacc/cpu/scuxl4711

Frontend Computer (FEC) - NFS Init
Another folder on the ASL 6/7 cluster. Each Host System has its own folder

Example: /common/export/nfsinit/scuxl4711

Standard Device Properties

some info on coding pzud-device.cc provides some data and standard device properties

• methods
  • resetDevice, init of all get-values
  • initDevice, as reset , but init of all set-values too;
  • updateStatus, is triggered periodically to get and update the device status
  • onlineTest, is triggered periodically to get and update the device status
  • getVersionString, obtains version info

USRs (User Service Routines) provide methods dedicated to PZUD only; USRs are defined in the file pzud.xml

• pzud-write-evtsequ.cc, writes event data for a specific virtual accelerator and channel to the firmware, important method used by the 'UNILAC Super Pulszentrale'
• pzud-read-evtsequ.cc, reads event data for a specific virtual accelerator and channel to the firmware
• ...

For more specifics on pzud checkout this.

Tool Chain for Building

Fairly straight forward. A text editor and the command line is all you need. There are no make files, and one needs to fiddle around with various xml files. The most important ones are

• 'pom.xml'; defines the some basic stuff like version number (here: /home/bel/USER/lnx/DEVACC/eqmodel_pz/pzud/pom.xml)
• 'src/pzud.xml'; defines the interface and your own class specific USRs (User Service Routines). USR definition includes properties like write/read data, parameter, description etc.....
• 'SConscript'; analogue to 'Makefile', defines how your stuff is build; (here: /home/bel/USER/lnx/DEVACC/eqmodel_pz/pzud/src/SConscript). In case you'd like to link against 3rd party stuff like external shared librarires, this is the place you need to look at.
• folder 'src'; contains source code; (here: /home/bel/USER/lnx/DEVACC/eqmodel_pz/pzud/src)
• if things don't work as expected the following might help
  • try mvn dependency:tree to check for broken depencies
  • try mvn versions:use-latest-releases to update your depencies to the latest version
  • if everything fails, try fixing the versions of your depencies by checking the many pom.xml files, sorrry

Warning

This How-To is intended for me (db), mainly for fixing issues with PZUD and related FECs.

However, the git and nexus repositories are maintained by the front-end groups. I decided, not to commit to git 'master' branch and not to nexus. Why? I don't want to brake things for the main developer at the FE group. The following just describes changes, building and rollout in an early development stage or 'on-the-fly'. For doing things properly, synchronize with the frontend group!!!

Build EQM (here: PZUD)

cd ~/DEVACC
git clone git@git.acc.gsi.de:devacc/eqmodel_pz.git    // clone repo using ssh authentication; requires to setup public/private key first
cd ~/DEVACC/eqmodel_pz                                // cd to equipment model of PZ
git(k) ...                                            // check what's the commit / tag of the release we would like to use 
                                                      // why? HEAD of master is pointing at NEXTRELEASE-SNAPSHOT but this might not be what we want
git checkout 10.01.10                                 // example for checking out the release 10.01.10
mvn dependency:tree                                   // gives you a first insight of the dependencies
mvn versions:use-latest-releases                      // optional: update the dependencies to the latest releases
mvn dependency:tree                                   // if the dependency tree is broken, you need to fix that (pom.xml etc)
mvn clean                                             // clean environment
mvn install                                           // build equipment model and install to your local cache in '~/.m2'

cd ~/DEVACC/eqmodel_pz...                             // from now on, its probably fine to work only in 'my' code for PZUD
emacs ...
mvn clean
mvn install
... and so on...

DON'T do the following
- git push ...                                        // don't use this command to push your git commits to the git MASTER branch
                                                      // if you really like to commit/push, use your own git branch
- mvn deploy                                          // don't use this command to push the equipment model to nexus

Build FEC

cd ~/DEVACC
git clone git@git.acc.gsi.de:devacc/fec_scuxl0132.git // clone repo
cd ~/DEVACC/fec_scuxl0132                             // cd to FEC
git(k) ...                                            // for FECs, it's probably fine to use the current HEAD of master
mvn versions:use-latest-releases                      // be brave: update the dependencies to the latest releases
mvn dependency:tree                                   // check the dependency tree ...
...                                                   // ... and have a look at the VERSION of PZUD ...
[INFO] de.gsi.cs.co.fe.devacc.fecs:fec-scuxl0132:pom:10.26.06-SNAPSHOT
[INFO] ...
[INFO] \- de.gsi.cs.co.fe.devacc.eqmodels:eqmodel-pz-pzud-x86_64:zip:10.01.10:compile
                                                     ^^^^            ^^.^^.^^  
                                                      // if the version is identical to the one you have built above, then you are fine
                                                      // else: edit the pom.xml of the FEC and fix the version                
mvn clean                                             // clean up
mvn install                                           // build zip for FEC

Rollout

Quick and Dirty and not Bootsafe

(see Kochbuch, section 'III')

• on ASL 6
  • build EQM (see above)
  • scp x86_64/target/build/pzud.so root@scuxl4711:lib/pzud.so
• on FEC/SCU
  • kill and then restart the 'devman' process:
  • devman --persistent

A Cleaner Rollout

• on ASL 6
  • build EQM (see above)
  • build FEC (see above)
  • there are two options
    • cleaner: copygup -z target scuxl4711 10.26.xx
    • hackish: manually copy the zip file fec-scuxl4711-VERSION.zip to /common/export/devacc/cpu/scuxl4711 and set the symbolic link
• reboot the FEC/SCU

A Clean Rollout

Everything is decribed in this How-To. Try s.th. like this: WARNING: The following will push to git and nexus! We do this only if we are responsible for this specific FEC!

cd ~/DEVACC/fec_scuxl4711/
mvn versions:use-latest-releases                                                               // checks for lates releases of the dependencies
mvn versions:commit                                                                            // updates pom.xml to the latest dependencies
git status
git commit -a -m "use latest releases"                                                         // commits pom.xml to GIT
git push                                                                                       // and pushes to the repo
mvn release:prepare --batch-mode -DscmCommentPrefix="use latest releases"                      // prepares for next release and pushes to nexus csco.snapshot
mvn release:perform                                                                            // and push artificats to nexus
mvn package                                                                                    // (re)builds stuff
copygup -z target scuxl4711 10.26.xx !                                                         // copies required files (zip...) to export folder on the asl cluster
...
==> reboot scuxl4711                                                                           // reboot the fec

Check FEC for DEVACC

cd /common/export/devacc/cpu/scuxl4711
ll
-rw-rw-r-- 1 USER  bel      337 Feb 27 14:34 2020-02-27.log
-rw-rw-r-- 1 USER  bel 11924389 Mar  2 12:26 fec-scuxl4711-VERSION.zip                         // the zip file for the FEC you have built and copied
-rw-rw-r-- 1 USER  bel      802 Feb 27 14:34 scuxl4711.dbs                                     // defines how instances are started on the FEC
lrwxrwxrwx 1 USER  bel       35 Feb 28 10:56 scuxl4711.zip -> fec-scuxl4711-VERSION.zip        // symbolic link to your zip file

Check NFS-Init

Example for pzud:

cd /common/export/nfsinit/scuxl4711/
ll
lrwxrwxrwx 1 USER bel 37 Dec 13 14:19 20_timing-rte -> ../global/timing-rte-tg-enigma-v5.0.4   // timing RTE
lrwxrwxrwx 1 USER bel 16 Feb 27 12:37 90_devacc -> ../global/devacc                            // Device Access

Testing

Checkout this Wiki.

-- DietrichBeck - 14 Aug 2020