first commit

1 files changed, 725 insertions, 0 deletions

diff --git a/source/doc/porting.txt b/source/doc/porting.txt
new file mode 100644
index 0000000..3d28eec
--- /dev/null
+++ b/source/doc/porting.txt
@@ -0,0 +1,725 @@
+                   How to Port Snes9x to a New Platform
+                   ====================================
+
+Version: 1.01
+Date: 23-December-1998
+
+(c) Copyright 1998 Gary Henderson (gary@daniver.demon.co.uk)
+
+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.
+
+Initialisation Code
+-------------------
+
+This is what the Linux, UNIX and MS-DOS ports do, I suspect your code
+might be similar:
+
+- The Settings structure is initialised to some sensible default values -
+  check the main function in unix.cpp for the values it uses.
+
+- The command line is parsed, options specified override default values in
+  the Settings structure and specify a ROM image filename that the user
+  wants loaded. Your port could load user preferences from a file or some
+  other source at this point. Most values, with a little care, can be changed
+  via a GUI once the emulator is running.
+
+- Some Settings structure value validation takes place, for example if
+  transparency effects are requested the code also makes sure 16-bit
+  screen rendering is turned on as well.
+
+- Memory.Init() and S9xInitAPU() are called, checking neither failed. The
+  only reason they would fail is if memory allocation failed.
+
+- Memory.LoadROM (filename) is called to load the specified ROM image into
+  memory. If that worked Memory.LoadSRAM (sram_filename) is called to load
+  the ROM's S-RAM file, if one exists. The all current ports base the
+  sram_filename on the filename of the ROM image, changing the file's
+  extension (the .smc or whatever bit) and changing the directory where its
+  located - you won't be able to save S-RAM files onto a CD if that's where
+  the ROM image is located!
+
+  If your port has a GUI, you can delay this step until the user picks an
+  image to load.
+
+  SNES roms images come in all shapes and sizes, some with headers, some
+  without, some have been mangled by the copier device in one of two ways, and
+  some split into several pieces; plus the SNES itself has several different
+  memory map models. The code tries to auto-detect all these various types,
+  but sometimes the SNES ROM header information has been manually edited by
+  someone at some stage and the code guesses wrong. To help it out it these
+  situations, the Settings structure contains several options to force a
+  particular ROM image format; these values must be initialised prior to each
+  call to Memory.LoadROM(filename).
+
+- The Linux and UNIX ports now do some more operating system initialisation
+  ready for a system timer to be started.
+
+- The host display hardware is now initialised. The actual screen depth and
+  resolution should be picked based on the user preferences if possible.
+  The X Window System port can't control the screen depth or resolution, if
+  the user requests transparency effects but the display hardware is only
+  set to 8-bit, it has to invoke an extra step of converting the 16-bit SNES
+  rendered screen to a fixed palette 8-bit display just before the SNES
+  screen is copied to the display hardware.
+
+  The GFX.Screen pointer needs to be initialised to point to an array of
+  uint8 for 8-bit screen rendering or uint16 for 16-bit rendering, cast to
+  an array of uint8. The array needs to be at least 256x239 bytes or shorts
+  in size for lo-res only support (Settings.SupportHiRes = FALSE) or
+  512x478 for lo-res and hi-res support. If transparency effects are
+  required, the GFX.SubScreen array also needs to be initialised to another
+  identically sized array of the same type, otherwise it can be just
+  initialised to NULL.
+
+  The GFX.Pitch variable needs to be set to the number of bytes on each line
+  of the arrays, e.g. 256 for lo-res only support, up to 1024 for 16-bit
+  hi-res support. If GFX.Screen is pointing into an existing array, one
+  created by the library function rather than just calling malloc or new,
+  then set GFX.Pitch to the number of bytes per line of that array,
+  including any padding the library function may have added.
+
+  If the target hardware supports fast access to video RAM, the screen is in
+  16-bit format supported by the SNES rendering code and you can double
+  buffer the display, you might want to point GFX.Screen directly at the
+  video buffer RAM. You will need to recompute the GFX.Delta value every
+  time you change the GFX.Screen value to double-buffer the rendering and
+  display.
+
+- A call to S9xGraphicsInit() is made; make sure all your graphics rendering
+  options are setup correctly by now. If later, you want to change some
+  settings, for example 16-bit to 8-bit rendering, call S9xGraphicsDeinit()
+  first, change your settings, GFX.Screen and GFX.SubScreen arrays, etc.,
+  then call S9xGraphicsInit() again.
+
+- S9xInitSound(int playbackrate, bool8 stereo, int sound_buffer_size)
+  is now called, which in turn will call your S9xOpenSoundDevice function -
+  see below.
+
+- The display is switched to graphics mode using a call to S9xGraphicsMode().
+
+- The system timer is started; its used for keeping the emulator speed
+  relatively constant on the MS-DOS port and noting when the sound hardware
+  sound should be able to accept more sound data on the Linux and UNIX ports.
+
+- A main loop is entered which is just a loop constantly calling
+  S9xMainLoop() then polling the operating system for any pending events
+  such as key presses and releases, joystick updates, mouse position
+  updates, GUI user interaction, etc. 
+
+  Pause functionality can be implemented by skipping the call to S9xMainLoop
+  and muting the sound output by calling S9xSetSoundMute (TRUE).
+
+  Don't enter the main loop until a SNES ROM image has been loaded, or at
+  least skip calling S9xMainLoop inside the loop until one is and make sure
+  S9xReset is called instead before entering the main loop. The Mac port
+  implements this technique by starting in pause mode and refusing to unpause
+  until a ROM image is loaded.
+
+  S9xMainLoop processes SNES CPU emulation, SNES screen rendering, DMA and
+  H-DMA emulation, until emulated scan-line 0 is reached, then it returns.
+  Now is your chance to process any system events pending, scan the
+  keyboard, read joystick values, etc.
+
+  If DEBUGGER compile-time support is enabled and the CPU emulation has hit
+  a break point or single-stepping is switched on, or the DEBUG_MODE_FLAG is
+  set in the CPU.Flags variable, then the S9xMainLoop routine returns early,
+  allowing you to act on the event in some way. The Linux, DOS and UNIX ports
+  respond to the DEBUG_MODE_FLAG being set by calling S9xDoDebug(), which in
+  turn outputs the current instruction and loops reading commands from stdin
+  and outputting debug information, currently via stdout. The debugger
+  desperately needs rewriting to support a GUI interface, more descriptive
+  commands and better error handling; maybe one day...
+
+Existing Interface Routines
+---------------------------
+
+These are routines already written that you will either need to call or
+might find useful.
+
+-> bool8 Memory.Init ()
+
+Allocates and initialises several major lumps of memory, for example
+the SNES ROM and RAM arrays, tile cache arrays, etc. Returns FALSE if
+memory allocation fails.
+
+-> void Memory.Deinit ()
+
+Undoes the memory allocations made by Memory.Init.
+
+-> bool8 S9xGraphicsInit ()
+
+Allocated and initialises several lookup tables used to speed up SNES
+graphics rendering. Call after you have initialised the GFX.Screen, 
+GFX.SubScreen and GFX.Pitch values. If Settings.Transparency is false it
+does not allocate tables used to speed up transparency effects. If you
+want to provide the user with option to turn the effects on and off during
+game play, make sure Settings.Transparency is true when this function is
+called, it can later be set to FALSE.
+
+Returns FALSE if memory allocation fails.
+
+-> void S9xGraphicsDeinit ()
+
+Undoes the memory allocations made by S9xGraphicsInit.
+
+-> bool8 S9xInitAPU ()
+
+Allocates and initialises several arrays used by the sound CPU and sound
+generation code.
+
+-> void S9xDeinitAPU ()
+
+Undoes the allocations made by S9xInitAPU.
+
+-> bool8 S9xInitSound (int mode, bool8 stereo, int buffer_size)
+
+Does more sound code initialisation and opens the host system's sound hardware
+by calling the S9xOpenSoundDevice function provided by you.
+
+-> void S9xReset ()
+
+Resets the SNES emulated hardware back to the state it was in at 'switch-on'
+except the S-RAM area is presevered. The effect is it resets the current game
+back to the start. This function is automatically called by Memory.LoROM.
+
+-> bool8 Memory.LoadROM (const char *filename)
+
+Attempts to load the specified ROM image filename into the emulated ROM area.
+There are many different SNES ROM image formats and the code attempts to
+auto-detect as many different types as it can and in a vast majority of the
+cases gets it right. However, some ROM images have been edited by someone at
+some stage or have been mangled by the ROM copier that produced them and
+LoadROM needs help. Inparticular, it can't auto-detect the odd way in which
+some Super FX games have been mangled and needs to be told, via
+Settings.Interleaved2, that the ROM image is in that format, or that
+odd-sized ROM images have a 512 byte copier header.
+
+There are several other ROM image options in the Settings structure;
+allow the user to set them before calling LoadROM, or make sure they all
+reset to default values before each call to LoadROM.
+
+-> bool8 Memory.LoadSRAM (const char *filename)
+
+Call this routine to load the associated S-RAM save file (if any). The
+filename should be based on the ROM image name to allow easy linkage.
+The current ports change the directory and the filename extension of the ROM
+filename to derive the S-RAM filename.
+
+-> bool8 Memory.SaveSRAM (const char *filename)
+
+Call this routine to save the emulated S-RAM area into a file so it can
+be restored again the next time the user wants to play the game. Remember
+to call this when just before the emulator exits or when the user has been
+playing a game and is about to load another one.
+
+-> void S9xMainLoop()
+
+The emulator main loop. Call this from your own main loop that calls this
+function (if a ROM image is loaded and the game is not paused), processes
+any pending host system events, then goes back around the loop again until
+the emulator exits.
+
+S9xMainLoop normally returns control to your main loop once every emulated
+frame, when it reaches the start of scan-line zero. However, the routine
+can return more often if the DEBUGGER compile-time flag is defined and the
+CPU has hit a break point, or the DEBUG_MODE_FLAG bit is set in CPU.Flags
+or instruction single-stepping is enabled.
+
+-> void S9xMixSamples (uint8 *buffer, int sample_count)
+
+Call this routine from your host sound hardware handling code to fill the
+specified buffer with ready mixed SNES sound data. If 16-bit sound mode is
+choosen, then the buffer will be filled with an array of sample_count int16,
+otherwise an array of sample_count uint8. If stereo sound generation is
+selected the buffer is filled with the same number of samples, but in pairs,
+first a left channel sample followed by the right channel sample.
+
+There is a limit on how much data S9xMixSamples can deal with in one go and
+hence a limit on the sample_count value; the limit is the value of the
+MAX_BUFFER_SIZE symbol, normally 4096 bytes.
+
+-> bool8 S9xSetSoundMute (bool8 mute)
+
+Call with a TRUE parmeter to prevent S9xMixSamples from processing SNES
+sample data and instead just filling the return buffer with silent sound
+data. Useful if your sound system is interrupt or callback driven and the
+game has been paused either directly or indirectly because the user 
+interacting with the emulator's user interface in some way.
+
+-> bool8 S9xFreezeGame (const char *filename)
+
+Call this routine to record the current SNES hardware state into a file,
+the file can be loaded back using S9xUnfreezeGame at a later date effectively
+restoring the current game to exact same spot. Call this routine while
+you're processing any pending system events when S9xMainLoop has returned
+control to you in your main loop.
+
+-> bool8 S9xUnfreezeGame (const char *filename)
+
+Restore the SNES hardware back to the exactly the state it was in when
+S9xFreezeGame was used to generate the file specified. You have to arrange
+the correct ROM is already loaded using Memory.LoadROM, an easy way to
+arrange this is to base freeze-game filenames on the ROM image name. The
+Linux, UNIX and DOS ports load freeze-game files when the user presses a
+function key, with the names romfilename.000 for F1, romfilename.001 for F2,
+etc. Games are frozen in the first place when the user presses Shift-function
+key. You could choose some other scheme.
+
+-> void S9xNextController ()
+
+The real SNES allows several different types of devices to be plugged into
+the game controller ports. The devices Snes9x emulates are a joy-pad,
+multi-player adaptor (allowing a further 4 joy-pads to be plugged in),
+a 2-button mouse and a light gun known as the SuperScope.
+
+Each call to S9xNextController will step the current emulated device on to
+the next device in the sequence multi-player, joy-pad, mouse on port 1,
+mouse on port 2, light gun then back to multi-player again. Defines
+allocating a number of each device type are in snes9x.h. The currently
+selected device is stored in IPPU.Controller if you want to give some
+feedback to the user. The initial value of IPPU.Controller (set when
+S9xReset is called) is obtained from Settings.ControllerOption based on
+currently enabled options.
+
+Some ROMs object to certain non-joy-pad devices being plugged into the real
+SNES while they are running, all Super FX games should only allow joy-pads to
+be plugged in because the Super FX chip and any other device would overload
+the SNES power supply. Tetris and Dr. Mario also objects for reasons best
+known to itself. For this reason there are switches in the Settings
+structure to enable and display the emulation of the various devices.
+
+const char *S9xGameGenieToRaw (const char *code, uint32 &address, uint8 &byte)
+
+const char *S9xProActionReplayToRaw (const char *code, uint32 &address, 
+                                     uint8 &byte)
+
+const char *S9xGoldFingerToRaw (const char *code, uint32 &address, bool8 &sram,
+			        uint8 &num_bytes, uint8 bytes[3])
+
+void S9xApplyCheats (bool8 apply)
+
+void S9xRemoveCheats ()
+
+void S9xAddCheat (uint32 address, bool8 cpu_address, bool8 sram, uint8 num_bytes,
+	          uint8 byte1, uint8 byte2, uint8 byte3)
+
+void S9xDeleteCheats ()
+
+void S9xDoDebug ()
+
+Interface Routines You Need to Implement
+----------------------------------------
+
+bool8 S9xOpenSnapshotFile (const char *base, bool8 read_only, STREAM *file)
+***************************************************************************
+void S9xCloseSnapshotFile (STREAM file)
+***************************************
+
+Routines to open and close freeze-game files. STREAM is defined as a
+gzFile if ZLIB is defined else its defined as FILE *. The read_only parameter
+is set to TRUE when reading a freeze-game file and FALSE when writing a
+freeze-game file.
+
+void S9xExit ()
+***************
+
+Called when some fatal error situation arises or when the 'q' debugger
+command is used. The Mac port just beeps and drops back to the GUI when
+S9xExit is called, the MS-DOS, Linux and Solaris ports all call exit () to
+terminate the emulator process.
+
+void S9xParseArg (char **argv, int &index, int argc)
+****************************************************
+
+void S9xExtraUsage ()
+*********************
+
+If you're going to be using the simple command line parser, when it
+encounters an unknown option it calls S9xUsage which is supposed to report
+all options the generic parse knows about (I haven't been keeping it up to
+date of late). S9xUsage then, in turn calls S9xExtraUsage which you
+implement to report any port-specific options available.
+
+void S9xGraphicsMode ()
+***********************
+void S9xTextMode ()
+*******************
+
+The SNES debugger calls these routines to switch from a graphics screen
+mode used to display the SNES game to a debugger screen used to display
+debugger output. If the SNES screen can be displayed at the same time as
+a text display, as would be the case when the host system implements a
+graphical window system, or you're not going to support the SNES debugger,
+then these routines should do nothing.
+
+On the X Window System UNIX/Linux port, these routines do nothing where as
+on the MS-DOS port they switch between a graphics screen mode and a text-only
+screen mode.
+
+bool8 S9xInitUpdate ()
+**********************
+
+Called just before Snes9x starts to render a SNES screen. The Windows port
+uses this call to lock Direct X screen area to allow exclusive access; on
+other existing ports its implemented as an empty function.
+
+bool8 S9xDeinitDisplay (int width, int height, bool8 sixteen_bit)
+*****************************************************************
+
+Called once a complete SNES screen has been rendered into the GFX.Screen
+memory buffer, now is your chance to copy the SNES rendered screen to the
+host computer's screen memory. The problem is that you have to cope with
+different sized SNES rendered screens. Width is always 256, unless you're
+supporting SNES hi-res. screen modes (Settings.SupportHiRes is TRUE), in
+which case it can be 256 or 512. The height parameter can be either 224 or
+239 if you're only supporting SNES lo-res. screen modes, or 224, 239, 448 or
+478 if hi-res. SNES screen modes are being supported.
+
+All current ports support scaling the SNES screen to fill the host system's
+screen, the many ports even supports interpolation - blending the colours of
+adjacent pixels to help hide the fact they've been scaled - and scan-line
+simulation - slightly darkening every other horizontal line.
+
+Don't forget that if you're just placing the SNES image centerally in the
+screen then you might need to clear areas of the screen if the SNES image
+changes size between calls to S9xDeinitDisplay. The MS-DOS and UNIX ports
+currently don't do this which results in junk being left on the screen if
+the ROM changes SNES screen modes.
+
+The sixteen_bit is just a copy of the Settings.SixteenBit setting and if
+TRUE indicates a 16-bit SNES screen image has been rendered, 8-bit otherwise.
+
+void S9xMessage (int type, int number, const char *message)
+***********************************************************
+
+I've started work on converting all the old printfs into calls to this
+routine.  When Snes9x wants to display an error, information or warning
+message, it calls this routine. Check in messages.h for the types and
+individual message numbers that Snes9x currently passes as parameters.
+
+The idea is display the message string so the user can see it, but you
+choose not to display anything at all, or change the message based on the
+message number or message type.
+
+Eventually all debug output will also go via this function, trace information
+already does.
+
+bool8 S9xOpenSoundDevice(int mode, bool8 stereo, int buffer_size)
+*****************************************************************
+
+S9xInitSound calls this function to actually open the host operating system's
+sound device, or initialise the sound card in MS-DOS port. 
+
+The mode parameter is the value passed in on the command line with the -r
+command line flag, assuming you're using the Snes9x parser. Its meant to
+indicate what playback the sound hardware should be set to, value 1 to 7.
+I think the real SNES sound chip playback rate is 30kHz, but such high
+playback rates take a lot of native CPU power to emulate. The default
+playback rate is 22kHz for the MS-DOS and UNIX ports.
+
+The stereo flag indicates if the user wants stereo sound. Again, stereo
+sound takes more CPU to power to emulate compared to mono sound.
+
+The buffer_size value indicates what sample buffer size the user wants,
+usually zero, meaning you should pick the value best suited to the current
+playback rate. Sound data is normally passed to the sound hardware in
+blocks, the smaller the block the less latency between the SNES game playing
+a sound and it being heard by the user. But if you pick a too smaller value,
+and you're having to periodically poll the operating system to see if it can
+accept more sound data, then the sound output will break up because other
+actions such as rendering the SNES screen can prevent you from polling the
+hardware often enough and the operating system runs out of sound data to
+play.
+
+The MS-DOS port uses a buffer size of 128 samples since the sound card
+sends an interrupt when more data is required which is acted upon promptly,
+where as the Linux and Solaris ports use a buffer size of 512 samples or
+more depending on the playback rate. Stereo and 16-bit sound both double the
+actual size of the buffer in bytes.
+
+uint32 S9xReadJoypad (int which1_0_to_4)
+****************************************
+
+This function is called to return a bit-wise mask of the state of one of the
+five emulated SNES controllers. Return 0 if you're not supporting controllers
+past a certain number or return the mask representing the current state of
+the controller number passed as a parameter or'ed with 0x80000000.
+
+Symbolic constants are defined in snes9x.h indicating the bit positions of
+the various SNES buttons and direction indicators; they're all in the form
+SNES_X_MASK where X is the SNES controller button name.
+
+The MS-DOS and X Window System ports record what keys are currently pressed
+and use that to build up a mask, the Windows port polls the operating system
+when S9xReadJoypad is called to find out what keys are pressed. All ports
+also implement host joysticks and joy-pads via this interface.
+
+bool8 S9xReadMousePosition (int which1_0_to_1, int &x, int &y, uint32 &buttons)
+*******************************************************************************
+
+Used by Snes9x to get the current position of the host pointing device,
+usually a mouse, used to emulated the SNES mouse. Snes9x converts the x and
+y values to delta values required by the SNES mouse, so the actual x and y
+values are unimportant, only the change in value since the last call to
+this function is used. 
+
+Graphical windowing systems normally restrict the movement of the pointer on
+the screen, if you're porting to such an environment you might want to make
+a note of the change in position in the mouse since the last time you asked
+the operating system the mouse position, add this change in value to some
+saved x and y value, the reposition the pointer back to the centre of the
+SNES display window. The saved x and y values will be the values returned
+by this function.
+
+The buttons return value is a bit-wise mask of the two SNES mouse buttons,
+bit 0 for button 1 (left) and bit 1 for button 2 (right).
+
+bool8 S9xReadSuperScopePosition (int &x, int &y, uint32 &buttons)
+*****************************************************************
+
+void S9xSetPalette ()
+*********************
+
+void S9xSyncSpeed ()
+S9xUnixProcessSound
+void _makepath(char *, char const *, char const *, char const *, char const *)
+void _splitpath(char const *, char *, char *, char *, char *)
+
+
+Sound Generation
+----------------
+
+Settings
+--------