Flight Patches

Version 1.19. Last updated June 20, 2023.

Generating on-orbit version of flight patches

When a set of optional patches has been tested by Peter Ford on the engineering unit and MIT has certified the corresponding ECO, this document describes the process by which the patches may be converted into a set of addPatch commands for use on orbit.

The set of all such commands to upload a complete desired set of patches onto ACIS, including the final addPatch command which establishes the software version number, is called a "patchload".

During engineering unit testing and completion of the MIT ECO process, command files in bcmd format will already have been built. The flight versions will differ in three ways. Throughout this document, we will use the designators, X-Y-Z, where X is the standard patch release level, Y is the optional patch release level, and Z is the certification level. For example, if the release is E-F-G (standard E, optional F, certifications G), then X=E, Y=F, Z=G.

Summary of Inputs and Products

The inputs to the flight patch build process are

In a given certification release, there will often be several sets of optional patches which are certified to work as a unit with the underlying standard patch release. The procedure described in this document is aimed at constructing one "patchload" for each of these certified combinations (as well as an additional patchload that contains only the standard patches.) Each patchload is a sequence of ACIS addPatch command packets, starting with those for the standard patches, continuing (for all but the standard-only patchload) with each of the optional patches in a certified combination, and ending with an addPatch command which sets the flight software version number (FSVN.)

There will be just one of these certified combinations that we intend to place on orbit and incorporate right away in an SOP. The other patchloads will be constructed and minimally tested, then held in reserve so that we can expeditiously develop an SOP for them should the need arise. Which is the correct flight patchload should be obvious from ECO review and ACIS Ops Working Group meetings; if not, just ask around.

The primary outputs are For the record, we will also preserve one set of intermediate products, the "_mit.bcmd" files, one for each patchload, which will have been created in step 10. This is intended to make it easy, if desired, to repeat the verification that we have made no unintended changes to the contents of the patch packets.

An aside on ID Pools

SACGS uses identity pools to keep track of unique identifiers. When you build a new parameter block or power command, you checkout new identifiers from the ID pools to prevent subsequent reuse. There are six ID pools; four of which are in common use (te, cc, win, cmdseqno) and two of which are only used for flight software patches (fsver, pnode). If a previous user created new FSW patch packets and neglected to "make idcheckin", the fsver and pnode pools could remain incorrect until the next patch is required. Don't skip steps! The most obvious symptom that this has happened is in step 10, when building the patchloads. Each patchload includes a final packet with the flight software version number which should not be the same as the previous set of flight software patches. The fsver and pnode ID pools can be repaired in the same way as the rest -- consult the SACGS maintainer for help.

Finding the Sources

Although one may always obtain a full flight software release from the MIT ACIS team at /nfs/acis/h3/acisfs/configcntl/, there's no way to obtain the bcmd files for the addPatch commands without building pretty much everything from scratch - which requires a particular environment with the necessary cross-compilers.

We have therefore always skipped all that, and proceeded to just steal outright the bcmds which MIT used for its ECO certifications.

The certifications are documented in a certification directory

/nfs/acis/h3/acisfs/patchbld/cert-X-Z

where X is a letter designating the standard release, and Z is a letter designating the certification release.

In that directory, you will find files and subdirectories named after certified patch combinations, such as:

cc3x3+eventhist+compressall+txings/

cc3x3+eventhist+compressall+txings.notes

cc3x3+eventhist+compressall+untricklebias+txings/

cc3x3+eventhist+compressall+untricklebias+txings.notes

Each .notes file indicates a certified combination, for which we must build a corresponding patchload. To learn which optional patches are included in the certification, always look in the notes, because the patches explicit in the subdirectory name may not be the entire list. The notes will also indicate a list of "Test Support Patches". Also known as "engineering patches", these are used to support diagnostics during testing on the engineering unit, but are never intended to be loaded on orbit.

Patch order. At this point, you will also want to determine the order in which you will load the optional patches. As of this writing, the one real order dependency is that smtimedlookup must precede eventhist and cc3x3. But additional dependencies may arise. Peter Ford has undertaken to state the load order of the patches within the first page of the corresponding .notes file in the future, so look there.

******************************

HOPEFULLY SUPERFLUOUS NOTE

Should the patch order not be listed, contact Peter. Or you can follow the old instructions which follow.

The one way to be sure of patch order is to open an MIT test script (runtest.tcl) under each certification, and examine the order in which the script invoked its optional patches. (There's one test script for each patch, but within a certification they will list the patches in the same order.)

These tcl scripts, typically named runtest.tcl, are found in the MIT patchbld area under cert-X-Z//

END HOPEFULLY SUPERFLOUS NOTE

*****************************

Let's suppose you are ready to build the flight patches for a particular certification. Continuing with the above example, you will have found that the included patches are

smtimedlookup

cc3x3

eventhist

compressall

txings

The bcmd for the standard patches is the file standard.bcmd in

patchbld/release-X-opt-Y/release/dist/standard-release-X-opt-Y

The bcmd for the optional patches is in

patchbld/release-X-opt-Y/release/dist/options-release-X-opt-Y

Each patch sits in its own file, with an "opt_" prefix. For example,
opt_smtimedlookup.bcmd
contains the patch for smtimedlookup.

The engineering patches are considered optional patches, and have been stable since launch. They're loaded into high patch memory, to minimize the chance that their addresses will have to change as flight patches are added. There are four of them, deaeng, dearepl, printswhouse, and tlmio.

There will be additional optional patches in the directory that will not be included in the certification release and will not be loaded onto the flight instrument.

Process

You'll do most of your real work on the Harvard side. You'll peek into the MIT net only to grab the ECO version of the bcmds, do a sanity check on the engineering unit with the commands you've built, and obtain the patch dump comparison file.

You should be in the SACGS environment. Whether interactively or via .login or .cshrc, you should have sourced the latest DS release, as well as sg_env_source. The superior HEAD directory for all the patch building is /data/acis/cmdgen/patching/acisfs_patchbld. We shall refer to this as $PTCHBLD.

e.g.:
% cd /home/ascds

% source /home/ascds/.ascrc

% newgrp acisops

% source data/acis/cmdgen/sacgs/bin/sg_env_source

% setenv PTCHBLD "/data/acis/cmdgen/patching/acisfs_patchbld"

(Your usual $SGDAT should work fine, but if you choose to dedicate a separate one to this task, be sure to run
% make setup
there.)
  1. Select names for the patchloads and patch packets.

    There hasn't been a solid convention on how to name either the .cmd files containing the patchloads, or the names of the packets themselves. However, you can look at previous patchloads and previous .cmb files for models, and this much has been constant:

    The final letter in the patch name should be the optional patch letter, WUpppppYnn e.g. WUEVHSTF01 through WUEVHSTF15 for the release E-F-G (optional patches F) version of event histogram. Careful! If you assign too long a name, it will be truncated. (The script will try to make the result look meaningful by dropping vowels first, from right to left.) Stick to six letters and you won't be surprised.

    Note that even when the source code for a given optional patch is unchanged from the previous release, the load addresses are likely to be different, so patch packet contents will change.

    Finally, the patches for the flight software version number have names of the form "WUFSVhhhhh", where hhhhh is the hex version number.

  2. Copy source bcmds.

    From Peter Ford's patchbld directory on the MIT net (/nfs/acis/h3/acisfs/patchbld), recursively copy the subdirectory

    release-X-opt-Y/release/dist

    onto the HEAD directory

    $PTCHBLD/release-X-opt-Y.

    % mkdir -p $PTCHBLD/release-X-opt-Y/release

    % scp -r maaxnew.mit.edu:/nfs/acis/h3/acisfs/patchbld/release-X-opt-Y/release/dist $PTCHBLD/release-X-opt-Y/release

    Remember to include your username if it's different between MIT and HEAD. Also note that the copy needs to go through knockknock.mit.edu, either in two steps, or by setting up keypairs and ssh configuration.

    Example results for standard E optional F certification G:
    % ls $PTCHBLD/release-E-opt-F/release/dist/
options-release-E-opt-F/        standard-release-E-opt-F/ 
options-release-E-opt-F.notes   standard-release-E-opt-F.notes
    You'll find the bcmd for the standard patches on the subdirectory standard-release-X-opt-Y and bcmds for the various optional patches on the subdirectory options-release-X-opt-Y

  3. Create subdirectories for the new flightloads under $PTCHBLD/patchloads.
    For the engineering patches, there'll be subdirectory eng-X-opt-Y.
    For the intermediate .cmds, there'll be the working subdirectory, singlets.
    Finally, create a subdirectory for each flight patchload:
    wustandx
    wuxyz_Lcom
    where X (or x) and Y (or y) are the standard and optional patch release, z is the certification release, and L is a lowercase letter, unique within the release, identifying a particular certified set of optional patches. (If there are no new or updated standard patches, you will re-use the wustandx that already exists.)
    % mkdir $PTCHBLD/patchloads/eng-X-opt-Y
    % mkdir $PTCHBLD/patchloads/wustandx
    % mkdir $PTCHBLD/patchloads/wuxyz_Lcom (where L can be a,b,c or more)
    To determine L, look at the first page of the Engineering Change Order Certification. This will list the combinations of optional patches that are certified. You want to use these letters for L and you want to build ALL patch combinations that have been certified. (If only one combination has been certified, L will be "a".)

    The singlets directory may contain intermediate products from the last patch building exercise. Copy the contents to a parallel directory with a name indicating its vintage (i.e. singlets_xyz), then clear the singlets directory out.

    % rm $PTCHBLD/patchloads/singlets/*

  4. Install makefiles.

    Copy $SGPROD/bin/sacgs_ops_make to Makefile on each of the subdirectories you created in the previous step, and on the singlets directory.

    %cp $SGPROD/bin/sacgs_ops_make $PTCHBLD/patchloads/singlets/Makefile
    %cp $SGPROD/bin/sacgs_ops_make $PTCHBLD/patchloads/eng-X-opt-Y/Makefile
    %cp $SGPROD/bin/sacgs_ops_make $PTCHBLD/patchloads/wustandx/Makefile
    %cp $SGPROD/bin/sacgs_ops_make $PTCHBLD/patchloads/wuxyz_Lcom/Makefile
    (where the the copy to wustandx may be unnecessary if there are no new standard patches, and the last command will be repeated for each value of L.)

  5. Create the master component file.

    A component file is a tab separated file with records of the form:
    <bcmd file><tab> <patchnm> <tab> <ccccccc> <tab> {'N' | 'Y'}
    Each line represents an input bcmd file that will be used in at least one of the certified combination loads. (Optional patches that are not included in the certification release do not need to appear in the component files.)

    Component files will serve as inputs to id4pkts.pl in steps 8 and 10, in which the script will generate or assign identifiers and FSW version numbers and output cmd files suitable for eventual insertion into the ACIS tables. id4pkts.pl will be run once in the singlets directory, where it will assign new command sequence numbers and patch nodes, as appropriate, to all the standard and optional patch packets. It will then be run again for each patch combination to create the full cmd patchload file, re-using the IDs assigned in the singlets run, and adding the FSW version number.

    In a component file, each input bcmd (component) is described by one line, consisting of four fields:

    Look at the .cmb files from a previous release to see models for the construction of these files. Note that the final letter in each packet id field should be the release letter. For standard X opt Y, the the standard packet id will end in 'x'; and each optional packet id will end in 'y'. If either X or Y is a vowel, take special care to choose short names, since id4pkts.pl's truncation algorithm eliminates trailing vowels first.

    In the working directory singlets, create the component file for the first id4pkts.pl run (step 8 below). It should include all standard and optional components that will be included in any of the certified combinations for this patch release; all entries (except perhaps the standard patch line, see note below) will have a 'Y' in the selection field. This first component file will not necessarily correspond to any particular certified combination load. Call it all_patches.cmb

    As in Section 3, use the first page of the Engineering Change Order Certification to determine which optional patches are certified in this release. The release-X-opt-Y directory will contain more patches than what has been certified. You only need to place the certified patches in the all_patches.cmb file. Enter them in the order in which they were loaded for testing in their certification. The Certification ECO notes or the release email from Peter should indicate the valid order.

    NOTE: If the standard patches have not changed (i.e., they remain at the same release letter), you don't want to assign new ids for the standard patch packets, you want to re-use the existing ids. Write 'N' for the standard patches in the selection field of the component file for the first id4pkts.pl run in the singlets directory. Copy the existing standard patches file, standard.bcmd, from the previous release into the singlets directory. It will get picked up as input to the subsequent id4pkts.pl runs. Also, copy the existing standard patches, wustandx.cmd, from the previous singlets directory (singlets_xyz) into singlets for the record.

  6. Create the patchload component files. On each wustandx and wuxyz_Lcom directory, create a component file. The component file for the wustandx directory, needed only if there are new standard patches, will select only the standard component (by entering a 'Y' in the selection field). The load for each optional patch combination will select the standard component plus all the optional components in that certified combination. These component files have the same format as the master component file in the previous step, and will be used in step 10 below.

  7. Create the engineering patches.
    1. % cd $PTCHBLD/patchloads/eng-X-opt-Y
    2. Copy the four engineering bcmd files from $PTCHBLD/release-X-opt-Y/release/dist/options-release-X-opt-Y:
      opt_deaeng.bcmd
      opt_dearepl.bcmd
      opt_printswhouse.bcmd
      opt_tlmio.bcmd
    3. Then run
      % renumber_eng.pl opt_tlmio.bcmd opt_printswhouse.bcmd opt_deaeng.bcmd opt_dearepl.bcmd
      For neatness and historical consistency, the files should be listed in just that order. The purpose of this exercise is to insert patch node numbers into the commands. The script doesn't have to reference the idpools, because it assigns the node numbers working down from high values, so as to avoid any possible conflict with flight patch ids.

      There will be four output files, with "_renumbered" inserted into their names just before the file extension, e.g. opt_tlmio_renumbered.bcmd. The only difference between these and the inputs is that their packets will have patch ids assigned to them.

      Peter typically includes a packet in each engineering patch that sets the flight software number to high values. Since the engineering unit loads engineering patches last, these packets would overwrite the real flight software patch version number. So the renumber_eng.pl script drops those packets from its output.

    4. Run each of the renumbered files through bcmd, to get binary packets, for example:
      % bcmd -r opt_tlmio_renumbered.bcmd > opt_tlmio_renumbered.ipkts
      (The "i" in the "ipkts" suffix denotes that identifiers have been added.)

    5. On the MIT side:
      % cd /nfs/acis/h5/buehler/cypress/engpatch

      % mkdir X-opt-Y

    6. Although the official configuration controlled copies of the flight packets and their source is maintained on the HEAD LAN, courtesy to MIT and a general love of redundancy inspire us to keep permanent historical copies in a standard spot on the MIT side as well. Back in your HEAD window, copy both the output bcmd and the ipkts files onto the MIT network.
      % scp *renumbered* maaxnew.mit.edu:/nfs/acis/h5/buehler/cypress/engpatch/X-opt-Y/.
    7. That will provide the permanent copy on the MIT side. Finally, in your MIT window, where you are still on the engpatch/X-opt-Y subdirectory,
      % cp *renumbered* ..
      That places the engineering patch binaries on the parent directory, where the napcat2bcmd Makefile can look for them.

    Notes: The engineering command packets will not go into the ACIS tables. Creating these MIT copies of engineering patches will not affect ordinary engineering unit runs, which will continue to use the previous patches until you change the contents of "Flight imitation" targets in the Makefile, as described in step 13.


  8. Assign identifiers for on-orbit packets. This is the point at which you should send out a warning to acisdude to hold off on creating new SI modes or command packets with SACGS until you've finished step 9. That will ensure that no one else will snap up the various identifiers you've checked out locally. The last command in step 9 ("make idcheckin") will do a global check in of the identifiers, at which point you can give an all clear to the rest of the team. If you discover at any point that someone has run SACGS anyway, you should return to the top of step 8, unless you have already successfully completed step 9.
    % cd $PTCHBLD/patchloads/singlets
    % make idstart

    This places a working copy of the idpools on $SGDAT/data/idp and another on $SGDAT/ckpoint. (There is no "make clean" step; the "make lidcheckin" essentially does the cleanup.)

    Perform the first id4pkts run:

    % id4pkts.pl -f all_patches.cmb -i $SGDAT/idp -a -r XYZ
    where X, Y, and Z are the release letters for standard patches, optional patches, and certification, respectively.

    The script expects to find MIT input .bcmd files on the directories

    $PTCHBLD/release-X-opt-Y/release/dist/standard-release-X-opt-Y and

    $PTCHBLD/release-X-opt-Y/release/dist/options-release-X-opt-Y.

    It will fill in command sequence numbers, patchnode numbers, and (as comments) 10-character packet ids. Later eatdat will read these comments to learn what packet ids to use as keys into the ACIS Tables.
    Note: the id4pkts.pl code is re-entrant. The first thing the script does is to copy the id pools originally obtained by "make idstart" from $SGDAT/ckpoint to $SGDAT/idp. So repeated runs of the script will assign the same ids, until you issue the "make lidcheckin" command.

    Note 2: At this stage, there should be no packets in the cmd files of the form

    # Patch id 1
    add 0xefff patch 1 0x8001dfd0 {
    0x0000ffff
    }
    You can check this with a grep on "Patch Id".

    If there are, delete them. They won't do serious harm: the flight software version number packets added in step 10 will override them, turning them essentially into no-ops. But they are extraneous, and finding them on board may cause confusion to humans later on. (Peter has one of these, which sets the flight software version number to 0, in each of his individual patch .bcmds; it makes it clear when a run is being performed on patches in development, rather than on the current flight load.)

  9. Check and check in.

    Still in the singlets directory, compare the output files for the standard or individual optional patch cmds to the MIT input bcmds. You'll do one check for each optional patch and one for the standard patches.

    Historical note. In the past, the .cmd files created in this procedure wrote out their patch packets with four hex words to a line, while many of Peter's utilities put out one hex word to a line. For ease of comparison, you may want to process bcmds through a dumb little script I've put onto $SGPROD/bin. E.g.:

    % cat $PTCHBLD/release-X-opt-Y/release/dist/options-release-X-opt-Y/opt_compressall.bcmd | four2aline_bcmd.pl opt_compressall.bcmd
    before comparing. End historical note.

    If the original bcmd files already have the same number of hex values per line as the cmd files, just copy, e. g.:
    % cp $PTCHBLD/release-X-opt-Y/release/dist/options-release-X-opt-Y/opt_compressall.bcmd .
    Then check for differences between the MIT version of each patch and your own, e.g.:
    % diff opt_compressall.bcmd wucmprsy.cmd
    The expected differences will consist only of lines like this:
    < add 0xccdd patch 2 0x800e3654 {

    ---

    > add 11228 patch 1050 0x800e3654 { ## WUCMPRSF02

    The first and second numeric fields (command sequence and patch id) show an expected difference, the hex field (patch load address) should be identical; and the comment with the packet id has been added.

    Once you are satisfied there are no other differences, you can synchronize your local copies of the id pools. (All of the make commands for id pools will run correctly from any directory with a Makefile.)

    % make lidcheckin
    This copies the idpools from $SGDAT/idp to the $SGDAT/ckpoint directory.

    If you are certain no one else has run SACGS and obtained IDs from the global ID pools since you started step 8, run

    % make idcheckin

    Otherwise, return to run step 8.

  10. Build patchloads.

    In step 8, you used id4pkts.pl to assign identifiers for command packets within each individual patch. Now, you will use it to combine those individual patches into patchloads

    For each patchload directory where you created a component file in step 6 (wustandx and wuxyz_Lcom):

    1. Cd to the directory

    2. Create a comparison file. Look at the cmb file for this patchload to get the names of the included patches and their order (selection field = 'Y' for included patches). Preserving this order, concatenate the corresponding bcmds of its patch subset into a corresponding comparison file, e.g.
      % cat ../singlets/standard.bcmd ../singlets/opt_smtimedlookup.bcmd ... > wuxyz_Lcom_mit.bcmd

    3. Run the script id4pkts.pl there. It will concatenate all the patches in the load, and add the final patch packet which installs the flight software version number.
      % id4pkts.pl -f <component file> -l <loadname> -r XYZ
      Here "loadname" is the desired output file name minus the file extension, wustandx or wuxyz_Lcom. These outputs are the files which, once verified, you will place under source control on the Harvard LAN, in step 17.
    4. % make lidcheckin
      Do a separate lidcheckin for each patchload directory, otherwise the flight version number will be multiply assigned.

    5. Compare <loadname>.cmd to the <loadname>_mit.bcmd you made in step B. The only differences should be the id changes in the add patch lines, and an altered FSVersion packet.

    At this point, confirm that the FSW version numbers are unique and do not overlap with the FSW version numbers assigned to the previous patch level. If they do, you will need to repair the ID pools and do the ID assignment again.

  11. Create the rest of the ipkts files.

    If this is a new standard patchload:

    % cd $PTCHBLD/patchloads/wustandx
    % bcmd -r wustandx.cmd > wustandx.ipkts
    and for each L combination
    % cd $PTCHBLD/patchloads/wuxyz_Lcom
    % bcmd -r wuxyz_Lcom.cmd > wuxyz_Lcom.ipkts
  12. Transfer commands to MIT.
    % cd $PTCHBLD/patchloads
    % scp wustandx/wustandx.* maaxnew.mit.edu:/nfs/acis/h5/buehler/cypress/engpatch/X-opt-Y
    % scp wuxyz_*com/wuxyz*com.* maaxnew.mit.edu:/nfs/acis/h5/buehler/cypress/engpatch/X-opt-Y
    (Again remembering username if different and navigating through knockknock.mit.edu with keypairs and ssh configuration.)

    Both the cmds and the ipkts will now have permanent MIT side copies. (They won't override the existing copies, which sit on subdirectories specific to their own X-opt-Y.)

  13. Update the Makefile for EU testing. Log into maaxnew at MIT.
    % cd /nfs/acis/h5/buehler/cypress/napcat2bcmd/

    Save the old Makefile somewhere convenient, just in case. Use the current patch release PATCH= definitions, above the "Historical-only section" line, as a model to create the new patchload definitions. The new definitions should go above the current patch.

    For sanity testing of the certified loads that we aren't planning to place on orbit, add only one PATCH= definition, modeled on "Flight imitation with image loader", but call it something like "wuxyz_Lcom with image loader".

    Later, when we actually put the new patches on orbit, we'll move the "Historical-only" line above the first PATCH= line for the old release.

  14. EU sanity check.

    Run a few TE and CC SI modes with the current production patches and then new patches in place. (You select the patchload you want to run in the Makefile, leaving only one "PATCH=" line uncommented out.) The runs should complete without errors and with the expected output files. This testing takes time -- confirm that no one else needs the EU and that your network connection can stay open.

    Specifically, to perform the sanity check for the new patches we are planning to upload to Chandra, you will follow the instructions for standard SI mode testing here and as described below. Make sure the right flight software version number comes up in pmon for each test.

    1. To setup, log into maaxnew, and create a suitably named new subdirectory, e.g.:
      % cd /nfs/acis/h5/buehler/cypress/cmdver/or/guest
      % mkdir fswv48
      % cd fswv48
      % mkdir telem
      (In case some anomaly arises - not just a mistake in the patch generation process, but a difficulty with the engineering unit, or with the patches themselves - we'll want to preserve the contents of this directory, and redo this step in a parallel subdirectory when the anomaly is resolved.)

    2. In place of step 5.1, copy the most current dat and cfg ACIS table files to this directory
      % cp /nfs/acis/h1/www/bin/current.* .
    3. Continue with step 5.1.1 to setup shim and the image loader. Check that the Makefile has only the current production FSW uncommented ("Flight imitation with iloader, day to day workhorse").

    4. Continue with step 5.2.2 to create the monitor, pmon, and rundat windows. Instead of changing directories to "../cmdver/or/guest", change to the directory you created above, i.e. "fswv48". Start filterClient as directed.

    5. make start to warmboot the EU and load patches. Make sure pmon shows the expected flight software version number.

    6. Now you loop through a series of tests. For each set, you'll run run-dat3.pl, then save the 5rpt file and check that there are no errors in the rpt file with
      rptchk_rundat $rootname
      which will report its results to stdout.

    7. Run the current six CCD ECS runs
      % run-dat3.pl -I -c current.cfg -d current.dat TE_00B26B TE_00B26 TE_007ACB TE_007AC TE_007AEB TE_007AE > & fswv48_cti.rpt
      % mv current.5rpt fswv48_cti.5rpt
      % rptchk_rundat fswv48_cti
    8. Then four often used SI Modes in TE
      % run-dat3.pl -I -c current.cfg -d current.dat TE_004A4B TE_004A4 TE_00458B TE_00458 TE_00714B TE_00714 TE_004F2B TE_004F2 >& fswv48_te.rpt
      % mv current.5rpt fswv48_te.5rpt
      % rptchk_rundat fswv48_te
    9. Then four often used SI modes in CC
      % run-dat3.pl -I -c current.cfg -d current.dat CC_00044B CC_00044 CC_0004AB CC_0004A CC_000DAB CC_000DA CC_00046B CC_00046>& fswv48_cc.rpt
      % mv current.5rpt fswv48_cc.5rpt
      % rptchk_rundat fswv48_cc
    10. Then two special SIMODEs
      % run-dat3.pl -I -c current.cfg -d current.dat TE_007E8B TE_007E8 TE_0095CB TE_0095C >& fswv48_spc.rpt
      % mv current.5rpt fswv48_spc.5rpt
      % rptchk_rundat fswv48_spc
      (TE_007E8 uses multiple spatial windows, and TE_0095C exercises subarrays.)

    11. Then two event histogram modes, designed to run quickly (only 10 frames to a histogram):
      % run-dat3.pl -I -c current.cfg -d current.dat TE_009F4B TE_00946B TE_00946 >& fswv48_evhst.rpt
      % mv current.5rpt fswv48_evhst.5rpt
      % rptchk_rundat fswv48_evhst
    12. You've completed the comparison tests with the production FSW. Edit the Makefile so that only the new wuxyz_Lcom "day-to-day workhorse" is uncommented, then go back and run steps E-K a second time.

    All EU runs should complete without errors and the resulting rpt files should look very similar between the two FSW versions (except for times, etc.)

    If there are additional certified combinations, set the PATCH= line in the Makefile accordingly, and perform a single run-dat3.pl run, with one or two of the CCs, and one or two of the TEs that you used above. Follow the same steps to check the rpt file.

  15. Update the dumped patches comparison file. You'll know which certified combination of optional patches you want to run on orbit, say wuxyz_Lcom. In a shim window (MIT working directory /nfs/acis/h5/buehler/cypress/napcat2bcmd), select this patchload, WITHOUT any of the engineering patches, in the Makefile. It's the "PATCH=" line you created in step 13 as "Actual flight".

    "make start" will load the patches. Start a filter client in the monitor window:

    % filterClient -h cypress | psci -T -B -m -v -l wuxyz_Lcom_compare &
    Back in your cypress napcat2bcmd window, issue the command:
    % echo dump 0 patchlist | bcmd | sendCmds | cclient cypress 7000
    In the Monitor window you will see lines reporting a series of 'dumpedPatches' packets, and in particular one which indicates total "bytes written to `wuxyz_Lcom_compare_dumpedPtaches.1.dat". Wait for one more swHousekeeping packet, and you know your patch comparison dump is complete.

    The filterClient will produce (possibly among other things you can ignore) the binary file wuxyz_Lcom_compare.dumpedPatches.1.dat. Copy this to the following places:

    Finally, set the PATCH= line back to the "flight imitation with image loader" for the release that's currently on orbit, and run a quick CC mode through run-dat3.pl:

    % run-dat3.pl -Z -I -c current.cfg -d current.dat CC_00044B CC_00044 >& backto_fswvn44.rpt
    You're doing this just to make sure the flight software version number is restored in pmon, for the next production run on the engineering unit. (The additional "-Z" flag powers down FEPs and video boards when run-dat3 finishes.)

    Finish up as directed in the standard EU instructions.

  16. Install patches in ACIS Tables.

    Back on the Harvard net,

    Concatenate all the .cmd files creatd in step 10, and copy that concatenated file to your $SGDAT directory (or whatever subdirectory of $SGDAT you choose to work in.) Suppose the concatenated file is called patches_xyz.cmd. There will be a lot of repetition in this cmd file, but that's all right. The cmd2dat script doesn't care if it gets multiple copies of a packet; it will add in the first one, and ignore the others.

    % cd $SGDAT
    % cp patches_xyz.cmd obsreqs.cmd
    % make clean
    % make start
    % cmd2dat patches_xyz >& patches_xyz.session1
    (Check the results)
    % log2cfg patches_xyz >& patches_xyz.session2
    (This is essentially a NO-OP, since you are not adding any new configurations, but make products wants the file there.)
    % make ROOT=patches_xyz ODBTAG=yy_mm_dd_XYZL products
    At this point, follow steps 7.2 to the end of the SACGS short form, which does some book-keeping and distributes the new ACIS tables to the FOT and to the EGSE.

  17. Update configuration control (If you are unfamiliar with CVS, you can ask Catherine to do this step for you.) The SACGS CVSROOT (/data/acis/cmdgen/admin) has an "onorbit_patch" module. A copy is checked out as the directory /data/acis/cmdgen/patching/patches. On this top level directory is an html file containing a table describing flight patch configuration data, ACISPatchConfigs.html. Update the table in this file with information about the new patch release, with a separate line for each patchload, and copy the updated file to /proj/web-cxc/htdocs/acis/ptchConfig.

    The Patch Release ECO # is in Peter's ECO document, upper right corner of the first page.

    The Certification Release ECO # in Peter's ECO document, the Certification page, upper right corner.

    For the checksum, just run Unix cksum on the patch comparison file.

    Create the directories /data/acis/cmdgen/patching/patches/patchloads/release-X-opt-Y and /data/acis/cmdgen/patching/patches/patchloads/eng-X-opt-Y and Into the first, copy the patchload .cmd files, one for each certified combination, likewise the .bcmd and .cmb files, the .ipkts, and the dumped patches comparison file. Into the second, copy the bcmd, *renumbered.bcmd, and *renumbered.ipkts for each of the engineering patches. Then enter them all, including the ACISPatchConfigs.html, into CVS.

  18. Update the flight software load procedures. This document does not attempt to cover creation of the SOPs. However, early in that process the FOT will want a listing of the patch packets for which they must create realtime CLDs. You can get the information they're used to seeing (checksums and "byte" counts - actually 16 bit word counts) in neat tabular form by running the script

    % cat wuxyz_Lcom.cmd | patchid_rpt.pl > <report file>

    Name the report file any way you like, and email it to Ken Gage at the FOT. When the procedures are finalized for both SOT and FOT, enter them into the table on /data/acis/cmdgen/patching/patches/ACISPatchConfigs.html, and copy the updated page to /proj/web-cxc/htdocs/acis/ptchConfig.

Some notes on source control and backup

Some use is made of regular sacgs operations. Otherwise, we have:
Executables: id4pkts.pl, renumber_eng.pl, patchid_rpt.pl. Checked into CVS under /cmdgen/util. The util directory is highly nonvolatile, but ought to be copied to /data/acis-bak now and then. Being on /data/acis, it does get backed up to tape.
There are three significant outputs:
A. patches_xyz.cmd - stored on $SGPROD/data/atbls/cmds by 'make products'.
B. The engineering .cmd and .ipkts. On the Harvard side, these are stored on $PTCHBLD/patchloads in the eng-X-opt-Y directory. On the MIT side they're in /nfs/acis/h5/buehler/cypress/engpatch
There's a CVS module "onorbit_patch" under the SACGS CVSROOT, where the .cmb, .cmd and .ipkts files are stored under release-X-opt-Y subdirectories.
C. The packets themselves, ensconced in the ACIS Tables. Same backup and version control as all ACIS tables: Separate files for each version, kept in perpetuity on /data/acis, with hot backup to /data/acis-bak. Separate version control of ACIS Tables within OCC, from which we can recover them via lucky.