GBProg

Unknown
                         Programming Info

Information about GameBoy hardware and programming is extremely hard to
find. Most of it is incomplete, uncertain and vague. If you have any new
information, PLEASE, email it to me. The following information is mostly
based on a document by Pan of Anthrox, Jeff Frohwein's, Pascal Felber's,
and my own findings.
---------------------------------------------------------------------------

Memory Map

--------------------------- FFFF  | 32kB ROMs are non-switchable and occupy
 I/O ports + internal RAM         | 0000-7FFF are. Bigger ROMs use one of two
--------------------------- FF00  | different bank switches. The type of a
 Internal RAM                     | bank switch can be determined from the
--------------------------- C000  | internal info area located at 0100-014F
 8kB switchable RAM bank          | in each cartridge.
--------------------------- A000  |
 16kB VRAM                        | MBC1 (Memory Bank Controller 1):
--------------------------- 8000  | Writing a value into 2000-3FFF area will
 16kB switchable ROM bank         | select an appropriate ROM bank at
--------------------------- 4000  | 4000-7FFF. Writing a value into 4000-5FFF
 16kB ROM bank #0                 | area will select an appropriate RAM bank
--------------------------- 0000  | at A000-C000.
                                  |
                                  | MBC2 (Memory Bank Controller 2):
                                  | Writing a value into 2100-21FF area will
                                  | select an appropriate ROM bank at
                                  | 4000-7FFF. RAM switching is not provided.

CPU

As it appears, the CPU used in GameBoy is not exactly Z80. Some of Z80
instructions and registers are missing while others are added:

   * The "shadow" set of registers (BC',DE',HL',AF') and the index
     registers (IX,IY) are missing and, consequently, there are no DD and
     FD opcode tables.
   * I/O ports are gone and so are all IN/OUT opcodes.
   * HALT is interrupted even when interrupts are disabled.

Following Z80 opcodes are changed:

------------------------------------------------------------------------------
Code       Z80 operation  GameBoy operation
------------------------------------------------------------------------------
08 xx xx   EX AF,AF'      LD (word),SP     Save SP at given address
10 xx      DJNZ offset    STOP             Meaning unknown
22         LD (word),HL   LD (HLI),A       Save A at (HL) and increment HL
2A         LD HL,(word)   LD A,(HLI)       Load A from (HL) and increment HL
32         LD (word),A    LD (HLD),A       Save A at (HL) and decrement HL
3A         LD A,(word)    LD A,(HLD)       Load A from (HL) and decrement HL
D3         OUTA (byte)    No operation
D9         EXX            RETI             Enable interrupts and return
DB         INA (byte)     No operation
DD         Prefix DD      No operation
E0 xx      RET PO         LD (byte),A      Save A at (FF00+byte)
E2         JP PO,word     LD (C),A         Save A at (FF00+C)
E3         EX HL,(SP)     No operation
E4         CALL PO,word   No operation
E8 xx      RET PE         ADD SP,offset    Add signed offset to SP
EA xx xx   JP PE,word     LD (word),A      Save A at given address
EB         EX DE,HL       No operation
EC         CALL PE,word   No operation
F0 xx      RET P          LD A,(byte)      Load A from (FF00+byte)
F2         JP P,word      No operation
F4         CALL P,word    No operation
F8 xx      RET M          LDHL SP,offset   Load HL with SP + signed offset
FA xx xx   JP M,word      LD A,(word)      Load A from given address
FC         CALL M,word    No operation
FD         Prefix FD      No operation
------------------------------------------------------------------------------

Internal information area

The internal information area is located at 0100-014F in each cartridge. It
contains following values:

0100-0103  A sequence of bytes 00 C3 xx xx where last two bytes contain the
           starting address of a cartridge (lower byte first). The first two
           bytes of this sequence can be used as a "magic number" to
           recognize GameBoy cartridges. When GameBoy starts, the control is
           passed to address 0100 and then the sequence is interpreted as
           NOP; JP .
0105-0133  Nintendo character area:
           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
0134-0143  Title of the game in ASCII terminated by zeroes
0144-0146  Not used
0147       Cartridge type:
           0 - ROM ONLY         3 - ROM+MBC1+RAM+BATTERY
           1 - ROM+MBC1         5 - ROM+MBC2
           2 - ROM+MBC1+RAM     6 - ROM+MBC2+BATTERY
0148       ROM size:
           0 - 256kBit =  32kB =  2 banks
           1 - 512kBit =  64kB =  4 banks
           2 -   1MBit = 128kB =  8 banks
           3 -   2MBit = 256kB = 16 banks
           4 -   4MBit = 512kB = 32 banks
0149       RAM size:
           0 - None
           1 -  16kBit =  2kB = 1 bank
           2 -  64kBit =  8kB = 1 bank
           3 - 256kBit = 32kB = 4 banks
0150-0151  Manufacturer code:
           3301 - Nintendo
           7901 - Accolade
           A400 - Konami
014C       Version number
014D       Complement check
014E-014F  Checksum (higher byte first) produced by adding all bytes of
           a cartridge except for two checksum bytes together and taking
           two lower bytes of the result.

Interrupts

This section is not ready yet.

Video

The main GameBoy screen buffer (aka background) consists of 256x256 pixels
or 32x32 tiles (8x8 pixels each). Only 160x144 pixels can be displayed on
the screen. Registers SCROLLX and SCROLLY hold the coordinates of
background to be displayed in the left upper corner of the screen.
Background wraps around the screen i.e. when part of it goes off the
screen, it appears on the opposite side.

An area of VRAM known as Background Tile Table 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 Pattern 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 Pattern Table address for the background can be selected via LCDCONT
register.

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
WNDPOSX and WNDPOSY registers. Screen coordinates of the top left corner of
a window are WNDPOSX-7,WNDPOSY. The tile numbers for the window are stored
in the Window Tile Table in the same way as background tiles are stored in
the Background Tile Table. The tile patterns are taken from the table at
8800-97FF and therefore have unsigned numbers.

Both background and window can be disabled or enabled separately via bits
in the LCDCONT register.

The tile images are stored in the Tile Pattern Tables. Each 8x8 image
occupies 16 bytes, where each 2 bytes represent a line:

  Tile:                                              Image:

  .33333..                               .33333.. -> 01111100 -> 7Ch
  22...22.                                           01111100 -> 7Ch
  11...11.                               22...22. -> 00000000 -> 00h
  2222222. <-- digits represent                      11000110 -> C6h
  33...33.     color numbers             11...11. -> 11000110 -> C6h
  22...22.                                           00000000 -> 00h
  11...11.                               2222222. -> 00000000 -> 00h
  ........                                           11111110 -> FEh
                                         33...33. -> 11000110 -> C6h
                                                     11000110 -> C6h
                                         22...22. -> 00000000 -> 00h
                                                     11000110 -> C6h
                                         11...11. -> 11000110 -> C6h
                                                     00000000 -> 00h
                                         ........ -> 00000000 -> 00h
                                                     00000000 -> 00h

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.

Sprites

GameBoy video controller can display up to 40 sprites either in 8x8 or in
8x16 mode. Sprite patterns have the same format as tiles, but they are
taken from the Sprite Pattern Table located at 8000-8FFF and therefore have
unsigned numbers. Sprite attributes reside in the Sprite Attribute Table
(aka OAM) at FE00-FE9F. OAM is divided into 40 4-byte blocks each of which
corresponds to a sprite. Blocks have the following format:

  Byte0  Y position on the screen
  Byte1  X position on the screen
  Byte2  Pattern number 0-255 [notice that unlike tile numbers, sprite
         pattern numbers are unsigned]
  Byte3  Flags:
         Bit7  Priority
               Sprite is displayed in front of the window if this bit
               is set to 1. Otherwise, sprite is shown behind the
               window but in front of the background.
         Bit6  Y flip
               Sprite pattern is flipped vertically if this bit is
               set to 1.
         Bit5  X flip
               Sprite pattern is flipped horizontally if this bit is
               set to 1.
         Bit4  Palette number
               Sprite colors are taken from OBJ1PAL if this bit is
               set to 1 and from OBJ0PAL otherwise.

Sound

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
produces sound in four different ways:

   * Quadrangular wave patterns with sweep and envelope functions
   * Quadrangular wave patterns with envelope functions
   * Voluntary wave pattern
   * White noise

These four sounds can be controlled independantly and then mixed separately
for each of the output terminals.

I/O Ports

  I/O ports are mapped to memory locations in FF00-FFFF area:
------------------------------------------------------------------------------
FF00 -- JOYPAD [RW] Joypad port
      Bit5   Bit4    | In order to scan the keys, output 0 into either Bit4
Bit3  DOWN   START   | or Bit5 of JOYPAD, wait for some time and read JOYPAD.
Bit2  UP     SELECT  | Bits 0-3 will be set to zeroes if corresponding
Bit1  LEFT   B       | buttons are pressed. Bits 6 and 7 are not used. Bits
Bit0  RIGHT  A       | 0-3 are connected to input lines P10-P13. Bits 4 and 5
                     | are connected to ouput lines P14 and P15.

        Example:
        ; Routine finding which buttons were pressed since the last check
        LD A,20h     ; Set 0 at the output line P14
        LD (FF00h),A ;
        LD A,(FF00h) ; Read JOYPAD several times to accomodate the noise
        LD A,(FF00h) ;
        CPL          ; Bits 0-3 are now 1s if corresponding buttons pressed
        AND 0Fh      ; Extract lower 4 bits carrying button status...
        SWAP A       ; ...and move them into upper for bits
        LD B,A       ; At this point: B = START.SELECT.B.A.x.x.x.x
        LD A,10h     ; Set 0 at the output line P15
        LD (FF00h),A ;
        LD A,(FF00h) ; Read JOYPAD several times to accomodate the noise
        LD A,(FF00h) ;
        LD A,(FF00h) ;
        LD A,(FF00h) ;
        LD A,(FF00h) ;
        LD A,(FF00h) ;
        CPL          ; Bits 0-3 are now 1s if corresponding buttons pressed
        AND 0Fh      ; Extract lower 4 bits carrying buttons' status...
        OR B         ; ...and combine them with 4 other button status bits
        LD D,A       ; At this point: D = START.SELECT.B.A.DOWN.UP.LEFT.RIGHT
        LD A,(FF8Bh) ; Read old button status from RAM
        XOR D        ; Set 1s for buttons whose status has changed
        AND D        ; Extract buttons which were *pressed* since last check
        LD (FF8Ch),A ; Save information of those buttons
        LD A,D       ; Update button status in RAM
        LD (FF8Bh),A ;
        LD A,30h     ; Set 1s at both P14 and P15 lines
        LD (FF00h),A ; [probably to reset the circuitry]

------------------------------------------------------------------------------
FF01 -- SIODATA [RW] Serial I/O Data
----------------------------------------------+---------------+---------------
FF02 -- SIOCONT [RW] Serial I/O Control       | when set to 1 | when set to 0
Bit7  Transfer start flag                     | START         | NO TRANSFER
Bit0  Serial I/O clock select                 | INTERNAL      | EXTERNAL
----------------------------------------------+---------------+---------------
FF04 -- DIVIDER [RW] Divider [meaning unknown]
------------------------------------------------------------------------------
FF05 -- TIMECNT [RW] Timer Counter
        This register contains constantly increasing number. The timer
        interrupt occurs when this register overflows.
------------------------------------------------------------------------------
FF06 -- TIMEMOD [RW] Timer Modulo
        The contents of TIMEMOD are loaded into TIMECNT every time TIMECNT
        overflows.
----------------------------------------------+---------------+---------------
FF07 -- TIMCONT [RW] Timer Control            | when set to 1 | when set to 0
Bit2    Start/Stop timer                      | COUNTING      | STOPPED
Bit1-0  Timer clock select:
  00 - 4096Hz    01 - 262144Hz    10 - 65536Hz    11 - 16384Hz
----------------------------------------------+---------------+---------------
FF0F -- IFLAGS [RW] Interrupt Flags           | when set to 1 | when set to 0
Bit4  Transition High->Low on pins P10-P13    | OCCURED       | NO
Bit3  End of serial I/O transfer              | OCCURED       | NO
Bit2  Timer overflow                          | OCCURED       | NO
Bit1  LCD controller interrupt [see LCDSTAT]  | OCCURED       | NO
Bit0  LCD vertical blanking impulse           | OCCURED       | NO
----------------------------------------------+---------------+---------------
FF10 -- SNDREG10 [RW] Sweep [Sound Mode #1]
Bit6-4  Sweep time:
  000: SWEEP OFF    010: 15.6ms    100: 31.3ms    110: 46.9ms
  001: 7.8ms        011: 23.4ms    101: 39.1ms    111: 54.7ms
Bit3    Frequency increase[0]/decrease[1]
Bit2-0  Number of shifts
------------------------------------------------------------------------------
FF11 -- SNDREG11 [RW] Sound Length/Pattern Duty [Sound Mode #1]
Bit7-6  Wave Pattern Duty [only these bits can be read]:
  00: 12.5%    01: 25%    10: 50%    11: 75%
Bit5-0  Length of sound data
------------------------------------------------------------------------------
FF12 -- SNDREG12 [RW] Control [Sound Mode #1]
Bit7-4  Initial value of envelope
Bit3    Envelope up[1]/down[0]
Bit2-0  Number of envelope sweep
------------------------------------------------------------------------------
FF13 -- SNDREG13 [W] Frequency Low [Sound Mode #1]
        Lower 8 bits of the 11bit frequency. Higher 3 bits are in SNDREG14.
------------------------------------------------------------------------------
FF14 -- SNDREG14 [RW] Frequency High [Sound Mode #1]
Bit7    When 1 is written into this bit, sound restarts
Bit6    Counter/Consecutive selection [only this bit can be read]
Bit2-0  Higher 3 bits of the 11bit frequency
------------------------------------------------------------------------------
FF16 -- SNDREG21 [RW] Sound Length/Pattern Duty [Sound Mode #2]
Bit7-6  Wave Pattern Duty [only these bits can be read]:
  00: 12.5%    01: 25%    10: 50%    11: 75%
Bit5-0  Length of sound data
------------------------------------------------------------------------------
FF17 -- SNDREG22 [RW] Control [Sound Mode #2]
Bit7-4  Initial value of envelope
Bit3    Envelope up[1]/down[0]
Bit2-0  Number of envelope step
------------------------------------------------------------------------------
FF18 -- SNDREG23 [W] Frequency Low [Sound Mode #2]
        Lower 8 bits of the 11bit frequency. Higher 3 bits are in SNDREG24.
------------------------------------------------------------------------------
FF19 -- SNDREG24 [RW] Frequency High [Sound Mode #2]
Bit7    When 1 is written into this bit, sound restarts
Bit6    Counter/Consecutive selection [only this bit can be read]
Bit2-0  Higher 3 bits of the 11bit frequency
------------------------------------------------------------------------------
FF1A -- SNDREG30 [RW] Control [Sound Mode #3]
Bit7    Sound on[1]/off[0]
------------------------------------------------------------------------------
FF1B -- SNDREG31 [RW] Sound Length [Sound Mode #3]
------------------------------------------------------------------------------
FF1C -- SNDREG32 [RW] Output Level [Sound Mode #3]
Bit6-5  Output Level:
  00: MUTE    01: 100%    10: 50%    11: 25%
------------------------------------------------------------------------------
FF1D -- SNDREG33 [W] Frequency Low [Sound Mode #3]
        Lower 8 bits of the 11bit frequency. Higher 3 bits are in SNDREG34.
------------------------------------------------------------------------------
FF1E -- SNDREG34 [RW] Frequency High [Sound Mode #3]
Bit7    When 1 is written into this bit, sound restarts
Bit6    Counter/Consecutive selection [only this bit can be read]
Bit2-0  Higher 3 bits of the 11bit frequency
------------------------------------------------------------------------------
FF20 -- SNDREG41 [RW] Sound Length/Pattern Duty [Sound Mode #4]
Bit5-0  Length of sound data
------------------------------------------------------------------------------
FF21 -- SNDREG42 [RW] Control [Sound Mode #4]
Bit7-4  Initial value of envelope
Bit3    Envelope up[1]/down[0]
Bit2-0  Number of envelope step
------------------------------------------------------------------------------
FF22 -- SNDREG43 [RW] Polynomial Counter [Sound Mode #4]
Bit7-4  Shift clock frequency for the counter
  0000: Dividing ratio of frequencies / 2
  0001: Dividing ratio of frequencies / 2^2
  0010: Dividing ratio of frequencies / 2^3
  ....  ....
  1101: Dividing ratio of frequencies / 2^14
  1100: Prohibited
  1111: Prohibited
Bit3    Number of steps: 7 [1]/15 [0]
Bit2-0  Dividing ratio of frequences
  000: f*2    010: f/2    100: f/4    110: f/6    where f = 4.194304Mhz/8
  001: f*1    011: f/3    101: f/5    111: f/7
------------------------------------------------------------------------------
FF23 -- SNDREG44 [RW] Frequency High [Sound Mode #4]
Bit7    When 1 is written into this bit, sound restarts
Bit6    Counter/Consecutive selection [only this bit can be read]
------------------------------------------------------------------------------
FF24 -- SNDREG50 [RW] Channel and Volume Control
Bit7    Vin -> SO2 on[1]/off[0]
Bit6-4  Volume on SO2
Bit3    Vin -> SO1 on[1]/off[0]
Bit2-0  Volume on SO1
------------------------------------------------------------------------------
FF25 -- SNDREG51 [RW] Sound Output Terminal Selector
Bit7  Sound 4 -> SO2  |
Bit6  Sound 3 -> SO2  |
Bit5  Sound 2 -> SO2  | SO1 and SO2 are two sound outputs connected to the
Bit4  Sound 1 -> SO2  | headphones. Vin is an input terminal in the cartridge
Bit3  Sound 4 -> SO1  | slot.
Bit2  Sound 3 -> SO1  |
Bit1  Sound 2 -> SO1  |
Bit0  Sound 1 -> SO1  |
----------------------+-------------------------------------------------------
FF26 -- SNDREG52 [RW] Sound ON/OFF
Bit7  All sound on[1]/off[0]
Bit3  Sound 4 on[1]/off[0]
Bit2  Sound 3 on[1]/off[0]
Bit1  Sound 2 on[1]/off[0]
Bit0  Sound 1 on[1]/off[0]
----------------------------------------------+---------------+---------------
FF40 -- LCDCONT [RW] LCD Control              | when set to 1 | when set to 0
Bit7  LCD operation                           | ON            | OFF
Bit6  Window Tile Table address               | 9C00-9FFF     | 9800-9BFF
Bit5  Window display                          | ON            | OFF
Bit4  Tile Pattern Table address              | 8000-8FFF     | 8800-97FF
Bit3  Background Tile Table address           | 9C00-9FFF     | 9800-9BFF
Bit2  Sprite size                             | 8x16          | 8x8
Bit1  Color #0 transparency in the window     | SOLID         | TRANSPARENT
Bit0  Background display                      | ON            | OFF
----------------------------------------------+---------------+---------------
FF41 -- LCDSTAT [RW] LCD Status               | when set to 1 | when set to 0
Bit6    Interrupt on scanline coincidence     | ON            | OFF
Bit5    Interrupt on controller mode 10       | ON            | OFF
Bit4    Interrupt on controller mode 01       | ON            | OFF
Bit3    Interrupt on controller mode 00       | ON            | OFF
Bit2    Scanline coincidence flag             | COINCIDENCE   | NO COINCIDENCE
Bit1-0  LCD Controller mode:
  00 - Horizontal blanking impulse [VRAM 8000-9FFF can be accessed by CPU]
  01 - Vertical blanking impulse [VRAM 8000-9FFF can be accessed by CPU]
  10 - OAM FE00-FE90 is accessed by LCD controller
  11 - Both OAM FE00-FE90 and VRAM 8000-9FFF are accessed by LCD controller
------------------------------------------------------------------------------
FF42 -- SCROLLY [RW] Background Vertical Scrolling
------------------------------------------------------------------------------
FF43 -- SCROLLX [RW] Background Horizontal Scrolling
------------------------------------------------------------------------------
FF44 -- CURLINE [RW] Current Scanline
        This register contains the number of a screen line currently being
        scanned. It can take values 0-153 where 144-153 indicate the vertical
        blanking period. Writing into this register resets it.
------------------------------------------------------------------------------
FF45 -- CMPLINE [RW] Scanline Comparison
        When contents of CURLINE are equal to contents of CMPLINE, scanline
        coincidence flag is set in the LCD status register and an interrupt
        may occur.
------------------------------------------------------------------------------
FF47 -- BGRDPAL [W] Background Palette
Bit7-6  Palette for color #3  |
Bit5-4  Palette for color #2  |     00 ------- 01 ------- 10 -------> 11
Bit3-2  Palette for color #1  |     lightest                     darkest
Bit1-0  Palette for color #0  |
------------------------------+-----------------------------------------------
FF48 -- OBJ0PAL [W] Sprite Palette #0
Bit7-6  Palette for color #3  |
Bit5-4  Palette for color #2  |     00 ------- 01 ------- 10 -------> 11
Bit3-2  Palette for color #1  |     lightest                     darkest
Bit1-0  Palette for color #0  |
------------------------------+-----------------------------------------------
FF49 -- OBJ1PAL [W] Sprite Palette #1
Bit7-6  Palette for color #3  |
Bit5-4  Palette for color #2  |     00 ------- 01 ------- 10 -------> 11
Bit3-2  Palette for color #1  |     lightest                     darkest
Bit1-0  Palette for color #0  |
------------------------------+-----------------------------------------------
FF4A -- WNDPOSY [RW] Window Y Position
        WNDPOSY may assume values 0-143. It determines the vertical position
        of the left upper corner of a window on the screen.
------------------------------------------------------------------------------
FF4B -- WNDPOSX [RW] Window X Position
        WNDPOSX may assume values 7-166. It determines the horizontal position
        of the left upper corner of a window on the screen. The real position
        is WNDPOSX-7.
------------------------------------------------------------------------------
FF46 -- DMACONT [W] DMA Transfer Control
        Writing to this register will cause a DMA transfer into OAM located
        at FE00-FE9F. The written value determines the source address in a
        following way: 00 -> 0000, 01 -> 0100, ... , 9A -> 9A00, ...
        The DMA transfer takes about 160 nanoseconds.

        Example:
        ; Routine transferring 0400-049F into OAM
        DI           ; Disable interrupts
        LD A,04h     ; Transferring data from 0400h
        LD (FF46h),A ; Start DMA transfer
  LOOP: LD A,#40     ; Wait
        DEC A        ;
        JR NZ,LOOP   ;
        EI           ; Enable interrupts

----------------------------------------------+---------------+---------------
FFFF -- ISWITCH [RW] Interrupt Enable/Disable | when set to 1 | when set to 0
Bit4  Transition High->Low on pins P10-P13    | ENABLED       | DISABLED
Bit3  End of serial I/O transfer              | ENABLED       | DISABLED
Bit2  Timer overflow                          | ENABLED       | DISABLED
Bit1  LCD controller interrupt [see LCDSTAT]  | ENABLED       | DISABLED
Bit0  LCD vertical blanking impulse           | ENABLED       | DISABLED
----------------------------------------------+---------------+---------------