From 2a9bd8781c99ee01ae185a892f480b9d7867b042 Mon Sep 17 00:00:00 2001 From: slack Date: Tue, 9 Jan 2007 11:05:47 +0000 Subject: [PATCH 1/1] Import inicial. git-svn-id: http://slack.codemaniacs.com/wenboi@1 0666ae3d-8926-0410-aeff-ae84559ff337 --- Makefile | 17 + docs/GBCPUman.pdf | Bin 0 -> 298668 bytes docs/pandocs.htm | 2899 +++++++++++++++++++++++++++++++++++++++++++++ docs/pandocs.txt | 2885 ++++++++++++++++++++++++++++++++++++++++++++ gbcore.cc | 618 ++++++++++ gbcore.h | 0 gbrom.cc | 36 + gbrom.h | 77 ++ sized_types.h | 155 +++ 9 files changed, 6687 insertions(+) create mode 100644 Makefile create mode 100644 docs/GBCPUman.pdf create mode 100644 docs/pandocs.htm create mode 100644 docs/pandocs.txt create mode 100644 gbcore.cc create mode 100644 gbcore.h create mode 100644 gbrom.cc create mode 100644 gbrom.h create mode 100644 sized_types.h diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..274c684 --- /dev/null +++ b/Makefile @@ -0,0 +1,17 @@ +CXXFLAGS=-g -Wall -Weffc++ -Wstrict-null-sentinel -Wold-style-cast \ + -Woverloaded-virtual + +all: gbcore.o + +tests: tests/test_gbrom + +gbcore.o: gbcore.cc gbcore.h gbrom.h + g++ $(CXXFLAGS) -c -o $@ $< + +tests/test_gbrom: gbrom.cc gbrom.h + g++ -DTEST_GBROM -o $@ $< + +clean: + rm -f *.o tests/* + +.PHONY: clean tests all diff --git a/docs/GBCPUman.pdf b/docs/GBCPUman.pdf new file mode 100644 index 0000000000000000000000000000000000000000..7cf38e1b25a03f5c7067d149ba91b04b560b2157 GIT binary patch literal 298668 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⁢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 BoqzxU literal 0 HcmV?d00001 diff --git a/docs/pandocs.htm b/docs/pandocs.htm new file mode 100644 index 0000000..a5308a3 --- /dev/null +++ b/docs/pandocs.htm @@ -0,0 +1,2899 @@ + + Specifications + + +
 Pan Docs

+Overview
+About the Pan Docs
+Game Boy Technical Data
+Memory Map
+
+I/O Ports
+Video Display
+Sound Controller
+Joypad Input
+Serial Data Transfer (Link Cable)
+Timer and Divider Registers
+Interrupts
+CGB Registers
+SGB Functions
+
+CPU Specifications
+CPU Registers and Flags
+CPU Instruction Set
+CPU Comparision with Z80
+
+Cartridges
+The Cartridge Header
+Memory Bank Controllers
+Gamegenie/Shark Cheats
+
+Other
+Power Up Sequence
+Reducing Power Consumption
+Sprite RAM Bug
+External Connectors
+
+
+
 About the Pan Docs

+
 =================================================================
+       Everything You Always Wanted To Know About GAMEBOY *
+ =================================================================
+

+
                     * but were afraid to ask
+

+
        Pan of -ATX- Document Updated by contributions from:
+     Marat Fayzullin, Pascal Felber, Paul Robson, Martin Korth
+             CPU, SGB, CGB, AUX specs by Martin Korth
+

+
                  Last updated 10/2001 by nocash
+               Previously updated 4-Mar-98 by kOOPa
+

+Forward
+The following was typed up for informational purposes regarding the +inner workings on the hand-held game machine known as GameBoy, +manufactured and designed by Nintendo Co., LTD. This info is presented +to inform a user on how their Game Boy works and what makes it "tick". +GameBoy is copyrighted by Nintendo Co., LTD. Any reference to +copyrighted material is not presented for monetary gain, but for +educational purposes and higher learning.
+
+Available Document Formats
+The present version of this document is available in Text and Html format:
+
  http://www.work.de/nocash/pandocs.txt
+  http://www.work.de/nocash/pandocs.htm
+
Also, a copy of this document is included in the manual of newer +versions of the no$gmb debugger, because of recent piracy attacks (many +thanks and best wishes go to hell) I have currently no intention to +publish any such or further no$gmb updates though.
+
+
+
 Game Boy Technical Data

+
  CPU          - 8-bit (Similar to the Z80 processor)
+  Clock Speed  - 4.194304MHz (4.295454MHz for SGB, max. 8.4MHz for CGB)
+  Work RAM     - 8K Byte (32K Byte for CGB)
+  Video RAM    - 8K Byte (16K Byte for CGB)
+  Screen Size  - 2.6"
+  Resolution   - 160x144 (20x18 tiles)
+  Max sprites  - Max 40 per screen, 10 per line
+  Sprite sizes - 8x8 or 8x16
+  Palettes     - 1x4 BG, 2x3 OBJ (for CGB: 8x4 BG, 8x3 OBJ)
+  Colors       - 4 grayshades (32768 colors for CGB)
+  Horiz Sync   - 9198 KHz (9420 KHz for SGB)
+  Vert Sync    - 59.73 Hz (61.17 Hz for SGB)
+  Sound        - 4 channels with stereo sound
+  Power        - DC6V 0.7W (DC3V 0.7W for GB Pocket, DC3V 0.6W for CGB)
+

+
+
 Memory Map

+The gameboy is having a 16bit address bus, that is used to address ROM, +RAM, and I/O registers.
+
+General Memory Map
+
  0000-3FFF   16KB ROM Bank 00     (in cartridge, fixed at bank 00)
+  4000-7FFF   16KB ROM Bank 01..NN (in cartridge, switchable bank number)
+  8000-9FFF   8KB Video RAM (VRAM) (switchable bank 0-1 in CGB Mode)
+  A000-BFFF   8KB External RAM     (in cartridge, switchable bank, if any)
+  C000-CFFF   4KB Work RAM Bank 0 (WRAM)
+  D000-DFFF   4KB Work RAM Bank 1 (WRAM)  (switchable bank 1-7 in CGB Mode)
+  E000-FDFF   Same as C000-DDFF (ECHO)    (typically not used)
+  FE00-FE9F   Sprite Attribute Table (OAM)
+  FEA0-FEFF   Not Usable
+  FF00-FF7F   I/O Ports
+  FF80-FFFE   High RAM (HRAM)
+  FFFF        Interrupt Enable Register
+

+Jump Vectors in First ROM Bank
+The following addresses are supposed to be used as jump vectors:
+
  0000,0008,0010,0018,0020,0028,0030,0038   for RST commands
+  0040,0048,0050,0058,0060                  for Interrupts
+
However, the memory may be used for any other purpose in case that your +program doesn't use any (or only some) RST commands or Interrupts. RST +commands are 1-byte opcodes that work similiar to CALL opcodes, except +that the destination address is fixed.
+
+Cartridge Header in First ROM Bank
+The memory at 0100-014F contains the cartridge header. This area +contains information about the program, its entry point, checksums, +information about the used MBC chip, the ROM and RAM sizes, etc. Most of +the bytes in this area are required to be specified correctly. For more +information read the chapter about The Cartridge Header.
+
+External Memory and Hardware
+The areas from 0000-7FFF and A000-BFFF may be used to connect external +hardware. The first area is typically used to address ROM (read only, of +course), cartridges with Memory Bank Controllers (MBCs) are additionally +using this area to output data (write only) to the MBC chip. The second +area is often used to address external RAM, or to address other external +hardware (Real Time Clock, etc). External memory is often battery +buffered, and may hold saved game positions and high scrore tables +(etc.) even when the gameboy is turned of, or when the cartridge is +removed. For specific information read the chapter about Memory Bank +Controllers.
+
+
+
 Video Display

+Video I/O Registers
+LCD Control Register
+LCD Status Register
+LCD Interrupts
+LCD Position and Scrolling
+LCD Monochrome Palettes
+LCD Color Palettes (CGB only)
+LCD VRAM Bank (CGB only)
+LCD OAM DMA Transfers
+LCD VRAM DMA Transfers (CGB only)
+
+Video Memory
+VRAM Tile Data
+VRAM Background Maps
+VRAM Sprite Attribute Table (OAM)
+Accessing VRAM and OAM
+
+
+
 LCD Control Register

+FF40 - LCDC - LCD Control (R/W)
+
  Bit 7 - LCD Display Enable             (0=Off, 1=On)
+  Bit 6 - Window Tile Map Display Select (0=9800-9BFF, 1=9C00-9FFF)
+  Bit 5 - Window Display Enable          (0=Off, 1=On)
+  Bit 4 - BG & Window Tile Data Select   (0=8800-97FF, 1=8000-8FFF)
+  Bit 3 - BG Tile Map Display Select     (0=9800-9BFF, 1=9C00-9FFF)
+  Bit 2 - OBJ (Sprite) Size              (0=8x8, 1=8x16)
+  Bit 1 - OBJ (Sprite) Display Enable    (0=Off, 1=On)
+  Bit 0 - BG Display (for CGB see below) (0=Off, 1=On)
+

+LCDC.7 - LCD Display Enable
+CAUTION: Stopping LCD operation (Bit 7 from 1 to 0) may be performed +during V-Blank ONLY, disabeling the display outside of the V-Blank +period may damage the hardware. This appears to be a serious issue, +Nintendo is reported to reject any games that do not follow this rule.
+V-blank can be confirmed when the value of LY is greater than or equal +to 144. When the display is disabled the screen is blank (white), and +VRAM and OAM can be accessed freely.
+
+--- LCDC.0 has different Meanings depending on Gameboy Type ---
+
+LCDC.0 - 1) Monochrome Gameboy and SGB: BG Display
+When Bit 0 is cleared, the background becomes blank (white). Window and +Sprites may still be displayed (if enabled in Bit 1 and/or Bit 5).
+
+LCDC.0 - 2) CGB in CGB Mode: BG and Window Master Priority
+When Bit 0 is cleared, the background and window lose their priority - +the sprites will be always displayed on top of background and window, +independently of the priority flags in OAM and BG Map attributes.
+
+LCDC.0 - 3) CGB in Non CGB Mode: BG and Window Display
+When Bit 0 is cleared, both background and window become blank (white), +ie. the Window Display Bit (Bit 5) is ignored in that case. Only Sprites +may still be displayed (if enabled in Bit 1).
+This is a possible compatibility problem - any monochrome games (if any) +that disable the background, but still want to display the window +wouldn't work properly on CGBs.
+
+
+
 LCD Status Register

+FF41 - STAT - LCDC Status (R/W)
+
  Bit 6 - LYC=LY Coincidence Interrupt (1=Enable) (Read/Write)
+  Bit 5 - Mode 2 OAM Interrupt         (1=Enable) (Read/Write)
+  Bit 4 - Mode 1 V-Blank Interrupt     (1=Enable) (Read/Write)
+  Bit 3 - Mode 0 H-Blank Interrupt     (1=Enable) (Read/Write)
+  Bit 2 - Coincidence Flag  (0:LYC<>LY, 1:LYC=LY) (Read Only)
+  Bit 1-0 - Mode Flag       (Mode 0-3, see below) (Read Only)
+            0: During H-Blank
+            1: During V-Blank
+            2: During Searching OAM-RAM
+            3: During Transfering Data to LCD Driver
+

+The two lower STAT bits show the current status of the LCD controller.
+
  Mode 0: The LCD controller is in the H-Blank period and
+          the CPU can access both the display RAM (8000h-9FFFh)
+          and OAM (FE00h-FE9Fh)
+

+
  Mode 1: The LCD contoller is in the V-Blank period (or the
+          display is disabled) and the CPU can access both the
+          display RAM (8000h-9FFFh) and OAM (FE00h-FE9Fh)
+

+
  Mode 2: The LCD controller is reading from OAM memory.
+          The CPU <cannot> access OAM memory (FE00h-FE9Fh)
+          during this period.
+

+
  Mode 3: The LCD controller is reading from both OAM and VRAM,
+          The CPU <cannot> access OAM and VRAM during this period.
+          CGB Mode: Cannot access Palette Data (FF69,FF6B) either.
+

+The following are typical when the display is enabled:
+
  Mode 2  2_____2_____2_____2_____2_____2___________________2____
+  Mode 3  _33____33____33____33____33____33__________________3___
+  Mode 0  ___000___000___000___000___000___000________________000
+  Mode 1  ____________________________________11111111111111_____
+

+The Mode Flag goes through the values 0, 2, and 3 at a cycle of about +109uS. 0 is present about 48.6uS, 2 about 19uS, and 3 about 41uS. This +is interrupted every 16.6ms by the VBlank (1). The mode flag stays set +at 1 for about 1.08 ms.
+
+Mode 0 is present between 201-207 clks, 2 about 77-83 clks, and 3 about +169-175 clks. A complete cycle through these states takes 456 clks. +VBlank lasts 4560 clks. A complete screen refresh occurs every 70224 +clks.)
+
+
+
 LCD Interrupts

+INT 40 - V-Blank Interrupt
+The V-Blank interrupt occurs ca. 59.7 times a second on a regular GB and +ca. 61.1 times a second on a Super GB (SGB). This interrupt occurs at +the beginning of the V-Blank period (LY=144).
+During this period video hardware is not using video ram so it may be +freely accessed. This period lasts approximately 1.1 milliseconds.
+
+INT 48 - LCDC Status Interrupt
+There are various reasons for this interrupt to occur as described by +the STAT register ($FF40). One very popular reason is to indicate to the +user when the video hardware is about to redraw a given LCD line. This +can be useful for dynamically controlling the SCX/SCY registers +($FF43/$FF42) to perform special video effects.
+
+
+
 LCD Position and Scrolling

+FF42 - SCY - Scroll Y (R/W)
+FF43 - SCX - Scroll X (R/W)
+Specifies the position in the 256x256 pixels BG map (32x32 tiles) which +is to be displayed at the upper/left LCD display position.
+Values in range from 0-255 may be used for X/Y each, the video +controller automatically wraps back to the upper (left) position in BG +map when drawing exceeds the lower (right) border of the BG map area.
+
+FF44 - LY - LCDC Y-Coordinate (R)
+The LY indicates the vertical line to which the present data is +transferred to the LCD Driver. The LY can take on any value between 0 +through 153. The values between 144 and 153 indicate the V-Blank period. +Writing will reset the counter.
+
+FF45 - LYC - LY Compare (R/W)
+The gameboy permanently compares the value of the LYC and LY registers. +When both values are identical, the coincident bit in the STAT register +becomes set, and (if enabled) a STAT interrupt is requested.
+
+FF4A - WY - Window Y Position (R/W)
+FF4B - WX - Window X Position minus 7 (R/W)
+Specifies the upper/left positions of the Window area. (The window is an +alternate background area which can be displayed above of the normal +background. OBJs (sprites) may be still displayed above or behinf the +window, just as for normal BG.)
+The window becomes visible (if enabled) when positions are set in range +WX=0..166, WY=0..143. A postion of WX=7, WY=0 locates the window at +upper left, it is then completly covering normal background.
+
+
+
 LCD Monochrome Palettes

+FF47 - BGP - BG Palette Data (R/W) - Non CGB Mode Only
+This register assigns gray shades to the color numbers of the BG and +Window tiles.
+
  Bit 7-6 - Shade for Color Number 3
+  Bit 5-4 - Shade for Color Number 2
+  Bit 3-2 - Shade for Color Number 1
+  Bit 1-0 - Shade for Color Number 0
+
The four possible gray shades are:
+
  0  White
+  1  Light gray
+  2  Dark gray
+  3  Black
+
In CGB Mode the Color Palettes are taken from CGB Palette Memory +instead.
+
+FF48 - OBP0 - Object Palette 0 Data (R/W) - Non CGB Mode Only
+This register assigns gray shades for sprite palette 0. It works exactly +as BGP (FF47), except that the lower two bits aren't used because sprite +data 00 is transparent.
+
+FF49 - OBP1 - Object Palette 1 Data (R/W) - Non CGB Mode Only
+This register assigns gray shades for sprite palette 1. It works exactly +as BGP (FF47), except that the lower two bits aren't used because sprite +data 00 is transparent.
+
+
+
 LCD Color Palettes (CGB only)

+FF68 - BCPS/BGPI - CGB Mode Only - Background Palette Index
+This register is used to address a byte in the CGBs Background Palette +Memory. Each two byte in that memory define a color value. The first 8 +bytes define Color 0-3 of Palette 0 (BGP0), and so on for BGP1-7.
+
  Bit 0-5   Index (00-3F)
+  Bit 7     Auto Increment  (0=Disabled, 1=Increment after Writing)
+
Data can be read/written to/from the specified index address through +Register FF69. When the Auto Increment Bit is set then the index is +automatically incremented after each <write> to FF69. Auto Increment has +no effect when <reading> from FF69, so the index must be manually +incremented in that case.
+
+FF69 - BCPD/BGPD - CGB Mode Only - Background Palette Data
+This register allows to read/write data to the CGBs Background Palette +Memory, addressed through Register FF68.
+Each color is defined by two bytes (Bit 0-7 in first byte).
+
  Bit 0-4   Red Intensity   (00-1F)
+  Bit 5-9   Green Intensity (00-1F)
+  Bit 10-14 Blue Intensity  (00-1F)
+
Much like VRAM, Data in Palette Memory cannot be read/written during the +time when the LCD Controller is reading from it. (That is when the STAT +register indicates Mode 3).
+Note: Initially all background colors are initialized as white.
+
+FF6A - OCPS/OBPI - CGB Mode Only - Sprite Palette Index
+FF6B - OCPD/OBPD - CGB Mode Only - Sprite Palette Data
+These registers are used to initialize the Sprite Palettes OBP0-7, +identically as described above for Background Palettes. Note that four +colors may be defined for each OBP Palettes - but only Color 1-3 of each +Sprite Palette can be displayed, Color 0 is always transparent, and can +be initialized to a don't care value.
+Note: Initially all sprite colors are uninitialized.
+
+RGB Translation by CGBs
+When developing graphics on PCs, note that the RGB values will have +different appearance on CGB displays as on VGA monitors:
+The highest intensity will produce Light Gray color rather than White. +The intensities are not linear; the values 10h-1Fh will all appear very +bright, while medium and darker colors are ranged at 00h-0Fh.
+The CGB display will mix colors quite oddly, increasing intensity of +only one R,G,B color will also influence the other two R,G,B colors.
+For example, a color setting of 03EFh (Blue=0, Green=1Fh, Red=0Fh) will +appear as Neon Green on VGA displays, but on the CGB it'll produce a +decently washed out Yellow.
+
+RGB Translation by GBAs
+Even though GBA is described to be compatible to CGB games, most CGB +games are completely unplayable on GBAs because most colors are +invisible (black). Of course, colors such like Black and White will +appear the same on both CGB and GBA, but medium intensities are arranged +completely different.
+Intensities in range 00h..0Fh are invisible/black (unless eventually +under best sunlight circumstances, and when gazing at the screen under +obscure viewing angles), unfortunately, these intensities are regulary +used by most existing CGB games for medium and darker colors.
+Newer CGB games may avoid this effect by changing palette data when +detecting GBA hardware. A relative simple method would be using the +formula GBA=CGB/2+10h for each R,G,B intensity, probably the result +won't be perfect, and (once colors became visible) it may turn out that +the color mixing is different also, anyways, it'd be still ways better +than no conversion.
+Asides, this translation method should have been VERY easy to implement +in GBA hardware directly, even though Nintendo obviously failed to do +so. How did they say, This seal is your assurance for excellence in +workmanship and so on?
+
+
+
 LCD VRAM Bank (CGB only)

+FF4F - VBK - CGB Mode Only - VRAM Bank
+This 1bit register selects the current Video Memory (VRAM) Bank.
+
  Bit 0 - VRAM Bank (0-1)
+
Bank 0 contains 192 Tiles, and two background maps, just as for +monochrome games. Bank 1 contains another 192 Tiles, and color attribute +maps for the background maps in bank 0.
+
+
+
 LCD OAM DMA Transfers

+FF46 - DMA - DMA Transfer and Start Address (W)
+Writing to this register launches a DMA transfer from ROM or RAM to OAM +memory (sprite attribute table). The written value specifies the +transfer source address divided by 100h, ie. source & destination are:
+
  Source:      XX00-XX9F   ;XX in range from 00-F1h
+  Destination: FE00-FE9F
+
It takes 160 microseconds until the transfer has completed (80 +microseconds in CGB Double Speed Mode), during this time the CPU can +access only HRAM (memory at FF80-FFFE). For this reason, the programmer +must copy a short procedure into HRAM, and use this procedure to start +the transfer from inside HRAM, and wait until the transfer has finished:
+
   ld  (0FF46h),a ;start DMA transfer, a=start address/100h
+   ld  a,28h      ;delay...
+  wait:           ;total 5x40 cycles, approx 200ms
+   dec a          ;1 cycle
+   jr  nz,wait    ;4 cycles
+
Most programs are executing this procedure from inside of their VBlank +procedure, but it is possible to execute it during display redraw also, +allowing to display more than 40 sprites on the screen (ie. for example +40 sprites in upper half, and other 40 sprites in lower half of the +screen).
+
+
+
 LCD VRAM DMA Transfers (CGB only)

+FF51 - HDMA1 - CGB Mode Only - New DMA Source, High
+FF52 - HDMA2 - CGB Mode Only - New DMA Source, Low
+FF53 - HDMA3 - CGB Mode Only - New DMA Destination, High
+FF54 - HDMA4 - CGB Mode Only - New DMA Destination, Low
+FF55 - HDMA5 - CGB Mode Only - New DMA Length/Mode/Start
+These registers are used to initiate a DMA transfer from ROM or RAM to +VRAM. The Source Start Address may be located at 0000-7FF0 or A000-DFF0, +the lower four bits of the address are ignored (treated as zero). The +Destination Start Address may be located at 8000-9FF0, the lower four +bits of the address are ignored (treated as zero), the upper 3 bits are +ignored either (destination is always in VRAM).
+
+Writing to FF55 starts the transfer, the lower 7 bits of FF55 specify +the Transfer Length (divided by 10h, minus 1). Ie. lengths of 10h-800h +bytes can be defined by the values 00h-7Fh. And the upper bit of FF55 +indicates the Transfer Mode:
+
+Bit7=0 - General Purpose DMA
+When using this transfer method, all data is transferred at once. The +execution of the program is halted until the transfer has completed. +Note that the General Purpose DMA blindly attempts to copy the data, +even if the LCD controller is currently accessing VRAM. So General +Purpose DMA should be used only if the Display is disabled, or during +V-Blank, or (for rather short blocks) during H-Blank.
+The execution of the program continues when the transfer has been +completed, and FF55 then contains a value if FFh.
+
+Bit7=1 - H-Blank DMA
+The H-Blank DMA transfers 10h bytes of data during each H-Blank, ie. at +LY=0-143, no data is transferred during V-Blank (LY=144-153), but the +transfer will then continue at LY=00. The execution of the program is +halted during the separate transfers, but the program execution +continues during the 'spaces' between each data block.
+Note that the program may not change the Destination VRAM bank (FF4F), +or the Source ROM/RAM bank (in case data is transferred from bankable +memory) until the transfer has completed!
+Reading from Register FF55 returns the remaining length (divided by 10h, +minus 1), a value of 0FFh indicates that the transfer has completed. It +is also possible to terminate an active H-Blank transfer by writing zero +to Bit 7 of FF55. In that case reading from FF55 may return any value +for the lower 7 bits, but Bit 7 will be read as "1".
+
+Confirming if the DMA Transfer is Active
+Reading Bit 7 of FF55 can be used to confirm if the DMA transfer is +active (1=Not Active, 0=Active). This works under any circumstances - +after completion of General Purpose, or H-Blank Transfer, and after +manually terminating a H-Blank Transfer.
+
+Transfer Timings
+In both Normal Speed and Double Speed Mode it takes about 8us to +transfer a block of 10h bytes. That are 8 cycles in Normal Speed Mode, +and 16 'fast' cycles in Double Speed Mode.
+Older MBC controllers (like MBC1-4) and slower ROMs are not guaranteed +to support General Purpose or H-Blank DMA, that's because there are +always 2 bytes transferred per microsecond (even if the itself program +runs it Normal Speed Mode).
+
+
+
 VRAM Tile Data

+Tile Data is stored in VRAM at addresses 8000h-97FFh, this area defines +the Bitmaps for 192 Tiles. In CGB Mode 384 Tiles can be defined, because +memory at 0:8000h-97FFh and at 1:8000h-97FFh is used.
+
+Each tile is sized 8x8 pixels and has a color depth of 4 colors/gray +shades. Tiles can be displayed as part of the Background/Window map, +and/or as OAM tiles (foreground sprites). Note that foreground sprites +may have only 3 colors, because color 0 is transparent.
+
+As it was said before, there are two Tile Pattern Tables at $8000-8FFF +and at $8800-97FF. The first one can be used for sprites and the +background. Its tiles are numbered from 0 to 255. The second table can +be used for the background and the window display and its tiles are +numbered from -128 to 127.
+
+Each Tile occupies 16 bytes, where each 2 bytes represent a line:
+
  Byte 0-1  First Line (Upper 8 pixels)
+  Byte 2-3  Next Line
+  etc.
+
For each line, the first byte defines the least significant bits of the +color numbers for each pixel, and the second byte defines the upper bits +of the color numbers. In either case, Bit 7 is the leftmost pixel, and +Bit 0 the rightmost.
+
+So, each pixel is having a color number in range from 0-3. The color +numbers are translated into real colors (or gray shades) depending on +the current palettes. The palettes are defined through registers +FF47-FF49 (Non CGB Mode), and FF68-FF6B (CGB Mode).
+
+
+
 VRAM Background Maps

+The gameboy contains two 32x32 tile background maps in VRAM at addresses +9800h-9BFFh and 9C00h-9FFFh. Each can be used either to display "normal" +background, or "window" background.
+
+BG Map Tile Numbers
+An area of VRAM known as Background Tile Map contains the numbers of +tiles to be displayed. It is organized as 32 rows of 32 bytes each. Each +byte contains a number of a tile to be displayed. Tile patterns are +taken from the Tile Data Table located either at $8000-8FFF or +$8800-97FF. In the first case, patterns are numbered with unsigned +numbers from 0 to 255 (i.e. pattern #0 lies at address $8000). In the +second case, patterns have signed numbers from -128 to 127 (i.e. pattern +#0 lies at address $9000). The Tile Data Table address for the +background can be selected via LCDC register.
+
+BG Map Attributes (CGB Mode only)
+In CGB Mode, an additional map of 32x32 bytes is stored in VRAM Bank 1 +(each byte defines attributes for the corresponding tile-number map +entry in VRAM Bank 0):
+
  Bit 0-2  Background Palette number  (BGP0-7)
+  Bit 3    Tile VRAM Bank number      (0=Bank 0, 1=Bank 1)
+  Bit 4    Not used
+  Bit 5    Horizontal Flip            (0=Normal, 1=Mirror horizontally)
+  Bit 6    Vertical Flip              (0=Normal, 1=Mirror vertically)
+  Bit 7    BG-to-OAM Priority         (0=Use OAM priority bit, 1=BG Priority)
+
When Bit 7 is set, the corresponding BG tile will have priority above +all OBJs (regardless of the priority bits in OAM memory). There's also +an Master Priority flag in LCDC register Bit 0 which overrides all other +priority bits when cleared.
+
+As one background tile has a size of 8x8 pixels, the BG maps may hold a +picture of 256x256 pixels, an area of 160x144 pixels of this picture can +be displayed on the LCD screen.
+
+Normal Background (BG)
+The SCY and SCX registers can be used to scroll the background, allowing +to select the origin of the visible 160x144 pixel area within the total +256x256 pixel background map. Background wraps around the screen (i.e. +when part of it goes off the screen, it appears on the opposite side.)
+
+The Window
+Besides background, there is also a "window" overlaying the background. +The window is not scrollable i.e. it is always displayed starting from +its left upper corner. The location of a window on the screen can be +adjusted via WX and WY registers. Screen coordinates of the top left +corner of a window are WX-7,WY. The tiles for the window are stored in +the Tile Data Table. Both the Background and the window share the same +Tile Data Table.
+
+Both background and window can be disabled or enabled separately via +bits in the LCDC register.
+
+
+
 VRAM Sprite Attribute Table (OAM)

+GameBoy video controller can display up to 40 sprites either in 8x8 or +in 8x16 pixels. Because of a limitation of hardware, only ten sprites +can be displayed per scan line. Sprite patterns have the same format as +BG tiles, but they are taken from the Sprite Pattern Table located at +$8000-8FFF and have unsigned numbering.
+
+Sprite attributes reside in the Sprite Attribute Table (OAM - Object +Attribute Memory) at $FE00-FE9F. Each of the 40 entries consists of four +bytes with the following meanings:
+
+Byte0 - Y Position
+Specifies the sprites vertical position on the screen (minus 16).
+An offscreen value (for example, Y=0 or Y>=160) hides the sprite.
+
+Byte1 - X Position
+Specifies the sprites horizontal position on the screen (minus 8).
+An offscreen value (X=0 or X>=168) hides the sprite, but the sprite
+still affects the priority ordering - a better way to hide a sprite is +to set its Y-coordinate offscreen.
+
+Byte2 - Tile/Pattern Number
+Specifies the sprites Tile Number (00-FF). This (unsigned) value selects +a tile from memory at 8000h-8FFFh. In CGB Mode this could be either in +VRAM Bank 0 or 1, depending on Bit 3 of the following byte.
+In 8x16 mode, the lower bit of the tile number is ignored. Ie. the upper +8x8 tile is "NN AND FEh", and the lower 8x8 tile is "NN OR 01h".
+
+Byte3 - Attributes/Flags:
+
  Bit7   OBJ-to-BG Priority (0=OBJ Above BG, 1=OBJ Behind BG color 1-3)
+         (Used for both BG and Window. BG color 0 is always behind OBJ)
+  Bit6   Y flip          (0=Normal, 1=Vertically mirrored)
+  Bit5   X flip          (0=Normal, 1=Horizontally mirrored)
+  Bit4   Palette number  **Non CGB Mode Only** (0=OBP0, 1=OBP1)
+  Bit3   Tile VRAM-Bank  **CGB Mode Only**     (0=Bank 0, 1=Bank 1)
+  Bit2-0 Palette number  **CGB Mode Only**     (OBP0-7)
+

+Sprite Priorities and Conflicts
+When sprites with different x coordinate values overlap, the one with +the smaller x coordinate (closer to the left) will have priority and +appear above any others. This applies in Non CGB Mode only.
+When sprites with the same x coordinate values overlap, they have +priority according to table ordering. (i.e. $FE00 - highest, $FE04 - +next highest, etc.) In CGB Mode priorities are always assigned like +this.
+
+Only 10 sprites can be displayed on any one line. When this limit is +exceeded, the lower priority sprites (priorities listed above) won't be +displayed. To keep unused sprites from affecting onscreen sprites set +their Y coordinate to Y=0 or Y=>144+16. Just setting the X coordinate to +X=0 or X=>160+8 on a sprite will hide it but it will still affect other +sprites sharing the same lines.
+
+Writing Data to OAM Memory
+The recommened method is to write the data to normal RAM first, and to +copy that RAM to OAM by using the DMA transfer function, initiated +through DMA register (FF46).
+Beside for that, it is also possible to write data directly to the OAM +area by using normal LD commands, this works only during the H-Blank and +V-Blank periods. The current state of the LCD controller can be read out +from the STAT register (FF41).
+
+
+
 Accessing VRAM and OAM

+CAUTION
+When the LCD Controller is drawing the screen it is directly reading +from Video Memory (VRAM) and from the Sprite Attribute Table (OAM). +During these periods the Gameboy CPU may not access the VRAM and OAM. +That means, any attempts to write to VRAM/OAM are ignored (the data +remains unchanged). And any attempts to read from VRAM/OAM will return +undefined data (typically a value of FFh).
+
+For this reason the program should verify if VRAM/OAM is accessable +before actually reading or writing to it. This is usually done by +reading the Mode Bits from the STAT Register (FF41). When doing this (as +described in the examples below) you should take care that no interrupts +occur between the wait loops and the following memory access - the +memory is guaranted to be accessable only for a few cycles directly +after the wait loops have completed.
+
+VRAM (memory at 8000h-9FFFh) is accessable during Mode 0-2
+
  Mode 0 - H-Blank Period,
+  Mode 1 - V-Blank Period, and
+  Mode 2 - Searching OAM Period
+
A typical procedure that waits for accessibility of VRAM would be:
+
  ld   hl,0FF41h    ;-STAT Register
+ @@wait:            ;\
+  bit  1,(hl)       ; Wait until Mode is 0 or 1
+  jr   nz,@@wait    ;/
+
Even if the procedure gets executed at the <end> of Mode 0 or 1, it is +still proof to assume that VRAM can be accessed for a few more cycles +because in either case the following period is Mode 2 which allows +access to VRAM either.
+In CGB Mode an alternate method to write data to VRAM is to use the HDMA +Function (FF51-FF55).
+
+OAM (memory at FE00h-FE9Fh) is accessable during Mode 0-1
+
  Mode 0 - H-Blank Period, and
+  Mode 1 - V-Blank Period
+
Beside for that, OAM can be accessed at any time by using the DMA +Function (FF46). When directly reading or writing to OAM, a typical +procedure that waits for accessibilty or OAM Memory would be:
+
  ld   hl,0FF41h    ;-STAT Register
+ @@wait1:           ;\
+  bit  1,(hl)       ; Wait until Mode is -NOT- 0 or 1
+  jr   z,@@wait1    ;/
+ @@wait2:           ;\
+  bit  1,(hl)       ; Wait until Mode 0 or 1 -BEGINS-
+  jr   nz,@@wait2   ;/
+
The two wait loops ensure that Mode 0 or 1 will last for a few clock +cycles after completion of the procedure. In V-Blank period it might be +recommended to skip the whole procedure - and in most cases using the +above mentioned DMA function would be more recommended anyways.
+
+Note
+When the display is disabled, both VRAM and OAM are accessable at any +time. The downside is that the screen is blank (white) during this +period, so that disabling the display would be recommended only during +initialization.
+
+
+
 Sound Controller

+Sound Overview
+Sound Channel 1 - Tone & Sweep
+Sound Channel 2 - Tone
+Sound Channel 3 - Wave Output
+Sound Channel 4 - Noise
+Sound Control Registers
+
+
+
 Sound Overview

+There are two sound channels connected to the output terminals SO1 and +SO2. There is also a input terminal Vin connected to the cartridge. It +can be routed to either of both output terminals. GameBoy circuitry +allows producing sound in four different ways:
+
+
   Quadrangular wave patterns with sweep and envelope functions.
+   Quadrangular wave patterns with envelope functions.
+   Voluntary wave patterns from wave RAM.
+   White noise with an envelope function.
+

+These four sounds can be controlled independantly and then mixed +separately for each of the output terminals.
+
+Sound registers may be set at all times while producing sound.
+
+(Sounds will have a 2.4% higher frequency on Super GB.)
+
+
+
 Sound Channel 1 - Tone & Sweep

+FF10 - NR10 - Channel 1 Sweep register (R/W)
+
  Bit 6-4 - Sweep Time
+  Bit 3   - Sweep Increase/Decrease
+             0: Addition    (frequency increases)
+             1: Subtraction (frequency decreases)
+  Bit 2-0 - Number of sweep shift (n: 0-7)
+
Sweep Time:
+
  000: sweep off - no freq change
+  001: 7.8 ms  (1/128Hz)
+  010: 15.6 ms (2/128Hz)
+  011: 23.4 ms (3/128Hz)
+  100: 31.3 ms (4/128Hz)
+  101: 39.1 ms (5/128Hz)
+  110: 46.9 ms (6/128Hz)
+  111: 54.7 ms (7/128Hz)
+

+The change of frequency (NR13,NR14) at each shift is calculated by the +following formula where X(0) is initial freq & X(t-1) is last freq:
+
  X(t) = X(t-1) +/- X(t-1)/2^n
+

+FF11 - NR11 - Channel 1 Sound length/Wave pattern duty (R/W)
+
  Bit 7-6 - Wave Pattern Duty (Read/Write)
+  Bit 5-0 - Sound length data (Write Only) (t1: 0-63)
+
Wave Duty:
+
  00: 12.5% ( _-------_-------_------- )
+  01: 25%   ( __------__------__------ )
+  10: 50%   ( ____----____----____---- ) (normal)
+  11: 75%   ( ______--______--______-- )
+
Sound Length = (64-t1)*(1/256) seconds
+The Length value is used only if Bit 6 in NR14 is set.
+
+FF12 - NR12 - Channel 1 Volume Envelope (R/W)
+
  Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound)
+  Bit 3   - Envelope Direction (0=Decrease, 1=Increase)
+  Bit 2-0 - Number of envelope sweep (n: 0-7)
+            (If zero, stop envelope operation.)
+
Length of 1 step = n*(1/64) seconds
+
+FF13 - NR13 - Channel 1 Frequency lo (Write Only)
+
+Lower 8 bits of 11 bit frequency (x).
+Next 3 bit are in NR14 ($FF14)
+
+FF14 - NR14 - Channel 1 Frequency hi (R/W)
+
  Bit 7   - Initial (1=Restart Sound)     (Write Only)
+  Bit 6   - Counter/consecutive selection (Read/Write)
+            (1=Stop output when length in NR11 expires)
+  Bit 2-0 - Frequency's higher 3 bits (x) (Write Only)
+
Frequency = 131072/(2048-x) Hz
+
+
+
 Sound Channel 2 - Tone

+This sound channel works exactly as channel 1, except that it doesn't +have a Tone Envelope/Sweep Register.
+
+FF16 - NR21 - Channel 2 Sound Length/Wave Pattern Duty (R/W)
+
  Bit 7-6 - Wave Pattern Duty (Read/Write)
+  Bit 5-0 - Sound length data (Write Only) (t1: 0-63)
+
Wave Duty:
+
  00: 12.5% ( _-------_-------_------- )
+  01: 25%   ( __------__------__------ )
+  10: 50%   ( ____----____----____---- ) (normal)
+  11: 75%   ( ______--______--______-- )
+
Sound Length = (64-t1)*(1/256) seconds
+The Length value is used only if Bit 6 in NR24 is set.
+
+FF17 - NR22 - Channel 2 Volume Envelope (R/W)
+
  Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound)
+  Bit 3   - Envelope Direction (0=Decrease, 1=Increase)
+  Bit 2-0 - Number of envelope sweep (n: 0-7)
+            (If zero, stop envelope operation.)
+
Length of 1 step = n*(1/64) seconds
+
+FF18 - NR23 - Channel 2 Frequency lo data (W)
+Frequency's lower 8 bits of 11 bit data (x).
+Next 3 bits are in NR24 ($FF19).
+
+FF19 - NR24 - Channel 2 Frequency hi data (R/W)
+
  Bit 7   - Initial (1=Restart Sound)     (Write Only)
+  Bit 6   - Counter/consecutive selection (Read/Write)
+            (1=Stop output when length in NR21 expires)
+  Bit 2-0 - Frequency's higher 3 bits (x) (Write Only)
+
Frequency = 131072/(2048-x) Hz
+
+
+
 Sound Channel 3 - Wave Output

+This channel can be used to output digital sound, the length of the +sample buffer (Wave RAM) is limited to 32 digits. This sound channel can +be also used to output normal tones when initializing the Wave RAM by a +square wave. This channel doesn't have a volume envelope register.
+
+FF1A - NR30 - Channel 3 Sound on/off (R/W)
+
  Bit 7 - Sound Channel 3 Off  (0=Stop, 1=Playback)  (Read/Write)
+

+FF1B - NR31 - Channel 3 Sound Length
+
  Bit 7-0 - Sound length (t1: 0 - 255)
+
Sound Length = (256-t1)*(1/256) seconds
+This value is used only if Bit 6 in NR34 is set.
+
+FF1C - NR32 - Channel 3 Select output level (R/W)
+
  Bit 6-5 - Select output level (Read/Write)
+
Possible Output levels are:
+
  0: Mute (No sound)
+  1: 100% Volume (Produce Wave Pattern RAM Data as it is)
+  2:  50% Volume (Produce Wave Pattern RAM data shifted once to the right)
+  3:  25% Volume (Produce Wave Pattern RAM data shifted twice to the right)
+

+FF1D - NR33 - Channel 3 Frequency's lower data (W)
+Lower 8 bits of an 11 bit frequency (x).
+
+FF1E - NR34 - Channel 3 Frequency's higher data (R/W)
+
  Bit 7   - Initial (1=Restart Sound)     (Write Only)
+  Bit 6   - Counter/consecutive selection (Read/Write)
+            (1=Stop output when length in NR31 expires)
+  Bit 2-0 - Frequency's higher 3 bits (x) (Write Only)
+
Frequency = 4194304/(64*(2048-x)) Hz = 65536/(2048-x) Hz
+
+FF30-FF3F - Wave Pattern RAM
+Contents - Waveform storage for arbitrary sound data
+
+This storage area holds 32 4-bit samples that are played back upper 4 +bits first.
+
+
+
 Sound Channel 4 - Noise

+This channel is used to output white noise. This is done by randomly +switching the amplitude between high and low at a given frequency. +Depending on the frequency the noise will appear 'harder' or 'softer'.
+
+It is also possible to influence the function of the random generator, +so the that the output becomes more regular, resulting in a limited +ability to output Tone instead of Noise.
+
+FF20 - NR41 - Channel 4 Sound Length (R/W)
+
  Bit 5-0 - Sound length data (t1: 0-63)
+
Sound Length = (64-t1)*(1/256) seconds
+The Length value is used only if Bit 6 in NR44 is set.
+
+FF21 - NR42 - Channel 4 Volume Envelope (R/W)
+
  Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound)
+  Bit 3   - Envelope Direction (0=Decrease, 1=Increase)
+  Bit 2-0 - Number of envelope sweep (n: 0-7)
+            (If zero, stop envelope operation.)
+
Length of 1 step = n*(1/64) seconds
+
+FF22 - NR43 - Channel 4 Polynomial Counter (R/W)
+The amplitude is randomly switched between high and low at the given +frequency. A higher frequency will make the noise to appear 'softer'.
+When Bit 3 is set, the output will become more regular, and some +frequencies will sound more like Tone than Noise.
+
  Bit 7-4 - Shift Clock Frequency (s)
+  Bit 3   - Counter Step/Width (0=15 bits, 1=7 bits)
+  Bit 2-0 - Dividing Ratio of Frequencies (r)
+
Frequency = 524288 Hz / r / 2^(s+1) ;For r=0 assume r=0.5 instead
+
+FF23 - NR44 - Channel 4 Counter/consecutive; Inital (R/W)
+
  Bit 7   - Initial (1=Restart Sound)     (Write Only)
+  Bit 6   - Counter/consecutive selection (Read/Write)
+            (1=Stop output when length in NR41 expires)
+

+
+
 Sound Control Registers

+FF24 - NR50 - Channel control / ON-OFF / Volume (R/W)
+The volume bits specify the "Master Volume" for Left/Right sound output.
+
  Bit 7   - Output Vin to SO2 terminal (1=Enable)
+  Bit 6-4 - SO2 output level (volume)  (0-7)
+  Bit 3   - Output Vin to SO1 terminal (1=Enable)
+  Bit 2-0 - SO1 output level (volume)  (0-7)
+
The Vin signal is received from the game cartridge bus, allowing +external hardware in the cartridge to supply a fifth sound channel, +additionally to the gameboys internal four channels. As far as I know +this feature isn't used by any existing games.
+
+FF25 - NR51 - Selection of Sound output terminal (R/W)
+
  Bit 7 - Output sound 4 to SO2 terminal
+  Bit 6 - Output sound 3 to SO2 terminal
+  Bit 5 - Output sound 2 to SO2 terminal
+  Bit 4 - Output sound 1 to SO2 terminal
+  Bit 3 - Output sound 4 to SO1 terminal
+  Bit 2 - Output sound 3 to SO1 terminal
+  Bit 1 - Output sound 2 to SO1 terminal
+  Bit 0 - Output sound 1 to SO1 terminal
+

+FF26 - NR52 - Sound on/off
+If your GB programs don't use sound then write 00h to this register to +save 16% or more on GB power consumption. Disabeling the sound +controller by clearing Bit 7 destroys the contents of all sound +registers. Also, it is not possible to access any sound registers +(execpt FF26) while the sound controller is disabled.
+
  Bit 7 - All sound on/off  (0: stop all sound circuits) (Read/Write)
+  Bit 3 - Sound 4 ON flag (Read Only)
+  Bit 2 - Sound 3 ON flag (Read Only)
+  Bit 1 - Sound 2 ON flag (Read Only)
+  Bit 0 - Sound 1 ON flag (Read Only)
+
Bits 0-3 of this register are read only status bits, writing to these +bits does NOT enable/disable sound. The flags get set when sound output +is restarted by setting the Initial flag (Bit 7 in NR14-NR44), the flag +remains set until the sound length has expired (if enabled). A volume +envelopes which has decreased to zero volume will NOT cause the sound +flag to go off.
+
+
+
 Joypad Input

+FF00 - P1/JOYP - Joypad (R/W)
+The eight gameboy buttons/direction keys are arranged in form of a 2x4 +matrix. Select either button or direction keys by writing to this +register, then read-out bit 0-3.
+
  Bit 7 - Not used
+  Bit 6 - Not used
+  Bit 5 - P15 Select Button Keys      (0=Select)
+  Bit 4 - P14 Select Direction Keys   (0=Select)
+  Bit 3 - P13 Input Down  or Start    (0=Pressed) (Read Only)
+  Bit 2 - P12 Input Up    or Select   (0=Pressed) (Read Only)
+  Bit 1 - P11 Input Left  or Button B (0=Pressed) (Read Only)
+  Bit 0 - P10 Input Right or Button A (0=Pressed) (Read Only)
+
Note: Most programs are repeatedly reading from this port several times +(the first reads used as short delay, allowing the inputs to stabilize, +and only the value from the last read actually used).
+
+Usage in SGB software
+Beside for normal joypad input, SGB games mis-use the joypad register to +output SGB command packets to the SNES, also, SGB programs may read out +gamepad states from up to four different joypads which can be connected +to the SNES.
+See SGB description for details.
+
+INT 60 - Joypad Interrupt
+Joypad interrupt is requested when any of the above Input lines changes +from High to Low. Generally this should happen when a key becomes +pressed (provided that the button/direction key is enabled by above +Bit4/5), however, because of switch bounce, one or more High to Low +transitions are usually produced both when pressing or releasing a key.
+
+Using the Joypad Interrupt
+It's more or less useless for programmers, even when selecting both +buttons and direction keys simultaneously it still cannot recognize all +keystrokes, because in that case a bit might be already held low by a +button key, and pressing the corresponding direction key would thus +cause no difference. The only meaningful purpose of the keystroke +interrupt would be to terminate STOP (low power) standby state.
+Also, the joypad interrupt does not appear to work with CGB and GBA +hardware (the STOP function can be still terminated by joypad keystrokes +though).
+
+
+
 Serial Data Transfer (Link Cable)

+FF01 - SB - Serial transfer data (R/W)
+8 Bits of data to be read/written
+
+FF02 - SC - Serial Transfer Control (R/W)
+
  Bit 7 - Transfer Start Flag (0=No Transfer, 1=Start)
+  Bit 1 - Clock Speed (0=Normal, 1=Fast) ** CGB Mode Only **
+  Bit 0 - Shift Clock (0=External Clock, 1=Internal Clock)
+
The clock signal specifies the rate at which the eight data bits in SB +(FF01) are transferred. When the gameboy is communicating with another +gameboy (or other computer) then either one must supply internal clock, +and the other one must use external clock.
+
+Internal Clock
+In Non-CGB Mode the gameboy supplies an internal clock of 8192Hz only +(allowing to transfer about 1 KByte per second). In CGB Mode four +internal clock rates are available, depending on Bit 1 of the SC +register, and on whether the CGB Double Speed Mode is used:
+
    8192Hz -  1KB/s - Bit 1 cleared, Normal
+   16384Hz -  2KB/s - Bit 1 cleared, Double Speed Mode
+  262144Hz - 32KB/s - Bit 1 set,     Normal
+  524288Hz - 64KB/s - Bit 1 set,     Double Speed Mode
+

+External Clock
+The external clock is typically supplied by another gameboy, but might +be supplied by another computer (for example if connected to a PCs +parallel port), in that case the external clock may have any speed. Even +the old/monochrome gameboy is reported to recognizes external clocks of +up to 500KHz. And there is no limitiation into the other direction - +even when suppling an external clock speed of "1 bit per month", then +the gameboy will still eagerly wait for the next bit(s) to be +transferred. It isn't required that the clock pulses are sent at an +regular interval either.
+
+Timeouts
+When using external clock then the transfer will not complete until the +last bit is received. In case that the second gameboy isn't supplying a +clock signal, if it gets turned off, or if there is no second gameboy +connected at all) then transfer will never complete. For this reason the +transfer procedure should use a timeout counter, and abort the +communication if no response has been received during the timeout +interval.
+
+Delays and Synchronization
+The gameboy that is using internal clock should always execute a small +delay between each transfer, in order to ensure that the opponent +gameboy has enough time to prepare itself for the next transfer, ie. the +gameboy with external clock must have set its transfer start bit before +the gameboy with internal clock starts the transfer. Alternately, the +two gameboys could switch between internal and external clock for each +transferred byte to ensure synchronization.
+
+Transfer is initiated by setting the Transfer Start Flag. This bit is +automatically set to 0 at the end of Transfer. Reading this bit can be +used to determine if the transfer is still active.
+
+INT 58 - Serial Interrupt
+When the transfer has completed (ie. after sending/receiving 8 bits, if +any) then an interrupt is requested by setting Bit 3 of the IF Register +(FF0F). When that interrupt is enabled, then the Serial Interrupt vector +at 0058 is called.
+
+XXXXXX...
+
+Transmitting and receiving serial data is done simultaneously. The +received data is automatically stored in SB.
+
+The serial I/O port on the Gameboy is a very simple setup and is crude +compared to standard RS-232 (IBM-PC) or RS-485 (Macintosh) serial ports. +There are no start or stop bits.
+
+During a transfer, a byte is shifted in at the same time that a byte is +shifted out. The rate of the shift is determined by whether the clock +source is internal or external.
+The most significant bit is shifted in and out first.
+
+When the internal clock is selected, it drives the clock pin on the game +link port and it stays high when not used. During a transfer it will go +low eight times to clock in/out each bit.
+
+The state of the last bit shifted out determines the state of the output +line until another transfer takes place.
+
+If a serial transfer with internal clock is performed and no external +GameBoy is present, a value of $FF will be received in the transfer.
+
+The following code causes $75 to be shifted out the serial port and a +byte to be shifted into $FF01:
+
+
    ld   a,$75
+    ld  ($FF01),a
+    ld   a,$81
+    ld  ($FF02),a
+

+
+
 Timer and Divider Registers

+FF04 - DIV - Divider Register (R/W)
+This register is incremented at rate of 16384Hz (~16779Hz on SGB). In +CGB Double Speed Mode it is incremented twice as fast, ie. at 32768Hz. +Writing any value to this register resets it to 00h.
+
+FF05 - TIMA - Timer counter (R/W)
+This timer is incremented by a clock frequency specified by the TAC +register ($FF07). When the value overflows (gets bigger than FFh) then +it will be reset to the value specified in TMA (FF06), and an interrupt +will be requested, as described below.
+
+FF06 - TMA - Timer Modulo (R/W)
+When the TIMA overflows, this data will be loaded.
+
+FF07 - TAC - Timer Control (R/W)
+
  Bit 2    - Timer Stop  (0=Stop, 1=Start)
+  Bits 1-0 - Input Clock Select
+             00:   4096 Hz    (~4194 Hz SGB)
+             01: 262144 Hz  (~268400 Hz SGB)
+             10:  65536 Hz   (~67110 Hz SGB)
+             11:  16384 Hz   (~16780 Hz SGB)
+

+INT 50 - Timer Interrupt
+Each time when the timer overflows (ie. when TIMA gets bigger than FFh), +then an interrupt is requested by setting Bit 2 in the IF Register +(FF0F). When that interrupt is enabled, then the CPU will execute it by +calling the timer interrupt vector at 0050h.
+
+Note
+The above described Timer is the built-in timer in the gameboy. It has +nothing to do with the MBC3s battery buffered Real Time Clock - that's a +completely different thing, described in the chapter about Memory +Banking Controllers.
+
+
+
 Interrupts

+IME - Interrupt Master Enable Flag (Write Only)
+
  0 - Disable all Interrupts
+  1 - Enable all Interrupts that are enabled in IE Register (FFFF)
+
The IME flag is used to disable all interrupts, overriding any enabled +bits in the IE Register. It isn't possible to access the IME flag by +using a I/O address, instead IME is accessed directly from the CPU, by +the following opcodes/operations:
+
  EI     ;Enable Interrupts  (ie. IME=1)
+  DI     ;Disable Interrupts (ie. IME=0)
+  RETI   ;Enable Ints & Return (same as the opcode combination EI, RET)
+  <INT>  ;Disable Ints & Call to Interrupt Vector
+
Whereas <INT> means the operation which is automatically executed by the +CPU when it executes an interrupt.
+
+FFFF - IE - Interrupt Enable (R/W)
+
  Bit 0: V-Blank  Interrupt Enable  (INT 40h)  (1=Enable)
+  Bit 1: LCD STAT Interrupt Enable  (INT 48h)  (1=Enable)
+  Bit 2: Timer    Interrupt Enable  (INT 50h)  (1=Enable)
+  Bit 3: Serial   Interrupt Enable  (INT 58h)  (1=Enable)
+  Bit 4: Joypad   Interrupt Enable  (INT 60h)  (1=Enable)
+

+FF0F - IF - Interrupt Flag (R/W)
+
  Bit 0: V-Blank  Interrupt Request (INT 40h)  (1=Request)
+  Bit 1: LCD STAT Interrupt Request (INT 48h)  (1=Request)
+  Bit 2: Timer    Interrupt Request (INT 50h)  (1=Request)
+  Bit 3: Serial   Interrupt Request (INT 58h)  (1=Request)
+  Bit 4: Joypad   Interrupt Request (INT 60h)  (1=Request)
+
When an interrupt signal changes from low to high, then the +corresponding bit in the IF register becomes set. For example, Bit 0 +becomes set when the LCD controller enters into the V-Blank period.
+
+Interrupt Requests
+Any set bits in the IF register are only <requesting> an interrupt to be +executed. The actual <execution> happens only if both the IME flag, and +the corresponding bit in the IE register are set, otherwise the +interrupt 'waits' until both IME and IE allow its execution.
+
+Interrupt Execution
+When an interrupt gets executed, the corresponding bit in the IF +register becomes automatically reset by the CPU, and the IME flag +becomes cleared (disabeling any further interrupts until the program +re-enables the interrupts, typically by using the RETI instruction), and +the corresponding Interrupt Vector (that are the addresses in range +0040h-0060h, as shown in IE and IF register decriptions above) becomes +called.
+
+Manually Requesting/Discarding Interrupts
+As the CPU automatically sets and cleares the bits in the IF register it +is usually not required to write to the IF register. However, the user +may still do that in order to manually request (or discard) interrupts. +As for real interrupts, a manually requested interrupt isn't executed +unless/until IME and IE allow its execution.
+
+Interrupt Priorities
+In the following three situations it might happen that more than 1 bit +in the IF register are set, requesting more than one interrupt at once:
+
  1) More than one interrupt signal changed from Low
+     to High at the same time.
+  2) Several interrupts have been requested during a
+     time in which IME/IE didn't allow these interrupts
+     to be executed directly.
+  3) The user has written a value with several "1" bits
+     (for example 1Fh) to the IF register.
+
Provided that IME and IE allow the execution of more than one of the +requested interrupts, then the interrupt with the highest priority +becomes executed first. The priorities are ordered as the bits in the IE +and IF registers, Bit 0 (V-Blank) having the highest priority, and Bit 4 +(Joypad) having the lowest priority.
+
+Nested Interrupts
+The CPU automatically disables all other interrupts by setting IME=0 +when it executes an interrupt. Usually IME remains zero until the +interrupt procedure returns (and sets IME=1 by the RETI instruction). +However, if you want any other interrupts of lower or higher (or same) +priority to be allowed to be executed from inside of the interrupt +procedure, then you can place an EI instruction into the interrupt +procedure.
+
+
+
 CGB Registers

+Forward
+This chapter describes only CGB (Color Gameboy) registers that didn't +fit into normal categories - most CGB registers are described in the +chapter about Video Display (Color Palettes, VRAM Bank, VRAM DMA +Transfers, and changed meaning of Bit 0 of LCDC Control register). Also, +a changed bit is noted in the chapter about the Serial/Link port.
+
+Unlocking CGB functions
+When using any CGB registers (including those in the Video/Link +chapters), you must first unlock CGB features by changing byte 0143h in +the cartridge header. Typically use a value of 80h for games which +support both CGB and monochrome gameboys, and C0h for games which work +on CGBs only. Otherwise, the CGB will operate in monochrome "Non CGB" +compatibility mode.
+
+Detecting CGB (and GBA) functions
+CGB hardware can be detected by examing the CPU accumulator (A-register) +directly after startup. A value of 11h indicates CGB (or GBA) hardware, +if so, CGB functions can be used (if unlocked, see above).
+When A=11h, you may also examine Bit 0 of the CPUs B-Register to +separate between CGB (bit cleared) and GBA (bit set), by that detection +it is possible to use 'repaired' color palette data matching for GBA +displays.
+
+FF4D - KEY1 - CGB Mode Only - Prepare Speed Switch
+
  Bit 7: Current Speed     (0=Normal, 1=Double) (Read Only)
+  Bit 0: Prepare Speed Switch (0=No, 1=Prepare) (Read/Write)
+
This register is used to prepare the gameboy to switch between CGB +Double Speed Mode and Normal Speed Mode. The actual speed switch is +performed by executing a STOP command after Bit 0 has been set. After +that Bit 0 will be cleared automatically, and the gameboy will operate +at the 'other' speed. The recommended speed switching procedure in +pseudo code would be:
+
  IF KEY1_BIT7 <> DESIRED_SPEED THEN
+    IE=00H       ;(FFFF)=00h
+    JOYP=30H     ;(FF00)=30h
+    KEY1=01H     ;(FF4D)=01h
+    STOP         ;STOP
+  ENDIF
+
The CGB is operating in Normal Speed Mode when it is turned on. Note +that using the Double Speed Mode increases the power consumption, it +would be recommended to use Single Speed whenever possible. However, the +display will flicker (white) for a moment during speed switches, so this +cannot be done permanentely.
+In Double Speed Mode the following will operate twice as fast as normal:
+
  The CPU (2.10 MHz, 1 Cycle = approx. 0.5us)
+  Timer and Divider Registers
+  Serial Port (Link Cable)
+  DMA Transfer to OAM
+
And the following will keep operating as usual:
+
  LCD Video Controller
+  HDMA Transfer to VRAM
+  All Sound Timings and Frequencies
+

+FF56 - RP - CGB Mode Only - Infrared Communications Port
+This register allows to input and output data through the CGBs built-in +Infrared Port. When reading data, bit 6 and 7 must be set (and obviously +Bit 0 must be cleared - if you don't want to receive your own gameboys +IR signal). After sending or receiving data you should reset the +register to 00h to reduce battery power consumption again.
+
  Bit 0:   Write Data   (0=LED Off, 1=LED On)             (Read/Write)
+  Bit 1:   Read Data    (0=Receiving IR Signal, 1=Normal) (Read Only)
+  Bit 6-7: Data Read Enable (0=Disable, 3=Enable)         (Read/Write)
+
Note that the receiver will adapt itself to the normal level of IR +pollution in the air, so if you would send a LED ON signal for a longer +period, then the receiver would treat that as normal (=OFF) after a +while. For example, a Philips TV Remote Control sends a series of 32 LED +ON/OFF pulses (length 10us ON, 17.5us OFF each) instead of a permanent +880us LED ON signal.
+Even though being generally CGB compatible, the GBA does not include an +infra-red port.
+
+FF70 - SVBK - CGB Mode Only - WRAM Bank
+In CGB Mode 32 KBytes internal RAM are available. This memory is divided +into 8 banks of 4 KBytes each. Bank 0 is always available in memory at +C000-CFFF, Bank 1-7 can be selected into the address space at D000-DFFF.
+
  Bit 0-2  Select WRAM Bank (Read/Write)
+
Writing a value of 01h-07h will select Bank 1-7, writing a value of 00h +will select Bank 1 either.
+
+FF6C - Undocumented (FEh) - Bit 0 (Read/Write) - CGB Mode Only
+FF72 - Undocumented (00h) - Bit 0-7 (Read/Write)
+FF73 - Undocumented (00h) - Bit 0-7 (Read/Write)
+FF74 - Undocumented (00h) - Bit 0-7 (Read/Write) - CGB Mode Only
+FF75 - Undocumented (8Fh) - Bit 4-6 (Read/Write)
+FF76 - Undocumented (00h) - Always 00h (Read Only)
+FF77 - Undocumented (00h) - Always 00h (Read Only)
+These are undocumented CGB Registers. The numbers in brackets () +indicate the initial values. Purpose of these registers is unknown (if +any). Registers FF6C and FF74 are always FFh if the CGB is in Non CGB +Mode.
+
+
+
 SGB Functions

+General Information
+SGB Description
+SGB Unlocking and Detecting SGB Functions
+SGB Command Packet Transfers
+SGB VRAM Transfers
+SGB Command Summary
+SGB Color Palettes Overview
+
+SGB Commands
+SGB Palette Commands
+SGB Color Attribute Commands
+SGB Sound Functions
+SGB System Control Commands
+SGB Multiplayer Command
+SGB Border and OBJ Commands
+
+
+
 SGB Description

+General Description
+Basically, the SGB (Super Gameboy) is an adapter cartridge that allows +to play gameboy games on a SNES (Super Nintendo Entertainment System) +gaming console. In detail, you plug the gameboy cartridge into the SGB +cartridge, then plug the SGB cartridge into the SNES, and then connect +the SNES to your TV Set. In result, games can be played and viewed on +the TV Set, and are controlled by using the SNES joypad(s).
+
+More Technical Description
+The SGB cartridge just contains a normal gameboy CPU and normal gameboy +video controller. Normally the video signal from this controller would +be sent to the LCD screen, however, in this special case the SNES read +out the video signal and displays it on the TV set by using a special +SNES BIOS ROM which is located in the SGB cartridge. Also, normal +gameboy sound output is forwared to the SNES and output to the TV Set, +vice versa, joypad input is forwared from the SNES controller(s) to the +gameboy joypad inputs.
+
+Normal Monochrome Games
+Any gameboy games which have been designed for normal monochrome +handheld gameboys will work with the SGB hardware as well. The SGB will +apply a four color palette to these games by replacing the normal four +grayshades. The 160x144 pixel gamescreen is displayed in the middle of +the 256x224 pixel SNES screen (the unused area is filled by a screen +border bitmap). The user may access built-in menues, allowing to change +color palette data, to select between several pre-defined borders, etc.
+
+Games that have been designed to support SGB functions may also access +the following additional features:
+
+Colorized Game Screen
+There's limited ability to colorize the gamescreen by assigning custom +color palettes to each 20x18 display characters, however, this works +mainly for static display data such like title screens or status bars, +the 20x18 color attribute map is non-scrollable, and it is not possible +to assign separate colors to moveable foreground sprites (OBJs), so that +animated screen regions will be typically restricted to using a single +palette of four colors only.
+
+SNES Foreground Sprites
+Up to 24 foreground sprites (OBJs) of 8x8 or 16x16 pixels, 16 colors can +be displayed. When replacing (or just overlaying) the normal gameboy +OBJs by SNES OBJs it'd be thus possible to display OBJs with other +colors than normal background area. This method doesn't appear to be +very popular, even though it appears to be quite easy to implement, +however, the bottommost character line of the gamescreen will be masked +out because this area is used to transfer OAM data to the SNES.
+
+The SGB Border
+The possibly most popular and most impressive feature is to replace the +default SGB screen border by a custom bitmap which is stored in the game +cartridge.
+
+Multiple Joypads
+Up to four joypads can be conected to the SNES, and SGB software may +read-out each of these joypads separately, allowing up to four players +to play the same game simultaneously. Unlike for multiplayer handheld +games, this requires only one game cartridge and only one SGB/SNES, and +no link cables are required, the downside is that all players must share +the same display screen.
+
+Sound Functions
+Beside for normal gameboy sound, a number of digital sound effects is +pre-defined in the SNES BIOS, these effects may be accessed quite +easily. Programmers whom are familiar with SNES sounds may also access +the SNES sound chip, or use the SNES MIDI engine directly in order to +produce other sound effects or music.
+
+Taking Control of the SNES CPU
+Finally, it is possible to write program code or data into SNES memory, +and to execute such program code by using the SNES CPU.
+
+SGB System Clock
+Because the SGB is synchronized to the SNES CPU, the gameboy system +clock is directly chained to the SNES system clock. In result, the +gameboy CPU, video controller, timers, and sound frequencies will be all +operated approx 2.4% faster as by normal gameboys.
+Basically, this should be no problem, and the game will just run a +little bit faster. However sensitive musicians may notice that sound +frequencies are a bit too high, programs that support SGB functions may +avoid this effect by reducing frequencies of gameboy sounds when having +detected SGB hardware.
+Also, I think that I've heard that SNES models which use a 50Hz display +refresh rate (rather than 60Hz) are resulting in respectively slower +SGB/gameboy timings ???
+
+
+
 SGB Unlocking and Detecting SGB Functions

+Cartridge Header
+SGB games are required to have a cartridge header with Nintendo and +proper checksum just as normal gameboy games. Also, two special entries +must be set in order to unlock SGB functions:
+
  146h - SGB Flag - Must be set to 03h for SGB games
+  14Bh - Old Licensee Code - Must be set 33h for SGB games
+
When these entries aren't set, the game will still work just like all +'monochrome' gameboy games, but it cannot access any of the special SGB +functions.
+
+Detecting SGB hardware
+The recommended detection method is to send a MLT_REQ command which +enables two (or four) joypads. A normal handheld gameboy will ignore +this command, a SGB will now return incrementing joypad IDs each time +when deselecting keyboard lines (see MLT_REQ description for details).
+Now read-out joypad state/IDs several times, and if the ID-numbers are +changing, then it is a SGB (a normal gameboy would typically always +return 0Fh as ID). Finally, when not intending to use more than one +joypad, send another MLT_REQ command in order to re-disable the +multi-controller mode.
+Detection works regardless of whether and how many joypads are +physically connected to the SNES. However, detection works only when +having unlocked SGB functions in the cartridge header, as described +above.
+
+Separating between SGB and SGB2
+It is also possible to separate between SGB and SGB2 models by examining +the inital value of the accumulator (A-register) directly after startup.
+
  01h  SGB or Normal Gameboy (DMG)
+  FFh  SGB2 or Pocket Gameboy
+  11h  CGB or GBA
+
Because values 01h and FFh are shared for both handhelds and SGBs, it is +still required to use the above MLT_REQ detection procedure. As far as I +know the SGB2 doesn't have any extra features which'd require separate +SGB2 detection except for curiosity purposes, for example, the game +"Tetris DX" chooses to display an alternate SGB border on SGB2s.
+
+Reportedly, some SGB models include link ports (just like handheld +gameboy) (my own SGB does not have such an port), possibly this feature +is available in SGB2-type models only ???
+
+
+
 SGB Command Packet Transfers

+Command packets (aka Register Files) are transferred from the gameboy to +the SNES by using P14 and P15 output lines of the JOYPAD register +(FF00h), these lines are normally used to select the two rows in the +gameboy keyboard matrix (which still works).
+
+Transferring Bits
+A command packet transfer must be initiated by setting both P14 and P15 +to LOW, this will reset and start the SNES packet receiving program. +Data is then transferred (LSB first), setting P14=LOW will indicate a +"0" bit, and setting P15=LOW will indicate a "1" bit. For example:
+
       RESET 0   0   1   1   0   1   0
+  P14  --_---_---_-----------_-------_--...
+  P15  --_-----------_---_-------_------...
+
Data and reset pulses must be kept LOW for at least 5us. P14 and P15 +must be kept both HIGH for at least 15us between any pulses.
+Obviously, it'd be no good idea to access the JOYPAD register during the +transfer, for example, in case that your VBlank interrupt procedure +reads-out joypad states each frame, be sure to disable that interrupt +during the transfer (or disable only the joypad procedure by using a +software flag).
+
+Transferring Packets
+Each packet is invoked by a RESET pulse, then 128 bits of data are +transferred (16 bytes, LSB of first byte first), and finally, a "0"-bit +must be transferred as stop bit. The structure of normal packets is:
+
   1 PULSE Reset
+   1 BYTE  Command Code*8+Length
+  15 BYTES Parameter Data
+   1 BIT   Stop Bit (0)
+
The above 'Length' indicates the total number of packets (1-7, including +the first packet) which will be sent, ie. if more than 15 parameter +bytes are used, then further packet(s) will follow, as such:
+
   1 PULSE Reset
+  16 BYTES Parameter Data
+   1 BIT   Stop Bit (0)
+
By using all 7 packets, up to 111 data bytes (15+16*6) may be sent.
+Unused bytes at the end of the last packet must be set to zero.
+A 60ms (4 frames) delay should be invoked between each packet transfer.
+
+
+
 SGB VRAM Transfers

+Overview
+Beside for the packet transfer method, larger data blocks of 4KBytes can +be transferred by using the video signal. These transfers are invoked by +first sending one of the commands with the ending _TRN (by using normal +packet transfer), the 4K data block is then read-out by the SNES from +gameboy display memory during the next frame.
+
+Transfer Data
+Normally, transfer data should be stored at 8000h-8FFFh in gameboy VRAM,
+even though the SNES receives the data in from display scanlines, it +will automatically re-produce the same ordering of bits and bytes, as +being originally stored at 8000h-8FFFh in gameboy memory.
+
+Preparing the Display
+The above method works only when recursing the following things: BG Map +must display unsigned characters 00h-FFh on the screen; 00h..13h in +first line, 14h..27h in next line, etc. The gameboy display must be +enabled, the display may not be scrolled, OBJ sprites should not overlap +the background tiles, the BGP palette register must be set to E4h.
+
+Transfer Time
+Note that the transfer data should be prepared in VRAM <before> sending +the transfer command packet. The actual transfer starts at the beginning +of the next frame after the command has been sent, and the transfer ends +at the end of the 5th frame after the command has been sent (not +counting the frame in which the command has been sent).
+
+Avoiding Screen Garbage
+The display will contain 'garbage' during the transfer, this dirt-effect +can be avoided by freezing the screen (in the state which has been +displayed before the transfer) by using the MASK_EN command.
+Of course, this works only when actually executing the game on a SGB +(and not on normal handheld gameboys), it'd be thus required to detect +the presence of SGB hardware before blindly sending VRAM data.
+
+
+
 SGB Command Summary

+SGB System Command Table
+
  Code Name      Expl.
+  00   PAL01     Set SGB Palette 0,1 Data
+  01   PAL23     Set SGB Palette 2,3 Data
+  02   PAL03     Set SGB Palette 0,3 Data
+  03   PAL12     Set SGB Palette 1,2 Data
+  04   ATTR_BLK  "Block" Area Designation Mode
+  05   ATTR_LIN  "Line" Area Designation Mode
+  06   ATTR_DIV  "Divide" Area Designation Mode
+  07   ATTR_CHR  "1CHR" Area Designation Mode
+  08   SOUND     Sound On/Off
+  09   SOU_TRN   Transfer Sound PRG/DATA
+  0A   PAL_SET   Set SGB Palette Indirect
+  0B   PAL_TRN   Set System Color Palette Data
+  0C   ATRC_EN   Enable/disable Attraction Mode
+  0D   TEST_EN   Speed Function
+  0E   ICON_EN   SGB Function
+  0F   DATA_SND  SUPER NES WRAM Transfer 1
+  10   DATA_TRN  SUPER NES WRAM Transfer 2
+  11   MLT_REG   Controller 2 Request
+  12   JUMP      Set SNES Program Counter
+  13   CHR_TRN   Transfer Character Font Data
+  14   PCT_TRN   Set Screen Data Color Data
+  15   ATTR_TRN  Set Attribute from ATF
+  16   ATTR_SET  Set Data to ATF
+  17   MASK_EN   Game Boy Window Mask
+  18   OBJ_TRN   Super NES OBJ Mode
+

+
+
 SGB Color Palettes Overview

+Available SNES Palettes
+The SGB/SNES provides 8 palettes of 16 colors each, each color may be +defined out of a selection of 34768 colors (15 bit). Palettes 0-3 are +used to colorize the gamescreen, only the first four colors of each of +these palettes are used. Palettes 4-7 are used for the SGB Border, all +16 colors of each of these palettes may be used.
+
+Color 0 Restriction
+Color 0 of each of the eight palettes is transparent, causing the +backdrop color to be displayed instead. The backdrop color is typically +defined by the most recently color being assigned to Color 0 (regardless +of the palette number being used for that operation).
+Effectively, gamescreen palettes can have only three custom colors each, +and SGB border palettes only 15 colors each, additionally, color 0 can +be used for for all palettes, which will then all share the same color +though.
+
+Translation of Grayshades into Colors
+Because the SGB/SNES reads out the gameboy video controllers display +signal, it translates the different grayshades from the signal into SNES +colors as such:
+
  White       -->  Color 0
+  Light Gray  -->  Color 1
+  Dark Gray   -->  Color 2
+  Black       -->  Color 3
+
Note that gameboy colors 0-3 are assigned to user-selectable grayshades +by the gameboys BGP, OBP1, and OBP2 registers. There is thus no fixed +relationship between gameboy colors 0-3 and SNES colors 0-3.
+
+Using Gameboy BGP/OBP Registers
+A direct translation of color 0-3 into color 0-3 may be produced by +setting BGP/OBP registers to a value of 0E4h each. However, in case that +your program uses black background for example, then you may internally +assign background as "White" at the gameboy side by BGP/OBP registers +(which is then interpreted as SNES color 0, which is shared for all SNES +palettes). The advantage is that you may define Color 0 as Black at the +SNES side, and may assign custom colors for Colors 1-3 of each SNES +palette.
+
+System Color Palette Memory
+Beside for the actually visible palettes, up to 512 palettes of 4 colors +each may be defined in SNES RAM. Basically, this is completely +irrelevant because the palettes are just stored in RAM whithout any +relationship to the displayed picture, anyways, these pre-defined colors +may be transferred to actually visible palettes slightly faster as when +transferring palette data by separate command packets.
+
+
+
 SGB Palette Commands

+SGB Command 00h - PAL01
+Transmit color data for SGB palette 0, color 0-3, and for SGB palette 1, +color 1-3 (without separate color 0).
+
  Byte  Content
+  0     Command*8+Length (fixed length=01h)
+  1-E   Color Data for 7 colors of 2 bytes (16bit) each:
+          Bit 0-4   - Red Intensity   (0-31)
+          Bit 5-9   - Green Intensity (0-31)
+          Bit 10-14 - Blue Intensity  (0-31)
+          Bit 15    - Not used (zero)
+  F     Not used (00h)
+
The value transferred as color 0 will be applied for all eight palettes.
+
+SGB Command 01h - PAL23
+Same as above PAL01, but for Palettes 2 and 3 respectively.
+
+SGB Command 02h - PAL03
+Same as above PAL01, but for Palettes 0 and 3 respectively.
+
+SGB Command 03h - PAL12
+Same as above PAL01, but for Palettes 1 and 2 respectively.
+
+SGB Command 0Ah - PAL_SET
+Used to copy pre-defined palette data from SGB system color palette to +actual SGB palette.
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1-2   System Palette number for SGB Color Palette 0 (0-511)
+  3-4   System Palette number for SGB Color Palette 1 (0-511)
+  5-6   System Palette number for SGB Color Palette 2 (0-511)
+  7-8   System Palette number for SGB Color Palette 3 (0-511)
+  9     Attribute File
+          Bit 0-5 - Attribute File Number (00h-2Ch) (Used only if Bit7=1)
+          Bit 6   - Cancel Mask           (0=No change, 1=Yes)
+          Bit 7   - Use Attribute File    (0=No, 1=Apply above ATF Number)
+  A-F   Not used (zero)
+
Before using this function, System Palette data should be initialized by +PAL_TRN command, and (when used) Attribute File data should be +initialized by ATTR_TRN.
+
+SGB Command 0Bh - PAL_TRN
+Used to initialize SGB system color palettes in SNES RAM.
+System color palette memory contains 512 pre-defined palettes, these +palettes do not directly affect the display, however, the PAL_SET +command may be later used to transfer four of these 'logical' palettes +to actual visible 'physical' SGB palettes. Also, the OBJ_TRN function +will use groups of 4 System Color Palettes (4*4 colors) for SNES OBJ +palettes (16 colors).
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1-F   Not used (zero)
+
The palette data is sent by VRAM-Transfer (4 KBytes).
+
  000-FFF  Data for System Color Palette 0-511
+
Each Palette consists of four 16bit-color definitions (8 bytes).
+Note: The data is stored at 3000h-3FFFh in SNES memory.
+
+
+
 SGB Color Attribute Commands

+SGB Command 04h - ATTR_BLK
+Used to specify color attributes for the inside or outside of one or +more rectangular screen regions.
+
  Byte  Content
+  0     Command*8+Length (length=1..7)
+  1     Number of Data Sets (01h..12h)
+  2-7   Data Set #1
+          Byte 0 - Control Code (0-7)
+            Bit 0 - Change Colors inside of surrounded area     (1=Yes)
+            Bit 1 - Change Colors of surrounding character line (1=Yes)
+            Bit 2 - Change Colors outside of surrounded area    (1=Yes)
+            Bit 3-7 - Not used (zero)
+            Exception: When changing only the Inside or Outside, then the
+            Surrounding line becomes automatically changed to same color.
+          Byte 1 - Color Palette Designation
+            Bit 0-1 - Palette Number for inside of surrounded area
+            Bit 2-3 - Palette Number for surrounding character line
+            Bit 4-5 - Palette Number for outside of surrounded area
+            Bit 6-7 - Not used (zero)
+          Data Set Byte 2 - Coordinate X1 (left)
+          Data Set Byte 3 - Coordinate Y1 (upper)
+          Data Set Byte 4 - Coordinate X2 (right)
+          Data Set Byte 5 - Coordinate Y2 (lower)
+            Specifies the coordinates of the surrounding rectangle.
+  8-D   Data Set #2 (if any)
+  E-F   Data Set #3 (continued at 0-3 in next packet) (if any)
+
When sending three or more data sets, data is continued in further +packet(s). Unused bytes at the end of the last packet should be set to +zero. The format of the separate Data Sets is described below.
+
+SGB Command 05h - ATTR_LIN
+Used to specify color attributes of one or more horizontal or vertical +character lines.
+
  Byte  Content
+  0     Command*8+Length (length=1..7)
+  1     Number of Data Sets (01h..6Eh) (one byte each)
+  2     Data Set #1
+          Bit 0-4 - Line Number    (X- or Y-coordinate, depending on bit 7)
+          Bit 5-6 - Palette Number (0-3)
+          Bit 7   - H/V Mode Bit   (0=Vertical line, 1=Horizontal Line)
+  3     Data Set #2 (if any)
+  4     Data Set #3 (if any)
+  etc.
+
When sending 15 or more data sets, data is continued in further +packet(s). Unused bytes at the end of the last packet should be set to +zero. The format of the separate Data Sets (one byte each) is described +below.
+The length of each line reaches from one end of the screen to the other +end. In case that some lines overlap each other, then lines from +lastmost data sets will overwrite lines from previous data sets.
+
+SGB Command 06h - ATTR_DIV
+Used to split the screen into two halfes, and to assign separate color +attributes to each half, and to the division line between them.
+
  Byte  Content
+  0     Command*8+Length   (fixed length=1)
+  1     Color Palette Numbers and H/V Mode Bit
+          Bit 0-1  Palette Number below/right of division line
+          Bit 2-3  Palette Number above/left of division line
+          Bit 4-5  Palette Number for division line
+          Bit 6    H/V Mode Bit  (0=split left/right, 1=split above/below)
+  2     X- or Y-Coordinate (depending on H/V bit)
+  3-F   Not used (zero)
+

+SGB Command 07h - ATTR_CHR
+Used to specify color attributes for separate characters.
+
  Byte  Content
+  0     Command*8+Length (length=1..6)
+  1     Beginning X-Coordinate
+  2     Beginning Y-Coordinate
+  3-4   Number of Data Sets (1-360)
+  5     Writing Style   (0=Left to Right, 1=Top to Bottom)
+  6     Data Sets 1-4   (Set 1 in MSBs, Set 4 in LSBs)
+  7     Data Sets 5-8   (if any)
+  8     Data Sets 9-12  (if any)
+  etc.
+
When sending 41 or more data sets, data is continued in further +packet(s). Unused bytes at the end of the last packet should be set to +zero. Each data set consists of two bits, indicating the palette number +for one character.
+Depending on the writing style, data sets are written from left to +right, or from top to bottom. In either case the function wraps to the +next row/column when reaching the end of the screen.
+
+SGB Command 15h - ATTR_TRN
+Used to initialize Attribute Files (ATFs) in SNES RAM. Each ATF consists +of 20x18 color attributes for the gameboy screen. This function does not +directly affect display attributes. Instead, one of the defined ATFs may +be copied to actual display memory at a later time by using ATTR_SET or +PAL_SET functions.
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1-F   Not used (zero)
+
The ATF data is sent by VRAM-Transfer (4 KBytes).
+
  000-FD1  Data for ATF0 through ATF44 (4050 bytes)
+  FD2-FFF  Not used
+
Each ATF consists of 90 bytes, that are 5 bytes (20x2bits) for each of +the 18 character lines of the gameboy window. The two most significant +bits of the first byte define the color attribute (0-3) for the first +character of the first line, the next two bits the next character, and +so on.
+
+SGB Command 16h - ATTR_SET
+Used to transfer attributes from Attribute File (ATF) to gameboy window.
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1     Attribute File Number (00-2Ch), Bit 6=Cancel Mask
+  2-F   Not used (zero)
+
When above Bit 6 is set, the gameboy screen becomes re-enabled after the +transfer (in case it has been disabled/frozen by MASK_EN command).
+Note: The same functions may be (optionally) also included in PAL_SET +commands, as described in the chapter about Color Palette Commands.
+
+
+
 SGB Sound Functions

+SGB Command 08h - SOUND
+Used to start/stop internal sound effect, start/stop sound using +internal tone data.
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1     Sound Effect A (Port 1) Decrescendo 8bit Sound Code
+  2     Sound Effect B (Port 2) Sustain     8bit Sound Code
+  3     Sound Effect Attributes
+          Bit 0-1 - Sound Effect A Pitch  (0..3=Low..High)
+          Bit 2-3 - Sound Effect A Volume (0..2=High..Low, 3=Mute on)
+          Bit 4-5 - Sound Effect B Pitch  (0..3=Low..High)
+          Bit 6-7 - Sound Effect B Volume (0..2=High..Low, 3=Not used)
+  4     Music Score Code (must be zero if not used)
+  5-F   Not used (zero)
+
See Sound Effect Tables below for a list of available pre-defined effects.
+"Notes"
+1) Mute is only active when both bits D2 and D3 are 1.
+2) When the volume is set for either Sound Effect A or Sound Effect B, +mute is turned off.
+3) When Mute on/off has been executed, the sound fades out/fades in.
+4) Mute on/off operates on the (BGM) which is reproduced by Sound Effect +A, Sound Effect B, and the Super NES APU. A "mute off" flag does not +exist by itself. When mute flag is set, volume and pitch of Sound Effect +A (port 1) and Sound Effect B (port 2) must be set.
+
+SGB Command 09h - SOU_TRN
+Used to transfer sound code or data to SNES Audio Processing Unit memory +(APU-RAM).
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1-F   Not used (zero)
+
The sound code/data is sent by VRAM-Transfer (4 KBytes).
+
  000      One (or two ???) 16bit expression(s ???) indicating the
+           transfer destination address and transfer length.
+  ...-...  Transfer Data
+  ...-FFF  Remaining bytes not used
+
Possible destinations in APU-RAM are:
+
  0400h-2AFFh  APU-RAM Program Area (9.75KBytes)
+  2B00h-4AFFh  APU-RAM Sound Score Area (8Kbytes)
+  4DB0h-EEFFh  APU-RAM Sampling Data Area (40.25 Kbytes)
+
This function may be used to take control of the SNES sound chip, and/or +to access the SNES MIDI engine. In either case it requires deeper +knowledge of SNES sound programming.
+
+SGB Sound Effect A/B Tables
+Below lists the digital sound effects that are pre-defined in the +SGB/SNES BIOS, and which can be used with the SGB "SOUND" Command.
+Effect A and B may be simultaneously reproduced.
+The P-column indicates the recommended Pitch value, the V-column +indicates the numbers of Voices used. Sound Effect A uses voices 6,7. +Sound Effect B uses voices 0,1,4,5. Effects that use less voices will +use only the upper voices (eg. 4,5 for Effect B with only two voices).
+
+Sound Effect A Flag Table
+
  Code Description             P V     Code Description             P V
+  00  Dummy flag, re-trigger   - 2     18  Fast Jump                3 1
+  80  Effect A, stop/silent    - 2     19  Jet (rocket) takeoff     0 1
+  01  Nintendo                 3 1     1A  Jet (rocket) landing     0 1
+  02  Game Over                3 2     1B  Cup breaking             2 2
+  03  Drop                     3 1     1C  Glass breaking           1 2
+  04  OK ... A                 3 2     1D  Level UP                 2 2
+  05  OK ... B                 3 2     1E  Insert air               1 1
+  06  Select...A               3 2     1F  Sword swing              1 1
+  07  Select...B               3 1     20  Water falling            2 1
+  08  Select...C               2 2     21  Fire                     1 1
+  09  Mistake...Buzzer         2 1     22  Wall collapsing          1 2
+  0A  Catch Item               2 2     23  Cancel                   1 2
+  0B  Gate squeaks 1 time      2 2     24  Walking                  1 2
+  0C  Explosion...small        1 2     25  Blocking strike          1 2
+  0D  Explosion...medium       1 2     26  Picture floats on & off  3 2
+  0E  Explosion...large        1 2     27  Fade in                  0 2
+  0F  Attacked...A             3 1     28  Fade out                 0 2
+  10  Attacked...B             3 2     29  Window being opened      1 2
+  11  Hit (punch)...A          0 2     2A  Window being closed      0 2
+  12  Hit (punch)...B          0 2     2B  Big Laser                3 2
+  13  Breath in air            3 2     2C  Stone gate closes/opens  0 2
+  14  Rocket Projectile...A    3 2     2D  Teleportation            3 1
+  15  Rocket Projectile...B    3 2     2E  Lightning                0 2
+  16  Escaping Bubble          2 1     2F  Earthquake               0 2
+  17  Jump                     3 1     30  Small Laser              2 2
+
Sound effect A is used for formanto sounds (percussion sounds).
+
+Sound Effect B Flag Table
+
  Code Description             P V     Code Description             P V
+  00  Dummy flag, re-trigger   - 4     0D  Waterfall                2 2
+  80  Effect B, stop/silent    - 4     0E  Small character running  3 1
+  01  Applause...small group   2 1     0F  Horse running            3 1
+  02  Applause...medium group  2 2     10  Warning sound            1 1
+  03  Applause...large group   2 4     11  Approaching car          0 1
+  04  Wind                     1 2     12  Jet flying               1 1
+  05  Rain                     1 1     13  UFO flying               2 1
+  06  Storm                    1 3     14  Electromagnetic waves    0 1
+  07  Storm with wind/thunder  2 4     15  Score UP                 3 1
+  08  Lightning                0 2     16  Fire                     2 1
+  09  Earthquake               0 2     17  Camera shutter, formanto 3 4
+  0A  Avalanche                0 2     18  Write, formanto          0 1
+  0B  Wave                     0 1     19  Show up title, formanto  0 1
+  0C  River                    3 2
+
Sound effect B is mainly used for looping sounds (sustained sounds).
+
+
+
 SGB System Control Commands

+SGB Command 17h - MASK_EN
+Used to mask the gameboy window, among others this can be used to freeze +the gameboy screen before transferring data through VRAM (the SNES then +keeps displaying the gameboy screen, even though VRAM doesn't contain +meaningful display information during the transfer).
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1     Gameboy Screen Mask (0-3)
+          0  Cancel Mask   (Display activated)
+          1  Freeze Screen (Keep displaying current picture)
+          2  Blank Screen  (Black)
+          3  Blank Screen  (Color 0)
+  2-F   Not used (zero)
+
Freezing works only if the SNES has stored a picture, ie. if necessary +wait one or two frames before freezing (rather than freezing directly +after having displayed the picture).
+The Cancel Mask function may be also invoked (optionally) by completion +of PAL_SET and ATTR_SET commands.
+
+SGB Command 0Ch - ATRC_EN
+Used to enable/disable Attraction mode. It is totally unclear what an +attraction mode is ???, but it is enabled by default.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     Attraction Disable  (0=Enable, 1=Disable)
+  2-F   Not used (zero)
+

+SGB Command 0Dh - TEST_EN
+Used to enable/disable test mode for "SGB-CPU variable clock speed +function". This function is disabled by default.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     Test Mode Enable    (0=Disable, 1=Enable)
+  2-F   Not used (zero)
+
Maybe intended to determine whether SNES operates at 50Hz or 60Hz +display refresh rate ??? Possibly result can be read-out from joypad +register ???
+
+SGB Command 0Eh - ICON_EN
+Used to enable/disable ICON function. Possibly meant to enable/disable +SGB/SNES popup menues which might otherwise activated during gameboy +game play. By default all functions are enabled (0).
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     Disable Bits
+          Bit 0 - Use of SGB-Built-in Color Palettes    (1=Disable)
+          Bit 1 - Controller Set-up Screen    (0=Enable, 1=Disable)
+          Bit 2 - SGB Register File Transfer (0=Receive, 1=Disable)
+          Bit 3-6 - Not used (zero)
+  2-F   Not used (zero)
+
Above Bit 2 will suppress all further packets/commands when set, this +might be useful when starting a monochrome game from inside of the +SGB-menu of a multi-gamepak which contains a collection of different +games.
+
+SGB Command 0Fh - DATA_SND
+Used to write one or more bytes directly into SNES Work RAM.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     SNES Destination Address, low
+  2     SNES Destination Address, high
+  3     SNES Destination Address, bank number
+  4     Number of bytes to write (01h-0Bh)
+  5     Data Byte #1
+  6     Data Byte #2 (if any)
+  7     Data Byte #3 (if any)
+  etc.
+
Unused bytes at the end of the packet should be set to zero, this +function is restricted to a single packet, so that not more than 11 +bytes can be defined at once.
+Free Addresses in SNES memory are Bank 0 1800h-1FFFh, Bank 7Fh +0000h-FFFFh.
+
+SGB Command 10h - DATA_TRN
+Used to transfer binary code or data directly into SNES RAM.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     SNES Destination Address, low
+  2     SNES Destination Address, high
+  3     SNES Destination Address, bank number
+  4-F   Not used (zero)
+
The data is sent by VRAM-Transfer (4 KBytes).
+
  000-FFF  Data
+
Free Addresses in SNES memory are Bank 0 1800h-1FFFh, Bank 7Fh +0000h-FFFFh. The transfer length is fixed at 4KBytes ???, so that directly +writing to the free 2KBytes at 0:1800h would be a not so good idea ???
+
+SGB Command 12h - JUMP
+Used to set the SNES program counter to a specified address. Optionally, +it may be used to set a new address for the SNES NMI handler, the NMI +handler remains unchanged if all bytes 4-6 are zero.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     SNES Program Counter, low
+  2     SNES Program Counter, high
+  3     SNES Program Counter, bank number
+  4     SNES NMI Handler, low
+  5     SNES NMI Handler, high
+  6     SNES NMI Handler, bank number
+  7-F   Not used, zero
+
Note: The game "Space Invaders 94" uses this function when selecting +"Arcade mode" to execute SNES program code which has been previously +transferred from the SGB to the SNES. The type of the CPU which is used +in the SNES is unknown ???
+
+
+
 SGB Multiplayer Command

+SGB Command 11h - MLT_REQ
+Used to request multiplayer mode (ie. input from more than one joypad).
+Because this function provides feedback from the SGB/SNES to the gameboy +program, it is also used to detect SGB hardware.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     Multiplayer Control (0-3) (Bit0=Enable, Bit1=Two/Four Players)
+          0 = One player
+          1 = Two players
+          3 = Four players
+  2-F   Not used (zero)
+
In one player mode, the second joypad (if any) is used for the SGB +system program. In two player mode, both joypads are used for the game. +Because SNES have only two joypad sockets, four player mode requires an +external "Multiplayer 5" adapter.
+
+Reading Multiple Controllers (Joypads)
+When having enabled multiple controllers by MLT_REQ, data for each +joypad can be read out through JOYPAD register (FF00) as follows: First +set P14 and P15 both HIGH (deselect both Buttons and Cursor keys), you +can now read the lower 4bits of FF00 which indicate the joypad ID for +the following joypad input:
+
  0Fh  Joypad 1
+  0Eh  Joypad 2
+  0Dh  Joypad 3
+  0Ch  Joypad 4
+
Next, set P14 and P15 low (one after each other) to select Buttons and +Cursor lines, and read-out joypad state as normally. When completed, set +P14 and P15 back HIGH, this automatically increments the joypad number +(or restarts counting once reached the lastmost joypad). Repeat the +procedure until you have read-out states for all two (or four) joypads.
+
+
+
 SGB Border and OBJ Commands

+SGB Command 13h - CHR_TRN
+Used to transfer tile data (characters) to SNES Tile memory in VRAM. This +normally used to define BG tiles for the SGB Border (see PCT_TRN), but +might be also used to define moveable SNES foreground sprites (see +OBJ_TRN).
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1     Tile Transfer Destination
+          Bit 0   - Tile Numbers   (0=Tiles 00h-7Fh, 1=Tiles 80h-FFh)
+          Bit 1   - Tile Type      (0=BG Tiles, 1=OBJ Tiles)
+          Bit 2-7 - Not used (zero)
+  2-F   Not used (zero)
+
The tile data is sent by VRAM-Transfer (4 KBytes).
+
  000-FFF  Bitmap data for 128 Tiles
+
Each tile occupies 16bytes (8x8 pixels, 16 colors each).
+When intending to transfer more than 128 tiles, call this function twice +(once for tiles 00h-7Fh, and once for tiles 80h-FFh). Note: The BG/OBJ +Bit seems to have no effect and writes to the same VRAM addresses for +both BG and OBJ ???
+
+SGB Command 14h - PCT_TRN
+Used to transfer tile map data and palette data to SNES BG Map memory in +VRAM to be used for the SGB border. The actual tiles must be separately +transferred by using the CHR_TRN function.
+
  Byte  Content
+  0     Command*8+Length    (fixed length=1)
+  1-F   Not used (zero)
+
The map data is sent by VRAM-Transfer (4 KBytes).
+
  000-7FF  BG Map 32x32 Entries of 16bit each (2048 bytes)
+  800-87F  BG Palette Data (Palettes 4-7, each 16 colors of 16bits each)
+  880-FFF  Not used, don't care
+
Each BG Map Entry consists of a 16bit value as such:
+
  Bit 0-9   - Character Number (use only 00h-FFh, upper 2 bits zero)
+  Bit 10-12 - Palette Number   (use only 4-7, officially use only 4-6)
+  Bit 13    - BG Priority      (use only 0)
+  Bit 14    - X-Flip           (0=Normal, 1=Mirror horizontally)
+  Bit 15    - Y-Flip           (0=Normal, 1=Mirror vertically)
+
Even though 32x32 map entries are transferred, only upper 32x28 are +actually used (256x224 pixels, SNES screen size). The 20x18 entries in +the center of the 32x28 area should be set to 0000h as transparent space +for the gameboy window to be displayed inside. Reportedly, +non-transparent border data will cover the gameboy window.
+
+SGB Command 18h - OBJ_TRN
+Used to transfer OBJ attributes to SNES OAM memory. Unlike all other +functions with the ending _TRN, this function does not use the usual +one-shot 4KBytes VRAM transfer method.
+Instead, when enabled (below execute bit set), data is permanently (each +frame) read out from the lower character line of the gameboy screen. To +suppress garbage on the display, the lower line is masked, and only the +upper 20x17 characters of the gameboy window are used - the masking +method is unknwon - frozen, black, or recommended to be covered by the +SGB border, or else ??? Also, when the function is enabled, "system +attract mode is not performed" - whatever that means ???
+
  Byte  Content
+  0     Command*8+Length (fixed length=1)
+  1     Control Bits
+          Bit 0   - SNES OBJ Mode enable (0=Cancel, 1=Enable)
+          Bit 1   - Change OBJ Color     (0=No, 1=Use definitions below)
+          Bit 2-7 - Not used (zero)
+  2-3   System Color Palette Number for OBJ Palette 4 (0-511)
+  4-5   System Color Palette Number for OBJ Palette 5 (0-511)
+  6-7   System Color Palette Number for OBJ Palette 6 (0-511)
+  8-9   System Color Palette Number for OBJ Palette 7 (0-511)
+          These color entries are ignored if above Control Bit 1 is zero.
+          Because each OBJ palette consists of 16 colors, four system
+          palette entries (of 4 colors each) are transferred into each
+          OBJ palette. The system palette numbers are not required to be
+          aligned to a multiple of four, and will wrap to palette number
+          0 when exceeding 511. For example, a value of 511 would copy
+          system palettes 511, 0, 1, 2 to the SNES OBJ palette.
+  A-F   Not used (zero)
+
The recommended method is to "display" gameboy BG tiles F9h..FFh from +left to right as first 7 characters of the bottom-most character line of +the gameboy screen. As for normal 4KByte VRAM transfers, this area +should not be scrolled, should not be overlapped by gameboy OBJs, and +the gameboy BGP palette register should be set up properly. By following +that method, SNES OAM data can be defined in the 70h bytes of the +gameboy BG tile memory at following addresses:
+
  8F90-8FEF  SNES OAM, 24 Entries of 4 bytes each (96 bytes)
+  8FF0-8FF5  SNES OAM MSBs, 24 Entries of 2 bits each (6 bytes)
+  8FF6-8FFF  Not used, don't care (10 bytes)
+
The format of SNES OAM Entries is:
+
  Byte 0  OBJ X-Position (0-511, MSB is separately stored, see below)
+  Byte 1  OBJ Y-Position (0-255)
+  Byte 2-3  Attributes (16bit)
+    Bit 0-8    Tile Number     (use only 00h-FFh, upper bit zero)
+    Bit 9-11   Palette Number  (use only 4-7)
+    Bit 12-13  OBJ Priority    (use only 3)
+    Bit 14     X-Flip          (0=Normal, 1=Mirror horizontally)
+    Bit 15     Y-Flip          (0=Normal, 1=Mirror vertically)
+
The format of SNES OAM MSB Entries is:
+
  Actually, the format is unknown ??? However, 2 bits are used per entry:
+  One bit is the most significant bit of the OBJ X-Position.
+  The other bit specifies the OBJ size (8x8 or 16x16 pixels).
+

+
+
 CPU Registers and Flags

+Registers
+
  16bit Hi   Lo   Name/Function
+  AF    A    -    Accumulator & Flags
+  BC    B    C    BC
+  DE    D    E    DE
+  HL    H    L    HL
+  SP    -    -    Stack Pointer
+  PC    -    -    Program Counter/Pointer
+
As shown above, most registers can be accessed either as one 16bit +register, or as two separate 8bit registers.
+
+The Flag Register (lower 8bit of AF register)
+
  Bit  Name  Set Clr  Expl.
+  7    zf    Z   NZ   Zero Flag
+  6    n     -   -    Add/Sub-Flag (BCD)
+  5    h     -   -    Half Carry Flag (BCD)
+  4    cy    C   NC   Carry Flag
+  3-0  -     -   -    Not used (always zero)
+
Conatins the result from the recent instruction which has affected +flags.
+
+The Zero Flag (Z)
+This bit becomes set (1) if the result of an operation has been zero +(0). Used for conditional jumps.
+
+The Carry Flag (C, or Cy)
+Becomes set when the result of an addition became bigger than FFh (8bit) +or FFFFh (16bit). Or when the result of a subtraction or comparision +became less than zero (much as for Z80 and 80x86 CPUs, but unlike as for +65XX and ARM CPUs). Also the flag becomes set when a rotate/shift +operation has shifted-out a "1"-bit.
+Used for conditional jumps, and for instructions such like ADC, SBC, RL, +RLA, etc.
+
+The BCD Flags (N, H)
+These flags are (rarely) used for the DAA instruction only, N Indicates +whether the previous instruction has been an addition or subtraction, +and H indicates carry for lower 4bits of the result, also for DAA, the C +flag must indicate carry for upper 8bits.
+After adding/subtracting two BCD numbers, DAA is intended to convert the +result into BCD format; BCD numbers are ranged from 00h to 99h rather +than 00h to FFh.
+Because C and H flags must contain carry-outs for each digit, DAA cannot +be used for 16bit operations (which have 4 digits), or for INC/DEC +operations (which do not affect C-flag).
+
+
+
 CPU Instruction Set

+Tables below specify the mnemonic, opcode bytes, clock cycles, affected +flags (ordered as znhc), and explanatation.
+The timings assume a CPU clock frequency of 4.194304 MHz (or 8.4
+MHz for CGB in double speed mode), as all gameboy timings are divideable
+by 4, many people specify timings and clock frequency divided by 4.
+
+GMB 8bit-Loadcommands
+
  ld   r,r         xx         4 ---- r=r
+  ld   r,n         xx nn      8 ---- r=n
+  ld   r,(HL)      xx         8 ---- r=(HL)
+  ld   (HL),r      7x         8 ---- (HL)=r
+  ld   (HL),n      36 nn     12 ----
+  ld   A,(BC)      0A         8 ----
+  ld   A,(DE)      1A         8 ----
+  ld   A,(nn)      FA        16 ----
+  ld   (BC),A      02         8 ----
+  ld   (DE),A      12         8 ----
+  ld   (nn),A      EA        16 ----
+  ld   A,(FF00+n)  F0 nn     12 ---- read from io-port n (memory FF00+n)
+  ld   (FF00+n),A  E0 nn     12 ---- write to io-port n (memory FF00+n)
+  ld   A,(FF00+C)  F2         8 ---- read from io-port C (memory FF00+C)
+  ld   (FF00+C),A  E2         8 ---- write to io-port C (memory FF00+C)
+  ldi  (HL),A      22         8 ---- (HL)=A, HL=HL+1
+  ldi  A,(HL)      2A         8 ---- A=(HL), HL=HL+1
+  ldd  (HL),A      32         8 ---- (HL)=A, HL=HL-1
+  ldd  A,(HL)      3A         8 ---- A=(HL), HL=HL-1
+

+GMB 16bit-Loadcommands
+
  ld   rr,nn       x1 nn nn  12 ---- rr=nn (rr may be BC,DE,HL or SP)
+  ld   SP,HL       F9         8 ---- SP=HL
+  push rr          x5        16 ---- SP=SP-2  (SP)=rr   (rr may be BC,DE,HL,AF)
+  pop  rr          x1        12 (AF) rr=(SP)  SP=SP+2   (rr may be BC,DE,HL,AF)
+

+GMB 8bit-Arithmetic/logical Commands
+
  add  A,r         8x         4 z0hc A=A+r
+  add  A,n         C6 nn      8 z0hc A=A+n
+  add  A,(HL)      86         8 z0hc A=A+(HL)
+  adc  A,r         8x         4 z0hc A=A+r+cy
+  adc  A,n         CE nn      8 z0hc A=A+n+cy
+  adc  A,(HL)      8E         8 z0hc A=A+(HL)+cy
+  sub  r           9x         4 z1hc A=A-r
+  sub  n           D6 nn      8 z1hc A=A-n
+  sub  (HL)        96         8 z1hc A=A-(HL)
+  sbc  A,r         9x         4 z1hc A=A-r-cy
+  sbc  A,n         DE nn      8 z1hc A=A-n-cy
+  sbc  A,(HL)      9E         8 z1hc A=A-(HL)-cy
+  and  r           Ax         4 z010 A=A & r
+  and  n           E6 nn      8 z010 A=A & n
+  and  (HL)        A6         8 z010 A=A & (HL)
+  xor  r           Ax         4 z000
+  xor  n           EE nn      8 z000
+  xor  (HL)        AE         8 z000
+  or   r           Bx         4 z000 A=A | r
+  or   n           F6 nn      8 z000 A=A | n
+  or   (HL)        B6         8 z000 A=A | (HL)
+  cp   r           Bx         4 z1hc compare A-r
+  cp   n           FE nn      8 z1hc compare A-n
+  cp   (HL)        BE         8 z1hc compare A-(HL)
+  inc  r           xx         4 z0h- r=r+1
+  inc  (HL)        34        12 z0h- (HL)=(HL)+1
+  dec  r           xx         4 z1h- r=r-1
+  dec  (HL)        35        12 z1h- (HL)=(HL)-1
+  daa              27         4 z-0x decimal adjust akku
+  cpl              2F         4 -11- A = A xor FF
+

+GMB 16bit-Arithmetic/logical Commands
+
  add  HL,rr     x9           8 -0hc HL = HL+rr     ;rr may be BC,DE,HL,SP
+  inc  rr        x3           8 ---- rr = rr+1      ;rr may be BC,DE,HL,SP
+  dec  rr        xB           8 ---- rr = rr-1      ;rr may be BC,DE,HL,SP
+  add  SP,dd     E8          16 00hc SP = SP +/- dd ;dd is 8bit signed number
+  ld   HL,SP+dd  F8          12 00hc HL = SP +/- dd ;dd is 8bit signed number
+

+GMB Rotate- und Shift-Commands
+
  rlca           07           4 000c rotate akku left
+  rla            17           4 000c rotate akku left through carry
+  rrca           0F           4 000c rotate akku right
+  rra            1F           4 000c rotate akku right through carry
+  rlc  r         CB 0x        8 z00c rotate left
+  rlc  (HL)      CB 06       16 z00c rotate left
+  rl   r         CB 1x        8 z00c rotate left through carry
+  rl   (HL)      CB 16       16 z00c rotate left through carry
+  rrc  r         CB 0x        8 z00c rotate right
+  rrc  (HL)      CB 0E       16 z00c rotate right
+  rr   r         CB 1x        8 z00c rotate right through carry
+  rr   (HL)      CB 1E       16 z00c rotate right through carry
+  sla  r         CB 2x        8 z00c shift left arithmetic (b0=0)
+  sla  (HL)      CB 26       16 z00c shift left arithmetic (b0=0)
+  swap r         CB 3x        8 z000 exchange low/hi-nibble
+  swap (HL)      CB 36       16 z000 exchange low/hi-nibble
+  sra  r         CB 2x        8 z00c shift right arithmetic (b7=b7)
+  sra  (HL)      CB 2E       16 z00c shift right arithmetic (b7=b7)
+  srl  r         CB 3x        8 z00c shift right logical (b7=0)
+  srl  (HL)      CB 3E       16 z00c shift right logical (b7=0)
+

+GMB Singlebit Operation Commands
+
  bit  n,r       CB xx        8 z01- test bit n
+  bit  n,(HL)    CB xx       12 z01- test bit n
+  set  n,r       CB xx        8 ---- set bit n
+  set  n,(HL)    CB xx       16 ---- set bit n
+  res  n,r       CB xx        8 ---- reset bit n
+  res  n,(HL)    CB xx       16 ---- reset bit n
+

+GMB CPU-Controlcommands
+
  ccf            3F           4 -00c cy=cy xor 1
+  scf            37           4 -001 cy=1
+  nop            00           4 ---- no operation
+  halt           76         N*4 ---- halt until interrupt occurs (low power)
+  stop           10 00        ? ---- low power standby mode (VERY low power)
+  di             F3           4 ---- disable interrupts, IME=0
+  ei             FB           4 ---- enable interrupts, IME=1
+

+GMB Jumpcommands
+
  jp   nn        C3 nn nn    16 ---- jump to nn, PC=nn
+  jp   HL        E9           4 ---- jump to HL, PC=HL
+  jp   f,nn      xx nn nn 16;12 ---- conditional jump if nz,z,nc,c
+  jr   PC+dd     18 dd       12 ---- relative jump to nn (PC=PC+/-7bit)
+  jr   f,PC+dd   xx dd     12;8 ---- conditional relative jump if nz,z,nc,c
+  call nn        CD nn nn    24 ---- call to nn, SP=SP-2, (SP)=PC, PC=nn
+  call f,nn      xx nn nn 24;12 ---- conditional call if nz,z,nc,c
+  ret            C9          16 ---- return, PC=(SP), SP=SP+2
+  ret  f         xx        20;8 ---- conditional return if nz,z,nc,c
+  reti           D9          16 ---- return and enable interrupts (IME=1)
+  rst  n         xx          16 ---- call to 00,08,10,18,20,28,30,38
+

+
+
 CPU Comparision with Z80

+Comparision with 8080
+Basically, the gameboy CPU works more like an older 8080 CPU rather than +like a more powerful Z80 CPU. It is, however, supporting CB-prefixed +instructions. Also, all known gameboy assemblers using the more obvious +Z80-style syntax, rather than the chaotic 8080-style syntax.
+
+Comparision with Z80
+Any DD-, ED-, and FD-prefixed instructions are missing, that means no +IX-, IY-registers, no block commands, and some other missing commands.
+All exchange instructions have been removed (including total absence of +second register set), 16bit memory accesses are mostly missing, and +16bit arithmetic functions are heavily cut-down.
+The gameboy has no IN/OUT instructions, instead I/O ports are accessed +directly by normal LD instructions, or by special LD (FF00+n) opcodes.
+The sign and parity/overflow flags have been removed.
+The gameboy operates approximately as fast as a 4MHz Z80 (8MHz in CGB +double speed mode), execution time of all instructions has been rounded +up to a multiple of 4 cycles though.
+
+Moved, Removed, and Added Opcodes
+
  Opcode  Z80             GMB
+  ---------------------------------------
+  08      EX   AF,AF      LD   (nn),SP
+  10      DJNZ PC+dd      STOP
+  22      LD   (nn),HL    LDI  (HL),A
+  2A      LD   HL,(nn)    LDI  A,(HL)
+  32      LD   (nn),A     LDD  (HL),A
+  3A      LD   A,(nn)     LDD  A,(HL)
+  D3      OUT  (n),A      -
+  D9      EXX             RETI
+  DB      IN   A,(n)      -
+  DD      <IX>            -
+  E0      RET  PO         LD   (FF00+n),A
+  E2      JP   PO,nn      LD   (FF00+C),A
+  E3      EX   (SP),HL    -
+  E4      CALL P0,nn      -
+  E8      RET  PE         ADD  SP,dd
+  EA      JP   PE,nn      LD   (nn),A
+  EB      EX   DE,HL      -
+  EC      CALL PE,nn      -
+  ED      <pref>          -
+  F0      RET  P          LD   A,(FF00+n)
+  F2      JP   P,nn       LD   A,(FF00+C)
+  F4      CALL P,nn       -
+  F8      RET  M          LD   HL,SP+dd
+  FA      JP   M,nn       LD   A,(nn)
+  FC      CALL M,nn       -
+  FD      <IY>            -
+  CB3X    SLL  r/(HL)     SWAP r/(HL)
+
Note: The unused (-) opcodes will lock-up the gameboy CPU when used.
+
+
+
 The Cartridge Header

+An internal information area is located at 0100-014F in
+each cartridge. It contains the following values:
+
+0100-0103 - Entry Point
+After displaying the Nintendo Logo, the built-in boot procedure jumps to +this address (100h), which should then jump to the actual main program +in the cartridge. Usually this 4 byte area contains a NOP instruction, +followed by a JP 0150h instruction. But not always.
+
+0104-0133 - Nintendo Logo
+These bytes define the bitmap of the Nintendo logo that is displayed +when the gameboy gets turned on. The hexdump of this bitmap is:
+
  CE ED 66 66 CC 0D 00 0B 03 73 00 83 00 0C 00 0D
+  00 08 11 1F 88 89 00 0E DC CC 6E E6 DD DD D9 99
+  BB BB 67 63 6E 0E EC CC DD DC 99 9F BB B9 33 3E
+
The gameboys boot procedure verifies the content of this bitmap (after +it has displayed it), and LOCKS ITSELF UP if these bytes are incorrect. +A CGB verifies only the first 18h bytes of the bitmap, but others (for +example a pocket gameboy) verify all 30h bytes.
+
+0134-0143 - Title
+Title of the game in UPPER CASE ASCII. If it is less than 16 characters +then the remaining bytes are filled with 00's. When inventing the CGB, +Nintendo has reduced the length of this area to 15 characters, and some +months later they had the fantastic idea to reduce it to 11 characters +only. The new meaning of the ex-title bytes is described below.
+
+013F-0142 - Manufacturer Code
+In older cartridges this area has been part of the Title (see above), in +newer cartridges this area contains an 4 character uppercase +manufacturer code. Purpose and Deeper Meaning unknown.
+
+0143 - CGB Flag
+In older cartridges this byte has been part of the Title (see above). In +CGB cartridges the upper bit is used to enable CGB functions. This is +required, otherwise the CGB switches itself into Non-CGB-Mode. Typical +values are:
+
  80h - Game supports CGB functions, but works on old gameboys also.
+  C0h - Game works on CGB only (physically the same as 80h).
+
Values with Bit 7 set, and either Bit 2 or 3 set, will switch the +gameboy into a special non-CGB-mode with uninitialized palettes. Purpose +unknown, eventually this has been supposed to be used to colorize +monochrome games that include fixed palette data at a special location +in ROM.
+
+0144-0145 - New Licensee Code
+Specifies a two character ASCII licensee code, indicating the company or +publisher of the game. These two bytes are used in newer games only +(games that have been released after the SGB has been invented). Older +games are using the header entry at 014B instead.
+
+0146 - SGB Flag
+Specifies whether the game supports SGB functions, common values are:
+
  00h = No SGB functions (Normal Gameboy or CGB only game)
+  03h = Game supports SGB functions
+
The SGB disables its SGB functions if this byte is set to another value +than 03h.
+
+0147 - Cartridge Type
+Specifies which Memory Bank Controller (if any) is used in the +cartridge, and if further external hardware exists in the cartridge.
+
  00h  ROM ONLY                 13h  MBC3+RAM+BATTERY
+  01h  MBC1                     15h  MBC4
+  02h  MBC1+RAM                 16h  MBC4+RAM
+  03h  MBC1+RAM+BATTERY         17h  MBC4+RAM+BATTERY
+  05h  MBC2                     19h  MBC5
+  06h  MBC2+BATTERY             1Ah  MBC5+RAM
+  08h  ROM+RAM                  1Bh  MBC5+RAM+BATTERY
+  09h  ROM+RAM+BATTERY          1Ch  MBC5+RUMBLE
+  0Bh  MMM01                    1Dh  MBC5+RUMBLE+RAM
+  0Ch  MMM01+RAM                1Eh  MBC5+RUMBLE+RAM+BATTERY
+  0Dh  MMM01+RAM+BATTERY        FCh  POCKET CAMERA
+  0Fh  MBC3+TIMER+BATTERY       FDh  BANDAI TAMA5
+  10h  MBC3+TIMER+RAM+BATTERY   FEh  HuC3
+  11h  MBC3                     FFh  HuC1+RAM+BATTERY
+  12h  MBC3+RAM
+

+0148 - ROM Size
+Specifies the ROM Size of the cartridge. Typically calculated as "32KB +shl N".
+
  00h -  32KByte (no ROM banking)
+  01h -  64KByte (4 banks)
+  02h - 128KByte (8 banks)
+  03h - 256KByte (16 banks)
+  04h - 512KByte (32 banks)
+  05h -   1MByte (64 banks)  - only 63 banks used by MBC1
+  06h -   2MByte (128 banks) - only 125 banks used by MBC1
+  07h -   4MByte (256 banks)
+  52h - 1.1MByte (72 banks)
+  53h - 1.2MByte (80 banks)
+  54h - 1.5MByte (96 banks)
+

+0149 - RAM Size
+Specifies the size of the external RAM in the cartridge (if any).
+
  00h - None
+  01h - 2 KBytes
+  02h - 8 Kbytes
+  03h - 32 KBytes (4 banks of 8KBytes each)
+
When using a MBC2 chip 00h must be specified in this entry, even though +the MBC2 includes a built-in RAM of 512 x 4 bits.
+
+014A - Destination Code
+Specifies if this version of the game is supposed to be sold in japan, +or anywhere else. Only two values are defined.
+
  00h - Japanese
+  01h - Non-Japanese
+

+014B - Old Licensee Code
+Specifies the games company/publisher code in range 00-FFh. A value of +33h signalizes that the New License Code in header bytes 0144-0145 is +used instead.
+(Super GameBoy functions won't work if <> $33.)
+
+014C - Mask ROM Version number
+Specifies the version number of the game. That is usually 00h.
+
+014D - Header Checksum
+Contains an 8 bit checksum across the cartridge header bytes 0134-014C. +The checksum is calculated as follows:
+
  x=0:FOR i=0134h TO 014Ch:x=x-MEM[i]-1:NEXT
+
The lower 8 bits of the result must be the same than the value in this +entry. The GAME WON'T WORK if this checksum is incorrect.
+
+014E-014F - Global Checksum
+Contains a 16 bit checksum (upper byte first) across the whole cartridge +ROM. Produced by adding all bytes of the cartridge (except for the two +checksum bytes). The Gameboy doesn't verify this checksum.
+
+
+
 Memory Bank Controllers

+As the gameboys 16 bit address bus offers only limited space for ROM and +RAM addressing, many games are using Memory Bank Controllers (MBCs) to +expand the available address space by bank switching. These MBC chips +are located in the game cartridge (ie. not in the gameboy itself), +several different MBC types are available:
+
+None (32KByte ROM only)
+MBC1 (max 2MByte ROM and/or 32KByte RAM)
+MBC2 (max 256KByte ROM and 512x4 bits RAM)
+MBC3 (max 2MByte ROM and/or 32KByte RAM and Timer)
+HuC1 (MBC with Infrared Controller)
+
+MBC Timing Issues
+
+In each cartridge, the required (or preferred) MBC type should be +specified in byte at 0147h of the ROM. (As described in the chapter +about The Cartridge Header.)
+
+
+
 None (32KByte ROM only)

+Small games of not more than 32KBytes ROM do not require a MBC chip for +ROM banking. The ROM is directly mapped to memory at 0000-7FFFh. +Optionally up to 8KByte of RAM could be connected at A000-BFFF, even +though that could require a tiny MBC-like circuit, but no real MBC chip.
+
+
+
 MBC1 (max 2MByte ROM and/or 32KByte RAM)

+This is the first MBC chip for the gameboy. Any newer MBC chips are +working similiar, so that is relative easy to upgrade a program from one +MBC chip to another - or even to make it compatible to several different +types of MBCs.
+
+Note that the memory in range 0000-7FFF is used for both reading from +ROM, and for writing to the MBCs Control Registers.
+
+0000-3FFF - ROM Bank 00 (Read Only)
+This area always contains the first 16KBytes of the cartridge ROM.
+
+4000-7FFF - ROM Bank 01-7F (Read Only)
+This area may contain any of the further 16KByte banks of the ROM, +allowing to address up to 125 ROM Banks (almost 2MByte). As described +below, bank numbers 20h, 40h, and 60h cannot be used, resulting in the +odd amount of 125 banks.
+
+A000-BFFF - RAM Bank 00-03, if any (Read/Write)
+This area is used to address external RAM in the cartridge (if any). +External RAM is often battery buffered, allowing to store game positions +or high score tables, even if the gameboy is turned off, or if the +cartridge is removed from the gameboy. Available RAM sizes are: 2KByte +(at A000-A7FF), 8KByte (at A000-BFFF), and 32KByte (in form of four 8K +banks at A000-BFFF).
+
+0000-1FFF - RAM Enable (Write Only)
+Before external RAM can be read or written, it must be enabled by +writing to this address space. It is recommended to disable external RAM +after accessing it, in order to protect its contents from damage during +power down of the gameboy. Usually the following values are used:
+
  00h  Disable RAM (default)
+  0Ah  Enable RAM
+
Practically any value with 0Ah in the lower 4 bits enables RAM, and any +other value disables RAM.
+
+2000-3FFF - ROM Bank Number (Write Only)
+Writing to this address space selects the lower 5 bits of the ROM Bank +Number (in range 01-1Fh). When 00h is written, the MBC translates that +to bank 01h also. That doesn't harm so far, because ROM Bank 00h can be +always directly accessed by reading from 0000-3FFF.
+But (when using the register below to specify the upper ROM Bank bits), +the same happens for Bank 20h, 40h, and 60h. Any attempt to address +these ROM Banks will select Bank 21h, 41h, and 61h instead.
+
+4000-5FFF - RAM Bank Number - or - Upper Bits of ROM Bank Number (Write Only) +This 2bit register can be used to select a RAM Bank in range from +00-03h, or to specify the upper two bits (Bit 5-6) of the ROM Bank +number, depending on the current ROM/RAM Mode. (See below.)
+
+6000-7FFF - ROM/RAM Mode Select (Write Only)
+This 1bit Register selects whether the two bits of the above register +should be used as upper two bits of the ROM Bank, or as RAM Bank Number.
+
  00h = ROM Banking Mode (up to 8KByte RAM, 2MByte ROM) (default)
+  01h = RAM Banking Mode (up to 32KByte RAM, 512KByte ROM)
+
The program may freely switch between both modes, the only limitiation +is that only RAM Bank 00h can be used during Mode 0, and only ROM Banks +00-1Fh can be used during Mode 1.
+
+
+
 MBC2 (max 256KByte ROM and 512x4 bits RAM)

+0000-3FFF - ROM Bank 00 (Read Only)
+Same as for MBC1.
+
+4000-7FFF - ROM Bank 01-0F (Read Only)
+Same as for MBC1, but only a total of 16 ROM banks is supported.
+
+A000-A1FF - 512x4bits RAM, built-in into the MBC2 chip (Read/Write)
+The MBC2 doesn't support external RAM, instead it includes 512x4 bits of +built-in RAM (in the MBC2 chip itself). It still requires an external +battery to save data during power-off though.
+As the data consists of 4bit values, only the lower 4 bits of the +"bytes" in this memory area are used.
+
+0000-1FFF - RAM Enable (Write Only)
+The least significant bit of the upper address byte must be zero to +enable/disable cart RAM. For example the following addresses can be used +to enable/disable cart RAM: 0000-00FF, 0200-02FF, 0400-04FF, ..., +1E00-1EFF.
+The suggested address range to use for MBC2 ram enable/disable is +0000-00FF.
+
+2000-3FFF - ROM Bank Number (Write Only)
+Writing a value (XXXXBBBB - X = Don't cares, B = bank select bits) into +2000-3FFF area will select an appropriate ROM bank at 4000-7FFF.
+
+The least significant bit of the upper address byte must be one to +select a ROM bank. For example the following addresses can be used to +select a ROM bank: 2100-21FF, 2300-23FF, 2500-25FF, ..., 3F00-3FFF.
+The suggested address range to use for MBC2 rom bank selection is +2100-21FF.
+
+
+
 MBC3 (max 2MByte ROM and/or 32KByte RAM and Timer)

+Beside for the ability to access up to 2MB ROM (128 banks), and 32KB RAM +(4 banks), the MBC3 also includes a built-in Real Time Clock (RTC). The +RTC requires an external 32.768 kHz Quartz Oscillator, and an external +battery (if it should continue to tick when the gameboy is turned off).
+
+0000-3FFF - ROM Bank 00 (Read Only)
+Same as for MBC1.
+
+4000-7FFF - ROM Bank 01-7F (Read Only)
+Same as for MBC1, except that accessing banks 20h, 40h, and 60h is +supported now.
+
+A000-BFFF - RAM Bank 00-03, if any (Read/Write)
+A000-BFFF - RTC Register 08-0C (Read/Write)
+Depending on the current Bank Number/RTC Register selection (see below), +this memory space is used to access an 8KByte external RAM Bank, or a +single RTC Register.
+
+0000-1FFF - RAM and Timer Enable (Write Only)
+Mostly the same as for MBC1, a value of 0Ah will enable reading and +writing to external RAM - and to the RTC Registers! A value of 00h will +disable either.
+
+2000-3FFF - ROM Bank Number (Write Only)
+Same as for MBC1, except that the whole 7 bits of the RAM Bank Number +are written directly to this address. As for the MBC1, writing a value +of 00h, will select Bank 01h instead. All other values 01-7Fh select the +corresponding ROM Banks.
+
+4000-5FFF - RAM Bank Number - or - RTC Register Select (Write Only)
+As for the MBC1s RAM Banking Mode, writing a value in range for 00h-03h +maps the corresponding external RAM Bank (if any) into memory at +A000-BFFF.
+When writing a value of 08h-0Ch, this will map the corresponding RTC +register into memory at A000-BFFF. That register could then be +read/written by accessing any address in that area, typically that is +done by using address A000.
+
+6000-7FFF - Latch Clock Data (Write Only)
+When writing 00h, and then 01h to this register, the current time +becomes latched into the RTC registers. The latched data will not change +until it becomes latched again, by repeating the write 00h->01h +procedure.
+This is supposed for <reading> from the RTC registers. It is proof to +read the latched (frozen) time from the RTC registers, while the clock +itself continues to tick in background.
+
+The Clock Counter Registers
+
  08h  RTC S   Seconds   0-59 (0-3Bh)
+  09h  RTC M   Minutes   0-59 (0-3Bh)
+  0Ah  RTC H   Hours     0-23 (0-17h)
+  0Bh  RTC DL  Lower 8 bits of Day Counter (0-FFh)
+  0Ch  RTC DH  Upper 1 bit of Day Counter, Carry Bit, Halt Flag
+        Bit 0  Most significant bit of Day Counter (Bit 8)
+        Bit 6  Halt (0=Active, 1=Stop Timer)
+        Bit 7  Day Counter Carry Bit (1=Counter Overflow)
+
The Halt Flag is supposed to be set before <writing> to the RTC +Registers.
+
+The Day Counter
+The total 9 bits of the Day Counter allow to count days in range from +0-511 (0-1FFh). The Day Counter Carry Bit becomes set when this value +overflows. In that case the Carry Bit remains set until the program does +reset it.
+Note that you can store an offset to the Day Counter in battery RAM. For +example, every time you read a non-zero Day Counter, add this Counter to +the offset in RAM, and reset the Counter to zero. This method allows to +count any number of days, making your program Year-10000-Proof, provided +that the cartridge gets used at least every 511 days.
+
+Delays
+When accessing the RTC Registers it is recommended to execute a 4ms +delay (4 Cycles in Normal Speed Mode) between the separate accesses.
+
+
+
 HuC1 (MBC with Infrared Controller)

+This controller (made by Hudson Soft) appears to be very similar to an +MBC1 with the main difference being that it supports infrared LED input +/ output. (Similiar to the infrared port that has been later invented in +CGBs.)
+
+The Japanese cart "Fighting Phoenix" (internal cart name: SUPER B DAMAN) +is known to contain this chip.
+
+
+
 MBC Timing Issues

+Using MBCs with CGB Double Speed Mode
+The MBC5 has been designed to support CGB Double Speed Mode.
+There have been rumours that older MBCs (like MBC1-3) wouldn't be fast +enough in that mode. If so, it might be nethertheless possible to use +Double Speed during periods which use only code and data which is +located in internal RAM.
+However, despite of the above, my own good old selfmade MBC1-EPROM card +appears to work stable and fine even in Double Speed Mode though.
+
+
+
 Gamegenie/Shark Cheats

+Game Shark and Gamegenie are external cartridge adapters that can be +plugged between the gameboy and the actual game cartridge. Hexadecimal +codes can be then entered for specific games, typically providing things +like Infinite Sex, 255 Cigarettes, or Starting directly in Wonderland +Level PRO, etc.
+
+Gamegenie (ROM patches)
+Gamegenie codes consist of nine-digit hex numbers, formatted as +ABC-DEF-GHI, the meaning of the separate digits is:
+
  AB    New data
+  FCDE  Memory address, XORed by 0F000h
+  GI    Old data, XORed by 0BAh and rotated left by two
+  H     Don't know, maybe checksum and/or else
+
The address should be located in ROM area 0000h-7FFFh, the adapter +permanently compares address/old data with address/data being read by +the game, and replaces that data by new data if necessary. That method +(more or less) prohibits unwanted patching of wrong memory banks. +Eventually it is also possible to patch external RAM ?
+Newer devices reportedly allow to specify only the first six digits +(optionally). As far as I rememeber, around three or four codes can be +used simultaneously.
+
+Game Shark (RAM patches)
+Game Shark codes consist of eight-digit hex numbers, formatted as +ABCDEFGH, the meaning of the separate digits is:
+
  AB    External RAM bank number
+  CD    New Data
+  GHEF  Memory Address (internal or external RAM, A000-DFFF)
+
As far as I understand, patching is implement by hooking the original +VBlank interrupt handler, and re-writing RAM values each frame. The +downside is that this method steals some CPU time, also, it cannot be +used to patch program code in ROM.
+As far as I rememeber, somewhat 10-25 codes can be used simultaneously.
+
+
+
 Power Up Sequence

+When the GameBoy is powered up, a 256 byte program starting at memory +location 0 is executed. This program is located in a ROM inside the +GameBoy. The first thing the program does is read the cartridge +locations from $104 to $133 and place this graphic of a Nintendo logo on +the screen at the top. This image is then scrolled until it is in the +middle of the screen. Two musical notes are then played on the internal +speaker. Again, the cartridge locations $104 to $133 are read but this +time they are compared with a table in the internal rom. If any byte +fails to compare, then the GameBoy stops comparing bytes and simply +halts all operations. If all locations compare the same, then the +GameBoy starts adding all of the bytes in the cartridge from $134 to +$14d. A value of 25 decimal is added to this total. If the least +significant byte of the result is a not a zero, then the GameBoy will +stop doing anything. If it is a zero, then the internal ROM is disabled +and cartridge program execution begins at location $100 with the +following register values:
+
+
   AF=$01B0
+   BC=$0013
+   DE=$00D8
+   HL=$014D
+   Stack Pointer=$FFFE
+   [$FF05] = $00   ; TIMA
+   [$FF06] = $00   ; TMA
+   [$FF07] = $00   ; TAC
+   [$FF10] = $80   ; NR10
+   [$FF11] = $BF   ; NR11
+   [$FF12] = $F3   ; NR12
+   [$FF14] = $BF   ; NR14
+   [$FF16] = $3F   ; NR21
+   [$FF17] = $00   ; NR22
+   [$FF19] = $BF   ; NR24
+   [$FF1A] = $7F   ; NR30
+   [$FF1B] = $FF   ; NR31
+   [$FF1C] = $9F   ; NR32
+   [$FF1E] = $BF   ; NR33
+   [$FF20] = $FF   ; NR41
+   [$FF21] = $00   ; NR42
+   [$FF22] = $00   ; NR43
+   [$FF23] = $BF   ; NR30
+   [$FF24] = $77   ; NR50
+   [$FF25] = $F3   ; NR51
+   [$FF26] = $F1-GB, $F0-SGB ; NR52
+   [$FF40] = $91   ; LCDC
+   [$FF42] = $00   ; SCY
+   [$FF43] = $00   ; SCX
+   [$FF45] = $00   ; LYC
+   [$FF47] = $FC   ; BGP
+   [$FF48] = $FF   ; OBP0
+   [$FF49] = $FF   ; OBP1
+   [$FF4A] = $00   ; WY
+   [$FF4B] = $00   ; WX
+   [$FFFF] = $00   ; IE
+

+It is not a good idea to assume the above values will always exist. A +later version GameBoy could contain different values than these at +reset. Always set these registers on reset rather than assume they are +as above.
+
+Please note that GameBoy internal RAM on power up contains random data. +All of the GameBoy emulators tend to set all RAM to value $00 on entry.
+
+Cart RAM the first time it is accessed on a real GameBoy contains random +data. It will only contain known data if the GameBoy code initializes it +to some value.
+
+
+
 Reducing Power Consumption

+The following can be used to recude the power consumption of the +gameboy, and to extend the life of the batteries.
+
+PWR Using the HALT Instruction
+PWR Using the STOP Instruction
+PWR Disabeling the Sound Controller
+PWR Not using CGB Double Speed Mode
+PWR Using the Skills
+
+
+
 PWR Using the HALT Instruction

+It is recommended that the HALT instruction be used whenever possible to +reduce power consumption & extend the life of the batteries. This +command stops the system clock reducing the power consumption of both +the CPU and ROM.
+
+The CPU will remain suspended until an interrupt occurs at which point +the interrupt is serviced and then the instruction immediately following +the HALT is executed.
+
+Depending on how much CPU time is required by a game, the HALT +instruction can extend battery life anywhere from 5 to 50% or possibly +more.
+
+When waiting for a vblank event, this would be a BAD example:
+
  @@wait:
+   ld   a,(0FF44h)      ;LY
+   cp   a,144
+   jr   nz,@@wait
+

+A better example would be a procedure as shown below. In this case the +vblank interrupt must be enabled, and your vblank interrupt procedure +must set vblank_flag to a non-zero value.
+
   ld   hl,vblank_flag  ;hl=pointer to vblank_flag
+   xor  a               ;a=0
+  @@wait:               ;wait...
+   halt                 ;suspend CPU - wait for ANY interrupt
+   cp   a,(hl)          ;vblank flag still zero?
+   jr   z,@@wait        ;wait more if zero
+   ld   (hl),a          ;set vblank_flag back to zero
+
The vblank_flag is used to determine whether the HALT period has been +terminated by a vblank interrupt, or by another interrupt. In case that +your program has all other interrupts disabled, then it would be proof +to replace the above procedure by a single HALT instruction.
+
+
+
 PWR Using the STOP Instruction

+The STOP instruction is intended to switch the gameboy into VERY low +power standby mode. For example, a program may use this feature when it +hasn't sensed keyboard input for a longer period (assuming that somebody +forgot to turn off the gameboy).
+
+Before invoking STOP, it might be required to disable Sound and Video +manually (as well as IR-link port in CGB). Much like HALT, the STOP +state is terminated by interrupt events - in this case this would be +commonly a joypad interrupt. The joypad register might be required to be +prepared for STOP either.
+
+
+
 PWR Disabeling the Sound Controller

+If your programs doesn't use sound at all (or during some periods) then +write 00h to register FF26 to save 16% or more on GB power consumption.
+Sound can be turned back on by writing 80h to the same register, all +sound registers must be then re-initialized.
+When the gameboy becomes turned on, sound is enabled by default, and +must be turned off manually when not used.
+
+
+
 PWR Not using CGB Double Speed Mode

+Because CGB Double Speed mode consumes more power, it'd be recommended +to use normal speed when possible.
+There's limited ability to switch between both speeds, for example, a +game might use normal speed in the title screen, and double speed in the +game, or vice versa.
+However, during speed switch the display collapses for a short moment, +so that it'd be no good idea to alter speeds within active game or title +screen periods.
+
+
+
 PWR Using the Skills

+Most of the above power saving methods will produce best results when +using efficient and tight assembler code which requires as less CPU +power as possible. Thus, experienced old-school programmers will +(hopefully) produce lower power consumption, as than HLL-programming +teenagers, for example.
+
+
+
 Sprite RAM Bug

+There is a flaw in the GameBoy hardware that causes trash to be written +to OAM RAM if the following commands are used while their 16-bit content +is in the range of $FE00 to $FEFF:
+
  inc rr        dec rr          ;rr = bc,de, or hl
+  ldi a,(hl)    ldd a,(hl)
+  ldi (hl),a    ldd (hl),a
+
Only sprites 1 & 2 ($FE00 & $FE04) are not affected by these +instructions.
+
+
+
 External Connectors

+Cartridge Slot
+
  Pin   Name    Expl.
+  1     VDD     Power Supply +5V DC
+  2     PHI     System Clock
+  3     /WR     Write
+  4     /RD     Read
+  5     /CS     Chip Select
+  6-21  A0-A15  Address Lines
+  22-29 D0-D7   Data Lines
+  30    /RES    Reset signal
+  31    VIN     External Sound Input
+  32    GND     Ground
+

+Link Port
+Pin numbers are arranged as 2,4,6 in upper row, 1,3,5 un lower row; +outside view of gameboy socket; flat side of socket upside.
+Colors as used in most or all standard link cables, because SIN and SOUT +are crossed, colors Red and Orange are exchanged at one cable end.
+
  Pin Name Color  Expl.
+  1   VCC  -      +5V DC
+  2   SOUT red    Data Out
+  3   SIN  orange Data In
+  4   P14  -      Not used
+  5   SCK  green  Shift Clock
+  6   GND  blue   Ground
+
Note: The original gameboy used larger plugs (unlike pocket gameboys and +newer), linking between older/newer gameboys is possible by using cables +with one large and one small plug though.
+
+Stereo Sound Connector (3.5mm, female)
+
  Pin     Expl.
+  Tip     Sound Left
+  Middle  Sound Right
+  Base    Ground
+

+External Power Supply
+...
+
+
+
+
 END
+ \ No newline at end of file diff --git a/docs/pandocs.txt b/docs/pandocs.txt new file mode 100644 index 0000000..b983910 --- /dev/null +++ b/docs/pandocs.txt @@ -0,0 +1,2885 @@ +Pan Docs +-------- + +Overview +--> About the Pan Docs +--> Game Boy Technical Data +--> Memory Map + +I/O Ports +--> Video Display +--> Sound Controller +--> Joypad Input +--> Serial Data Transfer (Link Cable) +--> Timer and Divider Registers +--> Interrupts +--> CGB Registers +--> SGB Functions + +CPU Specifications +--> CPU Registers and Flags +--> CPU Instruction Set +--> CPU Comparision with Z80 + +Cartridges +--> The Cartridge Header +--> Memory Bank Controllers +--> Gamegenie/Shark Cheats + +Other +--> Power Up Sequence +--> Reducing Power Consumption +--> Sprite RAM Bug +--> External Connectors + +About the Pan Docs +------------------ + + ================================================================= + Everything You Always Wanted To Know About GAMEBOY * + ================================================================= + + * but were afraid to ask + + Pan of -ATX- Document Updated by contributions from: + Marat Fayzullin, Pascal Felber, Paul Robson, Martin Korth + CPU, SGB, CGB, AUX specs by Martin Korth + + Last updated 10/2001 by nocash + Previously updated 4-Mar-98 by kOOPa + +Forward +The following was typed up for informational purposes regarding the inner +workings on the hand-held game machine known as GameBoy, manufactured and +designed by Nintendo Co., LTD. This info is presented to inform a user on how +their Game Boy works and what makes it "tick". GameBoy is copyrighted by +Nintendo Co., LTD. Any reference to copyrighted material is not presented for +monetary gain, but for educational purposes and higher learning. + +Available Document Formats +The present version of this document is available in Text and Html format: + http://www.work.de/nocash/pandocs.txt + http://www.work.de/nocash/pandocs.htm +Also, a copy of this document is included in the manual of newer versions of +the no$gmb debugger, because of recent piracy attacks (many thanks and best +wishes go to hell) I have currently no intention to publish any such or +further no$gmb updates though. + +Game Boy Technical Data +----------------------- + + CPU - 8-bit (Similar to the Z80 processor) + Clock Speed - 4.194304MHz (4.295454MHz for SGB, max. 8.4MHz for CGB) + Work RAM - 8K Byte (32K Byte for CGB) + Video RAM - 8K Byte (16K Byte for CGB) + Screen Size - 2.6" + Resolution - 160x144 (20x18 tiles) + Max sprites - Max 40 per screen, 10 per line + Sprite sizes - 8x8 or 8x16 + Palettes - 1x4 BG, 2x3 OBJ (for CGB: 8x4 BG, 8x3 OBJ) + Colors - 4 grayshades (32768 colors for CGB) + Horiz Sync - 9198 KHz (9420 KHz for SGB) + Vert Sync - 59.73 Hz (61.17 Hz for SGB) + Sound - 4 channels with stereo sound + Power - DC6V 0.7W (DC3V 0.7W for GB Pocket, DC3V 0.6W for CGB) + +Memory Map +---------- + +The gameboy is having a 16bit address bus, that is used to address ROM, RAM, +and I/O registers. + +General Memory Map + 0000-3FFF 16KB ROM Bank 00 (in cartridge, fixed at bank 00) + 4000-7FFF 16KB ROM Bank 01..NN (in cartridge, switchable bank number) + 8000-9FFF 8KB Video RAM (VRAM) (switchable bank 0-1 in CGB Mode) + A000-BFFF 8KB External RAM (in cartridge, switchable bank, if any) + C000-CFFF 4KB Work RAM Bank 0 (WRAM) + D000-DFFF 4KB Work RAM Bank 1 (WRAM) (switchable bank 1-7 in CGB Mode) + E000-FDFF Same as C000-DDFF (ECHO) (typically not used) + FE00-FE9F Sprite Attribute Table (OAM) + FEA0-FEFF Not Usable + FF00-FF7F I/O Ports + FF80-FFFE High RAM (HRAM) + FFFF Interrupt Enable Register + +Jump Vectors in First ROM Bank +The following addresses are supposed to be used as jump vectors: + 0000,0008,0010,0018,0020,0028,0030,0038 for RST commands + 0040,0048,0050,0058,0060 for Interrupts +However, the memory may be used for any other purpose in case that your +program doesn't use any (or only some) RST commands or Interrupts. RST +commands are 1-byte opcodes that work similiar to CALL opcodes, except that +the destination address is fixed. + +Cartridge Header in First ROM Bank +The memory at 0100-014F contains the cartridge header. This area contains +information about the program, its entry point, checksums, information about +the used MBC chip, the ROM and RAM sizes, etc. Most of the bytes in this area +are required to be specified correctly. For more information read the chapter +about The Cartridge Header. + +External Memory and Hardware +The areas from 0000-7FFF and A000-BFFF may be used to connect external +hardware. The first area is typically used to address ROM (read only, of +course), cartridges with Memory Bank Controllers (MBCs) are additionally using +this area to output data (write only) to the MBC chip. The second area is +often used to address external RAM, or to address other external hardware +(Real Time Clock, etc). External memory is often battery buffered, and may +hold saved game positions and high scrore tables (etc.) even when the gameboy +is turned of, or when the cartridge is removed. For specific information read +the chapter about Memory Bank Controllers. + +Video Display +------------- + +Video I/O Registers +--> LCD Control Register +--> LCD Status Register +--> LCD Interrupts +--> LCD Position and Scrolling +--> LCD Monochrome Palettes +--> LCD Color Palettes (CGB only) +--> LCD VRAM Bank (CGB only) +--> LCD OAM DMA Transfers +--> LCD VRAM DMA Transfers (CGB only) + +Video Memory +--> VRAM Tile Data +--> VRAM Background Maps +--> VRAM Sprite Attribute Table (OAM) +--> Accessing VRAM and OAM + +LCD Control Register +-------------------- + +FF40 - LCDC - LCD Control (R/W) + Bit 7 - LCD Display Enable (0=Off, 1=On) + Bit 6 - Window Tile Map Display Select (0=9800-9BFF, 1=9C00-9FFF) + Bit 5 - Window Display Enable (0=Off, 1=On) + Bit 4 - BG & Window Tile Data Select (0=8800-97FF, 1=8000-8FFF) + Bit 3 - BG Tile Map Display Select (0=9800-9BFF, 1=9C00-9FFF) + Bit 2 - OBJ (Sprite) Size (0=8x8, 1=8x16) + Bit 1 - OBJ (Sprite) Display Enable (0=Off, 1=On) + Bit 0 - BG Display (for CGB see below) (0=Off, 1=On) + +LCDC.7 - LCD Display Enable +CAUTION: Stopping LCD operation (Bit 7 from 1 to 0) may be performed during +V-Blank ONLY, disabeling the display outside of the V-Blank period may damage +the hardware. This appears to be a serious issue, Nintendo is reported to +reject any games that do not follow this rule. +V-blank can be confirmed when the value of LY is greater than or equal to 144. +When the display is disabled the screen is blank (white), and VRAM and OAM can +be accessed freely. + +--- LCDC.0 has different Meanings depending on Gameboy Type --- + +LCDC.0 - 1) Monochrome Gameboy and SGB: BG Display +When Bit 0 is cleared, the background becomes blank (white). Window and +Sprites may still be displayed (if enabled in Bit 1 and/or Bit 5). + +LCDC.0 - 2) CGB in CGB Mode: BG and Window Master Priority +When Bit 0 is cleared, the background and window lose their priority - the +sprites will be always displayed on top of background and window, +independently of the priority flags in OAM and BG Map attributes. + +LCDC.0 - 3) CGB in Non CGB Mode: BG and Window Display +When Bit 0 is cleared, both background and window become blank (white), ie. +the Window Display Bit (Bit 5) is ignored in that case. Only Sprites may still +be displayed (if enabled in Bit 1). +This is a possible compatibility problem - any monochrome games (if any) that +disable the background, but still want to display the window wouldn't work +properly on CGBs. + +LCD Status Register +------------------- + +FF41 - STAT - LCDC Status (R/W) + Bit 6 - LYC=LY Coincidence Interrupt (1=Enable) (Read/Write) + Bit 5 - Mode 2 OAM Interrupt (1=Enable) (Read/Write) + Bit 4 - Mode 1 V-Blank Interrupt (1=Enable) (Read/Write) + Bit 3 - Mode 0 H-Blank Interrupt (1=Enable) (Read/Write) + Bit 2 - Coincidence Flag (0:LYC<>LY, 1:LYC=LY) (Read Only) + Bit 1-0 - Mode Flag (Mode 0-3, see below) (Read Only) + 0: During H-Blank + 1: During V-Blank + 2: During Searching OAM-RAM + 3: During Transfering Data to LCD Driver + +The two lower STAT bits show the current status of the LCD controller. + Mode 0: The LCD controller is in the H-Blank period and + the CPU can access both the display RAM (8000h-9FFFh) + and OAM (FE00h-FE9Fh) + + Mode 1: The LCD contoller is in the V-Blank period (or the + display is disabled) and the CPU can access both the + display RAM (8000h-9FFFh) and OAM (FE00h-FE9Fh) + + Mode 2: The LCD controller is reading from OAM memory. + The CPU access OAM memory (FE00h-FE9Fh) + during this period. + + Mode 3: The LCD controller is reading from both OAM and VRAM, + The CPU access OAM and VRAM during this period. + CGB Mode: Cannot access Palette Data (FF69,FF6B) either. + +The following are typical when the display is enabled: + Mode 2 2_____2_____2_____2_____2_____2___________________2____ + Mode 3 _33____33____33____33____33____33__________________3___ + Mode 0 ___000___000___000___000___000___000________________000 + Mode 1 ____________________________________11111111111111_____ + +The Mode Flag goes through the values 0, 2, and 3 at a cycle of about 109uS. 0 +is present about 48.6uS, 2 about 19uS, and 3 about 41uS. This is interrupted +every 16.6ms by the VBlank (1). The mode flag stays set at 1 for about 1.08 +ms. + +Mode 0 is present between 201-207 clks, 2 about 77-83 clks, and 3 about +169-175 clks. A complete cycle through these states takes 456 clks. VBlank +lasts 4560 clks. A complete screen refresh occurs every 70224 clks.) + +LCD Interrupts +-------------- + +INT 40 - V-Blank Interrupt +The V-Blank interrupt occurs ca. 59.7 times a second on a regular GB and ca. +61.1 times a second on a Super GB (SGB). This interrupt occurs at the +beginning of the V-Blank period (LY=144). +During this period video hardware is not using video ram so it may be freely +accessed. This period lasts approximately 1.1 milliseconds. + +INT 48 - LCDC Status Interrupt +There are various reasons for this interrupt to occur as described by the STAT +register ($FF40). One very popular reason is to indicate to the user when the +video hardware is about to redraw a given LCD line. This can be useful for +dynamically controlling the SCX/SCY registers ($FF43/$FF42) to perform special +video effects. + +LCD Position and Scrolling +-------------------------- + +FF42 - SCY - Scroll Y (R/W) +FF43 - SCX - Scroll X (R/W) +Specifies the position in the 256x256 pixels BG map (32x32 tiles) which is to +be displayed at the upper/left LCD display position. +Values in range from 0-255 may be used for X/Y each, the video controller +automatically wraps back to the upper (left) position in BG map when drawing +exceeds the lower (right) border of the BG map area. + +FF44 - LY - LCDC Y-Coordinate (R) +The LY indicates the vertical line to which the present data is transferred to +the LCD Driver. The LY can take on any value between 0 through 153. The values +between 144 and 153 indicate the V-Blank period. Writing will reset the +counter. + +FF45 - LYC - LY Compare (R/W) +The gameboy permanently compares the value of the LYC and LY registers. When +both values are identical, the coincident bit in the STAT register becomes +set, and (if enabled) a STAT interrupt is requested. + +FF4A - WY - Window Y Position (R/W) +FF4B - WX - Window X Position minus 7 (R/W) +Specifies the upper/left positions of the Window area. (The window is an +alternate background area which can be displayed above of the normal +background. OBJs (sprites) may be still displayed above or behinf the window, +just as for normal BG.) +The window becomes visible (if enabled) when positions are set in range +WX=0..166, WY=0..143. A postion of WX=7, WY=0 locates the window at upper +left, it is then completly covering normal background. + +LCD Monochrome Palettes +----------------------- + +FF47 - BGP - BG Palette Data (R/W) - Non CGB Mode Only +This register assigns gray shades to the color numbers of the BG and Window +tiles. + Bit 7-6 - Shade for Color Number 3 + Bit 5-4 - Shade for Color Number 2 + Bit 3-2 - Shade for Color Number 1 + Bit 1-0 - Shade for Color Number 0 +The four possible gray shades are: + 0 White + 1 Light gray + 2 Dark gray + 3 Black +In CGB Mode the Color Palettes are taken from CGB Palette Memory instead. + +FF48 - OBP0 - Object Palette 0 Data (R/W) - Non CGB Mode Only +This register assigns gray shades for sprite palette 0. It works exactly as +BGP (FF47), except that the lower two bits aren't used because sprite data 00 +is transparent. + +FF49 - OBP1 - Object Palette 1 Data (R/W) - Non CGB Mode Only +This register assigns gray shades for sprite palette 1. It works exactly as +BGP (FF47), except that the lower two bits aren't used because sprite data 00 +is transparent. + +LCD Color Palettes (CGB only) +----------------------------- + +FF68 - BCPS/BGPI - CGB Mode Only - Background Palette Index +This register is used to address a byte in the CGBs Background Palette Memory. +Each two byte in that memory define a color value. The first 8 bytes define +Color 0-3 of Palette 0 (BGP0), and so on for BGP1-7. + Bit 0-5 Index (00-3F) + Bit 7 Auto Increment (0=Disabled, 1=Increment after Writing) +Data can be read/written to/from the specified index address through Register +FF69. When the Auto Increment Bit is set then the index is automatically +incremented after each to FF69. Auto Increment has no effect when + from FF69, so the index must be manually incremented in that case. + +FF69 - BCPD/BGPD - CGB Mode Only - Background Palette Data +This register allows to read/write data to the CGBs Background Palette Memory, +addressed through Register FF68. +Each color is defined by two bytes (Bit 0-7 in first byte). + Bit 0-4 Red Intensity (00-1F) + Bit 5-9 Green Intensity (00-1F) + Bit 10-14 Blue Intensity (00-1F) +Much like VRAM, Data in Palette Memory cannot be read/written during the time +when the LCD Controller is reading from it. (That is when the STAT register +indicates Mode 3). +Note: Initially all background colors are initialized as white. + +FF6A - OCPS/OBPI - CGB Mode Only - Sprite Palette Index +FF6B - OCPD/OBPD - CGB Mode Only - Sprite Palette Data +These registers are used to initialize the Sprite Palettes OBP0-7, identically +as described above for Background Palettes. Note that four colors may be +defined for each OBP Palettes - but only Color 1-3 of each Sprite Palette can +be displayed, Color 0 is always transparent, and can be initialized to a don't +care value. +Note: Initially all sprite colors are uninitialized. + +RGB Translation by CGBs +When developing graphics on PCs, note that the RGB values will have different +appearance on CGB displays as on VGA monitors: +The highest intensity will produce Light Gray color rather than White. The +intensities are not linear; the values 10h-1Fh will all appear very bright, +while medium and darker colors are ranged at 00h-0Fh. +The CGB display will mix colors quite oddly, increasing intensity of only one +R,G,B color will also influence the other two R,G,B colors. +For example, a color setting of 03EFh (Blue=0, Green=1Fh, Red=0Fh) will appear +as Neon Green on VGA displays, but on the CGB it'll produce a decently washed +out Yellow. + +RGB Translation by GBAs +Even though GBA is described to be compatible to CGB games, most CGB games are +completely unplayable on GBAs because most colors are invisible (black). Of +course, colors such like Black and White will appear the same on both CGB and +GBA, but medium intensities are arranged completely different. +Intensities in range 00h..0Fh are invisible/black (unless eventually under +best sunlight circumstances, and when gazing at the screen under obscure +viewing angles), unfortunately, these intensities are regulary used by most +existing CGB games for medium and darker colors. +Newer CGB games may avoid this effect by changing palette data when detecting +GBA hardware. A relative simple method would be using the formula +GBA=CGB/2+10h for each R,G,B intensity, probably the result won't be perfect, +and (once colors became visible) it may turn out that the color mixing is +different also, anyways, it'd be still ways better than no conversion. +Asides, this translation method should have been VERY easy to implement in GBA +hardware directly, even though Nintendo obviously failed to do so. How did +they say, This seal is your assurance for excellence in workmanship and so on? + +LCD VRAM Bank (CGB only) +------------------------ + +FF4F - VBK - CGB Mode Only - VRAM Bank +This 1bit register selects the current Video Memory (VRAM) Bank. + Bit 0 - VRAM Bank (0-1) +Bank 0 contains 192 Tiles, and two background maps, just as for monochrome +games. Bank 1 contains another 192 Tiles, and color attribute maps for the +background maps in bank 0. + +LCD OAM DMA Transfers +--------------------- + +FF46 - DMA - DMA Transfer and Start Address (W) +Writing to this register launches a DMA transfer from ROM or RAM to OAM memory +(sprite attribute table). The written value specifies the transfer source +address divided by 100h, ie. source & destination are: + Source: XX00-XX9F ;XX in range from 00-F1h + Destination: FE00-FE9F +It takes 160 microseconds until the transfer has completed (80 microseconds in +CGB Double Speed Mode), during this time the CPU can access only HRAM (memory +at FF80-FFFE). For this reason, the programmer must copy a short procedure +into HRAM, and use this procedure to start the transfer from inside HRAM, and +wait until the transfer has finished: + ld (0FF46h),a ;start DMA transfer, a=start address/100h + ld a,28h ;delay... + wait: ;total 5x40 cycles, approx 200ms + dec a ;1 cycle + jr nz,wait ;4 cycles +Most programs are executing this procedure from inside of their VBlank +procedure, but it is possible to execute it during display redraw also, +allowing to display more than 40 sprites on the screen (ie. for example 40 +sprites in upper half, and other 40 sprites in lower half of the screen). + +LCD VRAM DMA Transfers (CGB only) +--------------------------------- + +FF51 - HDMA1 - CGB Mode Only - New DMA Source, High +FF52 - HDMA2 - CGB Mode Only - New DMA Source, Low +FF53 - HDMA3 - CGB Mode Only - New DMA Destination, High +FF54 - HDMA4 - CGB Mode Only - New DMA Destination, Low +FF55 - HDMA5 - CGB Mode Only - New DMA Length/Mode/Start +These registers are used to initiate a DMA transfer from ROM or RAM to VRAM. +The Source Start Address may be located at 0000-7FF0 or A000-DFF0, the lower +four bits of the address are ignored (treated as zero). The Destination Start +Address may be located at 8000-9FF0, the lower four bits of the address are +ignored (treated as zero), the upper 3 bits are ignored either (destination is +always in VRAM). + +Writing to FF55 starts the transfer, the lower 7 bits of FF55 specify the +Transfer Length (divided by 10h, minus 1). Ie. lengths of 10h-800h bytes can +be defined by the values 00h-7Fh. And the upper bit of FF55 indicates the +Transfer Mode: + +Bit7=0 - General Purpose DMA +When using this transfer method, all data is transferred at once. The +execution of the program is halted until the transfer has completed. Note that +the General Purpose DMA blindly attempts to copy the data, even if the LCD +controller is currently accessing VRAM. So General Purpose DMA should be used +only if the Display is disabled, or during V-Blank, or (for rather short +blocks) during H-Blank. +The execution of the program continues when the transfer has been completed, +and FF55 then contains a value if FFh. + +Bit7=1 - H-Blank DMA +The H-Blank DMA transfers 10h bytes of data during each H-Blank, ie. at +LY=0-143, no data is transferred during V-Blank (LY=144-153), but the transfer +will then continue at LY=00. The execution of the program is halted during the +separate transfers, but the program execution continues during the 'spaces' +between each data block. +Note that the program may not change the Destination VRAM bank (FF4F), or the +Source ROM/RAM bank (in case data is transferred from bankable memory) until +the transfer has completed! +Reading from Register FF55 returns the remaining length (divided by 10h, minus +1), a value of 0FFh indicates that the transfer has completed. It is also +possible to terminate an active H-Blank transfer by writing zero to Bit 7 of +FF55. In that case reading from FF55 may return any value for the lower 7 +bits, but Bit 7 will be read as "1". + +Confirming if the DMA Transfer is Active +Reading Bit 7 of FF55 can be used to confirm if the DMA transfer is active +(1=Not Active, 0=Active). This works under any circumstances - after +completion of General Purpose, or H-Blank Transfer, and after manually +terminating a H-Blank Transfer. + +Transfer Timings +In both Normal Speed and Double Speed Mode it takes about 8us to transfer a +block of 10h bytes. That are 8 cycles in Normal Speed Mode, and 16 'fast' +cycles in Double Speed Mode. +Older MBC controllers (like MBC1-4) and slower ROMs are not guaranteed to +support General Purpose or H-Blank DMA, that's because there are always 2 +bytes transferred per microsecond (even if the itself program runs it Normal +Speed Mode). + +VRAM Tile Data +-------------- + +Tile Data is stored in VRAM at addresses 8000h-97FFh, this area defines the +Bitmaps for 192 Tiles. In CGB Mode 384 Tiles can be defined, because memory at +0:8000h-97FFh and at 1:8000h-97FFh is used. + +Each tile is sized 8x8 pixels and has a color depth of 4 colors/gray shades. +Tiles can be displayed as part of the Background/Window map, and/or as OAM +tiles (foreground sprites). Note that foreground sprites may have only 3 +colors, because color 0 is transparent. + +As it was said before, there are two Tile Pattern Tables at $8000-8FFF and at +$8800-97FF. The first one can be used for sprites and the background. Its +tiles are numbered from 0 to 255. The second table can be used for the +background and the window display and its tiles are numbered from -128 to 127. + +Each Tile occupies 16 bytes, where each 2 bytes represent a line: + Byte 0-1 First Line (Upper 8 pixels) + Byte 2-3 Next Line + etc. +For each line, the first byte defines the least significant bits of the color +numbers for each pixel, and the second byte defines the upper bits of the +color numbers. In either case, Bit 7 is the leftmost pixel, and Bit 0 the +rightmost. + +So, each pixel is having a color number in range from 0-3. The color numbers +are translated into real colors (or gray shades) depending on the current +palettes. The palettes are defined through registers FF47-FF49 (Non CGB Mode), +and FF68-FF6B (CGB Mode). + +VRAM Background Maps +-------------------- + +The gameboy contains two 32x32 tile background maps in VRAM at addresses +9800h-9BFFh and 9C00h-9FFFh. Each can be used either to display "normal" +background, or "window" background. + +BG Map Tile Numbers +An area of VRAM known as Background Tile Map contains the numbers of tiles to +be displayed. It is organized as 32 rows of 32 bytes each. Each byte contains +a number of a tile to be displayed. Tile patterns are taken from the Tile Data +Table located either at $8000-8FFF or $8800-97FF. In the first case, patterns +are numbered with unsigned numbers from 0 to 255 (i.e. pattern #0 lies at +address $8000). In the second case, patterns have signed numbers from -128 to +127 (i.e. pattern #0 lies at address $9000). The Tile Data Table address for +the background can be selected via LCDC register. + +BG Map Attributes (CGB Mode only) +In CGB Mode, an additional map of 32x32 bytes is stored in VRAM Bank 1 (each +byte defines attributes for the corresponding tile-number map entry in VRAM +Bank 0): + Bit 0-2 Background Palette number (BGP0-7) + Bit 3 Tile VRAM Bank number (0=Bank 0, 1=Bank 1) + Bit 4 Not used + Bit 5 Horizontal Flip (0=Normal, 1=Mirror horizontally) + Bit 6 Vertical Flip (0=Normal, 1=Mirror vertically) + Bit 7 BG-to-OAM Priority (0=Use OAM priority bit, 1=BG Priority) +When Bit 7 is set, the corresponding BG tile will have priority above all OBJs +(regardless of the priority bits in OAM memory). There's also an Master +Priority flag in LCDC register Bit 0 which overrides all other priority bits +when cleared. + +As one background tile has a size of 8x8 pixels, the BG maps may hold a +picture of 256x256 pixels, an area of 160x144 pixels of this picture can be +displayed on the LCD screen. + +Normal Background (BG) +The SCY and SCX registers can be used to scroll the background, allowing to +select the origin of the visible 160x144 pixel area within the total 256x256 +pixel background map. Background wraps around the screen (i.e. when part of it +goes off the screen, it appears on the opposite side.) + +The Window +Besides background, there is also a "window" overlaying the background. The +window is not scrollable i.e. it is always displayed starting from its left +upper corner. The location of a window on the screen can be adjusted via WX +and WY registers. Screen coordinates of the top left corner of a window are +WX-7,WY. The tiles for the window are stored in the Tile Data Table. Both the +Background and the window share the same Tile Data Table. + +Both background and window can be disabled or enabled separately via bits in +the LCDC register. + +VRAM Sprite Attribute Table (OAM) +--------------------------------- + +GameBoy video controller can display up to 40 sprites either in 8x8 or in 8x16 +pixels. Because of a limitation of hardware, only ten sprites can be displayed +per scan line. Sprite patterns have the same format as BG tiles, but they are +taken from the Sprite Pattern Table located at $8000-8FFF and have unsigned +numbering. + +Sprite attributes reside in the Sprite Attribute Table (OAM - Object Attribute +Memory) at $FE00-FE9F. Each of the 40 entries consists of four bytes with the +following meanings: + +Byte0 - Y Position +Specifies the sprites vertical position on the screen (minus 16). +An offscreen value (for example, Y=0 or Y>=160) hides the sprite. + +Byte1 - X Position +Specifies the sprites horizontal position on the screen (minus 8). +An offscreen value (X=0 or X>=168) hides the sprite, but the sprite +still affects the priority ordering - a better way to hide a sprite is to set +its Y-coordinate offscreen. + +Byte2 - Tile/Pattern Number +Specifies the sprites Tile Number (00-FF). This (unsigned) value selects a +tile from memory at 8000h-8FFFh. In CGB Mode this could be either in VRAM Bank +0 or 1, depending on Bit 3 of the following byte. +In 8x16 mode, the lower bit of the tile number is ignored. Ie. the upper 8x8 +tile is "NN AND FEh", and the lower 8x8 tile is "NN OR 01h". + +Byte3 - Attributes/Flags: + Bit7 OBJ-to-BG Priority (0=OBJ Above BG, 1=OBJ Behind BG color 1-3) + (Used for both BG and Window. BG color 0 is always behind OBJ) + Bit6 Y flip (0=Normal, 1=Vertically mirrored) + Bit5 X flip (0=Normal, 1=Horizontally mirrored) + Bit4 Palette number **Non CGB Mode Only** (0=OBP0, 1=OBP1) + Bit3 Tile VRAM-Bank **CGB Mode Only** (0=Bank 0, 1=Bank 1) + Bit2-0 Palette number **CGB Mode Only** (OBP0-7) + +Sprite Priorities and Conflicts +When sprites with different x coordinate values overlap, the one with the +smaller x coordinate (closer to the left) will have priority and appear above +any others. This applies in Non CGB Mode only. +When sprites with the same x coordinate values overlap, they have priority +according to table ordering. (i.e. $FE00 - highest, $FE04 - next highest, +etc.) In CGB Mode priorities are always assigned like this. + +Only 10 sprites can be displayed on any one line. When this limit is exceeded, +the lower priority sprites (priorities listed above) won't be displayed. To +keep unused sprites from affecting onscreen sprites set their Y coordinate to +Y=0 or Y=>144+16. Just setting the X coordinate to X=0 or X=>160+8 on a sprite +will hide it but it will still affect other sprites sharing the same lines. + +Writing Data to OAM Memory +The recommened method is to write the data to normal RAM first, and to copy +that RAM to OAM by using the DMA transfer function, initiated through DMA +register (FF46). +Beside for that, it is also possible to write data directly to the OAM area by +using normal LD commands, this works only during the H-Blank and V-Blank +periods. The current state of the LCD controller can be read out from the STAT +register (FF41). + +Accessing VRAM and OAM +---------------------- + +CAUTION +When the LCD Controller is drawing the screen it is directly reading from +Video Memory (VRAM) and from the Sprite Attribute Table (OAM). During these +periods the Gameboy CPU may not access the VRAM and OAM. That means, any +attempts to write to VRAM/OAM are ignored (the data remains unchanged). And +any attempts to read from VRAM/OAM will return undefined data (typically a +value of FFh). + +For this reason the program should verify if VRAM/OAM is accessable before +actually reading or writing to it. This is usually done by reading the Mode +Bits from the STAT Register (FF41). When doing this (as described in the +examples below) you should take care that no interrupts occur between the wait +loops and the following memory access - the memory is guaranted to be +accessable only for a few cycles directly after the wait loops have completed. + +VRAM (memory at 8000h-9FFFh) is accessable during Mode 0-2 + Mode 0 - H-Blank Period, + Mode 1 - V-Blank Period, and + Mode 2 - Searching OAM Period +A typical procedure that waits for accessibility of VRAM would be: + ld hl,0FF41h ;-STAT Register + @@wait: ;\ + bit 1,(hl) ; Wait until Mode is 0 or 1 + jr nz,@@wait ;/ +Even if the procedure gets executed at the of Mode 0 or 1, it is still +proof to assume that VRAM can be accessed for a few more cycles because in +either case the following period is Mode 2 which allows access to VRAM either. +In CGB Mode an alternate method to write data to VRAM is to use the HDMA +Function (FF51-FF55). + +OAM (memory at FE00h-FE9Fh) is accessable during Mode 0-1 + Mode 0 - H-Blank Period, and + Mode 1 - V-Blank Period +Beside for that, OAM can be accessed at any time by using the DMA Function +(FF46). When directly reading or writing to OAM, a typical procedure that +waits for accessibilty or OAM Memory would be: + ld hl,0FF41h ;-STAT Register + @@wait1: ;\ + bit 1,(hl) ; Wait until Mode is -NOT- 0 or 1 + jr z,@@wait1 ;/ + @@wait2: ;\ + bit 1,(hl) ; Wait until Mode 0 or 1 -BEGINS- + jr nz,@@wait2 ;/ +The two wait loops ensure that Mode 0 or 1 will last for a few clock cycles +after completion of the procedure. In V-Blank period it might be recommended +to skip the whole procedure - and in most cases using the above mentioned DMA +function would be more recommended anyways. + +Note +When the display is disabled, both VRAM and OAM are accessable at any time. +The downside is that the screen is blank (white) during this period, so that +disabling the display would be recommended only during initialization. + +Sound Controller +---------------- + +--> Sound Overview +--> Sound Channel 1 - Tone & Sweep +--> Sound Channel 2 - Tone +--> Sound Channel 3 - Wave Output +--> Sound Channel 4 - Noise +--> Sound Control Registers + +Sound Overview +-------------- + +There are two sound channels connected to the output terminals SO1 and SO2. +There is also a input terminal Vin connected to the cartridge. It can be +routed to either of both output terminals. GameBoy circuitry allows producing +sound in four different ways: + + Quadrangular wave patterns with sweep and envelope functions. + Quadrangular wave patterns with envelope functions. + Voluntary wave patterns from wave RAM. + White noise with an envelope function. + +These four sounds can be controlled independantly and then mixed separately +for each of the output terminals. + +Sound registers may be set at all times while producing sound. + +(Sounds will have a 2.4% higher frequency on Super GB.) + +Sound Channel 1 - Tone & Sweep +------------------------------ + +FF10 - NR10 - Channel 1 Sweep register (R/W) + Bit 6-4 - Sweep Time + Bit 3 - Sweep Increase/Decrease + 0: Addition (frequency increases) + 1: Subtraction (frequency decreases) + Bit 2-0 - Number of sweep shift (n: 0-7) +Sweep Time: + 000: sweep off - no freq change + 001: 7.8 ms (1/128Hz) + 010: 15.6 ms (2/128Hz) + 011: 23.4 ms (3/128Hz) + 100: 31.3 ms (4/128Hz) + 101: 39.1 ms (5/128Hz) + 110: 46.9 ms (6/128Hz) + 111: 54.7 ms (7/128Hz) + +The change of frequency (NR13,NR14) at each shift is calculated by the +following formula where X(0) is initial freq & X(t-1) is last freq: + X(t) = X(t-1) +/- X(t-1)/2^n + +FF11 - NR11 - Channel 1 Sound length/Wave pattern duty (R/W) + Bit 7-6 - Wave Pattern Duty (Read/Write) + Bit 5-0 - Sound length data (Write Only) (t1: 0-63) +Wave Duty: + 00: 12.5% ( _-------_-------_------- ) + 01: 25% ( __------__------__------ ) + 10: 50% ( ____----____----____---- ) (normal) + 11: 75% ( ______--______--______-- ) +Sound Length = (64-t1)*(1/256) seconds +The Length value is used only if Bit 6 in NR14 is set. + +FF12 - NR12 - Channel 1 Volume Envelope (R/W) + Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound) + Bit 3 - Envelope Direction (0=Decrease, 1=Increase) + Bit 2-0 - Number of envelope sweep (n: 0-7) + (If zero, stop envelope operation.) +Length of 1 step = n*(1/64) seconds + +FF13 - NR13 - Channel 1 Frequency lo (Write Only) + +Lower 8 bits of 11 bit frequency (x). +Next 3 bit are in NR14 ($FF14) + +FF14 - NR14 - Channel 1 Frequency hi (R/W) + Bit 7 - Initial (1=Restart Sound) (Write Only) + Bit 6 - Counter/consecutive selection (Read/Write) + (1=Stop output when length in NR11 expires) + Bit 2-0 - Frequency's higher 3 bits (x) (Write Only) +Frequency = 131072/(2048-x) Hz + +Sound Channel 2 - Tone +---------------------- + +This sound channel works exactly as channel 1, except that it doesn't have a +Tone Envelope/Sweep Register. + +FF16 - NR21 - Channel 2 Sound Length/Wave Pattern Duty (R/W) + Bit 7-6 - Wave Pattern Duty (Read/Write) + Bit 5-0 - Sound length data (Write Only) (t1: 0-63) +Wave Duty: + 00: 12.5% ( _-------_-------_------- ) + 01: 25% ( __------__------__------ ) + 10: 50% ( ____----____----____---- ) (normal) + 11: 75% ( ______--______--______-- ) +Sound Length = (64-t1)*(1/256) seconds +The Length value is used only if Bit 6 in NR24 is set. + +FF17 - NR22 - Channel 2 Volume Envelope (R/W) + Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound) + Bit 3 - Envelope Direction (0=Decrease, 1=Increase) + Bit 2-0 - Number of envelope sweep (n: 0-7) + (If zero, stop envelope operation.) +Length of 1 step = n*(1/64) seconds + +FF18 - NR23 - Channel 2 Frequency lo data (W) +Frequency's lower 8 bits of 11 bit data (x). +Next 3 bits are in NR24 ($FF19). + +FF19 - NR24 - Channel 2 Frequency hi data (R/W) + Bit 7 - Initial (1=Restart Sound) (Write Only) + Bit 6 - Counter/consecutive selection (Read/Write) + (1=Stop output when length in NR21 expires) + Bit 2-0 - Frequency's higher 3 bits (x) (Write Only) +Frequency = 131072/(2048-x) Hz + +Sound Channel 3 - Wave Output +----------------------------- + +This channel can be used to output digital sound, the length of the sample +buffer (Wave RAM) is limited to 32 digits. This sound channel can be also used +to output normal tones when initializing the Wave RAM by a square wave. This +channel doesn't have a volume envelope register. + +FF1A - NR30 - Channel 3 Sound on/off (R/W) + Bit 7 - Sound Channel 3 Off (0=Stop, 1=Playback) (Read/Write) + +FF1B - NR31 - Channel 3 Sound Length + Bit 7-0 - Sound length (t1: 0 - 255) +Sound Length = (256-t1)*(1/256) seconds +This value is used only if Bit 6 in NR34 is set. + +FF1C - NR32 - Channel 3 Select output level (R/W) + Bit 6-5 - Select output level (Read/Write) +Possible Output levels are: + 0: Mute (No sound) + 1: 100% Volume (Produce Wave Pattern RAM Data as it is) + 2: 50% Volume (Produce Wave Pattern RAM data shifted once to the right) + 3: 25% Volume (Produce Wave Pattern RAM data shifted twice to the right) + +FF1D - NR33 - Channel 3 Frequency's lower data (W) +Lower 8 bits of an 11 bit frequency (x). + +FF1E - NR34 - Channel 3 Frequency's higher data (R/W) + Bit 7 - Initial (1=Restart Sound) (Write Only) + Bit 6 - Counter/consecutive selection (Read/Write) + (1=Stop output when length in NR31 expires) + Bit 2-0 - Frequency's higher 3 bits (x) (Write Only) +Frequency = 4194304/(64*(2048-x)) Hz = 65536/(2048-x) Hz + +FF30-FF3F - Wave Pattern RAM +Contents - Waveform storage for arbitrary sound data + +This storage area holds 32 4-bit samples that are played back upper 4 bits +first. + +Sound Channel 4 - Noise +----------------------- + +This channel is used to output white noise. This is done by randomly switching +the amplitude between high and low at a given frequency. Depending on the +frequency the noise will appear 'harder' or 'softer'. + +It is also possible to influence the function of the random generator, so the +that the output becomes more regular, resulting in a limited ability to output +Tone instead of Noise. + +FF20 - NR41 - Channel 4 Sound Length (R/W) + Bit 5-0 - Sound length data (t1: 0-63) +Sound Length = (64-t1)*(1/256) seconds +The Length value is used only if Bit 6 in NR44 is set. + +FF21 - NR42 - Channel 4 Volume Envelope (R/W) + Bit 7-4 - Initial Volume of envelope (0-0Fh) (0=No Sound) + Bit 3 - Envelope Direction (0=Decrease, 1=Increase) + Bit 2-0 - Number of envelope sweep (n: 0-7) + (If zero, stop envelope operation.) +Length of 1 step = n*(1/64) seconds + +FF22 - NR43 - Channel 4 Polynomial Counter (R/W) +The amplitude is randomly switched between high and low at the given +frequency. A higher frequency will make the noise to appear 'softer'. +When Bit 3 is set, the output will become more regular, and some frequencies +will sound more like Tone than Noise. + Bit 7-4 - Shift Clock Frequency (s) + Bit 3 - Counter Step/Width (0=15 bits, 1=7 bits) + Bit 2-0 - Dividing Ratio of Frequencies (r) +Frequency = 524288 Hz / r / 2^(s+1) ;For r=0 assume r=0.5 instead + +FF23 - NR44 - Channel 4 Counter/consecutive; Inital (R/W) + Bit 7 - Initial (1=Restart Sound) (Write Only) + Bit 6 - Counter/consecutive selection (Read/Write) + (1=Stop output when length in NR41 expires) + +Sound Control Registers +----------------------- + +FF24 - NR50 - Channel control / ON-OFF / Volume (R/W) +The volume bits specify the "Master Volume" for Left/Right sound output. + Bit 7 - Output Vin to SO2 terminal (1=Enable) + Bit 6-4 - SO2 output level (volume) (0-7) + Bit 3 - Output Vin to SO1 terminal (1=Enable) + Bit 2-0 - SO1 output level (volume) (0-7) +The Vin signal is received from the game cartridge bus, allowing external +hardware in the cartridge to supply a fifth sound channel, additionally to the +gameboys internal four channels. As far as I know this feature isn't used by +any existing games. + +FF25 - NR51 - Selection of Sound output terminal (R/W) + Bit 7 - Output sound 4 to SO2 terminal + Bit 6 - Output sound 3 to SO2 terminal + Bit 5 - Output sound 2 to SO2 terminal + Bit 4 - Output sound 1 to SO2 terminal + Bit 3 - Output sound 4 to SO1 terminal + Bit 2 - Output sound 3 to SO1 terminal + Bit 1 - Output sound 2 to SO1 terminal + Bit 0 - Output sound 1 to SO1 terminal + +FF26 - NR52 - Sound on/off +If your GB programs don't use sound then write 00h to this register to save +16% or more on GB power consumption. Disabeling the sound controller by +clearing Bit 7 destroys the contents of all sound registers. Also, it is not +possible to access any sound registers (execpt FF26) while the sound +controller is disabled. + Bit 7 - All sound on/off (0: stop all sound circuits) (Read/Write) + Bit 3 - Sound 4 ON flag (Read Only) + Bit 2 - Sound 3 ON flag (Read Only) + Bit 1 - Sound 2 ON flag (Read Only) + Bit 0 - Sound 1 ON flag (Read Only) +Bits 0-3 of this register are read only status bits, writing to these bits +does NOT enable/disable sound. The flags get set when sound output is +restarted by setting the Initial flag (Bit 7 in NR14-NR44), the flag remains +set until the sound length has expired (if enabled). A volume envelopes which +has decreased to zero volume will NOT cause the sound flag to go off. + +Joypad Input +------------ + +FF00 - P1/JOYP - Joypad (R/W) +The eight gameboy buttons/direction keys are arranged in form of a 2x4 matrix. +Select either button or direction keys by writing to this register, then +read-out bit 0-3. + Bit 7 - Not used + Bit 6 - Not used + Bit 5 - P15 Select Button Keys (0=Select) + Bit 4 - P14 Select Direction Keys (0=Select) + Bit 3 - P13 Input Down or Start (0=Pressed) (Read Only) + Bit 2 - P12 Input Up or Select (0=Pressed) (Read Only) + Bit 1 - P11 Input Left or Button B (0=Pressed) (Read Only) + Bit 0 - P10 Input Right or Button A (0=Pressed) (Read Only) +Note: Most programs are repeatedly reading from this port several times (the +first reads used as short delay, allowing the inputs to stabilize, and only +the value from the last read actually used). + +Usage in SGB software +Beside for normal joypad input, SGB games mis-use the joypad register to +output SGB command packets to the SNES, also, SGB programs may read out +gamepad states from up to four different joypads which can be connected to the +SNES. +See SGB description for details. + +INT 60 - Joypad Interrupt +Joypad interrupt is requested when any of the above Input lines changes from +High to Low. Generally this should happen when a key becomes pressed (provided +that the button/direction key is enabled by above Bit4/5), however, because of +switch bounce, one or more High to Low transitions are usually produced both +when pressing or releasing a key. + +Using the Joypad Interrupt +It's more or less useless for programmers, even when selecting both buttons +and direction keys simultaneously it still cannot recognize all keystrokes, +because in that case a bit might be already held low by a button key, and +pressing the corresponding direction key would thus cause no difference. The +only meaningful purpose of the keystroke interrupt would be to terminate STOP +(low power) standby state. +Also, the joypad interrupt does not appear to work with CGB and GBA hardware +(the STOP function can be still terminated by joypad keystrokes though). + +Serial Data Transfer (Link Cable) +--------------------------------- + +FF01 - SB - Serial transfer data (R/W) +8 Bits of data to be read/written + +FF02 - SC - Serial Transfer Control (R/W) + Bit 7 - Transfer Start Flag (0=No Transfer, 1=Start) + Bit 1 - Clock Speed (0=Normal, 1=Fast) ** CGB Mode Only ** + Bit 0 - Shift Clock (0=External Clock, 1=Internal Clock) +The clock signal specifies the rate at which the eight data bits in SB (FF01) +are transferred. When the gameboy is communicating with another gameboy (or +other computer) then either one must supply internal clock, and the other one +must use external clock. + +Internal Clock +In Non-CGB Mode the gameboy supplies an internal clock of 8192Hz only +(allowing to transfer about 1 KByte per second). In CGB Mode four internal +clock rates are available, depending on Bit 1 of the SC register, and on +whether the CGB Double Speed Mode is used: + 8192Hz - 1KB/s - Bit 1 cleared, Normal + 16384Hz - 2KB/s - Bit 1 cleared, Double Speed Mode + 262144Hz - 32KB/s - Bit 1 set, Normal + 524288Hz - 64KB/s - Bit 1 set, Double Speed Mode + +External Clock +The external clock is typically supplied by another gameboy, but might be +supplied by another computer (for example if connected to a PCs parallel +port), in that case the external clock may have any speed. Even the +old/monochrome gameboy is reported to recognizes external clocks of up to +500KHz. And there is no limitiation into the other direction - even when +suppling an external clock speed of "1 bit per month", then the gameboy will +still eagerly wait for the next bit(s) to be transferred. It isn't required +that the clock pulses are sent at an regular interval either. + +Timeouts +When using external clock then the transfer will not complete until the last +bit is received. In case that the second gameboy isn't supplying a clock +signal, if it gets turned off, or if there is no second gameboy connected at +all) then transfer will never complete. For this reason the transfer procedure +should use a timeout counter, and abort the communication if no response has +been received during the timeout interval. + +Delays and Synchronization +The gameboy that is using internal clock should always execute a small delay +between each transfer, in order to ensure that the opponent gameboy has enough +time to prepare itself for the next transfer, ie. the gameboy with external +clock must have set its transfer start bit before the gameboy with internal +clock starts the transfer. Alternately, the two gameboys could switch between +internal and external clock for each transferred byte to ensure +synchronization. + +Transfer is initiated by setting the Transfer Start Flag. This bit is +automatically set to 0 at the end of Transfer. Reading this bit can be used to +determine if the transfer is still active. + +INT 58 - Serial Interrupt +When the transfer has completed (ie. after sending/receiving 8 bits, if any) +then an interrupt is requested by setting Bit 3 of the IF Register (FF0F). +When that interrupt is enabled, then the Serial Interrupt vector at 0058 is +called. + +XXXXXX... + +Transmitting and receiving serial data is done simultaneously. The received +data is automatically stored in SB. + +The serial I/O port on the Gameboy is a very simple setup and is crude +compared to standard RS-232 (IBM-PC) or RS-485 (Macintosh) serial ports. There +are no start or stop bits. + +During a transfer, a byte is shifted in at the same time that a byte is +shifted out. The rate of the shift is determined by whether the clock source +is internal or external. +The most significant bit is shifted in and out first. + +When the internal clock is selected, it drives the clock pin on the game link +port and it stays high when not used. During a transfer it will go low eight +times to clock in/out each bit. + +The state of the last bit shifted out determines the state of the output line +until another transfer takes place. + +If a serial transfer with internal clock is performed and no external GameBoy +is present, a value of $FF will be received in the transfer. + +The following code causes $75 to be shifted out the serial port and a byte to +be shifted into $FF01: + + ld a,$75 + ld ($FF01),a + ld a,$81 + ld ($FF02),a + +Timer and Divider Registers +--------------------------- + +FF04 - DIV - Divider Register (R/W) +This register is incremented at rate of 16384Hz (~16779Hz on SGB). In CGB +Double Speed Mode it is incremented twice as fast, ie. at 32768Hz. Writing any +value to this register resets it to 00h. + +FF05 - TIMA - Timer counter (R/W) +This timer is incremented by a clock frequency specified by the TAC register +($FF07). When the value overflows (gets bigger than FFh) then it will be reset +to the value specified in TMA (FF06), and an interrupt will be requested, as +described below. + +FF06 - TMA - Timer Modulo (R/W) +When the TIMA overflows, this data will be loaded. + +FF07 - TAC - Timer Control (R/W) + Bit 2 - Timer Stop (0=Stop, 1=Start) + Bits 1-0 - Input Clock Select + 00: 4096 Hz (~4194 Hz SGB) + 01: 262144 Hz (~268400 Hz SGB) + 10: 65536 Hz (~67110 Hz SGB) + 11: 16384 Hz (~16780 Hz SGB) + +INT 50 - Timer Interrupt +Each time when the timer overflows (ie. when TIMA gets bigger than FFh), then +an interrupt is requested by setting Bit 2 in the IF Register (FF0F). When +that interrupt is enabled, then the CPU will execute it by calling the timer +interrupt vector at 0050h. + +Note +The above described Timer is the built-in timer in the gameboy. It has nothing +to do with the MBC3s battery buffered Real Time Clock - that's a completely +different thing, described in the chapter about Memory Banking Controllers. + +Interrupts +---------- + +IME - Interrupt Master Enable Flag (Write Only) + 0 - Disable all Interrupts + 1 - Enable all Interrupts that are enabled in IE Register (FFFF) +The IME flag is used to disable all interrupts, overriding any enabled bits in +the IE Register. It isn't possible to access the IME flag by using a I/O +address, instead IME is accessed directly from the CPU, by the following +opcodes/operations: + EI ;Enable Interrupts (ie. IME=1) + DI ;Disable Interrupts (ie. IME=0) + RETI ;Enable Ints & Return (same as the opcode combination EI, RET) + ;Disable Ints & Call to Interrupt Vector +Whereas means the operation which is automatically executed by the CPU +when it executes an interrupt. + +FFFF - IE - Interrupt Enable (R/W) + Bit 0: V-Blank Interrupt Enable (INT 40h) (1=Enable) + Bit 1: LCD STAT Interrupt Enable (INT 48h) (1=Enable) + Bit 2: Timer Interrupt Enable (INT 50h) (1=Enable) + Bit 3: Serial Interrupt Enable (INT 58h) (1=Enable) + Bit 4: Joypad Interrupt Enable (INT 60h) (1=Enable) + +FF0F - IF - Interrupt Flag (R/W) + Bit 0: V-Blank Interrupt Request (INT 40h) (1=Request) + Bit 1: LCD STAT Interrupt Request (INT 48h) (1=Request) + Bit 2: Timer Interrupt Request (INT 50h) (1=Request) + Bit 3: Serial Interrupt Request (INT 58h) (1=Request) + Bit 4: Joypad Interrupt Request (INT 60h) (1=Request) +When an interrupt signal changes from low to high, then the corresponding bit +in the IF register becomes set. For example, Bit 0 becomes set when the LCD +controller enters into the V-Blank period. + +Interrupt Requests +Any set bits in the IF register are only an interrupt to be +executed. The actual happens only if both the IME flag, and the +corresponding bit in the IE register are set, otherwise the interrupt 'waits' +until both IME and IE allow its execution. + +Interrupt Execution +When an interrupt gets executed, the corresponding bit in the IF register +becomes automatically reset by the CPU, and the IME flag becomes cleared +(disabeling any further interrupts until the program re-enables the +interrupts, typically by using the RETI instruction), and the corresponding +Interrupt Vector (that are the addresses in range 0040h-0060h, as shown in IE +and IF register decriptions above) becomes called. + +Manually Requesting/Discarding Interrupts +As the CPU automatically sets and cleares the bits in the IF register it is +usually not required to write to the IF register. However, the user may still +do that in order to manually request (or discard) interrupts. As for real +interrupts, a manually requested interrupt isn't executed unless/until IME and +IE allow its execution. + +Interrupt Priorities +In the following three situations it might happen that more than 1 bit in the +IF register are set, requesting more than one interrupt at once: + 1) More than one interrupt signal changed from Low + to High at the same time. + 2) Several interrupts have been requested during a + time in which IME/IE didn't allow these interrupts + to be executed directly. + 3) The user has written a value with several "1" bits + (for example 1Fh) to the IF register. +Provided that IME and IE allow the execution of more than one of the requested +interrupts, then the interrupt with the highest priority becomes executed +first. The priorities are ordered as the bits in the IE and IF registers, Bit +0 (V-Blank) having the highest priority, and Bit 4 (Joypad) having the lowest +priority. + +Nested Interrupts +The CPU automatically disables all other interrupts by setting IME=0 when it +executes an interrupt. Usually IME remains zero until the interrupt procedure +returns (and sets IME=1 by the RETI instruction). However, if you want any +other interrupts of lower or higher (or same) priority to be allowed to be +executed from inside of the interrupt procedure, then you can place an EI +instruction into the interrupt procedure. + +CGB Registers +------------- + +Forward +This chapter describes only CGB (Color Gameboy) registers that didn't fit into +normal categories - most CGB registers are described in the chapter about +Video Display (Color Palettes, VRAM Bank, VRAM DMA Transfers, and changed +meaning of Bit 0 of LCDC Control register). Also, a changed bit is noted in +the chapter about the Serial/Link port. + +Unlocking CGB functions +When using any CGB registers (including those in the Video/Link chapters), you +must first unlock CGB features by changing byte 0143h in the cartridge header. +Typically use a value of 80h for games which support both CGB and monochrome +gameboys, and C0h for games which work on CGBs only. Otherwise, the CGB will +operate in monochrome "Non CGB" compatibility mode. + +Detecting CGB (and GBA) functions +CGB hardware can be detected by examing the CPU accumulator (A-register) +directly after startup. A value of 11h indicates CGB (or GBA) hardware, if so, +CGB functions can be used (if unlocked, see above). +When A=11h, you may also examine Bit 0 of the CPUs B-Register to separate +between CGB (bit cleared) and GBA (bit set), by that detection it is possible +to use 'repaired' color palette data matching for GBA displays. + +FF4D - KEY1 - CGB Mode Only - Prepare Speed Switch + Bit 7: Current Speed (0=Normal, 1=Double) (Read Only) + Bit 0: Prepare Speed Switch (0=No, 1=Prepare) (Read/Write) +This register is used to prepare the gameboy to switch between CGB Double +Speed Mode and Normal Speed Mode. The actual speed switch is performed by +executing a STOP command after Bit 0 has been set. After that Bit 0 will be +cleared automatically, and the gameboy will operate at the 'other' speed. The +recommended speed switching procedure in pseudo code would be: + IF KEY1_BIT7 <> DESIRED_SPEED THEN + IE=00H ;(FFFF)=00h + JOYP=30H ;(FF00)=30h + KEY1=01H ;(FF4D)=01h + STOP ;STOP + ENDIF +The CGB is operating in Normal Speed Mode when it is turned on. Note that +using the Double Speed Mode increases the power consumption, it would be +recommended to use Single Speed whenever possible. However, the display will +flicker (white) for a moment during speed switches, so this cannot be done +permanentely. +In Double Speed Mode the following will operate twice as fast as normal: + The CPU (2.10 MHz, 1 Cycle = approx. 0.5us) + Timer and Divider Registers + Serial Port (Link Cable) + DMA Transfer to OAM +And the following will keep operating as usual: + LCD Video Controller + HDMA Transfer to VRAM + All Sound Timings and Frequencies + +FF56 - RP - CGB Mode Only - Infrared Communications Port +This register allows to input and output data through the CGBs built-in +Infrared Port. When reading data, bit 6 and 7 must be set (and obviously Bit 0 +must be cleared - if you don't want to receive your own gameboys IR signal). +After sending or receiving data you should reset the register to 00h to reduce +battery power consumption again. + Bit 0: Write Data (0=LED Off, 1=LED On) (Read/Write) + Bit 1: Read Data (0=Receiving IR Signal, 1=Normal) (Read Only) + Bit 6-7: Data Read Enable (0=Disable, 3=Enable) (Read/Write) +Note that the receiver will adapt itself to the normal level of IR pollution +in the air, so if you would send a LED ON signal for a longer period, then the +receiver would treat that as normal (=OFF) after a while. For example, a +Philips TV Remote Control sends a series of 32 LED ON/OFF pulses (length 10us +ON, 17.5us OFF each) instead of a permanent 880us LED ON signal. +Even though being generally CGB compatible, the GBA does not include an +infra-red port. + +FF70 - SVBK - CGB Mode Only - WRAM Bank +In CGB Mode 32 KBytes internal RAM are available. This memory is divided into +8 banks of 4 KBytes each. Bank 0 is always available in memory at C000-CFFF, +Bank 1-7 can be selected into the address space at D000-DFFF. + Bit 0-2 Select WRAM Bank (Read/Write) +Writing a value of 01h-07h will select Bank 1-7, writing a value of 00h will +select Bank 1 either. + +FF6C - Undocumented (FEh) - Bit 0 (Read/Write) - CGB Mode Only +FF72 - Undocumented (00h) - Bit 0-7 (Read/Write) +FF73 - Undocumented (00h) - Bit 0-7 (Read/Write) +FF74 - Undocumented (00h) - Bit 0-7 (Read/Write) - CGB Mode Only +FF75 - Undocumented (8Fh) - Bit 4-6 (Read/Write) +FF76 - Undocumented (00h) - Always 00h (Read Only) +FF77 - Undocumented (00h) - Always 00h (Read Only) +These are undocumented CGB Registers. The numbers in brackets () indicate the +initial values. Purpose of these registers is unknown (if any). Registers FF6C +and FF74 are always FFh if the CGB is in Non CGB Mode. + +SGB Functions +------------- + +General Information +--> SGB Description +--> SGB Unlocking and Detecting SGB Functions +--> SGB Command Packet Transfers +--> SGB VRAM Transfers +--> SGB Command Summary +--> SGB Color Palettes Overview + +SGB Commands +--> SGB Palette Commands +--> SGB Color Attribute Commands +--> SGB Sound Functions +--> SGB System Control Commands +--> SGB Multiplayer Command +--> SGB Border and OBJ Commands + +SGB Description +--------------- + +General Description +Basically, the SGB (Super Gameboy) is an adapter cartridge that allows to play +gameboy games on a SNES (Super Nintendo Entertainment System) gaming console. +In detail, you plug the gameboy cartridge into the SGB cartridge, then plug +the SGB cartridge into the SNES, and then connect the SNES to your TV Set. In +result, games can be played and viewed on the TV Set, and are controlled by +using the SNES joypad(s). + +More Technical Description +The SGB cartridge just contains a normal gameboy CPU and normal gameboy video +controller. Normally the video signal from this controller would be sent to +the LCD screen, however, in this special case the SNES read out the video +signal and displays it on the TV set by using a special SNES BIOS ROM which is +located in the SGB cartridge. Also, normal gameboy sound output is forwared to +the SNES and output to the TV Set, vice versa, joypad input is forwared from +the SNES controller(s) to the gameboy joypad inputs. + +Normal Monochrome Games +Any gameboy games which have been designed for normal monochrome handheld +gameboys will work with the SGB hardware as well. The SGB will apply a four +color palette to these games by replacing the normal four grayshades. The +160x144 pixel gamescreen is displayed in the middle of the 256x224 pixel SNES +screen (the unused area is filled by a screen border bitmap). The user may +access built-in menues, allowing to change color palette data, to select +between several pre-defined borders, etc. + +Games that have been designed to support SGB functions may also access the +following additional features: + +Colorized Game Screen +There's limited ability to colorize the gamescreen by assigning custom color +palettes to each 20x18 display characters, however, this works mainly for +static display data such like title screens or status bars, the 20x18 color +attribute map is non-scrollable, and it is not possible to assign separate +colors to moveable foreground sprites (OBJs), so that animated screen regions +will be typically restricted to using a single palette of four colors only. + +SNES Foreground Sprites +Up to 24 foreground sprites (OBJs) of 8x8 or 16x16 pixels, 16 colors can be +displayed. When replacing (or just overlaying) the normal gameboy OBJs by SNES +OBJs it'd be thus possible to display OBJs with other colors than normal +background area. This method doesn't appear to be very popular, even though it +appears to be quite easy to implement, however, the bottommost character line +of the gamescreen will be masked out because this area is used to transfer OAM +data to the SNES. + +The SGB Border +The possibly most popular and most impressive feature is to replace the +default SGB screen border by a custom bitmap which is stored in the game +cartridge. + +Multiple Joypads +Up to four joypads can be conected to the SNES, and SGB software may read-out +each of these joypads separately, allowing up to four players to play the same +game simultaneously. Unlike for multiplayer handheld games, this requires only +one game cartridge and only one SGB/SNES, and no link cables are required, the +downside is that all players must share the same display screen. + +Sound Functions +Beside for normal gameboy sound, a number of digital sound effects is +pre-defined in the SNES BIOS, these effects may be accessed quite easily. +Programmers whom are familiar with SNES sounds may also access the SNES sound +chip, or use the SNES MIDI engine directly in order to produce other sound +effects or music. + +Taking Control of the SNES CPU +Finally, it is possible to write program code or data into SNES memory, and to +execute such program code by using the SNES CPU. + +SGB System Clock +Because the SGB is synchronized to the SNES CPU, the gameboy system clock is +directly chained to the SNES system clock. In result, the gameboy CPU, video +controller, timers, and sound frequencies will be all operated approx 2.4% +faster as by normal gameboys. +Basically, this should be no problem, and the game will just run a little bit +faster. However sensitive musicians may notice that sound frequencies are a +bit too high, programs that support SGB functions may avoid this effect by +reducing frequencies of gameboy sounds when having detected SGB hardware. +Also, I think that I've heard that SNES models which use a 50Hz display +refresh rate (rather than 60Hz) are resulting in respectively slower +SGB/gameboy timings ??? + +SGB Unlocking and Detecting SGB Functions +----------------------------------------- + +Cartridge Header +SGB games are required to have a cartridge header with Nintendo and proper +checksum just as normal gameboy games. Also, two special entries must be set +in order to unlock SGB functions: + 146h - SGB Flag - Must be set to 03h for SGB games + 14Bh - Old Licensee Code - Must be set 33h for SGB games +When these entries aren't set, the game will still work just like all +'monochrome' gameboy games, but it cannot access any of the special SGB +functions. + +Detecting SGB hardware +The recommended detection method is to send a MLT_REQ command which enables +two (or four) joypads. A normal handheld gameboy will ignore this command, a +SGB will now return incrementing joypad IDs each time when deselecting +keyboard lines (see MLT_REQ description for details). +Now read-out joypad state/IDs several times, and if the ID-numbers are +changing, then it is a SGB (a normal gameboy would typically always return 0Fh +as ID). Finally, when not intending to use more than one joypad, send another +MLT_REQ command in order to re-disable the multi-controller mode. +Detection works regardless of whether and how many joypads are physically +connected to the SNES. However, detection works only when having unlocked SGB +functions in the cartridge header, as described above. + +Separating between SGB and SGB2 +It is also possible to separate between SGB and SGB2 models by examining the +inital value of the accumulator (A-register) directly after startup. + 01h SGB or Normal Gameboy (DMG) + FFh SGB2 or Pocket Gameboy + 11h CGB or GBA +Because values 01h and FFh are shared for both handhelds and SGBs, it is still +required to use the above MLT_REQ detection procedure. As far as I know the +SGB2 doesn't have any extra features which'd require separate SGB2 detection +except for curiosity purposes, for example, the game "Tetris DX" chooses to +display an alternate SGB border on SGB2s. + +Reportedly, some SGB models include link ports (just like handheld gameboy) +(my own SGB does not have such an port), possibly this feature is available in +SGB2-type models only ??? + +SGB Command Packet Transfers +---------------------------- + +Command packets (aka Register Files) are transferred from the gameboy to the +SNES by using P14 and P15 output lines of the JOYPAD register (FF00h), these +lines are normally used to select the two rows in the gameboy keyboard matrix +(which still works). + +Transferring Bits +A command packet transfer must be initiated by setting both P14 and P15 to +LOW, this will reset and start the SNES packet receiving program. Data is then +transferred (LSB first), setting P14=LOW will indicate a "0" bit, and setting +P15=LOW will indicate a "1" bit. For example: + RESET 0 0 1 1 0 1 0 + P14 --_---_---_-----------_-------_--... + P15 --_-----------_---_-------_------... +Data and reset pulses must be kept LOW for at least 5us. P14 and P15 must be +kept both HIGH for at least 15us between any pulses. +Obviously, it'd be no good idea to access the JOYPAD register during the +transfer, for example, in case that your VBlank interrupt procedure reads-out +joypad states each frame, be sure to disable that interrupt during the +transfer (or disable only the joypad procedure by using a software flag). + +Transferring Packets +Each packet is invoked by a RESET pulse, then 128 bits of data are transferred +(16 bytes, LSB of first byte first), and finally, a "0"-bit must be +transferred as stop bit. The structure of normal packets is: + 1 PULSE Reset + 1 BYTE Command Code*8+Length + 15 BYTES Parameter Data + 1 BIT Stop Bit (0) +The above 'Length' indicates the total number of packets (1-7, including the +first packet) which will be sent, ie. if more than 15 parameter bytes are +used, then further packet(s) will follow, as such: + 1 PULSE Reset + 16 BYTES Parameter Data + 1 BIT Stop Bit (0) +By using all 7 packets, up to 111 data bytes (15+16*6) may be sent. +Unused bytes at the end of the last packet must be set to zero. +A 60ms (4 frames) delay should be invoked between each packet transfer. + +SGB VRAM Transfers +------------------ + +Overview +Beside for the packet transfer method, larger data blocks of 4KBytes can be +transferred by using the video signal. These transfers are invoked by first +sending one of the commands with the ending _TRN (by using normal packet +transfer), the 4K data block is then read-out by the SNES from gameboy display +memory during the next frame. + +Transfer Data +Normally, transfer data should be stored at 8000h-8FFFh in gameboy VRAM, +even though the SNES receives the data in from display scanlines, it will +automatically re-produce the same ordering of bits and bytes, as being +originally stored at 8000h-8FFFh in gameboy memory. + +Preparing the Display +The above method works only when recursing the following things: BG Map must +display unsigned characters 00h-FFh on the screen; 00h..13h in first line, +14h..27h in next line, etc. The gameboy display must be enabled, the display +may not be scrolled, OBJ sprites should not overlap the background tiles, the +BGP palette register must be set to E4h. + +Transfer Time +Note that the transfer data should be prepared in VRAM sending the +transfer command packet. The actual transfer starts at the beginning of the +next frame after the command has been sent, and the transfer ends at the end +of the 5th frame after the command has been sent (not counting the frame in +which the command has been sent). + +Avoiding Screen Garbage +The display will contain 'garbage' during the transfer, this dirt-effect can +be avoided by freezing the screen (in the state which has been displayed +before the transfer) by using the MASK_EN command. +Of course, this works only when actually executing the game on a SGB (and not +on normal handheld gameboys), it'd be thus required to detect the presence of +SGB hardware before blindly sending VRAM data. + +SGB Command Summary +------------------- + +SGB System Command Table + Code Name Expl. + 00 PAL01 Set SGB Palette 0,1 Data + 01 PAL23 Set SGB Palette 2,3 Data + 02 PAL03 Set SGB Palette 0,3 Data + 03 PAL12 Set SGB Palette 1,2 Data + 04 ATTR_BLK "Block" Area Designation Mode + 05 ATTR_LIN "Line" Area Designation Mode + 06 ATTR_DIV "Divide" Area Designation Mode + 07 ATTR_CHR "1CHR" Area Designation Mode + 08 SOUND Sound On/Off + 09 SOU_TRN Transfer Sound PRG/DATA + 0A PAL_SET Set SGB Palette Indirect + 0B PAL_TRN Set System Color Palette Data + 0C ATRC_EN Enable/disable Attraction Mode + 0D TEST_EN Speed Function + 0E ICON_EN SGB Function + 0F DATA_SND SUPER NES WRAM Transfer 1 + 10 DATA_TRN SUPER NES WRAM Transfer 2 + 11 MLT_REG Controller 2 Request + 12 JUMP Set SNES Program Counter + 13 CHR_TRN Transfer Character Font Data + 14 PCT_TRN Set Screen Data Color Data + 15 ATTR_TRN Set Attribute from ATF + 16 ATTR_SET Set Data to ATF + 17 MASK_EN Game Boy Window Mask + 18 OBJ_TRN Super NES OBJ Mode + +SGB Color Palettes Overview +--------------------------- + +Available SNES Palettes +The SGB/SNES provides 8 palettes of 16 colors each, each color may be defined +out of a selection of 34768 colors (15 bit). Palettes 0-3 are used to colorize +the gamescreen, only the first four colors of each of these palettes are used. +Palettes 4-7 are used for the SGB Border, all 16 colors of each of these +palettes may be used. + +Color 0 Restriction +Color 0 of each of the eight palettes is transparent, causing the backdrop +color to be displayed instead. The backdrop color is typically defined by the +most recently color being assigned to Color 0 (regardless of the palette +number being used for that operation). +Effectively, gamescreen palettes can have only three custom colors each, and +SGB border palettes only 15 colors each, additionally, color 0 can be used for +for all palettes, which will then all share the same color though. + +Translation of Grayshades into Colors +Because the SGB/SNES reads out the gameboy video controllers display signal, +it translates the different grayshades from the signal into SNES colors as +such: + White --> Color 0 + Light Gray --> Color 1 + Dark Gray --> Color 2 + Black --> Color 3 +Note that gameboy colors 0-3 are assigned to user-selectable grayshades by the +gameboys BGP, OBP1, and OBP2 registers. There is thus no fixed relationship +between gameboy colors 0-3 and SNES colors 0-3. + +Using Gameboy BGP/OBP Registers +A direct translation of color 0-3 into color 0-3 may be produced by setting +BGP/OBP registers to a value of 0E4h each. However, in case that your program +uses black background for example, then you may internally assign background +as "White" at the gameboy side by BGP/OBP registers (which is then interpreted +as SNES color 0, which is shared for all SNES palettes). The advantage is that +you may define Color 0 as Black at the SNES side, and may assign custom colors +for Colors 1-3 of each SNES palette. + +System Color Palette Memory +Beside for the actually visible palettes, up to 512 palettes of 4 colors each +may be defined in SNES RAM. Basically, this is completely irrelevant because +the palettes are just stored in RAM whithout any relationship to the displayed +picture, anyways, these pre-defined colors may be transferred to actually +visible palettes slightly faster as when transferring palette data by separate +command packets. + +SGB Palette Commands +-------------------- + +SGB Command 00h - PAL01 +Transmit color data for SGB palette 0, color 0-3, and for SGB palette 1, color +1-3 (without separate color 0). + Byte Content + 0 Command*8+Length (fixed length=01h) + 1-E Color Data for 7 colors of 2 bytes (16bit) each: + Bit 0-4 - Red Intensity (0-31) + Bit 5-9 - Green Intensity (0-31) + Bit 10-14 - Blue Intensity (0-31) + Bit 15 - Not used (zero) + F Not used (00h) +The value transferred as color 0 will be applied for all eight palettes. + +SGB Command 01h - PAL23 +Same as above PAL01, but for Palettes 2 and 3 respectively. + +SGB Command 02h - PAL03 +Same as above PAL01, but for Palettes 0 and 3 respectively. + +SGB Command 03h - PAL12 +Same as above PAL01, but for Palettes 1 and 2 respectively. + +SGB Command 0Ah - PAL_SET +Used to copy pre-defined palette data from SGB system color palette to actual +SGB palette. + Byte Content + 0 Command*8+Length (fixed length=1) + 1-2 System Palette number for SGB Color Palette 0 (0-511) + 3-4 System Palette number for SGB Color Palette 1 (0-511) + 5-6 System Palette number for SGB Color Palette 2 (0-511) + 7-8 System Palette number for SGB Color Palette 3 (0-511) + 9 Attribute File + Bit 0-5 - Attribute File Number (00h-2Ch) (Used only if Bit7=1) + Bit 6 - Cancel Mask (0=No change, 1=Yes) + Bit 7 - Use Attribute File (0=No, 1=Apply above ATF Number) + A-F Not used (zero) +Before using this function, System Palette data should be initialized by +PAL_TRN command, and (when used) Attribute File data should be initialized by +ATTR_TRN. + +SGB Command 0Bh - PAL_TRN +Used to initialize SGB system color palettes in SNES RAM. +System color palette memory contains 512 pre-defined palettes, these palettes +do not directly affect the display, however, the PAL_SET command may be later +used to transfer four of these 'logical' palettes to actual visible 'physical' +SGB palettes. Also, the OBJ_TRN function will use groups of 4 System Color +Palettes (4*4 colors) for SNES OBJ palettes (16 colors). + Byte Content + 0 Command*8+Length (fixed length=1) + 1-F Not used (zero) +The palette data is sent by VRAM-Transfer (4 KBytes). + 000-FFF Data for System Color Palette 0-511 +Each Palette consists of four 16bit-color definitions (8 bytes). +Note: The data is stored at 3000h-3FFFh in SNES memory. + +SGB Color Attribute Commands +---------------------------- + +SGB Command 04h - ATTR_BLK +Used to specify color attributes for the inside or outside of one or more +rectangular screen regions. + Byte Content + 0 Command*8+Length (length=1..7) + 1 Number of Data Sets (01h..12h) + 2-7 Data Set #1 + Byte 0 - Control Code (0-7) + Bit 0 - Change Colors inside of surrounded area (1=Yes) + Bit 1 - Change Colors of surrounding character line (1=Yes) + Bit 2 - Change Colors outside of surrounded area (1=Yes) + Bit 3-7 - Not used (zero) + Exception: When changing only the Inside or Outside, then the + Surrounding line becomes automatically changed to same color. + Byte 1 - Color Palette Designation + Bit 0-1 - Palette Number for inside of surrounded area + Bit 2-3 - Palette Number for surrounding character line + Bit 4-5 - Palette Number for outside of surrounded area + Bit 6-7 - Not used (zero) + Data Set Byte 2 - Coordinate X1 (left) + Data Set Byte 3 - Coordinate Y1 (upper) + Data Set Byte 4 - Coordinate X2 (right) + Data Set Byte 5 - Coordinate Y2 (lower) + Specifies the coordinates of the surrounding rectangle. + 8-D Data Set #2 (if any) + E-F Data Set #3 (continued at 0-3 in next packet) (if any) +When sending three or more data sets, data is continued in further packet(s). +Unused bytes at the end of the last packet should be set to zero. The format +of the separate Data Sets is described below. + +SGB Command 05h - ATTR_LIN +Used to specify color attributes of one or more horizontal or vertical +character lines. + Byte Content + 0 Command*8+Length (length=1..7) + 1 Number of Data Sets (01h..6Eh) (one byte each) + 2 Data Set #1 + Bit 0-4 - Line Number (X- or Y-coordinate, depending on bit 7) + Bit 5-6 - Palette Number (0-3) + Bit 7 - H/V Mode Bit (0=Vertical line, 1=Horizontal Line) + 3 Data Set #2 (if any) + 4 Data Set #3 (if any) + etc. +When sending 15 or more data sets, data is continued in further packet(s). +Unused bytes at the end of the last packet should be set to zero. The format +of the separate Data Sets (one byte each) is described below. +The length of each line reaches from one end of the screen to the other end. +In case that some lines overlap each other, then lines from lastmost data sets +will overwrite lines from previous data sets. + +SGB Command 06h - ATTR_DIV +Used to split the screen into two halfes, and to assign separate color +attributes to each half, and to the division line between them. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Color Palette Numbers and H/V Mode Bit + Bit 0-1 Palette Number below/right of division line + Bit 2-3 Palette Number above/left of division line + Bit 4-5 Palette Number for division line + Bit 6 H/V Mode Bit (0=split left/right, 1=split above/below) + 2 X- or Y-Coordinate (depending on H/V bit) + 3-F Not used (zero) + +SGB Command 07h - ATTR_CHR +Used to specify color attributes for separate characters. + Byte Content + 0 Command*8+Length (length=1..6) + 1 Beginning X-Coordinate + 2 Beginning Y-Coordinate + 3-4 Number of Data Sets (1-360) + 5 Writing Style (0=Left to Right, 1=Top to Bottom) + 6 Data Sets 1-4 (Set 1 in MSBs, Set 4 in LSBs) + 7 Data Sets 5-8 (if any) + 8 Data Sets 9-12 (if any) + etc. +When sending 41 or more data sets, data is continued in further packet(s). +Unused bytes at the end of the last packet should be set to zero. Each data +set consists of two bits, indicating the palette number for one character. +Depending on the writing style, data sets are written from left to right, or +from top to bottom. In either case the function wraps to the next row/column +when reaching the end of the screen. + +SGB Command 15h - ATTR_TRN +Used to initialize Attribute Files (ATFs) in SNES RAM. Each ATF consists of +20x18 color attributes for the gameboy screen. This function does not directly +affect display attributes. Instead, one of the defined ATFs may be copied to +actual display memory at a later time by using ATTR_SET or PAL_SET functions. + Byte Content + 0 Command*8+Length (fixed length=1) + 1-F Not used (zero) +The ATF data is sent by VRAM-Transfer (4 KBytes). + 000-FD1 Data for ATF0 through ATF44 (4050 bytes) + FD2-FFF Not used +Each ATF consists of 90 bytes, that are 5 bytes (20x2bits) for each of the 18 +character lines of the gameboy window. The two most significant bits of the +first byte define the color attribute (0-3) for the first character of the +first line, the next two bits the next character, and so on. + +SGB Command 16h - ATTR_SET +Used to transfer attributes from Attribute File (ATF) to gameboy window. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Attribute File Number (00-2Ch), Bit 6=Cancel Mask + 2-F Not used (zero) +When above Bit 6 is set, the gameboy screen becomes re-enabled after the +transfer (in case it has been disabled/frozen by MASK_EN command). +Note: The same functions may be (optionally) also included in PAL_SET +commands, as described in the chapter about Color Palette Commands. + +SGB Sound Functions +------------------- + +SGB Command 08h - SOUND +Used to start/stop internal sound effect, start/stop sound using internal tone +data. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Sound Effect A (Port 1) Decrescendo 8bit Sound Code + 2 Sound Effect B (Port 2) Sustain 8bit Sound Code + 3 Sound Effect Attributes + Bit 0-1 - Sound Effect A Pitch (0..3=Low..High) + Bit 2-3 - Sound Effect A Volume (0..2=High..Low, 3=Mute on) + Bit 4-5 - Sound Effect B Pitch (0..3=Low..High) + Bit 6-7 - Sound Effect B Volume (0..2=High..Low, 3=Not used) + 4 Music Score Code (must be zero if not used) + 5-F Not used (zero) +See Sound Effect Tables below for a list of available pre-defined effects. +"Notes" +1) Mute is only active when both bits D2 and D3 are 1. +2) When the volume is set for either Sound Effect A or Sound Effect B, mute is +turned off. +3) When Mute on/off has been executed, the sound fades out/fades in. +4) Mute on/off operates on the (BGM) which is reproduced by Sound Effect A, +Sound Effect B, and the Super NES APU. A "mute off" flag does not exist by +itself. When mute flag is set, volume and pitch of Sound Effect A (port 1) and +Sound Effect B (port 2) must be set. + +SGB Command 09h - SOU_TRN +Used to transfer sound code or data to SNES Audio Processing Unit memory +(APU-RAM). + Byte Content + 0 Command*8+Length (fixed length=1) + 1-F Not used (zero) +The sound code/data is sent by VRAM-Transfer (4 KBytes). + 000 One (or two ???) 16bit expression(s ???) indicating the + transfer destination address and transfer length. + ...-... Transfer Data + ...-FFF Remaining bytes not used +Possible destinations in APU-RAM are: + 0400h-2AFFh APU-RAM Program Area (9.75KBytes) + 2B00h-4AFFh APU-RAM Sound Score Area (8Kbytes) + 4DB0h-EEFFh APU-RAM Sampling Data Area (40.25 Kbytes) +This function may be used to take control of the SNES sound chip, and/or to +access the SNES MIDI engine. In either case it requires deeper knowledge of +SNES sound programming. + +SGB Sound Effect A/B Tables +Below lists the digital sound effects that are pre-defined in the SGB/SNES +BIOS, and which can be used with the SGB "SOUND" Command. +Effect A and B may be simultaneously reproduced. +The P-column indicates the recommended Pitch value, the V-column indicates the +numbers of Voices used. Sound Effect A uses voices 6,7. Sound Effect B uses +voices 0,1,4,5. Effects that use less voices will use only the upper voices +(eg. 4,5 for Effect B with only two voices). + +Sound Effect A Flag Table + Code Description P V Code Description P V + 00 Dummy flag, re-trigger - 2 18 Fast Jump 3 1 + 80 Effect A, stop/silent - 2 19 Jet (rocket) takeoff 0 1 + 01 Nintendo 3 1 1A Jet (rocket) landing 0 1 + 02 Game Over 3 2 1B Cup breaking 2 2 + 03 Drop 3 1 1C Glass breaking 1 2 + 04 OK ... A 3 2 1D Level UP 2 2 + 05 OK ... B 3 2 1E Insert air 1 1 + 06 Select...A 3 2 1F Sword swing 1 1 + 07 Select...B 3 1 20 Water falling 2 1 + 08 Select...C 2 2 21 Fire 1 1 + 09 Mistake...Buzzer 2 1 22 Wall collapsing 1 2 + 0A Catch Item 2 2 23 Cancel 1 2 + 0B Gate squeaks 1 time 2 2 24 Walking 1 2 + 0C Explosion...small 1 2 25 Blocking strike 1 2 + 0D Explosion...medium 1 2 26 Picture floats on & off 3 2 + 0E Explosion...large 1 2 27 Fade in 0 2 + 0F Attacked...A 3 1 28 Fade out 0 2 + 10 Attacked...B 3 2 29 Window being opened 1 2 + 11 Hit (punch)...A 0 2 2A Window being closed 0 2 + 12 Hit (punch)...B 0 2 2B Big Laser 3 2 + 13 Breath in air 3 2 2C Stone gate closes/opens 0 2 + 14 Rocket Projectile...A 3 2 2D Teleportation 3 1 + 15 Rocket Projectile...B 3 2 2E Lightning 0 2 + 16 Escaping Bubble 2 1 2F Earthquake 0 2 + 17 Jump 3 1 30 Small Laser 2 2 +Sound effect A is used for formanto sounds (percussion sounds). + +Sound Effect B Flag Table + Code Description P V Code Description P V + 00 Dummy flag, re-trigger - 4 0D Waterfall 2 2 + 80 Effect B, stop/silent - 4 0E Small character running 3 1 + 01 Applause...small group 2 1 0F Horse running 3 1 + 02 Applause...medium group 2 2 10 Warning sound 1 1 + 03 Applause...large group 2 4 11 Approaching car 0 1 + 04 Wind 1 2 12 Jet flying 1 1 + 05 Rain 1 1 13 UFO flying 2 1 + 06 Storm 1 3 14 Electromagnetic waves 0 1 + 07 Storm with wind/thunder 2 4 15 Score UP 3 1 + 08 Lightning 0 2 16 Fire 2 1 + 09 Earthquake 0 2 17 Camera shutter, formanto 3 4 + 0A Avalanche 0 2 18 Write, formanto 0 1 + 0B Wave 0 1 19 Show up title, formanto 0 1 + 0C River 3 2 +Sound effect B is mainly used for looping sounds (sustained sounds). + +SGB System Control Commands +--------------------------- + +SGB Command 17h - MASK_EN +Used to mask the gameboy window, among others this can be used to freeze the +gameboy screen before transferring data through VRAM (the SNES then keeps +displaying the gameboy screen, even though VRAM doesn't contain meaningful +display information during the transfer). + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Gameboy Screen Mask (0-3) + 0 Cancel Mask (Display activated) + 1 Freeze Screen (Keep displaying current picture) + 2 Blank Screen (Black) + 3 Blank Screen (Color 0) + 2-F Not used (zero) +Freezing works only if the SNES has stored a picture, ie. if necessary wait +one or two frames before freezing (rather than freezing directly after having +displayed the picture). +The Cancel Mask function may be also invoked (optionally) by completion of +PAL_SET and ATTR_SET commands. + +SGB Command 0Ch - ATRC_EN +Used to enable/disable Attraction mode. It is totally unclear what an +attraction mode is ???, but it is enabled by default. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Attraction Disable (0=Enable, 1=Disable) + 2-F Not used (zero) + +SGB Command 0Dh - TEST_EN +Used to enable/disable test mode for "SGB-CPU variable clock speed function". +This function is disabled by default. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Test Mode Enable (0=Disable, 1=Enable) + 2-F Not used (zero) +Maybe intended to determine whether SNES operates at 50Hz or 60Hz display +refresh rate ??? Possibly result can be read-out from joypad register ??? + +SGB Command 0Eh - ICON_EN +Used to enable/disable ICON function. Possibly meant to enable/disable +SGB/SNES popup menues which might otherwise activated during gameboy game +play. By default all functions are enabled (0). + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Disable Bits + Bit 0 - Use of SGB-Built-in Color Palettes (1=Disable) + Bit 1 - Controller Set-up Screen (0=Enable, 1=Disable) + Bit 2 - SGB Register File Transfer (0=Receive, 1=Disable) + Bit 3-6 - Not used (zero) + 2-F Not used (zero) +Above Bit 2 will suppress all further packets/commands when set, this might be +useful when starting a monochrome game from inside of the SGB-menu of a +multi-gamepak which contains a collection of different games. + +SGB Command 0Fh - DATA_SND +Used to write one or more bytes directly into SNES Work RAM. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 SNES Destination Address, low + 2 SNES Destination Address, high + 3 SNES Destination Address, bank number + 4 Number of bytes to write (01h-0Bh) + 5 Data Byte #1 + 6 Data Byte #2 (if any) + 7 Data Byte #3 (if any) + etc. +Unused bytes at the end of the packet should be set to zero, this function is +restricted to a single packet, so that not more than 11 bytes can be defined +at once. +Free Addresses in SNES memory are Bank 0 1800h-1FFFh, Bank 7Fh 0000h-FFFFh. + +SGB Command 10h - DATA_TRN +Used to transfer binary code or data directly into SNES RAM. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 SNES Destination Address, low + 2 SNES Destination Address, high + 3 SNES Destination Address, bank number + 4-F Not used (zero) +The data is sent by VRAM-Transfer (4 KBytes). + 000-FFF Data +Free Addresses in SNES memory are Bank 0 1800h-1FFFh, Bank 7Fh 0000h-FFFFh. +The transfer length is fixed at 4KBytes ???, so that directly writing to the +free 2KBytes at 0:1800h would be a not so good idea ??? + +SGB Command 12h - JUMP +Used to set the SNES program counter to a specified address. Optionally, it +may be used to set a new address for the SNES NMI handler, the NMI handler +remains unchanged if all bytes 4-6 are zero. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 SNES Program Counter, low + 2 SNES Program Counter, high + 3 SNES Program Counter, bank number + 4 SNES NMI Handler, low + 5 SNES NMI Handler, high + 6 SNES NMI Handler, bank number + 7-F Not used, zero +Note: The game "Space Invaders 94" uses this function when selecting "Arcade +mode" to execute SNES program code which has been previously transferred from +the SGB to the SNES. The type of the CPU which is used in the SNES is unknown +??? + +SGB Multiplayer Command +----------------------- + +SGB Command 11h - MLT_REQ +Used to request multiplayer mode (ie. input from more than one joypad). +Because this function provides feedback from the SGB/SNES to the gameboy +program, it is also used to detect SGB hardware. + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Multiplayer Control (0-3) (Bit0=Enable, Bit1=Two/Four Players) + 0 = One player + 1 = Two players + 3 = Four players + 2-F Not used (zero) +In one player mode, the second joypad (if any) is used for the SGB system +program. In two player mode, both joypads are used for the game. Because SNES +have only two joypad sockets, four player mode requires an external +"Multiplayer 5" adapter. + +Reading Multiple Controllers (Joypads) +When having enabled multiple controllers by MLT_REQ, data for each joypad can +be read out through JOYPAD register (FF00) as follows: First set P14 and P15 +both HIGH (deselect both Buttons and Cursor keys), you can now read the lower +4bits of FF00 which indicate the joypad ID for the following joypad input: + 0Fh Joypad 1 + 0Eh Joypad 2 + 0Dh Joypad 3 + 0Ch Joypad 4 +Next, set P14 and P15 low (one after each other) to select Buttons and Cursor +lines, and read-out joypad state as normally. When completed, set P14 and P15 +back HIGH, this automatically increments the joypad number (or restarts +counting once reached the lastmost joypad). Repeat the procedure until you +have read-out states for all two (or four) joypads. + +SGB Border and OBJ Commands +--------------------------- + +SGB Command 13h - CHR_TRN +Used to transfer tile data (characters) to SNES Tile memory in VRAM. This +normally used to define BG tiles for the SGB Border (see PCT_TRN), but might +be also used to define moveable SNES foreground sprites (see OBJ_TRN). + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Tile Transfer Destination + Bit 0 - Tile Numbers (0=Tiles 00h-7Fh, 1=Tiles 80h-FFh) + Bit 1 - Tile Type (0=BG Tiles, 1=OBJ Tiles) + Bit 2-7 - Not used (zero) + 2-F Not used (zero) +The tile data is sent by VRAM-Transfer (4 KBytes). + 000-FFF Bitmap data for 128 Tiles +Each tile occupies 16bytes (8x8 pixels, 16 colors each). +When intending to transfer more than 128 tiles, call this function twice (once +for tiles 00h-7Fh, and once for tiles 80h-FFh). Note: The BG/OBJ Bit seems to +have no effect and writes to the same VRAM addresses for both BG and OBJ ??? + +SGB Command 14h - PCT_TRN +Used to transfer tile map data and palette data to SNES BG Map memory in VRAM +to be used for the SGB border. The actual tiles must be separately transferred +by using the CHR_TRN function. + Byte Content + 0 Command*8+Length (fixed length=1) + 1-F Not used (zero) +The map data is sent by VRAM-Transfer (4 KBytes). + 000-7FF BG Map 32x32 Entries of 16bit each (2048 bytes) + 800-87F BG Palette Data (Palettes 4-7, each 16 colors of 16bits each) + 880-FFF Not used, don't care +Each BG Map Entry consists of a 16bit value as such: + Bit 0-9 - Character Number (use only 00h-FFh, upper 2 bits zero) + Bit 10-12 - Palette Number (use only 4-7, officially use only 4-6) + Bit 13 - BG Priority (use only 0) + Bit 14 - X-Flip (0=Normal, 1=Mirror horizontally) + Bit 15 - Y-Flip (0=Normal, 1=Mirror vertically) +Even though 32x32 map entries are transferred, only upper 32x28 are actually +used (256x224 pixels, SNES screen size). The 20x18 entries in the center of +the 32x28 area should be set to 0000h as transparent space for the gameboy +window to be displayed inside. Reportedly, non-transparent border data will +cover the gameboy window. + +SGB Command 18h - OBJ_TRN +Used to transfer OBJ attributes to SNES OAM memory. Unlike all other functions +with the ending _TRN, this function does not use the usual one-shot 4KBytes +VRAM transfer method. +Instead, when enabled (below execute bit set), data is permanently (each +frame) read out from the lower character line of the gameboy screen. To +suppress garbage on the display, the lower line is masked, and only the upper +20x17 characters of the gameboy window are used - the masking method is +unknwon - frozen, black, or recommended to be covered by the SGB border, or +else ??? Also, when the function is enabled, "system attract mode is not +performed" - whatever that means ??? + Byte Content + 0 Command*8+Length (fixed length=1) + 1 Control Bits + Bit 0 - SNES OBJ Mode enable (0=Cancel, 1=Enable) + Bit 1 - Change OBJ Color (0=No, 1=Use definitions below) + Bit 2-7 - Not used (zero) + 2-3 System Color Palette Number for OBJ Palette 4 (0-511) + 4-5 System Color Palette Number for OBJ Palette 5 (0-511) + 6-7 System Color Palette Number for OBJ Palette 6 (0-511) + 8-9 System Color Palette Number for OBJ Palette 7 (0-511) + These color entries are ignored if above Control Bit 1 is zero. + Because each OBJ palette consists of 16 colors, four system + palette entries (of 4 colors each) are transferred into each + OBJ palette. The system palette numbers are not required to be + aligned to a multiple of four, and will wrap to palette number + 0 when exceeding 511. For example, a value of 511 would copy + system palettes 511, 0, 1, 2 to the SNES OBJ palette. + A-F Not used (zero) +The recommended method is to "display" gameboy BG tiles F9h..FFh from left to +right as first 7 characters of the bottom-most character line of the gameboy +screen. As for normal 4KByte VRAM transfers, this area should not be scrolled, +should not be overlapped by gameboy OBJs, and the gameboy BGP palette register +should be set up properly. By following that method, SNES OAM data can be +defined in the 70h bytes of the gameboy BG tile memory at following addresses: + 8F90-8FEF SNES OAM, 24 Entries of 4 bytes each (96 bytes) + 8FF0-8FF5 SNES OAM MSBs, 24 Entries of 2 bits each (6 bytes) + 8FF6-8FFF Not used, don't care (10 bytes) +The format of SNES OAM Entries is: + Byte 0 OBJ X-Position (0-511, MSB is separately stored, see below) + Byte 1 OBJ Y-Position (0-255) + Byte 2-3 Attributes (16bit) + Bit 0-8 Tile Number (use only 00h-FFh, upper bit zero) + Bit 9-11 Palette Number (use only 4-7) + Bit 12-13 OBJ Priority (use only 3) + Bit 14 X-Flip (0=Normal, 1=Mirror horizontally) + Bit 15 Y-Flip (0=Normal, 1=Mirror vertically) +The format of SNES OAM MSB Entries is: + Actually, the format is unknown ??? However, 2 bits are used per entry: + One bit is the most significant bit of the OBJ X-Position. + The other bit specifies the OBJ size (8x8 or 16x16 pixels). + +CPU Registers and Flags +----------------------- + +Registers + 16bit Hi Lo Name/Function + AF A - Accumulator & Flags + BC B C BC + DE D E DE + HL H L HL + SP - - Stack Pointer + PC - - Program Counter/Pointer +As shown above, most registers can be accessed either as one 16bit register, +or as two separate 8bit registers. + +The Flag Register (lower 8bit of AF register) + Bit Name Set Clr Expl. + 7 zf Z NZ Zero Flag + 6 n - - Add/Sub-Flag (BCD) + 5 h - - Half Carry Flag (BCD) + 4 cy C NC Carry Flag + 3-0 - - - Not used (always zero) +Conatins the result from the recent instruction which has affected flags. + +The Zero Flag (Z) +This bit becomes set (1) if the result of an operation has been zero (0). Used +for conditional jumps. + +The Carry Flag (C, or Cy) +Becomes set when the result of an addition became bigger than FFh (8bit) or +FFFFh (16bit). Or when the result of a subtraction or comparision became less +than zero (much as for Z80 and 80x86 CPUs, but unlike as for 65XX and ARM +CPUs). Also the flag becomes set when a rotate/shift operation has shifted-out +a "1"-bit. +Used for conditional jumps, and for instructions such like ADC, SBC, RL, RLA, +etc. + +The BCD Flags (N, H) +These flags are (rarely) used for the DAA instruction only, N Indicates +whether the previous instruction has been an addition or subtraction, and H +indicates carry for lower 4bits of the result, also for DAA, the C flag must +indicate carry for upper 8bits. +After adding/subtracting two BCD numbers, DAA is intended to convert the +result into BCD format; BCD numbers are ranged from 00h to 99h rather than 00h +to FFh. +Because C and H flags must contain carry-outs for each digit, DAA cannot be +used for 16bit operations (which have 4 digits), or for INC/DEC operations +(which do not affect C-flag). + +CPU Instruction Set +------------------- + +Tables below specify the mnemonic, opcode bytes, clock cycles, affected flags +(ordered as znhc), and explanatation. +The timings assume a CPU clock frequency of 4.194304 MHz (or 8.4 +MHz for CGB in double speed mode), as all gameboy timings are divideable +by 4, many people specify timings and clock frequency divided by 4. + +GMB 8bit-Loadcommands + ld r,r xx 4 ---- r=r + ld r,n xx nn 8 ---- r=n + ld r,(HL) xx 8 ---- r=(HL) + ld (HL),r 7x 8 ---- (HL)=r + ld (HL),n 36 nn 12 ---- + ld A,(BC) 0A 8 ---- + ld A,(DE) 1A 8 ---- + ld A,(nn) FA 16 ---- + ld (BC),A 02 8 ---- + ld (DE),A 12 8 ---- + ld (nn),A EA 16 ---- + ld A,(FF00+n) F0 nn 12 ---- read from io-port n (memory FF00+n) + ld (FF00+n),A E0 nn 12 ---- write to io-port n (memory FF00+n) + ld A,(FF00+C) F2 8 ---- read from io-port C (memory FF00+C) + ld (FF00+C),A E2 8 ---- write to io-port C (memory FF00+C) + ldi (HL),A 22 8 ---- (HL)=A, HL=HL+1 + ldi A,(HL) 2A 8 ---- A=(HL), HL=HL+1 + ldd (HL),A 32 8 ---- (HL)=A, HL=HL-1 + ldd A,(HL) 3A 8 ---- A=(HL), HL=HL-1 + +GMB 16bit-Loadcommands + ld rr,nn x1 nn nn 12 ---- rr=nn (rr may be BC,DE,HL or SP) + ld SP,HL F9 8 ---- SP=HL + push rr x5 16 ---- SP=SP-2 (SP)=rr (rr may be +BC,DE,HL,AF) + pop rr x1 12 (AF) rr=(SP) SP=SP+2 (rr may be +BC,DE,HL,AF) + +GMB 8bit-Arithmetic/logical Commands + add A,r 8x 4 z0hc A=A+r + add A,n C6 nn 8 z0hc A=A+n + add A,(HL) 86 8 z0hc A=A+(HL) + adc A,r 8x 4 z0hc A=A+r+cy + adc A,n CE nn 8 z0hc A=A+n+cy + adc A,(HL) 8E 8 z0hc A=A+(HL)+cy + sub r 9x 4 z1hc A=A-r + sub n D6 nn 8 z1hc A=A-n + sub (HL) 96 8 z1hc A=A-(HL) + sbc A,r 9x 4 z1hc A=A-r-cy + sbc A,n DE nn 8 z1hc A=A-n-cy + sbc A,(HL) 9E 8 z1hc A=A-(HL)-cy + and r Ax 4 z010 A=A & r + and n E6 nn 8 z010 A=A & n + and (HL) A6 8 z010 A=A & (HL) + xor r Ax 4 z000 + xor n EE nn 8 z000 + xor (HL) AE 8 z000 + or r Bx 4 z000 A=A | r + or n F6 nn 8 z000 A=A | n + or (HL) B6 8 z000 A=A | (HL) + cp r Bx 4 z1hc compare A-r + cp n FE nn 8 z1hc compare A-n + cp (HL) BE 8 z1hc compare A-(HL) + inc r xx 4 z0h- r=r+1 + inc (HL) 34 12 z0h- (HL)=(HL)+1 + dec r xx 4 z1h- r=r-1 + dec (HL) 35 12 z1h- (HL)=(HL)-1 + daa 27 4 z-0x decimal adjust akku + cpl 2F 4 -11- A = A xor FF + +GMB 16bit-Arithmetic/logical Commands + add HL,rr x9 8 -0hc HL = HL+rr ;rr may be BC,DE,HL,SP + inc rr x3 8 ---- rr = rr+1 ;rr may be BC,DE,HL,SP + dec rr xB 8 ---- rr = rr-1 ;rr may be BC,DE,HL,SP + add SP,dd E8 16 00hc SP = SP +/- dd ;dd is 8bit signed number + ld HL,SP+dd F8 12 00hc HL = SP +/- dd ;dd is 8bit signed number + +GMB Rotate- und Shift-Commands + rlca 07 4 000c rotate akku left + rla 17 4 000c rotate akku left through carry + rrca 0F 4 000c rotate akku right + rra 1F 4 000c rotate akku right through carry + rlc r CB 0x 8 z00c rotate left + rlc (HL) CB 06 16 z00c rotate left + rl r CB 1x 8 z00c rotate left through carry + rl (HL) CB 16 16 z00c rotate left through carry + rrc r CB 0x 8 z00c rotate right + rrc (HL) CB 0E 16 z00c rotate right + rr r CB 1x 8 z00c rotate right through carry + rr (HL) CB 1E 16 z00c rotate right through carry + sla r CB 2x 8 z00c shift left arithmetic (b0=0) + sla (HL) CB 26 16 z00c shift left arithmetic (b0=0) + swap r CB 3x 8 z000 exchange low/hi-nibble + swap (HL) CB 36 16 z000 exchange low/hi-nibble + sra r CB 2x 8 z00c shift right arithmetic (b7=b7) + sra (HL) CB 2E 16 z00c shift right arithmetic (b7=b7) + srl r CB 3x 8 z00c shift right logical (b7=0) + srl (HL) CB 3E 16 z00c shift right logical (b7=0) + +GMB Singlebit Operation Commands + bit n,r CB xx 8 z01- test bit n + bit n,(HL) CB xx 12 z01- test bit n + set n,r CB xx 8 ---- set bit n + set n,(HL) CB xx 16 ---- set bit n + res n,r CB xx 8 ---- reset bit n + res n,(HL) CB xx 16 ---- reset bit n + +GMB CPU-Controlcommands + ccf 3F 4 -00c cy=cy xor 1 + scf 37 4 -001 cy=1 + nop 00 4 ---- no operation + halt 76 N*4 ---- halt until interrupt occurs (low power) + stop 10 00 ? ---- low power standby mode (VERY low power) + di F3 4 ---- disable interrupts, IME=0 + ei FB 4 ---- enable interrupts, IME=1 + +GMB Jumpcommands + jp nn C3 nn nn 16 ---- jump to nn, PC=nn + jp HL E9 4 ---- jump to HL, PC=HL + jp f,nn xx nn nn 16;12 ---- conditional jump if nz,z,nc,c + jr PC+dd 18 dd 12 ---- relative jump to nn (PC=PC+/-7bit) + jr f,PC+dd xx dd 12;8 ---- conditional relative jump if nz,z,nc,c + call nn CD nn nn 24 ---- call to nn, SP=SP-2, (SP)=PC, PC=nn + call f,nn xx nn nn 24;12 ---- conditional call if nz,z,nc,c + ret C9 16 ---- return, PC=(SP), SP=SP+2 + ret f xx 20;8 ---- conditional return if nz,z,nc,c + reti D9 16 ---- return and enable interrupts (IME=1) + rst n xx 16 ---- call to 00,08,10,18,20,28,30,38 + +CPU Comparision with Z80 +------------------------ + +Comparision with 8080 +Basically, the gameboy CPU works more like an older 8080 CPU rather than like +a more powerful Z80 CPU. It is, however, supporting CB-prefixed instructions. +Also, all known gameboy assemblers using the more obvious Z80-style syntax, +rather than the chaotic 8080-style syntax. + +Comparision with Z80 +Any DD-, ED-, and FD-prefixed instructions are missing, that means no IX-, +IY-registers, no block commands, and some other missing commands. +All exchange instructions have been removed (including total absence of second +register set), 16bit memory accesses are mostly missing, and 16bit arithmetic +functions are heavily cut-down. +The gameboy has no IN/OUT instructions, instead I/O ports are accessed +directly by normal LD instructions, or by special LD (FF00+n) opcodes. +The sign and parity/overflow flags have been removed. +The gameboy operates approximately as fast as a 4MHz Z80 (8MHz in CGB double +speed mode), execution time of all instructions has been rounded up to a +multiple of 4 cycles though. + +Moved, Removed, and Added Opcodes + Opcode Z80 GMB + --------------------------------------- + 08 EX AF,AF LD (nn),SP + 10 DJNZ PC+dd STOP + 22 LD (nn),HL LDI (HL),A + 2A LD HL,(nn) LDI A,(HL) + 32 LD (nn),A LDD (HL),A + 3A LD A,(nn) LDD A,(HL) + D3 OUT (n),A - + D9 EXX RETI + DB IN A,(n) - + DD - + E0 RET PO LD (FF00+n),A + E2 JP PO,nn LD (FF00+C),A + E3 EX (SP),HL - + E4 CALL P0,nn - + E8 RET PE ADD SP,dd + EA JP PE,nn LD (nn),A + EB EX DE,HL - + EC CALL PE,nn - + ED - + F0 RET P LD A,(FF00+n) + F2 JP P,nn LD A,(FF00+C) + F4 CALL P,nn - + F8 RET M LD HL,SP+dd + FA JP M,nn LD A,(nn) + FC CALL M,nn - + FD - + CB3X SLL r/(HL) SWAP r/(HL) +Note: The unused (-) opcodes will lock-up the gameboy CPU when used. + +The Cartridge Header +-------------------- + +An internal information area is located at 0100-014F in +each cartridge. It contains the following values: + +0100-0103 - Entry Point +After displaying the Nintendo Logo, the built-in boot procedure jumps to this +address (100h), which should then jump to the actual main program in the +cartridge. Usually this 4 byte area contains a NOP instruction, followed by a +JP 0150h instruction. But not always. + +0104-0133 - Nintendo Logo +These bytes define the bitmap of the Nintendo logo that is displayed when the +gameboy gets turned on. The hexdump of this bitmap is: + CE ED 66 66 CC 0D 00 0B 03 73 00 83 00 0C 00 0D + 00 08 11 1F 88 89 00 0E DC CC 6E E6 DD DD D9 99 + BB BB 67 63 6E 0E EC CC DD DC 99 9F BB B9 33 3E +The gameboys boot procedure verifies the content of this bitmap (after it has +displayed it), and LOCKS ITSELF UP if these bytes are incorrect. A CGB +verifies only the first 18h bytes of the bitmap, but others (for example a +pocket gameboy) verify all 30h bytes. + +0134-0143 - Title +Title of the game in UPPER CASE ASCII. If it is less than 16 characters then +the remaining bytes are filled with 00's. When inventing the CGB, Nintendo has +reduced the length of this area to 15 characters, and some months later they +had the fantastic idea to reduce it to 11 characters only. The new meaning of +the ex-title bytes is described below. + +013F-0142 - Manufacturer Code +In older cartridges this area has been part of the Title (see above), in newer +cartridges this area contains an 4 character uppercase manufacturer code. +Purpose and Deeper Meaning unknown. + +0143 - CGB Flag +In older cartridges this byte has been part of the Title (see above). In CGB +cartridges the upper bit is used to enable CGB functions. This is required, +otherwise the CGB switches itself into Non-CGB-Mode. Typical values are: + 80h - Game supports CGB functions, but works on old gameboys also. + C0h - Game works on CGB only (physically the same as 80h). +Values with Bit 7 set, and either Bit 2 or 3 set, will switch the gameboy into +a special non-CGB-mode with uninitialized palettes. Purpose unknown, +eventually this has been supposed to be used to colorize monochrome games that +include fixed palette data at a special location in ROM. + +0144-0145 - New Licensee Code +Specifies a two character ASCII licensee code, indicating the company or +publisher of the game. These two bytes are used in newer games only (games +that have been released after the SGB has been invented). Older games are +using the header entry at 014B instead. + +0146 - SGB Flag +Specifies whether the game supports SGB functions, common values are: + 00h = No SGB functions (Normal Gameboy or CGB only game) + 03h = Game supports SGB functions +The SGB disables its SGB functions if this byte is set to another value than +03h. + +0147 - Cartridge Type +Specifies which Memory Bank Controller (if any) is used in the cartridge, and +if further external hardware exists in the cartridge. + 00h ROM ONLY 13h MBC3+RAM+BATTERY + 01h MBC1 15h MBC4 + 02h MBC1+RAM 16h MBC4+RAM + 03h MBC1+RAM+BATTERY 17h MBC4+RAM+BATTERY + 05h MBC2 19h MBC5 + 06h MBC2+BATTERY 1Ah MBC5+RAM + 08h ROM+RAM 1Bh MBC5+RAM+BATTERY + 09h ROM+RAM+BATTERY 1Ch MBC5+RUMBLE + 0Bh MMM01 1Dh MBC5+RUMBLE+RAM + 0Ch MMM01+RAM 1Eh MBC5+RUMBLE+RAM+BATTERY + 0Dh MMM01+RAM+BATTERY FCh POCKET CAMERA + 0Fh MBC3+TIMER+BATTERY FDh BANDAI TAMA5 + 10h MBC3+TIMER+RAM+BATTERY FEh HuC3 + 11h MBC3 FFh HuC1+RAM+BATTERY + 12h MBC3+RAM + +0148 - ROM Size +Specifies the ROM Size of the cartridge. Typically calculated as "32KB shl N". + 00h - 32KByte (no ROM banking) + 01h - 64KByte (4 banks) + 02h - 128KByte (8 banks) + 03h - 256KByte (16 banks) + 04h - 512KByte (32 banks) + 05h - 1MByte (64 banks) - only 63 banks used by MBC1 + 06h - 2MByte (128 banks) - only 125 banks used by MBC1 + 07h - 4MByte (256 banks) + 52h - 1.1MByte (72 banks) + 53h - 1.2MByte (80 banks) + 54h - 1.5MByte (96 banks) + +0149 - RAM Size +Specifies the size of the external RAM in the cartridge (if any). + 00h - None + 01h - 2 KBytes + 02h - 8 Kbytes + 03h - 32 KBytes (4 banks of 8KBytes each) +When using a MBC2 chip 00h must be specified in this entry, even though the +MBC2 includes a built-in RAM of 512 x 4 bits. + +014A - Destination Code +Specifies if this version of the game is supposed to be sold in japan, or +anywhere else. Only two values are defined. + 00h - Japanese + 01h - Non-Japanese + +014B - Old Licensee Code +Specifies the games company/publisher code in range 00-FFh. A value of 33h +signalizes that the New License Code in header bytes 0144-0145 is used +instead. +(Super GameBoy functions won't work if <> $33.) + +014C - Mask ROM Version number +Specifies the version number of the game. That is usually 00h. + +014D - Header Checksum +Contains an 8 bit checksum across the cartridge header bytes 0134-014C. The +checksum is calculated as follows: + x=0:FOR i=0134h TO 014Ch:x=x-MEM[i]-1:NEXT +The lower 8 bits of the result must be the same than the value in this entry. +The GAME WON'T WORK if this checksum is incorrect. + +014E-014F - Global Checksum +Contains a 16 bit checksum (upper byte first) across the whole cartridge ROM. +Produced by adding all bytes of the cartridge (except for the two checksum +bytes). The Gameboy doesn't verify this checksum. + +Memory Bank Controllers +----------------------- + +As the gameboys 16 bit address bus offers only limited space for ROM and RAM +addressing, many games are using Memory Bank Controllers (MBCs) to expand the +available address space by bank switching. These MBC chips are located in the +game cartridge (ie. not in the gameboy itself), several different MBC types +are available: + +--> None (32KByte ROM only) +--> MBC1 (max 2MByte ROM and/or 32KByte RAM) +--> MBC2 (max 256KByte ROM and 512x4 bits RAM) +--> MBC3 (max 2MByte ROM and/or 32KByte RAM and Timer) +--> HuC1 (MBC with Infrared Controller) + +--> MBC Timing Issues + +In each cartridge, the required (or preferred) MBC type should be specified in +byte at 0147h of the ROM. (As described in the chapter about The Cartridge +Header.) + +None (32KByte ROM only) +----------------------- + +Small games of not more than 32KBytes ROM do not require a MBC chip for ROM +banking. The ROM is directly mapped to memory at 0000-7FFFh. Optionally up to +8KByte of RAM could be connected at A000-BFFF, even though that could require +a tiny MBC-like circuit, but no real MBC chip. + +MBC1 (max 2MByte ROM and/or 32KByte RAM) +---------------------------------------- + +This is the first MBC chip for the gameboy. Any newer MBC chips are working +similiar, so that is relative easy to upgrade a program from one MBC chip to +another - or even to make it compatible to several different types of MBCs. + +Note that the memory in range 0000-7FFF is used for both reading from ROM, and +for writing to the MBCs Control Registers. + +0000-3FFF - ROM Bank 00 (Read Only) +This area always contains the first 16KBytes of the cartridge ROM. + +4000-7FFF - ROM Bank 01-7F (Read Only) +This area may contain any of the further 16KByte banks of the ROM, allowing to +address up to 125 ROM Banks (almost 2MByte). As described below, bank numbers +20h, 40h, and 60h cannot be used, resulting in the odd amount of 125 banks. + +A000-BFFF - RAM Bank 00-03, if any (Read/Write) +This area is used to address external RAM in the cartridge (if any). External +RAM is often battery buffered, allowing to store game positions or high score +tables, even if the gameboy is turned off, or if the cartridge is removed from +the gameboy. Available RAM sizes are: 2KByte (at A000-A7FF), 8KByte (at +A000-BFFF), and 32KByte (in form of four 8K banks at A000-BFFF). + +0000-1FFF - RAM Enable (Write Only) +Before external RAM can be read or written, it must be enabled by writing to +this address space. It is recommended to disable external RAM after accessing +it, in order to protect its contents from damage during power down of the +gameboy. Usually the following values are used: + 00h Disable RAM (default) + 0Ah Enable RAM +Practically any value with 0Ah in the lower 4 bits enables RAM, and any other +value disables RAM. + +2000-3FFF - ROM Bank Number (Write Only) +Writing to this address space selects the lower 5 bits of the ROM Bank Number +(in range 01-1Fh). When 00h is written, the MBC translates that to bank 01h +also. That doesn't harm so far, because ROM Bank 00h can be always directly +accessed by reading from 0000-3FFF. +But (when using the register below to specify the upper ROM Bank bits), the +same happens for Bank 20h, 40h, and 60h. Any attempt to address these ROM +Banks will select Bank 21h, 41h, and 61h instead. + +4000-5FFF - RAM Bank Number - or - Upper Bits of ROM Bank Number (Write Only) +This 2bit register can be used to select a RAM Bank in range from 00-03h, or +to specify the upper two bits (Bit 5-6) of the ROM Bank number, depending on +the current ROM/RAM Mode. (See below.) + +6000-7FFF - ROM/RAM Mode Select (Write Only) +This 1bit Register selects whether the two bits of the above register should +be used as upper two bits of the ROM Bank, or as RAM Bank Number. + 00h = ROM Banking Mode (up to 8KByte RAM, 2MByte ROM) (default) + 01h = RAM Banking Mode (up to 32KByte RAM, 512KByte ROM) +The program may freely switch between both modes, the only limitiation is that +only RAM Bank 00h can be used during Mode 0, and only ROM Banks 00-1Fh can be +used during Mode 1. + +MBC2 (max 256KByte ROM and 512x4 bits RAM) +------------------------------------------ + +0000-3FFF - ROM Bank 00 (Read Only) +Same as for MBC1. + +4000-7FFF - ROM Bank 01-0F (Read Only) +Same as for MBC1, but only a total of 16 ROM banks is supported. + +A000-A1FF - 512x4bits RAM, built-in into the MBC2 chip (Read/Write) +The MBC2 doesn't support external RAM, instead it includes 512x4 bits of +built-in RAM (in the MBC2 chip itself). It still requires an external battery +to save data during power-off though. +As the data consists of 4bit values, only the lower 4 bits of the "bytes" in +this memory area are used. + +0000-1FFF - RAM Enable (Write Only) +The least significant bit of the upper address byte must be zero to +enable/disable cart RAM. For example the following addresses can be used to +enable/disable cart RAM: 0000-00FF, 0200-02FF, 0400-04FF, ..., 1E00-1EFF. +The suggested address range to use for MBC2 ram enable/disable is 0000-00FF. + +2000-3FFF - ROM Bank Number (Write Only) +Writing a value (XXXXBBBB - X = Don't cares, B = bank select bits) into +2000-3FFF area will select an appropriate ROM bank at 4000-7FFF. + +The least significant bit of the upper address byte must be one to select a +ROM bank. For example the following addresses can be used to select a ROM +bank: 2100-21FF, 2300-23FF, 2500-25FF, ..., 3F00-3FFF. +The suggested address range to use for MBC2 rom bank selection is 2100-21FF. + +MBC3 (max 2MByte ROM and/or 32KByte RAM and Timer) +-------------------------------------------------- + +Beside for the ability to access up to 2MB ROM (128 banks), and 32KB RAM (4 +banks), the MBC3 also includes a built-in Real Time Clock (RTC). The RTC +requires an external 32.768 kHz Quartz Oscillator, and an external battery (if +it should continue to tick when the gameboy is turned off). + +0000-3FFF - ROM Bank 00 (Read Only) +Same as for MBC1. + +4000-7FFF - ROM Bank 01-7F (Read Only) +Same as for MBC1, except that accessing banks 20h, 40h, and 60h is supported +now. + +A000-BFFF - RAM Bank 00-03, if any (Read/Write) +A000-BFFF - RTC Register 08-0C (Read/Write) +Depending on the current Bank Number/RTC Register selection (see below), this +memory space is used to access an 8KByte external RAM Bank, or a single RTC +Register. + +0000-1FFF - RAM and Timer Enable (Write Only) +Mostly the same as for MBC1, a value of 0Ah will enable reading and writing to +external RAM - and to the RTC Registers! A value of 00h will disable either. + +2000-3FFF - ROM Bank Number (Write Only) +Same as for MBC1, except that the whole 7 bits of the RAM Bank Number are +written directly to this address. As for the MBC1, writing a value of 00h, +will select Bank 01h instead. All other values 01-7Fh select the corresponding +ROM Banks. + +4000-5FFF - RAM Bank Number - or - RTC Register Select (Write Only) +As for the MBC1s RAM Banking Mode, writing a value in range for 00h-03h maps +the corresponding external RAM Bank (if any) into memory at A000-BFFF. +When writing a value of 08h-0Ch, this will map the corresponding RTC register +into memory at A000-BFFF. That register could then be read/written by +accessing any address in that area, typically that is done by using address +A000. + +6000-7FFF - Latch Clock Data (Write Only) +When writing 00h, and then 01h to this register, the current time becomes +latched into the RTC registers. The latched data will not change until it +becomes latched again, by repeating the write 00h->01h procedure. +This is supposed for from the RTC registers. It is proof to read the +latched (frozen) time from the RTC registers, while the clock itself continues +to tick in background. + +The Clock Counter Registers + 08h RTC S Seconds 0-59 (0-3Bh) + 09h RTC M Minutes 0-59 (0-3Bh) + 0Ah RTC H Hours 0-23 (0-17h) + 0Bh RTC DL Lower 8 bits of Day Counter (0-FFh) + 0Ch RTC DH Upper 1 bit of Day Counter, Carry Bit, Halt Flag + Bit 0 Most significant bit of Day Counter (Bit 8) + Bit 6 Halt (0=Active, 1=Stop Timer) + Bit 7 Day Counter Carry Bit (1=Counter Overflow) +The Halt Flag is supposed to be set before to the RTC Registers. + +The Day Counter +The total 9 bits of the Day Counter allow to count days in range from 0-511 +(0-1FFh). The Day Counter Carry Bit becomes set when this value overflows. In +that case the Carry Bit remains set until the program does reset it. +Note that you can store an offset to the Day Counter in battery RAM. For +example, every time you read a non-zero Day Counter, add this Counter to the +offset in RAM, and reset the Counter to zero. This method allows to count any +number of days, making your program Year-10000-Proof, provided that the +cartridge gets used at least every 511 days. + +Delays +When accessing the RTC Registers it is recommended to execute a 4ms delay (4 +Cycles in Normal Speed Mode) between the separate accesses. + +HuC1 (MBC with Infrared Controller) +------------------------------------ + +This controller (made by Hudson Soft) appears to be very similar to an MBC1 +with the main difference being that it supports infrared LED input / output. +(Similiar to the infrared port that has been later invented in CGBs.) + +The Japanese cart "Fighting Phoenix" (internal cart name: SUPER B DAMAN) is +known to contain this chip. + +MBC Timing Issues +----------------- + +Using MBCs with CGB Double Speed Mode +The MBC5 has been designed to support CGB Double Speed Mode. +There have been rumours that older MBCs (like MBC1-3) wouldn't be fast enough +in that mode. If so, it might be nethertheless possible to use Double Speed +during periods which use only code and data which is located in internal RAM. +However, despite of the above, my own good old selfmade MBC1-EPROM card +appears to work stable and fine even in Double Speed Mode though. + +Gamegenie/Shark Cheats +---------------------- + +Game Shark and Gamegenie are external cartridge adapters that can be plugged +between the gameboy and the actual game cartridge. Hexadecimal codes can be +then entered for specific games, typically providing things like Infinite Sex, +255 Cigarettes, or Starting directly in Wonderland Level PRO, etc. + +Gamegenie (ROM patches) +Gamegenie codes consist of nine-digit hex numbers, formatted as ABC-DEF-GHI, +the meaning of the separate digits is: + AB New data + FCDE Memory address, XORed by 0F000h + GI Old data, XORed by 0BAh and rotated left by two + H Don't know, maybe checksum and/or else +The address should be located in ROM area 0000h-7FFFh, the adapter permanently +compares address/old data with address/data being read by the game, and +replaces that data by new data if necessary. That method (more or less) +prohibits unwanted patching of wrong memory banks. Eventually it is also +possible to patch external RAM ? +Newer devices reportedly allow to specify only the first six digits +(optionally). As far as I rememeber, around three or four codes can be used +simultaneously. + +Game Shark (RAM patches) +Game Shark codes consist of eight-digit hex numbers, formatted as ABCDEFGH, +the meaning of the separate digits is: + AB External RAM bank number + CD New Data + GHEF Memory Address (internal or external RAM, A000-DFFF) +As far as I understand, patching is implement by hooking the original VBlank +interrupt handler, and re-writing RAM values each frame. The downside is that +this method steals some CPU time, also, it cannot be used to patch program +code in ROM. +As far as I rememeber, somewhat 10-25 codes can be used simultaneously. + +Power Up Sequence +----------------- + +When the GameBoy is powered up, a 256 byte program starting at memory location +0 is executed. This program is located in a ROM inside the GameBoy. The first +thing the program does is read the cartridge locations from $104 to $133 and +place this graphic of a Nintendo logo on the screen at the top. This image is +then scrolled until it is in the middle of the screen. Two musical notes are +then played on the internal speaker. Again, the cartridge locations $104 to +$133 are read but this time they are compared with a table in the internal +rom. If any byte fails to compare, then the GameBoy stops comparing bytes and +simply halts all operations. If all locations compare the same, then the +GameBoy starts adding all of the bytes in the cartridge from $134 to $14d. A +value of 25 decimal is added to this total. If the least significant byte of +the result is a not a zero, then the GameBoy will stop doing anything. If it +is a zero, then the internal ROM is disabled and cartridge program execution +begins at location $100 with the following register values: + + AF=$01B0 + BC=$0013 + DE=$00D8 + HL=$014D + Stack Pointer=$FFFE + [$FF05] = $00 ; TIMA + [$FF06] = $00 ; TMA + [$FF07] = $00 ; TAC + [$FF10] = $80 ; NR10 + [$FF11] = $BF ; NR11 + [$FF12] = $F3 ; NR12 + [$FF14] = $BF ; NR14 + [$FF16] = $3F ; NR21 + [$FF17] = $00 ; NR22 + [$FF19] = $BF ; NR24 + [$FF1A] = $7F ; NR30 + [$FF1B] = $FF ; NR31 + [$FF1C] = $9F ; NR32 + [$FF1E] = $BF ; NR33 + [$FF20] = $FF ; NR41 + [$FF21] = $00 ; NR42 + [$FF22] = $00 ; NR43 + [$FF23] = $BF ; NR30 + [$FF24] = $77 ; NR50 + [$FF25] = $F3 ; NR51 + [$FF26] = $F1-GB, $F0-SGB ; NR52 + [$FF40] = $91 ; LCDC + [$FF42] = $00 ; SCY + [$FF43] = $00 ; SCX + [$FF45] = $00 ; LYC + [$FF47] = $FC ; BGP + [$FF48] = $FF ; OBP0 + [$FF49] = $FF ; OBP1 + [$FF4A] = $00 ; WY + [$FF4B] = $00 ; WX + [$FFFF] = $00 ; IE + +It is not a good idea to assume the above values will always exist. A later +version GameBoy could contain different values than these at reset. Always set +these registers on reset rather than assume they are as above. + +Please note that GameBoy internal RAM on power up contains random data. All of +the GameBoy emulators tend to set all RAM to value $00 on entry. + +Cart RAM the first time it is accessed on a real GameBoy contains random data. +It will only contain known data if the GameBoy code initializes it to some +value. + +Reducing Power Consumption +-------------------------- + +The following can be used to recude the power consumption of the gameboy, and +to extend the life of the batteries. + +--> PWR Using the HALT Instruction +--> PWR Using the STOP Instruction +--> PWR Disabeling the Sound Controller +--> PWR Not using CGB Double Speed Mode +--> PWR Using the Skills + +PWR Using the HALT Instruction +------------------------------ + +It is recommended that the HALT instruction be used whenever possible to +reduce power consumption & extend the life of the batteries. This command +stops the system clock reducing the power consumption of both the CPU and ROM. + +The CPU will remain suspended until an interrupt occurs at which point the +interrupt is serviced and then the instruction immediately following the HALT +is executed. + +Depending on how much CPU time is required by a game, the HALT instruction can +extend battery life anywhere from 5 to 50% or possibly more. + +When waiting for a vblank event, this would be a BAD example: + @@wait: + ld a,(0FF44h) ;LY + cp a,144 + jr nz,@@wait + +A better example would be a procedure as shown below. In this case the vblank +interrupt must be enabled, and your vblank interrupt procedure must set +vblank_flag to a non-zero value. + ld hl,vblank_flag ;hl=pointer to vblank_flag + xor a ;a=0 + @@wait: ;wait... + halt ;suspend CPU - wait for ANY interrupt + cp a,(hl) ;vblank flag still zero? + jr z,@@wait ;wait more if zero + ld (hl),a ;set vblank_flag back to zero +The vblank_flag is used to determine whether the HALT period has been +terminated by a vblank interrupt, or by another interrupt. In case that your +program has all other interrupts disabled, then it would be proof to replace +the above procedure by a single HALT instruction. + +PWR Using the STOP Instruction +------------------------------ + +The STOP instruction is intended to switch the gameboy into VERY low power +standby mode. For example, a program may use this feature when it hasn't +sensed keyboard input for a longer period (assuming that somebody forgot to +turn off the gameboy). + +Before invoking STOP, it might be required to disable Sound and Video manually +(as well as IR-link port in CGB). Much like HALT, the STOP state is terminated +by interrupt events - in this case this would be commonly a joypad interrupt. +The joypad register might be required to be prepared for STOP either. + +PWR Disabeling the Sound Controller +----------------------------------- + +If your programs doesn't use sound at all (or during some periods) then write +00h to register FF26 to save 16% or more on GB power consumption. +Sound can be turned back on by writing 80h to the same register, all sound +registers must be then re-initialized. +When the gameboy becomes turned on, sound is enabled by default, and must be +turned off manually when not used. + +PWR Not using CGB Double Speed Mode +----------------------------------- + +Because CGB Double Speed mode consumes more power, it'd be recommended to use +normal speed when possible. +There's limited ability to switch between both speeds, for example, a game +might use normal speed in the title screen, and double speed in the game, or +vice versa. +However, during speed switch the display collapses for a short moment, so that +it'd be no good idea to alter speeds within active game or title screen +periods. + +PWR Using the Skills +-------------------- + +Most of the above power saving methods will produce best results when using +efficient and tight assembler code which requires as less CPU power as +possible. Thus, experienced old-school programmers will (hopefully) produce +lower power consumption, as than HLL-programming teenagers, for example. + +Sprite RAM Bug +-------------- + +There is a flaw in the GameBoy hardware that causes trash to be written to OAM +RAM if the following commands are used while their 16-bit content is in the +range of $FE00 to $FEFF: + inc rr dec rr ;rr = bc,de, or hl + ldi a,(hl) ldd a,(hl) + ldi (hl),a ldd (hl),a +Only sprites 1 & 2 ($FE00 & $FE04) are not affected by these instructions. + +External Connectors +------------------- + +Cartridge Slot + Pin Name Expl. + 1 VDD Power Supply +5V DC + 2 PHI System Clock + 3 /WR Write + 4 /RD Read + 5 /CS Chip Select + 6-21 A0-A15 Address Lines + 22-29 D0-D7 Data Lines + 30 /RES Reset signal + 31 VIN External Sound Input + 32 GND Ground + +Link Port +Pin numbers are arranged as 2,4,6 in upper row, 1,3,5 un lower row; outside +view of gameboy socket; flat side of socket upside. +Colors as used in most or all standard link cables, because SIN and SOUT are +crossed, colors Red and Orange are exchanged at one cable end. + Pin Name Color Expl. + 1 VCC - +5V DC + 2 SOUT red Data Out + 3 SIN orange Data In + 4 P14 - Not used + 5 SCK green Shift Clock + 6 GND blue Ground +Note: The original gameboy used larger plugs (unlike pocket gameboys and +newer), linking between older/newer gameboys is possible by using cables with +one large and one small plug though. + +Stereo Sound Connector (3.5mm, female) + Pin Expl. + Tip Sound Left + Middle Sound Right + Base Ground + +External Power Supply +... + + +END + \ No newline at end of file diff --git a/gbcore.cc b/gbcore.cc new file mode 100644 index 0000000..9ef4baa --- /dev/null +++ b/gbcore.cc @@ -0,0 +1,618 @@ +#include "gbcore.h" + +#include "sized_types.h" +#include "gbrom.h" +#include +#include + +class GameBoy +{ + u8 memory[65536]; + GBRom *rom; + + enum flags_enum + { + ZERO_FLAG=0x80, + ADD_SUB_FLAG=0x40, + HALF_CARRY_FLAG=0x20, + CARRY_FLAG=0x10, + }; + + // CPU Registers + // ENDIANNESS WARNING! + struct + { + union + { + u16 AF; + struct { u8 flags; u8 A; }; + }; + union + { + u16 BC; + struct { u8 C; u8 B; }; + }; + union + { + u16 DE; + struct { u8 E; u8 D; }; + }; + union + { + u16 HL; + struct { u8 L; u8 H; }; + }; + u16 SP; + u16 PC; + + } __attribute__((packed)) regs; + + void set_flag(const u8 f) { regs.flags |= f; } + void reset_flag(const u8 f) { regs.flags &= (~f); } + + public: + GameBoy(std::string rom_name); + + void reset(); + void run_cycle(); + void run(); + +}; + +GameBoy::GameBoy(std::string rom_name): + rom(0), regs() +{ + rom = read_gbrom(rom_name); + reset(); +} + +void GameBoy::reset() +{ + std::memcpy(memory, rom->data, 16384); + regs.PC = 0x100; +} + + +void GameBoy::run_cycle() +{ + int prefix; + int opcode; + opcode = memory[regs.PC++]; + if (opcode == 0xCB) + { + prefix=opcode; + opcode=memory[regs.PC++]; + } + + switch(opcode) + { + // LD n, nn + case 0x76: // LD A,n + regs.A = memory[regs.PC++]; + break; + case 0x06: // LD B,n + regs.B = memory[regs.PC++]; + break; + case 0x0E: // LD C,n + regs.C = memory[regs.PC++]; + break; + case 0x16: // LD D,n + regs.D = memory[regs.PC++]; + break; + case 0x1E: // LD E,n + regs.E = memory[regs.PC++]; + break; + case 0x26: // LD H,n + regs.H = memory[regs.PC++]; + break; + case 0x2E: // LD L,n + regs.L = memory[regs.PC++]; + break; + + // LD r1,r2 + case 0x7F: // LD A,A + regs.A = regs.A; + break; + case 0x78: // LD A,B + regs.A = regs.B; + break; + case 0x79: // LD A,C + regs.A = regs.C; + break; + case 0x7A: // LD A,D + regs.A = regs.D; + break; + case 0x7B: // LD A,E + regs.A = regs.E; + break; + case 0x7C: // LD A,H + regs.A = regs.H; + break; + case 0x7D: // LD A,L + regs.A = regs.L; + break; + case 0x7E: // LD A,(HL) + regs.A = memory[regs.HL]; + break; + + case 0x47: // LD B,A + regs.B = regs.A; + break; + case 0x40: // LD B,B + regs.B = regs.B; + break; + case 0x41: // LD B,C + regs.B = regs.C; + break; + case 0x42: // LD B,D + regs.B = regs.D; + break; + case 0x43: // LD B,E + regs.B = regs.E; + break; + case 0x44: // LD B,H + regs.B = regs.H; + break; + case 0x45: // LD B,L + regs.B = regs.L; + break; + case 0x46: // LD B,(HL) + regs.B = memory[regs.HL]; + break; + + case 0x4F: // LD C,A + regs.C = regs.A; + break; + case 0x48: // LD C,B + regs.C = regs.B; + break; + case 0x49: // LD C,C + regs.C = regs.C; + break; + case 0x4A: // LD C,D + regs.C = regs.D; + break; + case 0x4B: // LD C,E + regs.C = regs.E; + break; + case 0x4C: // LD C,H + regs.C = regs.H; + break; + case 0x4D: // LD C,L + regs.C = regs.L; + break; + case 0x4E: // LD C,(HL) + regs.C = memory[regs.HL]; + break; + + case 0x57: // LD D,A + regs.D = regs.A; + break; + case 0x50: // LD D,B + regs.D = regs.B; + break; + case 0x51: // LD D,C + regs.D = regs.C; + break; + case 0x52: // LD D,D + regs.D = regs.D; + break; + case 0x53: // LD D,E + regs.D = regs.E; + break; + case 0x54: // LD D,H + regs.D = regs.H; + break; + case 0x55: // LD D,L + regs.D = regs.L; + break; + case 0x56: // LD D,(HL) + regs.D = memory[regs.HL]; + break; + + case 0x5F: // LD E,A + regs.E = regs.A; + break; + case 0x58: // LD E,B + regs.E = regs.D; + break; + case 0x59: // LD E,C + regs.E = regs.C; + break; + case 0x5A: // LD E,D + regs.E = regs.D; + break; + case 0x5B: // LD E,E + regs.E = regs.E; + break; + case 0x5C: // LD E,H + regs.E = regs.H; + break; + case 0x5D: // LD E,L + regs.E = regs.L; + break; + case 0x5E: // LD E,(HL) + regs.E = memory[regs.HL]; + break; + + case 0x67: // LD H,A + regs.H = regs.A; + break; + case 0x60: // LD H,B + regs.H = regs.B; + break; + case 0x61: // LD H,C + regs.H = regs.C; + break; + case 0x62: // LD H,D + regs.H = regs.D; + break; + case 0x63: // LD H,E + regs.H = regs.E; + break; + case 0x64: // LD H,H + regs.H = regs.H; + break; + case 0x65: // LD H,L + regs.H = regs.L; + break; + case 0x66: // LD H,(HL) + regs.H = memory[regs.HL]; + break; + + case 0x6F: // LD L,A + regs.L = regs.A; + break; + case 0x68: // LD L,B + regs.L = regs.D; + break; + case 0x69: // LD L,C + regs.L = regs.C; + break; + case 0x6A: // LD L,D + regs.L = regs.D; + break; + case 0x6B: // LD L,E + regs.L = regs.E; + break; + case 0x6C: // LD L,H + regs.L = regs.H; + break; + case 0x6D: // LD L,L + regs.L = regs.L; + break; + case 0x6E: // LD L,(HL) + regs.L = memory[regs.HL]; + break; + + case 0x77: // LD (HL),A + memory[regs.HL] = regs.A; + break; + case 0x70: // LD (HL),B + memory[regs.HL] = regs.B; + break; + case 0x71: // LD (HL),C + memory[regs.HL] = regs.C; + break; + case 0x72: // LD (HL),D + memory[regs.HL] = regs.D; + break; + case 0x73: // LD (HL),E + memory[regs.HL] = regs.E; + break; + case 0x74: // LD (HL),H + memory[regs.HL] = regs.H; + break; + case 0x75: // LD (HL),L + memory[regs.HL] = regs.L; + break; + case 0x36: // LD (HL), n + memory[regs.HL] = memory[regs.PC++]; + break; + + // LD A, n + case 0x0A: // LD A, (BC) + regs.A = memory[regs.BC]; + break; + case 0x1A: // LD A, (DE) + regs.A = memory[regs.DE]; + break; + case 0xFA: // LD A, (nn) + regs.A = memory[memory[regs.PC] + memory[regs.PC+1]<<8]; + regs.PC+=2; + break; + + // LD n, A + case 0x02: // LD (BC), A + memory[regs.BC] = regs.A; + break; + case 0x12: // LD (DE), A + memory[regs.DE] = regs.A; + break; + case 0xEA: // LD (nn), A + memory[memory[regs.PC] + memory[regs.PC+1]<<8] = regs.A; + break; + + // LD A, (C) + case 0xF2: + regs.A = memory[0xFF00 + regs.C]; + break; + // LD (C), A + case 0xE2: + memory[0xFF00 + regs.C] = regs.A; + break; + + // LD A, (HLD); LD A, (HL-); LDD A,(HL); + case 0x3A: + regs.A = memory[regs.HL]; + --regs.HL; + break; + // LD (HLD), A; LD (HL-), A; LDD (HL), A; + case 0x32: + memory[regs.HL] = regs.A; + --regs.HL; + break; + // LD A, (HLI); LD A, (HL+); LDI A, (HL); + case 0x2A: + regs.A = memory[regs.HL]; + ++regs.HL; + break; + // LD (HLI), A; LD (HL+), A; LDI (HL), A; + case 0x22: + memory[regs.HL] = regs.A; + ++regs.HL; + break; + + // LDH (n), A + case 0xE0: + memory[0xFF00 + regs.PC++] = regs.A; + break; + // LDH A, (n) + case 0xF0: + regs.A = memory[0xFF00 + regs.PC++]; + break; + + // LD n, nn + case 0x01: // LD BC, nn + regs.BC = memory[regs.PC]+(memory[regs.PC+1] << 8); + regs.PC +=2; + break; + case 0x11: // LD DE, nn + regs.DE = memory[regs.PC]+(memory[regs.PC+1] << 8); + regs.PC +=2; + break; + case 0x21: // LD HL, nn + regs.HL = memory[regs.PC]+(memory[regs.PC+1] << 8); + regs.PC +=2; + break; + case 0x31: // LD SP, nn + regs.SP = memory[regs.PC]+(memory[regs.PC+1] << 8); + regs.PC +=2; + break; + + // LD SP, HL + case 0xF9: + regs.SP = regs.HL; + break; + + // LD HL, SP+n + // LDHL SP, n + case 0xF8: { + s8 offset = *(reinterpret_cast(memory+regs.PC++)); + int res = regs.SP + offset; + + // TODO: Verificar si los flags van asi + if (res > 0xFFFF) set_flag(CARRY_FLAG); + else reset_flag(CARRY_FLAG); + + // TODO: hacer lo apropiado con el half-carry flag + reset_flag(ADD_SUB_FLAG); + reset_flag(ZERO_FLAG); + + regs.HL = static_cast(res & 0xFFFF); + break; + } + + // LD (nn), SP + case 0x08: { + int addr = memory[regs.PC] + memory[regs.PC+1] << 8; + regs.PC += 2; + memory[addr] = regs.SP; + break; + } + + // PUSH nn + case 0xF5: // push AF + memory[regs.SP-1] = regs.A; + memory[regs.SP-2] = regs.flags; + regs.SP -= 2; + break; + case 0xC5: // push BC + memory[regs.SP-1] = regs.B; + memory[regs.SP-2] = regs.C; + regs.SP -= 2; + break; + case 0xD5: // push DE + memory[regs.SP-1] = regs.D; + memory[regs.SP-2] = regs.E; + regs.SP -= 2; + break; + case 0xE5: // push HL + memory[regs.SP-1] = regs.H; + memory[regs.SP-2] = regs.L; + regs.SP -= 2; + break; + + // POP nn + case 0xF1: // pop AF + regs.flags = memory[regs.SP]; + regs.A = memory[regs.SP+1]; + regs.SP += 2; + break; + case 0xC1: // pop BC + regs.C = memory[regs.SP]; + regs.B = memory[regs.SP+1]; + regs.SP += 2; + break; + case 0xD1: // pop DE + regs.E = memory[regs.SP]; + regs.D = memory[regs.SP+1]; + regs.SP += 2; + break; + case 0xE1: // pop HL + regs.L = memory[regs.SP]; + regs.H = memory[regs.SP+1]; + regs.SP += 2; + break; + + // 8-bit ALU + // ADD A, n + case 0x87: {// ADD A, A + int res = regs.A + regs.A; + int half_res = (regs.A & 0x0F) + (regs.A & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x80: {// ADD A, B + int res = regs.A + regs.B; + int half_res = (regs.A & 0x0F) + (regs.B & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x81: {// ADD A, C + int res = regs.A + regs.C; + int half_res = (regs.A & 0x0F) + (regs.C & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x82: {// ADD A, D + int res = regs.A + regs.D; + int half_res = (regs.A & 0x0F) + (regs.D & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x83: {// ADD A, E + int res = regs.A + regs.E; + int half_res = (regs.A & 0x0F) + (regs.E & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x84: {// ADD A, H + int res = regs.A + regs.H; + int half_res = (regs.A & 0x0F) + (regs.H & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x85: {// ADD A, L + int res = regs.A + regs.L; + int half_res = (regs.A & 0x0F) + (regs.L & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0x86: {// ADD A, (HL) + int res = regs.A + memory[regs.HL]; + int half_res = (regs.A & 0x0F) + (memory[regs.HL] & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + case 0xC6: {//ADD A, # + int inm = memory[regs.PC++]; + int res = regs.A + inm; + int half_res = (regs.A & 0x0F) + (inm & 0x0F); + + regs.A = static_cast(res); + if (res > 0xFF) + set_flag(CARRY_FLAG); + reset_flag(ADD_SUB_FLAG); + if (regs.A == 0) + set_flag(ZERO_FLAG); + + if (half_res > 0x0F) + set_flag(HALF_CARRY_FLAG); + break; + } + + + + + + + + + + } + +} + diff --git a/gbcore.h b/gbcore.h new file mode 100644 index 0000000..e69de29 diff --git a/gbrom.cc b/gbrom.cc new file mode 100644 index 0000000..b1c3082 --- /dev/null +++ b/gbrom.cc @@ -0,0 +1,36 @@ +#include "gbrom.h" +#include +#include +#include + +using std::ifstream; +using std::ios; +using std::cout; +using std::endl; + +GBRom *read_gbrom(std::string filename) +{ + ifstream is; + is.open(filename.c_str(), ios::binary); + + is.seekg(0,ios::end); + int length = is.tellg(); + cout << "Loading " << filename << " (length=" << length << ")" << endl; + is.seekg(0,ios::beg); + + void *buffer = ::operator new(length); + is.read((char*)buffer, length); + GBRom *rom = (GBRom*) buffer; + + char buf[17]; + std::memcpy(buf, rom->header.old_title, 16); + buf[16]=0; + cout << "Loaded " << buf << endl; +} + +#ifdef TEST_GBROM +int main(int argc, char *argv[]) +{ + GBRom *rom=read_gbrom(argv[1]); +} +#endif diff --git a/gbrom.h b/gbrom.h new file mode 100644 index 0000000..c88dd81 --- /dev/null +++ b/gbrom.h @@ -0,0 +1,77 @@ +#ifndef GBROM_H +#define GBROM_H + +#include "sized_types.h" +#include + +namespace cartrigde_types { + const u8 ROM_ONLY=0x00; + const u8 MBC1=0x01; + const u8 MBC1_RAM=0x02; + const u8 MBC1_RAM_BATTERY=0x03; + const u8 MBC2=0x05; + const u8 MBC2_BATTERY=0x06; + const u8 ROM_RAM=0x08; + const u8 ROM_RAM_BATTERY=0x09; + const u8 MMM01=0x0B; + const u8 MMM01_RAM=0x0C; + const u8 MMM01_RAM_BATTERY=0x0D; + const u8 MBC3_TIMER_BATTERY=0X0F; + const u8 MBC3_TIMER_RAM_BATTERY=0X10; + const u8 MBC3=0X11; + const u8 MBC3_RAM=0X12; + const u8 MBC3_RAM_BATTERY=0X13; + const u8 MBC4=0X15; + const u8 MBC4_RAM=0X16; + const u8 MBC4_RAM_BATTERY=0X17; + const u8 MBC5=0X19; + const u8 MBC5_RAM=0X1A; + const u8 MBC5_RAM_BATTERY=0X1B; + const u8 MBC5_RUMBLE=0X1C; + const u8 MBC5_RUMBLE_RAM=0X1D; + const u8 MBC5_RUMBLE_RAM_BATTERY=0X1E; + const u8 POCKET_CAMERA=0XFC; + const u8 BANDAI_TAMA5=0XFD; + const u8 HuC3=0XFE; + const u8 HuC1_RAM_BATTERY=0xFF; +} + + + + +struct GBRomHeader { + u8 dummy[256]; // ROM beginning, before header + u32 entry_point; // 0100-0103 + u8 nintendo_logo[48]; // 0104-0133 + union { + struct { + u8 old_title[16]; + }; + struct { + u8 new_title[11]; + u8 manuf_code[4]; + u8 cgb_flag; + }; + }; + u8 new_licensee_code[2]; + u8 sgb_flag; + u8 cartridge_type; + u8 rom_size; // 32Kb shl rom_size + u8 ram_size; + u8 destination_code; + u8 old_licensee_code; + u8 mask_rom_version_number; + u8 header_checksum; + u8 global_checksum[2]; +}; + +union GBRom { + GBRomHeader header; + u8 data[1]; // struct hack +}; + +GBRom *read_gbrom(std::string filename); + + +#endif + diff --git a/sized_types.h b/sized_types.h new file mode 100644 index 0000000..7bd0287 --- /dev/null +++ b/sized_types.h @@ -0,0 +1,155 @@ +#ifndef SIZED_TYPES_H +#define SIZED_TYPES_H + +#include + + +// NOTE: sizeof(char) <= sizeof(short) <= sizeof(int) +// <= sizeof(long) <= sizeof(long long) +// char >= 8 bit +// short >= 16 bit +// long >= 32 bit + + +// Define SIZEOF_CHAR +#if UCHAR_MAX == 0xff +#define SIZEOF_CHAR 1 +#elif UCHAR_MAX == 0xffff +#define SIZEOF_CHAR 2 +#elif UCHAR_MAX == 0xfffffffful +#define SIZEOF_CHAR 4 +#elif UCHAR_MAX == 0xfffffffffffffffful +#define SIZEOF_CHAR 8 +#endif // SIZEOF_CHAR + +// Define SIZEOF_SHORT +#if USHRT_MAX == 0xffff +#define SIZEOF_SHORT 2 +#elif USHRT_MAX == 0xfffffffful +#define SIZEOF_SHORT 4 +#elif USHRT_MAX == 0xfffffffffffffffful +#define SIZEOF_SHORT 8 +#endif // SIZEOF_SHORT + +// Define SIZEOF_INT +#if UINT_MAX == 0xffff +#define SIZEOF_INT 2 +#elif UINT_MAX == 0xfffffffful +#define SIZEOF_INT 4 +#elif UINT_MAX == 0xfffffffffffffffful +#define SIZEOF_INT 8 +#endif // SIZEOF_INT + +// Define SIZEOF_LONG +#if ULONG_MAX == 0xfffffffful +#define SIZEOF_LONG 4 +#elif ULONG_MAX == 0xfffffffffffffffful +#define SIZEOF_LONG 8 +#endif // SIZEOF_LONG + +// Define SIZEOF_LONG_LONG +#ifdef ULLONG_MAX +#if ULLONG_MAX == 0xffffffffull +#define SIZEOF_LONG_LONG 4 +#elif ULLONG_MAX == 0xffffffffffffffffull +#define SIZEOF_LONG_LONG 8 +#endif +#endif // SIZEOF_LONG_LONG + +#define COMPILE_TIME_ASSERT(name, x) \ + typedef int APRIL_SIZED_dummy_ ## name[(x) * 2 - 1] + + +// Define 8-bit types +#if SIZEOF_CHAR == 1 +typedef unsigned char uint8; +typedef signed char int8; +COMPILE_TIME_ASSERT(uint8, 1==sizeof(uint8)); +COMPILE_TIME_ASSERT(int8, 1==sizeof(int8)); +#define HAVE_INT8 +#define HAVE_UINT8 +#endif // short y siguientes tienen minimo 16 bits + +// Define 16-bit types +#if SIZEOF_SHORT == 2 +typedef unsigned short uint16; +typedef signed short int16; +COMPILE_TIME_ASSERT(uint16, 2==sizeof(uint16)); +COMPILE_TIME_ASSERT(int16, 2==sizeof(int16)); +#define HAVE_INT16 +#define HAVE_UINT16 +#endif + +// Define 32-bit types +#if SIZEOF_SHORT == 4 +typedef unsigned short uint32; +typedef signed short int32; +COMPILE_TIME_ASSERT(uint32, 4==sizeof(uint32)); +COMPILE_TIME_ASSERT(int32, 4==sizeof(int32)); +#define HAVE_INT32 +#define HAVE_UINT32 +#elif SIZEOF_INT == 4 +typedef unsigned int uint32; +typedef signed int int32; +COMPILE_TIME_ASSERT(uint32, 4==sizeof(uint32)); +COMPILE_TIME_ASSERT(int32, 4==sizeof(int32)); +#define HAVE_INT32 +#define HAVE_UINT32 +#elif SIZEOF_LONG == 4 +typedef unsigned long uint32; +typedef signed long int32; +COMPILE_TIME_ASSERT(uint32, 4==sizeof(uint32)); +COMPILE_TIME_ASSERT(int32, 4==sizeof(int32)); +#define HAVE_INT32 +#define HAVE_UINT32 +#elif SIZEOF_LONG_LONG == 4 +typedef unsigned long long uint32; +typedef signed long long int32; +COMPILE_TIME_ASSERT(uint32, 4==sizeof(uint32)); +COMPILE_TIME_ASSERT(int32, 4==sizeof(int32)); +#define HAVE_INT32 +#define HAVE_UINT32 +#endif + +// Define 64-bit types +#if SIZEOF_SHORT == 8 +typedef unsigned short uint64; +typedef signed short int64; +COMPILE_TIME_ASSERT(uint64, 8==sizeof(uint64)); +COMPILE_TIME_ASSERT(int64, 8==sizeof(int64)); +#define HAVE_INT64 +#define HAVE_UINT64 +#elif SIZEOF_INT == 8 +typedef unsigned int uint64; +typedef signed int int64; +COMPILE_TIME_ASSERT(uint64, 8==sizeof(uint64)); +COMPILE_TIME_ASSERT(int64, 8==sizeof(int64)); +#define HAVE_INT64 +#define HAVE_UINT64 +#elif SIZEOF_LONG == 8 +typedef unsigned long uint64; +typedef signed long int64; +COMPILE_TIME_ASSERT(uint64, 8==sizeof(uint64)); +COMPILE_TIME_ASSERT(int64, 8==sizeof(int64)); +#define HAVE_INT64 +#define HAVE_UINT64 +#elif SIZEOF_LONG_LONG == 8 +typedef unsigned long long uint64; +typedef signed long long int64; +COMPILE_TIME_ASSERT(uint64, 8==sizeof(uint64)); +COMPILE_TIME_ASSERT(int64, 8==sizeof(int64)); +#define HAVE_INT64 +#define HAVE_UINT64 +#endif + +typedef uint8 u8; +typedef int8 s8; +typedef uint16 u16; +typedef int16 s16; +typedef uint32 u32; +typedef int32 s32; + + + +#endif // SIZED_TYPES_H + -- 2.34.1