Version: 3.6.0
Date: 2020/08/01


I. Introduction

sim990 is a simulator for the TI 990 computer. It supports the TMS-9900,
990/10, 990/10a and 990/12 instruction sets, TILINE, memmory mapping, and CRU
expansion chassis. This version runs TX990, DX10, DNOS and DOCS diagnostics.


II. Build sim990

Lunix/Unix:

$ make

The make attempts to figure out which system to make for using uname.

WinBlows:

$ nmake nt


III. To run sim990

$ sim990 [-options] [object.file]

Where options are:

   -c configfile - File from which to read configuration information.
                   The command format is the same as command mode.
   -m model      - CPU model, model = 4, 5, 9, 10, 10A or 12.
   -p            - Run in Panel mode.
   -r file.rom   - Rom for high memory, default ti990-[model].rom.
   -s memsize    - Size of memory in bytes (can use K and M, eg. 256K).
   -w NN         - Size of panel window.

In command mode the simulator commands are:

   a = attach device, syntax:

         a [device[/switches] devaddr intlvl {device.file | device.port}]

      The command with no arguments will display the attached devices.

   B = begin trace pc (default 0), syntax:

         B location

   b = boot from device, syntax:

         b[r][n] device

   c = clear breakpoint/watchpoint

         c b|w

   D = disassemble instructions: syntax:

         D[r page] location [count]

   d = display memory, syntax:

         d[r page] location [length]

   E = End trace pc (default >1FFFFE), syntax:

         E location

   g = go (run program)

   h = help

         h [command | *]

   i = instructions, dumps instruction buffer (last 60 instructions)

   k = set breakpoint, syntax:

         k location

   l = load program, syntax:

         l[n] [loadaddr] object.file

   L = Lookup IDT and Symbol names.

         L [IDT[:SYM]]

   m = modify memory, syntax:

         m[r page] location newvalue

   N = disassemble next instructions, syntax:

         N [count]

   n = display next memory locations, syntax:

         n [length]

   o = Set CPU otions, syntax:

         o [options]

   p = set pc, syntax:

         p location

   q = quit the simulator

   r = reset the system

   s = single step program

   t = trace program, syntax:

         t[r] [count] trace.file

   W = set watchpoint, syntax:

         W location

   w = set workspace pointer, syntax:

         w location

   z = toggle panel mode, syntax:

         z [windowlen]

Where:

   device      = ce  - EIA console, default for /4, /9, /10 and /12 CPUs.
		 c2  - 9902 console, default for /5 and /10a CPUs.
		 c3  - 9903 console.
		 csn - ASR 733 cassette, n = 0-1.

		 pe  - EIA printer.
		 p2  - 9902 printer. 990/5 and 990/10a port.
		 p3  - 9903 printer. 990/5 port.
		 p4n - CI403 printer, n = 0-11.
		 pp  - Parallel printer.

		 sen - EIA serial device, n = 0-11.
		 s2n - 9902 serial device, n = 0-2. 990/5 and 990/10a port.
		 s3n - 9903 serial device, n = 0. 990/5 port.

		 a1n - CI401 serial device, n = 0-11.
		 a2n - CI402 serial device, n = 0-11.
		 a3n - CI403 TILINE serial device, n = 0-11.

		 cp  - Card punch.
		 cr  - Card reader.

		 fn  - FD800 floppy, n = 0-3.
		 vn  - 911 VDT, n = 0-11.
		 dn  - TILINE DISK, n = 0-11.
		 mn  - TILINE TAPE, n = 0-11.

	 For TILINE DISK, TAPE and CI403 devices:

		 devices 0-3  first controller address.
		 devices 4-7  second controller address.
		 devices 8-11 third controller address.

		 Checks are made to inusure that all devices on a controller
		 have the same device address and interrupt. For disks a check
		 is made that all disks have the same geometry (type) on the
		 controller. Excepet for SCSI and FD1000/FD800 disk controllers.
		 FD800 disk imagess are supported on the FD1000 TILINE
		 controller with or without geometry overhead information.

   switches    = Device specific switches:

	       CONSOLES and SERIAL terminal devices:
	          /e      - Emulate Terminal. Syntax:
			    /e=TERM[:print.file]
			    TERM:
				A733 - ASR 733, Enables Cassette support.
		  		H19  - Heath H19.
				V931 - TI 931 VDT.
				V940 - TI 940 VDT.
			    The [:print.file] specification allows for terminal
			    attached printers. Output is written to the file
			    print.file.
		  /l      - Logoff session on disconnect, telnet connections.
		  /r      - Set terminal to raw for real terminals. 
		  /s      - Display status line on line 25, V931 and V940 only.
		  /t      - Run as a telnet session.
		  /u      - Upcase keys.

	       911 VDT:
		  /l      - Logoff session on disconnect.
		  /u      - Upcase keys.

	       TAPE:
		  /c      - Create tape file.
		  /r      - Read only.

	       DISK:
		  /r      - Read only.
		  /m      - Specify disk model for real disk devices.
			    The geometry specified must match the real device.
			    /m=MODEL
			    MODEL:
				CMD16 CMD80 DS10 DS25 DS31 DS50 DS80 DS200
				DS300 FD1000 SI470 WD500 WD500A WD800-18
				WD800-43 WD800A-43 WD800A-100 WD900 MSU2
				MSU2A CP3540 ST312 

	       CASSETTE:
		  /c      - Create cassette tape file.

	       CARD PUNCH:
		  /t      - Trim trailing blanks.

   devaddr     = Device address. CRU addresses greater than or equal to >0400
   		 and less than >1F00 are assigned to an expansion chassis.

   intlvl      = Device interrupt level.

   device.file = File to be associated with non-VDT device.
		 A "NULL" specification means that the device is available but
		 is offline.
		 A "LOOP" specification means that the device is a
		 communications loopback device.
		 For console devices specify "TTY".
		 For tape devices real tape drives under Unix/Linux are
		 supported, eg. /dev/nst0.
		 For disk devices real disk drives under Unix/Linux are
		 supported, eg. /dev/sdf.

   device.port = TCP port to be associated with VDT device and serial terminal
		 telnet sessions.

   location    = Memory location. May be specified as a decimal, hex or
   		 symbolic value. Symbolic values have the format:
		    IDT[+/-num] | IDT:SYM[+/-num]

   newvalue    = Contents of displayed memory replaced with value.

   loadaddr    = Load address for relocatable objects.

   object.file = File containing 990 object.

   trace.file  = File containing the instruction trace.

   count       = Count of instructions to process before beginning trace.

   options     = CPU options:

   		 s    - Toggle Segement Protection.
		 t    - Toggle TILINE.

All numbers can be in either decimal for hexadecimal. Hexadecimal numbers are
indicated with a beginning greater than (>) sign or zero (0).

The 'n' option for the non-ROM boot and load commands means do not start. This
allows you to set breakpoints, etc. before execution begins.

The 'r' option for the boot command uses the ROM image to boot. The 990/12 ROM 
will occasionally fault due to not having the WCS implemented.

The 'r' option for the trace command includes the registers in the trace.

The 'r page' option for the display, disassemble and modify memory commands
selects the ROM page. The /5 and /12 CPUs support ROM pages greater than zero.

Panel mode operation displays the current registers, front panel value,
operation status and workspace. The panel display is updated after every 10
clock ticks. Also, the console (serial terminal) is displayed under the panel
display.

When the simulator is running the simulated program you enter the command break
character, CTRL-E, to regain command mode. The program is suspended and the
command prompt is displayed. You may enter any of the above commands and the
go command "g" resumes the simulated program.


IV. How to run the 733 ASR TXDS system

The 733 ASR TXDS system, asr733sys.fpy, is the standard TI distribution. The
system supports the TI 733 ASR terminal with two cassettes and two floppy disks.

To run TXDS interactively:

   $ sim990

   TI 990 Simulator VERSION: /4 CPU 56K

   : a ce/ue=A733 0 6 TTY
   : a cs0 0 6 NULL
   : a cs1 0 6 NULL
   : a f0 >80 7 asr733sys.fpy
   : b f0

 TX990         2.4.0  79.091    
MEMORY SIZE(WORDS): 28672    AVAILABLE: 20006

Enter an "!" (Exclamation point) to start the TXDS control program:

!
 TXDS          2.4.0  79.091 

PROGRAM: 

To run TXDS using a configuration file:

   $ sim990 -c txds.cfg

   TI 990 Simulator VERSION: /4 CPU 56K

 TX990         2.4.0  79.091    
MEMORY SIZE(WORDS): 28672    AVAILABLE: 20006

The configuration file, txds.cfg, contains:

   a ce/ue=A733 0 6 TTY
   a cs0 0 6 NULL
   a cs1 0 6 NULL
   a f0 >80 7 asr733sys.fpy
   b f0

To terminate you enter the command break character, CTRL-E, which puts the
simulator back into command mode, and enter the "q" command to terminate.


V. How to run the FORTH system

The supplied FORTH system disk, forthsys.fpy, is based on the 1983 version of
fig-FORTH. There is also a data disk, forthdat.fpy, that contains several
screens.

To run FORTH interactively:

   $ sim990

   TI 990 Simulator VERSION: /4 CPU 56K

   : a pe >40 4 print.out
   : a f0 >80 7 forthsys.fpy
   : a f1 >80 7 forthdat.fpy
   : b f0

   9900 FORTH 1.0.0

To run FORTH using a configuration file:

   $ sim990 -c forth.cfg

   TI 990 Simulator VERSION: /4 CPU 56K

   9900 FORTH 1.0.0

The configuration file, forth.cfg, contains:

   a pe >40 4 print.out
   a f0 >80 7 forthsys.fpy
   a f1 >80 7 forthdat.fpy
   b f0

To terminate you enter the command break character, CTRL-E, which puts the
simulator back into command mode, and enter the "q" command to terminate.


VI. How to run the FOCAL system

The supplied FOCAL system disk, focal.fpy, is based on the Digital PDP-8
Focal.

To run FOCAL interactively:

   $ sim990

   TI 990 Simulator VERSION: /4 CPU 56K

   : a pe >40 4 print.out
   : a f0 >80 7 focal.fpy
   : b f0

   FOCAL/990 execution begins
   *

To run FOCAL using a configuration file:

   $ sim990 -c focal.cfg

   TI 990 Simulator VERSION: /4 CPU 56K

   FOCAL/990 execution begins
   *

The configuration file, focal.cfg, contains:

   a pe >40 4 print.out
   a f0 >80 7 focal.fpy
   b f0

To terminate you enter the command break character, CTRL-E, which puts the
simulator back into command mode, and enter the "q" command to terminate.


VII. How to run DX10

The TILINE disks on the web site contain several version of DX10. To run the
3.6.0 version you can execute the following steps:

   $ sim990 -m 10 -s 512K

   TI 990 Simulator VERSION: /10 CPU 512K

   : a ce/u >0 6 TTY
   : a v0/ul >100 10 2000
   : a v1/ul >120 8 2001
   : a pe >60 14 print.out
   : a d0 >F800 13 DX10_3.6.0.dsk
   : a m0 >F880 9 NULL
   : b d0

The DX10 system boots and the display is on 911 VDT. To access the terminal
you telnet to the port, 2000 in the v0 attach, in another window:

   $ telnet localhost 2000

When telnet connects you'll be able to login by entering F10 (Gold) and
"!" (Exclamation point).

The first time you connect you will see a display that shows the "message of
the day" file. Enter F9 (CMD) to terminate the display. Now you will see a 
message that the system has not been initialized. Press enter and you will get
the SCI menu screen. At this point you enter the command "IS" and enter. You
take the defaults on all prompts and enter the appropriate date and time. When
you see the "WARMSTART PROCEDURE COMPLETE" message press enter to terminate the
procedure. Now reenter F10 and "!" and you will get the user log in screen.

After logging in you will see the "message of the day" file. Enter F9 (CMD) to
terminate the display. Then you will get the main SCI screen.

You can also put the above commands into a config file and boot as follows:

   $ sim990 -m 10 -s 512K -c dx10.cfg

To login on the console (the window in which sim990 is running) you enter an
escape character and "!". The console is configured as a TTY, not a VDT.

The SYSTEM account is:

User ID: SYS001
Passcode: SYSTEM


VIII. How to run DNOS

The TILINE disks on the web site contain several version of DNOS. To run the
1.3.0 version you can execute the following steps:

   $ sim990 -m 12 -s 512K

   TI 990 Simulator VERSION: /12 CPU 512K

   : a ce/u >0 6 TTY
   : a v0/ul >100 10 2000
   : a v1/ul >120 8 2001
   : a cr >40 4 NULL
   : a pe >60 14 print.out
   : a d0 >F800 13 DNOS_1.3.0.dsk
   : a m0 >F880 9 NULL
   : b d0

The DNOS system boots and the display is on 911 VDT. To access the terminal
you telnet to the port, 2000 in the v0 attach, in another window:

   $ telnet localhost 2000

When telnet connects you'll be able to login by entering F10 (Gold) and
"!" (Exclamation point).

The fist time you connect you will see an intialize the date and time screen.
Enter the appropriate date and time. Then you will get the user log in screen.

After logging in you will see the "message of the day" file. Enter F9 (CMD) to
terminate the display. Then you will get the main SCI screen.

You can also put the above commands into a config file and boot as follows:

   $ sim990 -m 12 -s 512K -c dnos.cfg

To login on the console (the window in which sim990 is running) you enter an
escape character and "!". The console is configured as a TTY, not a VDT.

The SYSTEM account is:

User ID: SYSTEM
Passcode: SYSTEM


IX. Known problems/Limitations/Notes

1. The CPU diagnostics clock test will fail as the instructions are executed
   at a much faster rate than the original hardware. Also, if the clock varies
   due to system load or other factors and if you have POSIX thread support;
   you can run with the "-R" option and this will attempt to dispatch the clock
   thread as a real time process at a higher priority. This will require you 
   to run sim990 as a super user process.

2. Only the /12 instruction CRC and Writeable Control Store (WCS) have not been
   implemented. The Segment Protection feature passes the diagnostics; but, has
   issues running the operating systems and is currently disabled by default.

3. Windows TELNET doesn't generate ANSI sequences for the function buttons.

4. The Card Punch was not supported by TI as an off the shelf device. The TI
   internal systems DID have card punches. However, I've not seen any 
   documentation for one; so I implemented it using the card reader interface
   as a model.

5. The CI401 only supports lines configured as switched.

6. When attaching real tape devices the tape drives must be loaded and online
   or the open will fail.

7. When attaching real disk drives you may have to run as root or change the 
   device permissions to allow normal user access.
