jetsetilly / gopher2600

Gopher2600 is an emulator for the Atari 2600 games console

Gopher2600

Gopher2600 is an emulator for the Atari 2600 written in Go.

See here for Current Status

Accuracy is very high and and there are no known problems with the emulation of the 6507, TIA or RIOT chips.

The key features of the emulator:

• Support for many of the known cartridge formats
  • emulation of the Supercharger - supports loading from WAV files
• Emulation of the ARM7TDMI as found in the Harmony cartridge
  • Preliminary support for the ARMv7-M as used in the UnoCart and PlusCart is also included
• Network access through PlusROM emulation
• AtariVox and SaveKey support
  • Speech support via Festival
• CRT TV Effects
• Flexible screenshot features
• Accurate audio reproduction (and optional stereo output)
• Support for common TIA revisions
• Implementation of Movie Cart
• Gameplay rewinding
• Tracker/Piano Keys visualisation
• Gameplay recording and playback
• Support for (and auto-detection of) the stick, paddle, keypad and also Sega Genesis style controllers
• ROM selector with live emulation preview and optional support for boxart and the standard stella.pro file

The graphical debugger:

• CPU and Color Clock level interaction
• Breakpoints, traps, watches on various CPU, TIA and RIOT targets
• Terminal interface (headless operation optional)
• Advanced ARM monitoring
  • Performance profiling
  • Source code inspection and breakpoints
  • DWARF support (global & local variable inspection)

Logo is based on Gopherize.me which itself is based on the work of Ashley McNamara and is licensed under the Creative Commons.

Documentation

User documentation for the emulator can be found in the Gopher2600-Docs repository and in particular the live wiki.

Development & Maintenance documentation can be found in the Gopher2600-Dev-Docs repository. Also, source level documentation (for the most recent release) can be found on go.dev.

Example Screenshots

The following screenshots were taken in playmode with CRT effects enabled.

ROMs shown: Pitfall; Chiphead; Thrust; Man Goes Down; Soul of the Beast; Egypt 2600BC ; Draconian; Zookeeper

Resources used

The Stella project (https://stella-emu.github.io/) was used as a visual reference for video output. In the absence of VCS hardware (which I didn't have during initial TIA development) Stella was a good alternative for checking the accuracy of video output.

In addition, Stella was used as reference in the following areas:

• During the development of the CDF cartridge formats. These recent formats don't seem to be documented anywhere accept in the Stella source.

• Cartridge fingerprints for ParkerBros, Wickstead Design, SCABS, UA and JANE.

• As a reference for the audio implementation (the 6502.ts project was also referenced for this reason).

• Fingerprint patterns for automated controller/peripheral selection.

In all these instances, primary sources of information could not be found.

(Earlier revision of Gopher2600 used Stella a reference for the EF cartridge format. However, the implementation has been vastly simplified by declaring EF to be a nothing more than a 64k Atari ROM. The discussion that led to this revelation can be found in the link below.)

https://forums.atariage.com/topic/346341-64ksc-multi-sprite-roms-error-out-in-stella-for-me/page/2/#comment-5188396

Many notes and clues from the AtariAge message boards. Most significantly the following threads proved very useful indeed:

• "Cosmic Ark Star Field Revisited"
• "Properly model NUSIZ during player decode and draw"
• "Requesting help in improving TIA emulation in Stella"
• "3F Bankswitching"
• "TIA Sounding Off in the Digital Domain"

And from and old mailing list:

• "Games that do bad things to HMOVE..." https://www.biglist.com/lists/stella/archives/199804/msg00198.html

These mailing lists and forums have supplied me with many useful test ROMs. I aim to package these up and distribute them sometime in the future (assuming I can get the required permissions).

Extensive references have been made to Andrew Towers' "Atari 2600 TIA Hardware Notes v1.0"

Cartridge format information was found in Kevin Horton's "Cart Information v6.0" file (sometimes named bankswitch_sizes.txt)

The WF8 format discussed here on AtariAge

https://forums.atariage.com/topic/367157-smurf-rescue-alternative-rom-with-wf8-bankswitch-format/

The "Stella Programmer's Guide" by Steve Wright is of course a key document, used frequently throughout development.

Colour values for NTSC and PAL television signals taken from https://www.qotile.net/minidig/docs/tia_color.html

The TIA Audio implementation is based almost entirely on the work of Chris Brenner.

https://atariage.com/forums/topic/249865-tia-sounding-off-in-the-digital-domain/

Musical information as seen in the tracker window taken from Random Terrain.

https://www.randomterrain.com/atari-2600-memories-music-and-sound.html

The 6507 information was taken from Leventhal's "6502 Assembly Language Programming" and the text file "64doc.txt" v1.0, by John West and Marko Makela.

Undocumented 650x instructions and implementation details in "6502/6510/8500/8502 Opcode matrix"

http://www.oxyron.de/html/opcodes02.html

6502 functional tests from https://github.com/Klaus2m5/6502_65C02_functional_tests

US Patent Number 4,644,495 was referenced for the implementation of the DPC cartridge format (the format used in Pitfall 2) https://patents.google.com/patent/US4644495/en

US patent 4,485,457A was used to help implement the CBS cartridge format https://patents.google.com/patent/US4485457A/en

European patent 84300730.3 was used to help implement the SCABS cartridge format https://worldwide.espacenet.com/patent/search/family/023848640/publication/EP0116455A2?q=84300730.3

DPC+ format implemented according to notes provided by Spiceware https://atariage.com/forums/topic/163495-harmony-dpc-programming and https://atariage.com/forums/blogs/entry/11811-dpcarm-part-6-dpc-cartridge-layout/

DPC+ARM information on Spiceware's blog https://atariage.com/forums/blogs/entry/11712-dpc-arm-development/?tab=comments#comment-27116

The "Mostly Inclusive Atari 2600 Mapper / Selected Hardware Document" (dated 03/04/12) by Kevin Horton

Supercharger information from the Kevin Horton document above and also the sctech.txt document

Reference for the ARM7TDMI-S, as used in the Harmony cartridge formats:

https://developer.arm.com/documentation/ddi0234/b

For detail about the Thumb instruction set the following document was preferred. Mnemonics used in the ARM disassembly are from this document:

http://bear.ces.cwru.edu/eecs_382/ARM7-TDMI-manual-pt1.pdf

Further information from the ARM Architecture Reference Manual:

http://www.ecs.csun.edu/~smirzaei/docs/ece425/arm7tdmi_instruction_set_reference.pdf

https://www.cs.miami.edu/home/burt/learning/Csc521.141/Documents/arm_arm.pdf

Specific information about UXP ARM7TDMI-S

https://www.nxp.com/docs/en/user-guide/UM10161.pdf

Thumb-2 information in the ARM Architecture Reference Manual Thumb-2 Supplement

https://documentation-service.arm.com/static/5f1066ca0daa596235e7e90a

and the "ARMv7-M Architecture Reference Manual" can be found at:

https://documentation-service.arm.com/static/606dc36485368c4c2b1bf62f

Specific information about the STM32F407 used in the UnoCart and PlusCart can be found at:

https://www.st.com/resource/en/reference_manual/dm00031020-stm32f405-415-stm32f407-417-stm32f427-437-and-stm32f429-439-advanced-arm-based-32-bit-mcus-stmicroelectronics.pdf

In relation to ARM development, information about the DWARF format is being taken from the DWARF2 and DWARF4 standards:

https://dwarfstd.org/doc/dwarf-2.0.0.pdf

https://dwarfstd.org/doc/DWARF4.pdf

ARM specific DWARF information taken from:

https://github.com/ARM-software/abi-aa/releases/download/2023Q1/aadwarf32.pdf

Other Software / Libraries

The following projects are used in the Gopher2600 project:

• https://github.com/ocornut/imgui

• https://github.com/inkyblackness/imgui-go

• https://github.com/veandco/go-sdl2

• https://github.com/go-gl/gl

• https://github.com/hajimehoshi/go-mp3

• https://github.com/pkg/term

• https://github.com/go-audio/wav

• https://github.com/sahilm/fuzzy

• FontAwesome

  • https://fontawesome.com/
  • licensed under the Font Awesome Free License

• Hack-Regular

  • https://github.com/source-foundry/Hack
  • licensed under the MIT License

• JetBrainsMono

  • https://github.com/JetBrains/JetBrainsMono
  • licensed under the OFL-1.1 License

Both 6502.ts and Stella were used as reference for the Audio implementation.

Some ideas for the fragment shaders taken from:

• https://github.com/libretro/glsl-shaders/blob/master/crt/shaders/crt-pi.glsl
• https://www.shadertoy.com/view/ltB3zD
• https://github.com/mattiasgustavsson/crtview
• https://gist.github.com/Beefster09/7264303ee4b4b2086f372f1e70e8eddd

The Festival Speech Synthesis System is an optional program that can be run alongside the emulator for AtariVox support

http://www.festvox.org/docs/manual-2.4.0/festival_toc.html

Personal Thanks and Acknowledgements

At various times during the development of this project, the following people have provided advice and encouragement: Andrew Rice, David Kelly. And those from AtariAge who have provided testing, advice and most importantly, encouragement (alphabetically): alex_79; Al Nafuur; Andrew Davie; DirtyHairy; John Champeau; MarcoJ; MrSQL; Rob Bairos; Spiceware; Thomas Jenztsch; Zachary Scolaro; ZeroPageHomebrew

gopher2600's Issues

MVC playback max volume crash

When playing an MVC file, increasing the volume past maximum causes a crash.

cannot load an 3E+ cart

Hey! Great emulator, and wonderful, clear code. (I poked into the mapper code to see if I could hunt down this bug.)

Stella accepts these 3E+ cart demos I was working on, which run and display a rather ugly X/O pattern.

The first game-9k.e3p loads in debug mode until you try to run it, but is then rejected in run mode probably due to its 9 KB size:

* error in RUN mode: playmode: setup: cartridge: 3E: wrong number of bytes in the cartridge data

The second game-8k.e3p is the same code. Just shrunk down to 8 KB (a normal power of 2). It loads in RUN mode, and then does nothing and seems to freeze the emulator entirely. But when in DEBUG mode it prints this and quits:

* error in DEBUG mode: debugger: disassembly: bless: cartridge does not reset to an address in the cartridge area.

I use banks-witching very aggressively, which may be why? I'm not sure Stella should accept it either, honestly... but it does run in Stella.

Attached is a zip file with the two ROM images.

game.zip

TIA "undriven" pins

Following today discussion on AA about the undriven TIA pins, I did check on Gopher2600 and found a couple of issues.

Here is a test rom that I wrote a while ago (to show similar problems that were in Stella).
tiadriven_test.zip

The rom reads from addresses $00 to $0f, and displays the results on screen.

The registers are read with the instruction

lda $ff,x

with x ranging from $01 to $10.

In this case, the last value on the bus that will affect bits 0 - 5 is the value stored in ram address "$ff" (because the 6502 performs an extra fetch from the base address before adding the index, as described here).
The test rom changes that value at address $ff every 30 frames alternating between $ff and $00.

So with "random pins" off, bits 5 to 0 should alternate between "0" and "1" every half second.
This is also the result that you (typically) get on real hardware.

On Gopher instead those bits currently take their value from the register address.

The second issue is with the input registers INPT0 to INPT5, where bit 6 must always read as "0", no matter how the "random pins" option is set.

Doesn't build on my machine - Xubuntu 18.04

1. Installed go V1.13.4 as detailed on Go website
2. Grabbed the repo
3. typed 'make release' as detailed in the README...

Output:

link@link-FLO:~/Applications/Gopher2600$ make release go build -gcflags '-c 3 -B -+ -wb=false' . gopher2600.go:24:2: cannot find package "gopher2600/cartridgeloader" in any of: /usr/local/go/src/gopher2600/cartridgeloader (from $GOROOT) /home/link/go/src/gopher2600/cartridgeloader (from $GOPATH) gopher2600.go:25:2: cannot find package "gopher2600/debugger" in any of: /usr/local/go/src/gopher2600/debugger (from $GOROOT) /home/link/go/src/gopher2600/debugger (from $GOPATH) gopher2600.go:26:2: cannot find package "gopher2600/debugger/terminal" in any of: /usr/local/go/src/gopher2600/debugger/terminal (from $GOROOT) /home/link/go/src/gopher2600/debugger/terminal (from $GOPATH) gopher2600.go:27:2: cannot find package "gopher2600/debugger/terminal/colorterm" in any of: /usr/local/go/src/gopher2600/debugger/terminal/colorterm (from $GOROOT) /home/link/go/src/gopher2600/debugger/terminal/colorterm (from $GOPATH) gopher2600.go:28:2: cannot find package "gopher2600/debugger/terminal/plainterm" in any of: /usr/local/go/src/gopher2600/debugger/terminal/plainterm (from $GOROOT) /home/link/go/src/gopher2600/debugger/terminal/plainterm (from $GOPATH) gopher2600.go:29:2: cannot find package "gopher2600/disassembly" in any of: /usr/local/go/src/gopher2600/disassembly (from $GOROOT) /home/link/go/src/gopher2600/disassembly (from $GOPATH) gopher2600.go:30:2: cannot find package "gopher2600/errors" in any of: /usr/local/go/src/gopher2600/errors (from $GOROOT) /home/link/go/src/gopher2600/errors (from $GOPATH) gopher2600.go:31:2: cannot find package "gopher2600/gui" in any of: /usr/local/go/src/gopher2600/gui (from $GOROOT) /home/link/go/src/gopher2600/gui (from $GOPATH) gopher2600.go:32:2: cannot find package "gopher2600/gui/sdldebug" in any of: /usr/local/go/src/gopher2600/gui/sdldebug (from $GOROOT) /home/link/go/src/gopher2600/gui/sdldebug (from $GOPATH) gopher2600.go:33:2: cannot find package "gopher2600/gui/sdlplay" in any of: /usr/local/go/src/gopher2600/gui/sdlplay (from $GOROOT) /home/link/go/src/gopher2600/gui/sdlplay (from $GOPATH) gopher2600.go:34:2: cannot find package "gopher2600/modalflag" in any of: /usr/local/go/src/gopher2600/modalflag (from $GOROOT) /home/link/go/src/gopher2600/modalflag (from $GOPATH) gopher2600.go:35:2: cannot find package "gopher2600/paths" in any of: /usr/local/go/src/gopher2600/paths (from $GOROOT) /home/link/go/src/gopher2600/paths (from $GOPATH) gopher2600.go:36:2: cannot find package "gopher2600/performance" in any of: /usr/local/go/src/gopher2600/performance (from $GOROOT) /home/link/go/src/gopher2600/performance (from $GOPATH) gopher2600.go:37:2: cannot find package "gopher2600/playmode" in any of: /usr/local/go/src/gopher2600/playmode (from $GOROOT) /home/link/go/src/gopher2600/playmode (from $GOPATH) gopher2600.go:38:2: cannot find package "gopher2600/recorder" in any of: /usr/local/go/src/gopher2600/recorder (from $GOROOT) /home/link/go/src/gopher2600/recorder (from $GOPATH) gopher2600.go:39:2: cannot find package "gopher2600/regression" in any of: /usr/local/go/src/gopher2600/regression (from $GOROOT) /home/link/go/src/gopher2600/regression (from $GOPATH) gopher2600.go:40:2: cannot find package "gopher2600/television" in any of: /usr/local/go/src/gopher2600/television (from $GOROOT) /home/link/go/src/gopher2600/television (from $GOPATH) gopher2600.go:41:2: cannot find package "gopher2600/wavwriter" in any of: /usr/local/go/src/gopher2600/wavwriter (from $GOROOT) /home/link/go/src/gopher2600/wavwriter (from $GOPATH) Makefile:16: recipe for target 'release' failed make: *** [release] Error 1 link@link-FLO:~/Applications/Gopher2600$

Cropped screen in World's End

While other games display fine, this game is heavily cropped even with pixel perfect ratio.
this is how it should look
https://www.retroplace.com/pics/atari2600/titles/194952--world-end.png

When I brought the replay menu, it would appear fine on the screen video, however in-game it refuses to switch to the correct picture

include domain name in module paths; local module paths may be reserved in the future

First of, really cool work @JetSetIlly! I tried running Gopher2600 on two games and it worked well :)

As I wanted to dive into the documentation of the project, I checked the GoDoc page. At the end of the page, I noticed these warnings:

The go get command cannot install this package because of the following issues:

    Unrecognized import path "gopher2600/wavwriter" (gopher2600.go:42:2)
    Unrecognized import path "gopher2600/gui/sdldebug" (gopher2600.go:32:2)
    Unrecognized import path "gopher2600/gui/sdlimgui" (gopher2600.go:33:2)
    Unrecognized import path "gopher2600/disassembly" (gopher2600.go:29:2)
    Unrecognized import path "gopher2600/playmode" (gopher2600.go:38:2)

If possible, I'd suggest updating the module path to github.com/jetsetilly/gopher2600, as this includes the domain name in the fully qualified import path. One reason this is important is that there is a proposal to reserve specific path prefixes for local (user-defined) modules (e.g. local/gopher2600); see golang/go#37641. Since the Gopher2600 project is hosted on a remote site, it makes sense to include the full domain name in the module path.

Wish you all the best and happy coding.

Cheers,
Robin

RIOT port B output functionality missing

Setting RIOT port B as output doesn't seem to be implemented in Gopher2600.

Despite what the "Stella Programmer Guide" says, Port B is fully configurable just like port A, and in fact the 3 unused bit can be used as extra storage if set as output.

More info and a few test roms here:
https://atariage.com/forums/topic/167173-what-does-the-game-select-switch-actually-do/

The following roms are the one I posted here
https://atariage.com/forums/topic/192031-stella-35-released/?do=findComment&comment=2435332
with just a minor change (writes to SWCHA/B now only happen when you actually change the value for those, while before they were written also when you changed SWACNT/SWBCNT)
riot_port_test_v2.zip

In the debugger it would be useful to see both the "Data Register" (in Stella indicated as "SWCHA(W)"/"SWCHB(W)" ) as well as the value that can be read from the port, as they can differ depending on how the "Data Direction Register" (SWACNT/SWBCNT) is set.

Compressed ROM files support (zip,7z etc)

Well, as the title says. Do we have a plan for future support for zipped roms or maybe they are already supported and I'm too dumb for missing some trivial dll files?

Apple M2

Would anyone with access to a Mac with an M2 processor be able to help me debug an issue I'm having with Gopher2600?

The emulator has worked well for several years on Linux, Windows and MacOS
(Intel CPUs) but will immediately crash when compiled for MacOS with an M2.

The problem I'm having is that I don't have M2 hardware immediately available:

The error printed to stdout in the event of the crash is:

"signal 16 received but handler not on signal stack
fatal error: non-Go code set up signal handler without SA_ONSTACK flag"

Looking at the go.mod file we can see there are a couple of packages that might
be the cause of this and the documentation for the signal package explains why.

https://pkg.go.dev/os/signal#hdr-Go_programs_that_use_cgo_or_SWIG

Yes, this should be fixed but more importantly, there is some other error,
probably in my Go code, that is causing the signal to be raised.

The help I need therefore is:

1. Figuring out which package is not setting up a signal handler correctly
2. Finding the reason why the signal is being raised.

Apple Ventura VSYNC issues

There appears to be VSYNC issues with Apple Ventura. This occurred with Monterey when it was first released, and has recently reappeared with Ventura.

libsdl-org/SDL#4918

Pinning this issue until it is known to have been resolved.

Installer does not run on Windows 10

Nothing appears when I click on the exe, not even a popup window. I use the latest Windows 10 update, 64bit version.

ROM selection doesn't work on Windows (v0.31 and v0.32)?

Checkptr failure

As of version 1.14 of Go the race detector adds checkptr instrumention. This compilation option ensures that program's follow Go's unsafe.Pointer safety rules. https://golang.org/doc/go1.14#compiler

Currently, Gopher2600 fails the checkptr test because of how fonts are setup for imgui-go. To wit, the following triggers the checkptr error:

// Store our identifier
rnd.imguiIO.Fonts().SetTextureID(imgui.TextureID(rnd.fontTexture))

fontTexture has previously been generated and bound and has the value 0. imgui.TextureID casts that value to a uintptr and thus triggers the error (pointer value too low).

It is possible to turn off checkptr with a build flag (the Makefile includes a race target that does this):

go run -race -gcflags=all=-d=checkptr=0 gopher2600.go debug

This is useful because it has allowed gopher2600 to be cleaned of race errors but the checkptr error remains.

In a nutshell, I'm not sure how to fix it. As far as I can tell, the fontTexture value is not really a pointer but casting it to uintptr raises the suspicions of the checkPtrcode. I also cannot see how to alter imgui-go in such a way to avoid using uintptr.

Seg fault trying to debug a ROM

Console:

`link@link-FLO:~/go/src/gopher2600$ ./gopher2600 debug ~/Code/retrotools/combat.bin

• symbols error: no symbols file for /home/link/Code/retrotools/combat.bin
• error running debugger initialisation script: script error: cannot open script file (open /home/link/.config/gopher2600/debuggerInit: no such file or directory)
  panic: runtime error: invalid memory address or nil pointer dereference
  [signal SIGSEGV: segmentation violation code=0x1 addr=0x28 pc=0x66fa97]

goroutine 1 [running, locked to thread]:
gopher2600/debugger/script.(*Rescribe).TermRead(0x0, 0xc00000ab00, 0xff, 0xff, 0xc00001a380, 0x12, 0x6, 0xc000062720, 0xc0000e1220, 0x203000, ...)
/home/link/go/src/gopher2600/debugger/script/rescribe.go:90 +0x37
gopher2600/debugger.(*Debugger).inputLoop(0xc000001c80, 0x85e4a0, 0x0, 0x0, 0xc000495ad0, 0x1)
/home/link/go/src/gopher2600/debugger/inputloop.go:170 +0xc83
gopher2600/debugger.(*Debugger).Start(0xc000001c80, 0xc0000184e0, 0x2a, 0x7ffd13125425, 0x25, 0x7d722c, 0x4, 0x0, 0x0, 0x0, ...)
/home/link/go/src/gopher2600/debugger/debugger.go:223 +0x668
main.debug.func1(0x865760, 0xc0000835f0)
/home/link/go/src/gopher2600/gopher2600.go:206 +0xf5
main.debug(0xc0000e2180, 0x0, 0x0)
/home/link/go/src/gopher2600/gopher2600.go:223 +0x7f3
main.main()
/home/link/go/src/gopher2600/gopher2600.go:76 +0x304
`

args not passed to elf_main

When loading an elf rom the elf_main() function should be passed an array of uint32_t that specifies the system type, clock rate, and feature flags.

See UCA firmware for an example here: https://github.com/Al-Nafuur/United-Carts-of-Atari/blob/main/source/STM32firmware/PlusCart/Src/cartridge_emulation_ELF.c

uint32_t mainArgs[MP_COUNT] =
{
	0, // MP_SYSTEM_TYPE (TBD below)		0  - Should be set based on TV
	SystemCoreClock, // MP_CLOCK_HZ			1 - Should be set based on arm CPU clock
	FF_MULTI_CART, // MP_FEARTURE_FLAGS		2 - Use this flag to indicate that the game should support exiting 
};

// For MP_SYSTEM_TYPE
#define ST_NTSC_2600 0
#define ST_PAL_2600 1
#define ST_PAL60_2600 2

// For MP_FEATURE_FLAGS
#define FF_MULTI_CART 1 // Indicates elf is loaded by multicart and should allow exiting (return from main() function)

Portable Version?

Hi, first of all thanks for your emulator.
My request is quite obvious, could you provide a portable version?
Like many people, I dont like the installation versions.
Thanks in advance, hope you will consider it.
Best regards!