MMBNLC GBAState struct

Generally lives at address 0x80200040. Every GBA ASM function takes a GBAState reference as its first and only parameter, and is expected to return the original value of r15.

When you hook a GBA ASM function, you'll generally always find a reference to this struct in one of the registers. Which register it is can vary, though.

The way memory is accessed is slightly different between GBA and LC. In GBA, a memory pointer can be dereferenced directly to get the data. In LC, memory pointers are actually offsets in the GBA memory map. This means you have to add the base memory map address ("memory" field in GBAState.env) to the offset to get the actual virtual memory location of the data. While the GBA memory map used in LC is generally the same as the one on a real GBA, there is a difference in how variables and constants are loaded. On GBA variables are stored in WRAM (0x02000000 or sometimes 0x03000000) while constants are stored in the ROM (0x08000000). In LC these are both linked to memory range memory+0x00004000, which is initialized with labels.bin from the exe.dat file. It starts with zero-initialized data (hence why labels.bin is all zeros at the start) followed by constants.

#include <stdbool.h>
#include <stdint.h>

typedef enum : uint32_t {
    CPU_FLAG_NONE = 0x0,
    // The following 4 flags are used in the flags field
    CPU_FLAG_N = 0x1,  // signed flag
    CPU_FLAG_C = 0x2,  // carry flag
    CPU_FLAG_Z = 0x4,  // zero flag
    CPU_FLAG_V = 0x8,  // overflow flag
    // The following 4 flags are used in the flagsImplicitUpdate field
    CPU_FLAG_UPDATE_N = 0x10,
    CPU_FLAG_UPDATE_C = 0x20,
    CPU_FLAG_UPDATE_Z = 0x40,
    CPU_FLAG_UPDATE_V = 0x80,
} CPUFlags;

class nbExe;

typedef struct {
    struct {
        /* offset 0x00, size 0x4 */ uint32_t r0;
        /* offset 0x04, size 0x4 */ uint32_t r1;
        /* offset 0x08, size 0x4 */ uint32_t r2;
        /* offset 0x0C, size 0x4 */ uint32_t r3;
        /* offset 0x10, size 0x4 */ uint32_t r4;
        /* offset 0x14, size 0x4 */ uint32_t r5;
        /* offset 0x18, size 0x4 */ uint32_t r6;
        /* offset 0x1C, size 0x4 */ uint32_t r7;
        /* offset 0x20, size 0x4 */ uint32_t r8;
        /* offset 0x24, size 0x4 */ uint32_t r9;
        /* offset 0x28, size 0x4 */ uint32_t r10;
        /* offset 0x2C, size 0x4 */ uint32_t r11;
        /* offset 0x30, size 0x4 */ uint32_t r12;
        /* offset 0x34, size 0x4 */ union { uint32_t sp; uint32_t r13; };
        /* offset 0x38, size 0x4 */ union { uint32_t lr; uint32_t r14; };
        /* offset 0x3C, size 0x4 */ union { uint32_t pc; uint32_t r15; };
    } regs;
    struct {
        /// Original GBA ARM CPU flags
        /* offset 0x40, size 0x4 */ CPUFlags flags;
        /// CMP/TST instructions explicitly update all flags, but some instructions (e.g. ADD, SUB) can implicitly update flags.
        /// This field indicates which flags will be implicitly updated for such instructions. The other flags are preserved.
        /* offset 0x44, size 0x4 */ CPUFlags flagsImplicitUpdate;
        /// Points to GBA memory map, see below
        /* offset 0x48, size 0x8 */ void *memory;
        /// Direct virtual memory pointer to the bottom of the stack - maybe actually used for something else?
        /* offset 0x50, size 0x8 */ void *stackBottom;
        /// Pointer to nbExe class instance which owns the GBA instance
        /* offset 0x58, size 0x8 */ nbExe *owner;
        /// While a LDMIA/STMIA instruction is being run, the transient memory address is stored and incremented here
        /* offset 0x60, size 0x4 */ uint32_t addrLdmiaStmia;
        /// Number of registers on the stack
        /* offset 0x64, size 0x4 */ uint32_t stackCount;
        /// Incremented by 1 when lr (r14) is pushed onto the stack
        /// Decremented by 1 when pc (r15) is popped from the stack
        /* offset 0x68, size 0x4 */ uint32_t callDepth;
        /// Always set to 1? Purpose unknown
        /* offset 0x6C, size 0x4 */ uint32_t always1;
        /// Set to true when entering a function from an alternate entry point
        /// Reset to false after alternate entry point is checked
        /* offset 0x70, size 0x1 */ bool isAltEntry;
        /// Unknown pointer related to overlays
        /* offset 0x78, size 0x8 */ void *overlayUnk;
        /// Overlay picture on background
        /* offset 0x80, size 0x8 */ void *overlayBG;
        /// Overlay picture on sprite objects
        /* offset 0x88, size 0x8 */ void *overlayOBJ;
        /// Unknown pointer which is written (only?) in objtrans::ObjCharInit but doesn't seem to be used
        /* offset 0x90, size 0x8 */ void *objUnk;
    } env;
} GBAState __attribute__((aligned(0x40)));

Full memory size = 0x14800000
memory+0x00004000 = Initialized R+W data (labels.bin)
memory+0x02000000 = GBA Working RAM (equivalent to 0x2000000 on GBA)
    Most game variables are in labels, but WRAM is still used for e.g. graphics data buffers
memory+0x04000000 = GBA I/O Registers (equivalent to 0x4000000 on GBA)
memory+0x05000000 = GBA Palette RAM (equivalent to 0x5000000 on GBA)
memory+0x06000000 = GBA Video RAM (equivalent to 0x6000000 on GBA)
memory+0x07000000 = GBA Object RAM (equivalent to 0x7000000 on GBA)
memory+0x08000000 = GBA ROM Original (equivalent to 0x80000000 on GBA)
    Japanese ROM is loaded here (even if playing in English)
memory+0x10000000 = mpak
    mpak for current language is loaded here
memory+0x12000000 = GBA Working RAM (equivalent to 0x2000000)
    Text archive which would normally be loaded to 0x20xxxxx is loaded to 0x120xxxxx instead
    See game function moji::sub::MojiPrintVramSet
    Presumably done to allow loading text archives which exceed the size of the original buffer
    (This does happen with some English text archives)
memory+0x13FFFDB0 = ???
memory+0x13FFFF60 = GBA ROM Localized (equivalent to 0x8000000 on GBA)
    English ROM is loaded here

On alternate entry points: some functions have two entry points, for instance:

entryPointA:
    mov     r0,0x0
    b       @@startOfFunction
entryPointB:
    mov     r0,0x4
@@startOfFunction:
    push    r4-r7,r15
    // ...

In LC, the way this is handled is entryPointA sets isAltEntry to true and then jumps to entryPointB. entryPointB checks isAltEntry and if it's set to true, it will skip doing its own initialization before @@startOfFunction, and set isAltEntry back to false.