LVDC Flowchart Editor Tutorial

History

• 2023-07-20.  First draft.

Contents

• Introduction
• Preparation
  
• How to Build an LVDC Flowchart from Source Code
• Flowchart Annotations in LVDC Source Code
• FLOW Directives
• Working Example:  the SQUARE ROOT UTILITY Module of AS-512
  

Introduction

If you're reading this, I assume you know what the LVDC was, know what the flight software for it is, and that you have access to the available LVDC flight-program source code in compliance with whatever ITAR restrictions on export of that software from the U.S. may or may not be, so I won't rehash that territory here.

Rather, this page is solely about the creation and maintenance of software flowcharts based LVDC flight-program software.  By that, I do not mean creation of flowcharts that allow complete and accurate recreation of the flight-program software.  Instead, I refer to a set of undocumented annotations that appear in AS-512 and AS-513 flight-program software (and presumably other versions of the flight software not available to us) that I theorize may have been hints for draftsmen creating mid-level flowcharts that could provide convenient guidance to someone trying to understand the general flow of the software.

In fact, this is entirely my own idea:  There is no available evidence at all about who created the annotations I refer to, when they were created, why they were created, whether they actually relate to flowcharting, how to interpret the annotations, nor whether flowcharts created from them provide a reasonably-accurate view of the software flow that could be useful to someone or not.  I merely observe that flowcharts can be created based on these annotations, that those flowcharts are pleasing to me, and that perhaps that they are not entirely without merit more generally.

But they are not perfect.  The two main problems about the flowcharts that bother me are:

1. The LVDC software's flowchart-related annotations — if that's what they are! — are neither fully complete nor fully correct.  Therefore, manual corrections to the annotations are sometimes useful in producing more-informative flowcharts.
   
2. We don't know if the flowcharts we produce are actually good reflections of the software source code or not.  Perhaps they're misleading!  They need to be checked and corrected if they do turn out to mislead.
   

Potentially, the latter of these problems may ultimately require updates to the flowchart-generation software (more about that in a moment)  But regardless, the first step for either of the problems is human inspection of the flowcharts and of their relationship to the LVDC source code, along with manual editing of the flowcharting annotations as necessary.  Both are difficult tasks, but are the kinds of tasks that can be rewarding in terms of the understanding gained of the LVDC software in the process.  This tutorial is addressed to someone who would want to involve themself in process of checking and improving the LVDC flowcharts.

Preparation

As far as the flowcharts themselves are concerned, you don't actually need copies of them since you'll have the capability of building them yourself.  With that said ....  Unlike the LVDC source code, I do not believe that the flowcharts are restricted by ITAR, and so it's possible you may find them on the LVDC web page.  However, at least at first, I am continuing to treat them as ITAR-restricted, so it may be that the only place you'll find them is the same place you got the LVDC source code.

Having downloaded the LVDC source code and (optionally) the flowcharts onto your computer, you'll have encrypted archives in the 7z format, respectively LVDC-software.git.7z and (optionally) dots.7z.  You'll need 7z-enabled archiving software to unpack these archives.  Google it to find out what the right archiving software is for you platform.

The unpacked LVDC software is in the form of a git repository, so to access it you'll need to have git installed on your computer.  The unpacked git repository will be called LVDC-software.git, and won't appear to have any usable files in it.  You'll need to run the command

git clone LVDC-software.git

thus creating a new folder (called just LVDC-software) in which you'll be able to find all of the LVDC source-code files.

You will need to have Python 3 installed on your computer in order to run the flowchart-generation software.  I don't believe that any nonstandard Python modules need to be separately installed.  Python 2 will not suffice.

My flowchart-generation software needs to be downloaded.  The only files actually needed are yaASMflowchart2.py and sdl.ps.  No installation is needed, though you may find it helpful to give yaASMflowchart2.py "executable" permissions (if that's something that exists in your operating system) and to put it in your PATH.  The easiest thing to do with sdl.ps is to put it directly in whatever folders hold LVDC source-code files (*.lvdc).

The graph-visualization software graphviz is needed.  This is a free download (Linux/Windows/Mac).

(Optional.)  In viewing or editing LVDC source code, it is helpful though not required for the viewing/editing software to be able to provide syntax highlighting for LVDC assembly language.  You'll see examples of that below.  The only editor presently having LVDC syntax-highlighting capability is vim, which is admittedly not to everyone's taste.

(Optional.)  The flowcharts are produced in PostScript format.  To view them, you either need document-viewer software that supports PostScript, or else graphics software that can conveniently convert PostScript to some other image format, preferably PNG.  There are so many possibilities on so many different platforms (Linux vs Windows vs Mac) that it is hard to make solid recommendations.  With that said, I most-often use ImageMagick graphics software when converting to PNG, and instructions I give will be geared towards it.  Personally, I seldom have reason to perform such conversions.

How to Build an LVDC Flowchart from Source Code

Creation of software flowcharts from LVDC source-code files is a multistep process, which in general looks like this:

1. Conversion of LVDC source-code files (*.lvdc) to flowcharts in the DOT graph-description language is carried out by the program yaASMflowchart2.py.
2. Conversion of DOT files to flowcharts in the PostScript page-description language is performed by the program called "dot" that is provided by your installation of graphviz.
3. (Optionally) PostScript files are converted to other viewing formats (PNG, JPG, PDF, etc.) by graphics software such as ImageMagic, GIMP, maybe Adobe Acrobat, maybe Photoshop, etc., though in general it's just easier to view the PostScript files directly in appropriate viewing software.
   

Let's consider these steps in order.

Creation of DOT files from LVDC files.  Recall that any given LVDC flight program consists of a set of dozens of LVDC source-code files.  We don't create a single, immense flowchart for an LVDC flight program as a whole.  Rather, the flowcharting annotations in the LVDC software define many, many smaller flowcharts.  Usually there's a single flowchart in an individual LVDC source file.  But sometimes there are multiple flowcharts in a single source file, and sometimes (though rarely) there are none at all.  The naming of the flowchart files is provided by the flowcharting annotations and not by the filenames of the source-code files.  You can either process each source-code file individually, or else you can concatenate some or all of them and process them all at once.  If yaASMflowchart2.py is in your PATH, from a command line you could process a single LVDC source-code file (say, SQUARE_ROOT_UTILITY.lvdc) like so:

yaASMflowchart2.py <SQUARE_ROOT_UTILITY.lvdc

Or in Linux, you could process all of the LVDC files in the current folder at once like this:

cat *.lvdc | yaASMflowchart2.py

In Windows, the corresponding command would be:

type *.lvdc | yaASMflowchart2.py

ABSOLUTE-COMMAND_FREEZE_UTILITY_(FR).dot
ACCELEROMETER_PROCESSING_(AP).dot
ACCELEROMETER_READ_(AR).dot
ACQUISITION_GAIN-LOSS_(GL).dot
APS_ATTITUDE_CONTROL_TEST_(AC).dot
ARCTANGENT_UTILITY_(AT).dot
BOOST_NAVIGATION_(NE).dot
CHI_COMPUTATIONS_(CC).dot
CMC_CUTOFF_(CI).dot
COMPRESSED_DATA_TELEMETRY_(CT).dot
...

dot -l sdl.ps "SQUARE_ROOT_UTILITY_(SR).dot" >"SQUARE_ROOT_UTILITY_(SR).ps"

convert -density 96 "SQUARE_ROOT_UTILITY_(SR).ps" -background white -flatten "SQUARE_ROOT_UTILITY_(SR).png"

magick -density 96 "SQUARE_ROOT_UTILITY_(SR).ps" -background white -flatten "SQUARE_ROOT_UTILITY_(SR).png"

Flowchart Annotations in LVDC Source Code

As I've mentioned, AS-512 and AS-513 flight-program source code contains various unexplained annotations among the program comments that usually have no immediately-obvious interpretation in terms of describing what the source code is doing.  After contemplating the meaning of these for a couple of months, I formed an impression that these annotations may have something to do with flowcharts, and specifically may be hints for creating a flowchart of the associated code.  Or possibly at one time had even been exact instructions for automating generation of flowcharts, but had deteriorated over time due to neglect and lack of programmer training.  Whatever the explanation, in AS-512 and AS-513, by my reckoning, the annotations can no longer be interpreted with 100% reliability.  Thus the explanations I'm going to give you of these annotations and how to interpret (or edit) them are based on my own inferences, and have lots of exceptions where they don't agree with my explanations.

Throughout this section, I'll illustrate my explanations using AS-512's MATRIX MULTIPLY UTILITY module.  Here's the entire original source code for that module, sans and modern comments we added when transcribing it.  Everything that I think is part of a flowcharting annotation in one way or another has been highlighted either in red, green, or blue:

$SEGMENT  MM   REF           MATRIX MULTIPLY UTILITY (MM)

       TITLE   'MATRIX MULTIPLY UTILITY (MM)                A0840'

**********************************************************************
*                                                                    *
*                                                                    *
*      MATRIX MULTIPLY UTILITY (MM)                                  *J
*                                                                    *
*                                                                    *
**********************************************************************

* DATE              5 - 18 - 68

* REVISIONS         NONE

* FUNCTION          THE FUNCTION OF THE MATRIX MULTIPLY UTILITY MODULE
*                   IS TO PERFORM A MATRIX MULTIPLICATION ON THE TWO
*                   SPECIFIED MATRICES

* ENTRIES           U.MM00 - TWO ARGUMENTS SUPPLIED UPON ENTRY. IN AC,
*                            A DFW ON THE FORM CLA,A,MPY,B WHERE A AND
*                            B ARE THE INITIAL LOCATIONS OF THE
*                            MATRICES TO BE MULTIPLIED.  IN PQ, A WORD
*                            CONTAINING A DFW OF THE FORM STO,C IN
*                            SYLLABLE 1 AND A COUNTER (SCALED B25) IN
*                            SYLLABLE 0.  C IS THE INITIAL LOCATION OF
*                            THE PRODUCT MATRIX.

*              LIST                                                   $
*    ARROWLEFT DRAW <                                                 $
*    ARROWRIGHTDRAW >                                                 $
*    ARROWDOWN DRAW V                                                 $
*    SYMBOL    DRAW .                                                 $
       ORG     P.MOD,C.UT
*Q                                                                    *
*                           U.MM00                                    S
U.MM00 STO     777          SAVE RETURN LINKAGES AND INPUT ARGUMENTS  B
       SUB     =O01         AKJUST DFW FOR USE
       STO     D.VUTB+4
       CLA     775
       STO     D.VUTB
       AND     =3
       STO     D.VUTB+5     SAVE COUNTER
       CLA     777
       STO     D.VUTB+6
MM100  HOP     MM500        (U.VD01)FORM VECTOR DOT                   P
       EXM     0,1,0        STORE 1ST ELEMENT                         B
       HOP     MM500        (U.VD01)FORM VECTOR DOT                   P
       EXM     0,1,1        STORE 2ND ELEMENT                         B
       HOP     MM500        (U.VD01)FORM VECTOR DOT                   P
       EXM     0,1,2        STORE 3RD ELEMENT                         B
       CLA     D.VUTB+5
       SUB     =1
       TNZ     MM200        MATRIX MULTIPLICAT- ION COMPLETE          N
       HOP     D.VUTB+6     RETURN                                    X
*              NONE 8                                                 $
MM200  STO     D.VUTB+5     SET TO FORM ELEMENTS FOR NEXT ROW         B
       CLA     D.VUTB+4     *
       ADD     =O7500004    * RESET A ADDRESS, INCREMENT B ADDRESS
       STO     D.VUTB+4     *
       CLA     D.VUTB
       ADD     =O01          *  INCREMENT C ADDRESS
       STO     D.VUTB
       TRA     MM100                                                  G

MM500  STO     777          SET TO PEFORM VECTOR DOT
       CLA     D.VUTB+4
       ADD     =O01
       STO     D.VUTB+4
       TRA     U.VD01
*                                                                     E
*                                                                     H

• J indicates the start of a flowchart.  It invariably appears only in full-line comments, and the remainder of the comment (shown above in blue), minus any * or spaces at the beginning or end, is the title of the flowchart.
• H indicates the end of a flowchart.  Any source-code lines not between J and H are not included in any flowchart.
  

Aside:  Other than J and H lines, I currently just ignore all full-line comments, because I haven't figured out any reliable interpretation for them.  It's possible they may be best interpreted as captions for blocks of flowchart elements, and that they should be printed on the flowchart separately from any individual boxes or arrows.  I just don't know.  However, omitting them doesn't seem to do much harm.

Red Annotation	Interpretation	Flowchart Shape
S, X, G	Entry or exit point.  Or more specifically: S:  Start point.  Caption:  If the line of code has a symbolic label, it uses that symbolic label; otherwise, if the program comment is of the form "(label)remainder of comment", it uses label; otherwise, if the program comment isn't empty and has no spaces in it, it just uses the comment in its entirety; if all of the that fails, then there's an error message. X:  Exit point. Caption: If the program comment, sans any leading or trailing "(something)", isn't empty and contains no spaces, that's used as the caption; otherwise, if the assembly-language instruction is either TRA or HOP, then the operand of the instruction is used if it can be interpreted as a symbolic label; otherwise, "Line N" is used, where N is the source-code line number. G:  Go to.  Caption: The assembly-language instruction is expected to be a TRA or HOP to a symbolic label, and that operand is used as the caption.
P	Call to a subroutine or expansion of a macro; i.e., a named sequence of instructions.  Caption:  The program comment is generally of the form "(label)remainder of comment", and is used (word-wrapped) as the caption.  If "(label)" is present, a linefeed is also inserted following it.
M, L, B, D	Unnamed sequence of instructions.  The caption is generated the same way as for P (see above).  The distinction between M, L, B, and D isn't clear.  Perhaps the following interpretations, in order of increasing uncertainty, are meaningful.  Perhaps not: M: Mask L: switch seLector B: Begin, Bias, Backup, Bits, Burn, feedBack, oBtain, time Base D: —\_(ツ)_/— (For future readers, if any, that's a shrug emoji.) Perhaps the real truth here is that there's no consistent way for us to distinguish these annotations from each other.  The flowchart-generator software doesn't even try, and treats them as interchangeable.
Q	Decision.  The caption is generated the same way as for P (see above).
I	Input or output, generally via PIO instructions.  The caption is generated the same way as for P (see above).

Red Annotation	Interpretation	Flowchart Shape
Y	Yes
N	No

• Any line with a symbolic label may potentially appear in the flowchart as a TERMINAL box, captioned by the symbolic label itself.
  
• Even without a symbolic label, any line may potentially appear in the flowchart as a TERMINAL box if it's the target of a HOP, TRA, TMI, or TNZ instruction.  Without a symbolic label, the TERMINAL box will be captioned as "Line N", where N is the source-code line number.
• Unannotated TRA instructions are treated as if they were annotated by G.
• Unannotated TMI and TNZ instructions are treated as if they were decision boxes (Q) combined with uncaptioned exit arrows.
• Note:  Unannotated HOP instructions are not treated in any special way, since either P vs G could be the appropriate annotation, and the flowchart generator has no way to know which is which.
  

In most cases, the flowchart depicts control flow by following the simple rule that each flowchart box has an arrow to the next box, in the order that the annotations associated with the boxes are encountered in the source code.  But there are exceptions that interrupt this simple default ordering:

• S boxes do not receive a default arrow from the preceding box.
• Boxes do not receive a default arrow if the preceding box is an X box, a G box, or if the preceding LVDC instruction was TRA.
• And there are certain rare cases involving Q, Y, and N in which there is no default arrow from the Q box to the next box.

Decision boxes are the trickiest aspect of program flow in the flowcharts.  The stereotypical case is a two-way decision, in which the pattern of LVDC instructions and flowchart annotations looks like this:

        ... instructions to set up a test ...
       final instruction of the setup                     Q
       TMI|TNZ label1                                     Y or N
       next instruction
       ... additional instructions ...

The flowchart associated with this has a decision box (labeled with the comment for the "final instruction of the setup"), an arrow captioned YES or NO to label1, and an arrow captioned NO or YES to the next box following the decision box.  The complexity comes in because there are many ways to do this differently or even wrong, and the flowchart generator tries to handle as many of those exceptions as it can.

For one thing, suppose we instead had this:

        ... instructions to set up a test ...
       final instruction of the setup                     Q
       TMI|TNZ label1                                     Y or N
       TMI|TNZ label2                                     N or Y
       next instruction
       ... additional instructions ...

This is treated as a 3-way decision instead of a 2-way decision, so that we have an arrow captioned YES or NO to label1, and an arrow captioned NO or YES to label2, and an uncaptioned arrow to the next box following the decision box.  Perhaps a bit misleading, but inescapable given that Y and N are the only red annotations available for the arrow captioning.  (Fortunately, there seem to be no 4-way or higher decisions in LVDC code.)

A common situation, which may or may not be an error on the part of the original programmer, is when the Q annotation is missing:

        ... instructions to set up a test ...
       final instruction of the setup              
       TMI|TNZ label1                                     Y or N
       next instruction
       ... additional instructions ...

In this case, the flowchart generator compensates by inserting a decision box captioned by the comment associated with the TMI|TNZ (not from the "final instruction of the setup"), but otherwise proceeds as if the decision box had been present all along; i.e., there is still an arrow from the decision box to label1, and so on.

I probably haven't captured all of the possible aberrations associated with decision-box annotations here, but the lesson is clear: poorly-annotated decision-boxes are fairly common.

FLOW Directives

The FLOW directive is the mechanism provided to compensate for poor flowchart annotations in the original source code.  A detailed worked-out example appears in the following section.

When you want to correct poor flowchart annotations, the first step is to determine what the correct annotations should have been.  However, having determined the correct annotations, you can't simply modify the LVDC source code's annotations, because our unalterable rule is that the LVDC source code must match the original program listing exactly, even if the original code was in error.  Because otherwise, we have no means of verifying that the transcription process was correct.  But we do allow additions to the source code of directives defined only by the modern LVDC assembler and not accepted by the original LVDC assembler, because there's no way of confusing such a directive with incorrectly-transcribed source code.

The FLOW directive is one such modern-only addition to LVDC assembly language.  The FLOW directive is placed on the line immediately preceding a line with poor flowchart annotations, and provides corrections to those annotations.  However, the FLOW directive is used only by the flowchart generator program, and is entirely discarded by the modern LVDC assembler, so that the presence of FLOW directives does not in any way alter assembled LVDC code.

From the description in the preceding section, you'll have noted that the following characteristics of a line of LVDC code sometimes affect flowchart generation:

1. The red annotation.
2. The symbolic label of the line.
3. The LVDC instruction.
4. The operand of the LVDC instruction.
5. (Intentionally blank; relates to a property of full-line comments that's no longer used).
6. The "label" in a comment of the form "(label)remainder of comment".
7. The "remainder of comment" in a comment of either the form "(label)remainder of comment" or "remainder of comment".
   

The FLOW directive has 7 fields corresponding to these parameters (including the always-blank #5), and allows you to correct any or all of them for any given line of LVDC code.  The format of a FLOW-directive line is:

       FLOW    F1,F2,F3,F4,F5,F6,F7

where the fields F1 and so on correspond to the 7 characteristics mentioned above.  Note that there are no spaces shown.  In fact, no spaces are allowed until F7 is reached, since F7 is the only one of the seven fields that can actually contain any spaces.  Any field you don't want to provide a correction for is left empty.  For example, the directive

       FLOW    ,,,,,,

would correct nothing at all.  If the correction you want to apply is to blank out something that isn't empty already, you can use the field ""; i.e., two double-quotes side-by-side.  Thus the following command would blank out all seven flowchart characteristics:

       FLOW    "","","","","","",""

       FLOW    Q,,,,,,MY DECISION?

• ? indicates a decision box, and at the same time an uncaptioned exit arrow from the box.  It's like a Y or N unaccompanied by a preceding Q (as described above) but without any caption on the arrow.
  
• - is used for marking lines that have a symbolic label but are otherwise without flowchart annotations.

For example, suppose you had code like so,

       TMI     *+1
       TRA     label
       ... some instruction ...

The TMI instruction will turn into a decision box and will want to have an arrow to "some instruction", but "some instruction" has no symbolic label, and thus the flowchart generator will want to insert a terminal box with a caption like "Line N".  But if you instead inserted a FLOW directive,

       TMI     *+1
       TRA     label
       FLOW    -,MYLABL,,,,,
       ... some instruction ...

Working Example:  the SQUARE ROOT UTILITY Module of AS-512

What I'd like to do in this section is work through a real-life example, namely that of the SQUARE ROOT UTILITY module from the AS-512 flight program that has already been used several times above as an example.  It's a very short file that has a relatively-large number of potential improvements.  Fixing it up the flowchart will thus be a lot of work, but at the same time we'll gain a lot of understanding about the code along the way.

To the left is the relevant portion of the source-code file, which I've chosen to look at using the vim editor, because LVDC syntax-highlighting is available in vim.  Whereas to the right we see the flowchart generated from that source code as-is.

As mentioned earlier, one issue with the flowchart is that we may have succeeded in accurately reproducing the program flow — that remains to be seen! — but inadequate flowcharting annotations in the original source code may not have allowed decent labeling of some of the boxes or arrows in the flowchart.  You can see this particularly in the decision boxes labeled "Line 68", "Line 77", and "Line 85", and in the associated entry points labeled "Line 70", "Line 76", and "Line 88".  Why these goofy labels?  It's because there's nothing in the source code that tells the flowchart-generator software anything meaningful about the test being performed or the significance of the test results. 

So if we want to fix up the flowchart at those points with meaningful captions, we have to use our soft human brains to figure out the intent of the original source code.  This will require actual thinking and rummaging around in the LVDC source code, and cannot be done in some formulaic rote fashion.

Let's first see if we can figure out what's happening at line 68 of the source code and its environs.  According to the comments at the top of the source code, subroutine U.SR00 accepts a number (let's call it x) in the accumulator register and is supposed to compute its square root.  D.VUTB (a variable), it tells us, contains the "previous square root of argument".  So presumably one would load an initial guess for the square root (perhaps x/2) into D.VUTB before calling U.SR00 the first time, and could then keep calling U.SR00 iteratively in order to keep refining the square-root value.

It's too bad that the comments in the source code don't actually say that, and instead force us to presume it.  As it happens, there is external documentation that can help us out somewhat, sometimes, in figuring out stuff like this.  The external documentation I speak of is something called the Equation Defining Document (EDD).  Unfortunately, there are several separate EDDs, and we only have the one called "LVDC Equation Defining Document (EDD) for the Saturn IB Flight Program".  Which is not what the AS-512 flight program is, given that AS-512 used a Saturn V launch vehicle.  But still, it's close enough in some ways to be helpful.  Rather than making you look in the document library for the document, here are direct links to the various parts of that EDD:

• Part I, Sections 1-3
• Part I, Sections 4-5
• Part I, Sections 7-9
• Part I, Sections 10-11
• Part I, Sections 12-14
• Part I, Section 15
• Part II

Now, if you look at line 79 in the source code, you'll notice a reference to EQ. 13.6.1.  That's an equation in the EDD, though since we have a different version of the EDD, it's not necessarily the same equation number.  As it happens, in the Saturn IB EDD it's section 13.5 (rather than 13.6) that describes SQUARE ROOT ALGORITHM, so the relevant equation is 13.5.1.  Let me quote the EDD in full:

       SUB     D.VUTB       IS 1/2 ARGUMENT LESS THAN FIRST GUESS     Q
       TMI     *+2                                                    Y
       TRA     SR10                                                   N

       FLOW    Q,,,,,,IS 1/2 ARGUMENT LESS THAN FIRST GUESS
       SUB     D.VUTB
       FLOW    Y,,,,,,
       TMI     *+2
       TRA     SR10         IS 1/2 ARGUMENT LESS THAN FIRST GUESS     N

       FLOW    Y,,,SR05,,,
       TMI     *+2

Aside:  Here's a pro tip for you.  Fix the flowcharting problems from the bottom of the source-code file upward.  That way, addition of FLOW directives doesn't keep messing up the line numbers!

       SUB     D.KB25
       TNZ     *-1
       CLA     D.VUTB

       FLOW    Q,,,,,,DIVISION DELAY COMPLETE?
       SUB     D.KB25
       FLOW    N,,,,,,
       TNZ     *-1
       CLA     D.VUTB

       FLOW    Q,,,,,,3 ITERATIONS COMPLETED?
       SUB     =1
       FLOW    Y,,,,,,
       TMI     *+3
       STO     D.VUTB+2
       TRA     SR05
       FLOW    -,DONE,,,,,
       CLA     D.VUTB

    

       FLOW    B,,,,,,DIVIDE BY CURRENT ESTIMATE

← Before vs After →