// Author David Holdsworth <ecldh@leeds.ac.uk>
// KDF9 program mode emulator

// The most recent version of this program is on-line at:
//        http://sw-pres.computerconservationsociety.org/C-src/KDF9/kdf9.c

// Ths program is written C--, i.e. a strict subset of C without using pointer arithmetic, or struct
//                     but I could not resist the C++ comment convention
// The main emulation routines are also valid as Java
// Has run with gcc on Win98SE, Win10, FreeBSD UNIX and GNU/Linux, and with both gcc and cc on Solaris

// First parameter is the file containing the binary program as generated in file mt.out by kal3.c
// Second parameter is the file of paper tape data (default ptr.txt).

// Verbosity is controlled by -v switch
//     >= 1 -- EXITs, 
//     >= 2 -- jumps taken, 
//      & 2 -- store accesses (only if v&2 != 0)
//     >= 4 -- each instruction,  
//     == 5 -- divide diagnostics
//   6 or 7 -- each instruction and each store access

// Switches are:
//    -v4      set verbosity to 4
//    -t8888   turn on -v7 diagnostics after 8888 instructions
//    -t1234/5 when execution first reaches address 1234 (octal) syllable 5 set -v7 (N.B. must have / char)
//    -f1234/5 when execution first reaches address 1234/5 set -v7 and then abandon after 1000 instructions
//    -a9999   abandon execution after 9999 instructions
//    -d       write the diagnostics to file log.txt rather than standard output (useful with gdb)
//    -o       print direct memory addresses in octal not decimal
//    -m70     will monitor the contents of word 70 (decimal) for changes
//    -Q7      Q7 is printed on the -v4 log, otherwise, the most recently modified Q-store
//    -D       run in director mode, i.e. start at word 4, not 0
//    -T       Findlay compatible tracing -- as for -t
//    -B234    Set octal value 0234 in LS half of word 0 (c.f. TINT B)
//    -I0      Do an even restart on failure (equivalent to TINT;I0 or REACT;.em on KDF9 console)
//    -I1      Ditto but odd restart

// Param 1 is a binary file as generated by kal3.exe, i.e. 6 bytes to a word (big-endian) memory image starting at word 0
// Param 2 is the name of the paper tape data file, default ptr.txt (end message is @, subten is ~, not-equals is #)
// Param 3 is the name of a second paper tape data file, default data.txt

// Paper tape output is on punch.txt (via OUT 8) -- actually all OUT 8 output to a non-zero stream is in this file
// Ops' console query OUT; is answered with N dot em first time.  Second time fails

// There is a very half-hearted attempt to emulate time.

// Floating point rounding introduced Jan 2022 -- including FLOAT

// Overflow on SHA used to be imperfect, and should be OK now.
// Don't know what it does on =+Mq =+Iq =+Cq.  I assume that =+Qq sets overflow, as it works using the nest.

// Not all instructions are implemented, but those that have are all tested.
// Floating point underflow is not handled properly

// An OUT 70 has been introduced for emulation of POST PANACEA, which is invoked iwth a -DPOST on compilation
// It used to be compiled alongside out70.c

// 20 Feb 2017 -- bug discovered in FP addition and subtraction -- now fixed

// July 2019 -- signal implemented to produce illegal("Operator abort") in response to control-C

// November 2020 -- 2nd paper tape reader added

// December 2020 -- Eldon2 disc outs and diagnotstic OUT70 included by default, can be suppressed by -DLITE

// September 2021 -- Slight improvement to diagnostic output