Contents

• Introduction
  
• References
• Workstation Setup
  
• First Example: Simulating a Small Digital Circuit
• Big Example:  Simulating an Entire AGC
• Choices To Make
• The Workflow
  
• Technical Appendix
• AGC Software for Simulation Purposes
  
• Transcribing/Editing a Schematic Diagram with eeschema
  
• Creating a Netlist with eeschema
  
• Converting Netlists to Verilog Source code with dumbVerilog.py
  
• The pins.txt File
  
• The module.init file and dumbInitialization.py
  
• Converting Verilog Module(s) to Verilog Test Bench
• Compilation of the Verilog Source Code
  
• Running the Simulation
• Visualization
  
• Tying It All Together
  

Introduction

Digital simulation of the AGC electrical design can provide detailed insight into how the computer functions.  Aside from satisfying simple personal interest, this is very valuable if you wish to create a simulation of the AGC, in the manner of Virtual AGC Project's Block II AGC software simulator or Block I AGC software simulator, or John Pultorak's Block I AGC hardware simulator, and want to have some way of verifying that your creation works properly.

Realize, though, that the purpose of such simulations can only be accurate examination or verification of AGC behavior, and they are not practical substitutes for software (such as our yaAGC program) designed and dedicated solely to running AGC software.  While you can use digital electrical simulations to run AGC software, these simulations are very much slower than real time.  One day, as computer speeds continue to advance, I expect that digital electrical simulations will be much faster than now!  But "faster than now" not now.  Recognize too that while simulation of the AGC or DSKY's analog circuitry is also possible, that's not what I'm talking about here.  It is simulation of the digital circuitry — i.e., the collection of logic gates in the AGC — that will be of interest.

Here's an executive summary of the workflow of the digital-simulation process as I envisage it, and which will be used throughout the remainder of this page: 

Aside:  Regarding the choice of software used in the workflow — i.e., the holy trinity KiCad, iVerilog, and GTKWave —, disagreement as to whether these are the optimal choices is always possible, and indeed likely if you happen to be a person with expertise in this particular area.  The programs were chosen because they are free of charge (and indeed are open source, like the Virtual AGC Project itself) and available for Linux, Windows, and Mac OS.  If you can make it work with the fancier tools a professional may have at their disposal, then by all means do so and let me know.  I won't change an open-source workflow into a non-open-source workflow no matter how terrific an alternate tool may be, but at least I'll be interested to hear the news and can parrot it back to the general public!

Although multiple types of simulation are possible, we'll concentrate just on these particular configurations:

• A full AGC, consisting of multiple "logic modules" interconnected via a backplane into which they plug.
  
• A single logic module, or portion thereof.
  

References

The Virtual AGC Project's Electro-Mechanical page.

Apollo-era AGC/DSKY electrical-schematic diagrams:

• Block I AGC/DSKY schematic diagrams redrawn in AC Electronics Manual ND-1021041, with theory of operation: Volume 1 and Volume 2.
  
• Scans of the original electrical-schematic drawings for Block II AGC p/n 2003993.
  
• Scans of the original electrical-schematic drawings for Block II AGC p/n 2003100 & 2003200, and associated DSKYs. 
  
• Block II AGC/DSKY schematic diagrams redrawn in AC Electronics Manual ND-1021042, with theory of operation: Volume 2.
  
• Drawing-by-drawing index into the items above.

• GitHub repository

Open-source software:

• KiCad (Electrical schematic-capture CAD)
• KiCad-to-Verilog translator script
• Icarus Verilog (Verilog compiler and simulator)
• GTKWave (viewer for waveforms output by Icarus Verilog)

Mike Stewart's similar transcription + simulation effort:

• KiCad schematics
• Verilog translations

Aside:  It should be noted that the AGC simulations described on this page were not based on Mike Stewart's pre-existing project, other than in spirit.  Mike's simulation was a very important resource in the sense that cross comparisons of the results output by Mike's implementation with those output by mine provided a way to detect errors in both implementations that would not have been easily discoverable otherwise.  And I can honestly tell you that it would never even have occurred to me to try this if Mike hadn't already done what he did!  It's very much a case of "me too!" on my part.   With that said, there are some pros and cons that work in both directions.  My schematics closely match the original AGC schematics, so closely that you can overlay them, while Mike's schematics are intended to be — and I believe, are! — functionally identical to the original schematics, but impossible to verify vs the original schematics without considerable intellectual effort.  Mike's version is more efficient in the sense that his simulation runs significantly faster than mine ... but you can't compare his side-by-side with the original schematics to verify correctness as you can with mine.  Which approach you prefer is a matter of taste.  What I'll be discussing here is my own approach rather than Mike's.

Workstation Setup

If you are using Virtual AGC via the Virtual AGC 64-bit Virtual Machine, then everything is already set up for you.

If not, you'll want to install the following software on your computer:

• KiCad EDA
• Icarus Verilog
  
• GTKWave

On Ubuntu Linux or Debian Linux, or derivatives of either of them like Linux Mint, installation of the three programs mentioned above is as simple as using the command "sudo apt install kicad iverilog gtkwave"; with Red Hat or Fedora, I believe but don't guarantee that you could use "sudo yum install kicad iverilog gtkwave"; on other Linux platforms, Solaris, or FreeBSD there's likely to be some easy way, but you'll have to research it yourself.

On Windows, install KiCad from the installer found at the hyperlink given above; watch for an option to add the KiCad command-line program (kicad-cli.exe) to your PATH, and if there is such an option then be sure to take advantage of it.  There's also an installer providing both Icarus Verilog and GTKWave, and I'd suggest using it rather than the individual hyperlinks given above.  But note that you'll find some additional setup instructions at the end of this section.

On Mac OS, the least-painful approach would seem to be installing homebrew, if you don't already have it, and then using brew to install the three programs rather than doing anything recommended at the links above.

• brew install --cask kicad
  
• brew install icarus-verilog
• brew install --HEAD randomplum/gtkwave/gtkwave
  
• Close any open command-line terminals.
  

Aside:  While the foregoing advice about Mac OS results in an easy installation, there are things about the process that are unpleasant and perhaps warrant a few words of warning so that you won't be blind-sided when you encounter them. 

• KiCad:  Expect that the first usage after installation of any of the programs in the KiCad suite (including kicad-cli) will take a very long time to load.  Load times of the KiCad applications after that first load take a much more reasonable amount of time.
  
• Icarus Verilog:  A pleasure!
  
• GTKWave:  At some point in the installation, it will abort and insist that you change ownership and permissions of a couple of folders before retrying the installation.  Whether this is good to do as a security matter, I'm not qualified to say; moreover, the installation will take a long time, measured in hours rather than minutes because of the many, many prerequisites it has to build.  Supposedly there is a second possibility, "brew install --cask gtkwave", but this command has been deprecated and (I believe) does not actually result in a functional gtkwave.
  

On all operating systems, download the "schematics" branch of the Virtual AGC repository from GitHub.  There are many different ways you might do this, depending on your computer platform and personal tastes, and I wouldn't presume to dictate to you.  For the sake of discussion, however, I'll assume that you've done this by creating a folder called "virtualagc-schematics" in your home directory.  For example, if you have the git program installed on your computer, you could do it with a command like:

git clone --depth=1 -b schematics https://github.com/virtualagc/virtualagc.git virtualagc-schematics

Install Python 3 if not already installed, and then install the Python module TatSu:

pip install tatsu

or perhaps

pip3 install tatsu

or perhaps

pip[3] install --break-system-packages tatsu

Aside:  This "--break-system-packages" option doesn't imply that there's anything wrong with the TatSu package.  Rather, it relates to a wonderful new trend of using Python environments which are "externally managed", in which no new Python modules whatever can be installed in the default environment without this "--break-system-packages" command-line option.   Isn't that a lovely development in user-friendliness?  Easily-extensible systems that can't be extended?   Ubuntu has it; Mac OS has it; soon, everybody may have it.  Oh brave new world that has such stuff in it!

Within the virtualagc-schematics folder (or whatever you chose to call it) you've just created, you'll find a folder called "Scripts".  Add the path to this Scripts folder into your PATH environment variable.  Depending on your particular computer platform, the way of doing that varies.  But the following should usually work:

• Linux: Add the line "export PATH=$PATH:PathToScripts" to the file ~/.bashrc using a text editor.
• Mac OS: Add the line "export PATH=$PATH:PathToScripts" to both of the files ~/.bashrc and ~/.zprofile using a text editor.
• Windows:  I'd suggest opening up the desktop menu and searching for "edit environment variables".  Edit the "Path" variable for your account and add PathToScripts to it.

• The folder you just added to the PATH needs also to be added to a probably-new environment variable called PYTHONPATH if you'd like all of the instructions you'll find in the text below to work for you.  Use the same technique as described above for editing the PATH.

Even More Environment Variables for Windows:

• After installing KiCad, perform the test of opening a command line and using the command "kicad-cli".  if you are told that kicad-cli cannot be found, then you have encountered a bug in the KiCad installer, which you ought to work around by adding the folder containing the kicad-cli.exe file to your PATH.  For me, that folder was C:\Users\USERNAME\AppData\Local\Programs\KiCad\8.0\bin.  For you, it may turn out to be different.

It's likely that the changes to the PATH or PYTYONPATH won't affect any existing command line terminals which are already open, so you'll probably have to open a new command-line terminal to get the benefit of the change(s).

First Example: Simulating a Small Digital Circuit

The Virtual AGC software repository already contains some fully-worked out examples of digital simulations. The simplest example is something called "testVerilog", which is actually a small circuit block extracted from the AGC's circuit module A1, the "scaler" module.  Per the installation instructions in the preceding section, all of the workflow steps will be carried out in the folder virtualagc-schematics/Schematics/testVerilog/.  The results given below were generated using KiCad v6, but any later version should work as well, I hope.  If you have KiCad v5 or earlier, the transcribed schematics are no longer present in the current repository, and the module schematics (testVerilog/*.sch) would have to be retrieved from the older repository version tagged as "KiCad-5"; but I have not tested, and other files might need retrieval as well.

Aside:  My intent is to walk you through the steps of the simulation workflow.  If you haven't the fortitude for that — I understand and forgive you! —, there's a script (simulateModuleII or simulateModuleII.bat) which can do all of the work for you and just present you with the visualization of the simulation data created by the workflow.  If you feel strong enough, then take the high road and skip past simulateBlockII to the main narrative instead of running the script.

But if you must, here's how to take the low road and use the script.  For KiCad 7 or later, you can do the following (with \ in place of / in Windows):

cd virtualagc-schematics/Schematics/testVerilog
simulateModuleII A1 

It's slightly more involved for KiCad 6:

cd virtualagc-schematics/Schematics/testVerilog
# Edit module.kicad_sch in eeschema and generate netlist file module.net,
# via eeschema's File/Export/Netlist/OrcadPCB2/Export Netlist.
# Then exit eeschema.
eeschema module.kicad_sch
simulateModuleII A1 module.net 

After the simulation completes, you can just jump down to workflow step #8 to see the simulation data displayed in a visualization program.

Workflow Step #1:  We've actually transcribed this circuit for you already as a file called module.kicad_sch, so you needn't do anything.  Still, just to give you an idea how it works, here's very high-level summary.

Start with the original Apollo Program schematic-diagram drawing for module A1, which is drawing 2005259A, two sheets (click to enlarge):

 

Don't be confused by the fact that the inputs of NOR gates in the circuit are decorated with little triangles that make the gates look like rocket ships.  (Was it intentional, I wonder?)  They're just regular NOR gates in spite of that.  The numbered oval pads are the inputs from or outputs to the AGC backplane into which the various AGC circuitry modules plug.  Perhaps I should also point out that the NOR gates used in the AGC were open-drain gates, in which you can directly tie together outputs from different gates (effectively AND'ing them without any literal AND gate).  

Aside:  I won't cover here how to actually transcribe paper drawings of electrical schematics into KiCad schematic files.  It's a complicated affair.  Just any old transcription won't do.  And honestly, you may not have to understand how to make transcriptions anyway, since I've already transcribed all of the pre-existing AGC schematics for you.  Nevertheless, in the Appendix there's a list of some of the rules you'd have to follow to get schematic files that are usable for our simulation workflow.  There are also common-sense rules that aren't covered in the Appendix, such as "you have to use wires for electrical interconnections rather than just lines".  One rule not in the Appendix that I've personally followed in order to make verification of correctness of the transcriptions much simpler is that the transcribed schematics should appear to be so visually identical to the originals that you can overlay them with nothing perceptibly out of place.  There's no technical necessity for that particular rule.  Mike Stewart's transcriptions, for example, are designed entirely for functional correctness and have no visual resemblance whatever to the originals.  On the other hand, Mike's transcriptions don't follow the rules laid out in the Appendix either, so certain steps in our simulation workflow (which post-date Mike's transcriptions) will fail.  In case you're wondering how to transcribe a circuit so as to make it visually identical to the original, KiCad's schematic capture program, eeschema, allows you to use a JPG image as the backdrop of your schematic.  Thus if you use the scanned images (as seen above) for your backdrops in eeschema, you can almost-trivially insure that all of your components and wires are in exactly the right places, which also helps to insure that the nets in the transcription are as they should be.

Transcriptions which follow the rules in the Appendix (and my additional criteria) look like this:

 

Now as I mentioned, AGC module A1 is the "scaler" circuit.  If you want to read about it in some detail, you can look at section 4-5.3.4 of document ND-1021042, which covers the theory of operation of this module.  The module's purpose is to take a clock signal called FS01/ (a 51.2 KHz square wave), which you can see coming into the module from the AGC's backplane near the upper left on the first sheet of the schematic, and to run it through a sequence of identical circuit blocks that successively cut the frequency of that signal in half, as follows, outputting those slower clocks back to the AGC's backplane:

• Output signal FS02 is 25.6 KHz
• Output signal FS03 is 12.8 KHz
• ...
• Output signal FS33 is 0.000011921 Hz

ND-1021042 has a handy table listing all of the values for FS01 through FS17, but for whatever reason doesn't deign to list FS18 through FS33 for us.

To simplify things, the testVerilog example cuts this all down so that just the first of the many divide-by-two circuit blocks.  The abridged circuit produces the output signal FS02 from input signal FS01/ and implements what's known to electrical engineers as a "flip-flop".   Here is an image of that circuit:

Workflow Step 2:  One way to create the netlist is to load the schematic file into eeschema, then from the main menu select File/Export/Netlist/OrcadPCB2/ExportNetlist and create a file called module.net.  For this discussion, I did this from using KiCad v6, and got the resulting file

( { EESchema Netlist Version 1.1 created  Tue 14 Jan 2025 05:51:55 AM CST }
 ( /00000000-0000-0000-0000-00005d281baf $noname  J2 ConnectorA1-200
  (  202 Net-(J2-Pad202) )
  (  204 Net-(J2-Pad204) )
  (  205 Net-(J2-Pad205) )
  (  206 Net-(J2-Pad206) )
  (  208 Net-(J2-Pad208) )
  (  209 Net-(J2-Pad209) )
  (  212 0VDCA )
  (  222 +4VDC )
  (  236 0VDCA )
  (  250 +4VDC )
  (  260 0VDCA )
 )
 ( /00000000-0000-0000-0000-00005d281ba1 $noname  U129 D3NOR-+4VDC-0VDCA-ABC-E_F
  (    1 Net-(U127-Pad8) )
  (    2 Net-(J2-Pad202) )
  (    3 Net-(J2-Pad205) )
  (    4 Net-(U127-Pad2) )
  (    5 0VDCA )
  (    6 0VDCA )
  (    7 Net-(U127-Pad8) )
  (    8 Net-(J2-Pad204) )
  (    9 Net-(J2-Pad202) )
  (   10 +4VDC )
 )
 ( /00000000-0000-0000-0000-00005d281b3e $noname  U126 D3NOR-+4VDC-0VDCA-A_B-E_F
  (    6 0VDCA )
  (    7 Net-(U126-Pad7) )
  (    8 Net-(J2-Pad206) )
  (    9 Net-(J2-Pad208) )
 )
 ( /00000000-0000-0000-0000-00005d281b94 $noname  U127 D3NOR-+4VDC-0VDCA-B_C-E_F
  (    1 Net-(U126-Pad7) )
  (    2 Net-(U127-Pad2) )
  (    3 Net-(J2-Pad204) )
  (    4 0VDCA )
  (    5 0VDCA )
  (    6 0VDCA )
  (    7 Net-(U126-Pad7) )
  (    8 Net-(U127-Pad8) )
  (    9 Net-(J2-Pad204) )
  (   10 +4VDC )
 )
 ( /00000000-0000-0000-0000-00005d281b45 $noname  U128 D3NOR-+4VDC-0VDCA-ABC-E_F
  (    1 Net-(U127-Pad2) )
  (    2 Net-(U127-Pad8) )
  (    3 Net-(J2-Pad205) )
  (    4 Net-(J2-Pad209) )
  (    5 0VDCA )
  (    6 0VDCA )
  (    7 Net-(U126-Pad7) )
  (    8 Net-(U127-Pad2) )
  (    9 Net-(J2-Pad209) )
  (   10 +4VDC )
 )
)
*

dumbVerilog.py A1 module.net pins.txt 20 ../empty.init module.kicad_sch >module.v
dumbInitialization.py <module.v
dumbVerilog.py A1 module.net pins.txt 20 A1.init module.kicad_sch >module.v

python -m dumbVerilog A1 module.net pins.txt 20 ..\empty.init module.kicad_sch >module.v
python -m dumbInitialization <module.v
python -m dumbVerilog A1 module.net pins.txt 20 A1.init module.kicad_sch >module.v

python3 -m dumbVerilog A1 module.net pins.txt 20 ..\empty.init module.kicad_sch >module.v
python3 -m dumbInitialization <module.v
python3 -m dumbVerilog A1 module.net pins.txt 20 A1.init module.kicad_sch >module.v

# Auto-generated for module A1 by dumbInitialization.py.
U127 1 0
U129 1 0

# Auto-generated for module A1 by dumbInitialization.py.
U126 0 1
U127 0 1
U128 1 0

// Verilog module auto-generated for AGC module A1 by dumbVerilog.py

module A1 ( 
  rst, FS01_, F02A, F02B, FS02, FS02A
);

input wire rst, FS01_;

output wire F02A, F02B, FS02, FS02A;

parameter GATE_DELAY = 20; // This default may be overridden at compile time.
initial $display("Gate delay (A1) will be %f ns.", GATE_DELAY);

// Gate A1-U129A
pullup(g38205);
assign #GATE_DELAY g38205 = rst ? 1'bz : ((0|g38203|FS01_|F02B) ? 1'b0 : 1'bz);
// Gate A1-U129B
pullup(F02B);
assign #GATE_DELAY F02B = rst ? 0 : ((0|g38205|FS02) ? 1'b0 : 1'bz);
// Gate A1-U126B
pullup(FS02A);
assign #GATE_DELAY FS02A = rst ? 0 : ((0|g38204) ? 1'b0 : 1'bz);
// Gate A1-U127A
pullup(g38204);
assign #GATE_DELAY g38204 = rst ? 1'bz : ((0|FS02|g38203) ? 1'b0 : 1'bz);
// Gate A1-U127B
pullup(FS02);
assign #GATE_DELAY FS02 = rst ? 0 : ((0|g38204|g38205) ? 1'b0 : 1'bz);
// Gate A1-U128A
pullup(g38203);
assign #GATE_DELAY g38203 = rst ? 0 : ((0|F02A|FS01_|g38205) ? 1'b0 : 1'bz);
// Gate A1-U128B
pullup(F02A);
assign #GATE_DELAY F02A = rst ? 0 : ((0|g38204|g38203) ? 1'b0 : 1'bz);
// End of NOR gates


endmodule

# In Linux:
dumbTestbench.py <module.v >module_tb.v
# Or in Windows:
python -m dumbTestbench <module.v >module_tb.v
# Or in Mac OS:
python3 -m dumbTestbench <module.v >module_tb.v

// Verilog testbench created by dumbTestbench.py
`timescale 1ns / 1ps

module agc;

parameter GATE_DELAY = 20;
`include "tb.v"

wire F02A, F02B, FS02, FS02A;

A1 iA1 (
  rst, FS01_, F02A, F02B, FS02, FS02A
);
defparam iA1.GATE_DELAY = GATE_DELAY;

endmodule

// Include-file used by module_tb.py for automating testbench generation.

reg rst = 1;
initial begin
  // Assumes compilation with the -fst option.
  $dumpfile("module.fst");
  $dumpvars(0, agc);
  
  # 2000 rst = 0;
  # 500000 $finish;
end

reg FS01_ = 0;
always #9765.625 FS01_ = !FS01_;
  
initial
  $timeformat(-6, 0, " us", 10);
initial
  $monitor("At time %t, rst=%d, FS01_=%d, F02B=%d, FS02=%d, FS02A=%d, FS02A=%d", $time, rst, FS01_, F02B, FS02, F02A, FS02A);

iverilog -o module.vvp module_tb.v module.v

vvp module.vvp -fst

Gate delay (A1) will be 20.000000 ns.
FST info: dumpfile module.fst opened for output.
Gate delay (A1) will be 20.000000 ns.
FST info: dumpfile module.fst opened for output.
At time       0 us, rst=1, FS01_=0, F02B=x, FS02=x, FS02A=x, FS02A=x
At time       0 us, rst=1, FS01_=0, F02B=0, FS02=0, FS02A=0, FS02A=0
At time       2 us, rst=0, FS01_=0, F02B=0, FS02=0, FS02A=0, FS02A=0
At time       9 us, rst=0, FS01_=1, F02B=0, FS02=0, FS02A=0, FS02A=0
At time       9 us, rst=0, FS01_=1, F02B=1, FS02=0, FS02A=0, FS02A=0
At time      19 us, rst=0, FS01_=0, F02B=1, FS02=0, FS02A=0, FS02A=0
At time      19 us, rst=0, FS01_=0, F02B=1, FS02=1, FS02A=0, FS02A=1
At time      19 us, rst=0, FS01_=0, F02B=0, FS02=1, FS02A=0, FS02A=1
At time      29 us, rst=0, FS01_=1, F02B=0, FS02=1, FS02A=0, FS02A=1
At time      29 us, rst=0, FS01_=1, F02B=0, FS02=1, FS02A=1, FS02A=1
At time      39 us, rst=0, FS01_=0, F02B=0, FS02=1, FS02A=1, FS02A=1
At time      39 us, rst=0, FS01_=0, F02B=0, FS02=0, FS02A=1, FS02A=1
At time      39 us, rst=0, FS01_=0, F02B=0, FS02=0, FS02A=0, FS02A=0
At time      48 us, rst=0, FS01_=1, F02B=0, FS02=0, FS02A=0, FS02A=0
At time      48 us, rst=0, FS01_=1, F02B=1, FS02=0, FS02A=0, FS02A=0
...
At time     468 us, rst=0, FS01_=0, F02B=0, FS02=0, FS02A=0, FS02A=0
At time     478 us, rst=0, FS01_=1, F02B=0, FS02=0, FS02A=0, FS02A=0
At time     478 us, rst=0, FS01_=1, F02B=1, FS02=0, FS02A=0, FS02A=0
At time     488 us, rst=0, FS01_=0, F02B=1, FS02=0, FS02A=0, FS02A=0
At time     488 us, rst=0, FS01_=0, F02B=1, FS02=1, FS02A=0, FS02A=1
At time     488 us, rst=0, FS01_=0, F02B=0, FS02=1, FS02A=0, FS02A=1
At time     498 us, rst=0, FS01_=1, F02B=0, FS02=1, FS02A=0, FS02A=1
At time     498 us, rst=0, FS01_=1, F02B=0, FS02=1, FS02A=1, FS02A=1

# In Linux or Windows:
gtkwave module.fst

Note:  While the waveforms shown in the two graphs are the same, there is  nevertheless a significant difference:   Figure 4-121 purports to display the signal FS01, whereas our data visualization displays signal FS01/, which is inverted from FS01.  Then too, the position of the final pulse of F02B doesn't match.  One of us must be wrong!  Which one could it be?  Could it be ... me?  Could it be ... them?  The suspense is terrible!  I hope it'll last.  Check it out yourself.

Cheat sheet:  I've made most of this line white-on-white, to make it harder to read accidentally.  If you highlight this entire line, I expect it will be enlightening.   To figure out who's wrong, it's relatively easy to work backward from the condition F02A HIGH to see what conditions it requires for the inputs of the various NOR gates, then to work backward to the NOR gates feeding those inputs, and so on.  You'll quickly find that F02A HIGH implies that FS01/ is HIGH as well, which means that Figure 4-121 is wrong in asserting that F02A is HIGH at the same time as FS01 is HIGH.  Identical reasoning applies to determining the conditions for F02B being HIGH, demonstrating that Figure 4-121 is incorrect about the positioning of the final pulse.

Big Example: Simulating an Entire AGC

Choices To Make

1. Which model of AGC is to be simulated?
2. Which of the available AGC programs is going to be run on the simulated AGC?
3. What is the test bench going to be like?
   

Aside:  Model 2003993, in differing specific dash numbers, was used for almost all missions, so I hope you'll forgive me for running out of steam at the end of the table and just covering all of the remaining missions with a bland "etc." rather than giving you 20+ more rows of model 2003993!  The way to get the information for the missing entries is by drilling down into the GN&C mission hierarchy table.  That is also the place to go in order to match a particular AGC model to a specific set of electrical schematics.

But there are really less choices than it appears at first glance.  There's a table in the Technical Appendix that lists all of the logic modules appearing in the different AGC models, in terms of the assocated schematic-diagram drawing numbers, and we can summarize what we learn from that table as follows:

• AGC models 1003656 and 1003700 use the same logic modules, in so far as the electrical schematics are concerned.
• AGC model 2003100 uses logic modules for which the electrical schematics aren't available to us.
• AGC models 2003200 and 2003993 use the same logic modules, in so far as the electrical schematics are concerned.

Or in other words, the only essentially-different cases are that we can simulate either AGC model 1003700 (Block I) or model 2003993 (Block II). 

Aside:  And of those two choices, only the simulation workflow for Block II has been debugged so far and can be considered mature enough to be "working", so the choice reduces to AGC model 2003993 ... which coincidentally, is the one that is likely most desired by people.

Regarding the test bench:  Well, this is really no different than what was discussed in the preceding section, except that we need a test bench for the entire AGC, rather than test benches for individual logic modules.  I have created some test-bench files that can be used as starting points.  The are named tb-2003993.v, tb-2003200.v, etc.

The Workflow

Aside:  As in the case of simulating a single module, I've provided a script which can perform the entire sequence of steps needed to carry out the simulation, assuming that the choices described in the preceding section have been made.  At the moment, the script only works for Linux or Mac OS, or something similar enough,  but I haven't yet created the equivalent batch file for Windows.  The script is run from the Schematics directory, and its calling sequence from the command line is

simulateAGC AGCMODEL SOFTWARE VERILOGPARMS

where AGCMODEL defaults to "2003993", SOFTWARE defaults to "Validation-hardware-simulation", and VERILOGPARMS (a quoted list of command-line parameters for the Verilog compiler that alter values in the test bench) is empty ("").  By default, every signal is logged by the simulation. To run the simulation while accepting all of the defaults, you could use the simple command.

simulateAGC

This will perform the entire workflow and jump you right to the visualization of the data output by the simulation, thus avoiding the possibility of having to learn anything in the meantime.

• A1 = 2005259A
• A2 = 2005260A
• A3 = 2005251A
• A4 = 2005262A
• A5 = 2005261A
• A6 = 2005263A
• A7 = 2005252A
• A8 =  2005255-
• A9 =  2005256A
• A10 =  2005257A
• A11 =  2005258A
• A12 = 2005253A
• A13 =  2005269-
• A14 =  2005264B
• A15 =  2005265A
• A16 =  2005266-
• A17 =  2005267A
• A18 =  2005268A
• A19 =  2005270-
• A20 =  2005254-
• A21 =  2005250-
• A22 =  2005271-
• A23 =  2005272A
• A24 =  2005273A"
  

1. Run dumbVerilog.py for the logic module to generate a kind of "rough draft" of the Verilog source code.
2. Run dumbInitialization.py on the rough drafts to create an initialization file for the implicit flip-flops in the design.
3. Run dumbVerilog.py again, using the new initialization file to get the final form of the module's Verilog source code.
   

1. Run dumbVerilog.py for each of the logic modules comprising the AGC to generate a kind of "rough draft" of the Verilog source code for each of them.
2. Combine all of the rough-draft Verilog source-code files for the modules by appending them end-to-end into one big file.
3. Run dumbInitialization.py on the big Verilog file to generate an initialization file.
4. Run dumbVerilog.py for each of the logic modules comprising the AGC, this time using the just-created initialization file, to generate a final form of the Verilog source code for each of them.
5. Combine all of the final Verilog source-code files for the modules by appending them end-to-end into one big file that contains their collective final Verilog source code.

• A model for erasable memory hardware.  This Verilog file has been pre-created, and is always the same.  It's the file called RAM.v in the folder Schematics/fixed_erasable_memory/.
• A model for TBD.  This Verilog file has been pre-created, and is always the same.  It's the file called BUFFER.v in the folder Schematics/fixed_erasable_memory/.
• A model for fixed-memory hardware.  As for the erasable memory, this is simply a file that always is the same, namely ROM.v in the folder Schematics/fixed_erasable_memory/.
• A model for the AGC software.  ROM.v, mentioned just above, always includes a file called rom.v from the folder Schematics/roms/ that contains this model.  As I mentioned earlier, Schematics/roms/ already contains a number of models for specific AGC software versions, such as Luminary099.v or Validation-hardware-simulation.v.

Combining those ideas, what Step #5 of the workflow does is to copy the appropriate file Schematics/roms/SOFTWAREVERSION.v to Schematics/roms/rom.v, and then appends the holy trinity of RAM.v, ROM.v, and BUFFER.v to the end of the BFVF.

Workflow Step #6 (compilation of the Verilog). The BFVF and the testbench file generated by dumbTestbench.py in Step #4 above are the input files to the compiler. 

But the full AGC has a lot of signal nets in it — about 8500 of them —, so there's a lot more flexibility in choosing which of those you want to look at in the data visualization than there is in any single logic module.  In case it hasn't been clear already, any or all of the signals logged when the simulation was performed can be displayed, in any order, with or without various kinds of decorations.  Which ones of them to display, and how, is typically a matter on which you'd consult the schematic diagrams and/or the theory-of-operation documents a lot in order to figure out which signals were helpful and which were merely clutter.  What I've done for pedagogical purposes in the screenshot below is to select the signals corresponding to the upper portion of Figure 4-121 of the theory-of-operations document  ND-1021042, of which you may recall that in the preceding section I used only the lower portion of that figure.  One comforting feature of this simulation is that when we saw this same data in the preceding section, the test bench had supplied the input signal FS01/ at the proper clock rate, whereas in our full-AGC simulation here, signal FS01/ is instead generated by the upstream portions of the circuitry.  And yet the simulation still generates an FS01/ signal at the same correct frequency as before.

• The top portion of Figure 4-121, from POI/ through FS01, shows signals that are all from logic module A2.  I imagine that this drawn first, and was correctly drawn.
• The bottom portion of Figure 4-121, below but not including FS01, shows signals from logic module A1. 
  
• Signal FS01 is not present in module A1, but FS01/ is present instead.  I imagine that when the bottom portion was drawn, whoever drew it simply became confused and thought that FS01 was present in module A1, when it was really signal FS01/.

There!  That neatly explains, I think, why I'm right, and everyone else is to blame for any apparent errors, and how my simulation is beautiful and perfect.  And they said it could not be done!  My next trick will to be to run for public office of some kind.  On the other hand, alternate explanations concluding that I and my simulations are idiotic are welcome too.  Anything that advances the dialog!  Let me know if you come up with one.

Technical Appendix

AGC Software for Simulation Purposes

Unmodified AGC software may not be 100% suitable for the purposes of digitally simulating the AGC electronics, and may require some modifications in order to be suitable.  At this writing, the only example of this is in the Validation program, which is a small suite of test routines for the AGC CPU that I wrote, based on the original documentation.  However, Validation is an interactive program, and dependence on a DSKY may not be very desirable in the context of simulating the digital electronics of the AGC.  One approach to this problem would be simply to clone the AGC program one wishes to run, and then make whatever changes were desired directly to the cloned source code.

Another approach is to embed directives in the original AGC program that act like conditional compilation, so that sections of the source code can be modified at assembly time without maintaining two copies of the source code.  The assembler (yaYUL) supports this approach via a command-line switch, --simulation, and embedded directives -SIMULATION or +SIMULATION within end-of-line comments in the AGC source code.  Lines of AGC source code without either of these embedded directives, or with those directives embedded in full-line comments, are processed normally by yaYUL whether or not the --simulation command-line switch is present.  However, if --simulation is in effect, yaYUL comments out any lines with an embedded -SIMULATION directive.  Conversely, if --simulation is not in effect, yaYUL comments out any lines with an embedded +SIMULATION directive.

The AGC Validation program has such directives embedded in it, and when assembled with --simulation produces a version of the program more-suitable for simulating the AGC electronics.  This alternate version of Validation is known as Validation-hardware-simulation, and thus is the program run by default when simulating the AGC electronics.

More-sophisticated AGC test programs (such as Borealis) and the original test programs (like Aurora and Sundial) are available as well, but they have not received the treatment mentioned above.

Transcribing/Editing a Schematic Diagram with eeschema

This is too detailed a topic for me to give much helpful advice about in a limited space.  Plus, I consider it unlikely that you'll find yourself needing to transcribe an AGC-related schematic diagram.  I will simply point out the following:

• The schematic-capture editor supplied with KiCad EDA is called eeschema.
  
• Schematic diagrams transcribed from the original Apollo Guidance, Navigation & Control (GNC) system are found in the "schematics" branch of our Virtual AGC repository, in the folder called "Schematics".
• There is a separate folder for each original drawing number, such as 1005700A or 2005259-.  All operations specific to a given drawing are expected to be performed within its folder unless otherwise stated.  The top-level page of the schematic has the filename "module.sch" (for KiCad v.5 or prior) or "module.kicad_sch" (for KiCad v.6 or later).  The descriptions below assume the latter.
  
• All operations described on this web-page were originally performed with KiCad v.5 but are today tested with KiCad v.6 and v.7.  If you have installed KiCad v.8 or v.9, I have every expectation that they will operate as described, but have not tested them.
  

Creating a Netlist with eeschema

There are two methods. 

Method 1:  While viewing the top-level page of a schematic diagram in eeschema, select File/Export/Netlist from the main menu.  In the "Export Netlist" window which pops up, select the tab labeled "OrcadPCB2" and click the button labeled "Export Netlist".  In the "Save Netlist File" dialog which appears, which should have pre-chosen the folder containing the top-level schematic file itself, save the netlist as "module.net".

Method 2:  For KiCad v.7 or later, the netlist can be created from a command line without even running eeschema.  The command would be

kicad-cli sch export netlist --output module.net --format orcadpcb2 module.kicad_sch

Converting Netlists to Verilog Source Code with dumbVerilog.py

• Only the AGC modules (i.e., drawing numbers) designated as "logic modules" are relevant to the digital simulation.  For example, for AGC model 2003993, the logic modules are A1 (schematic drawing 2005259), A2 (schematic drawing 2005260), and so on.
  
• The only digital-logic components used in logic modules are dual triple-input open-drain NOR gates.
  
• Each digital-logic component has a reference designator of the form Usnn, where snn is a three-digit decimal number.  The two NOR gates of a single dual-NOR component share the same reference designator.  In other respects, these reference designators are unique throughout a given logic module (i.e., top-level schematic).  Each logic module is a 2-sided circuit board, with all reference designators on the "top" side having s=1 and all on the "bottom" having s=2.
• Each NOR gate has a 5-digit "location", mmnnn that's unique throughout the entire AGC.  Any given dual-gate component thus has two separate locations, one for each of the two gates.  The digits mm are specific to the logic module and the digits nnn vary across module.
• When the logic circuit being simulated spans more than a single logic module, as is the case when simulating the entirety of an AGC, the logic modules interconnect by being plugged into a common backplane.  In the electrical schematics, this backplane is represented as 4 separate 72-pin connectors, with reference designators J1, J2, J3, and J4.  For example, pin J2-5 represents the same signal within every logic module.
• In summary, digital circuits which can be simulated using the supplied tools consist entirely of triple-input open-drainNOR gates, backplane connectors, and the wires interconnecting them.
  

Aside:  To be completely honest, I'm no longer entirely sure how many of these rules the supplied tools actually depend upon, as opposed to these rules just being the ones obeyed by the original developers.  Most of them are relied upon.

dumbVerilog.py MODULE module.net pins.txt DELAY module.init module.kicad_sch [WIRETYPE] >module.v

• MODULE would be something like "A1", "A2", etc.  It's the designation of the specific logic module to which the schematic belongs.  The tool doesn't actually use this for anything except as a unique identifier when multiple logic modules are interconnected, so if you're working with a circuit other than the official AGC modules, it doesn't really matter what you use here, though I would recommend that it still be of the form Ann.
• DELAY, roughly speaking, is the propagation delay of signals from the input of a NOR gate to its output.  The unit in which DELAY is expressed ultimately depends upon the time-scale that will be set in the test bench, but that's conventionally 100 ns.  The nominal gate delay of AGC NOR gates was 20 ns, so that means a reasonable DELAY might be 0.2.
• WIRETYPE is an optional parameter having the value either "wire" or "wand".  It shouldn't matter which is chosen, so this parameter should probably be omitted.
  

The pins.txt File

Abstractly, the AGC circuitry consists of a number of "modules" (each represented by an electrical schematic), plugged into a "backplane".  The backplane, again abstractly, consists of a set of connectors whose pins are interconnected by wires.  However, there is no schematic diagram as such for the backplane, so to incorporate the backplane into our simulation the interconnections in the backplane must be specified in some other form.  That alternate form of description is the pins.txt file, which is just a text file having a separate line in it for each pin of each connector on the backplane. 

Each line of the file has four fields, delimited by space characters.  Those fields are:

1. A module number (Ann or Bnn).
2. A pin number on the backplane connector for the module.
   
3. A signal type:  IN, OUT, INOUT, BP, FIX, FOX, NC, SPARE
4. A signal name (blank if signal type is NC or SPARE)
   

Aside:  Technically, there are actually two separate backplanes, designated "A" and "B", into which the AGC modules Ann and Bnn respectively plug, with some interconnections between the two backplanes.  The pins.txt file describes both, so we may as well think of it simply as one big backplane.

Regarding the module-to-backplane connectors, for the logic modules that interest us for simulation purposes, each module had a physical 284-pin connector consisting of 4 rows of 71 pins each.  (The 21st pin from either end of a row was missing, so you could equally-well consider it physically to be a 276-pin connector consisting of 4 rows of 69 pins each.  But the pin numbering pretends that the missing pins were present.)  On the other hand, on the electrical schematics for the logic modules, each of the 71-pin rows was considered a separate connector, and thus the schematics show 4 separate connectors each, designated as J1, J2, J3, and J4.

Just to emphasize this point, in case the message was lost in the details:  In pins.txt each backplane connector for a logic module has 284 pins, while on the logic module's electrical schematics there are instead 4 connectors of 71 pins each.

In principle, a separate pins.txt file should be used for each different AGC model.  In practice, there's little difference between AGC models 2003200 and 2003993, and so there is presently a single pins.txt file used for those two models.  As far as other AGC models is concerned, there is presently no available pins.txt for them.

Aside:  Strictly speaking, this isn't quite true.  The existing pins.txt was derived from Mike Stewart's digital simulation of the AGC.  Mike's backplane pin data was derived in turn by a script that analyzed his Verilog files.  Thus if we indeed wanted to generate a separate pins.txt file for each Block II AGC model we'd have an awkward chicken-and-egg problem, since dumbVerilog.py needs pins.txt before generating our Verilog files, whereas the only automated way of generating pins.txt does so after creating the Verilog files.  On the other hand, for Block I AGC's I've created a similar file, pinsBlockI.txt, by processing Block I schematics (rather than Verilog files) using an AWK script, so perhaps the same technique could be used for Block II as well.  However, the pinsBlockI.txt file is in a somewhat different format than pins.txt, and dumbVerilog.py isn't presently able to support that particular format.  Although I don't recall for certain, I suppose this means that I had only done preliminary work on Block I AGC simulation, without having taken it to the point of the simulation actually functioning. 

The module.init file and dumbInitialization.py

The only digital components present in AGC logic-module schematics are dual triple-input open-drain NOR gates (as in the figure to the left), which in themselves are stateless; i.e., the output signal of a NOR gate is directly determined by the current state of its input signals.  Or at least, the output is determined by the state of the input signals after however long it takes the signals to propagate through the gate, which is nominally 20 nanoseconds.  Nevertheless, it is possible to interconnect NOR gates in such a way that a block of NOR gates has an output signal that does not necessarily depend on the current state of the inputs.  In other words, the block of NOR gates has "memory".  The most-common such circuit block in the AGC uses several NOR gates to form what's known as a "flip-flop"; i.e., a memory element capable of indefinitely storing a single bit indefinitely.  Or rather, of storing a bit until the power is cycled, at which point the value of the bit is lost.  The testVerilog circuit used in examples above is such a flip-flop. 

This has an implication on the initial conditions for a digital simulation, since we need to specify not only the levels of the input signals to the circuit being simulated, but the initial states of these implicit flip-flops as well.  After power-up is no issue, since if we know the states of the flip-flops at power up, the simulation itself takes care of computing their states at later times.  But we first have to have some way of knowing what the states were at power-up in order to do that.

In the design of the physical AGC, almost no effort was given to putting these implicit flip-flops into any given state.  (And in those cases where an effort had been made, the mechanisms used would put the simulated flip-flops into a known state too.)  Rather, the developers just seemed to feel that the flip-flops would generally settle down into some stable state, and that happy thought proved to be adequate for their purposes.  For our purposes, namely digital simulation, it's not enough!  In simulation, it's perfectly possible for a such a flip-flop to oscillate indefinitely without ever settling down into some stable state, which means that the Verilog emulator could get stuck in an infinite loop or timeout while trying to compute the initial state of the circuit.  No good!

To specify the initial states of flip-flops, module.init allows you to state the initial output signal of any or all of the NOR gates.  As we say in the figure above, a dual NOR-gate component used in the AGC has two outputs, which are designated as pin J for one of the NOR gates and K for the other of the NOR gates.  The way these are specified in module.init is that there is a line in the file for each dual NOR component that you want to specify, and that line has the format

Unnn OutputJ [ OutputK [ DelayJ [ DelayK ] ] ]

U127 1 0
U129 1 0

In other words, U127's J output is 1 ("on") and K output is 0 ("off"); and the same for U129.  I've illustrated that in the image to the right by coloring NOR-gate outputs specified initially as 1 in green, and those specified initially as 0 in red.  You don't need to specify the output for every NOR gate, and thus the outputs of U126 and U128 are left unspecified.  But if you manually create the module.init file, it's entirely up to you to determine which ones you want to specify; and since not all possible combinations of signals are logically consistent, you must insure the consistency, which can be quite tiresome if done manually.  Because of the way NOR gates work, specifying that U129's OutputJ is 1 forces U127 OutputK, U128 OutputJ, and U129 OutputK all to be 0.  So if you specified any of those latter outputs to be 1, you'd be creating an inconsistent set of inital conditions.

dumbInitialization.py <TheVerilogSourceCode.v

where TheVerilogSourceCode.v is (surprise!) the Verilog source-code for which you wish to generate some initialization information.  There are actually two basically-different scenarios in terms of acquiring the TheVerilogSourceCode.v file:

1. If you're interested in simulating a single module, you can just use module.v.
2. If you're interested in simulating an entire AGC, you should concatenate the module.v files for each of the AGC's logic modules, end to end, into one big file.  The order in which the individual files appear does not matter.
   

Actually, these are just the two extreme cases of the unified scenario "concatenate all of the module.v files comprising the circuit in which you're interested".  But there's a practical difference between cases #1 and #2, in that if you decide you want to simulate (say) AGC model 2003993, you probably don't actually know without considerable research which particular logic modules comprise it, thus increasing the difficulty level.  Another tricky aspect is that some logic-module drawing numbers are repeated in an AGC.  For example for the Block I AGC, schematic 1006540A is used not only for module A1, but also for A2 through A16 as well, and thus there is no single "module.v" associated with schematic 1006540A, but rather a module.v generated for module A1, one generated for module A2, and so on.    The table below is a handy cheat sheet of the logic modules vs schematic numbers relevant to various AGC models.  I suppose I should warn you that the revision levels shown for the schematic drawings are simply the revisions we have, rather than necessarily the ones originally used.  AGC model 2003100, alas!, is highlighted mostly in red to indicate schematics that haven't survived or to which we have no access.

Because dumbInitialization.py expects to be dealing with a collection of modules rather than necessarily an individual module, it does not output any file specifically called "module.init".  Rather, it expects to be operating on an entire AGC circuit, so it outputs separate initialization files for each of the AGC's logic modules:  A1.init, A2.init, and so on.  As you may recall, the testVerilog circuit is a snippet from the circuit for logic module A1, so we'd have to rename A1.init as module.init after running dumbInitializion.py.  Still, the operation seems pretty simple.

This supposed simplicity hides a nasty chicken-and-egg truth, namely that we need to have module.init for dumbVerilog.py to produce module.v, and we need module.v for dumbInitialization.py to produce module.init.  Catch 22!

Fortunately, this circle is not as vicious as it appears, since all you really have to do is follow this 3-step procedure:

1. Use dumbVerilog.py with an empty module.init, or else one of your own devising, to create module.v.  We actually provide such an empty module.init (Schematics/empty.init) for this very purpose.
   
2. Use dumbInitialization.py to generate A1.init, and rename A1.init as module.init.
   
3. Use dumbVerilog.py again, to regenerate module.v.

And indeed, this process works for us, giving us

# Auto-generated for module A1 by dumbInitialization.py.
U127 1 0
U129 1 0

Converting Verilog Module to Verilog Test Bench

dumbTestbench.py <TheVerilogSourceCode.v >TestBench.v

• Messages printed by the simulation at startup, on termination, or upon other conditions.
• How long the simulation is supposed to last.
• The name of a file to which simulated events and signals are logged.
• The list of signals that are logged.
• The manner in which input signals are changed over time.
• And so on.
  

// Verilog testbench created by dumbTestbench.py
`timescale 1ns / 1ps

module agc;

parameter GATE_DELAY = 20;
`include "tb.v"

wire F02A, F02B, FS02, FS02A;

A1 iA1 (
  rst, FS01_, F02A, F02B, FS02, FS02A
);
defparam iA1.GATE_DELAY = GATE_DELAY;

endmodule

// Include-file used by dumbTestbench.py for automating testbench generation.

reg rst = 1;
initial begin
  // Assume compilation with -fst switch.
  $dumpfile("testVerilog.fst");
  $dumpvars(0, agc);
  
  # 2000 rst = 0;
  # 500000 $finish;
end

reg FS01_ = 0;
always #4882.8125 FS01_ = !FS01_;
  
initial
  $timeformat(-6, 0, " us", 10);
initial
  $monitor("At time %t, rst=%d, FS01_=%d, F02B=%d, FS02=%d, FS02A=%d, FS02A=%d", $time, rst, FS01_, F02B, FS02, F02A, FS02A);

Compilation of the Verilog Source Code

iverilog -o OUTPUT.vvp ListOfVerilogSourceCodeModulesIncludingTheTestBench

For a single logic module or other standalone schematic, that's typically just

iverilog -o module.vvp module_tb.v module.v

For a collection of modules, such as an entire AGC, the basic command is still the same, but it's a bit more complicated since the list of Verilog source-code files is much larger and includes:

• One source-code file for each module.  If schematics are reused for several modules, there will still be separate Verilog files for each, since they will have been generated (using dumbVerilog.py) with different module designations (A1, A2, A3, and so on).
• One for the ROM containing the AGC software the simulated CPU will run.
• One for the test bench.

Running the Simulation

This is the easiest thing of all, since the command is simply

vvp module.vvp -fst

The -fst option perhaps requires some explanation.  It selects the file format to be used for logging simulation data.  Because our intention is to use gtkwave to visualize the logged data (see the next section), it's necessary to choose a file format supported both by vvp and by gtkwave, or at least can be inter-converted.  At the present writing (vvp v11 and gtkwave v3.3.x), that would appear to be a wide and confusing range of formats:

• vvp:  VCD, LXT, LXT2, FST
• gtkwave:  VCD, FST, LXT, LXT2, VZT, IDX, GHW, AET2, VPD, WLF, FSDB

The bad news or good news (depending on your point of view) is that gtkwave documentation makes it clear that all of the formats I've italicized are scheduled to be deleted in gtkwave v4, in addition to which GHW is a format used only for VHDL and therefore is unlikely ever to be supported by Verilog systems.  That leaves only VCD and FST likely to be common to iverilog and gtkwave in the future.  Of these two remaining formats, VCD (from gtkwave documentation) "is the industry standard file format generated by most Verilog simulators and is specified in IEEE-1364. This is the slowest of the formats for the viewer to process and requires the most memory. However, this format is ubiquitous, and almost all tools support it".  Whereas FST "is designed for very fast sequential and random access".  Which to choose is, of course, a matter of personal preference.

Visualization of the Simulation Data

It's probably best to review the gtkwave documentation if you have questions, rather than relying on anything I have to say about it.  The command to do it is simply

gtkwave NameOfTheSimulationLogFile

Tying It All Together

For a Single Block II Logic Module, a Portion Thereof, or Similar

1. Create a schematic (module.sch for KiCad v5- or module.kicad_sch for KiCad v6+), if it doesn't already exist.
   
2. Create a tb.v file, as described above.
3. From within the folder containing your schematic and the tb.v file, run the following command:

simulateBlockII A1 [NETLIST.net]

Of course, the parameter A1 is specific to the testVerilog example, and probably would be something else for you.  The module.net parameter is optional, in the sense that simulateBlockII will try to generate a file called module.net itself if the parameter is missing, but NETLIST.net must already exist if the parameter is present.  KiCad v7 or later is required if you're going to omit the NETLIST.net parameter.

For an Entire AGC

simulateAGC AGC_MODEL AGC_SOFTWARE "LIST_OF_OPTIONS"

• AGC_MODEL:  One of 1003565, 1003700, 2003100, 2003200, or 2003993 (the default).  However, 1003565 and 1003700 are in fact equivalent, as are 2003200 and 2003993.  But at present, the simulation isn't yet expected to work for Block I AGC's, and we do not yet have any of the schematic diagrams for Block II model 2003100.  So in reality, the only presently-viable choice is essentially 2003993.
• AGC_SOFTWARE:  Any of the software versions present in Schematics/roms/, such as Comanche055, Luminary099, or Borealis.  The default is Validation-hardware-simulation.
• "LIST_OF_OPTIONS":  A quoted list of space-separated options used to override hard-coded values in the testbench files tb-AGC_MODEL.v.  The default is "-DDUMP_ALL".  Here are some of the individual options which can appear in the list:
• -Pagc.GATE_DELAY=N — Specify the NOR-gate propagation delay in nanoseconds.  Default is 20.
• -DSPOOF_SC — Provides a Verilog model for certain signals from the spacecraft.  It is primarily useful in attempting to match simulation results versus simulation results from Mike Stewart's Verilog-based simulation of the AGC.
• -DDUMP_ALL — Dump all AGC signals to the simulation's output dataset.  Note:  The various DUMP_xxx options are mutually exclusive.
• -DUMP_DECODER — Dump signals pertaining to the CPU's instruction decoder to the simulation's output dataset.
• -DUMP_HELPFUL — Dump only those signals I've designated as "helpful" to the simulation's output dataset, which is the same as -DDUMP_DECODER plus a few others.
  
• -DUMP_BACKPLANE — Dump signals from the AGC's backplane to the simulation's output dataset.
  

• It does not attempt to create netlist files, so those must pre-exist.
• The simulation is not run automatically after Verilog source-code compilation, nor is data visualization performed automatically.
• In addition to creation of the whole-AGC simulation file (named AGC_MODEL.vvp), simulation files (module.vvp) are created as well for each of the logic modules comprising the AGC design.
• The defaults are equivalent to:  AGC_MODULE=2003200, AGC_SOFTWARE=Validation-hardware-simulation, "LIST_OF_OPTIONS"="-DSPOOF_SC -DDUMP_HELPFUL", however this is not the actual syntax used for specifiying options.  See the comments in the makefile itself for that syntax and supported options.
  

cd Schematics
make
vvp 2003200.vvp -fst
gtkwave agc.fst

This page is available under the Creative Commons No Rights Reserved License
Last modified by Ronald Burkey on 2025-01-17