Proposal for Handling M&C Software Versions for the GBT

Mark H. Clark

November 15, 2000

Goal

Provide a trail of defined, working releases of the GBT control software.

Nomenclature

Source directories are described by a two-digit string, M.E, e.g., 3.2. The E represents an enhancement and the M a major enhancement.  These directories are generated whenever  developers feel  an enhancement or set of enhancements is ready for full integration testing on the telescope or the mockup.  Installation directories are described by three-digit strings, M.E.D, such as 3.2.2, where the D tracks the debugging of the version.  CVS revisions are labeled by this installation string, i.e., "VM_E_D."  The installation directory M.E.D may only be installed from its associated source directory M.E.

A typical sequence of events would be as follows:  I have modified the DCR in my development area to optimize the latency between scans and have tested as well as I can separate from the telescope.  The current version running the telescope is 3.2.4.  I inform the other M&C developers that I plan to create a new version 3.3 with the updated DCR.  Joe has changes to the FEM model which he would like to make part of the same version.  I check out a version  with the new code for the DCR and FEM into a source directory named 3.3.  It is installed into 3.3.0.  During test time the telescope version is switched from 3.2.4 to 3.3.0 using setVersion.  During testing on the telescope (or perhaps in attempting to build 3.3) various bugs are found and fixed in the 3.3 source directory.  After testing reaches some criterion specific to the goals of this version, e.g., an overnight run using the DCR and pointing turned on, and there are no known bugs resulting from the enhancements, the files in 3.3 are committed, labeled "V3_3_0,"  reinstalled in 3.3.0 and installed in 3.3.1.   Note that the developer may commit any changes he or she wishes, but only source revisions which have a tested installation are labeled.  Installation 3.3.0 is now frozen.  Any new bugs are fixed in the 3.3 source directory and installed in 3.3.1.  When this version reaches some criterion of stability or usefulness, then the files in 3.3 are committed, labeled "V3_3_1,"  reinstalled in 3.3.1 and installed in 3.3.2.  Future bug fixes are installed in 3.3.2.  This continues as long as this set of enhancements requires bug fixes.

Various "favorite" versions could be also installed in mockup for use in the lab or for simulations.

Scenarios

(Examples from Richard Prestage.)
 
  • I am the main scheduled observer. I want to get on with my observations, using the K-band receiver and the Spectrometer, and I don't want anyone  else to mess me about. I run from gbt, version 3.4.5.

  • I am an engineer checking out the Q-band receiver through CLEO in the lab while the primary observer is as in above. I need the latest mods to the Q-band Manager, which include the new version of the receiver base class which accommodates our new calibration scheme. I don't want to mess the observer about. I run from mockup using version found in the  test installation, or one set up specifically for the engineer by the developer, e.g., called Richard.

  • The Q-band receiver is all checked out and working, but not yet updated in any version source directory.   We get an urgent request to install its hardware and software on the telescope.  At the same time as the Q-band manager developments were being made, Joe was upgrading the Antenna manager, but his mods are only half finished. He had made his mods in his own area, I had made mine in my area.   I put mine into a new source directory 3.5  and install in 3.5.0 so the observer can use the receiver.

  • I am a member of the M&C group who has modified the Spectral Processor to write FITSVER=2.7 FITS files. The primary observer is using 3.4.5. Because this is a developmental version of the Spectral Processor Manager, I have made my changes in my area. I want to take a whole pile of FITS files to exercise all modes of the Spectral Processor, without annoying the primary observer. I don't care what IF inputs I have, I'd like to generate switching signals internally, and the observer only wants Spectrometer internal switching signals.  I ask operations' permission to use the spectral processor while the telescope is being used.  I install my spectral processor code into the mockup in either test or my area, reboot the spectral processor to run out of mockup rather than gbt, and do my thing.  When completed, I reboot the spectral processor to run from gbt and report to operations that I am finished.

  • The primary observer is using L-band, the Berkely Pulsar Processor, 3.2.m. I am an engineer trying to track down a baseline stability problem in the K band receiver using the Spectrometer as the backend. I don't care where the antenna is pointed, but I need to use the real K-band receiver and IF system. I want to use the Scan Coordinator, Archivist, etc, and a glish script which will execute multiple scans. I don't want the observer to notice that I am there.  If I want to use some of the same equipment that the observer is using then I will have to wait for test time; if, however, the equipment is mutually exclusive, then -- as with the spectral processor above -- one set can be run from gbt and the other from mockup.

  • The observer from the night before discovers a bug in the Spectrometer Manager. I think I know how to make a fix, but I am not sure if it will work. The observer says she is willing to try it.  I make the fix in M.E.D+1 and continue trying to make the fix with the observer's permission.  When these changes are completed so they may be committed and labeled depends on the criterion:  if it is simply the user saying that the problem is solved, then the changes are committed, labeled "VM_E_D+1," reinstalled in M.E.D+1 and, for future bug fixes, installed into M.E.D+2.

  • It is three weeks later. We are up to version M.E.D+4. A new observer  comes along, and discovers that the "fix" has made things worse for his configuration, and he wants to go back (at 2 am in the morning) to M.E.D+1, which he is convinced worked for him.  To return to an earlier version (or to change versions in general), one brings down all of the M&C daemons, runs setVersion, brings the daemons back up, and reboots the single board computers:
    • su monctrl
    source /home/gbt/gbt.bash
    cd /home/gbt
    ssh fornax TaskMaster fornax systemstop
    ssh vega TaskMaster vega systemstop
    ssh gemini TaskMaster gemini systemstop
    setVersion M.E.D+1
    ssh fornax TaskMaster fornax systemstart /home/gbt/etc/config/fornaxProc.conf
    ssh vega TaskMaster vega systemstart /home/gbt/etc/config/vegaProc.conf
    ssh gemini TaskMaster gemini systemstart /home/gbt/etc/config/geminiProc.conf
    cleo ResetBox
    then press Reset All Ports on All Boxes
     

    Glossary

    source
    a set of C++, C, makefiles, and associated files/directories under CVS for building executibles.
    installation
    a directory tree holding all the files necessary to run the monitor and control software.
    version
    a labeled set of source or executable files defined under CVS which together provide a working system
    enhancement
    a modification which provides new capabilities; such as integration of the active surface into the antenna, a new Manager is added, switching signals are handled differently (better?), all Samplers have code to tag bad data, or the DCR uses cfitsio.
    major enhancement
    an enhancement that affects the capabilities of the system as a whole or changes the interfaces between modules such as the text of messages are stored external to the compiled code, a consistent format for FITS files, a change in hardware architecture, or a base library changes its public methods.
    gbt
    a set of installation directory trees for running equipment on the telescope.
    mockup
    a set of installation directory trees for running equipment in the lab or for running simulators.
    integration directory
    a set of source directory trees which accepts the most recent enhancements and bug fixes from version and development source trees through CVS updates.
    test installation
    a set of directories which accepts the installation of the most recent enhancements and bug fixes from version, test and development source trees.