Luma's Workshop - User contributions [en]

Memory Map

2026-04-26T21:13:08Z

Shibboleet: /* Broadway / IOS Global Memory Locations */

{| class="wikitable"
|-
! Start Address
! End Address
! Physical Address
! Physical End Address
! Size
! Description
|-
| 0x80000000
| 0x817FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Cached)
|-
| 0xC0000000
| 0xC17FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Uncached)
|-
| 0x90000000
| 0x93FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Cached)
|-
| 0xD0000000
| 0xD3FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Uncached)
|-
| 0xCD000000
| 0xCD008000
| 0x0D000000
| 0x0D008000
| 32 KB
| |Hollywood Registers (shared with Starlet)
|-
| 0xCC000000
| 0xCC008003
| 0x0C000000
| 0x0C008003
| 32 KB
| Broadway hardware registers
|-
| 0xC8000000
| 0xC8300000
| 0x08000000
| 0x08300000
| 3MB
| GX Embedded FrameBuffer (EFB)
|-
| Not Mapped
| Not Mapped
| 0xFFF00100
| 0xFFF0013F
| 64 bytes
| EXI boot code mirror
|}

== Broadway / IOS Global Memory Locations ==
{| class="wikitable"
|-
! Address
! Size
! (Typical) Value
! Description
|-
| 0x80000000
| 4
| 0x52535045
| Game Code 'RSPE' (Wii Sports)
|-
| 0x80000004
| 2
| 0x3031 (01)
| Maker code
|-
| 0x80000006
| 1
| 0
| Disc Number (multidisc games)
|-
| 0x80000007
| 1
| ?
| Disc Version
|-
| 0x80000008
| 1
| ?
| Disc Streaming flag
|-
| 0x80000009
| 1
| ?
| Disc Streaming buffer size
|-
| 0x80000018
| 4
| 0x5D1C9EA3
| Disc layout magic (Wii)
|-
| 0x8000001C
| 4
| 0xC2339F3D
| Disc layout magic (GC)
|-
| 0x80000020
| 4
| 0x0D15EA5E
| Nintendo Standard Boot Code.
|-
| 0x80000024
| 4
| 0x00000001
| Version (set by apploader)
|-
| 0x80000028
| 4
| 0x01800000
| Memory Size (Physical) 24MB
|-
| 0x8000002C
| 4
| 0x00000023
| Production Board Model
|-
| 0x80000030
| 4
| 0x00000000
| Arena Low
|-
| 0x80000034
| 4
| 0x817FEC60
| Arena High
|-
| 0x80000038
| 4
| 0x817FEC60
| Start of FST (varies in all games)
|-
| 0x8000003C
| 4
| 0x00001394
| Maximum FST Size (varies in all games)
|-
| 0x80000040
| 4
| ?
| Beginning of the DB global struct
|-
| 0x80000044
| 4
| ?
| DB marked exception mask
|-
| 0x80000048
| 4
| 0x81340000
| DB exception destination
|-
| 0x8000004C
| 4
| ?
| DB return address
|-
| 0x80000060
| 0x24
| OSDBIntegrator [http://hitmen.c02.at/files/yagcd/yagcd/chap4.html#sec4.2.1.3 Debugger Hook]
| Hook to be jumped to by debugged exceptions, but is disabled in production software. If nothing is written to it, SDK titles will write the 0x20 bytes of instructions here.
|-
| 0x800000C0
| 4
| ?
| Current OSContext instance (real mode)
|-
| 0x800000C4
| 4
| 0xffffff00
| User interrupt mask
|-
| 0x800000C8
| 4
| 0
| Revolution OS interrupt mask
|-
| 0x800000CC
| 4
| 0
| Value indicating the current video mode. 0 = NTSC, 1 = PAL, 2 = MPAL
|-
| 0x800000D4
| 4
| ?
| Current OSContext instance (translated mode)
|-
| 0x800000D8
| 4
| 0
| OSContext to save FPRs to (NULL if floating point mode hasn't been used since the last interrupt)
|-
| 0x800000DC
| 4
| ?
| Pointer to the earliest created OSThread
|-
| 0x800000E0
| 4
| ?
| Pointer to the most recently created OSThread
|-
| 0x800000E4
| 4
| ?
| Pointer to the current OSThread
|-
| 0x800000EC
| 4
| 0x81800000
| Dev Debugger Monitor Address (If present)
|-
| 0x800000F0
| 4
| 0x01800000
| Simulated Memory Size
|-
| 0x800000F4
| 4
| 0x817FDF80
| Pointer to data read from partition's bi2.bin, set by apploader, or the emulated bi2.bin created by the NAND Boot Program
|-
| 0x800000F8
| 4
| 0x0E7BE2C0
| Console Bus Speed
|-
| 0x800000FC
| 4
| 0x2B73A840
| Console CPU Speed
|-
| 0x80000100
| 0x1700
|
| Exception handlers (0x100 bytes reserved for each handler)
|- style="background-color: #fdd;"
| 0x80001800
| 0x1800
|
| Unused exception handler area, the SDK does not use or clear it. Custom code uses this memory region for the loader.
|-
| 0x80003000
| 0x3c
| ?
| Exception vector area
|-
| 0x80003040
| 4
| ?
| __OSInterrupt table.
|-
| 0x800030C0
| 8
| ?
| EXI Probe start times, for both channels 0 and 1.
|-
| 0x800030C8
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the first loaded REL file.
|-
| 0x800030CC
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the last loaded REL file.
|-
| 0x800030D0
| 4
| 0
| Pointer to a REL module name table, or 0. Added to the name offset in each REL file.
|-
| 0x800030D8
| 8
| 0x005498F053407000
| System time, measured as time since January 1st 2000 in units of 1/40500000th of a second.
|-
| 0x800030E4
| 2
| ?
| __OSPADButton. Apploader puts button state of GCN port 4 at game start here for Gamecube NR disc support
|-
| 0x800030E6
| 2
| ?
| DVD Device Code Address
|-
| 0x800030E8
| 4
| ?
| Debug-related info
|-
| 0x800030F0
| 4
| 0x00000000
| DOL Execute Parameters
|-
| 0x800030F4
| 4
| ?
| Current TGC Offset in the Apploader.
|-
| 0x80003100
| 4
| ?
| Physical MEM1 size
|-
| 0x80003104
| 4
| ?
| Simulated MEM1 size
|-
| 0x8000310C
| 4
| ?
| MEM1 Arena Start (start of usable memory by the game)
|-
| 0x80003110
| 4
| ?
| MEM1 Arena End (end of usable memory by the game)
|-
| 0x80003118
| 4
| 0x04000000
| Physical MEM2 size. (0x3118-0x314C are set by IOS upon reload.)
|-
| 0x8000311C
| 4
| 0x04000000
| Simulated MEM2 size.
|-
| 0x80003120
| 4
| 0x93400000
| End of MEM2 addressable to PPC.
|-
| 0x80003124
| 4
| 0x90000800
| Usable MEM2 Start (start of usable memory by the game)
|-
| 0x80003128
| 4
| 0x933E0000
| Usable MEM2 End (end of usable memory by the game)
|-
| 0x80003130
| 4
| 0x933E0000
| IOS IPC Buffer Start
|-
| 0x80003134
| 4
| 0x93400000
| IOS IPC Buffer End
|-
| 0x80003138
| 4
| 0x00000011
| Hollywood Version
|-
| 0x80003140
| 4
| 0x00090204
| IOS version (090204 = IOS9, v2.4)
|-
| 0x80003144
| 4
| 0x00062507
| IOS Build Date (62507 = 06/25/07 = June 25, 2007)
|-
| 0x80003148
| 4
| 0x93600000
| IOS Reserved Heap Start
|-
| 0x8000314C
| 4
| 0x93620000
| IOS Reserved Heap End
|-
| 0x80003158
| 4
| 0x0000FF16
| GDDR Vendor Code
|-
| 0x8000315C
| 1
| 0x80
| During the boot process, u32 0x315c is first set to 0xdeadbeef by IOS in the boot_ppc syscall. The value is set to 0x80 by the NAND Boot Program to indicate that it was loaded by the boot program (and probably 0x81 by apploaders)
|-
| 0x8000315D
| 1
| 0?
| "Enable legacy DI" mode? 0x81 = false, anything else means true (though typically set to 0x80). Required to be set when loading Gamecube apploader.
|-
| 0x8000315E
| 2
| 0x0113
| "Devkit boot program version", written to by the system menu. The value carries over to disc games. 0x0113 appears to mean v1.13.
|-
| 0x80003160
| 4
| 0x00000000
| Init semaphore (1-2 main() waits for this to clear)
|-
| 0x80003164
| 4
| 0x00000000
| GC (MIOS) mode flag, set to 1 by boot2 when MIOS triggers a shutdown; the System Menu reads this and turns off the console if it is set to 1 and :/title/00000001/00000002/data/state.dat|state.dat is set appropriately.
|-
| 0x80003180
| 4
| 0x52535045
| Game ID 'RSPE' Wii Sports ID. If these 4 bytes don't match the ID at 80000000, WC24 mode in games is disabled.
|-
| 0x80003184
| 1
| 0x80
| Application type. 0x80 for disc games, 0x81 for channels.
|-
| 0x80003186
| 1
| 0x00
| Application type 2. Appears to be set to the when a game loads a channel (e.g. Mario Kart Wii loading the region select menu will result in this being 0x80 from the disc and the main application type being 0x81, or the Wii Fit channel transitioning to the Wii Fit disc will result in this being 0x81 and the main type being 0x80).
|-
| 0x80003187
| 1
| 0x00
| Determines if the current application needs a TMD Ticket to launch. (0x00 = Not Locked, 0x80 = Locked)
|-
| 0x80003188
| 4
| 0x00351011
| Minimum IOS version (2 bytes for the major version, 2 bytes for the title version)
|-
| 0x8000318C
| 4
| 0x00000000
| Title Booted from NAND (Launch Code)
|-
| 0x80003190
| 4
| 0x00000000
| Title Booted from NAND (Return Code)
|-
| 0x80003194
| 4
| 0x00000000
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition type to 0x3194. The partition type for data partitions is 0, so typically this location always has 0.
|-
| 0x80003198
| 4
| data partition offset
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition offset to 0x3198.
|-
| 0x8000319C
| 1
| 0x80
| Set by the apploader to 0x80 for single-layer discs and 0x81 for dual-layer discs (determined by whether 0x7ed40000 is the value at offset 0x30 in the partition's bi2.bin; it seems that that value is 0 for single-layer discs). Early titles' apploaders do not set it at all, leaving the value as 0. This controls the out-of-bounds Error #001 read for titles that do make such a read: they try to read at 0x7ed40000 for dual-layer discs and 0x460a0000 for single-layer discs.
|- style="background-color: #fdd;"
| 0x80003400
| 0x400
|
| "BS1" boot code
|- style="background-color: #eed;"
| 0x80003F00
| 0x132c100 (~19.2MB)
|
| Standard application executable area
|- style="background-color: #fdd;"
| 0x81330000
| 0x4d0000 (~4.8MB)
|
| Loader executable area, also used by a NAND Boot Program
|}

By convention, applications should use the 0x80003F00 – 0x81330000 area for executable code and data loaded as part of their ELF/DOL, while loaders should use from 0x81330000 onwards. Applications can use the loader area and MEM2 as data work space once they are running, but they should restrict the sections contained in the DOL or ELF to the executable area only, since MEM2 is reserved as work area for the loader at that time. To preserve "return to loader" functionality, applications should never use the 0x80001800-0x80003000 area.

Memory Map

2026-04-26T21:10:38Z

Shibboleet: add TGC offset for apploader

{| class="wikitable"
|-
! Start Address
! End Address
! Physical Address
! Physical End Address
! Size
! Description
|-
| 0x80000000
| 0x817FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Cached)
|-
| 0xC0000000
| 0xC17FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Uncached)
|-
| 0x90000000
| 0x93FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Cached)
|-
| 0xD0000000
| 0xD3FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Uncached)
|-
| 0xCD000000
| 0xCD008000
| 0x0D000000
| 0x0D008000
| 32 KB
| |Hollywood Registers (shared with Starlet)
|-
| 0xCC000000
| 0xCC008003
| 0x0C000000
| 0x0C008003
| 32 KB
| Broadway hardware registers
|-
| 0xC8000000
| 0xC8300000
| 0x08000000
| 0x08300000
| 3MB
| GX Embedded FrameBuffer (EFB)
|-
| Not Mapped
| Not Mapped
| 0xFFF00100
| 0xFFF0013F
| 64 bytes
| EXI boot code mirror
|}

== Broadway / IOS Global Memory Locations ==
{| class="wikitable"
|-
! Address
! Size
! (Typical) Value
! Description
|-
| 0x80000000
| 4
| 0x52535045
| Game Code 'RSPE' (Wii Sports)
|-
| 0x80000004
| 2
| 0x3031 (01)
| Maker code
|-
| 0x80000006
| 1
| 0
| Disc Number (multidisc games)
|-
| 0x80000007
| 1
| ?
| Disc Version
|-
| 0x80000008
| 1
| ?
| Disc Streaming flag
|-
| 0x80000009
| 1
| ?
| Disc Streaming buffer size
|-
| 0x80000018
| 4
| 0x5D1C9EA3
| Disc layout magic (Wii)
|-
| 0x8000001C
| 4
| 0xC2339F3D
| Disc layout magic (GC)
|-
| 0x80000020
| 4
| 0x0D15EA5E
| Nintendo Standard Boot Code.
|-
| 0x80000024
| 4
| 0x00000001
| Version (set by apploader)
|-
| 0x80000028
| 4
| 0x01800000
| Memory Size (Physical) 24MB
|-
| 0x8000002C
| 4
| 0x00000023
| Production Board Model
|-
| 0x80000030
| 4
| 0x00000000
| Arena Low
|-
| 0x80000034
| 4
| 0x817FEC60
| Arena High
|-
| 0x80000038
| 4
| 0x817FEC60
| Start of FST (varies in all games)
|-
| 0x8000003C
| 4
| 0x00001394
| Maximum FST Size (varies in all games)
|-
| 0x80000040
| 4
| ?
| Beginning of the DB global struct
|-
| 0x80000044
| 4
| ?
| DB marked exception mask
|-
| 0x80000048
| 4
| 0x81340000
| DB exception destination
|-
| 0x8000004C
| 4
| ?
| DB return address
|-
| 0x80000060
| 0x24
| OSDBIntegrator [http://hitmen.c02.at/files/yagcd/yagcd/chap4.html#sec4.2.1.3 Debugger Hook]
| Hook to be jumped to by debugged exceptions, but is disabled in production software. If nothing is written to it, SDK titles will write the 0x20 bytes of instructions here.
|-
| 0x800000C0
| 4
| ?
| Current OSContext instance (real mode)
|-
| 0x800000C4
| 4
| 0xffffff00
| User interrupt mask
|-
| 0x800000C8
| 4
| 0
| Revolution OS interrupt mask
|-
| 0x800000CC
| 4
| 0
| Value indicating the current video mode. 0 = NTSC, 1 = PAL, 2 = MPAL
|-
| 0x800000D4
| 4
| ?
| Current OSContext instance (translated mode)
|-
| 0x800000D8
| 4
| 0
| OSContext to save FPRs to (NULL if floating point mode hasn't been used since the last interrupt)
|-
| 0x800000DC
| 4
| ?
| Pointer to the earliest created OSThread
|-
| 0x800000E0
| 4
| ?
| Pointer to the most recently created OSThread
|-
| 0x800000E4
| 4
| ?
| Pointer to the current OSThread
|-
| 0x800000EC
| 4
| 0x81800000
| Dev Debugger Monitor Address (If present)
|-
| 0x800000F0
| 4
| 0x01800000
| Simulated Memory Size
|-
| 0x800000F4
| 4
| 0x817FDF80
| Pointer to data read from partition's bi2.bin, set by apploader, or the emulated bi2.bin created by the NAND Boot Program
|-
| 0x800000F8
| 4
| 0x0E7BE2C0
| Console Bus Speed
|-
| 0x800000FC
| 4
| 0x2B73A840
| Console CPU Speed
|-
| 0x80000100
| 0x1700
|
| Exception handlers (0x100 bytes reserved for each handler)
|- style="background-color: #fdd;"
| 0x80001800
| 0x1800
|
| Unused exception handler area, the SDK does not use or clear it. Custom code uses this memory region for the loader.
|-
| 0x80003000
| 0x3c
| ?
| Exception vector area
|-
| 0x80003040
| 4
| ?
| __OSInterrupt table.
|-
| 0x800030C0
| 8
| ?
| EXI Probe start times, for both channels 0 and 1.
|-
| 0x800030C8
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the first loaded REL file.
|-
| 0x800030CC
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the last loaded REL file.
|-
| 0x800030D0
| 4
| 0
| Pointer to a REL module name table, or 0. Added to the name offset in each REL file.
|-
| 0x800030D8
| 8
| 0x005498F053407000
| System time, measured as time since January 1st 2000 in units of 1/40500000th of a second.
|-
| 0x800030E4
| 2
| ?
| __OSPADButton. Apploader puts button state of GCN port 4 at game start here for Gamecube NR disc support
|-
| 0x800030E6
| 2
| ?
| DVD Device Code Address
|-
| 0x800030E8
| 4
| ?
| Debug-related info
|-
| 0x800030F0
| 4
| 0x00000000
| DOL Execute Parameters
|-
| 0x800030F4
| 4
| 0x00000000
| Current TGC Offset in the Apploader.
|-
| 0x80003100
| 4
| ?
| Physical MEM1 size
|-
| 0x80003104
| 4
| ?
| Simulated MEM1 size
|-
| 0x8000310C
| 4
| ?
| MEM1 Arena Start (start of usable memory by the game)
|-
| 0x80003110
| 4
| ?
| MEM1 Arena End (end of usable memory by the game)
|-
| 0x80003118
| 4
| 0x04000000
| Physical MEM2 size. (0x3118-0x314C are set by IOS upon reload.)
|-
| 0x8000311C
| 4
| 0x04000000
| Simulated MEM2 size.
|-
| 0x80003120
| 4
| 0x93400000
| End of MEM2 addressable to PPC.
|-
| 0x80003124
| 4
| 0x90000800
| Usable MEM2 Start (start of usable memory by the game)
|-
| 0x80003128
| 4
| 0x933E0000
| Usable MEM2 End (end of usable memory by the game)
|-
| 0x80003130
| 4
| 0x933E0000
| IOS IPC Buffer Start
|-
| 0x80003134
| 4
| 0x93400000
| IOS IPC Buffer End
|-
| 0x80003138
| 4
| 0x00000011
| Hollywood Version
|-
| 0x80003140
| 4
| 0x00090204
| IOS version (090204 = IOS9, v2.4)
|-
| 0x80003144
| 4
| 0x00062507
| IOS Build Date (62507 = 06/25/07 = June 25, 2007)
|-
| 0x80003148
| 4
| 0x93600000
| IOS Reserved Heap Start
|-
| 0x8000314C
| 4
| 0x93620000
| IOS Reserved Heap End
|-
| 0x80003158
| 4
| 0x0000FF16
| GDDR Vendor Code
|-
| 0x8000315C
| 1
| 0x80
| During the boot process, u32 0x315c is first set to 0xdeadbeef by IOS in the boot_ppc syscall. The value is set to 0x80 by the NAND Boot Program to indicate that it was loaded by the boot program (and probably 0x81 by apploaders)
|-
| 0x8000315D
| 1
| 0?
| "Enable legacy DI" mode? 0x81 = false, anything else means true (though typically set to 0x80). Required to be set when loading Gamecube apploader.
|-
| 0x8000315E
| 2
| 0x0113
| "Devkit boot program version", written to by the system menu. The value carries over to disc games. 0x0113 appears to mean v1.13.
|-
| 0x80003160
| 4
| 0x00000000
| Init semaphore (1-2 main() waits for this to clear)
|-
| 0x80003164
| 4
| 0x00000000
| GC (MIOS) mode flag, set to 1 by boot2 when MIOS triggers a shutdown; the System Menu reads this and turns off the console if it is set to 1 and :/title/00000001/00000002/data/state.dat|state.dat is set appropriately.
|-
| 0x80003180
| 4
| 0x52535045
| Game ID 'RSPE' Wii Sports ID. If these 4 bytes don't match the ID at 80000000, WC24 mode in games is disabled.
|-
| 0x80003184
| 1
| 0x80
| Application type. 0x80 for disc games, 0x81 for channels.
|-
| 0x80003186
| 1
| 0x00
| Application type 2. Appears to be set to the when a game loads a channel (e.g. Mario Kart Wii loading the region select menu will result in this being 0x80 from the disc and the main application type being 0x81, or the Wii Fit channel transitioning to the Wii Fit disc will result in this being 0x81 and the main type being 0x80).
|-
| 0x80003188
| 4
| 0x00351011
| Minimum IOS version (2 bytes for the major version, 2 bytes for the title version)
|-
| 0x8000318C
| 4
| 0x00000000
| Title Booted from NAND (Launch Code)
|-
| 0x80003190
| 4
| 0x00000000
| Title Booted from NAND (Return Code)
|-
| 0x80003194
| 4
| 0x00000000
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition type to 0x3194. The partition type for data partitions is 0, so typically this location always has 0.
|-
| 0x80003198
| 4
| data partition offset
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition offset to 0x3198.
|-
| 0x8000319C
| 1
| 0x80
| Set by the apploader to 0x80 for single-layer discs and 0x81 for dual-layer discs (determined by whether 0x7ed40000 is the value at offset 0x30 in the partition's bi2.bin; it seems that that value is 0 for single-layer discs). Early titles' apploaders do not set it at all, leaving the value as 0. This controls the out-of-bounds Error #001 read for titles that do make such a read: they try to read at 0x7ed40000 for dual-layer discs and 0x460a0000 for single-layer discs.
|- style="background-color: #fdd;"
| 0x80003400
| 0x400
|
| "BS1" boot code
|- style="background-color: #eed;"
| 0x80003F00
| 0x132c100 (~19.2MB)
|
| Standard application executable area
|- style="background-color: #fdd;"
| 0x81330000
| 0x4d0000 (~4.8MB)
|
| Loader executable area, also used by a NAND Boot Program
|}

By convention, applications should use the 0x80003F00 – 0x81330000 area for executable code and data loaded as part of their ELF/DOL, while loaders should use from 0x81330000 onwards. Applications can use the loader area and MEM2 as data work space once they are running, but they should restrict the sections contained in the DOL or ELF to the executable area only, since MEM2 is reserved as work area for the loader at that time. To preserve "return to loader" functionality, applications should never use the 0x80001800-0x80003000 area.

Memory Map

2026-04-26T21:09:14Z

Shibboleet: Created page with " {| class="wikitable" |- ! Start Address ! End Address ! Physical Address ! Physical End Address ! Size ! Description |- | 0x80000000 | 0x817FFFFF | 0x00000000 | 0x017FFFFF | 24 MB | MEM1 Memory (Cached) |- | 0xC0000000 | 0xC17FFFFF | 0x00000000 | 0x017FFFFF | 24 MB | MEM1 Memory (Uncached) |- | 0x90000000 | 0x93FFFFFF | 0x10000000 | 0x13FFFFFF | 64 MB | MEM2 Memory (Cached) |- | 0xD0000000 | 0xD3FFFFFF | 0x10000000 | 0x13FFFFFF | 64 MB | MEM2 Memory (Uncached) |- | 0xCD..."

{| class="wikitable"
|-
! Start Address
! End Address
! Physical Address
! Physical End Address
! Size
! Description
|-
| 0x80000000
| 0x817FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Cached)
|-
| 0xC0000000
| 0xC17FFFFF
| 0x00000000
| 0x017FFFFF
| 24 MB
| MEM1 Memory (Uncached)
|-
| 0x90000000
| 0x93FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Cached)
|-
| 0xD0000000
| 0xD3FFFFFF
| 0x10000000
| 0x13FFFFFF
| 64 MB
| MEM2 Memory (Uncached)
|-
| 0xCD000000
| 0xCD008000
| 0x0D000000
| 0x0D008000
| 32 KB
| |Hollywood Registers (shared with Starlet)
|-
| 0xCC000000
| 0xCC008003
| 0x0C000000
| 0x0C008003
| 32 KB
| Broadway hardware registers
|-
| 0xC8000000
| 0xC8300000
| 0x08000000
| 0x08300000
| 3MB
| GX Embedded FrameBuffer (EFB)
|-
| Not Mapped
| Not Mapped
| 0xFFF00100
| 0xFFF0013F
| 64 bytes
| EXI boot code mirror
|}

== Broadway / IOS Global Memory Locations ==
{| class="wikitable"
|-
! Address
! Size
! (Typical) Value
! Description
|-
| 0x80000000
| 4
| 0x52535045
| Game Code 'RSPE' (Wii Sports)
|-
| 0x80000004
| 2
| 0x3031 (01)
| Maker code
|-
| 0x80000006
| 1
| 0
| Disc Number (multidisc games)
|-
| 0x80000007
| 1
| ?
| Disc Version
|-
| 0x80000008
| 1
| ?
| Disc Streaming flag
|-
| 0x80000009
| 1
| ?
| Disc Streaming buffer size
|-
| 0x80000018
| 4
| 0x5D1C9EA3
| Disc layout magic (Wii)
|-
| 0x8000001C
| 4
| 0xC2339F3D
| Disc layout magic (GC)
|-
| 0x80000020
| 4
| 0x0D15EA5E
| Nintendo Standard Boot Code.
|-
| 0x80000024
| 4
| 0x00000001
| Version (set by apploader)
|-
| 0x80000028
| 4
| 0x01800000
| Memory Size (Physical) 24MB
|-
| 0x8000002C
| 4
| 0x00000023
| Production Board Model
|-
| 0x80000030
| 4
| 0x00000000
| Arena Low
|-
| 0x80000034
| 4
| 0x817FEC60
| Arena High
|-
| 0x80000038
| 4
| 0x817FEC60
| Start of FST (varies in all games)
|-
| 0x8000003C
| 4
| 0x00001394
| Maximum FST Size (varies in all games)
|-
| 0x80000040
| 4
| ?
| Beginning of the DB global struct
|-
| 0x80000044
| 4
| ?
| DB marked exception mask
|-
| 0x80000048
| 4
| 0x81340000
| DB exception destination
|-
| 0x8000004C
| 4
| ?
| DB return address
|-
| 0x80000060
| 0x24
| OSDBIntegrator [http://hitmen.c02.at/files/yagcd/yagcd/chap4.html#sec4.2.1.3 Debugger Hook]
| Hook to be jumped to by debugged exceptions, but is disabled in production software. If nothing is written to it, SDK titles will write the 0x20 bytes of instructions here.
|-
| 0x800000C0
| 4
| ?
| Current OSContext instance (real mode)
|-
| 0x800000C4
| 4
| 0xffffff00
| User interrupt mask
|-
| 0x800000C8
| 4
| 0
| Revolution OS interrupt mask
|-
| 0x800000CC
| 4
| 0
| Value indicating the current video mode. 0 = NTSC, 1 = PAL, 2 = MPAL
|-
| 0x800000D4
| 4
| ?
| Current OSContext instance (translated mode)
|-
| 0x800000D8
| 4
| 0
| OSContext to save FPRs to (NULL if floating point mode hasn't been used since the last interrupt)
|-
| 0x800000DC
| 4
| ?
| Pointer to the earliest created OSThread
|-
| 0x800000E0
| 4
| ?
| Pointer to the most recently created OSThread
|-
| 0x800000E4
| 4
| ?
| Pointer to the current OSThread
|-
| 0x800000EC
| 4
| 0x81800000
| Dev Debugger Monitor Address (If present)
|-
| 0x800000F0
| 4
| 0x01800000
| Simulated Memory Size
|-
| 0x800000F4
| 4
| 0x817FDF80
| Pointer to data read from partition's bi2.bin, set by apploader, or the emulated bi2.bin created by the NAND Boot Program
|-
| 0x800000F8
| 4
| 0x0E7BE2C0
| Console Bus Speed
|-
| 0x800000FC
| 4
| 0x2B73A840
| Console CPU Speed
|-
| 0x80000100
| 0x1700
|
| Exception handlers (0x100 bytes reserved for each handler)
|- style="background-color: #fdd;"
| 0x80001800
| 0x1800
|
| Unused exception handler area, the SDK does not use or clear it. Custom code uses this memory region for the loader.
|-
| 0x80003000
| 0x3c
| ?
| Exception vector area
|-
| 0x80003040
| 4
| ?
| __OSInterrupt table.
|-
| 0x800030C0
| 8
| ?
| EXI Probe start times, for both channels 0 and 1.
|-
| 0x800030C8
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the first loaded REL file.
|-
| 0x800030CC
| 4
| ?
| Related to Nintendo's dynamic linking system (REL). Pointer to the last loaded REL file.
|-
| 0x800030D0
| 4
| 0
| Pointer to a REL module name table, or 0. Added to the name offset in each REL file.
|-
| 0x800030D8
| 8
| 0x005498F053407000
| System time, measured as time since January 1st 2000 in units of 1/40500000th of a second.
|-
| 0x800030E4
| 2
| ?
| __OSPADButton. Apploader puts button state of GCN port 4 at game start here for Gamecube NR disc support
|-
| 0x800030E6
| 2
| ?
| DVD Device Code Address
|-
| 0x800030E8
| 4
| ?
| Debug-related info
|-
| 0x800030F0
| 4
| 0x00000000
| DOL Execute Parameters
|-
| 0x80003100
| 4
| ?
| Physical MEM1 size
|-
| 0x80003104
| 4
| ?
| Simulated MEM1 size
|-
| 0x8000310C
| 4
| ?
| MEM1 Arena Start (start of usable memory by the game)
|-
| 0x80003110
| 4
| ?
| MEM1 Arena End (end of usable memory by the game)
|-
| 0x80003118
| 4
| 0x04000000
| Physical MEM2 size. (0x3118-0x314C are set by IOS upon reload.)
|-
| 0x8000311C
| 4
| 0x04000000
| Simulated MEM2 size.
|-
| 0x80003120
| 4
| 0x93400000
| End of MEM2 addressable to PPC.
|-
| 0x80003124
| 4
| 0x90000800
| Usable MEM2 Start (start of usable memory by the game)
|-
| 0x80003128
| 4
| 0x933E0000
| Usable MEM2 End (end of usable memory by the game)
|-
| 0x80003130
| 4
| 0x933E0000
| IOS IPC Buffer Start
|-
| 0x80003134
| 4
| 0x93400000
| IOS IPC Buffer End
|-
| 0x80003138
| 4
| 0x00000011
| Hollywood Version
|-
| 0x80003140
| 4
| 0x00090204
| IOS version (090204 = IOS9, v2.4)
|-
| 0x80003144
| 4
| 0x00062507
| IOS Build Date (62507 = 06/25/07 = June 25, 2007)
|-
| 0x80003148
| 4
| 0x93600000
| IOS Reserved Heap Start
|-
| 0x8000314C
| 4
| 0x93620000
| IOS Reserved Heap End
|-
| 0x80003158
| 4
| 0x0000FF16
| GDDR Vendor Code
|-
| 0x8000315C
| 1
| 0x80
| During the boot process, u32 0x315c is first set to 0xdeadbeef by IOS in the boot_ppc syscall. The value is set to 0x80 by the NAND Boot Program to indicate that it was loaded by the boot program (and probably 0x81 by apploaders)
|-
| 0x8000315D
| 1
| 0?
| "Enable legacy DI" mode? 0x81 = false, anything else means true (though typically set to 0x80). Required to be set when loading Gamecube apploader.
|-
| 0x8000315E
| 2
| 0x0113
| "Devkit boot program version", written to by the system menu. The value carries over to disc games. 0x0113 appears to mean v1.13.
|-
| 0x80003160
| 4
| 0x00000000
| Init semaphore (1-2 main() waits for this to clear)
|-
| 0x80003164
| 4
| 0x00000000
| GC (MIOS) mode flag, set to 1 by boot2 when MIOS triggers a shutdown; the System Menu reads this and turns off the console if it is set to 1 and :/title/00000001/00000002/data/state.dat|state.dat is set appropriately.
|-
| 0x80003180
| 4
| 0x52535045
| Game ID 'RSPE' Wii Sports ID. If these 4 bytes don't match the ID at 80000000, WC24 mode in games is disabled.
|-
| 0x80003184
| 1
| 0x80
| Application type. 0x80 for disc games, 0x81 for channels.
|-
| 0x80003186
| 1
| 0x00
| Application type 2. Appears to be set to the when a game loads a channel (e.g. Mario Kart Wii loading the region select menu will result in this being 0x80 from the disc and the main application type being 0x81, or the Wii Fit channel transitioning to the Wii Fit disc will result in this being 0x81 and the main type being 0x80).
|-
| 0x80003188
| 4
| 0x00351011
| Minimum IOS version (2 bytes for the major version, 2 bytes for the title version)
|-
| 0x8000318C
| 4
| 0x00000000
| Title Booted from NAND (Launch Code)
|-
| 0x80003190
| 4
| 0x00000000
| Title Booted from NAND (Return Code)
|-
| 0x80003194
| 4
| 0x00000000
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition type to 0x3194. The partition type for data partitions is 0, so typically this location always has 0.
|-
| 0x80003198
| 4
| data partition offset
| While reading a disc, the system menu reads the first partition table (0x20 bytes from 0x00040020) and stores a pointer to the data partition entry. When launching the disc game, it copies the partition offset to 0x3198.
|-
| 0x8000319C
| 1
| 0x80
| Set by the apploader to 0x80 for single-layer discs and 0x81 for dual-layer discs (determined by whether 0x7ed40000 is the value at offset 0x30 in the partition's bi2.bin; it seems that that value is 0 for single-layer discs). Early titles' apploaders do not set it at all, leaving the value as 0. This controls the out-of-bounds Error #001 read for titles that do make such a read: they try to read at 0x7ed40000 for dual-layer discs and 0x460a0000 for single-layer discs.
|- style="background-color: #fdd;"
| 0x80003400
| 0x400
|
| "BS1" boot code
|- style="background-color: #eed;"
| 0x80003F00
| 0x132c100 (~19.2MB)
|
| Standard application executable area
|- style="background-color: #fdd;"
| 0x81330000
| 0x4d0000 (~4.8MB)
|
| Loader executable area, also used by a NAND Boot Program
|}

By convention, applications should use the 0x80003F00 – 0x81330000 area for executable code and data loaded as part of their ELF/DOL, while loaders should use from 0x81330000 onwards. Applications can use the loader area and MEM2 as data work space once they are running, but they should restrict the sections contained in the DOL or ELF to the executable area only, since MEM2 is reserved as work area for the loader at that time. To preserve "return to loader" functionality, applications should never use the 0x80001800-0x80003000 area.

Decompiling

2025-05-20T18:29:17Z

Shibboleet: /* Getting Set Up */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01(1).i64 SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Splitting ==
''Splitting'' refers to "splitting" up each object file with its respective segments to properly build a matching object. This can be code / data, or just data.

A simple split looks like this:
<pre>
Game/NameObj/NameObj.cpp:
.text start:0x802616B4 end:0x802618B4
.data start:0x805A7758 end:0x805A7780
.sbss start:0x806B5BE0 end:0x806B5BE8
</pre>

Each segment needs a '''start''' and an '''end''' address, and the '''end''' address always needs to be larger than the '''start''' address. You can use IDA (or Ghidra) to see what segment a specific set of code / data belongs to. For this specific split:
* '''.text''' begins at '''0x802616B4''' and ends at '''0x802618B4'''.
* '''.data''' begins at '''0x805A7758''' and ends at '''0x805A7780'''.
* '''.sbss''' begins at '''0x806B5BE0''' and ends at '''0x806B5BE8'''.

You can change these splits by changing '''config/RMGKXX/splits.txt''' where '''XX''' is the version of the Korean version you are using. It is worth noting that any data addresses (ie .data, .bss, .sdata) need to be rounded to the nearest 8th byte, as they are 8-byte aligned.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Actor Decompiling ==
An ''actor'' is how the game refers to something that is present in a ''scene'' (ie a Goomba or a Coin). The approach to decompiling an actor is rather repetitive, but can change based on the actor itself. However, most of them follow a straightforward structure. They contain a constructor that takes in a '''const char *''' pointer (which is the name of the actor) and passes that to the parent class, which can range from ''LiveActor'' to ''MapObjActor''.

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-20T18:29:00Z

Shibboleet: /* Getting Set Up */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.i64 SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Splitting ==
''Splitting'' refers to "splitting" up each object file with its respective segments to properly build a matching object. This can be code / data, or just data.

A simple split looks like this:
<pre>
Game/NameObj/NameObj.cpp:
.text start:0x802616B4 end:0x802618B4
.data start:0x805A7758 end:0x805A7780
.sbss start:0x806B5BE0 end:0x806B5BE8
</pre>

Each segment needs a '''start''' and an '''end''' address, and the '''end''' address always needs to be larger than the '''start''' address. You can use IDA (or Ghidra) to see what segment a specific set of code / data belongs to. For this specific split:
* '''.text''' begins at '''0x802616B4''' and ends at '''0x802618B4'''.
* '''.data''' begins at '''0x805A7758''' and ends at '''0x805A7780'''.
* '''.sbss''' begins at '''0x806B5BE0''' and ends at '''0x806B5BE8'''.

You can change these splits by changing '''config/RMGKXX/splits.txt''' where '''XX''' is the version of the Korean version you are using. It is worth noting that any data addresses (ie .data, .bss, .sdata) need to be rounded to the nearest 8th byte, as they are 8-byte aligned.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Actor Decompiling ==
An ''actor'' is how the game refers to something that is present in a ''scene'' (ie a Goomba or a Coin). The approach to decompiling an actor is rather repetitive, but can change based on the actor itself. However, most of them follow a straightforward structure. They contain a constructor that takes in a '''const char *''' pointer (which is the name of the actor) and passes that to the parent class, which can range from ''LiveActor'' to ''MapObjActor''.

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-20T17:56:44Z

Shibboleet:

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Splitting ==
''Splitting'' refers to "splitting" up each object file with its respective segments to properly build a matching object. This can be code / data, or just data.

A simple split looks like this:
<pre>
Game/NameObj/NameObj.cpp:
.text start:0x802616B4 end:0x802618B4
.data start:0x805A7758 end:0x805A7780
.sbss start:0x806B5BE0 end:0x806B5BE8
</pre>

Each segment needs a '''start''' and an '''end''' address, and the '''end''' address always needs to be larger than the '''start''' address. You can use IDA (or Ghidra) to see what segment a specific set of code / data belongs to. For this specific split:
* '''.text''' begins at '''0x802616B4''' and ends at '''0x802618B4'''.
* '''.data''' begins at '''0x805A7758''' and ends at '''0x805A7780'''.
* '''.sbss''' begins at '''0x806B5BE0''' and ends at '''0x806B5BE8'''.

You can change these splits by changing '''config/RMGKXX/splits.txt''' where '''XX''' is the version of the Korean version you are using. It is worth noting that any data addresses (ie .data, .bss, .sdata) need to be rounded to the nearest 8th byte, as they are 8-byte aligned.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Actor Decompiling ==
An ''actor'' is how the game refers to something that is present in a ''scene'' (ie a Goomba or a Coin). The approach to decompiling an actor is rather repetitive, but can change based on the actor itself. However, most of them follow a straightforward structure. They contain a constructor that takes in a '''const char *''' pointer (which is the name of the actor) and passes that to the parent class, which can range from ''LiveActor'' to ''MapObjActor''.

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-06T17:19:26Z

Shibboleet: /* Splitting */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Splitting ==
''Splitting'' refers to "splitting" up each object file with its respective segments to properly build a matching object. This can be code / data, or just data.

A simple split looks like this:
<pre>
Game/NameObj/NameObj.cpp:
.text start:0x802616B4 end:0x802618B4
.data start:0x805A7758 end:0x805A7780
.sbss start:0x806B5BE0 end:0x806B5BE8
</pre>

Each segment needs a '''start''' and an '''end''' address, and the '''end''' address always needs to be larger than the '''start''' address. You can use IDA (or Ghidra) to see what segment a specific set of code / data belongs to. For this specific split:
* '''.text''' begins at '''0x802616B4''' and ends at '''0x802618B4'''.
* '''.data''' begins at '''0x805A7758''' and ends at '''0x805A7780'''.
* '''.sbss''' begins at '''0x806B5BE0''' and ends at '''0x806B5BE8'''.

You can change these splits by changing '''config/RMGKXX/splits.txt''' where '''XX''' is the version of the Korean version you are using. It is worth noting that any data addresses (ie .data, .bss, .sdata) need to be rounded to the nearest 8th byte, as they are 8-byte aligned.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-06T17:19:01Z

Shibboleet:

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Splitting ==
''Splitting'' refers to "splitting" up each object file with its respective segments to properly build a matching object. This can be code / data, or just data.

A simple split looks like this:
<pre>
Game/NameObj/NameObj.cpp:
.text start:0x802616B4 end:0x802618B4
.data start:0x805A7758 end:0x805A7780
.sbss start:0x806B5BE0 end:0x806B5BE8
</pre>

Each segment needs a '''start''' and an '''end address, and the '''end''' address always needs to be larger than the '''start''' address. You can use IDA (or Ghidra) to see what segment a specific set of code / data belongs to. For this specific split:
* '''.text''' begins at '''0x802616B4''' and ends at '''0x802618B4'''.
* '''.data''' begins at '''0x805A7758''' and ends at '''0x805A7780'''.
* '''.sbss''' begins at '''0x806B5BE0''' and ends at '''0x806B5BE8'''.

You can change these splits by changing '''config/RMGKXX/splits.txt''' where '''XX''' is the version of the Korean version you are using. It is worth noting that any data addresses (ie .data, .bss, .sdata) need to be rounded to the nearest 8th byte, as they are 8-byte aligned.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-06T17:10:51Z

Shibboleet: /* Getting Set Up */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.
* [https://github.com/ninja-build/ninja/releases Ninja]

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

Decompiling

2025-05-06T17:09:52Z

Shibboleet:

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Code Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into '''orig/RMGK01/main.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command ''''ninja'''. This will download the decompilation toolkit (dtk) and "split" the binary, then compile the code.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| assets || Just assets for the README.
|-
| build || The folder that gets created when '''ninja''' is ran. Contains the compiled object files and the compilers.
|-
| config || Contains the configurations for each SMG1 version for decompilation and splitting.
|-
| docs || Documents relating to using '''dtk'''.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| md || Documentation for completed functions.
|-
| orig || Contains the DOLs for each game version for splitting and matching.
|-
| src || Contains all of the source files for '''Super Mario Galaxy''' and its libraries.
|-
| tools || Misc tools that dtk uses.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

== Operator Overloads ==
There are specific ways that CodeWarrior mangles symbols when overloading operators for classes.
{| class="wikitable"
! Operator !! Mangled Symbol
|-
| "+" || "pl"
|-
| "-" || "mi"
|-
| "*" || "ml"
|-
| "/" || "dv"
|-
| "%" || "md"
|-
| "^" || "er"
|-
| "/=" || "adv"
|-
| "&" || "ad"
|-
| "|" || "or"
|-
| "~" || "co"
|-
| "!" || "nt"
|-
| "=" || "as"
|-
| "<" || "lt"
|-
| ">" || "gt"
|-
| "+=" || "apl"
|-
| "-=" || "ami"
|-
| "*=" || "amu"
|-
| "%=" || "amd"
|-
| "^=" || "aer"
|-
| "&=" || "aad"
|-
| "|=" || "aor"
|-
| "<<" || "ls"
|-
| ">>" || "rs"
|-
| ">>=" || "ars"
|-
| "<<=" || "als"
|-
| "==" || "eq"
|-
| "!=" || "ne"
|-
| "<=" || "le"
|-
| ">=" || "ge"
|-
| "&&" || "aa"
|-
| "||" || "oo"
|-
| "++" || "pp"
|-
| "--" || "mm"
|-
| "()" || "cl"
|-
| "[]" || "vc"
|-
| "->" || "rf"
|-
| "," || "cm"
|-
| "->*" || "rm"
|}

THP (File Format)

2025-04-22T18:52:32Z

Shibboleet: clarify what THP stands for

[[Category:File formats]]
{{SDK Reference}}
'''THP''' stands for '''T'''ecmo '''H'''ome '''P'''roduction. It's mainly used for prerendered cutscenes and other prerendered videos. This format was also used on the Nintendo GameCube.

= Format Specifications =
Below you'll find helpful tables on how the file is structured
== Header ==
Each THP starts with a ''header''
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || "THP0" in ASCII
|-
| 0x04 || UInt32 || ''Version Number''. SMG uses 0x1048832
|-
| 0x08 || UInt32 || The Maximum Frame data size
|-
| 0x0C || UInt32 || Max no. of Audio Samples. SMG uses 0x570556416
|-
| 0x10 || Float || Frame Rate. Defaults to 29.97 in ''THPConv.exe''. SMG uses 59.97 (the max value)
|-
| 0x14 || UInt32 || Total number of frames
|-
| 0x18 || UInt32 || The length of the first frame
|-
| 0x1C || UInt32 || The length of ALL frames
|-
| 0x20 || UInt32 || Offset to components
|-
| 0x24 || UInt32 || Offset to FrameOffsetData
|-
| 0x28 || UInt32 || First frame offset
|-
| 0x2C || UInt32 || Last frame offset
|-
|}
== Frame Comp Info ==
This section is for the Component structure
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Number of components in this frame. Max is 16
|-
| 0x04 || UInt8[16] || Component types (0 = video, 1 = audio, -1 = none)
|-
|}
== Video ==
This section contains the video data.
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Width. SMG uses 640
|-
| 0x04 || UInt32 || Height. SMG uses 368
|-
| 0x08 || UInt32 || Video format (Only used in certain versions)
|-
|}

== Audio ==
This sections contains the audio data.
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Number of Audio Channels (Min is 0, Max is 2)
|-
| 0x04 || UInt32 || Frequency
|-
| 0x08 || UInt32 || Number of samples played
|-
| 0x0C || UInt32 || Number of tracks (Only used in certain versions)
|-
|}
== Frame ==
A frame starts with a frame ''header''
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Total size of the next frame
|-
| 0x04 || UInt32 || Total size of previous frame
|-
| 0x08 || UInt32 || Total size of the current frame
|-
| 0x0C || UInt32 || Audio size (Only if there is audio in the current frame)
|-
| 0x0C or 0x10 || colspan="2" style="text-align:center; background: #d0d0d0;" | Image Data
|-
|}
=== Video ===
Video data
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Int8['''I'''] || Image Data
|-
| '''I''' || colspan="2" style="text-align:center; background: #d0d0d0;" | End of Image Data
|-
|}
=== Audio ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Channel size
|-
| 0x04 || UInt32 || Number of samples
|-
| 0x08 || Int16[16] || Table 1
|-
| 0x28 || Int16[16] || Table 2
|-
| 0x48 || Int16 || Channel 1 previous 1
|-
| 0x4A || Int16 || Channel 1 previous 2
|-
| 0x4C || Int16 || Channel 2 previous 1
|-
| 0x4E || Int16 || Channel 2 previous 2
|-
| 0x50 || colspan="2" style="text-align:center; background: #d0d0d0;" | Audio Data
|-
|}
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Int8['''M'''] || Audio Data
|-
| '''M''' || colspan="2" style="text-align:center; background: #d0d0d0;" | End of Audio Data
|-
|}
= Tools =
The following tools can handle THP files:
* [https://github.com/soopercool101/BrawlCrate BrawlCrate] (Can only view the files)
* [https://www.ffmpeg.org/ ffmpeg] (Can convert THP videos to other video formats)
* [https://sites.google.com/site/wiiflowiki4/trailers/thp-video-convertor Wiiflow THP Video Converter] (Creates thp videos. Only supports 30 fps)
* [https://github.com/Lord-Giganticus/THP-Conveter THP-Converter] (Can convert to and from THP files using other programs)
* [[THPConv.exe]] (Nintendo's internal program to make thp videos, used by other programs)

Paired Singles

2025-02-16T23:16:21Z

Shibboleet: Created page with "''Paired Singles'' are a part of the Broadway / Gekko processor that allows for two single-precision floating point values to be stored in a single register. This allows for faster vector and matrix math. ''Paired Singles'' are handwritten assembly code; they cannot be generated by the compiler '''unless''' it is for pushing / popping the stack frame in a functions prologue or epilogue. The ''Super Mario Galaxy'' games do not use very many different paired single instruc..."

''Paired Singles'' are a part of the Broadway / Gekko processor that allows for two single-precision floating point values to be stored in a single register. This allows for faster vector and matrix math. ''Paired Singles'' are handwritten assembly code; they cannot be generated by the compiler '''unless''' it is for pushing / popping the stack frame in a functions prologue or epilogue. The ''Super Mario Galaxy'' games do not use very many different paired single instructions, so this page only covers the ones used by the game.

== Loading And Storing ==
=== psq_l ===
Loads a paired single into the destination register '''FRD'''.
<pre>
psq_l FRD, D(RA), W, I
</pre>
{| class="wikitable"
|-
! Name !! Description
|-
| FRD|| Destination register for the paired single loaded.
|-
| D(RA)|| Memory address, where '''D''' is the offset, and '''RA''' is the source register.
|-
| W || Size of the paired single. '''0''' loads the first two floats where '''1''' only loads the third.
|-
| I || Determines the type of register to load from. Only used as '''0''' (floating point).
|}

== Math ==
=== ps_madd ===
<pre>
ps_madd FRT, FRA, FRB, FRC
</pre>

<math>
\text{FRT}_{\text{high}} = (\text{FRA}_{\text{high}} \times \text{FRB}_{\text{high}}) + \text{FRC}_{\text{high}}
</math>

<math>
\text{FRT}_{\text{low}} = (\text{FRA}_{\text{low}} \times \text{FRB}_{\text{low}}) + \text{FRC}_{\text{low}}
</math>

SMG1 to SMG2 Code Changes

2024-12-17T01:48:51Z

Shibboleet: Created page with "Between the game ''Super Mario Galaxy'' and ''Super Mario Galaxy 2'', a few changes were made under the hood to make things easier to work with in the codebase. This page will be listing those changes that the developers made. == NameObj == ''NameObj'' is the most basic form of an object in the game. It contains an executor index, the execution flags, and the name of the object. <pre> class NameObj { public: NameObj(const char *pName); virtual ~NameObj(); virtual..."

Between the game ''Super Mario Galaxy'' and ''Super Mario Galaxy 2'', a few changes were made under the hood to make things easier to work with in the codebase. This page will be listing those changes that the developers made.

== NameObj ==
''NameObj'' is the most basic form of an object in the game. It contains an executor index, the execution flags, and the name of the object.
<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* 0x4 */ const char *mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

However, ''Super Mario Galaxy 2'' changes the base object a little. It adds a ''JMapLinkInfo'' instance to the NameObj for easier linking using the new ''LinkID'' attribute introduced in the JMap. It also introduces two new virtual functions, ''NameObj::startMovement'' and ''NameObj::endMovement'' which are called before and after a movement is executed.

<pre>
class NameObj {
public:
NameObj(const char *);

virtual ~NameObj();
virtual void init(const JMapInfoIter &);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();
virtual void startMovement();
virtual void endMovement();

const char* mName; // 0x04
vu16 mFlags; // 0x08
s16 mExecutorIdx; // 0x0A
JMapLinkInfo mLinkInfo; // 0x0C
};
</pre>

== StageSwitchContainer ==
''StageSwitchContainer'' is the class that controls the switches for a specific galaxy. They are very similar in both games, with a small change (mainly for code cleanliness) made to how it works.

In ''Super Mario Galaxy'', the ''StageSwitchContainer'' class stores an array of ''StageSwitch::ContainerSwitch'' instances that contained "data" (which is the Zone ID it is contained in) and the ''ZoneSwitch'' pointer which contained the actual switch data itself.

<pre>
class StageSwitchContainer : public NameObj {
public:
struct ContainerSwitch {
s32 mData; // 0x0
ZoneSwitch* mSwitch; // 0x4
};
ContainerSwitch mSwitches[20]; // 0xC
s32 mCount; // 0xAC
ZoneSwitch* mGlobalSwitches; // 0xB0
};
</pre>

The developers probably realized that the zone ID here does not need to be stored in conjunction with the switch, it can just be stored ''inside'' of the switch instance. So, they added the Zone ID attribute into ''ZoneSwitch'' and made the array smaller, as well as making it a pointer array of ''ZoneSwitch'' instances.

<pre>
class StageSwitchContainer : public NameObj {
public:
ZoneSwitch* mZoneSwitches[0x10]; // 0x14
s32 mSwitchCount; // 0x54
ZoneSwitch* mParentZone; // 0x58
};
</pre>

Decompiling

2024-04-06T12:45:01Z

Shibboleet: Class Mapping -- inheriting

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into this folder, and rename it to '''baserom.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command '''python setup.py'''. This will verify your DOL and install all of the libraries used, and the compilers we use to compile the code.
# Run the command '''python build.py'''. This will build the entire project. If you see any warnings, do not worry about them.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| archive || The folder that gets created when '''build.py -link''' is ran. Contains an archive of the object files in each library.
|-
| build || The folder that gets created when '''build.py''' is ran. Contains the compiled object files.
|-
| csv || Contains CSV files that store the status of functions being matched.
|-
| data || Contains map files and the percentage badges for the GitHub repo.
|-
| docs || The folder that gets created when '''progress.py''' is ran. Contains all of the Markdown documentation for matching status.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| libs || Contains this folder structure but for different libraries used by the game.
|-
| scripts || Various scripts used in IDA for generating headers.
|-
| source || Contains all of the source files for ''Super Mario Galaxy'' specific code.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Inheriting Class ===
The process of mapping a class that inherits another class is mainly the same as mapping a base class, except there are things to watch out for so you don't accidentally duplicate a member variable. The first step is to look at the ''constructor'' of the class you want to map:

[[Image:TripodBossCoin_Ctor.png|frameless|700px|The constructor for ''TripodBossCoin''.]]

There are a few takeaways from this by looking at the constructor:
* The class inherits NameObj. Since ''NameObj'' is 0xC bytes long, we know that any member variables for ''TripodBossCoin'' start at '''0xC'''.
* The vtable pointer '''(this + 0x0)''' from ''NameObj'' is overridden with the vtable for ''TripodBossCoin'' implicitly.
* '''(this + 0xC)''' is a 32-bit integer initialized to 0. It is not possible to determine if it is signed or not from this store alone.
* '''(this + 0x10)''' is the same scenario as '''(this + 0xC)'''.
* There is a direct instance of ''JGeometry::TMatrix34<JGeometry::SMatrix34C<f32>'' at 0x14. (in Petari & Syati this is typedef'd as ''TMtx34f''). Since ''TMtx34f'' is 0x30 in size, the next member variable is at 0x14 + 0x30, which is '''0x44'''.
* '''(this + 0x44)''' is a signed 32-bit integer, due to '''-1''' being stored to it.

After these observations, our class looks like this:
<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

Next are the virtuals. The process is a little different from a base class. Let's take a look at the vtable for ''TripodBossCoin'':

[[Image:TripodBossCoin_Vtable.png|frameless|700px|The vtable for ''TripodBossCoin''.]]

The biggest takeaway from this screenshot is that only three virtuals are overriden by ''TripodBossCoin''. And those three functions are '''TripodBossCoin::~TripodBossCoin()''', '''TripodBossCoin::init()''' and '''TripodBossCoin::movement()'''. So we define them as such:

<pre>
class TripodBossCoin : public NameObj {
public:
TripodBossCoin(const char *);

virtual ~TripodBossCoin();
virtual void init(const JMapInfoIter &);
virtual void movement();

u32 _C;
u32 _10;
TMtx34f _14;
s32 _44;
};
</pre>

It is worth noting that the '''override''' keyword was not a part of the C++ standard at this point in time, so all overrides are implicit. After all of this is done, you simply have to repeat the process for base classes and document the member functions that are a part of the class.

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

File:TripodBossCoin Vtable.png

2024-04-06T12:32:14Z

Shibboleet:

File:TripodBossCoin Ctor.png

2024-04-06T12:32:02Z

Shibboleet:

Decompiling

2024-04-06T12:21:02Z

Shibboleet: /* Base Class */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into this folder, and rename it to '''baserom.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command '''python setup.py'''. This will verify your DOL and install all of the libraries used, and the compilers we use to compile the code.
# Run the command '''python build.py'''. This will build the entire project. If you see any warnings, do not worry about them.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| archive || The folder that gets created when '''build.py -link''' is ran. Contains an archive of the object files in each library.
|-
| build || The folder that gets created when '''build.py''' is ran. Contains the compiled object files.
|-
| csv || Contains CSV files that store the status of functions being matched.
|-
| data || Contains map files and the percentage badges for the GitHub repo.
|-
| docs || The folder that gets created when '''progress.py''' is ran. Contains all of the Markdown documentation for matching status.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| libs || Contains this folder structure but for different libraries used by the game.
|-
| scripts || Various scripts used in IDA for generating headers.
|-
| source || Contains all of the source files for ''Super Mario Galaxy'' specific code.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing members. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

Decompiling

2024-04-06T12:20:34Z

Shibboleet: /* Base Class */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into this folder, and rename it to '''baserom.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command '''python setup.py'''. This will verify your DOL and install all of the libraries used, and the compilers we use to compile the code.
# Run the command '''python build.py'''. This will build the entire project. If you see any warnings, do not worry about them.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| archive || The folder that gets created when '''build.py -link''' is ran. Contains an archive of the object files in each library.
|-
| build || The folder that gets created when '''build.py''' is ran. Contains the compiled object files.
|-
| csv || Contains CSV files that store the status of functions being matched.
|-
| data || Contains map files and the percentage badges for the GitHub repo.
|-
| docs || The folder that gets created when '''progress.py''' is ran. Contains all of the Markdown documentation for matching status.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| libs || Contains this folder structure but for different libraries used by the game.
|-
| scripts || Various scripts used in IDA for generating headers.
|-
| source || Contains all of the source files for ''Super Mario Galaxy'' specific code.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialize every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing arguments. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

Decompiling

2024-04-06T12:19:43Z

Shibboleet: /* Base Class */

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into this folder, and rename it to '''baserom.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command '''python setup.py'''. This will verify your DOL and install all of the libraries used, and the compilers we use to compile the code.
# Run the command '''python build.py'''. This will build the entire project. If you see any warnings, do not worry about them.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| archive || The folder that gets created when '''build.py -link''' is ran. Contains an archive of the object files in each library.
|-
| build || The folder that gets created when '''build.py''' is ran. Contains the compiled object files.
|-
| csv || Contains CSV files that store the status of functions being matched.
|-
| data || Contains map files and the percentage badges for the GitHub repo.
|-
| docs || The folder that gets created when '''progress.py''' is ran. Contains all of the Markdown documentation for matching status.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| libs || Contains this folder structure but for different libraries used by the game.
|-
| scripts || Various scripts used in IDA for generating headers.
|-
| source || Contains all of the source files for ''Super Mario Galaxy'' specific code.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, its type (as close as you can guess), its virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialized every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing arguments. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

Decompiling

2024-04-06T12:19:05Z

Shibboleet: class mapping

[[Category:Guides]]
[[Category:Decompiling]]
{{WIP}}

== Introduction ==
''Decompiling'' is the process of taking assembly code and turning it back into a higher level language such as C or C++. It is essentially the reverse of ''compiling''. ''Matching decompilation'' is the process of decompiling, but having the compiled code match the original assembly 1:1. While matching decompilation is harder than normal decompiling, it can become easier when you understand the patterns of the compiler used. This page aims to let new people understand how this process works, and hopefully be able to get new people into decompilation! While you do not need to be an expert at C or C++ to decompile, it is recommended that you have some experience before attempting decompilation. It is also very recommended that you have some prior knowledge of PowerPC assembly, as that is the key to understanding how a function works. [https://www.nxp.com/docs/en/reference-manual/MPC82XINSET.pdf This document] is a good way to learn or refresh knowledge of the PowerPC architecture. [https://www.warthman.com/images/IBM_PPC_Compiler_Writer%27s_Guide-cwg.pdf This document] is also good to learn some of the patterns that CodeWarrior does.

== Getting Set Up ==
To begin decompiling ''Super Mario Galaxy'', you first need to set up the environment. You will need the following tools:
* [https://gitforwindows.org/ Git (Windows)]
* Any IDE ([https://code.visualstudio.com/ Visual Studio Recommended])
* [https://www.python.org/downloads/release/python-397/ Python 3.9.7]
* IDA Pro (recommended) or Ghidra (Not recommended)
* [https://shibbo.net/smg/RMGK01_01.idb SMG1 Korean IDB (For IDA)]
* A ''Super Mario Galaxy'' Korean region DOL.

After you have acquired all of these, setting up [https://github.com/shibbo/Petari Petari] is very simple.

# With a new command prompt open, type in '''git clone https://github.com/shibbo/Petari'''. This will clone the repository into a directory called "Petari".
# In this new "Petari" folder, place the SMG1 Korean '''main.dol''' into this folder, and rename it to '''baserom.dol'''.
# Open a new command prompt in the "Petari" folder.
# Run the command '''python setup.py'''. This will verify your DOL and install all of the libraries used, and the compilers we use to compile the code.
# Run the command '''python build.py'''. This will build the entire project. If you see any warnings, do not worry about them.

== Environment ==
To properly utilize and use ''Petari'', it is necessary to understand the structure of the environment. Petari is structured in a way that makes it easy to access and use.

{| class="wikitable"
|-
! Folder Name !! Description
|-
| archive || The folder that gets created when '''build.py -link''' is ran. Contains an archive of the object files in each library.
|-
| build || The folder that gets created when '''build.py''' is ran. Contains the compiled object files.
|-
| csv || Contains CSV files that store the status of functions being matched.
|-
| data || Contains map files and the percentage badges for the GitHub repo.
|-
| docs || The folder that gets created when '''progress.py''' is ran. Contains all of the Markdown documentation for matching status.
|-
| include || Contains all of the header files for ''Super Mario Galaxy'' specific code.
|-
| libs || Contains this folder structure but for different libraries used by the game.
|-
| scripts || Various scripts used in IDA for generating headers.
|-
| source || Contains all of the source files for ''Super Mario Galaxy'' specific code.
|}

== Libraries ==
''Super Mario Galaxy'' uses a lot of libraries for certain functionality such as heaps, layouts, OS specific code, and more. Each library described in the table below are '''statically linked''' to the game, so every library's used code is inside of the ''main.dol''.

=== Non-SMG Libraries ===
{| class="wikitable"
|-
! Name !! Language !! Description
|-
| JSystem || C++ || Contains classes for backend things, such as heaps and linked lists.
|-
| MetroTRK || C || Target Resident Kernel, for debugging.
|-
| MSL_C || C & C++ || Contains standard library functions and types.
|-
| nw4r || C++ || Contains classes for sounds, layouts, and more. (SMG only uses the layouts and some math functions)
|-
| Runtime || C & C++ || Contains functions that relate to CodeWarrior's runtime code generation (ctor / dtor lists, etc)
|-
| RVL_SDK || C || Contains functions that relate to the Wii's "OS".
|-
| RVLFaceLib || C || Contains functions that relate to Miis.
|}

=== SMG Libraries ===
All of ''Super Mario Galaxy'''s libraries are written in C++.

{| class="wikitable"
|-
! Header text !! Header text
|-
| Animation || Library for animation playing.
|-
| AreaObj || Library for invisible areas that can be accessed by players in the game.
|-
| AudioLib || N/A
|-
| Boss || Library for all of the bosses and mini-bosses in the game.
|-
| Camera || Library for all camera types.
|-
| Demo || Library for all cutscenes.
|-
| Effect || Library for all effect rendering.
|-
| Enemy || Library for all enemies.
|-
| GameAudio || N/A
|-
| Gravity || Library for all of the gravity types in the game.
|-
| LiveActor || Library for LiveActor, which is an actor that can switch states.
|-
| Map || Library for map classes that do not directly interact with the player. (ie switches)
|-
| MapObj || Library for all of the map objects in the game.
|-
| NameObj || Library for the most basic form of an object in the game.
|-
| NPC || Library for all of the non-playable characters.
|-
| NWC24 || Library for the mail system in the game.
|-
| Player || Library for all of the player related functions.
|-
| RhythmLib || N/A
|-
| Ride || Library for all of the actors that can be controlled by the player.
|-
| Scene || Library for all of the game scene related code.
|-
| Screen || Library for all of the layouts in the game.
|-
| Speaker || Library for the sound effect playing done on the Wiimote.
|-
| System || Library for a lot of the game's backend systems.
|-
| Util || Library for utility functions and classes.
|}

== Basics ==
To properly decompile, it is vital to know how a lot of the assembly will translate into C / C++ code. Here are a couple of patterns that you will see when decompiling code.

== Class Mapping ==
=== Base Class ===
The first step to decompiling a class is to map out the class itself. You need to be sure that you document every member, it's type (as close as you can guess), it's virtual functions, and more. The easiest way to achieve this is to look at the class's ''constructor''. Seen below, is an example of a ''constructor''.

[[Image:NameObj_Ctor.png|frameless|700px|The constructor for ''NameObj''.]]

There are a couple of takeaways from this screenshot:
* The constructor passes an argument, which is a '''const char *''' (contained in r4) and is stored in (r3 + 0x4).
* (r3 + 0x0) is where the vtable is ''usually'' stored when a class has virtual functions. There are rare execptions.
* (r3 + 0x8) is stored with a '''sth''', which means that it is a '''short''' datatype.
* (r3 + 0xA) is also stored with a '''sth''', but with a '''-1''' value, so we know for sure that this type is ''signed''.

Keep in mind that a constructor does not have to initialized every single member variable in the class! So there could be other members in a class that aren't mentioned in the constructor at all. After you look at the constructor, look around at the ''member functions'' to see if they use any members that are not initialized in the constructor. You can always verify if your class setup is correct when you can find where this class is created using the '''new''' operator. Check if the size passed to the '''new''' call matches the size of the class that you have mapped. If it is smaller, you are missing arguments. If it is bigger, you have too many! Remember that the vtable is implicitly stored at '''(this + 0x0)''', so you do not have to explicitly define it. With all of these members documented, our class setup looks a little like this so far:

<pre>
class NameObj {
public:
NameObj(const char *pName);

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

After the members comes the '''vtable''', or ''virtual table''. It is an array of function pointers that can be overridden by classes that inherit the parent class. The vtable for '''NameObj''' looks like this:
[[Image:NameObj_Vtable.png|frameless|700px|The vtable for ''NameObj''.]]

To document the vtable, you simply document every single function placed here that contains the class name of the class you are currently decompiling. Since ''NameObj'' is a base class, every single function here is going to be defined. If a class overrides a function, you will only document the functions that are overridden. After documenting the vtable, our class looks something like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

Once the vtable is complete, you want to document all of the member functions that are in the class. Since ''Super Mario Galaxy 1'' has a symbol map, we can easily find the member functions that ''NameObj'' contains. Once you have figured out their return types and their arguments, you can finish mapping out a class! After finding all of ''NameObj'''s member functions, the class looks like this:

<pre>
class NameObj {
public:
NameObj(const char *pName);

virtual ~NameObj();
virtual void init(const JMapInfoIter &rIter);
virtual void initAfterPlacement();
virtual void movement();
virtual void draw() const;
virtual void calcAnim();
virtual void calcViewAndEntry();

void initWithoutIter();
void setName(const char *pName);
void executeMovement();
void requestSuspend();
void requestResume();
void syncWithFlags();

/* remember that the vtable will be placed here once we define our virtuals! */
/* 0x4 */ const char* mName;
/* 0x8 */ volatile u16 mFlags;
/* 0xA */ s16 mExecutorIdx;
};
</pre>

=== Loops ===
==== Predefined bounds ====
Let's take a simple loop that stores nullptr in each 8 elements of a pointer array.

<pre>
class TestClass {
public:
TestClass();

int* mPointers[8];
};

TestClass::TestClass() {
for (int i = 0; i < 8; i++) {
mPointers[i] = nullptr;
}
}
</pre>

The output assembly would look something like:

<pre>
li r0, 8 # there are 8 elements in this loop
li r5, 0 # the value to store in the element (nullptr)
li r4, 0 # the current element offset in the loop
mtctr r0 # move the number of iterations into the counter register (8)

loop:
stwx r5, r3, r4 # store 0 (r5) into the array at r3 (this) + r4 (our current offset, which is i * 4)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
bdnz+ loop # branch back to our loop again
</pre>

==== Variable Length Bounds ====
Let's take a simple loop that stores nullptr in each element of a variable-length array. We will have a class with two members, one that contains the pointer array itself, and another that stores the number of pointers.

<pre>
class TestClass {
public:
TestClass();

int** mPointers;
int mNumPointers;
};

TestClass::TestClass() {
mNumPointers = 8;
for (int i = 0; i < mNumPointers ; i++) {
mPointers[i] = nullptr;
}
}
</pre>

Because we do not know how many pointers we have stored, we cannot use the counter register like we did with a fixed-size array. Instead, the compiler will use a cmpw (signed integer) or cmplw (unsigned) instruction to compare the current iteration to how many pointers are stored in the class.

<pre>
li r0, 8 # there are 8 elements in this loop
li r7, 0 # the value to store in the element (nullptr)
stw r0, 4(r3) # r3 + 4 is the offset to our member variable "mNumPointers"
mr r6, r7 # simple copy of the 0 value so we can also use it for our counter
li r4, 0 # load 0 into our offset
b loop # branch into our loop

loop:
lwz r5, 0(r3) # load our pointer array from this + 0
addi r7, r7, 1 # increment our index by 1
stwx r6, r5, r4 # store our nullptr value (r6) into r5 + r4 (ptrArray + currentOffset)
addi r4, r4, 4 # increment our offset by sizeof(int) since integers are 32-bits
lwz r0, 4(r3) # load our number of pointers we will increment by (mNumPointers)
cmpw r7, r0 # compare our number of pointers to the current index in our loop
blt+ loop # branch if the number is less than mNumPointers
</pre>

==== Structure Access In Arrays (Pointer Array) ====
More complex forms of loops comes into play when you are iterating through structures and storing / loading members from those structures. Let's take this class for example:
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct** mStructures;
int mNumStructures;
};
</pre>
For the sake of simplicity, let's assume that the TestClass constructor initializes the number of structures to 8, and constructs them accordingly. With that in mind, let's see how a struct store will work.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < mNumStructures; i++) {
mStructures[i]->AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r7, 0 # our "i" used in the loop, starts at 0
li r4, 0 # our current offset into the array
li r6, 5 # the value we are storing into the array
b loop

loop:
lwz r5, 0(r3) # load the array pointer
addi r7, r7, 1 # increment our current index (i) by 1
lwzx r5, r5, r4 # load the current structure, mStructures[i] where r4 is the current offset
addi r4, r4, 4 # increment our offset by sizeof(TestStruct*), which is 4
stw r6, 4(r5) # store our value (5) into (mStructures[i] + 4), which is our AnotherMember
lwz r0, 4(r3) # load the number of structures from TestClass
cmpw r7, r0 # compare the current index to our value in TestClass
blt+ loop # loop back if it is less than the value
</pre>

==== Structure Access In Arrays (Direct Array) ====
Let's take the previous example and modify it a little. Instead of making an array of pointers to the struct instances, let's store the array directly into our class instance.
<pre>
struct TestStruct {
int SomeMember;
int AnotherMember;
};

class TestClass {
public:
TestClass();

void storeVals();

TestStruct mStructures[8];
};
</pre>
Again, let us assume that the array has already been constructed and everything is initialized as it should be.
<pre>
void TestClass::storeVals() {
for (int i = 0; i < 8; i++) {
mStructures[i].AnotherMember = 5;
}
}
</pre>
The output assembly would look something like:
<pre>
li r0, 8 # load our number of iterations (8)
li r4, 0 # current offset into the array. initialized at 0
li r6, 5 # the value to store into the array
mtctr r0 # move the number of iterations into the counter register

loop:
add r5, r3, r4 # jump to the offset into the array. r5 = (this + 0) + r4
addi r4, r4, 8 # increment our current offset by sizeof(TestStruct), which is 8
stw r6, 4(r5) # store our constant value (5) into the loaded struct + 4 (AnotherMember)
bdnz+ loop # branch back to the loop if the counter is not 8
</pre>

File:NameObj Vtable.png

2024-04-06T12:14:15Z

Shibboleet: vtable for nameobj

== Summary ==
vtable for nameobj

File:NameObj Ctor.png

2024-04-06T12:01:12Z

Shibboleet: NameObj constructor image

== Summary ==
NameObj constructor image

MSBT (File Format)

2024-03-07T16:05:21Z

Shibboleet: /* Label Indices */

[[Category:File formats]]
'''MSBT''' stands for ''Message Binary Text'', it contains all of the text used in '''Super Mario Galaxy 2'''.

== Header ==
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''MsgStdBn'' in ASCII.
|-
| 0x08 || UInt16 || Endianess. 0xFEFF for Big Endian, 0xFFFE for Little Endian.
|-
| 0x0A || UInt32 || Version.
|-
| 0x0E || UInt16 || Number of sections.
|-
| 0x10 || UInt16 || Padding.
|-
| 0x12 || UInt32 || File length.
|-
| 0x16 || Byte[0xA] || Padding.
|}

= Sections =
After the header follows the sections. It is worth noting that these sections are padded to the nearest 0x10th byte with the value 0xAB.

== LBL1 ==
''LBL1'' is a section that contains the "labels" that are assigned to text. It is a hash table to determine the index that the label is stored at. The indices of the offsets are determined by the "hash" of the number of entries in the list and the label name.

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''LBL1'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Label Entries ===

After the header come the label entries.
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Label count.
|-
| 0x04 || LabelArray[N] || Labels, where '''N''' is the label count read above.
|}

A label is defined by the following structure:
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Number of strings associated with this entry.
|-
| 0x04 || UInt32 || Offset to the strings associated with that label, offset relative to the field defining the amount of entries. Reads '''N''' strings, depending on the count read above.
|}

=== Label Indices ===
The following code can determine the index of a specific label:

<pre>
def hash_label(label, bucket_count):
val = 0
for c in label:
val = ((val * 0x492) + ord(c)) & 0xFFFFFFFF
return val % bucket_count
</pre>

For example, a file with '''0x65''' label entries with a label string of '''Pichan001_Flow001''' will be at index 0 of the label list, with '''PichanRacer000_Flow002''' being at index 1, and so on. If there is a gap between two indices, then it is filled with the previous entry's offset until the next index is determined.

== ATR1 ==

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''ATR1'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Attribute Entries ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Attribute set count.
|-
| 0x04 || UInt32 || Attribute size. The size of each attribute in bytes.
|-
| 0x08 || AttributeSetArray[N] || Attribute sets, where '''N''' is the set count read above.
|}

The attribute structure is dependent on the game, but in Super Mario Galaxy 2 each attribute is of size 0x0C and has the following structure:

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Byte || NPC Sound ID.TODO: Add a list of NPC Sounds here?
|-
| 0x01 || Byte || Camera type.
{| class="wikitable"
! ID !! Description
|-
| 0 || AUTOMATIC - The camera will be handled automatically by the game.
|-
| 1 || MANUAL - The camera used will be one from the CameraParam.bcam file inside the zone's Map archive.
|-
| 2 || NONE - The camera will not change.
|}
|-
| 0x02 || Byte || Trigger type.
{| class="wikitable"
! ID !! Description
|-
| 0 || The player has to be close to the NPC and press A to start the dialog.
|-
| 1 || The dialog is activated automatically when the player is close, but the player can still move when the dialog has started. The dialog stops when the player exits the trigger area.
|-
| 2 || The dialog is activated automatically when the player is close, but the player has to finish the dialog to continue moving.
|-
| 3 || The dialog is activated automatically when the player is anywhere (or in a much larger area?), but works otherwise like 2.
|}
|-
| 0x03 || Byte || Dialog style.
{| class="wikitable"
! ID !! Description
|-
| 0 – 2 || White textbox.
|-
| 3 || Billboard textbox.
|}
|-
| 0x04 || UInt16 || Camera ID. This is the ID that you find inside the CameraParam.bcam file. Needs to be higher than 0.
|-
| 0x06 || Byte || MessageArea ID. This matches with MessageArea's Obj Arg 0.
|-
| 0x07 || Byte ||
|-
| 0x08 || UInt32 || Offset to a UTF-16 encoded, null terminated, string. Seems to be unused.
|}

== TXT2 ==

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''TXT2'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Text Entries ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Text count.
|-
| 0x04 || Text[N] || Texts, where '''N''' is the text count read above.
|}

A text entry is a UTF-16 string, with embedded "tags" that affect the way the text displays and functions. A tag begins with a value of 0x000E and then the "tag". The following "tags" are possible:

{| class="wikitable"
! Type !! Description
|-
| 0x0 || System Group
|-
| 0x1 || Display Group
|-
| 0x2 || Sound Group
|-
| 0x3 || Picture Group
|-
| 0x4 || Font Size Group
|-
| 0x5 || Localize Group
|-
| 0x6 || Number Group
|-
| 0x7 || String Group
|-
| 0x9 || Race Time Group
|-
| 0xA || Font Group
|}

A "tag" can have a "command", which tells it how to function.

=== System Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Type. [0 == Japanese, 3 == Color]
|-
| 0x02 || UInt16 || Data size.
|-
| 0x04 || UInt16 || The color to use.
|}

=== Display Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Display type.
|-
| 0x02 || UInt16 || Data size.
|-
| 0x04 || UInt16 || Padding.
|-
| 0x06 || UInt16 || Number of frames to wait if the type is 0.
|}

=== Sound Group ===
Plays a given sound.

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Should always be 2.
|-
| 0x02 || UInt16 ||
|-
| 0x04 || UInt16 || String length.
|-
| 0x06 || String[Length] || UTF-16 string containing the sound effect to play.
|}

=== Picture Group ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Character index.
|-
| 0x02 || UInt16 || Font.
|-
| 0x04 || UInt16 || Character ID.
|}

=== Font Size Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Font Size.
|}

=== Localize Group ===
Inserts the current player's name.

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Byte[0x6] ||
|}

=== Number Group ===

=== String Group ===

=== Race Time Group ===

=== Font Group ===

MSBT (File Format)

2024-03-07T16:04:14Z

Shibboleet: be more specific about how the hash table on LBL1 works

[[Category:File formats]]
'''MSBT''' stands for ''Message Binary Text'', it contains all of the text used in '''Super Mario Galaxy 2'''.

== Header ==
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''MsgStdBn'' in ASCII.
|-
| 0x08 || UInt16 || Endianess. 0xFEFF for Big Endian, 0xFFFE for Little Endian.
|-
| 0x0A || UInt32 || Version.
|-
| 0x0E || UInt16 || Number of sections.
|-
| 0x10 || UInt16 || Padding.
|-
| 0x12 || UInt32 || File length.
|-
| 0x16 || Byte[0xA] || Padding.
|}

= Sections =
After the header follows the sections. It is worth noting that these sections are padded to the nearest 0x10th byte with the value 0xAB.

== LBL1 ==
''LBL1'' is a section that contains the "labels" that are assigned to text. It is a hash table to determine the index that the label is stored at. The indices of the offsets are determined by the "hash" of the number of entries in the list and the label name.

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''LBL1'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Label Entries ===

After the header come the label entries.
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Label count.
|-
| 0x04 || LabelArray[N] || Labels, where '''N''' is the label count read above.
|}

A label is defined by the following structure:
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Number of strings associated with this entry.
|-
| 0x04 || UInt32 || Offset to the strings associated with that label, offset relative to the field defining the amount of entries. Reads '''N''' strings, depending on the count read above.
|}

=== Label Indices ===
The following code can determine the index of a specific label:

<pre>
def hash_label(label, bucket_count):
val = 0
for c in label:
val = ((val * 0x492) + ord(c)) & 0xFFFFFFFF
return val % bucket_count
</pre>

For example, a file with '''0x65''' label entries with a label string of '''Pichan001_Flow001''' will be at index 0 of the label list, with '''PichanRacer000_Flow002''' being at index 1, and so on.

== ATR1 ==

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''ATR1'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Attribute Entries ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Attribute set count.
|-
| 0x04 || UInt32 || Attribute size. The size of each attribute in bytes.
|-
| 0x08 || AttributeSetArray[N] || Attribute sets, where '''N''' is the set count read above.
|}

The attribute structure is dependent on the game, but in Super Mario Galaxy 2 each attribute is of size 0x0C and has the following structure:

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Byte || NPC Sound ID.TODO: Add a list of NPC Sounds here?
|-
| 0x01 || Byte || Camera type.
{| class="wikitable"
! ID !! Description
|-
| 0 || AUTOMATIC - The camera will be handled automatically by the game.
|-
| 1 || MANUAL - The camera used will be one from the CameraParam.bcam file inside the zone's Map archive.
|-
| 2 || NONE - The camera will not change.
|}
|-
| 0x02 || Byte || Trigger type.
{| class="wikitable"
! ID !! Description
|-
| 0 || The player has to be close to the NPC and press A to start the dialog.
|-
| 1 || The dialog is activated automatically when the player is close, but the player can still move when the dialog has started. The dialog stops when the player exits the trigger area.
|-
| 2 || The dialog is activated automatically when the player is close, but the player has to finish the dialog to continue moving.
|-
| 3 || The dialog is activated automatically when the player is anywhere (or in a much larger area?), but works otherwise like 2.
|}
|-
| 0x03 || Byte || Dialog style.
{| class="wikitable"
! ID !! Description
|-
| 0 – 2 || White textbox.
|-
| 3 || Billboard textbox.
|}
|-
| 0x04 || UInt16 || Camera ID. This is the ID that you find inside the CameraParam.bcam file. Needs to be higher than 0.
|-
| 0x06 || Byte || MessageArea ID. This matches with MessageArea's Obj Arg 0.
|-
| 0x07 || Byte ||
|-
| 0x08 || UInt32 || Offset to a UTF-16 encoded, null terminated, string. Seems to be unused.
|}

== TXT2 ==

=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || String || ''TXT2'' in ASCII.
|-
| 0x04 || UInt32 || Section size. Does not account for this header or padding.
|-
| 0x08 || Byte[0x8] || Padding.
|}

=== Text Entries ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || Text count.
|-
| 0x04 || Text[N] || Texts, where '''N''' is the text count read above.
|}

A text entry is a UTF-16 string, with embedded "tags" that affect the way the text displays and functions. A tag begins with a value of 0x000E and then the "tag". The following "tags" are possible:

{| class="wikitable"
! Type !! Description
|-
| 0x0 || System Group
|-
| 0x1 || Display Group
|-
| 0x2 || Sound Group
|-
| 0x3 || Picture Group
|-
| 0x4 || Font Size Group
|-
| 0x5 || Localize Group
|-
| 0x6 || Number Group
|-
| 0x7 || String Group
|-
| 0x9 || Race Time Group
|-
| 0xA || Font Group
|}

A "tag" can have a "command", which tells it how to function.

=== System Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Type. [0 == Japanese, 3 == Color]
|-
| 0x02 || UInt16 || Data size.
|-
| 0x04 || UInt16 || The color to use.
|}

=== Display Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Display type.
|-
| 0x02 || UInt16 || Data size.
|-
| 0x04 || UInt16 || Padding.
|-
| 0x06 || UInt16 || Number of frames to wait if the type is 0.
|}

=== Sound Group ===
Plays a given sound.

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Should always be 2.
|-
| 0x02 || UInt16 ||
|-
| 0x04 || UInt16 || String length.
|-
| 0x06 || String[Length] || UTF-16 string containing the sound effect to play.
|}

=== Picture Group ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Character index.
|-
| 0x02 || UInt16 || Font.
|-
| 0x04 || UInt16 || Character ID.
|}

=== Font Size Group ===

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt16 || Font Size.
|}

=== Localize Group ===
Inserts the current player's name.

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Byte[0x6] ||
|}

=== Number Group ===

=== String Group ===

=== Race Time Group ===

=== Font Group ===

Decompiling

2024-03-02T18:42:26Z

Shibboleet:

Decompiling

2024-03-02T18:26:17Z

Shibboleet: /* Structure Access In Arrays */

Decompiling

2024-03-02T18:24:39Z

Shibboleet:

Decompiling

2024-03-02T17:57:21Z

Shibboleet: /* Predefined bounds */

Decompiling

2024-03-02T17:55:23Z

Shibboleet: /* Variable Length Bounds */

Decompiling

2024-03-02T17:54:49Z

Shibboleet: add info on loops

Decompiling

2024-02-23T17:18:22Z

Shibboleet: