sethm / symon

A 6502 System Simulator

SYMON - A 6502 System Simulator

Version: 1.4.0

Last Updated: 11 November, 2023

See the file COPYING for license.

1.0 About

Symon is a general purpose simulator for systems based on the MOS Technologies 6502 microprocessor and compatibles. Symon is implemented in Java. Its core goals are accuracy, ease of development, clear documentation, and extensive test suites for validating correctness.

Symon simulates a complete system with a 1 MHz NMOS 6502 or CMOS 65C02, 32KB of RAM, 16KB of ROM, a MOS 6551 or Motorola 6850 ACIA, a MOS 6522 VIA, and an experimental 6545 CRTC.

Symon has extensive unit tests to verify correctness, and fully passes Klaus Dormann's 6502 Functional Test Suite as of version 0.8.2 (See this thread on the 6502.org Forums for more information about this functional test suite).

Symon is under active maintenance. Feedback and patches are always welcome.

2.0 Requirements

• Java 1.8 or higher
• Maven 2.0.x or higher (for building from source)
• JUnit 4 or higher (for testing)

3.0 Features

Symon can simulate multiple 6502 based architectures. At present, four machines are implemented: Symon (the default), MULTICOMP, BenEater, and a "Simple" machine useful for debugging.

3.1 Memory Maps

3.1.1 Symon Memory Map

• $0000--$7FFF: 32KB RAM
• $8000--$800F: 6522 VIA
• $8800--$8803: MOS 6551 ACIA (Serial Console)
• $9000--$9001: MOS 6545 CRTC
• $C000--$FFFF: 16KB ROM

The CRT Controller uses memory address $7000 as the start of Video memory.

3.1.2 MULTICOMP Memory Map

• $0000--$DFFF: 56KB RAM
• $E000--$FFFF: 8KB ROM
• $FFD0--$FFD1: Motorola 6850 ACIA
• $FFD8--$FFDF: Controller for SD cards

3.1.3 Simple Memory Map

• $0000--$FFFF: 64KB RAM

3.1.4 BenEater Memory Map

• $0000--$3FFF: 16KB RAM
• $5000--$5003: MOS 6551 ACIA (Serial Console)
• $6000--$600F: 6522 VIA
• $8000--$FFFF: 16KB ROM

3.2 Serial Console and CPU Status

The main window of the simulator acts as the primary Input/Output system through a virtual serial terminal. It also provides CPU status. Contents of the accumulator, index registers, processor status flags, disassembly of the instruction register, and stack pointer are all displayed.

The terminal is attached to a simulated MOS 6551 ACIA. It behaves very much as described in the datasheet, with some exceptions:

• The simulated ACIA is permanently connected to the virtual terminal, the Data Carrier Detect and Data Set Ready status bits always indicate a connection is ready.
• The parity, stop-bits and bits-per-character settings are ignored. The ACIA always sends and receives 8-bit characters, and parity errors do not occur.
• The ACIA tries to honour the configured baud rate, but as a special case the default "16x External Clock" rate is interpreted to mean "as fast as possible" (The sample Enhanced BASIC ROM image is programmed for 9600 baud).
• The ACIA ignores the configured state of the Data Terminal Ready pin; it is always ready to receive and transmit.

For more information on the MOS 6551 ACIA and its programming model, see the official datasheet:

• MOS 6551 ACIA

The console supports font sizes from 10 to 20 points.

3.3 ROM Loading

Symon can load any appropriately sized ROM image. The Symon architecture expects as 16KB (16384 byte) ROM image, while the MULTICOMP architecture expects an 8KB (8192 byte) ROM image. Images are loaded via the "Load ROM..." action in the "File" menu. The selected ROM file will be loaded into memory at the correct ROM base address.

3.4 Memory Window

Memory contents can be viewed (and edited) one page at a time through the Memory Window.

3.5 Trace Log

The last 20,000 execution steps are disassembled and logged to the Trace Log Window.

3.6 Simulator Speeds

Simulated speeds may be set from 1MHz to 8MHz.

3.7 Breakpoints

Breakpoints can be set and removed through the Breakpoints window.

3.8 Experimental 6545 CRTC Video

This feature is highly experimental. It's possible to open a video window from the "View" menu. This window simulates the output of a MOS 6545 CRT Controller located at address $9000 and $9001.

By default, the 40 x 25 character display uses video memory located at base address $7000. This means that the memory from address $7000 (28672 decimal) to $73E8 (29672 decimal) is directly mapped to video.

• Address Register (at address $9000)
• R1: Horizontal Displayed Columns
• R6: Vertical Displayed Rows
• R9: Scan Lines per Row
• R10: Cursor Start Scan Line and Cursor Control Mode
• R11: Cursor End Scan Line
• R12: Display Start Address (High Byte)
• R13: Display Start Address (Low Byte)
• R14: Cursor Position (High Byte)
• R15: Cursor Position (Low Byte)

Although the simulation is pretty good, there are a few key differences between the simulated 6545 and a real 6545:

• The simulated 6545 supports only the straight binary addressing mode of the real 6545, and not the Row/Column addressing mode.

• The simulated 6545 has full 16 bit addressing, where the real 6545 has only a 14-bit address bus.

• The simulation is done at a whole-frame level, meaning that lots of 6545 programming tricks that were achieved by updating the frame address during vertical and horizontal sync times are not achievable. There is no way (for example) to change the Display Start Address (R12 and R13) while a frame is being drawn.

For more information on the 6545 CRTC and its programming model, please see the following resources

• CRTC 6545/6845 Information (André Fachat)
• CRTC Operation (André Fachat)
• MOS 6545 Datasheet (PDF)

3.8.1 Example BASIC Program to test Video

This program will fill the video screen with all printable characters.

10 J = 0
20 FOR I = 28672 TO 29672
30 POKE I,J
40 IF J < 255 THEN J = J + 1 ELSE J = 0
50 NEXT I
60 END

4.0 Usage

4.1 Building

To build Symon with Apache Maven, just type:

$ mvn package

Maven will build Symon, run unit tests, and produce a jar file in the target directory containing the compiled simulator.

Symon is meant to be invoked directly from the jar file. To run with Java 1.8 or greater, just type:

$ java -jar symon-1.2.0.jar

When Symon is running, you should be presented with a simple graphical interface.

4.1.1 Command Line Options

Two command line options may be passed to the JAR file on startup, to specify machine type and CPU type. The options are:

• -c,-cpu 6502: Use the NMOS 6502 CPU type by default.
• -c,-cpu 65c02: Use the CMOS 65C02 CPU type by default.
• -c,-machine symon: Use the Symon machine type by default.
• -c,-machine multicomp: Use the Multicomp machine type by default.
• -m,-machine simple: Use the Simple machine type by default.
• -m,-machine beneater: Use the BenEater machine type by default.
• -r,-rom <file>: Use the specified file as the ROM image.
• -b,-brk: Halt the simulator on a BRK instruction (default is to continue)

4.2 ROM images

The simulator requires a ROM image loaded into memory to work properly. Without a ROM in memory, the simulator will not be able to reset, since the reset vector for the 6502 is located in the ROM address space.

ROM images can be loaded with the -rom argument when running Symon from the command line. ROM images can also be swapped out at run-time with the "Load ROM..." item in the File menu.

The "samples" directory contains a ROM image for the Symon architecture named 'ehbasic.rom', containing Lee Davison's Enhanced 6502 BASIC. This serves as a good starting point for exploration.

Note: Presently, EhBASIC only works with the Symon machine architecture, not with MULTICOMP.

4.3 Loading A Program

In addition to ROM images, programs in the form of raw binary object files can be loaded directly into memory from "Load Program..." in the File menu.

Programs are loaded starting at addres $0300. After loading the program, the simulated CPU's reset vector is loaded with the values $00, $03, and the CPU is reset.

There are two very simple sample program in the "samples" directory, for testing.

• 'echo.prg' will echo back anything typed at the console.

• 'hello.prg' will continuously print "Hello, 6502 World!" to the console.

4.4 Running

After loading a program or ROM image, clicking "Run" will start the simulator running.

5.0 Revision History

• 1.4.0: 11 November 2023 - Adds a new machine, the Ben Eater machine. Correct handling of 6551 interrupts, and several 6551 bug fixes. Fixes power-on status of 6502 status register. Fixes a bug with ASCII backspace character not moving the cursor backwards. Finally, "halt on BRK" is no longer enabled by default, but can be set at runtime or by a command line flag. Thank you to Tim Allen and Chelsea Wilkinson for contributions!

• 1.3.2: 8 March 2022 - Minor bug fixes.

• 1.3.1: 12 October, 2019 - Add support for new command line option -cpu <type> to specify one of 6502 or 65c02 on startup, and new option -rom <file> to specify a ROM file to load.

• 1.3.0: 24 February, 2018 - Adds support for 65C02 opcodes.

• 1.2.1: 8 January, 2016 - Remove dependency on Java 8. Now supports compiling and running under Java 1.7.

• 1.2.0: 3 January, 2016 - Add symbolic disassembly to breakpoints window.

• 1.1.1: 2 January, 2016 - Minor enhancement: Allows breakpoints to be added with the Enter key.

• 1.1.0: 31 December, 2015 - Fixed delay loop to better simulate various clock speeds. Added ability to select clock speed at runtime. Status display now shows the next instruction to be executed, instead of the last instruction executed. Added support for breakpoints.

• 1.0.0: 10 August, 2014 - Added "Simple" machine implementation, pure RAM with no IO. Added Klaus Dormann's 6502 Functional Tests for further machine verification (these tests must be run in the "Simple" machine).

• 0.9.9.1: 27 July, 2014 - Pressing 'Control' while clicking 'Reset' now performs a memory clear.

• 0.9.9: 26 July, 2014 - MULTICOMP and multi-machine support contributed by Maik Merten <[email protected]>

• 0.9.1: 26 January, 2014 - Support for IRQ and NMI handling.

• 0.9.0: 29 December, 2013 - First pass at a 6545 CRTC simulation.

• 0.8.5: 30 March, 2013 - ASCII display for memory window. Allows user to select a step count from a drop-down box.

• 0.8.4: 4 March, 2013 - Fix for ZPX, ZPY display in the trace log (change contributed by jsissom)

• 0.8.3: 12 January, 2013 - Added tool-tip text. Memory is no longer cleared when resetting. Fixed swapped register labels.

• 0.8.2: 01 January, 2013 - Fully passes Klaus Dormann's 6502 Functional Test suite!

• 0.8.1: 30 December, 2012

• 0.8.0: 29 December, 2012

• 0.7.0: 9 December, 2012

• 0.6: 5 November, 2012

• 0.5: 21 October, 2012 - Able to run Enhanced BASIC for the first time.

• 0.3: 14 October, 2012

• 0.2: 22 April, 2012

• 0.1: 20 January, 2010

6.0 Roadmap

• 1.2: Better breakpoint support. Symbolic debugging of breakpoints.

• 2.0: Complete rewrite of the UI in JavaFX instead of Swing. Complete assembler and disassembler built in. Ability to attach source code for symbolic debugging.

7.0 To Do

• Feedback (in the form of dialogs, status bar, etc).

• Better debugging tools from the UI, including breakpoints and disassembly.

• UI needs a ton more polish.

• More extensive testing.

• Clean up JavaDoc.

• Implement CMOS 65C02 instructions and NMOS / CMOS mode flag.

• Allow displaying ACIA status and dumping ACIA buffers, for debugging.

• CRTC emulation is very naive. The whole frame is drawn in one CPU step. This should be improved by drawing scan lines during machine steps to approximate real NTSC/PAL refresh rates.

• Symbolic debugging.

8.0 Copyright and Acknowledgements

Copyright (c) 2014 Seth J. Morabito <[email protected]>

• Portions Copyright (c) 2014 Maik Merten <[email protected]>
• Portions Copyright (c) 2022 Tim Allen <[email protected]>
• Portions Copyright (c) 2023 Chelsea Wilkinson <[email protected]>

Additional components used in this project are copyright their respective owners.

• Enhanced 6502 BASIC Copyright (c) Lee Davison
• 6502 Functional Tests Copyright (c) Klaus Dormann
• JTerminal Copyright (c) Graham Edgecombe

This project would not have been possible without the following resources:

• Andrew Jacobs' 6502 Pages, for wonderfully detailed information about the 6502

• Neil Parker's "The 6502/65C02/65C816 Instruction Set Decoded", for information about how instructions are coded

9.0 Licensing

Symon is free software. It is distributed under the MIT License. Please see the file 'COPYING' for full details of the license.

symon's Issues

Top menus dont work on gentoo

I'm on fully up to date gentoo using openjdk and the top options File, View, Simulator don't work. When i try to click them there only open while I'm clicking and i can't click anything in it

could this be usable as a library?

I am asking around since this looks pretty cool. would there be any way to implement this as a library in eg: a minecraft mod to bring back the glory of redpower2

Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.12.4:test

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.167 s
[INFO] Finished at: 2021-09-10T02:39:45+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.12.4:test (default-test) on project symon: There are test failures.
[ERROR]
[ERROR] Please refer to /Users/graeme/Downloads/symon-master/target/surefire-reports for the individual test results.
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException

first exception is
changeCursorStartLineShouldTriggerCallback(com.loomcom.symon.CrtcTest)

% ls -la which mvn
lrwxr-xr-x 1 gharker admin 29 10 Sep 02:24 /usr/local/bin/mvn -> ../Cellar/maven/3.8.2/bin/mvn

% mvn -v
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
Maven home: /usr/local/Cellar/maven/3.8.2/libexec
Java version: 16.0.2, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/16.0.2/libexec/openjdk.jdk/Contents/Home
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.7", arch: "x86_64", family: "mac"
%

Disabling the CRTC cursor disables screen updates

First of all, thanks for making Symon! For someone just getting into 6502 programming, it's great to have a 6502 emulator with a simple memory map, simple I/O devices, that just loads a ROM my assembler toolchain produces.

I have noticed one puzzling behaviour, however, with the CRTC output.

Let's say I have the following program:

; Draw 'A' at the top-left position
lda #$41
sta $7000

I assemble it, I run java -jar symon-1.3.2.jar -rom symon-demo.rom, I enable the Video Window from the View menu, then I hit Run. In the top left corner of the Video window, underneath the blinking cursor, I get a capital A as expected. But that blinking cursor is distracting, let's try turning it off:

 ; select CRTC register 10, Cursor Start/Blink
lda #$0A
sta $9000
; Leave the start scanline at 0, set the blink mode to 01, hide cursor
lda #$10
sta $9000

; Draw 'A' at the top-left position
lda #$41
sta $7000

Now when I assemble and run the ROM, the Video window just stops updating: the cursor stops blinking, the top left position never changes to A. If I close the Video window and then re-open it, it correctly shows the new state.

Possibly related: if I click "Hard Reset" in the UI, the cursor does not resume blinking, even if I close and re-open the window.

jar

Hello,

I was searching for a 6502 tool to try to debug understand an old pcb poker game machine.

Sadly I give up on your prog. Strictly zero interest in installing or building any java things (mvn ????).

I just need "java -jar 6502emu.jar" !!!!!

Just publish the jar file.

Thank you

BUILD FAILURE: An API incompatibility was encountered

% mvn package
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8.373 s
[INFO] Finished at: 2021-09-25T06:51:32+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-jar-plugin:2.6:jar (default-jar) on project symon: Execution default-jar of goal org.apache.maven.plugins:maven-jar-plugin:2.6:jar failed: An API incompatibility was encountered while executing org.apache.maven.plugins:maven-jar-plugin:2.6:jar: java.lang.ExceptionInInitializerError: null

% mvn -v
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
Maven home: /usr/local/Cellar/maven/3.8.2/libexec
Java version: 17, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/17/libexec/openjdk.jdk/Contents/Home
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.7", arch: "x86_64", family: "mac"

Feature request: Command line flag to disable halt on BRK

Hello again!

BBC BASIC processes a command by calling BRK after typing a command and pressing enter.

This means that by default, Symon halts every time I send a new command. At every start, I have to disable it manually in the settings.

What would make things quicker and easier for me is a command line flag (perhaps "--no-halt" / "-nh"?) that would disable the halt on break at the very start.

Default rom.bin not working?

I followed the instructions for getting EhBASIC working and after a while noticed that nothing seemed to be working. I then looked at the memory map and everything was blank.

• copy ehbasic.rom to same folder as .jar; renaming it to rom.bin.
• double click on .jar (on Windows 11 if that matters)...

Memory blocks are empty, no error message, no indication that anything was loaded.

I then attempted to start the .jar using command line java -jar symon-1.3.2.jar and got the following error:

[main] INFO com.loomcom.symon.machines.SymonMachine - No ROM file specified, loading empty R/W memory image

Starting it by appending -rom rom.bin... things working as expected.

(BTW, THANK YOU!!!! I've spent the past several hours trying to get a copy of EhBASIC up and running so I can experiment with it for https://gotbasic.com and thanks to your efforts, SUCCESS!)

Loading EhBASIC...

Can you provide the steps necessary to get EhBASIC loaded/running? I see a screen shot in the main README showing that 2.22 is being utilized; are these from http://retro.hansotten.nl/uploads/leedavison/6502_EhBASIC_V2.22-master.zip and is it the regular or patched version? If not, where would I find a copy of this?

Any assistance with this would be wonderful and, assuming can get it working, I will be sure to include these instructions (and link to this project) on https://gotbasic.com under the EhBASIC section.

Thanks in advance.

Backspace key not deleting

Hello!

I've run into an issue while trying to use the serial terminal with the ACIA 6551 emulator. Transmitting the delete character (0x7F) successfully deletes the last character sent, but seems the backspace character (0x08) doesn't do the same. It just makes an empty space. I don't have the same problem on real hardware.

Is that by design, or is it an issue? It may be a problem with my own code, so let me know if you can't replicate it.

Trying to add crtc to ben-eater based machine doesn't work.

Align the documentation and implementation of the 6551 ACIA

I think it's a great idea for somebody learning assembly programming to be able to use actual real-world data-sheets for reference, and get a feel for what low-level programming is actually like. On the other hand, the whole reason we want to use an emulator to begin with is because real-world hardware is awkward and inconvenient in many ways, so there are good reasons to not implement every quirk of some piece of hardware. However, if the implemented hardware differs from the behaviour described in the data-sheet, it's good to document that so that people know what to expect.

This issue is about deciding how much actual 6551 behaviour Symon should implement, and then making sure that behaviour is implemented, and the remaining differences are documented.

I've been tinkering with Symon's emulated 6551, examining data-sheets and sample code I found online to figure out how it worked and what was going on. The first issue is that there are several data-sheets online for 6551-related chips, and it wasn't clear which one Symon was trying to match:

• The original MOS 6551
• The WDC W65C51S
• The WDC W65C51N

The original MOS 6551 data-sheet specifies (on page 7) that the power-on state of the the Command register is $02, i.e. with the receiver interrupt disabled. The power-on state of the Command register in Symon is $00, so it can't be emulating an original MOS 6551.

The W65C51N data-sheet documents (on page 9) that due to a design fault, the "Transmitter Data Register Empty" bit in the status register is broken and can't be relied upon, and that seems the kind of behaviour that's more annoying than educational, so I think Symon shoudn't emulate the W65C51N.

By elimination, that means Symon emulates the W65C51S.

Comparing Symon's behaviour to the W65C51S data-sheet, I note the following discrepancies:

• The ACIA exposes the state of the "Data Carrier Detect" and "Data Set Ready" serial-port pins in the status register, and it is supposed to generate an interrupt when either one changes state. However, in Symon the ACIA is permanently wired to the VT100 terminal in the main window, so it is impossible for them to change state
• Wikipedia tells me that for half-duplex communication the local computer should activate the "Ready To Send" pin, and wait for the "Clear To Send" pin to be raised by the remote side before sending. For full-duplex communication, the local computer is assumed to always be ready to send, and the RTS pin means "ready to receive" instead. There are bits in the ACIA command register to activate or deactivate the RTS pin, but both sending and receiving work just fine when it's inactive.
• The ACIA has an internal clock generator that can be configured to a number of different baud-rates, or it can be configured to use an external clock. Symon does not mention that it implements an external clock, so I worried that configuring the ACIA to use it might prevent anything from being transmitted. However, "external clock" mode is special-cased to mean "as fast as possible"
• The ACIA can be configured to send a different number of bits per character. However, Symon always sends 8 bits.
• There's a bit in the Command register that controls the "Data Terminal Ready" serial-port pin. The W65C51S data-sheet documents (on page 12) that it "enables all selected interrupts". The MOS 6551 data-sheet describes that flag as "enable receiver/transmitter". It seems like this should be a master switch for the entire ACIA, but in Symon everything works perfectly regardless of the state of this bit.
• Although bit 1 of the Command register defaults to 0 ("rx interrupts enabled"), the ACIA's power-on state is "rx interrupts disabled", which means the should-be-noop instructions lda $8802; sta $8802 actually result in rx interrupts being enabled