Gopher2600 is an emulator for the Atari 2600 written in the Go language. The accuracy of the emulation is very high and the 6507, TIA and RIOT chips appear to operate without bugs. Certainly, there are no known outstanding issues with any of the emulated chips.
It compare favourably with
Stella except for speed and final project polish.
The key features of the emulator:
- Support for many of the known cartridge formats
- Emulation of the ARM7TDMI as found in the
- Gameplay recording and playback
- Support for (and auto-detection of) stick, paddle and keypad
- Network access through PlusROM emulation
- Savekey support
- CRT Effects
- Stereo audio output
- Support for common TIA revisions
- Implementation of Movie Cart
The graphical debugger is still in development but the current features include:
- CPU and Video stepping
- Breakpoints, traps, watches on various CPU, TIA, RIOT targets
- Interactive rewinding
- Specialist windows for specific cartridge types (eg. supercharger tape)
- Script recording and playback
- Line terminal interface for harder to reach parts of the emulation
- Regression Database
The following screenshots were taken in playmode with CRT effects enabled.
Scope of the project
Gopher2600 was started as for fun and educational purposes, as way of
learning more about the
Atari 2600 and also about the
Go programming language.
The original intent was to create a tool for static analysis of a 6507 program
to help in the creation of
Atari 2600 games. I soon realised however that I
would need to emulate more of the 2600 and not just the CPU for this to be
Because of its origins, any flaws or limitations in the design should be borne in mind while the project is still in development. I am open to any suggestions on how to improve the project.
The development machine for
Gopher2600 was an i3-3225 with 16GB of RAM. Host
operating system throughout the development has been a Linux system (4.x
In playmode I can get a sustained frame rate of 60fps capped - good enough for NTSC. This includes emulation of the ARM7 chip if required.
In debug mode, I can get around 35fps.
To get a performance rating for your installation you can run the following:
> gopher2600 performance -display -fpscap=false
Which gives the maximum frame rate with the display. Omit the
for an absolute value.
Memory usage is currently around 40MB of system memory in playmode and around 120MB in debug mode. This can vary on the ROM used however. It shouldn't ever be a problem on modern hardware.
statsview is also available. See the section below on the Statistics
Viewer for details.
There are very few options available to improve performance of the emulator.
One thing you can do is to compile the project with at least version 1.17 of the Go compiler.
Turning CRT effects off will likely have no effect.
For ROMs that use the ARM chip, setting the ARM to
immediate mode will eliminate cycle counting and hence give a modest
The project has most recently been tested with Go v1.17.
The project uses the Go module system and dependencies will be resolved automatically. Do note however, that you will also require the SDL development kit installed on the system. For users of UNIX like systems, installation from your package manager is the easiest option (for MacOS use the homebrew package manager https://formulae.brew.sh/formula/sdl2)
Compile with GNU Make
> make release
During development, programmers may find it more useful to use the go command directly
> go run gopher2600.go
Gopher2600 makes use of SDL2. The SDL2 go binding used by the project requires a minimum
SDL2 version of
Gopher2600 is known to run on several platforms. It is known to work best
however on Linux based systems, on which it is being developed.
Native compilation of a Windows executable has not yet been tried. But cross-compilation does work via the Makefile:
> make cross_windows
Or for a statically linked binary:
> make cross_windows_static
This has been tested on a Linux system with mingw installed.
Once compiled run the executable with the help flag:
> gopher2600 -help
This will list the available sub-modes. Use the -help flag to get information about a sub-mode. For example:
> gopher2600 debug -help
To run a cartridge, you don't need to specify a sub-mode. For example:
> gopher2600 roms/Pitfall.bin
Although if want to pass flags to the run mode you'll need to specify it.
> gopher2600 run -help
Stick, paddle and keypad inputs are supported.
The stick is the most common control method for
Atari 2600 games. The
left-side player is controlled with the following keys.
|Cursor Keys||Stick Direction|
The right-side player is controlled with the following keys.
The stick for the left-side player can also be controlled with a gamepad.
The paddle for the left-side player can be controlled with the mouse or a gamepad.
In the case of the mouse, the mouse must be captured.
Neither of these input methods is a perfect replacement for a real paddle however and which device is used depends on the game. For some games, the triggers will suffice but other games will perform better when using the mouse.
Nightdriver is an example of a game that plays well with the triggers,
whereas experience says that
Circus Tricks is better played with the mouse.
The paddle for the right-side player is not currently supported.
Keypad input for both players is supported.
|Left-Side Player||Right-Side Player|
Gopher2600 supports auto-detection of input devices. In general, this is done
by 'waggling' the control a few times in order to wake up the device.
On startup, the stick is assumed to be the controller of choice.
In the case of keypad controllers, it's possible for the emulation to detect for certainty that a keypad controller is required. It is therefore not possible to switch to or from keypad control manually because there is no need.
For convenience the joystick and paddle for the left-side player can be controlled through a gamepad. For the joystick, use the left thumbstick or the DPad. Any of the face buttons will act as the joystick's fire button.
To control the paddle use the left and right analogue triggers. Note that you will need to 'waggle' the triggers a couple of times for the emulator to detect that you want to switch to the paddle.
The console's reset switch can be triggered with the gamepad's start button.
When using the mouse for paddle control, the mouse must first be 'captured'. You will know when the mouse is captured because the mouse pointer will no longer be visible.
In playmode, the mouse is most conveniently caputred by pressing the right
mouse button. To release the mouse from capture press the right mouse button.
Scroll Lock key will also toggle mouse capture.
In the debugger, there is a
Capture Mouse button in the
Control window. Or
you can use the
Scroll Lock key.
The VCS panel is controlled through the function keys of the keyboard.
F4Player 0 Pro Toggle
F5Player 1 Pro Toggle
In playmode, the additional keys are available:
F7Show FPS Indicator (also shows TV specification information)
F10Show Preferences Window
In addition, the following keys behave the same in both playmode and the debugger.
Scroll LockToggle mouse capture (
F14on some keyboards)
PausePause/Resume emulation (
F15on some keyboard)
To run the debugger use the
> gopher2600 debug roms/Pitfall.bin
Because the debugger is still in development, full documentation is not yet available. But briefly, the features we can see in this screeshot are:
The menu-bar across the top of the screen shows the
VCS and in this instance a
Debuggermenu you can open the preferences windows the terminal and others.
VCSmenu contains options to open windows that relate to the VCS itself.
- Many of them are already open but other, less frequently required windows are also available
Cartridgemenu appears when the loaded cartridge type has additional features. For example:
- Cartridge memory and or registers
- In this case, this is the menu for the
- At the very right of the menu bar we can see the file path for the loaded cartridge
Below the menu-bar are the debugging windows. In this screenshot we can see:
TV Screen. This shows the television output from the VCS.
- The screen is 'interactive' and will show information about the pixel underneath the cursor
- Clicking the screen will move the VCS emulation to the point where the VCS is outputting that pixel. This is part of the rewind system.
- Also available are a variety of
overlays. Click the overlay button (labelled
no overlayin the screenshot and select which overlay you want.
Audiowindow shows the waveform of the recent sound output.
Controlwindow allow you to
rewindthrough the emulation.
- The toggle to right of the
Stepbutton will put the emulation into
video-cyclemode. This will allow you to step by a single color-clock at a time, rather than a single CPU instruction.
<buttons will step back by eith a CPU instruction, a scanline or an entire frame. Stepping back by video-cycle is not currently supported.
- The toggle to right of the
Timerwindow shows the current state of the RIOT Timer.
CPUwindow shows the current state of the 6507.
Disassemblywindow shows the disassembled ROM.
- If a 'DASM' generated symbol file is available then that will be used.
- If a symbols file isn't available then the standard symbols will be used. This includes symbols for special cartridge areas that might exists. For example, a hotspot address for switching banks will be indicated with
BANK2, etc. instead of the address.
- Add or remove a
PC Breakpointby clicking on the address.
RAMwindow shows the contents of the VCS RAM. Cartidge RAM if available will be show in the
Cartridge RAMwindow. Not shown but available through the cartridge menu when appropriate.
- The highlighted bytes indicate those bytes that have changed since the emulation last halted.
TIAwindow details the six graphical parts of the VCS's graphics chip.
- The state of the
TIAcan be changed manually but note that the changes will not be retained when the emulation next updates that part of the TIA.
- The state of the
Note that much of the information presented in the windows is editable. For example, the contents of the CPU's PC register can be edited via the window. As in all areas of this project, the user is encouraged to experiment.
A (old) video of the debugger in action can be found here.
As an alternative to GUI interaction the debugger can also be controlled through a terminal. This is available through the
terminal window. The rest of this section describes the operation of the terminal in detail.
Help is available with the HELP command. Help on a specific topic is available by specifying a keyword. The list below shows the currently defined keywords. The rest of the section will give a brief run down of debugger features.
[ $f000 SEI ] >> help AUDIO BALL BREAK CARTRIDGE CLEAR CONTROLLER CPU DISASM DISPLAY DROP GREP HALT HELP INSERT KEYPAD LAST LINT LIST LOG MEMMAP MEMUSAGE MISSILE ONHALT ONSTEP ONTRACE PANEL PATCH PEEK PLAYER PLAYFIELD PLUSROM POKE PREFS QUANTUM QUIT RAM RESET REWIND RIOT RUN SCRIPT STEP STICK SYMBOL TIA TRACE TRAP TV WATCH
The debugger allows tab-completion in most situations. For example, pressing
W followed by the Tab key on your keyboard, will autocomplete the
WATCH command. This works for command arguments too. It does not currently work for filenames, or symbols. Given a choice of completions, the Tab key will cycle through the available options.
Addresses can be specified by decimal or hexadecimal. Hexadecimal addresses can be written
$80. The debugger will echo addresses in the first format. Addresses can also be specified by symbol if one is available. The debugger understands the canonical symbol names used in VCS development. For example,
WATCH NUSIZ0 will halt execution whenever address 0x04 (or any of its mirrors) is written to.
Watches are one of the three facilities that will halt execution of the emulator. The other two are
BREAK. Both of these commands will halt execution when a "target" changes or meets some condition. An example of a target is the Programmer Counter or the Scanline value. See
HELP BREAK and
HELP TRAP for more information.
Whenever the emulation does halt, the
ONHALT command will run. For example, a previous call to
ONHALT CPU will cause the
CPU command to run whenever the emulation stops. Similarly, the
ONSTEP command applies whenever the emulation is stepped forward. By default, the
LAST command is run on every step.
The debugger can step forward either, one CPU instruction at a time, or by one video cycle at a time. We can change this mode with the
QUANTUM command. We can also conveniently use the
STEP command, for example
STEP CLOCK, performing the quantum change and stepping forward in one go. The STEP command can also be to step forward one scanline or one frame. It can also be used to STEP backwards, although in some cases the REWIND command might be more convenient.
Scripts can be recorded and played back with the
SCRIPT command. All commands are available when in script recording mode, except
RUN and further
SCRIPT RECORD command. Playing back a script while recording a new script is possible.
Gopher2600 allows emulation state to be rewound to an earlier frame, scanline
or colour-clock. Rewinding by frame is best done through the
Control window of
Rewinding to a scanline/colour-clock is done by clicking the left mouse button on the debug screen, at the position required. This will change the state of the emulation accordingly. This can be done with any frame in the rewind history without damaging the rewind history.
The rewind history will be cropped and continue from the current point whenever the emulation is run or stepped.
The number of rewind states stored can be set via the preferences window (or through the terminal). In addition the snapshot frequency can also be altered. The frequency defines how many frames must pass before another snapshot is taken. This affects the number of frames that can be stored. For example, if number of states is 100 and frequency is 1 then one-hundred frames can be stored in the rewind history. On the other hand, if the number of states is 100 and frequency is 5 then five-hundred frames can be stored.
The rewind frequency does not affect the granularity of the rewind history. This means that you can rewind to any frame in the rewind history even if no no explicit snapshot has been taken.
The downside of large frequencies is that input events (from a joystick for
example) may be lost if they occurred between snapshots. Future versions of
Gopher2600 will correct this.
Rewind is also not currently available in playmode. Again, future version of
Gopher2600 will allow this.
Video quantum is also not fully supported. While the rewind system will work
when in video-stepping mode you can not currently interactively alter the
screen position to the level of an individual colour-clock. Left-clicking on the
screen, as described above, will 'quantise' to the next CPU instruction. Future
Gopher2600 will correct this.
Gopher2600 supports common revisions in the TIA chip and can be changed
through the prefrences window.
In playmode the preferences window can by opened by pressing
F10. Select the
TIA Revisions tab:
A summary of the known TIA revisions / bugs can be found at on Atari Compendium. Not all revisions / bugs are supported by
but the common ones are.
Gopher2600 tries to emulate the visual effect of a CRT television. This is by
no means complete and is an area of active development.
In playmode the preferences window can by opened by pressing
F10. Select the
In the debugger the preferences window can be opened from the
and a preview can be seen in the
TV Screen by pressing the
The effects can be turned off completely with the
Pixel Perfect option. In
this mode, there is still the option to specify pixel fade. This is roughly
equivalent to the
Gopher2600 offers three methods for creating a screenshot. Ideally, the
emulation will select the best method to use but this is currently not
possible (although this is an ongoing area of research).
The most basic method is the 'single frame' method. Press
F12 without any
modifiers and a single image is saved to the working directory (or working
folder for Windows users).
The 'double frame' method is useful for kernels that use a two-frame flicker
kernel. In this method two consecutive frames are blended together to create a
single image. This method is selected by pressing either
shift key at the
same time as the
The 'triple frame' method meanwhile, the image is created by belnding three
consecutive frames together. This is useful for the far rarer three-frame
flicker kernel. This method is selected by pressing either
ctrl key at the
same time as the
In the case of both the double and triple frame methods, multiple 'exposures' are made and saved (currently five). This is because it is not possible to guarantee the generation of a good image from a single exposure in all circumstances. From the exposures that are made the user can select the best image; and if absolutely necessary, make a composite image.
Screenshot filenames will include whether the CRT effects were enabled, the name of the ROM file (without extension), the date/time (to make the filename unique) and the screenshot method (along with frame exposure).
The dimensions of the image will be the same as the displayed screen (without any window padding).
Gopher2600 will look for certain files in a configuration directory. The location
of this directory depends on whether the executable is a release executable (built
with "make release") or a development executable (made with "make build"). For
development executables the configuration directory is named
.gopher2600 and is
located in the current working directory.
For release executables, the directory is placed in the user's configuration directory,
the location of which is dependent on the host OS. On modern Linux systems, the location
For MacOS the directory for release executables is
For Windows, a
gopher2600 will be placed somewhere in the user's
folder, either in the
In all instances, the directory, sub-directory and files will be created automatically as required.
Gopher2600 can load supercharger tapes from MP3 and WAV file, in addition to supercharger BIN files.
Multiload "tapes" are supported although care should be taken in how multiload files are created.
In the case of BIN files a straight concatenation of individual files should work, resulting in a file that is a multiple of 8448 bytes.
For MP3 and WAV files however, the waveform should be concatenated, not the individual MP3/WAV files themselves. A command line tool like SoX can be used for this.
Supercharger eulation relies on the presence of the real Supercharger BIOSt. The file must be named one of the following:
- Supercharger BIOS.bin
The file can be placed in the current working directory or in the same directory as the Supercharger file being loaded. Alternatively, it can be placed in the emulator's configuration directory.
Gopher2600 has basic support for the
SaveKey peripheral. This will be
expanded on in the future.
For now, the presence of the peripheral must be specified with the
arugment. This is only available in
debug mode. The simplest
invocation to load a ROM with the
> gopher2600 -savekey roms/mgd.bin
Note that the
SaveKey will always be inserted in the second player port.
Data saved to the
SaveKey will be saved in the configuration directory to the
binary file named simply,
The Atari2600 Pluscart is a third-party
peripheral that gives the Atari2600 internet connectivity.
automatically determine when a PlusROM enabled ROM is loaded.
The very first time you load a PlusROM cartridge you will be asked for a username. This username along with the automatically generated ID, will be used to identify you on the PlusROM server (different ROMs can have different servers.)
You can change your username through the debugger, either through the PlusROM
preferences window or through the terminal with the
PlusROM cartridges are rewindable but cannot be rewound
backwards past a network event 'boundary'. This to prevent the resending of
already sent network data.
Gopher2600 emulates the ARM7TDMI CPU that is found in the
cartridge. The presence of this CPU allows for highly flexible coprocessing.
Although the Harmony itself executes in both ARM and Thumb modes,
currently only emulates Thumb mode. It has been decided that ARM mode emulation
is not required - better to reimplement the ARM driver in the emulator's host
language (Go) - but it may be added in the future.
The characteristics of the ARM processor can be changed via the preferences window.
In playmode the preferences window can by opened by pressing
F10. Select the
Immediate ARM Execution instructs the emulation to execute the Thumb program
instantaneously without any cycle counting. For performance reasons, you may
want to have this selected but for development work you should leave it
If immediate mode is disabled then the
Default MAM State can be selected.
This is best kept set to the default,
Driver. This means that the emulated
drivers for the ARM using cartridge type set the MAM appropriately. If
required, this can be changed to
Abort on Illegal Memory Access option controls what happens when the
custom Thumb program tries to read or write to memory that doesn't exist. If
the option is on then the Thumb program will exit early and the 6502 program
(ie. normal console operation) will continue.
Note that if the memory access is an instruction fetch the program will always exit early regardless of this option's setting - there's nothing meaningful that can be done if the PC value is out of range.
Details of illegal memory accesses are always written to the log, regardless of
Abort on Illegal Memory Access option.
Gopher2600 debugger provides a
last execution window when an ARM using
cartridge is loaded. This window shows the disassembly of the most recent
execution of the ARM program. It is available via the
which will appear in the menubar if the coprocessor is present.
Goto button wil rewind the emulation to the point where the
ARM program last executed.
Save CSV button meanwhile will write a copy of the disassembly to a file
in the working directory. The file will be a semi-colon separated CSV file (not
commas in this instance).
Note that when the ARM emulation is run in
immediate mode, the cycles column
will not contain any meaningful information.
Estimation of ARM Execution Time (Cycle Counting)
For ARM development the
ARM7TDMI overlay is provided. This overlay will be
empty if the
Immediate ARM Execution option is enabled but normally it will
indicate the period the ARM program is running and the 6507 program is stalled.
Also note that for best results the
cropping option (see screenshot) should be disabled.
This view is useful during development to make sure you ARM program isn't running for too long.
Movie Cart is a new cartridge type specifically aimed at playing full length
movies on the Atari VCS. The reference code and circuit board information can
be found on Github: https://github.com/lodefmode/moviecart.
Gopher2600 allows Movie Cart files to be played just like any other ROM.
Files must have the '.mvc' file extension and can only be streamed from the a
local filing system. Streaming over HTTP will be supported in the future.
Gopher2600 can record all user input and playback for future viewing. This is a very efficient way
of recording gameplay and results in far smaller files than a video recording. It also has other uses,
not least for the recording of complex tests for the regression database.
To record a gameplay session, use the
record flag. Note that we have to specify the
run mode for the
flag to be recognised:
> gopher2600 run -record roms/Pitfall.bin
This will result in a recording file in your current working directory, with a name something like:
To playback a recording, simply specify the recording file instead of a ROM file:
> gopher2600 recording_Pitfall_20200201_093658
To help with the development process a regression testing system was added. This will prove useful during further development. To quickly add a ROM to the database:
> gopher2600 regress add roms/Pitfall.bin
By default, this adds a "video digest" of the first 10 frames of the named ROM. We can alter the
number of frames, and also other parameters with
regress add mode flags. For example, to run for
100 frames instead of 10:
> gopher2600 regress add -frames 100 roms/Pitfall.bin
The database also supports the adding of playback files. When the test is run, the playback file is run as normal and success measured. To add a playback to the test data, simply specify the playback file instead of a rom:
> gopher2600 regress add recording_Pitfall_20200201_093658
Consult the output of
gopher2600 regress add -help for other options.
To listing all previously add tests use the "list" sub-mode:
> gopher2600 regress list > 000 [video] player_switching [AUTO] frames=10 [NUSIZ] > 001 [video] NUSIZTest [AUTO] frames=10 [NUSIZ] > 002 [video] testSize2Copies_A [AUTO] frames=10 [NUSIZ] > 003 [video] testSize2Copies_B [AUTO] frames=10 [NUSIZ] > 004 [video] player8 [AUTO] frames=10 [NUSIZ] > 005 [video] player16 [AUTO] frames=10 [NUSIZ] > 006 [video] player32 [AUTO] frames=10 [NUSIZ] > 007 [video] barber [AUTO] frames=10 [NUSIZ] > 008 [video] test1.bas [AUTO] frames=10 [TIMER] > 009 [video] test2.bas [AUTO] frames=10 [TIMER] > 010 [video] test3.bas [AUTO] frames=10 [TIMER] > 011 [video] test4.bas [AUTO] frames=10 [TIMER] > Total: 12
To run all tests, use the
> gopher2600 regress run
To run specific tests, list the test numbers (as seen in the list command result) on the command line. For example:
> gopher2600 regress run 1 3 5
An interrupt signal (ctrl-c) will skip the current test. Two interrupt signals within a quarter of a second will stop the regression run completely.
Delete tests with the
delete sub-mode. For example:
> gopher2600 regress delete 3
The setup system is currently available only to those willing to edit the "database" system by hand.
The database is called
setupDB and is located in the project's configuration directory. The format
of the database is described in the setup package. Here is the direct link to the source
level documentation: https://godoc.org/github.com/JetSetIlly/Gopher2600/setup
This area of the emulation will be expanded upon in the future.
Supported Cartridge Formats
Gopher2600 currently supports the following formats:
- Atari 2k/4k/16/32k
- all of the above with the
- CBS (FA)
- Tigervision (3F)
- Parker Bros (E0)
- M-Network (E7)
In also supports the Supercharger format in both the
.bin format and is also able to load from an
MP3 recording of the supercharger tape.
Modern formats supported:
- CDF (including CDFJ and CDFJ+)
The last two formats often make use of the
ARM7TDMI coprocessor as found in
Harmony cartridge and are fully supported by
- X07. This was only ever used as far as I know, with
Stella's Stockingwhich has never been released (ROM dumped).
Playmode and debug mode can both be launched with a statistics viewer available
locally on your machine
> gopher2600 -statsview <rom> > gopher2600 debug -statsview <rom>
The screen below shows an example of the featured statistics. In this instance, this is the debugger running a 4k Atari cartridge (specifically, Pitfall).
For people who really want to dig deep into the running program,
localhost:12600/debug/pprof/ gives more raw, but still useful
Note that this feature requires you run a suitably compiled executable. The easiest way to do this is to use the Makefile.
> make release_statsview
See the https://github.com/JetSetIlly/Gopher2600-Utils/ repository for examples of tools
The Stella project (https://stella-emu.github.io/) was used as a reference for video output. In the absence of VCS hardware (which I don't have) Stella was the only option I had for checking video accuracy.
No reference to the Stella source was made at all except for the following:
During the development of the CDF cartridge formats. These recent formats don't seem to be documented anywhere accept in the Stella source.
The audio sub-system to convince myself that I was going about the problem correctly. Primarily however,
Gopher2600'saudio implementation references Ron Fries' original TIASound.c file.
ParkerBros fingerprint taken from Stella. I can't remember why I did this but a comment in the fingerprint.go file says I did.
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"
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 will 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.
Audio mixing was improved by the information found in the document, "TIA Sounding Off In The Digital Domain", by Chris Brenner.
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.
US Patent Number 4,644,495 was referenced for the implementation of the DPC cartridge format (the format used in Pitfall 2)
DPC+ format implemented according to notes provided by Spiceware https://atariage.com/forums/topic/163495-harmony-dpc-programming and
DPC+ARM information on Spiceware's blog
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
Reference for the ARM7TDMI-S, as used in the Harmony cartridge formats:
For detail about the Thumb instruction set the following document was preferred. Mnemonics used in the ARM disassembly are from this document:
Further information from the ARM Architecture Reference Manual:
Specific information about UXP ARM7TDMI-S
In addition to this readme, more information can be found with the command line
Many modes and sub-modes will accept operational flags. Specifying the
-help flag will print
a brief summary of available options.
Help on debugger commands is available with the
HELP command at the debugger command line.
More information is available in the Go source files and can be viewed with the
Go documentation system. With
> GOMOD=$(pwd) godoc -http=localhost:1234 -index >/dev/null &
Alternatively, the most current version of the docs available on github can be viewed at https://godoc.org/github.com/JetSetIlly/Gopher2600
Finally, development and maintenance documentation is beginning to be stored in its own Github repository: https://github.com/JetSetIlly/Gopher2600-Dev-Docs
There are some design decisions that would perhaps be made differently if I had known where the program was going. For instance, because the project was a way of learning a new programming language I chose to implement my own "database" to store regression test information. A more natural choice would be to use SQlite but actually the current solution works quite well.
A couple of packages may well be useful in other projects. The
is quite versatile. With a bit of work it could be generalised and put to use
in other projects. I think though, this package is a natural candidate to be
rewritten with type parameters. Not yet available in Go but scheduled for
release in 2022.
I would also replace the
commandline package. It works quite nicely but as
you would expect from a home-baked solution there are limitations to the
parser. It should be rewritten with
Other Software / Libraries
The following projects are used in the
Statsview provided by:
For testing instrumentation:
Some ideas for the fragment shader taken from:
There is no documentation for this package.
Package cartridgeloader is used to specify the cartridge data that is to be attached to the emulated VCS.
|Package cartridgeloader is used to specify the cartridge data that is to be attached to the emulated VCS.|
Package curated is a helper package for the plain Go language error type.
|Package curated is a helper package for the plain Go language error type.|
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.|
Package script allows the debugger to record and replay debugging scripts.
|Package script allows the debugger to record and replay debugging scripts.|
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.|
Package colorterm implements the Terminal interface for the gopher2600 debugger.
|Package colorterm implements the Terminal interface for the gopher2600 debugger.|
Package easyterm is a wrapper for "github.com/pkg/term/termios".
|Package easyterm is a wrapper for "github.com/pkg/term/termios".|
Package ansi defines ANSI control codes for styles and colours.
|Package ansi defines ANSI control codes for styles and colours.|
Package commandline facilitates parsing of command line input.
|Package commandline facilitates parsing of command line input.|
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.|
Package coprocessor is used to capture execution/disassembly information from any program running on a coprocessor that may be present in an attached VCS cartridge.
|Package coprocessor is used to capture execution/disassembly information from any program running on a coprocessor that may be present in an attached VCS cartridge.|
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 emulation is an abstraction of the various modes Gopher2600 can operate in, principally play-mode and the debugger.
|Package emulation is an abstraction of the various modes Gopher2600 can operate in, principally play-mode and the debugger.|
Package gui is an abstraction layer for real GUI implementations.
|Package gui is an abstraction layer for real GUI implementations.|
Package CRT contains non-gui-specific and non-VCS-specific information.
|Package CRT contains non-gui-specific and non-VCS-specific information.|
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.|
Package sdlaudio provides the Audio type.
|Package sdlaudio provides the Audio type.|
This file is part of Gopher2600.
|This file is part of Gopher2600.|
Package framebuffer provides a convenient way of working with OpenGL framebuffers.
|Package framebuffer provides a convenient way of working with OpenGL framebuffers.|
Package lazyvalues is the method used by sdlimgui to read emulator data from the GUI thread.
|Package lazyvalues is the method used by sdlimgui to read emulator data from the GUI thread.|
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.|
Package cpu emulates the 6507 microprocessor found in the Atari VCS.
|Package cpu emulates the 6507 microprocessor found in the Atari VCS.|
Package execution tracks the result of instruction execution on the CPU.
|Package execution tracks the result of instruction execution on the CPU.|
Package instructions defines the table of instruction for the 6507.
|Package instructions defines the table of instruction for the 6507.|
Package registers implements the three types of registers found in the 6507.
|Package registers implements the three types of registers found in the 6507.|
Package test contains functions useful for testing CPU registers.
|Package test contains functions useful for testing CPU registers.|
Package memory implements the Atari VCS memory model.
|Package memory implements the Atari VCS memory model.|
Package addresses contains all information about VCS addresses and registers, including canonical symbols for read and write addresses and registers.
|Package addresses contains all information about VCS addresses and registers, including canonical symbols for read and write addresses and registers.|
Package bus defines the memory bus concept.
|Package bus defines the memory bus concept.|
Package cartridge fully implements loading of mapping of cartridge memory.
|Package cartridge fully implements loading of mapping of cartridge memory.|
Package harmony implements the Harmony cartridge.
|Package harmony implements the Harmony cartridge.|
Package arm7tdmi imlplements the ARM7TDMI instruction set as defined in the ARM7TDMI Instruction Set Reference: http://www.ecs.csun.edu/~smirzaei/docs/ece425/arm7tdmi_instruction_set_reference.pdf For this project we only need to emulte the Thumb architecture.
|Package arm7tdmi imlplements the ARM7TDMI instruction set as defined in the ARM7TDMI Instruction Set Reference: http://www.ecs.csun.edu/~smirzaei/docs/ece425/arm7tdmi_instruction_set_reference.pdf For this project we only need to emulte the Thumb architecture.|
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.|
Package cdf implemnents the various CDF type cartridge mappers including CDFJ.
|Package cdf implemnents the various CDF type cartridge mappers including CDFJ.|
Package dpcplus implements the DPC+ cartridge mapper.
|Package dpcplus implements the DPC+ cartridge mapper.|
Package mapper contains the CartMapper interface.
|Package mapper contains the CartMapper interface.|
Package moviecart implements the Movie Cart special cartridge type.
|Package moviecart implements the Movie Cart special cartridge type.|
Package plusrom implements the PlusROM cartridge as developed by Wolfgang Stubig.
|Package plusrom implements the PlusROM cartridge as developed by Wolfgang Stubig.|
Package supercharger implements the tape based cartridge format.
|Package supercharger implements the tape based cartridge format.|
Package memorymap facilitates the translation of addresses to primary address equivalents.
|Package memorymap facilitates the translation of addresses to primary address equivalents.|
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.|
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.|
Package riot (RIOT) represents the active part of the PIA 6532.
|Package riot (RIOT) represents the active part of the PIA 6532.|
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).|
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.|
Package panel implements the front control panel of the VCS.
|Package panel implements the front control panel of the VCS.|
Package plugging conceptualises the act of plugging devices into the VCS ports.
|Package plugging conceptualises the act of plugging devices into the VCS ports.|
Package savekey implements the SaveKey external memory card.
|Package savekey implements the SaveKey external memory card.|
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).|
Package television implements the output device of the emulated VCS.
|Package television implements the output device of the emulated VCS.|
Package signal exposes the interface between the VCS and the television implementation.
|Package signal exposes the interface between the VCS and the television implementation.|
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.|
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.|
Package audio implements the audio generation of the TIA.
|Package audio implements the audio generation of the TIA.|
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.|
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.|
Package hmove represents the TIA HMOVE process.
|Package hmove represents the TIA HMOVE process.|
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.|
Package polycounter implements the polynomial counters found in the TIA.
|Package polycounter implements the polynomial counters found in the TIA.|
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.|
Package video implements pixel generation for the emulated TIA.
|Package video implements pixel generation for the emulated TIA.|
Hiscore package implements the communication between a Gopher2600 high-score server and the local client.
|Hiscore package implements the communication between a Gopher2600 high-score server and the local client.|
Package linter analyses disassembled code (from the disassembly package) producing a lint report.
|Package linter analyses disassembled code (from the disassembly package) producing a lint report.|
Package logger is the central log repository for gopher2600.
|Package logger is the central log repository for gopher2600.|
Package modalflag is a wrapper for the flag package in the Go standard library.
|Package modalflag is a wrapper for the flag package in the Go standard library.|
Package patch is used to patch the contents of a cartridge.
|Package patch is used to patch the contents of a cartridge.|
Package paths contains functions to prepare paths for gopher2600 resources.
|Package paths contains functions to prepare paths for gopher2600 resources.|
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.|
Package performance contains helper functions relating to performance.
|Package performance contains helper functions relating to performance.|
Package playmode is a simple way of running the emulation.
|Package playmode is a simple way of running the emulation.|
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 recorder handles recording and playback of user input.
|Package recorder handles recording and playback of user input.|
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.|
Package regression facilitates the regression testing of emulation code.
|Package regression facilitates the regression testing of emulation code.|
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 statsview is an optional package that will built only when the +statsview build constraint is present It provides a HTTP server running locally offering runtime statistics.
|Package statsview is an optional package that will built only when the +statsview build constraint is present It provides a HTTP server running locally offering runtime statistics.|
Package test bundles a bunch of useful functions useful for testing purposes, particular useful in conjunction with the standard go test harness The AssertMainThread() and AssertNonMainThread() functions require a bit of explanation.
|Package test bundles a bunch of useful functions useful for testing purposes, particular useful in conjunction with the standard go test harness The AssertMainThread() and AssertNonMainThread() functions require a bit of explanation.|
Package userinput handles input from real hardware that the the user of the emulator is using to control the emualted console.
|Package userinput handles input from real hardware that the the user of the emulator is using to control the emualted console.|
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.|