Documentation for GBSIM 0.99
============================

GBSIM is a GameBoy emulation for the PC.

-- PLEASE NOTE: ---------------------------------------------------------------
 This program is just an experiment and only interesting for freaks with
 hardware knowledge.

 I decided to stop the development of it, because there is another (better)
 emulation of the GB available (VGB by Marat Fayzullin). 

 I'm going to port the debugger of GBSIM to C and add it to VGB, but until
 this is done, GBSIM is the easiest way to debug GameBoy-programs.

 I'm going to release the code (TP6.0 + ASM) if enough people are interested.
 Please write to: 
  Jens Ch. Restemeier <jchrr@hrz.uni-bielefeld.de>
 If you want to send comments or suggestions for the GB-debugger, or you are
 completely bored, you may write, too.

 A added a music-record function, and changed the extension from ".GBS" to 
".GB".
-------------------------------------------------------------------------------

GBSIM doesn't expect a "specially optimized" configuration, as long as EMM386
is installed with EMS. I think 1 MB EMS is enough.

You need a binary game-image to see GBSIM work, but don't ask me about how to
get one ...

Copy everything into a directory and start it. GBSIM will load the file
given as parameter. Without a parameter, it will look for TETRIS.GBS.
You'll see the debugger (See below for commands). Press L and look.
(See below for keyboard controls).
If present, it loads a label file (<parameter>+'.L'). Look into GAMEBOY.L
for syntax (GAMEBOY.L is always loaded !).

Amazing, isn't it ?

Don't be surprized, if your PC locks up, while or after GBSIM runs. I do really
try to clean up, when GBSIM exits. 

This version isn't optimized for speed, it's just a quick & dirty
"It's-possible-!"-beta-version. Don't expect, that it runs with MS-Windows [95].
It works on a 386/486/Pentium, maybe you have to switch off the cache, remove
any TSRs, turn off your coffee-machine, darken the room, cast a magic spell,
light a black candle, burn incense or just wait for the next release...
It DOES NOT work on a 286, because I'm using 32-bit registers.

==============================================================================

Why did I waste my time developing a GB-emulator ? Well, first of all, it
wasn't _that_ work. The main coding was done at just one weekend.
I met people, who developed devices to read GB-cartridges (to C64 and Amiga)
and I built this for PC from the "c't Printer-Server" with two 8255 PIOs. (Then
a friend built this for the PC-printer Port. Needs 9 74xx logic chips.)
I heard that a Z80 is working in the GB, I tried to decode it with an
Z80-Disassembler on CP/M and the code seemed to be "runable".
So I wrote a simple Z80 disassembler with label support and tried to decode
Tetris. That did not work, so I modified the disassembler, until the code
seemed to be good. After discovering some internals (new opcodes, IO, Video), I
closed the project. Then, month later, after closing my first 100% assembler
project, I had a great idea how to write the CPU emulator, and a day later
I had the title of Tetris working.
The final improvements where month ago, I've got no new information, so
I think: Show it to everybody, maybe somebody gives me THE information
to finish it. 

I got a "GB-FAQ" recently, giving me all the info I need ! Shit, this Guy
developed a GB-Emulator, too. While I was first, there is no way to proove
it :-(
But now I have completed the CPU, and a documentation of the missing
registers...

I'm interested in internal information of other hardware, too, like SNES, 
PC-Engine, Mega Drive (Genesis), NES, Atari VCS, Vectrex, PSX, 32x, Saturn, 
Jaguar, Nintendo 64, Master System, FM-Towns, Super TwinCom...

==============================================================================

Commands:
=========

Debug-Mode:
===========
All numbers must be entered in HEX.

T       => Trace
S       => Step
H       => Here         Run, until here
G       => Goto         Set Cursor to
W       => Write        Set the value for the joypad:
			  0 => nothing
			  1 => A
			  2 => B
			  4 => Select
			  8 => Start
			  16 => right
			  32 => left
			  64 => Up
			  128 => Down
N       => Reset
M       => Memory  Set the position of the memory-window
R       => Run     The code is emulated, until an illegal opcode or the
		   HALT - opcode appears
I       => Look, whats on the screen (the GameBoy's of course...)
L       => Look-Mode    Show the screen while emulation.
O       => Output       Write a value to an adress.
Delete  => Set the actual opcode to NOP.

+       => Log $FF00-$FF4F (IO-Area) to \GBSIM.LOG (Hex)

B       => Set/Clear breakpoint ( max. 9)
C       => Clear all breakpoints
F       => Find next breakpoint from cursor

F1      => Save memory+registers (Snapshot)
F2      => Load memory+registers

F3      => Save Screen (IFF-Format, extension will be added)
	   Deluxe-Paint 2 PC does not like those Files, but 
	   Graphics Workshop (V7.0f DOS) can show/convert them !
	   This function will be good for making solutions or magazines.

F5      => ROM information, shows the Logo

ESC     => Exit the emulation

Down    => Move the cursor down
(Left/Right => Inc/Dec cursor-adress)

Look-mode:
==========
Use a 4-button joystick

Breakpoints don't work here.

Breaks on errors, ESC or HALT-instructions

==============================================================================

Technical info:
===============

CPU:
====
The Gameboy is based on a Z80-like CPU. Some opcodes are left out,
replaced or relocated. There is no second register-set and IX and IY are
missing. The $ED-Opcodes are killed.
The "Halt" instruction seems to be changed. If the emulation breaks there,
kill it. I could fix this, but my breakpoint-stuff works with "Halt", and
I'm too lazy to rewrite it. "Halt" is normaly coded as "ld (HL),(HL)", other
instructions of this kind seem to be changed, too: Tetris uses "ld b,b".
Any ideas ?

MEMORY:
=======
The first 32K of Memory are on the Cartridge, then there are 8K video-RAM.
From $C000 are 8K RAM. There is a "special" RAM-area from $FE00-$FFFE, while
the area from $FF00-$FF4f holds I/O registers.
The GB uses an MMU for Cartridges with more than 32KB on it. It switches the
memory configuration on a memory write to $2xxx. This adress is not full
decoded: If /WE and ((address AND $3000)=$2000) the MMU selects a new page.
Extension-memory banking is not done, yet.

I/O:
====
The IO-chips are spread from $FF00-$FF4F. I found the joypad-port at $FF00 and
the display-options from $FF40 to $FF4B.

VIDEO:
======
The font and the screen are stored in video-RAM. The font can have 3*128 chars
and there are two 32*32 screens (20*18 visible). The GB has 40 Sprites, 8x8 or
8x16 great. They are normal chars from the font. 

For more details read the GB-FAQ !

==============================================================================

The emulator is a Turbo Pascal (6.0, I don't like 7.0) program with a
Turbo Assembler kernal for CPU-emulation.

==============================================================================

Plans for the final Version (which will never get done...):
- 100% Assembler, P-Mode
- Cool GUI
- Better name than GBSIM: something like Super-Boy or Mega-Gameboy or
  Masterboy or Home-Boy or PC-Boy or Brain-Boy ...
- Trainer (Lifes, Energy, Level), like Action Replay
- Sound (SB, GUS)
- support for the Super-GB games (showing the Frame, Colors)
- IPS-Support, integrated cheats/games database
- PC-Joypad/SNES-Joypad (sure)/Genesis-Joypad (maybe) support
- PC<->Gameboy link option
- Double GB-emulation (for two player action on REAL fast machines) 

------ Cut here --------
Plans for the VGB-debugger:
1. everything, that GBSIM can:
    - single step execution
    - memory manipulation
    - breakpoints
    - RAM/register snapshot
    - intruction "NOP"-out
    - screen snapshot (I think about using Targa instead of IFF)
    - IO-Dump to file
    - label-support
2. what GBSIM can not:
    - source level debugging (ASM and C)
    - register manipulation
    - direct support for TASM and GBC symbols
    - disassemble into file
    - label manager (to add/modify labels)
I'm planning to write it "system independent" like VGB: all you need to port
it, is to write a "driver" for your system.

==============================================================================

History:

Beta 1:

- Quick and dirty first release (SSSSSLLLLLLOOOOOWWWWW).
- 286 Code
- internal debugger

Beta 2 (only shown/given to some friends):

- MS-Windows test: IT WILL NOT RUN WITH WINDOWS ;-)
- CPU emulation uses 386 code
- New CPU-engine.(Faster)
- Save+Loadgame
- Breakpoints
- Better keyboard-control in Look-mode
- EMM386.EXE used (VCPI:Breakpoints,Expanded Memory).

Beta 3 (only shown/given to some friends):
- Grafix-engine reworked (80% of display-options used, the rest would need a
complete rework)
- CPU-Engine reworked (faster)
- additions to the debugger

Beta 4 (only shown/given to some friends):
- Reworked IO-emulation

Beta 5 
- New GB-MMU emulation (other EMM386-Feature used, now it is impossible
to write into the ROM-area).

Beta 6
- CPU-Engine optimized (smaller, a little faster)
- Skips Smartcard-header, if present
- Auto-MMU-Patcher
- IO is done in Assembler !
- new GFX-engine !!!!!
- Screen Grabber

Beta 7
- even newer GFX-engine !
- killed keyboard driver
- added IBM-joystick driver, SF-pad driver comming soon !
- you'll see the Nintendo-Logo when getting cartridge-info !

Beta 8
- Lots of debugging and rewriting

P.S.:
- Does anybody know, how the "Super Gameboy" works ? It's a complete GB
without a display. The SNES seems to read the LCD-datastream and gives the
joypad-info back. It should be possible to build a PC-adapter for it (ignoring
the SF-ROM), and running it from DOS/OS2/Windows/Linux (OR an Amiga-adapter to
run it from the Workbench OR a [Power]Mac adapter to run it with MacOS).
You'll need to decode it's registers to host-IO and a Smartcard.
Maybe I'll try it, when I've got a Super-GB. What I know is this:
Super Donkey Kong checks it's presence by writing 030h to 0ff00h, then reading
it back: 0fxh: GB, 03xh: Super GB. It tries some serial transfer on the
joypad register: 030h Stop-Bit, 020h=Hi, 010h=low. The frame seems to be
transfered through the VRAM (Had no time to check this).
- I need a PAL/GAL-listing for a GB-MMU replacement. I don't like killing
cartridges to get a MMU.
- What do you think about an emulation of the "old" Nintendo ? Need Info !
- What do you think about an emulation of the "old" SEGA Master ? Need Info !

==============================================================================
IMPORTANT ! IMPORTANT ! IMPORTANT ! IMPORTANT ! IMPORTANT ! IMPORTANT ! IMPORT
==============================================================================
Use GBSIM at your own risk.  There is no warranty for the program of any kind.
I don't  take  responsibility  for  any  damage  caused by the program, either
direct or indirect, physical or psychical, to your hardware, software or soul.
==============================================================================

Hey, if you didn't notice it:
  GB is short for Nintendo GAMEBOY
  SF/SNES is short for Super Family Computer/Super Nintendo Entertainment Systen
  TP is short for Turbo-Pascal 6.0
  Genesis = "Mega Drive"

Nintendo, FamiCom and Gameboy are registered to Nintendo corp. 
Please excuse my wired ideas about english grammar and oatogrfi.

Fuck for Windows [NT/95].

You may give this stuff to anybody you like. (If anybody likes to get it.)
-------------------------------------------------------------------------------
