checkpoint(L) NAME checkpoint - EGSE program checkpointer and command uplink optimiser AUTHOR Craig DeForest SYNOPSIS checkpoint [ {-sw, -nosw, -sw=foo} ] foo.src [foobar.src ... ] DESCRIPTION checkpoint automates the processes of queueing and checkpointing EGSE programs for NRT uplink to the MDI instrument. It causes the EGSE to log various milestones that it passes on the way through the code, queues up groups of commands for faster broadcast, and inserts command- counter checkpoints periodically in the code. Checkpoint reads the given EGSE src files, adds additional instructions and modifies some instructions, and writes the output source into the same filename with a 'q_' or 'nq_' prepended. ('q_' indicates that the output code uses queueing; 'nq_' indicates no queuing). Unless told otherwise, it recursively descends an entire 'perform' tree. That is to say, if foo.src contains a line "perf bar.src", then check- pointing foo.src (without options) will cause both q_foo.src and q_bar.src to be generated. The line in q_foo.src will be chanced to "perf q_bar.src". Checkpoint is smart enough not to recompile a file more than once per invokation. Checkpoint checks that the first three non-comment, non-blank lines of the source code are 'program', 'source', and 'descr'. It updates the 'source' line to contain the correct '[n]q_' output source, whether or not the original contains the correct filename in its 'source' line. Valid 'descr' lines are also updated to follow the '[n]q_' naming con- vention. If one of the three lines is missing, or they are out of order, checkpoint emits a warning to stderr and continues working. A 'command block' is a section of EGSE code that contains no branches, loops, or subroutine calls, and that contains at least one spacecraft block command. Checkpoint divides the source code into command blocks of less than or equal to a specified size (default 50 commands), and inserts framing commands around each command block, to checkpoint the spacecraft command counter. You can cause checkpoint to synchronize your code with the housekeeping packets (eg if you need to check a TM variable in the EGSE code) with the magic string '###SYNC_HK###' alone on a line. When checkpoint spots the magic string, it causes the current command block to end, and inserts its own synchronization code. The ###SYNC_HK### syntax is 1 checkpoint(L) preferable to writing your own delay code, because checkpoint can be re-run on the code just before uplink, so the appropriate amount of delay (or the appropriate mf wait for the sim) can be added. When there are no waits within a block of commands, and queuing is not disabled by a command-line switch, checkpoint queues up groups of block commands with more than 2 and less than 50 (default -- the exact numbers are settable) commands. Checkpoint needs three local integer variables to keep track of the com- mand counter. It dynamically watches local variable use within your code, and uses local variables that have not been used by your EGSE source code. Once you mention a local variable, Checkpoint won't use that particular variable again for the rest of the file, which means that checkpoint dies with an error message if you use more than seven of the ten possible local integer variables. OPTIONS Checkpoint uses a simple parser to understand each option. Given an option foo, you can enter three forms: -foo, -nofoo, and -foo=bar. These set foo to '1' (flag set), set foo to '' (flag clear), and set foo to 'bar', respectively. Option switches and source file names are parsed in order on the command line, so that checkpoint -log-flow foo.src -nolog-flow bar.src will do different things to foo.src and bar.src. -destdir (string) Destination directory to which to send the compiled source code. Leaving this blank (the default) is equivalent to '.'. -recurse (flag) Causes checkpoint to descend the EGSE code's 'perform' tree recursively, checkpointing all code that is apropos to the pro- cedures named on the command line. (Set by default). This works in conjunction with the 'perf' flag -- if you say -norecurse, you probably also want -noperf. -perf (flag) Causes checkpoint to fix-up 'perform' procedure calls to call checkpointed versions of the original subroutines. (set by default). -status (flag) Causes the emitted code to display status information to the EGSE monitor. This is set by default; -nostatus omits status displays. -log-blocks (flag) Causes the emitted code to log each time it enters or exits a commanding block (ie at each checkpoint). (Set by default). 2 checkpoint(L) -log-flow (flag) Causes the emitted code to log each time it enters or exits a procedure. (Set by default). -maxcmds (integer) Maximum number of commands allowed in a command block. Defaults to 50. -queue (integer) Minimum number of commands that must be found in a queue- able group before enabling queuing. The last command in a queue- able block is not queued, so if this is set to , so that check- point will not turn on queuing for less than commands at a time. Setting this to zero causes queuing to be disabled -- use "-noqueue" to only allow one-at-a-time command uplink. -time Housekeeping packet delay, in seconds. Set this long enough that a spacecraft housekeeping packet is sure to arrive during the inter- val specified, so that the spacecraft command counter reflects the number of commands actually received. This time delay is used at the end of each commanding block, before checking the command counter. Since the s/c HK cadence is 7 seconds, this defaults to 8 seconds. In halo orbit, this may need to be longer to reflect speed-of-light delay. Setting -notime causes checkpoint to use "wait mf 2", which is the appropriate delay command for use on the simulator at Lockheed. -warnings (flag) Causes checkpoint to emit warnings to stderr when it finds irregularities in the input source code. (Set by default; -nowarn- ings causes checkpoint to keep its big mouth shut). -verbose (flag) Causes checkpoint to emit extra messages about what it's doing. (Clear by default). -help (flag) Causes checkpoint to emit a usage summary to stdout. Clear by default. BUGS Currently, checkpoint is not sufficiently smart about loops: if you have a 'for' loop with one command in it, checkpoint will bracket that one command with checkpointing code, and you'll have to wait for a housekeeping packet for each iteration of the loop. If you enter an improper description line (ie without an isolated single dash in the description string) that the EGSE won't like, checkpoint is equally brain damaged and won't recognize it as a 'descr' line at all. 3 checkpoint(L) Checkpoint does not check for string length, so (eg with long descrip- tion lines) it is possible to generate code that breaks the EGSE, which sets arbitrary string and line length limits -- and doesn't check for overruns. Bugs of this sort are hard to track down, as the EGSE will simply interpret extra characters as the beginning of a new line. Either the EGSE should be fixed, or checkpoint should generate long- string and long-line warnings. Code that contains tab characters ends up looking funny. Tabs should be changed into the proper number of spaces. Checkpoint is written in perl. " ( Hey -- that's not a bug -- it's a _feature_ ! ) 4 99