# Introduction

The PTC ADAPT Self-Test Program is software for the Launch Vehicle Digital Computer (LVDC) which, along with the companion Launch Vehicle Data Adapter (LVDA), was used in Apollo's Saturn rockets.  More accurately, it is softwre for the PTC ("Programmable Test Controller"), which was _ground-based_ equipment.  Thus this particular software was not use onboard the rocket; i.e., it is presented as an example of software for the LVDC computer, and not as flight software.  The reason it is presented as LVDC software, is that the PTC contained a modified LVDC, and thus that is the CPU on which this software runs.  The nature of the modifications to the CPU are significant, in the sense that software written for the LVDC may not be able to run directly on the PTC without changes, and vice-versa, but are nevertheless the differences are relatively small in the larger scheme of things. 

The ADAPT ("Aerospace Data Adapter/Processor Tester") was equipment for evaluating the LVDA, thus the PTC ADAPT Self-Test Program illuminates the interaction between the LVDC and LVDA.

Additional documentation may be found on [the Virtual AGC Project main website's LVDC page](http://www.ibiblio.org/apollo/LVDC.html#PTC_ADAPT_Self-Test_Program), which links documents for the PTC and ADAPT.  In particular, there is [a zipfile of the scanned page images of the assembly listing for the PTC ADAPT Self-Test Program](http://www.ibiblio.org/apollo/ScansForConversion/PTC%20ADAPT%20Self-Test%20Program.zip). These scanned images are the basis for the transcribed source code.

# Files

- PTC-ADAPT-Self-Test-Program.tsv — this is a transcription of the program's _octal listing_, which begins at p. 221 of the scanned pages and proceeds to the end of the scans.  The octal listing is the assembled form of the PTC ADAPT Self-Test Program.  The modern LVDC assembler also creates its own octal listing, of course, but this transcribed octal listing can be read by the assembler and used as a cross-check to validate that the modern assembler's results compares with the original assembler's results.
- PTC-ADAPT-Self-Test-Program.lvdc — this is a transcription of the program's assembly-language source code.  It can be used as an input to the modern LVDC assembler.

The transcribed source-code file assembles correctly and its assembled executable octals correspond 100% to those in the transcribed octal listing.  While the source code and the assembler undoubtedly still contain errors, they are nevertheless likely correct enough for practical purposes.

# Assembly Using the Modern LVDC Assembler (yaASM.py)

The original assembler program used during the Apollo Project is not available to us, but what we refer to as the _modern assembler_ has been created from scratch and can be used to assemble either the limited amount of LVDC source code or PTC source code available to us.  The assembler, found in this software repository at ../yaASM.py/yaASM.py requires Python3 to run.  You should be able to put it in your PATH; the file expression.py is also required.

The recommended syntax for assembling the PTC ADAPT Self-Test Program is one of the following:

    cd /to/the/folder/containing/this/file
    yaASM.py --ptc PTC-ADAPT-Self-Test-Program.tsv <PTC-ADAPT-Self-Test-Program.lvdc >listing.txt
   
or

    cd /to/the/folder/containing/this/file
    yaASM.py --ptc --past-bugs PTC-ADAPT-Self-Test-Program.tsv <PTC-ADAPT-Self-Test-Program.lvdc >listing.txt

The difference between these two forms is that the original Apollo-era assembler displayed buggy messages (but created correct executable octals) for a pseudo-op named "BCI".  By default (upper command), the modern assembler instead produces correct messages in the output assembly listing, but if --past-bugs is added to the command line (lower command), the modern assembler instead mimics the original operation and prints out the buggy messages.

The --ptc command-line switch must be used, as shown, or else the assembler will attempt to assemble the source code as an LVDC program rather than as a PTC program, and will fail to produce a usable result.

The files output by the process are:

- listing.txt &mdash; an assembly listing similar to the original scanned assembly listing, but not attempting to precisely duplicate the old format.
- yaASM.txt &mdash; an octal listing similar to the octal listing from the original scanned assembly listing, but conforming the (superior) LVDC format rather than the (inferior) original PTC format.  The data in this file is generated by the assembly process, and is _compared_ by the assembler to the transcribed octal listing, but none of the data in this output file comes from the transcribed octal listing.  This is a tab-delimited file, intended to be used as input to a PTC emulator program.
- yaASM.src &mdash; a listing of all source code, on an address by address basis, intended to be used as input to a PTC emulator program.
- yaASM.sym &mdash; a listing of all symbols in the software, on an address by address basis.  This is a tab-delimited file intended to be used as input to a PTC emulator program.

# Emulation, Using PTC/LVDC Emulator Software

The PTC/LVDC CPU emulator is called yaLVDC, and a crude PTC peripheral for it &mdash; i.e., representation of the PTC user interface panels, typewriter, printer, plotter, etc. &mdash; is called yaPTC.py.  Both appear in the yaLVDC folder of the Virtual AGC software repository, and they require nothing other than the material in that folder (and, of course, the files produced by the assembler from the PTC-ADAPT-Self-Test-Program source files).

The yaLVDC program must be built from source, using the instructions found in that folder.  Assuming you've done that, you can then run the emulation.

If, for example, the yaASM.tsv, .src, and .sym files created by the assembler were copied into the yaLVDC folder, then you could run the emulation by 

1. Opening up a pair of command lines and cd'ing each of them into the yaLVDC folder.
2. From one command line, run the command:
    ./yaLVDC --ptc --cold-start --assembly=yaASM
3. From the other command line, run the command:
    ./yaASM.py
4. The emulator (yaLVDC) has a gdb-like interface &mdash; or perhaps gdb "lite" would be more accurate &mdah; from which you can do things like set breakpoints, single-step through the program, let it free-run until breakpoints are hit, examine memory and registers, change the values in memory, list (or disassemble) portions of the source code, and so on.  But the assumption is that you probably want to run the test procedures associated with the PTC ADAPT Self-Test Program, and that topis is covered in the next section.

# Running the Tests in the Emulator

Chapter V if the original PTC documentation linked earlier describes quite a few test procedures.  Many of these have little to do with the PTC CPU or the software running on it, and more to do with characteristics of the PTC that have not been implemented in the somewhat-primitive yaPTC.py program.  (See the preceding section.)

According to my estimation &mdash; which is subject to reevaluation &mdash; the test procedures worth running in the emulator are these (by figure number from the PTC documentation), but particularly the final one:

* Chapter V, Figure 7-9, Central Processor Manual Checks.
* Chapter V, Figure 7-10, Central Processor Memory Automatic Checks.
* Chapter V, Figure 7-11, Self-Test Program Checks.