A KIM-1 simulator with the look and feel of the KIM-1 and a debugger to look ‘inside’

Downloads

Beta 0.9!

Source (requires Lazarus)
Executables for Windows and Raspberry PI OS

KIM-1 Simulator

Hans Otten, November 2021 Version 0.9.3 Latest version at http://retro.hansotten.nl
Changelog at bottom.

Applicable license: MIT license

Contents

• Introduction
• How to use
• The debugger
• Compile from sources

Introduction

The KIM-1 simulator is written for my personal use to aid me in developing and testing software for the KIM-1. It is not meant to be a cycle exact complete KIM-1 emulation. Instead it shows as much as possible what is happening inside. So do not expect it to run the typical KIM games on the LED and Keypad.
Just for fun and a tribute, it looks and feels and functions as a real KIM-1. The debugger is what the purpose of this program is. The program is developed on Windows 10 (32 bit executable) and tested and compiled also on Raspberry PI Os (a Debian Linux variant).

What is simulated

• 6502 or 65C02 CPU (only documented behaviour)
• KIM- LEDs and keypad
• TTY in and out with TTY console
• 6530-002 and 6530-003 ROM
• The suppress ‘echo TTYecho’ hardware
• The TTY/LED input bit

Limitations

What the KIM_1 Simulator does not do as the real KIM-1:

• Light the LED segments from the RRIOTs outputs. Instead the SCANDS routine is intercepted and the LEDs show the hex output of location F9 FA FB.The simulation is not cycle exact enough to perform the KIM-1 way of flashing the LEDs. So some First Book of KIM type programs will not work.
• The TTY in and out routines are intercepted and rerouted to an ACIA emulation. See the ACIA routines.
• The upper pages are not mapped to the lower pages as in most KIM-1 configurations. The vectors at FFFA etc are pointing to the KIM-1 ROM vectors, so RESET. NMI and IRQ work.
• Tape hardware is not emulated.
• No hardware single-step via NMI, the debugger has much better facilities for that/
• The CPU runs as fast the host CPU allows, and lets the host operating system do some work like key and display and other applications running and continue the emulation loop until the user stops the 6502 CPU.
• The CPU emulation may not be perfect, only valid opcodes and documented behaviour is implemented, especially ADC and SBC have many, not emulated here, undocumented issues.
• IRQ handling is not present in this version, see planned enhancements

Enhancements

The KIM-1 Simulator is a KIM-1 with:

• 6502 or 65C02 CPU (make the choice in the Debugger)
• RAM to $1400
• RAM from $2000 to $E000
• ACIA 6850 at $1600 (equal to Corsham’s I/O card)
• ROM at $F000 with ACIA routines
• Pages E and F are not mapped to page 0 and 1 as in most expanded KIM-1’s.
• LEDs and switches to the user RRIOT Port A and B
• Switch between TTY and LED/keypad

To do, planned expansions

• Tape emulation: intercept tape read and write ($1800, $1873) and reroute to a tape file emulation
• IRQ and 6530 timer support
• Enhance the TTY console with e.g. VT100 emulation. Now it is a simple teletype, with Carriage Return and Linefeed .
• Better documentation …

How to use as KIM-1

Start the emulator main program and push the ‘Run’ icon. Then press the RS key on the keyboard (or type R).
After that the LEDs awake and the keyboard is operational as a KIM-1.

  [0] to [F]  -   Sixteen keys used to define the hex code
                  of address or data

  [AD]  -   selects the address entry mode

  [DA]  -   selects the data entry mode

  [+]   -   increments the address by +1 but does
            not change the entry mode

  [PC]  -   recalls the address stored in the Program
            Counter locations (PCH, PCL) to the display

  [RS]  -   causes a total system reset and a return to
            the control of the operating program

  [GO]  -   causes program execution to begin starting
            at the address shown on the display

  [ST]  -   terminates the execution of  a program and
            causes a return to the control of the
            operating program

Besides pressing the keys on the KIM keypbaord on sthe screen you can aslo sue the PC keyboard:

  0-9 : key 0 - 9
  a-f : key A - F
  A-F : key A - F
  +   : +
  < : AD >   : DA
  P,p : PC
  G,g : GO
  S,s : ST
  R,r : RS
  S,s : ST

Load and Save

The menu has Load and Save functions, you can load and save to many 8 bit binary formats as MOS papertape, Intel HEX, Motorola S record, binary and simple hex.

TTY console mode

Press the TTY console switch to let the KIM simulator use a glass teletype in a console window. The standard KIM user interface is shown, see the manual hwo to use.
Note: set the PC keybaord to CAPS Lock, only uppercase is used in the KIM monitor.
Note the menu options to record a session, (Load Text to Console) or play (Save text from Console, followed by Stop saving text ) a text file in the console.
This is in fact the same functionality as a teletype with high speed papertape punch or reader. You can sue this to load and save Basic programs as ASCII text files.

The debugger

From the menu Simulator choose Debugger to show the debug window. This windows has step/single step/run buttons, shows the registers and flags, zeropage, memory and the stack. The Trace logfile facility may store a trace of what happened.The disassembler part shows a disassembly.

Several refresh buttons let you update the current state of the machine.

Single step, RUN, trace log

First set the PC to the first instruction of the program to test.

• Step in: execute next instruction
• Step over: execute next instruction but skip JSR subroutines
• RUN: execute at maximum speed ( wait 0) or slow (wait x seconds between steps), use the STOP button to halt execution
• Step n: execute n instructions full speed
• Run to: execute instructions full instructions until the breakpoint location is reached or STP pressed
• Trace log on/off: first set the Trace log file directory from the file Menu, then use any Step to have every instruction logged with status in the logfile and the tracelog. Note that this slows down execution a lot and the files can become large. So clean up regularly!
  The file name of the log is set to KIM1SIMtrace(datestamp).log.

Symbol table and the disassembler

The disassembler shows locations/labels in hex format. If the assembler symbol table is available (TASM can produce that as blank delimited list) you can load it and do some symbolic disassembly.
Load and show the symbol table from the menu “Symbol table”

RRIOT status display

From the menu Simulator choose RRIOT to show a windows with the current RRIOT status or you can enter new values for the various registers.
Press Refresh to update to the current state.
The 6530-002, responsible for the KIM-1 hardware, is decoded to the relevant in/output bits.

Compiling and building the simulator from source

Prerequisites

• A modern PC and operating system. Windows 10 is where the software has been developed, Raspberry OS /Linux have seen limited tested for now. MacOS may work, untested
• Development (Compile and run everywhere!) with Freepascal and Lazarus IDE, see https://www.lazarus-ide.org/
  Any version above 2.0 will be OK, No OS dependent functions are used afaik.
• The archive with the KIM-1 Simulator sources KIM1SIMs09.zip (or higher version).
• Unpack in a folder, avoid blanks in folder and filenames
• Start the IDE by clicking on KIM1SIM.lpi
• Build with Run – Build
• On Windows a Setup installable can be made with Inno Setup, KIM1SIM.iss and compile with Inno Studio.

The include files with KIM ROM and 6502 code

If and when the ACIA routines and other routines in the KIM1SIM ROM are altered you need to rebuild the KIM1SIMrom.inc file.
Subfolder ‘romtoconst’ contains the binary of the original KIM ROMS (6530-002.bin, 6530-003.bin) and the additional ROM binary with ACIA routines (kimsimrom.bin).
The .inc files for the compilation of the KIM1SIM, to be placed in the main folder, are created with the program creatINC.exe, a console application (source included here).
Copy the the tree .inc files to the main folder and compile the KIM1SIM program again.

D:\myfiles\development\kim-1 simulator\romtoconst>creatINC.exe
kimrom002 include file created
kimrom003 include file created
kimsimrom include file created

Folder KIM-1 assembler sources

Here you find assembler sources of various tests. Assemble with TASM, included in the folder. See TASM.HTML for information.
It is convenient to compile from an editor like Notepad++, plugin NPPEXEC
with command to create intel hex file

"D:\myfiles\development\kim-1 simulator\KIM-1 assembler sources\tasm" -65 -x3 -g0 -s $(FILE_NAME) $(NAME_PART).ihex  $(NAME_PART).lst  -s $(NAME_PART).sym

or to create a binary file with

"D:\myfiles\development\kim-1 simulator\KIM-1 assembler sources\tasm" -65 -x3 -g3 -s $(FILE_NAME) $(NAME_PART).bin  $(NAME_PART).lst  -s $(NAME_PART).sym

Note that also symbol files are generated which can be read in by the debugger in the KIM-1 Simulator.

• kim1sim6502test.asm : The 65(C)02 test, a program that runs on the TTY console
• kimsimrom.asm : the source of the KIM-1 Simulator ROM at $F000 with ACIA support for KIM-1 TTY in/out
• Various snippets used to test the cpu emulation

Changelog

• V 0.9 October 2021 First public beta
• V 0.9.1 November 2021 Fixed key 0 bug (Thanks Liu!)
• V 0.9.2 November 2021 Scroill bars in Laod/Save dialog boxes added, Linux tests
• V 0.9.3 November 2021 Added CC65 format symboltable load, added search in symbol table, fixed label display error in disassembly