The following is a general overview of the project's structure.
Decompiled C and assembly code (finished and unfinished) can be found under the src, include, and asm directories.
The src directory contains all of the decompiled C implementation files (.c files). Each file (excluding DLL code) is mapped from a specific address range in the base ROM via splat. These files are generally stubbed out by splat when a new address range is marked as C code and contain GLOBAL_ASM pragmas that include the original assembly code (in order) for each function in the file. When a function is fully decompiled and matching, the GLOBAL_ASM pragma is removed.
The src/dlls directory is special. Dinosaur Planet uses a unique DLL system. Each DLL has its own directory under src/dlls containing:
- A single C file for the full implementation of that DLL.
- An
exports.sfile which defines the DLL's export table. - A
dll.yamlfile that configures how the DLL should be extracted and recompiled. - A
syms.txtfile that defines addresses for known symbols for that specific DLL.
In the src/dlls/dlls.txt file, DLL numbers are mapped to their subdirectory.
Additionally, the dlls directory currently contains a special linker script for just DLL code.
The include directory contains all of the C header files (.h) for the project as well as shared assembly files (.inc) that are meant to be included in a .s file.
Headers related to libultra are currently split into three directories: PR, libultra, and libc.
PR(project reality) contains the typical headers used when developing an N64 title and only contains public variables, functions, and macros.libultracontains headers for internal libultra code that has been decompiled (typically these are taken/formatted like the existing libultra decompilation libreultra, however Dinosaur Planet uses a fairly modified version of libultra so not everything is the same).libccontains headers for... libc!
Additionally, the root of include contains the header ultra64.h which includes most of the PR headers all at once.
The macro.inc file is included at the top of every extracted assembly file and just contains a prelude of macros needed to reassemble those files.
TODO: document how headers for game systems and general code should be organized
Code and data extracted directly from the base ROM are located under the asm and bin directories respectively.
With the exception of the nonmatchings directory, everything under asm are segments of the ROM marked as assembly code that (usually) can't be decompiled into C code. The nonmatchings directory contains a single .s file for every function included from a .c file via GLOBAL_ASM. Everything under asm is managed directly by splat and shouldn't be modified directly.
The bin directory contains a .bin file for every ROM segment marked as generic binary data. This data could be anything from an audio file to the .rodata section of a file that hasn't been marked in splat yet.
The single exception to bin is the bin/assets/dlls directory, which contains individual .dll files for every DLL in the game unpacked directly from DLLS.bin.
The root of the repository contains various files that define symbol addresses, the configuration for splat, and the linker script used for the re-built ROM.
dino.ld- The linker script generated by splat. Should not be modified directly.splat.yaml- The project configuration for splat. Here is where ROM segments are marked for extraction.symbol_addrs.txt- Defines addresses for known symbols (only those are referenced directly in assembly code).undefined_funcs.txt- Defines addresses for functions that are known but aren't referenced directly in assembly code.undefined_syms.txt- Defines addresses for symbols that are known but aren't referenced directly in assembly code.undefined_funcs_auto.txt- Addresses of functions that splat found automatically. This file should not be modified directly.undefined_syms_auto.txt- Addresses of symbols that splat found automatically. This file should not be modified directly.export_symbol_addrs.txt- Defines symbol names for each DLLSIMPORT.tab entry. These symbols will also be found in the other symbol files and names should be kept in sync.
The root of the repository and the tools directory contain many scripts and programs used as part of the build system and as utilities for decomp.
dino.py- A general script for common tasks such as extracting and building the ROM as well as diffing.tools/asm_differ- Diffs assembly between the base and re-built ROM. The project configuration for asm differ can be found indiff_settings.pyin the repository root.tools/asm_processor- ProcessesGLOBAL_ASMpragmas when compiling C code by patching in the included assembly into the resulting object file.tools/build_clang_commands- Generates acompile_commands.jsonfile forclangd.tools/ido_recomp- Contains recompiled IDO executables to run on a modern system.tools/splat- Extracts assembly and data from the base ROM and generates the linker script for the re-built ROM.tools/configure.py- Configures the Ninja build script file (build.ninja) for the project.tools/dino_dll.py- Packs and unpacks theDLLS.binandDLLS_tab.binfiles.tools/dll_split.py- Like splat, but for Dinosaur Planet DLLs. Extracts assembly and data from each unpacked DLL and sets up a directory undersrc/dllscontaining a C stub, the DLL's export table, and automatically discovered symbols.tools/dlldump.py- Displays the header, relocation tables, and executable assembly for a given Dinosaur Planet.dllfile.tools/dllimports.py- Displays and provides address/index lookup for DLLSIMPORT.tab entries.tools/dlltab.py- Displays information from the DLLS.tab file.tools/elf2dll.py- Converts a standard ELF file to the unique Dinosaur Planet DLL format.tools/first-diff.py- Find the first N differences between the base and re-built ROM.tools/first_bin_diff.py- Find the first N differences between two binary files.tools/dlldiff.py- Finds differences between the base and re-built DLLs.tools/m2ctx.py- Creates a context file for mips2c/decomp.me.tools/progress.py- Calculates the current progress of the decomp.