TuxNES Hacking Guide

This file serves as a guide to developers interested in hacking on the
TuxNES codebase.


Coding Style
=----------=
The source code files in the TuxNES follow a certain coding style. You may
not agree with the style, but it is customary, when hacking on a project's
codebase, to conform to that project's coding style.

Use C89 comments (/* */) when commenting in the sources.
Also, when commenting out code, please use #if 0/#endif pairs instead.  This
allows for better nesting.


Architecture Overview
=-------------------=
An effective NES emulator basically boils down to this main loop:

 main:
  simulate ~114 cycles worth of 6502 CPU machine cycles
  draw 1 out of 240 image lines containing 256 pixels
  if all 240 lines are drawn, display image to the user
  goto main

A NES has a refresh rate of 60 Hz (at least for NTSC television; 50 Hz for
PAL). This means that the emulator needs to be able to perform the main
loop 60 times every second in order to maintain the illusion of being a
real NES.

There are other considerations, such as user input and audio synthesis, in
the architecture as well.

The program starts in emu.c.

CPU Emulation
=-----------=
Many emulator programs emulate a CPU by translating opcodes. With
this approach, the emulator program uses a variable which simulates a 
CPU program counter (PC) to walk through a region of opcodes which
represent an executable program written for a different CPU architecture.

TuxNES takes a slightly different approach to CPU emulation known as
dynamic recompilation (henceforth referred to as dyn-rec). The dyn-rec
approach transforms the CPU opcodes to be emulated into optimized native
machine opcodes on the fly.

Problems with the dyn-rec approach are:
It doesn't handle self-modifying code
It doesn't handle arbitrary reads and writes in the lower half of memory
There's a lot of assembly coding involved
Assembly is inherently unportable

Graphics
=------=


Sound
=---=


Mapper Interface
=--------------=
Many NES cartridges contain special hardware which effectively
extends the capability of the NES. This is one factor that makes NES
emulation inherently challenging: It's not enough simply to simulate the
functionality of NES hardware; special cartridge mapping hardware must
be simulated as well. The good news is that the majority of NES titles
use the same few sets of common mapper hardware. The bad news is that
there is also a plethora of titles, many from Japan, that rely on
their own custom hardware.

Due to the current limitations with the TuxNES dyn-rec implementation,
mappers which have registers mapped in the lower half of the 6502
address space ($0000 -> $7FFF) can't be emulated.

Any particular mapper has likely already been assigned an 8-bit
numerical designation in the NES emulation community. Many of the most
common mappers have already been implemented in TuxNES. However, if you
would like to add a new mapper, here are some general steps.

- Take a look through mapper.c. The mapper interface is relatively
simple.
- Decide on a name for the mapper. This will usually come from the
mapper documents publically available from the nesdev community. For
example, mapper #2 is referred to as "unrom".
- 

How to add a new mapper
Support functions
TuxNES limitations for mapper implementations
