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

Console, with choice of colors of font and background:

KIM-1 built in ROM tape load and save:

Downloads

Version 1.1.4 April 2022

Setup for Windows and executable for Raspberry PI OS and Ubuntu
Source (requires Lazarus IDE 2.x))

KIM-1 Simulator

Hans Otten, 2019- 2022, Version 1.1.4 Latest version at http://retro.hansotten.nl
Changelog at bottom.

Applicable license: MIT license

Contents

• Introduction
• Installation
• How to use
• Console
• The debugger
• The profiler
• 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 and Ubuntu 20.04.3 LTS. Since source is available, it will run anywhre Lazarus IDE is available.

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
• KIM-1 Tape load and save ti audio

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 and documented opcodes are 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 after version 1.0

• IRQ and 6530 timer support
• Testing and bugfixing
• Better documentation …

Installation

Windows

Run KIM1SIMsetup.exe or use the KIM1SIM.EXE + KIM1Simulator.html file in a folder of choice.

Raspberry Pi OS

Execute KIM1SIM from the Raspberry Pi folder

Ubuntu 20.04.3 LTS

Execute KIM1SIM from the Ubuntu folder

Note that the font used is Courier New. Install ttf cour.ttf on Linux in .home/.fonts to prevent substitution with artefacts

Other platforms
Install Lazarus (Version 2 and higher) and build from source.

After installation

Start the KIM-1 Simulator and choose Settings to set the default working directory. Otherwise files may appear at locations you do not want!

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 keybaord on the screen you can also use 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

Console

Press the TTY swicth and you have a console terminal. The KIM-1 teletype commands now work and also programs line KB9 Basic can be used. See the Console chapter below.

KIM-1 Tape load and save

The KIM-1 tape load ($1873) and save ($1800) programs are emulated.

Fill in the tape ID and optionally start and end address as documented in the KIM-1 User manual.

Start the Save at $1800 and the laod at $1873 with the KIM-1 monitor.

You will be prompted for file to load or save.

Default working directory and other settings

Use the menu Settings – Set default work folder to choose a folder for all files created or used by the emulator. The settings are saved between sessions.

Default settings config file : “/home/(user)/.config/KIM1SIM.cfg” or C:\users\(user)\Appdata\local\KIM1SIM.cfg”

Loaded at startup, updated via the Settings menu.

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 how to use.
Note: set the PC keyboard 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 use this to load and save Basic programs as ASCII text files. Or use the KIM-1 tape routines built in KB9 Basic!

The console

The console is an emulation video terminal (ANSI color, subset) connected to an ACIA (a Motorola 6850) in the KIM-1. The KIM Monitor is patched to send or receive via the ACIA and is transparant to the user of the KIM-1 I/O routines (even the quirlks like flags and returned register values!)

Keyboard input, when the console window has focus, is sent to the serial input of the ACIA. No local echo. The KIM-1 monitor only accepts uppercase (hint: Caps lock!), user programs are free to use upper or lowercase.

Characters sent tot to ACIA output are received by the console window and handled as a VT100 would do, a subset of the ANSI/VT100 is implemented.
All keys of the PC are usable, SHIFT works. Note the translation of codes from the PC keyboard to ASCII characters is for the US International keyboard.
Other mappings are possible by changing the routine in console.pas: procedure TFconsole.FormKeyDown

Received characters by the console are handled as follows, a subset of the ANSI set.

Single control character

$01 : CursorHome 
$04 : CursorRight 
$05 : CursorUp 
BS  : Backspace 
TB  : Tab 
LF  : LineFeed 
FF  : ClearScreen 
CR  : CarriageReturn 
$13 : CursorLeft 
$16 : DeleteToEndofLine 
$18 : CursorDown 
DEL : Backspace  

ESC sequences

ESC[K             Clear from cursor to the end of the line
ESC[0K            Clear from cursor to the end of the line
ESC[1K            Clear from the beginning of the current line to the cursor
ESC[2K            Clear the whole line
ESC[J             Clear the screen from cursor
ESC[0J            Clear the screen from cursor
ESC[1J            Clear the screen until cursor position
ESC[2J            Clear the screen and move the cursor to 0-0, defined sprites are removed, loaded bitmaps are kept

Insert / Delete

ESC[1@            Insert a blank character position (shift line to the right)
ESC[1P            Delete a character position (shift line to the left)
ESC[1L            Insert blank line at current row (shift screen down)
ESC[1M            Delete the current line (shift screen up)

Move cursor

ESC[H             Move to 0-0
ESC[f             Move to 0-0
ESC[s             Save the cursor position 
ESC[u             Move cursor to previously saved position 
ESC[(Row);(Col)H  Move to row,column
ESC[(Row};(Col)f  Move to row,column
ESC[nA            Move the cursor up n lines
ESC[nB            Move the cursor down n lines
ESC[nC            Move the cursor forward n characters
ESC[nD            Move the cursor backward n characters

Attributes

ESC[m             Reset all attributes
ESC[0m            Reset all attributes
ESC[1m            bold
ESC[4m            underline
ESC[5m            italics
ESC[7m            Turn on reverse color
ESC[27m           Turn off reverse color

Color attributes

color     FG       BG      FG high  BG high 
--------------------------------------------
black    ESC[30m  ESC[40m  ESC[90m  ESC[100m
red      ESC[31m  ESC[41m  ESC[91m  ESC[101m
green    ESC[32m  ESC[42m  ESC[92m  ESC[102m
yellow   ESC[33m  ESC[44m  ESC[99m  ESC[103m
blue     ESC[34m  ESC[44m  ESC[94m  ESC[104m
magenta  ESC[35m  ESC[45m  ESC[95m  ESC[105m
cyan     ESC[36m  ESC[46m  ESC[96m  ESC[106m
black    ESC[37m  ESC[47m  ESC[97m  ESC[107m

FG = foreground
BG = background
High = higher intensity

• Printable character (>= $20): placed on screen where te cursor is, cursor moved to next position
  Wrap around at end of line, screen scroll up when bottom line is reached
• CR Carriage Return: cursor moved to beginning of line
• LF LineFeed: cursor moved one line down, screen scroll up when bottom line is reached
• FF FormFeed: clear screen, position cursor top left
• ESC sequences start with the ESC character

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 or watchpoint location is reached or STOP pressed
• You can set 1o code breakpoints, 10 memory watch points and wacthpoinst on registers A,X,, Y and Stackpointer, press the Breakpoints and Watches button to show the form to fill in as desired.
• 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”. Supported symbol table formats: TASM 32 bit and CA65 (part of CC65 suite).

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, it is not updated realtime.
The 6530-002, responsible for the KIM-1 hardware, is decoded to the relevant in/output bits.
Note that the simulator does not perform the KIM-1 LED/key functions this way. Code for output to the LED displays is currently present but commented out in the source.
Timing limiting is essential for this to work, the simulation now runs as fast as the host CPU can deliver.

The Profiler

Available from the ‘watches and breaks’ form or from the Window menu

This facility keeps track (once activated with the Profiling Check box) how much an instruction is executed,
Independent of the debugger, always available.

Use the Refresh button to see the current state, not automatically updated so it is no a high performance hit.
Any opcode, from o to 255, is counted. The display shows the maximum 65C02 instruction set.

You can save the profiler data to a CSV file, with instruction mnemonic and number of times executed per line.
Invalid instructions are marked as ‘Unknown’.

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 and Ubuntu have been tested. MacOS may work, but is untested
• Development (Compile and run everywhere!) with Freepascal and Lazarus IDE, see https://www.lazarus-ide.org/
  Any Lazarus version above 2.0 will be OK.
• 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.

Note that the font used is Courier New. Install ttf cour.ttf on Linux in .home/pi/.fonts to prevent substitution with artefacts

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 Scrollbars in Load/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
• V 0.9.4 December 2021 emulated getch in kimsinrom.asm now returns with Y=$FF
• V 0.10.0 January 2022 Added 10 breakpoints and 10 watch points in debugger
• V 0.10.1 January 2022 Save memory bug solved
• V 0.10.2 January 2022 Watchpoints on registers and Stackpointer added
• V 0.11.0 January 2022 Profiler (count how much an opcode is executed) added, Windows main menu to get fast to one of the forms
• V 0.12.0 February 2022 Console cursor control (not finished yet)
• V 0.13.0 February 2022 Main screen updated, more help entries. Console updates (on screen menu for colors) and KIM-1 tape load and save emulation
• V 0.13.1 February 2022 Tested on Ubuntu, small updates and bugs fixed
• V 0.13.2 February 2022 Settings for work directory, KIM tape load/save added to Save/Load memory
• V1.0 February 2022, all planned functionally implemented (the console is now ANSI color enabled)
• V1.0.0.1 February 2022, NUM lock numeric keypad added, request for keyboard layout tests
• V1.1.1 KIMDLE works: timer and KIM keyboard fixes (no key return $15)
• V1.1.2 Settings for keyboard layout (US International and German for now), key handling KIM keypad and keyboard/console improved, free running timer
• V1.1.4 April 2022 Improved design, use of debugger Run buttions stops main Run/Stop run state