Skip to content

Latest commit

 

History

History
299 lines (241 loc) · 6.81 KB

CONTRIBUTING.md

File metadata and controls

299 lines (241 loc) · 6.81 KB
Raw

Decompiling

Code starts out in asm/. When decompiled to C, it goes into src/. The goal is to decompile all the code.

Some of the code in asm/ is handwritten assembly. It can't and shouldn't be decompiled. It's already commented, so there's no further work to do on these files. Check linker.ld and ignore anything under the "handwritten assembly" section.

The rest of the .s files in asm/ are fair game.

The basic decompilation process is:

  • Choose a file in asm/, i.e. asm/x.s. Create a C file called src/x.c.
  • Translate the first function in asm/x.s to C in src/x.c.
  • make, and tweak the function until it matches.
  • Clean up the code and comment.
  • Repeat for each function until asm/x.s is empty.

For example, let's decompile asm/evilSpirit.s.

1. Create src/evilSpirit.c

#include "global.h"

global.h contains typedefs for GBA programming and more. It must be the first include in the file. Other includes will assume you have included it.

2. Include it in the rom

Include src/evilSpirit.c in the rom by adding src/evilSpirit.o to linker.ld:

	asm/room.o(.text);
	asm/code_08080974.o(.text);
+	src/evilSpirit.o(.text);
	asm/evilSpirit.o(.text);
	asm/houseDoorExterior.o(.text);

Do not remove asm/evilSpirit.o(.text). We want both src/evilSpirit.c and asm/evilSpirit.s in the rom.

3. Translate the function to C

Take the first function in asm/evilSpirit.s. Either comment it out or remove it, whichever is easier.

	thumb_func_start sub_08086284
sub_08086284: @ 0x08086284
	push {r4, lr}
	adds r4, r0, #0
	ldr r1, _080862B4 @ =gUnk_08120668
	ldrb r0, [r4, #0xc]
	lsls r0, r0, #2
	adds r0, r0, r1
	ldr r1, [r0]
	adds r0, r4, #0
	bl _call_via_r1
	adds r1, r4, #0
	adds r1, #0x41
	movs r0, #0
	strb r0, [r1]
	adds r0, r4, #0
	adds r0, #0x76
	ldrh r1, [r0]
	adds r0, #4
	ldrh r2, [r0]
	adds r0, r4, #0
	movs r3, #0
	bl SetAffineInfo
	pop {r4, pc}
	.align 2, 0
_080862B4: .4byte gUnk_08120668

Then, start translating the code to src/evilSpirit.c, bit by bit:

	push {r4, lr}
	adds r4, r0, #0
	void sub_08086284(u8* r0) {
        ldr     r1, _080862B4 @ =gUnk_08120668
        ldrb    r0, [r4, #0xc]
        lsl     r0, r0, #0x2
        add     r0, r0, r1
        ldr     r1, [r0]
        add     r0, r4, #0
        bl      _call_via_r1
	gUnk_08120668[*(u8 *)(r0 + 0xc)](r0);
        add     r1, r4, #0
        add     r1, r1, #0x41
        mov     r0, #0
        strb    r0, [r1]
    *(u8 *)(r0 + 0x41) = 0;
        add     r0, r4, #0
        add     r0, r0, #0x76
        ldrh    r1, [r0]
        add     r0, r0, #0x4
        ldrh    r2, [r0]
        add     r0, r4, #0
        mov     r3, #0
        bl      SetAffineInfo
	SetAffineInfo(r0, *(u16 *)(r0 + 0x76), *(u16 *)(r0 + 0x7a), 0);
        pop     {r4, pc}
	return;

The type signature of the function depends on the return type. Return values are stored in r0, so pay attention to how the assembly treats this register toward the end of the function. ex:

  • add r0, r4, #0

    pop {r4, pc}

The compiler chose to move a value into r0 here; the most likely explanation is that it's returning something.

You will need to look at the caller and the function prologue to determine the exact type if not void.

Since it only used pop {r4, pc}, it's probably void.

Putting it all together, we get:

void sub_08086284(u8 *r0) {
    gUnk_08120668[*(u8 *)(r0 + 0xc)](r0);
    *(u8 *)(r0 + 0x41) = 0;
    SetAffineInfo(r0, *(u16 *)(r0 + 0x76), *(u16 *)(r0 + 0x7a), 0);
    return;
}

4. Simplify and document

This line doesn't look quite right.

	gUnk_08120668[*(u8 *)(r0 + 0xc)](r0);

What is r0? Since this function corresponds to an entity, we should first try to assign r0 to an Entity struct. You can find out what this is with git grep:

git grep "Entity" include/
include/entity.h:typedef struct Entity

So it's a struct called Entity. Let's look in entity.h:

typedef struct Entity_ {
    /*0x00*/ struct Entity_* prev;
    /*0x04*/ struct Entity_* next;
    /*0x08*/ u8 kind;
    /*0x09*/ u8 id;
    /*0x0a*/ u8 type;
    /*0x0b*/ u8 type2;
    /*0x0c*/ u8 action;
    /*0x0d*/ u8 subAction;
    ...
} Entity;

What's the 12th byte in this struct?

    /*0x00*/ struct Entity_* prev;
    /*0x04*/ struct Entity_* next;
    ...
    /*0x0c*/ u8 action; <-

The 12th byte belongs to action. We can substitute this in by replacing r0's parameter type and adding in the member names.

void sub_08086284(Entity *r0) {
    gUnk_08120668[r0->action](r0);

Much better.

void sub_08086284(Entity *r0) {
    gUnk_08120668[r0->action](r0);
    r0->bitfield = 0;
    SetAffineInfo(r0, r0->field_0x76.HWORD, r0->field_0x7a.HWORD, 0);
    return;
}

The fields at the end of of Entity are general purpose. For this reason the fields are defined as unions so the proper data size may be loaded. This isn't pretty, but right now we are just concerned with making the function match. Later on we can define these entity-specific fields.

5. Build

make
src/evilSpirit.c: In function `sub_08086284':
src/evilSpirit.c:4: syntax error before `*'
src/evilSpirit.c:5: `gUnk_08120668' undeclared (first use in this function)
src/evilSpirit.c:5: (Each undeclared identifier is reported only once for each function it appears in.)
src/evilSpirit.c:7: warning: implicit declaration of function `SetAffineInfo'

We got some errors. We need to tell the compiler what gUnk_08120668, Entity, and SetAffineInfo are.

We know r0 is an Entity, which is from entity.h. We can declare this above the function:

#include "entity.h"

What about gUnk_08120668 and SetAffineInfo?

extern void SetAffineInfo();
extern void (*gUnk_08120668[])(Entity *);

Now the compiler will look outside of this file for both of these. We don't have to set the size of gUnk_08120668, a function array, since it's size is irrelevant for now.

Now our file looks like this:

#include "global.h"
#include "entity.h"

extern void SetAffineInfo();
extern void (*gUnk_08120668[])(Entity *);

void sub_08086284(Entity *r0) {
    gUnk_08120668[r0->action](r0);
    r0->bitfield = 0;
    SetAffineInfo(r0, r0->field_0x76.HWORD, r0->field_0x7a.HWORD, 0);
    return;
}

Build again, and we get:

make
tmc.gba: OK

This means the function matches. Congratulations!

If it doesn't match, you will get:

tmc.gba: FAILED
sha1sum: WARNING: 1 computed checksum did NOT match

If you forgot to remove the function from asm/evilSpirit.s, you will get this error:

asm/evilSpirit.o: In function `sub_08086284':
(.text+0x0): multiple definition of `sub_08086284'
src/evilSpirit.o:(.text+0x0): first defined here