Gopher2600

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

The accuracy of the emulation is very high and there are no known outstanding problems with the 6507, TIA and RIOT chip emulation. Emulation of the ARM chip is currently limited to the Thumb subset of instructions but it does include accurate cycle counting and performance monitoring.

It is an ongoing project and bug reports are welcome.

The key features of the emulator:

• Support for many of the known cartridge formats including the Supercharger
• Emulation of the ARM7TDMI as found in the Harmony cartridge
• Network access through PlusROM emulation
• AtariVox and SaveKey support
• CRT Effects
• 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

The graphical debugger:

• Optional Color Clock level interaction
• Breakpoints, traps, watches on various CPU, TIA and RIOT targets
• Specialist windows for specific cartridge types (eg. supercharger tape)
• Terminal interface (headless operation optional)
• Script recording and playback
• ARM peformance monitoring

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.

• ParkerBros fingerprint taken from Stella. I can't remember why I did this but a comment in the fingerprint.go file says I did.

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

• Fingerprint patterns for automated controller/peripheral selection.

• As a reference for the Wickstead Design bankswitching protocol. Only one ROM of this type exists (the Pursuit of the Pink Panther).

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 "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

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

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

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 shader 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

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