1. Introduction

This document covers the steps needed to update from FS 10.0.0-beta1 to 10.1.0-beta2 and the changes since 10.1.0-beta1. This update is not an operational release. It is intended for testing by all stations using FS 10.1.0-beta1. If you do not already have FS 10.1.0-beta1 installed, please see the FS 10.1.0-beta2 Update Notes document instead.

If you already have FS 10.1.0-beta1 installed, the update from that is much simpler than the update to 10.1.0-beta1, see the Upgrading from 10.1.0-beta1 section below. The changes in the FS and drudg for 10.1.0-beta2 are covered in the Changes since 10.1.0-beta1 section below.

2. Upgrading from 10.1.0-beta1

You must have already installed 10.1.0-beta1 according to the FS 10.1.0-beta1 Update Notes document before following the directions in the current document. If you have not already installed 10.1.0-beta1, please see the FS 10.1.0-beta2 Update Notes document instead.

2.1. Login as root

The next step requires having root privileges.

2.2. Fix file permissions

Having the wrong ownership and/or permissions on the operational files (procedure libraries, control files, schedules, and logs) can cause errors during FS operations. For a full discussion, please refer to the Set operations file permissions section of the Installation Reference document. For stations with the standard configuration (all the operational files are owned by user oper in group rtx, with permissions ug+rw,o+r,o-w), the following command will enforce this (note that the execute/search bits are not changed):

/usr2/fs/misc/fix_perm

Answer y to the prompt if you wish to proceed. It is recommended for most stations.

2.3. Login as prog

This is necessary for updating the FS source, unless you must install from an archive, as described in the next step.

2.4. Fetch FS 10.1.0-beta2

There are two options given below:

  • If you are using an FSL9 or FSL10 system:

    cd /usr2/fs-git
git fetch
git checkout -q 10.1.0-beta2
    Note
    		 The github server was recently updated and the certificates available in FSL8 no longer work.

  • If you are unable to use git (you are using FSL8 or other older system):

    1. Please follow the steps, through the step that includes the option to set the link, in the Installing from an archive subsection in the Release Model document. Use 10.1.0-beta2 as the value for tag. Be sure to set the link for /usr2/fs.

2.5. Login as prog

Important
 The FS must be compiled as prog.

If you are already logged in as prog, no change is needed. This step is included to make sure you switch to prog in case you installed from an archive in the previous step.

2.6. Compile the FS

cd /usr2/fs
make rmdoto rmexe all >& /dev/null
make -s

No output from the last command indicates a successful make.

2.7. Login as oper

Except as indicated, the actions in the next step should be performed as oper.

2.8. Local customizations

  1. Install the default (new) erchk control file.

    cd /usr2/control
cp /usr2/fs/st.default/control/erchk.ctl .

    The default file will recreate the previous erchk behavior except that now sp errors will also be shown. More information on customizing the file can be found in erchk control file FS change item below.

  2. Make sure all lines with xterm in stpgm.ctl use x as the second field.

    For use without the display server, this will prevent the xterm from being aborted by a Control+C and causing the FS to abort. When used with the display server, this will make it part of the clients, which is normally what is needed.

2.9. Review changes

Please see the Changes since 10.1.0-beta1 section below for the details of the changes since that release.

3. Changes since 10.1.0-beta1

There are separate subsections with summaries of changes in the FS and drudg.

Clickable links such as, #36, connect to specific issues reported at https://github.com/nvi-inc/fs/issues.

A detailed list of changes can be found using the git log command from within the FS git repo directory, usually /usr2/fs-git.

Each change is listed as a numbered title, then usually a few summary sentences, followed by a toggle:

Details

Details are shown here.

that can be clicked to toggle showing (or not showing) the details. In this way, you can view the summary as a list and only reveal the details of items that interest you. The summary sentences and/or the details toggle may be omitted if they would not add any new information, usually because it is already covered in the numbered title item and/or the details are very brief.

3.1. FS changes

  1. Improve DBBC3 support:

    Several improvements were made in DBBC3 support, including: mask configuration for DDC_U, firmware version checking, fb_mode/mk5c_mode recorder mode setting, mask display by the core3h_mode command, the setcl program, clarifying how to configure an experiment mode, and other improvements in the DBBC3 Operations manual.

    Details

    1. Fix setting Core3H board masks for DDC_U.

      We received new information about setting the masks, which we have implemented.

      Details

      The following background information may provide some useful context for understanding the new method:

      • The FS core3h_mode command accepts two masks per board, mask2 and mask1.

      • The output for the first eight BBCs for a board is selected by mask1 and goes to the first Ethernet output port, eth0; the second eight BBCs, by mask2 and goes to the second port, eth1.

      • The Core3H board itself has two additional masks: mask4 and mask3; the values of which must match those of mask2 and mask1, respectively. The FS manages those masks for the user. They generally aren’t visible, except when they don’t have correct values.

      • The four Core3H board masks each must have the same number of channels and bits per channel, even if the corresponding core3h_mode mask has zero channels. As a result, both output ports will produce data, even if output from only one is desired.

      There are three requirements that the core3h_mode masks for a given board must meet:

      1. The number of channels selected for a mask must be zero or a power of two, up to 16.

      2. All selected channels for a mask must have the same width (bits/channel): one- or two-bit.

      3. If both masks are non-zero, they must be have the same number of channels and widths.

      The core3h_mode command will reject any mask combination for a board that doesn’t meet these requirements. Each board can have a different number of channels and width as long as each each individual board meets the requirements by itself.

      If output is not desired for a port, i.e., its core3h_mode mask is zero, it must be disabled by setting its destination to none. The FS does not set the Ethernet port destinations. That must be done by the boot configuration file or by the operator sending commands to the DBBC3.

      As an aid to the operator, when the core3h_mode command is used to check the board setup, it will check the destination set for the two ports. A error will be reported if the destination for a non-zero core3h_mode mask is set to none or if for a zero mask it is not set to none. Consequently to avoid an error, if a mask is set to zero, the destination for its port must be set to none.

      Note
      		 For DDC_V, there is only one mask, mask1. Only the first two mask requirements above, the number of channels is a power of two and uniform width, apply. In this case, the core3h_mode command will only check that the first Ethernet port’s destination is not set to none. The second port is irrelevant for DDC_V.

    2. Check the firmware version from the multicast, comparing it to the FS control files.

      Previously it was only checked for specific forms of the core3h_mode command (that still occurs). Firmware version error reports for the multicast will occur every 20 seconds and should be very hard to overlook, assuming multicast reception is enabled in the dbbad.ctl control file.

      Note
      		 The firmware version error messages for the core3h_mode command were reworded to use parallel construction to those from the multicast.

    3. Improve the magic string calculated in the fb_mode command (and its alias mk5c_mode) to agree with the new DBBC3 mask rules.

      Additionally, two special cases (not expected to occur in normal operations) are handled:

      1. Different sample widths on different Core3H boards.

        In this case, the number of channels and width are both set to 1 to allow the string to be accepted by jive5ab. The total data rate is correct allowing accurate calculations of the remaining space.

      2. Different sample rates for different Core3H boards.

        Such a configuration is trapped an as error. If one ever needs to be used, a method for implementing it is described in the help page for fb_mode command.

      Thanks to Marjolein Verkouter (JIVE) for suggesting how to handle these cases.`

    4. Improve the display of masks for core3_mode command.

      1. Display all non-zero Core3H board masks for DDC_V.

        All Core3H board masks except mask1 should be zero; non-zero values that occur are displayed. Additionally, when the configuration is checked, any masks that should be zero but are not will generate errors.

      2. Display core3h_mode masks in curl braces, {…​}, if its associated Ethernet port destination is none.

        This indicates there will be no output for that mask.

        Note
        		 For DDC_V, mask2 (if it is incorrectly non-zero) is always displayed in curly braces regardless of its destination setting because that port in inherently disabled for DDC_V.

    5. Improve setcl

      setcl will now reject being used with v124 (there is no time in the multicast) or if the board it is configured to use is not synced.

    6. Clarify that the boot configuration is the only recommended way to configure the DBBC3 at this time.

      The FS DBBC3 Operations Manual document was reorganized to emphasis that the boot configuration is the only recommended way to configure the DBBC3. The updated manual includes a procedure for determining and setting the boot configuration from a schedule using copy-and-paste.

      Note
      		 The method of using the FS to configure the DBBC3 directly has been moved to an appendix, Alternate Core3H board configuration method, of that document, where it is described as an “engineering test mode”. It use is not recommended at this time.

    7. Make other improvements to the FS DBBC3 Operations Manual document

      The document was improved in several other ways, including: adding a section on firmware version checking, non-DBBC3 specification sections were moved to appendices, the appendix on configuring the FS was improved and made a section of the main document, a workaround for scan_check not working (removing it) when writing a single VDIF thread per file was included, the description of handling .skd schedules was improved, a third level was added to the table of contents, and miscellaneous changes to bring it up to date for 10.1.0-beta2 were added.

      Details

      1. A section was added on how the FS handles checking the firmware version and reporting when the version loaded is different than expected.

      2. Non-DBBC3 specific sections were moved to appendices.

        They were retained in this document because although they are not specific to DBBC3s, it is expected that they will not get much use with other systems.

      3. The appendix on configuring the FS for use with a DBBC3 was changed to a section in the main part of the document.

        It was also made more complete, most significantly to add more information about customizing the station procedure library and how to make sure the Tsys monitor display window can get the focus to allow entry of commands.

      4. The fact that scan_check currently does not work when writing a single VDIF thread per file and how to workaround it (remove it) was noted.

      5. The description of the handling of .skd schedules by drudg for the DBBC3 was improved.

      6. A third level was added to the table of contents to provide clickable links for access to another level of subsections.

      7. It was updated for changes since 10.1.0-beta1.

  2. Turn data sending off before modifying an RDBE’s time in fmset.

    The fmset program will now make sure that transmission of data is turned off before updating the time. It will be re-enabled when fmset exits.

    Important
    		 All RDBE’s being recorded must have the same VDIF epoch. fmset is the safest way to change the VDIF epoch of an RDBE.
    Details

    Previously for RDBEs, the operator needed to turn data transmission off manually (rdbe=data_send=off) before using the sync (s) command in fmset. Then after leaving fmset, re-enable data transmission (rdbe=data_send=on). Using the s command was a rare event. As a result, handling this in a more automated way had not yet been implemented. Automating this became more important because we have received new information that data transmission must be off before making any change to an RDBE’s time, including the VDIF epoch.

    To streamline this process, fmset has been modified to turn off data transmission automatically for any RDBE that had data transmission on before its time is changed. When fmset is exited, it will re-enable data transmission for all RDBEs for which it had turned off the transmission.

    Important

    The VDIF epochs of all the RDBEs being recorded must agree to successfully record with a Mark 6 recorder. One of the ways they can get out of sync is if a subset of the RDBEs is rebooted. In order to simplify dealing with an RDBE needing to be rebooted during an experiment, it is recommended that the VDIF epochs be reset as soon as convenient (the first gap in observing) after an epoch change, which occurs at the start of January 1 and July 1 UT.

    A possible method for resetting the epoch is to reboot. However, rebooting creates a risk of a bad FPGA load, which in some cases, cannot be detected until the data reaches the correlator. Using fmset to update the epoch is safer since it does not involve an FPGA reload.

    If an RDBE has to be rebooted (sometimes it is unavoidable) after the epoch change and before there was a chance to update the epoch for all the RDBE, the rebooted RDBE’s VDIF epoch will not agree with the other RDBEs. The disagreeing epoch will be shown in inverse video in the RDBE monitor display (monit6). fmset can be used to decrement the epoch of the rebooted RDBE so that it agrees with others. It is not an error to have the RDBEs using a previous epoch, they just must all use the same one.

  3. Show incorrect DOT times in inverse video for the RDBE monitor display (monit6) window.

    Inverse video was added to help identify when the RDBEs are not all using the same time.

    Details

    Although in principle there is nothing wrong with recording data from RDBEs that have slightly different times (unlike having different VDIF epochs, which makes recording impossible with Mark 6 recorders), the recovery of the recorded data is too costly to use in most cases. As a result, to bring the operator’s attention to the conflict, monit6 was modified to show DOT values that are not the current time in inverse video. This change could have been limited to using inverse video to just show times that don’t agree with the majority since only a disagreement causes a problem. However, there did not seem to be a use case for recording with the time intentionally set wrong.

  4. Log phase-cal tones, for RDBEs, that have spacings of arbitrary multiples of 1 MHz.

    Previously, tones were logged for a 5 MHz spacing regardless of the actual spacing.

    Details

    In practice, the only other phase-cal spacing in use was 10 MHz. In that case, the RDBEs and the FS were still being setup for 5 MHz spacing. Because of where the first tones happened to fall, this resulted in the even numbered multiples of 5 MHz being logged even though they did not have any power.

    If the RDBEs and the FS had been setup for 10 MHz spacing, the tones logged with no power would have been the odd multiples of 5 MHz. Now only the tones expected to have power, multiples of 10 MHz, will be logged, assuming a correct 10 MHz spacing setup is used.

    For troubleshooting purposes, it may be useful to look at the tones for all one MHz multiples. This can be accomplished by setting the RDBEs and FS up for one MHz phase-cal spacing. In this case, the multiples of one MHz with power should correspond to the actual positions of the tones. For example, if the first tone actually occurs at 1.4 MHz in the band and the RDBE and FS are setup up for one MHz spacing, the 0th one MHz tone, corresponding to 0.4 MHz, should not have power. In this case, the first multiple of one MHz with power should be the 1st. The phase-cal offset in the lo command is ignored.

  5. erchk control file: Add control file for erchk (closing #174).

    The erchk program now uses a control file, erchk.ctl, which can be customized locally to change how errors are displayed.

    Details

    To give stations more control of how errors are displayed, the erchk program has been expanded to read a control file, /usr2/control/erchk.ctl. The stations can customize it as they see fit. A default/example file /usr2/fs/st.default/control/erchk.ctl has been provided. It recreates the behavior of erchk before this update with the exception that sp errors are no longer suppressed (as was requested in #174). A comment is included explaining how to restore suppression of sp errors, if that is desired. The complete syntax of the file is explained in the comments.

    The syntax of he control file is fairly simple, but it is important to be careful when modifying it. Some changes can prevent errors from being displayed and therefore make them harder to notice since they will only be shown in the log display. The default/example file is configured to cause all errors to be displayed.

    Note
    		 As before, the tnx command removes display of the selected errors from the erchk window (as well as log display window).

    If /usr2/control/erchk.ctl cannot be found or has syntax errors, messages with an explanation of how to fix the problem or find more information are provided. The messages are organized so they will be visible if erchk is run either manually or in a window by the FS or a window manager. If there is an error, or just to check to see if there is one, the erchk program can be run manually without the FS. This can be tried repeatedly until all issues are resolved.

    Thanks to Eskil Varenius (Onsala) for pointing out that sp errors were not being shown.

  6. Fix filag_mode, mk5c_mode, and fb_mode so that the upper four mask bits are considered when determining if data is one-bit or two-bit.

    This was probably benign since it was unlikely that the channels represented by the top four mask bits were the only ones with two-bit sampling. This would only have affected systems with a FiLa10G.

  7. Improve description in the help files for when the dbbc, dbbc3, fila10g, dbbc2, and fila10g2 commands are active.

  8. Correct errors/oversights introduced in 10.1.0-beta1:

    Details

    1. Correct /usr2/fs/st.default/equipctlfix script to append .bak instead of replacing the extension in the backup filename.

    2. Fix a class number eating bug that occurred if there were was a firmware version error detected while setting a Core3H board with force.

      The class with the message to report the firmware version returned by the DBBBC3 was being lost.

    3. Fix the core3h_mode command, with no parameters, to report errors (they were silently ignored before) for a board and stop instead of continuing on to the next.

    4. Limit the core3h command to available boards.

    5. Fix core3h_mode command, with ? as a parameter, to not report implied sample-rate when decimation/sample-rate aren’t set.

    6. Correct a bug in setcl that caused to it overwrite 120 bytes of memory for DBBC3 support.

      Apparently this never caused an issue.

    7. Add missing bbc_gain=all,agc in example d3fbstation.prc file.

    8. Limit core3h_mode sample rates by available decimations.

      Previously, there was a low, but artificial, numeric sample rate limit.

    9. Cleanup minor white-space issues in example dbbc3.ctl file (closing #173).

      Thanks to Eskil Varenius (Onsala) for reporting these.

    10. Make code improvements to remove the remaining vestiges of checking Core3H board state for monitor commands.

      This had no impact on users.

3.2. drudg changes

drudg opening message date is 2022-04-08.

  1. Correct errors/oversights introduced in 10.1.0-beta1:

    1. Remove ready procedure from .snp when recorder none is selected.

    2. Correct endef to enddef when generating thread…​ procedures (closing #177).

      Thanks to Beppe Maccaferri (Medicina) for reporting this issue.