		Snes96: Linux 0.72 Released 12th June 1997
		------------------------------------------

Gary Henderson (gary@daniver.demon.co.uk)

This is a Super Nintendo Entertainment System (SNES) emulator for Linux i386,
MS-DOS and Sun Solaris Sparc featuring work-in-progress 16-bit, digital
stereo sound on the Linux port only (Solaris and MS-DOS coming soon).

Snes96: Linux is a port/rewrite of the SNES emulator for Windows 95 originally
written by Jerremy Koot (jkoot@euronet.nl) and with considerable amounts of
new features, speed ups and bug fixes added by myself. Snes96 is coded in C++
with an assembler CPU emulation core on the Linux and MS-DOS ports.

About 85% of the ROMs that people have tested so far seem to work OK; these
include Donkey Kong County 1, 2 and 3, Secret Of the Evermore, The Final
Fantasy series, Metroid 3, F-Zero, Puzzle Bobble, Battle Toads: Double
Dragon, NBA Live '96, etc, etc.

Key features
------------
o Work-in-progress, 16-bit, digital stereo sound on Linux X11 port only.
o The only Snes emulator to have a large part of its documentation ripped
  off as well as its code.
o Speed, with a 100% assembler CPU emulation core on Linux and MS-DOS ports -
  it was the fastest SNES emulator around until recently and might be again
  one day (wait until the "other" emulator implements H-DMA - that will slow it
  down somewhat).
o Lots of ROMs work, the numbers are increasing with each release.
o Simultaneous two SNES joy-pad emulation allowing two player games to be
  played.
o Support for one 2, 4 or 6 button joystick or two 2-button joysticks - Linux
  and MS-DOS ports only.
o Snapshot a game in progress and restore the game to that exact point at
  a later time.
o Complete, fast mode 7 emulation (screen rotation and scaling) - all except
  one rarely used feature.
o Complete H-DMA emulation for those split screen and wavy background effects.
o Background clip windows for those H-DMA zoom effects.
o Variable CPU cycles length as on the real SNES, for fast and slow ROM
  emulation.
o Mosaic effect.
o Linux S-VGA and MS-DOS ports support various screen modes.
o Compressed and/or split ROM image support.
o SNES image scaling.
o 8-bit, 16-bit and 24-bit X11 server support.
o An uncrackable binary - mainly because it has no protection to crack such as
  time limits, limited colours, etc., etc. and never will.

It terms of what SNES hardware is actually emulated, most graphics registers
are emulated. The background-layers colour addition and subtraction feature
is not yet emulated and the lack of this causes some display 'priority'
problems for some ROMS. Offset change mode is also not yet emulated. A few
other odd features that no ROMs seem to use are also missing: direct
colour output, interlaced display, pseudo horizontal 512 pixel mode.

Some ROM cartridges contained additional hardware such as the SuperFX chip (a
16Mhz RISC processor) or DSP chip, neither of these chips are emulated at the
moment so games like Mario Kart, DOOM, Yoshi's Island, etc. don't work.

What's New Since Last Full Release
----------------------------------
- Linux port has work-in-progress, 16bit, digital stereo sound. Try the
  DKC series of ROMs for games that are working almost perfectly with the
  current sound emulation. However, for the moment, most other ROMs still
  crash, remain silent or produce a horrible noise when sound emulation is
  enabled.
- Included some old cached-tile based screen code. Press '9' to enable.
  Gives a noticeable speed increase but many ROMs then exhibit slight to
  severer screen redisplay problems - use only if you have to.
- Fixed the DOS filename handling - old Unix code was screwing up with ROM
  filenames that contained backslashes (\) - the ROM would load but S-RAM
  loading and saving would fail and the default filename for snapshots
  wouldn't work.
- Worked around the Chrono Trigger multiple button press problem where
  several joy-pad buttons have to be pressed simultaneously to proceed in
  the game (use one for the alternate keyboard mappings - some keyboards have
  limits on which keys it will register being pressed when pressed in
  combination - one combination should work for your keyboard).
- Added support for multi-part ROM images in form romimage.1, romimage.2,
  or sf24555a, sf25444b, etc.
- Added code to automatically remove headers from S-RAM save files with
  512 byte headers.
- 32Mbit ROMs in interleaved format are now automatically detected and
  converted.
- Added -ss 3 sound skip method support to the asm version - now NBA Live '96
  works again.
- Made libgz.so statically linked (again) on Linux port - sorry about that.
- Made writing to $4200 also clear any pending IRQs. This finally allows
  Battle Toads: Double Dragon, Spawn and Sieken 3 all the work with the same
  IRQ logic (but Sieken 3 still gets stuck in sound download code).
- Fixed a H-DMA wobble bug - some frames could randomly miss a line of
  H-DMA causing the F-Zero screen to wobble, and slight text character
  corruption on games like DKC3.
- Interleaved format ROM images are now swapped in-place, without the need
  for a temp 4Mb buffer (saves lots of disk swapping on a 16Mb Windows 95
  machine).

What you will need
------------------

You will need a Pentium-class PC running Linux, MS-DOS or Windows 95 with at
least 8Mb of RAM. Windows 95 will probably require 16Mb. I am unable to test
the MS-DOS port under Windows 3.11 but I see no reason why it shouldn't
work. 

The Linux port requires a recent, stable kernel version; I'm using 2.0.27.
The Sun Solaris Sparc port requires a fast Sun Sparc workstation running
Solaris 5.x.  Both the UNIX ports are dynamically linked and will require
access to various shared libraries. Use ldd snes96 to make sure you have all
the required libraries on your system.
 
The Solaris port and the Linux X11 version will also need an X server running.

For sound output on the Linux port, your kernel will require the 2.0 sound
drivers configured and linked in.

Access to SNES ROM images in *.smc, *.sfc, *.fig or *.1, *.2, or sf32xxxa,
sf32xxxb, etc., format will also help otherwise you will have nothing to run!
Several public domain images are available from:
http://www.rollanet.org/~khigh/emulator.htm

Some commercial ROM images are available via the Internet, try following links
from:
http://members.aol.com/zorkwiz/snesrom.htm

Please note, it is illegal in most countries to have commercial ROM images
without also owning the actual SNES ROM cartridge.

PLEASE DO NOT ASK JERREMY OR MYSELF FOR ROM IMAGES OR FOR INFORMATION ON WHERE
TO GET MORE, WE DO NOT KNOW AND WILL IGNORE ALL SUCH E-MAILS OR, IF WE ARE
HAVING A PARTICULARLY BAD DAY, FORWARD THE E-MAIL TO THE EMULATOR ABUSE
DATABASE.

Starting the emulator
---------------------

From a shell or DOS session just type:
snes96 <ROM filename>

Some command line flags are available:

-i Inform emulator ROM image is in interleaved format.
-f <frame skip count> (2)		See "Speeding up the Emulation" below
-h <0-100> Percentage of cpu cycles to execute per scan line (100)
-m <0-4> (Linux S-VGA) or <0-8> (MS-DOS) Select screen mode (0), try -m 2
   to see if its compatible with your system, it gives an noticeable emulation
   speed increase.
-ss <0-3> SPC-700 skip wait method (0), use 1 for Metroid 3 and Animatics,
    and 3 for NBA Live 96.
-S Enable a very buggy SPC700 sound CPU emulation and actual sound output on 
   the Linux port. Might allow some more ROMs to run that would otherwise have
   got stuck in sound down-load code. DO NOT USE SNAPSHOT FEATURE WITH
   SOUND CPU ENABLED.
-l <snapshot file name> Load snapshot file and required ROM image and restart
			game from saved position.
-s Swap emulated joy-pad 1 and 2 around.
-F Force Hi-ROM memory map for ROMs where the Hi-ROM header test fails.
-FL Force Lo-ROM memory map for ROMs where the Hi-ROM header test fails.
-o Enable old-style joy-pad emulation (required by a few ROMs)
-p Fool ROM into thinking this is a PAL SNES system.  (not usually
-n Fool ROM into thinking this is a NTSC SNES system.  required)
-H Turn off the H-DMA emulation.

Linux and DOS ports only:
-4 Joystick connected to computer has 4 buttons.
-6 Joystick connected to computer has 6 buttons.

Linux port only:
-stereo Enable stereo sound output (needs high-end Pentium-class machine)
-r 0-7 Sound playback rate/quality:
       0 - disable sound, 1 - 8192, 2 - 11025, 3 - 16500, 4 - 22050 (default),
       5 - 29300, 6 - 36600, 7 - 44000.
-B Buffer size in bytes 128-4096 (default auto-select for playback rate)

While the emulator is running:
'Escape'                quit the emulator

Joy-pad 1:
'up' or 'u'             Up direction
'down', 'j' or 'n'      Down direction
'left' or 'h'           Left direction
'right' or 'k'          Right direction
'a', 'v' or 'q'         TL button
'z', 'b' or 'w'         TR button
's', 'm' or 'e'         X button
'x', ',' or 'r'         Y button
'd', '.' or 't'         A button
'c', '/' or 'y'         B button
'Left Control' or 'Left Meta' Start button
'Left Shift'            Select button

Joy-pad 2:
'Keypad 8'              Up direction
'Keypad 2'              Down direction
'Keypad 6'              Left direction
'Keypad 4'              Right direction
'Insert'                TL button
'Delete'                TR button
'Home'                  X button
'End'                   Y button
'Page Up'               A button
'Page Down'             B button
'Right Control' or 'Right Meta'	Start button
'Right Shift'           Select button

'0'                     Toggle H-DMA emulation on/off (and speed up redrawing).
'1'                     Toggle background 1 on/off (useful for speeding up the
'2'                     Toggle background 2 on/off  emulation and for ROMs
'3'                     Toggle background 3 on/off  that use colour addition in
'4'                     Toggle background 4 on/off  a certain way, e.g. zelda)
'5'                     Toggle sprites (OBJs) on/off
'6'                     Toggle swapping of joy-pad one and two around
'9'			Toggle old, cached-tiled based screen redrawing method
			on/off. Gives noticeable speed increase but many ROMs
			can exhibit slight to severer screen redisplay
			problems.

'-'			Decrease frame redraw skip rate
'+'			Increase frame redraw skip rate
'F2'                    Load snapshot of game in progress (DO NOT USE WITH
'F3'                    Save snapshot of game in progress  SOUND CPU ENABLED)

Linux port only:
'F4' -> 'F11'		Toggle sound channels on/off
'F12'			Turn on all sound channels.

ROM images are normally loaded from the directory ./roms. This can be
changed by specifying a pathname with the image name or setting the
environment variable SNES96_ROM_DIR to point to a different directory.

Snapshot files and S-RAM save files are normally read from and written to the
directory $HOME/.snes96_snapshots for the UNIX ports or .\SNESNAPS for the
MS-DOS port. This can be changed by setting the environment variable
SNES96_SNAPSHOT_DIR to point to a different drive/directory.

Joystick Support
----------------

The Linux and MS-DOS ports of Snes96 supports one or two 2-button joysticks,
or one 4-button or 6-button joystick - this limitation is imposed by PC
hardware. The Linux port requires the kernel to have the joystick driver
compiled in or loaded as a module to enable Snes96 to access the joystick(s).
The driver source code is available from:
http://sunsite.unc.edu/pub/Linux/kernel/patches/console/joystick-0.8.0.tar.gz
Don't forget to also make the two devices in /dev - /dev/js0 and /dev/js1 and
make them readable by everyone; documentation supplied with the driver gives
details of this.

On a 2-button joystick only the A and B SNES buttons are available, the
remaining 4 can still be accessed via the keyboard.

The following diagram showing you the button layout for 6-button PC joy-pads
that look similar to real SNES joy-pads:

     ---TL---           ---TR---

        ^                  X
        |
     <-   ->            Y     A
        |       /  /
        v                  B


Make sure the joystick is centred or no buttons pressed for joy-pads when
the emulator is first started to enable auto-calibration to work.

Linux S-VGA Full-Screen Mode
----------------------------

The Linux port of Snes96 is supplied as two binaries: snes96 for the
X Window System version and ssnes96 for the S-VGA 256x256 full-screen version.

The S-VGA version needs root permissions so it can write to the PC video
registers to change screen modes (the X server has the same problem). You can
either run as root (not recommended) or set the binary to run set-uid root as
follows:

Log on as root or su to root.
Change to the directory where the ssnes96 binary is stored.
Type:
chown root ssnes96
chmod 4555 ssnes96

Now the binary can be run by an ordinary user in much the same way the
X server can. The default VGA screen mode is 320x240x256 mode-X, which should
work on any system. However, mode-X slows down the emulator a little so you
might what to try using the -m 2 command line flag to see if the slightly
faster 256x256x256 screen mode is compatible with your system.

Problems With ROMs
------------------

If the emulator just displays a black screen for over 10 seconds then one
of the following could be true:

1) The ROM image is corrupt. More likely is the ROM image is in interleaved 
   format; use the -i command line flag to tell the emulator it is in this
   format.
2) Some ROMs have a bad ROM header, mostly home-brewed SNES games or hacked
   commercial games. Snes96 cannot then detect if it is a Lo-ROM or Hi-ROM
   game and just guesses. You might have to use the -F to force Hi-ROM or -FL
   to force Lo-ROM to help it out.
3) The ROM is in a loop waiting for the Sound CPU to respond with a particular
   value and the sound wait skip code in the emulator hasn't spotted the fact.
   Try using a different -ss command line option value in the range 0 to 3.
   You could also try the -S command line flag which enables the very buggy
   SPC700 emulation. The allows several ROMs to continue that previously were
   stuck in sound down-load code.
4) The ROMs FAST ROM protection check has failed and the ROM has deliberately
   crashed itself. The only thing you could try is one of the utilities on
   the 'net that remove such protection.
5) You have set the -h command line value too low.
6) The original SNES ROM cartridge had additional hardware inside that is not
   emulated yet - this is true for all SuperFX games (DOOM, etc.) and DSP
   games (Mario Kart, Yoshi's Island, etc.). Some of the later ROMs (1994+)
   had additional hardware as a form of protection (Williams Arcade Classics,
   Clay Fighters II, etc.). There is nothing you can do about these games
   except patching the ROM or wait until I emulate the missing hardware, but
   this must be done individually, for each game.  (Williams Arcade Classics
   is already supported).
7) The ROM image has found a CPU emulator instruction or memory map bug -
   please e-mail with name of ROM images that do this. Unfortunately, it is
   difficult to tell this problem from the protection failure problem
   described above without disassembling the ROM.

If the game starts normally but refuses to go beyond the title screen try
using the -o command line flag to enable old-style SNES joy-pad emulation or
try pressing '6' in the emulator to swap joy-pads around; Mario All Stars
swaps joy-pads around with old-style SNES joy-pad emulation enabled.

If the ROM says "This game is not for your system" or something similar,
try using the -p flag to force PAL mode or -n to force NTSC mode.

Also, some ROMs use background colour addition (which isn't emulated yet) in
such a way that is hides the character you are trying to control or important
scenery; try toggling the background layers on and off with the keys 1 to 4 to
see if you can find the background layer causing the problem and leave it
switched off.

Converting ROM Images
---------------------

If you have a ROM image in several pieces, simply rename them so their
filename extensions are numbered: e.g. game.1, game.2, etc. Then, when
loading the ROM image, just specify the name of the first part; the remaining
parts will be loaded automatically.

If they are already in the form sf32xxxa, sf32xxxb, etc., you don't even have
to rename them; just specify the name for the first part as above.

Speeding up the Emulation
-------------------------

Try the following command line flags:
-f <frame skip rate> (default 2: only every 3rd frame is rendered and
		       displayed)
	Increasing this value will speed up the emulator but make screen
	updates more jerky. During a game, the '+' and '-' keys increase or
	decrease the frame skip rate.

-h <CPU percentage of cycles per scan line to execute> (default 100)
	Lowering this value will also speed up the emulator but setting the
	value too low can cause problems from some ROMs because not
	enough CPU instructions are being executed per frame as the ROM
	expects and can actually slow down a game!

-m <screen mode> Some screen modes allow faster screen update than others,
        try -m 2 to see if the faster, non-mode X VGA mode is compatible with
        your system. MS-DOS users could try -m 3 or higher to try one of the
        VESA screen modes.

Pressing '9', to enable some old, cached-tile based screen code also gives
a very noticeable speed increase but can cause severer screen redisplay problems
on some ROMs, which was why I removed the code in the first place. However, it
might make all the difference for people with slower machines.

Turning off some of the background layers by pressing '1' to '4' also speeds
up the emulator. As always, you could try running the emulator on a faster
machine!

Not enabling sound also speeds up the emulator because to get sound on an
SNES another 2.5Mhz CPU must be emulated together with the sound DSP. If you
must have sound, don't enable stereo output or lower the sample playback rate.

Credits
-------

A great big thank you to Steve Snake for his insights into SNES sound sample
decompression.

Many thanks must go to Jerremy Koot (jkoot@euronet.nl) because without all
his hard work on the original Snes96 and Snes97 Windows 95 versions, Snes96
would not exist in its current form.

Thanks also to Lord ESNES for his many discoveries and for a person who
shall remain nameless, for his continuing quest for SNES information on my
behalf.

I would also like to thank Shawn Hargreaves (shawn@talula.demon.co.uk) for
the Allegro library which made porting Snes96 relatively easy and my two
beta testers, Dave Baugh and Zorkwiz@aol.com.

SNES is a trademark of Nintendo. 
Sun, Solaris and Sparc are trademarks of Sun Microsystems, Inc.  
MS-DOS and Windows 95 are trademarks of the Microsoft Corporation.

------------------------------------------------------------------------------
Gary Henderson (gary@daniver.demon.co.uk)
