how2port.txt

著名SFC模拟器Snes9x的源代码。

                   How to Port Snes9x to a New Platform
                   ====================================

Version: 1.01
Date: 23-December-1998

(c) Copyright 1998 Gary Henderson ([e-mail])

Introduction
============

This is brief description of the steps involved in porting Snes9x, the Super
Nintendo Entertainment System emulator, to new hardware which is at least
similar to Workstation or PC. It describes what code you have to write and
what functions exist that you can make use of. It also gives some insights as
to how Snes9x actually works, although that will be subject of another
document yet to be written.

Host System Requirements
========================

A C++ compiler, so you can compile the emulator! Snes9x really isn't written
in C++, it just uses the C++ compiler as a 'better C' compiler to get inline
functions and so on. With some modification, it could be converted to be
compiled with an ordinary C compiler. Snes9x isn't very C type safe and
will probably not work on a system who's integers are less than 32-bits wide
without lots of editing.

If the host system uses a CPU that implements the i386 instruction set then
you will also want to use the three assembler CPU cores, although I recently
scrapped the SPC700 assembler code (too many bugs) and replaced it with
compiler generated assembler code that I haven't got around to optimising
yet.  The 65c816 and SPC700 code needs to be assembled using the GNU
assembler that comes with gcc and the Super FX code assembled with NASM
v0.97 or higher. gcc is available from lots of sites. NASM is available from
http://www.cryogen.com/Nasm

A fast CPU. SNES emulation is very compute intensive: two, or sometimes three
CPUs to emulate, an 8-channel 16-bit stereo sound digital signal processor
with real-time sample decompression, filter and echo effects, two custom
graphics processor chips that can produce transparency, scaling, rotation
and window effects in 32768 colors, and finally hardware DMA all take their
toll on the host CPU.

Lots of RAM. The SNES itself has 128k work RAM, 64k V-RAM and 64k sound CPU
RAM. If a Super FX game is being emulated, that usually comes with another
64k inside the game pack. Snes9x itself needs 4Mb to load SNES ROM images
into (or 6Mb if I ever figure out the SNES memory map of the 48Mbit ROM
images out there), 256k to cache decompressed sound samples in, 512k to
cache converted SNES tiles in, and another 64k for S-RAM emulation. And
that's not counting a few large lookup tables that the graphics code needs
for speeding up transparency effects plus few other tables used by the ZSNES
Super FX code. It all adds up to 7Mb (ish). Add to that RAM needed to
store the actual emulator code and RAM required by the host operating system
and any other process that is running; that's lots of RAM. Well, it is if
your host system only has a few mega-bytes of RAM available.

An 8-bit, 256 color (one byte per pixel) or deeper display, at least 256x239
pixels in resolution, or 512x478 if you're going to support the SNES'
hi-res. background screen modes. Ideally, a 16-bit, 65536 color screen mode
is required if you want to support transparency at speed, as that is what the
code renders internally. Any other format screen, with transparency enabled,
will require picture format conversion before you can place the rendered
SNES image on to the screen.

Sound output requires spooling 8-bit or 16-bit, mono or stereo digital sound
data to the host computer's sound hardware. The DOS port uses interrupts
from the sound card to know when more sound data is required, most other
ports have to periodically poll the host sound hardware to see if more data
is required; if it is then the SNES sound mixing code provided by Snes9x is
called to fill an area of system memory with ready mixed SNES sound data,
which then can be passed on to the host sound hardware. Sound data is
generated as an array of bytes (uint8) for 8-bit sound or shorts (int16) for
16-bit data.  Stereo sound data generates twice as many samples, with each
channel's samples interleaved, first left's then right's.

For the user to be able to control and play SNES games, some form of input
device is required, a joystick or keyboard, for example. The real SNES can
have 2 eight-button digital joy-pads connected to it or 5 joy-pads when an
optional multi-player adaptor was purchased, although most games only require
a single joy-pad. Access to all eight buttons and the direction pad, of
course, are usually required by most games. Snes9x does emulate the
multi-player adaptor hardware, if you were wondering, but its still up to
you to provide the emulation of the individual joy-pads.

The SNES also had a mouse and light gun available as optional extras,
Snes9x can emulate both of these using some form of pointing device,
usually the host system's mouse.

If an accurate, constant SNES play rate is required, then a real-time timer
will be needed that can time intervals of 16.7ms (NTSC frame time) or 20ms
(PAL frame time).

Some SNES game packs contained a small amount of extra RAM and a battery so
ROMs could save a player's progress through a game for games that takes many
hours to play from start to finish.  Snes9x simulates this S-RAM by saving
the contents of the area of memory normally occupied by the S-RAM into file
then automatically restoring it again the next time the user plays the same
game. If the hardware you're porting to doesn't have a hard disk available
then you could be in trouble.

Snes9x also implements freeze-game files which can record the state of the
SNES hardware and RAM at a particular point in time and can restore it to
that exact state at a later date - the result is that users can save a game
at any point, not just at save-game or password points provided by the
original game coders. Each freeze file is over 400k in size. To help save
disk space, Snes9x can be compiled with zlib, which is used to compress the
freeze files, reducing the size to typically below 100k.  Download zlib from
its homepage at http://www.cdrom.com/pub/infozip/zlib/, compile Snes9x with
ZLIB defined and link with zlib. zlib is also used to load any compressed
ROM images Snes9x my encounter, compressed with gzip or compress.

Porting
=======

In theory you will only need to edit port.h, then in a separate file write
all the initialisation code and interface routines that Snes9x expects the
you to implement. You, no doubt, will discover otherwise....

There are several compile-time only options available:

DEBUGGER
--------

Enables extra code to assist me in debugging SNES ROMs. The debugger has only
ever been a quick-hack by me and user-interface to debugger facilities is
virtually non-existent. Most of the debugger information is output via
stdout and enabling the compile-time options slows the whole emulator down
slightly. However, the debugger options available are very powerful; you
could use it to help get your port working. You probably still want to ship
the finished version with the debugger disabled, it will only confuse
non-technical users.

VAR_CYCLES
----------

I recommend you define this. The main CPU in the SNES actually varies in
speed depending on what area of memory its accessing and the ROM access
speed of the game pack; defining VAR_CYCLES causes Snes9x to emulate this,
using a good approximation, rather than fixed cycle length as ZSNES does. The
resultant code is slightly slower. Leaving it undefined results in many more
emulation timing errors appearing while playing games.

CPU_SHUTDOWN and SPC700_SHUTDOWN
--------------------------------

Again I recommend defining both of these. They are both speed up hacks.
When defined, Snes9x starts watching for when either the main or sound CPUs
are in simply loops waiting for a known event to happen - like the end of
the current scan-line, and interrupt or a sound timer to reach a particular
value. If Snes9x spots either CPU in such a loop it uses its insider
knowledge to simply skip the emulation of that CPU's instructions until the
event happens. It can be a big win with lots of SNES games.

I'm constantly amazed at the ingenuity of some programmers who are able to
produce complex code to do simple things: some ROM's wait loops are so
complex Snes9x fails to spot the CPU is in such a loop and the shutdown
speed up hacks don't work.

You might be wondering why VAR_CYCLES, and the two SHUTDOWN options have to
be enabled with defines, well, in the past they sometimes introduced
problems with some ROMs, so I kept them as options. I think I've fixed all
the problems now, but you never know...

SPC700_C
--------

Define this if you are using the C/C++ version of the SPC700 CPU core. It
enables a ROM compatibility feature that executes SPC700 instructions during
SNES DMA, it allows several games to start that would otherwise lock up and
fixes music pauses when ROMs do lots of DMA, usually when switching between
game screens.

ZLIB
----

Define this if you have the zlib library available and you want it to
compress freeze-game files to save disk space. The library is also used to
support compressed ROM images.

NO_INLINE_SET_GET
-----------------

Define this to stop several of the memory access routines from being
defined in-line. Whether the C++ compiler actually in-lines when this symbol
is not defined is up to the compiler itself. In-lines functions can speed up
the C++ CPU emulations on some architectures at the cost of increased code
size. Try fiddling with this option once you've got port working to see if
it helps the speed of your port.

EXECUTE_SUPERFX_PER_LINE and ZSNES_FX
-------------------------------------

Define these if you're going to be using the ZSNES Super FX i386 assembler
code, otherwise leave them both undefined. In theory,
EXECUTE_SUPERFX_PER_LINE can also be defined when using the C++ Super FX
emulation code, but the code is still buggy and enabling the option
introduces more problems than it fixes. Any takers for fixing the C++ code?

JOYSTICK_SUPPORT, SIDEWINDER_SUPPORT and GRIP_SUPPORT
-----------------------------------------------------

These options enable support for various input devices in the UNIX and MS-DOS
port code. They're only of interest if you're able to use the existing UNIX
or MS-DOS port specific code.

port.h
======

If the byte ordering of the target system is least significant byte first,
make sure LSB_FIRST is defined in this header, otherwise, make sure its not
defined.

If you're going to support 16-bit screen rendering (required if you want
transparency effects) and your system doesn't use RGB 565 - 5 bits for red,
6 bits for green and 5 bits for blue - then you'll need make sure RGB555,
BGR565 or BGR555 is defined instead. You might want to take a look at the
*_LOW_BIT_MASKs, *_HI_BIT_MASKs and BUILD_PIXEL macros to make sure they're
correct, because I've only every tested the RGB565 version, though the Mac
port uses the RGB555 option. If your system is 24 or 32-bit only, then
don't define anything; instead write a conversion routine that will take a
complete rendered 16-bit SNES screen in RGB565 format and convert to the
format required to be displayed on your hardware.

port.h also typedefs some types, uint8 for an unsigned, 8-bit quantity,
uint16 for an unsigned, 16-bit quantity, uint32 for a 32-bit, unsigned
quantity and bool8 for a true/false type. Signed versions are also
typedef'ed.

The CHECK_SOUND macro can be defined to invoke some code that polls the
host system's sound hardware to see if it can accept any more sound data.
Snes9x makes calls to this macro several times when it is rendering the SNES
screen, during large SNES DMAs and after every emulated CPU instruction.

Since this CHECK_SOUND macro is invoked often, the code should only take a
very small amount of time to execute or it will slow down the emulator's
performance. The Linux and UNIX ports use a system timer and set a variable
when it has expired; the CHECK_SOUND only has to check to see if the
variable is set. On the MS-DOS and Mac ports, the sound hardware is not
polled at all, instead it is driven by interrupts or callbacks and the
CHECK_SOUND macro is defined to be empty.