gopher2600

command module
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2024 License: GPL-3.0 Imports: 25 Imported by: 0

README

Gopher2600

gopher2600 logo

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

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:

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.

pitfall chiphead thrust
man goes down soul of the beast egypt genesis
draconian zookeeper

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 and UA.

  • 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:

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

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:

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

Some ideas for the fragment shaders taken from:

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

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
Package archivefs allows the traversal of a filetree and treating archive files transparently.
 Package archivefs allows the traversal of a filetree and treating archive files transparently.
Package bots is the root package for the bot subsystem.
 Package bots is the root package for the bot subsystem.
chess
Package chess contains the bots that can play the various chess games available on the Atari2600.
 Package chess contains the bots that can play the various chess games available on the Atari2600.
chess/uci
Package uci handles a running UCI engine.
 Package uci handles a running UCI engine.
spacejockey
Package spacejockey is a bot capable of playing Space Jockey.
 Package spacejockey is a bot capable of playing Space Jockey.
wrangler
Package wrangler keeps track of the running bot and handles the activating and termination of running bots.
 Package wrangler keeps track of the running bot and handles the activating and termination of running bots.
Package cartridgeloader is used to load cartridge data so that it can be used with the cartridge pacakage
 Package cartridgeloader is used to load cartridge data so that it can be used with the cartridge pacakage
Package comparison facilitates the running of a comparison emulator alongside the main emulation.
 Package comparison facilitates the running of a comparison emulator alongside the main emulation.
Package coprocessor contains the helper functions for cartridge coprocessors.
 Package coprocessor contains the helper functions for cartridge coprocessors.
developer
Package developer offers additional functionality to the developer of ROMs that use a coprocessor.
 Package developer offers additional functionality to the developer of ROMs that use a coprocessor.
developer/breakpoints
Package breakpoints records the breakpoints assigned to memory addresses.
 Package breakpoints records the breakpoints assigned to memory addresses.
developer/callstack
Package callstack maintains the callstack of an executing program as accurately as possible.
 Package callstack maintains the callstack of an executing program as accurately as possible.
developer/dwarf
developer/dwarf/leb128
Package leb128 implements the Variable Length Data encoding method as required by the DWARF debugging format.
 Package leb128 implements the Variable Length Data encoding method as required by the DWARF debugging format.
developer/faults
Package faults records memory faults generated by a coprocessor.
 Package faults records memory faults generated by a coprocessor.
developer/mapfile
Package mapfile reads a mapfile produced by GCC and parses it.
 Package mapfile reads a mapfile produced by GCC and parses it.
developer/profiling
Package profiling defines the types that are used to profile the performance of the coporocessor program.
 Package profiling defines the types that are used to profile the performance of the coporocessor program.
developer/yield
Package yield records the current yielded state of a coprocessor.
 Package yield records the current yielded state of a coprocessor.
disassembly
Package disassembly facilitates the disassembly of any coprocessor program in compatible ROM.
 Package disassembly facilitates the disassembly of any coprocessor program in compatible ROM.
Package database is a very simple way of storing structured and arbitrary entry types.
 Package database is a very simple way of storing structured and arbitrary entry types.
Package debugger implements a reaonably comprehensive debugging tool.
 Package debugger implements a reaonably comprehensive debugging tool.
dbgmem
Package dbgmem sits between the debugger and the acutal VCS memory.
 Package dbgmem sits between the debugger and the acutal VCS memory.
govern
Package govern defines the types that define the current condition of the emulation.
 Package govern defines the types that define the current condition of the emulation.
script
Package script allows the debugger to record and replay debugging scripts.
 Package script allows the debugger to record and replay debugging scripts.
terminal
Package terminal defines the operations required for command-line interaction with the debugger.
 Package terminal defines the operations required for command-line interaction with the debugger.
terminal/colorterm
Package colorterm implements the Terminal interface for the gopher2600 debugger.
 Package colorterm implements the Terminal interface for the gopher2600 debugger.
terminal/colorterm/easyterm
Package easyterm is a wrapper for "github.com/pkg/term/termios".
 Package easyterm is a wrapper for "github.com/pkg/term/termios".
terminal/colorterm/easyterm/ansi
Package ansi defines ANSI control codes for styles and colours.
 Package ansi defines ANSI control codes for styles and colours.
terminal/commandline
Package commandline facilitates parsing of command line input.
 Package commandline facilitates parsing of command line input.
terminal/plainterm
Package plainterm implements the Terminal interface for the gopher2600 debugger.
 Package plainterm implements the Terminal interface for the gopher2600 debugger.
Package digest is used to create mathematical hashes of VCS output.
 Package digest is used to create mathematical hashes of VCS output.
Package disassembly coordinates the disassembly of Atari2600 (6507) cartridges.
 Package disassembly coordinates the disassembly of Atari2600 (6507) cartridges.
symbols
Package symbols helps keep track of address symbols for the currently loaded cartridge.
 Package symbols helps keep track of address symbols for the currently loaded cartridge.
Package environment provides context for an emulation.
 Package environment provides context for an emulation.
gui
Package gui is an abstraction layer for real GUI implementations.
 Package gui is an abstraction layer for real GUI implementations.
crt
Package CRT contains non-gui-specific and non-VCS-specific information.
 Package CRT contains non-gui-specific and non-VCS-specific information.
fonts
Package fonts embeds a set of FontAwesome glyphs as font data into a byte array.
 Package fonts embeds a set of FontAwesome glyphs as font data into a byte array.
sdlaudio
Package sdlaudio provides the Audio type.
 Package sdlaudio provides the Audio type.
sdlimgui
This file is part of Gopher2600.
 This file is part of Gopher2600.
sdlimgui/caching
Package caching is used for copying gopher2600 data so it can be used by the GUI goroutine safely.
 Package caching is used for copying gopher2600 data so it can be used by the GUI goroutine safely.
sdlimgui/framebuffer
Package framebuffer provides a convenient way of working with OpenGL framebuffers.
 Package framebuffer provides a convenient way of working with OpenGL framebuffers.
sdlimgui/shaders
Package shaders contains the shader source for displaying GUI elements on the screen.
 Package shaders contains the shader source for displaying GUI elements on the screen.
Package hardware is the base package for the VCS emulation.
 Package hardware is the base package for the VCS emulation.
cpu
Package cpu emulates the 6507 microprocessor found in the Atari VCS.
 Package cpu emulates the 6507 microprocessor found in the Atari VCS.
cpu/execution
Package execution tracks the result of instruction execution on the CPU.
 Package execution tracks the result of instruction execution on the CPU.
cpu/functional_test
Package functional_test runs the 6502 functional test as defined by Klaus Dormann.
 Package functional_test runs the 6502 functional test as defined by Klaus Dormann.
cpu/instructions
Package instructions defines the table of instruction for the 6507.
 Package instructions defines the table of instruction for the 6507.
cpu/instructions/generator
cpu/registers
Package registers implements the three types of registers found in the 6507.
 Package registers implements the three types of registers found in the 6507.
cpu/registers/test
Package test contains functions useful for testing CPU registers.
 Package test contains functions useful for testing CPU registers.
input
Pacakge input coordinates all the different types of input into the VCS.
 Pacakge input coordinates all the different types of input into the VCS.
memory
Package memory implements the Atari VCS memory model.
 Package memory implements the Atari VCS memory model.
memory/cartridge
Package cartridge fully implements loading of mapping of cartridge memory.
 Package cartridge fully implements loading of mapping of cartridge memory.
memory/cartridge/ace
Package ace implements the ACE cartridge mapper.
 Package ace implements the ACE cartridge mapper.
memory/cartridge/arm
Package arm imlplements the ARM7TDMI instruction set as defined in the ARM7TDMI Instruction Set Reference:
 Package arm imlplements the ARM7TDMI instruction set as defined in the ARM7TDMI Instruction Set Reference:
memory/cartridge/arm/architecture
Package architecture defines the Map type that is used to specify the differences in cartridge and ARM archtectures.
 Package architecture defines the Map type that is used to specify the differences in cartridge and ARM archtectures.
memory/cartridge/arm/callfn
Package Callfn facilitates the ARM CALLFN process common to both DPC+ and CDF* cartridge mappers.
 Package Callfn facilitates the ARM CALLFN process common to both DPC+ and CDF* cartridge mappers.
memory/cartridge/arm/fpu
memory/cartridge/arm/peripherals
Package peripherals implements the optional modules that can make up the ARM processor.
 Package peripherals implements the optional modules that can make up the ARM processor.
memory/cartridge/cdf
Package cdf implemnents the various CDF type cartridge mappers including CDFJ.
 Package cdf implemnents the various CDF type cartridge mappers including CDFJ.
memory/cartridge/dpcplus
Package dpcplus implements the DPC+ cartridge mapper.
 Package dpcplus implements the DPC+ cartridge mapper.
memory/cartridge/elf
Package ace implements the ELF cartridge mapper.
 Package ace implements the ELF cartridge mapper.
memory/cartridge/mapper
Package mapper contains the CartMapper interface.
 Package mapper contains the CartMapper interface.
memory/cartridge/moviecart
Package moviecart implements the Movie Cart special cartridge type.
 Package moviecart implements the Movie Cart special cartridge type.
memory/cartridge/plusrom
Package plusrom implements the PlusROM cartridge as developed by Wolfgang Stubig.
 Package plusrom implements the PlusROM cartridge as developed by Wolfgang Stubig.
memory/cartridge/plusrom/plusnet
Package plusnet contains details of the PlusNET protocol.
 Package plusnet contains details of the PlusNET protocol.
memory/cartridge/supercharger
Package supercharger implements the tape based cartridge format.
 Package supercharger implements the tape based cartridge format.
memory/chipbus
Package chipbus defines the operations, addresses and symbols that are required by the TIA and RIOT chips when updated values in memory.
 Package chipbus defines the operations, addresses and symbols that are required by the TIA and RIOT chips when updated values in memory.
memory/cpubus
Package cpubus defines the operations, addresses and symbols that are required by the CPU when reading/writing to memory.
 Package cpubus defines the operations, addresses and symbols that are required by the CPU when reading/writing to memory.
memory/memorymap
Package memorymap facilitates the translation of addresses to primary address equivalents.
 Package memorymap facilitates the translation of addresses to primary address equivalents.
memory/vcs
Package vcs represents the areas of memory that are internal to the VCS hardware.
 Package vcs represents the areas of memory that are internal to the VCS hardware.
peripherals
Package peripherals is a container package for all the various peripherals for the Atari 2600 that are emulated.
 Package peripherals is a container package for all the various peripherals for the Atari 2600 that are emulated.
peripherals/atarivox
Package atarivox implements the atarivox peripheral.
 Package atarivox implements the atarivox peripheral.
peripherals/atarivox/atarivoxengines
Package atarivoxengines contains implementations of the AtariVoxEngine interface, for use with the AtariVox peripheral.
 Package atarivoxengines contains implementations of the AtariVoxEngine interface, for use with the AtariVox peripheral.
peripherals/controllers
Package controllers contains the implementations for all the emulated controllers for the VCS.
 Package controllers contains the implementations for all the emulated controllers for the VCS.
peripherals/savekey
Package savekey implements the SaveKey external memory card.
 Package savekey implements the SaveKey external memory card.
peripherals/savekey/i2c
Package i2c facilitates the reading of i2c data for the SaveKey (and AtariVox) peripherals.
 Package i2c facilitates the reading of i2c data for the SaveKey (and AtariVox) peripherals.
preferences
Package preferences (sub-package of the hardware package) coordinates the options for all variations in hardware operation.
 Package preferences (sub-package of the hardware package) coordinates the options for all variations in hardware operation.
riot
Package riot (RIOT) represents the active part of the PIA 6532.
 Package riot (RIOT) represents the active part of the PIA 6532.
riot/ports
Package ports represents the input/output parts of the VCS (the IO in RIOT).
 Package ports represents the input/output parts of the VCS (the IO in RIOT).
riot/ports/panel
Package panel implements the front control panel of the VCS.
 Package panel implements the front control panel of the VCS.
riot/ports/plugging
Package plugging conceptualises the act of plugging devices into the VCS ports.
 Package plugging conceptualises the act of plugging devices into the VCS ports.
riot/timer
Package timer represents the timer part of the RIOT (the T in RIOT).
 Package timer represents the timer part of the RIOT (the T in RIOT).
television
Package television implements the output device of the emulated VCS.
 Package television implements the output device of the emulated VCS.
television/coords
Package coords represents and can work with television coorindates
 Package coords represents and can work with television coorindates
television/signal
Package signal exposes the interface between the VCS and the television implementation.
 Package signal exposes the interface between the VCS and the television implementation.
television/specification
Package specification contains the definitions, including colour, of the PAL and NTSC television protocols supported by the emulation.
 Package specification contains the definitions, including colour, of the PAL and NTSC television protocols supported by the emulation.
tia
Package TIA implements the custom video/audio chip found in the the VCS.
 Package TIA implements the custom video/audio chip found in the the VCS.
tia/audio
Package audio implements the audio generation of the TIA.
 Package audio implements the audio generation of the TIA.
tia/audio/mix
Package mix is used to combine two distinct sound sources into either a mono or stereo signal.
 Package mix is used to combine two distinct sound sources into either a mono or stereo signal.
tia/delay
Package delay is a replacement for the future package, which has now been removed.
 Package delay is a replacement for the future package, which has now been removed.
tia/hmove
Package hmove represents the TIA HMOVE process.
 Package hmove represents the TIA HMOVE process.
tia/phaseclock
Package phaseclock defines the two phase clock generator used to drive the various polynomial counters in the TIA.
 Package phaseclock defines the two phase clock generator used to drive the various polynomial counters in the TIA.
tia/polycounter
Package polycounter implements the polynomial counters found in the TIA.
 Package polycounter implements the polynomial counters found in the TIA.
tia/revision
Package revision handles/documents the differences in the TIA across different models of the Atari 2600.
 Package revision handles/documents the differences in the TIA across different models of the Atari 2600.
tia/video
Package video implements pixel generation for the emulated TIA.
 Package video implements pixel generation for the emulated TIA.
Package logger is the central log repository for gopher2600.
 Package logger is the central log repository for gopher2600.
Package macro implements an input system that processes instructions from a macro script.
 Package macro implements an input system that processes instructions from a macro script.
Package notifications allow communication from a cartridge directly to the emulation instance.
 Package notifications allow communication from a cartridge directly to the emulation instance.
Package patch is used to patch the contents of a cartridge.
 Package patch is used to patch the contents of a cartridge.
Package performance contains helper functions relating to performance.
 Package performance contains helper functions relating to performance.
Package prefs facilitates the storage of preferential values in the Gopher2600 system.
 Package prefs facilitates the storage of preferential values in the Gopher2600 system.
Package preview is used to emulate a ROM for a short period of time in order to gather information that would takes time to acquire.
 Package preview is used to emulate a ROM for a short period of time in order to gather information that would takes time to acquire.
Package properties adds support for the Stella properties file, named stella.pro.
 Package properties adds support for the Stella properties file, named stella.pro.
Package random should be used in preference to the math/rand package when a random number is required inside the emulation.
 Package random should be used in preference to the math/rand package when a random number is required inside the emulation.
Package recorder handles recording and playback of input through the VCS input system.
 Package recorder handles recording and playback of input through the VCS input system.
Package reflection monitors the emulated hardware for conditions that would otherwise not be visible through normal emulation.
 Package reflection monitors the emulated hardware for conditions that would otherwise not be visible through normal emulation.
counter
Package counter is closely related to the reflection package.
 Package counter is closely related to the reflection package.
Package regression facilitates the regression testing of emulation code.
 Package regression facilitates the regression testing of emulation code.
Package resources contains functions to prepare paths for gopher2600 resources.
 Package resources contains functions to prepare paths for gopher2600 resources.
fs
Package fs is an abstraction for OS/filesystem functions that may be missing or require special handling.
 Package fs is an abstraction for OS/filesystem functions that may be missing or require special handling.
unique
Package unique contains functions that compose filenames that should be unique on the filesystem.
 Package unique contains functions that compose filenames that should be unique on the filesystem.
Package rewind coordinates the periodic snapshotting of the emulation state.
 Package rewind coordinates the periodic snapshotting of the emulation state.
Package setup is used to preset the emulation depending on the attached cartridge.
 Package setup is used to preset the emulation depending on the attached cartridge.
Package test contains helper functions to remove common boilerplate to make testing easier.
 Package test contains helper functions to remove common boilerplate to make testing easier.
Package thumbnailer can be used to create either a series of thumbnail images or a single thumbnail image with the CreateFromLoader() and SingleFrameFromRewindState() functions respsectively.
 Package thumbnailer can be used to create either a series of thumbnail images or a single thumbnail image with the CreateFromLoader() and SingleFrameFromRewindState() functions respsectively.
Packate tracker implements the audio.Tracker interface and can be used to record changes in the state of the TIA audio.
 Packate tracker implements the audio.Tracker interface and can be used to record changes in the state of the TIA audio.
Package userinput translates real hardware input from the user's computer, to the emulated console.
 Package userinput translates real hardware input from the user's computer, to the emulated console.
Package version provides a version string that can be used to indicate the version number of the project.
 Package version provides a version string that can be used to indicate the version number of the project.
Package wavwriter allows writing of audio data to disk as a WAV file.
 Package wavwriter allows writing of audio data to disk as a WAV file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.