GBA CODING GUIDE
----------------

This document contains various notes and tips for Game Boy Advance
programmers. It was written by James Jacobs of Amigan Software on 1/7/09,
and last updated on 17/7/09. If you have any additions, corrections or
suggestions, please email us.

EMail: amigansoftware@gmail.com
URL:   http://amigan.1emu.net/

RAM
---

Variables are stored in IWRAM by default. As this is only 32K, it can
easily overflow. The HAM compiler does not complain about huge
allocations, eg.

    int foo[999999999];

so you can easily overflow the limited RAM available, without getting any
warnings about the situation. 256K is available in EWRAM. Eg.

    int DATA_IN_EWRAM foo[50000];

Sound
-----

The master sound control register does not seem to be correctly emulated.
Eg. in VisualBoy Advance and Boycott Advance, you can toggle it on and off
to enable/disable the sound. However, on the real handheld, sound will not
be reenabled. Probably you have to set up some of the other sound
registers again.

Tone Generators
---------------

For the square wave generators (channels 1 and 2), the algorithm for
deriving the frequency is:

    frequency = 131,072Hz / (2,048 - val));

where val is the contents of bits 10..0 of REG_SND1FREQ or REG_SND2FREQ.
Zero for all these bits means silence. 64..131,072Hz is the achievable
range.

Noise Generator
---------------

For the noise generator (channel 4), the algorithm for deriving the
frequency is:

    if (r == 0)
    {   frequency =  1,048,576Hz      / (2 ^ (s + 1));
    } else
    {   frequency = (  524,288Hz / r) / (2 ^ (s + 1));
    }

s is the "shift clock frequency".
It is a 4-bit number (0..11). 12..15 are not legal values.
It is bits 7..4 of SOUND4CNT_H aka REG_SND4FREQ.
r is the "dividing ratio" aka "frequency ratio" aka "clock divider".
It is a 3-bit number (0..7).
It is bits 2..0 of SOUND4CNT_H aka REG_SND4FREQ.

This table shows the resultant frequency of all possible combinations:

                                 r
        0      1      2     3        4     5       6        7
 s ----------------------------------------------------------------
 0 524288 262144 131072 87381.3' 65536 52428.8 43690.6' 37449.14286
 1 262144 131072  65536 43690.6' 32768 26214.4 21845.3' 18724.57143
 2 131072  65536  32768 21845.3' 16384 13107.2 10922.6'  9362.28571
 3  65536  32768  16384 10922.6'  8192  6553.6  5461.3'  4681.14286
 4  32768  16384   8192  5461.3'  4096  3276.8  2730.6'  2340.57143
 5  16384   8192   4096  2730.6'  2048  1638.4  1365.3'  1170.28571
 6   8192   4096   2048  1365.3'  1024   819.2   682.6'   585.14286
 7   4096   2048   1024   682.6'   512   409.6   341.3'   292.57143
 8   2048   1024    512   341.3'   256   204.8   170.6'   146.28571
 9   1024    512    256   170.6'   128   102.4    85.3'    73.14286
10    512    256    128    85.3'    64    51.2    42.6'    36.57143
11    256    128     64    42.6'    32    25.6    21.3'    18.28571

The value to use for the low byte of SOUND4CNT_H aka REG_SND4FREQ is:

                  r
    0   1   2   3   4   5   6   7
 s -------------------------------    If you want to have only 7-stage
 0 $00 $01 $02 $03 $04 $05 $06 $07    noise (for a more "metallic" noise)
 1 $10 $11 $12 $13 $14 $15 $16 $17    instead of 15-stage noise, add $08
 2 $20 $21 $22 $23 $24 $25 $26 $27    to these values.
 3 $30 $31 $32 $33 $34 $35 $36 $37
 4 $40 $41 $42 $43 $44 $45 $46 $47
 5 $50 $51 $52 $53 $54 $55 $56 $57
 6 $60 $61 $62 $63 $64 $65 $66 $67
 7 $70 $71 $72 $73 $74 $75 $76 $77
 8 $80 $81 $82 $83 $84 $85 $86 $87
 9 $90 $91 $92 $93 $94 $95 $96 $97
10 $A0 $A1 $A2 $A3 $A4 $A5 $A6 $A7
11 $B0 $B1 $B2 $B3 $B4 $B5 $B6 $B7

Speed
-----

The emulators can run at the wrong speed. DMA timing is apparently not
correctly emulated. The real handheld seems to generally run slower than
the emulators.

END OF DOCUMENT-----------------------------------------------------------