

               ##### ####### ##   ## #### ######   ###   ####
              ##   #  ##   # ###  ##  ##  # ## #  ## ##   ##
             ##       ##     #### ##  ##    ##   ##   ##  ##
             ##       ####   #######  ##    ##   ##   ##  ##
             ##  ###  ##     ## ####  ##    ##   #######  ##
              ##  ##  ##   # ##  ###  ##    ##   ##   ##  ##  ##
               ##### ####### ##   ## ####  ####  ##   ## #######

                             [ Genital Readme ]
                  Copyright 2000, 2001 Bart Trzynadlowski


This is the documentation for Genital Version 1.2, please read it before going
off and asking questions that are most likely answered here. Make sure to read
and understand the terms of use.


----------------
  Terms Of Use
----------------

Genital is Copyright 2000, 2001 Bart Trzynadlowski.

"Genital" refers to GENITAL.EXE and README.TXT. To use Genital, you must agree
to the following terms:

    - Genital shall be distributed freely, unmodified, and intact.
    - Charging money, goods, or services for Genital is forbidden.
    - Claiming ownership or authorship of Genital is forbidden.
    - Genital may not be distributed in any medium for which money, goods, or
      services are solicited.

The author, Bart Trzynadlowski, reserves the right to use Genital in any way
he sees fit. The author of Genital claims no ownership to third-party software
present in Genital.

If you do not agree with these terms, remove Genital from your possession!


---------------
  What Is It?
---------------

Genital is a Sega Genesis/MegaDrive emulator for Pentium DOS machines. Most of
it was written in C, but a lot of it was written in assembly language. DJGPP
and NASM were used.
    Genital68K, which I wrote, is used to handle the 68000 emulation. The Z80
emulator, RAZE, was written by Richard Mitton. The 68000 disassembler was done
by Aaron Giles for the MAME project.

Check out the following URLs for more information:

    The Site of Bart Trzynadlowski: http://trzy.overclocked.org
    The Genital Home Page:          http://trzy.overclocked.org/genital
    The Genital68K Home Page:       http://trzy.overclocked.org/gen68k
    The RAZE Home Page:             http://www.rainemu.com/raze


-----------------------
  What It Can Emulate
-----------------------

Things that Genital emulates are:

    Main:
        - Motorola 68000 CPU (fast and accurate emulation)
        - 4MB of ROM with support for "Super Street Fighter 2" bank switching
        - Backup RAM for games which implement it
        - 64KB RAM
    VDP:
        - VRAM word/long word writes and reads
        - CRAM word/long word writes and reads
        - VSRAM word/long word writes and reads
        - VRAM byte writes
        - Data port, control port, status port
        - Registers
        - DMA (mostly, somewhat buggy)
        - HV counter (inaccurate)
        - Vertical interrupts
        - Vertical blanking period
        - Horizontal interrupts
        - Horizontal blanking period
        - Horizontal scrolling (full, cell, line, and invalid mode)
        - Vertical scrolling (full, each 2 cell)
        - Scroll A and Scroll B layers
        - Window
        - Sprites
        - Sprite limiting and masking (not perfect)
        - H40 and H32 cell modes
        - Non-interlaced and "Interlace 2" graphics modes
        - Shadow/highlight mode (not perfect)
        - Collision bit faking
        - FIFO faking
    Sound:
        - RAZE Z80 core by Richard Mitton (richard.mitton@bigfoot.com)
        - Z80 RAM
        - Bank register (and banking)
        - Z80 reset, BUSREQ
    Miscellaneous:
        - Version port (American, European, and Japanese systems selectable)
        - Control pad #1
        - Partial SVP "faking" (Virtua Racing runs, but without polygons)
        
As you can see, sound is not yet emulated. It's in the works, but don't expect
it soon. There are lots of other things I want to add, too.


-----------------
  How To Use It
-----------------

A Pentium with about 8MB of RAM (just a guess) is required. You will probably
need more RAM to run "Super Street Fighter 2." On a 180MHz Pentium, Genital
runs at a very decent speed (with a small amount of frame skipping.)

Specify the path of the ROM you wish to run on the command line. The ROM must
be in BIN/GEN or SMD format. If the ROM is larger than 4 megabytes, you will
have to use the -fload option to load it by force.
    Once in the emulator, the arrow keys represent the Genesis directional pad
and A, B, C, and Start are mapped to A, S, D, and Enter. You can re-map the
key layout by using the -remapkeys option. Other keys Genital recognizes are:

    F1                  Toggle Scroll A
    F2                  Toggle Scroll B
    F3                  Toggle sprites
    F4                  Toggle window
    F5                  Save a state
    F7                  Load a state
    F8                  Save state format (Genital or Genecyst)
    F9                  VSync
    F10                 Color or grayscale
    F11                 320x200x8bpp Mode 0x13 resolution
    F12                 320x240x8bpp Mode X resolution
    `                   Debugger
    1-0                 Select save slot
    + (on numpad)       Increase frame skip (maximum = 20)
    - (on numpad)       Decrease frame skip (minimum = 0)
    ALT-H               Horizontal interrupts
    ALT-L               Sprite limiting and masking
    ALT-R               Reset 68000
    ALT-Z               Z80 emulation
    
Command line options are:

    -?              Show help
    -h              Same as -?
    -vsync          Wait until VSync before blitting a frame. Use this on fast
                    machines
    -fskip <frames> Skips # frames before rendering or blitting. This really
                    helps speed things up on lower-end systems. The value
                    range is 0-20 [Default=0]
    -mode13         Uses the 320x200x8bpp Mode 0x13 resolution. This is the
                    fastest video mode, but 24 lines of the Genesis display
                    are cut off [Default]
    -modex          Uses the 320x240x8bpp Mode X resolution. This is slower
                    than Mode 0x13 but shows the full display
    -color          Color graphics [Default]
    -gray           Grayscale graphics
    -sprlimit       Enables sprite limiting and masking. Many games rely on
                    this, such as Sonic 1 (the title screen) [Default]
    -nosprlimit     Disables sprite limiting and masking. Since Genital's
                    graphics priorities aren't completely perfect, sprite
                    limiting can cause some unwanted clipping and flickering
                    in some extremely sprite-intensive games
    -setkeyu <code> Specify the hexadecimal scan code for the "Up" key
    -setkeyd <code> Specify the hexadecimal scan code for the "Down" key
    -setkeyl <code> Specify the hexadecimal scan code for the "Left" key
    -setkeyr <code> Specify the hexadecimal scan code for the "Right" key
    -setkeya <code> Specify the hexadecimal scan code for the "A" key
    -setkeyb <code> Specify the hexadecimal scan code for the "B" key
    -setkeyc <code> Specify the hexadecimal scan code for the "C" key
    -setkeys <code> Specify the hexadecimal scan code for the "Start" key
    -remapkeys      Launches a keyboard configuration utility
    -z80            Emulate the Z80 processor
    -noz80          Do not emulate the Z80 processor [Default]
    -gym            Log a GYM file
    -auto           Auto-detects which country the ROM can operate in and sets
                    the Genesis version register appropriately. Some of the
                    more uncommon country codes will throw the auto-detection
                    system off and force it to use USA [Default]
    -usa            Forces a USA/NTSC Sega Genesis system
    -europe         Forces a Europe/PAL Sega MegaDrive system
    -japan          Forces a Japan/NTSC Sega MegaDrive system
    -hint           Enables horizontal interrupts [Default]
    -nohint         Disables horizontal interrupts
    -gns            Makes Genital use its GNS save state format [Default]
    -gst            Uses the GST save state format
    -slot <slot>    Sets the save slot to #. [Default=0]
    -fload          Forces Genital to load the ROM, even if it exceeds 4MB
    -info           Displays information from the cartridge header
    -debug          Launch the Genesis debugger at start-up
    -dump           Dumps the 68K RAM, Z80 RAM, VRAM, CRAM, and VSRAM to
                    RAM.OUT, Z80RAM.OUT, VRAM.OUT, CRAM.OUT, and VSRAM.OUT
                    respectively when Genital exits. If Virtua Racing is being
                    emulated, it will also dump the SVP RAM to SVPRAM.OUT
    -romdir <dir>   Sets ROM directory
    -savedir <dir>  Sets the save directory

If a game does not work, try playing with horizontal interrupts and the Z80.
A lot of games can't be run because of flaws in Genital's emulation. Many
games are buggy.

The Genital Save State format is recommended over the Genecyst format because
it is much more reliable. Genital save states have the .GN* extension. The
format is described in my "Sega Genesis Save State Reference." You can find it
at my site.
    Backup RAM is automatically saved to *.GSV, it is compatible with Genecyst
backup RAM files. Games like "Mega Man: The Wily Wars" and "NBA Jam" use some
sort of a serially-programmed backup RAM system, their backup RAM isn't saved.


----------------
  The Debugger
----------------

The Sega Genesis debugger is arguably Genital's coolest feature. Press the `
key or use the -debug option to launch it. Use the ? command for a list of
commands. Most of it should be self-explanatory.
    Know that none of the code execution commands (b, e, t) do anything other
than run one of the processors. The other processor is not run and the VDP
doesn't do any of the work it normally does -- vertical/horizontal interrupts,
HV counter, etc.
    The m command will modify RAM and registers on the address space. It won't
modify ROM, use the p command to do this.
    If you need access to the Z80 area (0xA00000-0xA0FFFF) on the 68000 side,
or if the Z80 refuses to run because the 68000 has taken control, use the bus
command.

Watches are only available when debugging the 68000. Watches are special
conditions which the user is notified of if they become true. Certain
execution functions (breakpoint, trace) will process watches to see if they
evaluate true as code is being executed by the 68000.
    Watches are managed with the "w" command. The syntax for the command is as
follows:

    w [+/-] [expr/num]

The "+/-" specifies wether you are adding or removing a watch. If you are
adding a watch, specify the expression as the next argument. If you are
removing a watch, specify its number (or "*" to remove all.) Without any
arguments at all, the "w" command prints a list of active watches.
    The watch expression language is a very simple one where an expression
must consist of 3 parts:

    primary:condition:secondary

No white space is allowed, the colons (":") are the separators between the
parts (thus, no colons must ever be present in any of the 3 parts.)
    The secondary is what is being compared against the primary. It may be a
register, memory location, or immediate hexadecimal number. The primary can be
any of those things as well. The condition is the condition to test for. Below
is a table of elements you can use:

    rld0-rld7   D0-D7 (long word)       =   Equal
    rla0-rla7   A0-A7 (long word)       >   Greater than
    rlpc        PC (long word)          <   Less than
    rwsr        SR (word)               >=  Greater than or equal
    rbccr       CCR (byte)              <=  Less than or equal
    rwd0-rwd7   D0-D7 (word)            !=  Not equal
    rwa0-rwa7   A0-A7 (word)            1   Always true
    rwpc        PC (word)               0   Always false
    rbsr        SR (byte)
    rbd0-rbd7   D0-D7 (byte)
    rba0-rba7   A0-A7 (byte)
    rbpc        PC (byte)
    @la0-@la7   Long word at address in A0-A7
    @lpc        Long word at address in PC
    @wa0-@wa7   Word at address in A0-A7
    @wpc        Word at address in PC
    @ba0-@ba7   Byte at address in A0-A7
    @bpc        Byte at address in PC
    @#<addr>    Byte at immediate address
    #<data>     Immediate base 16 data
        
When data of different sizes is compared, the smaller data is zero-extended to
the size of the larger data item. All data is unsigned.


------------------
  Change History
------------------

April 10, 2001: Version 1.2
    - Scroll A is no longer drawn where Window is (fixes corrupt graphics in
      King of the Monsters 2, Virtua Fighter 2, Sonic 3, Turbo Outrun, etc.)
    - More Window information shown with debugger "v" command
    - Tweaked line 224/VBlank timing; many timing-sensitive games are happy
      now (Bubble & Squeak, Desert Strike, Ranger-X, etc.)
    - Improved Window mapping code (the Strike games, Herzog Zwei, Beavis &
      Butthead, etc.)
    - Changed a couple of misleading error messages
    - Changed VDP status register F flag handling a little
    - Added partial tile drawing function to handle Window/Scroll A pixel-
      granular clipping
    - Tweaked Z80 timing
    - Word writes to 0xC00010 are now handled properly
    - Rewrote VDP register handling to be much more efficient
    - Completely changed Genital's save state format (incompatible with older
      states) and rewrote the save state management code
    - Rewrote memory locking code
    - DMA VRAM fills are now accurately emulated (gets rid of those festering
      dots in Megaman: The Wily Wars, fixes very minor glitches in Contra)
    - Fixed a bug which allowed VRAM byte writes to go out of bounds
    - DMA VRAM copies are more accurate
    - Tweaked "Y" and "X" characters in the custom font to look a bit nicer
    - Z80-68K communication is more responsive (Golden Axe 2 and Gunstar
      Heroes can now run with Z80 emulation enabled)
    - Added VRAM dumping to the debugger
    - Improved Z80-to-68K mapping, 68K can now access Z80 bank area
    - Keyboard ISR uses a valid data selector thereby preventing spontaneous
      crashes when trying to load a save state
    - DMA now wraps source addresses at 128K boundaries
    - Fixed a possible 68K bug regarding MOVEM. Genital68K has not yet been
      updated
    - Small internal changes here and there

February 10, 2001: Version 1.1
    - Debugger "l" command now prints an error if no file was specified
    - Allowed layers (Scroll A/B, sprites, window) to be toggled individually
    - Blitter is no longer responsible for centering H32 display, renderer is
    - FastMemset() and FastMemcpy() are now part of the Genital core
    - More VDP information is shown when the debugger's "v" command is used
    - Fixed a nasty bug in the VDP RAM read/write functions
    - Rewrote tile renderers to be quicker and more efficient
    - Fixed vertical scrolling in interlace 2 (corrects Sonic 2 split screen)
    - Changed GetWord() and PutWord() into macros, huge speed increase
    - Fixed up keyboard configuration code
    - MMX is now used for fast 64-bit memory transfers (if detected)
    - Backup RAM files now use the .GSV extension
    - Fixed a watch processing bug
    - Added GYM logging
    - Assembly procedures are now much safer
    - Modified Genecyst save state management, added dedicated SSP and USP
      fields (thanks to Charles MacDonald and Quintesson for the info)
    - SIGSEGV and SIGILL are intercepted
    - Different directories for ROMs and save files can be specified
    - Debugger's 68K register display now shows which SP is A7
    - Added support for ALT-<key> combinations to the input system. Many keys
      have been re-mapped to use this, please check README.TXT!
    - Removed key for "Z80 reset", use the debugger to do it
    - Added a Z80 disassembler to the debugger
    - Added a lot of new features to the Z80 debugger making it quite usable
    - Minor changes to the 68000 emulator
    - Changed Z80 IRQ handling a bit
    - Added a "bus" command to both the 68000 and Z80 debuggers
    - Minor changes here and there

December 14, 2000: Version 1.0
    ** Features that made it: **
    - Improved VSync polling
    - Added a custom save state format, GNS: Genital Save State, user can
      toggle between GST and GNS formats for up to 20 save states
    - Completely restarted and finished Genital68K; removed Starscream
    - Wrote a very good, custom debugger
    - Messages now display in the correct position if a resolution other than
      320x200 is chosen at start up
    - Rewrote Mode X code. It's now much, much faster. Big thanks to Kuwanger
      for his input
    - Rewrote command line system and added config file support
    - Added shadow/highlight mode support
    - Rewrote and fixed control port decoding (Fixes EA logo, Desert Strike,
      etc.)
    - Emulated the invalid horizontal scroll setting (untested)
    - Added support for .GEN ROM files
    - Added support for Super Street Fighter II
    - Major source tree restructure and rewrite (based on the now defunct
      "Disco" Sega CD emulator source tree which was inspired by c2emu)
    - Now correctly handles lines with display turned off (also fixes "sticky
      messages")
    - Internal access mode data cleared when VDP registers are written (fixes
      Sonic 3D intro color bug and Golden Axe II Sega logo)
    - Added a grayscale effect
    - Minor tile rendering optimizations
    - Fixed up country detection and setting code
    - Added VDP register #1 M1 bit support -- DMA no longer works until M1=1
    - Removed Menacer support since it didn't work w/ commercial games (try
      Genital v0.3 to use it with the Menacer 6-in-1 Gamepak)
    - Slightly optimized VDP port access
    - Wrote a much faster Mode 0x13 blitter in assembly language
    - Added backup RAM support through Genital Backup RAM (GNR) files
    - VBlank now occurs at the end of line 224 (fixes Bubble and Squeak, but
      breaks Desert Strike)
    - Added H counter emulation (Road Rash 3 works fine)
    - Made a smaller and slicker font
    - Fixed "Memo" field in ROM information display
    - Hacked together some SVP groundwork to make Virtua Racing run (without
      polygons -- the actual SVP chip is not yet emulated)
    - Rewrote address space access handlers in assembly to take advantage of
      Genital68K resulting in a major speed boost
    - Major VDP status register fix regarding VB, HB, and DMA bits (fixes
      speed problems in Granada, Altered Beast, After Burner 2, Turbo Outrun,
      Ranger-X, Arcus Odyssey, etc.)
    - DMA flag now always indicates ready
    - Fixed up interlace 2 odd/even flag kludge
    - Added VDP PAL flag emulation
    - FIFO flags now always indicate empty
    - DMA registers are now updated after transfer (fixes Batman & Robin color
      bug in first level)
    - Added support for re-definable keys
    - Lots of little tweaks and changes here and there
    - Massive overall compatibility and speed boost
    - Changed terms of use (no longer public domain)
    ** Features that were removed before the release: **
    - Preliminary Sega CD driver (the much-rumored "Mystery Sega CD Emulator")
    - SH-2 emulator
    - Preliminary Sega 32X driver
    - Support for .32X ROMs

May 27, 2000: Version 0.3
    - Z80 RAM can now be dumped 
    - Started working on a custom 68K core (nothing yet)
    - Improved sprite limiting and turned it on by default
    - Improved CPU timing
    - Added country auto-detection
    - Added Window priority
    - Fixed the Window code (Raiden Trad, Phelios, etc.)
    - Added collision bit faking (Strider 2)
    - Added VDP RAM word reads
    - Fixed VRAM byte writes (Contra, Eternal Champions, many others)
    - Fixed a possible VGA bug (thanks to Charles MacDonald)
    - Added file size checking to SMD loader
    - Menacer support added (preliminary, thanks again to Charles MacDonald)
      via mouse
    - Revamped command line parsing
    - Added VRAM copy to DMA (untested)
    - Added Interlace 2-mode support
    - Added message printing w/ custom font
    - Revamped keyboard input system
    - Added sprite masking (thanks to Charles MacDonald)
    - Added Z80 toggle and Z80 reset to keyboard keys
    - Added resolution switching to keyboard keys, changed debugger key to: `
    - Minor tweaks here and there
                
April 24, 2000: Version 0.2
    - 320x240 Mode X resolution added 
    - Genecyst save state support added (10 save slots)
    - Memory dumps now occur only if requested
    - Added Starscream interactive debugger 
    - Added a DMA status register bit kludge
    - Implemented Z80 faking   
    - Added Z80 emulation w/ RAZE, Z80 RAM, bank register
    - Background color implemented
    - Added "each 2 cell" vertical scroll mode
    - Added correct VDP status register byte reads 
    - Modified HV counter 
    - Added horizontal interrupts
    - Added Window layer 
    - Added sprite limiting 
    - Major compatibility increase

April 9, 2000: Version 0.1
    - Completely rewritten
    - Initial release

January, 2000 - February 9, 2000: Version 0.0
    - Initial private version


------------------
  Special Thanks
------------------

Many thanks go out to all those people who made this long and exciting journey
possible. Without their help, direct and indirect, Genital would never be here
today. In no particular order, here they are:

    - Charles MacDonald
    - Joe Groff
    - Dave
    - Flavio
    - Christian Schiller
    - Stephane Dallongeville
    - Steve Snake
    - Quintesson
    - Tim Meekins
    - ATani
    - Charles Doty (and the contributors to the Sega Programming FAQ)
    - Kuwanger, Nurbs, and the rest of the DALnet #Programmers gang
    - Eli Dayan
    - Neil Bradley
    - Victor Moya
    - Dynarec Mailing List: M.I.K.e, Neil Griffiths, Gwenole, etc.
    - Neill Corlett
    - Joe Fenton
    - Sean Young
    - Sega ;)

And last, but not least, YOU and anyone else I might have forgotten: Thanks a
lot =)


-----------------------
  Contact Information
-----------------------

Bart Trzynadlowski
Email:  trzy@mailandnews.com
WWW:    http://trzy.overclocked.org

Information on the Sega Virtual Processor (SVP) would be appreciated. I'd like
to know exactly what kind of a DSP the SVP is, and if its internal ROM can be
dumped.

See you next time!
