Qwen32b-N64-Decomp-GGUF

Main, non-quantizied variant: https://huggingface.co/Allomgie/Qwen32B-N64-Decomp-16bit.

Qwen32B-N64-Decomp-16bit (Stage 2 Master)

This model is a specialized fine-tune of Qwen2.5-Coder-32B-Instruct, specifically engineered for decompiling MIPS assembly into C code compatible with the SGI IDO 5.3 compiler.

It has been trained in a two-stage process on a verified dataset. The final Stage 2 utilized an 8192-token context length and achieved a mean token accuracy of 96.5% on complex 8k-token samples.

The model focuses on:

• Logical reconstruction
• Precise register mapping
• Compiler-specific patterns
• Nintendo 64 reverse engineering workflows

---

Experimental Status

Project State

Advanced Testing Phase

This is the unquantized 16-bit (BF16) master checkpoint. While it performs exceptionally well and understands complex control flows (e.g. nested ternary operators and switch tables), the output must still be verified by a human.

It acts as an expert assistant for IDO decompilation, not an autonomous compiler.

Model Variants

BF16 (65.5GB) → maximum precision, server use
Q8_0 (ca. 35GB) → near-lossless, RE work
Q6_K (ca. 27GB) → balanced accuracy
Q5_K_M (ca. 23GB) → 24GB GPU optimal
Q4_K_M (ca. 20GB) → consumer fast inference

Hardware Requirements

BF16: ca. 80GB VRAM (H100 / A100 / multi-GPU)
Q8_0: ca. 40GB VRAM
Q6_K: ca. 32GB VRAM
Q5_K_M / Q4_K_M: ca. 24GB VRAM

CPU inference: ≥64GB RAM recommended

Data Provenance & Training

The dataset is fully clean-room, compiler-verified, and does NOT include raw copyrighted source leaks.

Pipeline

• Compiler-Guided Delta Debugging (IDO 5.3)
• Hash verification of compiled output
• Semantic pruning (dead code / noise removal)

---

1. The IDO-5.3 Verification Pipeline

Every single MIPS-to-C pair in the dataset was verified using the original SGI IDO 5.3 compiler.

The dataset was processed through a custom Compiler-Guided Delta Debugging Pipeline inspired by C-Reduce, but specifically tailored for IDO 5.3.

This pipeline guarantees that the C code is a minimal representation of the target assembly.

Verification Process

• Hash Verification
  Every C snippet is freshly compiled. The resulting MIPS assembly hash is compared against the target baseline. If they match exactly, the sample is considered valid.

• Semantic Noise Reduction
  The pipeline removes dead code, unused variables, phantom branches, and non-essential artifacts.

• Result
  The model learns a near 1:1 mapping of logical C constructs to MIPS instructions while remaining largely free of human formatting bias and unrelated source artifacts.

---

2. Dataset Composition

The dataset consists of over 200,000 strictly validated pairs heavily weighted toward generated, stressed, and reconstructed logic.

Structurally Accurate Synthetic Data

To closely align the model with real Nintendo 64 development environments without relying on proprietary source code, the dataset utilizes custom-generated synthetic C files.

These files were algorithmically generated to mimic:

• authentic naming conventions
• global variable layouts
• struct-heavy logic
• late-90s game-engine patterns

Synthetic Torture Tests

Alongside established generators such as:

• Csmith
• YARPGen

the dataset incorporates deeply nested control flow, complex arithmetic, branch-heavy logic, and intentionally convoluted compiler edge cases.

This forces the model to infer compiler behavior rather than memorize standard functions.

Normalized Algorithmic Patterns

The dataset additionally includes clean-room implementations of:

• math routines
• sorting algorithms
• state machines
• pointer-heavy control structures

compiled directly to MIPS-II.

Switch-Case Generators

Custom-generated datasets specifically target:

• IDO jump-table generation
• branch-delay slot behavior
• switch lowering patterns
• compiler-specific branch scheduling

---

3. The Two-Stage SFT Process

Stage 1 — Architectural Foundation

Trained on the full 200k+ dataset using a 4096-token context window.

Primary objectives:

• MIPS-II semantics
• IDO register allocation behavior
• stack-frame reconstruction
• C-type mapping
• branch reconstruction

Stage 2 — Semantic Precision

Trained exclusively on a curated "Golden Dataset" of 40,000 highly complex and heavily reduced samples using an 8192-token context window.

Primary objectives:

• long-form context retention
• precise struct-offset tracking
• complex nested ternary reconstruction
• switch-table reconstruction
• compiler-faithful control-flow generation

---

Model Specifications

Recommended for professional environments requiring maximum accuracy.

---

Hardware Requirements

---

The Prompting Workflow (Critical)

To get valid results, you must follow the Semantic Expert IR – v16 format.

The model expects:

1. A JSON-formatted Technical Environment
2. The cleaned assembly

---

1. Preprocessing and Environment Building

The model does not understand raw disassembler output.

It requires two distinct pieces of input.

Cleaned Assembly

Requirements:

• Remove block comments
• Prefix each instruction with its 8-digit hexadecimal opcode

Example:

8c2e4e70 lw $t6, %lo(...)($at)

Technical Environment JSON (v16)

A context object that extracts:

• C types
• Struct definitions
• Function signatures
• Stack-frame metadata
• Branch metadata
• Global access patterns
• Instruction-class flags

from associated header files and assembly.

Note: The official asm_cleanup.py and techenv_builder.py scripts are available both in this Hugging Face repository and in the standalone TechEnv Builder repository:

https://github.com/Allomgie/AI_Decomp_Tools/tree/4671144486a5a5dd0f818999c277691945e6ad6b/TechEnv_Builder

Additional details about the Technical Environment structure, schema, and formatting rules can be found in FORMAT.md.

---

2. The Prompt Structure

This model was fine-tuned using the ChatML format.

Wrap your input using:

• <|im_start|>
• <|im_end|>

and assign the roles correctly.

Raw Prompt Template

<|im_start|>system
Decompile N64 MIPS assembly to C (IDO compiler). Use the technical environment for types, struct layouts, and calling context.
<|im_end|>

<|im_start|>user
### Technical Environment:
{
  "env": {
    "s": {},
    "sym": {
      "var_6": "int",
      "var_7": "unsigned int"
    },
    "ext": {}
  },
  "funcs": [
    {
      "n": "test",
      "sf": 56,
      "stk": {
        "saved": {
          "ra": "0x1c",
          "gp": "0x18"
        },
        "locals": {
          "blocks": [
            {
              "off": "0x38",
              "size": 24
            }
          ],
          "singles": 1
        }
      },
      "mem": [
        {
          "base": "var_6",
          "fields": [
            {
              "off": "0x0",
              "rw": "w"
            }
          ]
        }
      ],
      "br": [
        {
          "op": "beqz"
        }
      ],
      "calls": [
        {
          "type": "direct",
          "name": "max",
          "argc": 3
        }
      ],
      "args": ["a0", "a1", "a2", "a3"],
      "argc_conf": "medium",
      "ret": "void",
      "ret_conf": "medium",
      "globals": {
        "var_6": "rw",
        "var_7": "rw"
      }
    }
  ]
}

### MIPS Assembly:
.section .text
glabel test # 0

8f810000 lw          $at, %got(var_6)($gp)
27bdffc8 addiu       $sp, $sp, -0x38
[...]

03e00008 jr          $ra
00000000 nop

endlabel test
<|im_end|>

<|im_start|>assistant

---

3. Understanding the v16 Technical Environment

The Technical Environment JSON block is the most critical part of the prompt.

It acts as the model's symbol table and guarantees that memory offsets and registers are mapped to the exact C types used by the IDO compiler.

Omitting this information can cause hallucinations.

Key concepts in v16

env.s

Struct definitions extracted from .h files.

env.sym

Global variable declarations and their associated C types.

env.ext

External function signatures. When a function is declared here, args and ret are ground truth and argc_conf / ret_conf are omitted.

funcs

Metadata describing the target function.

Includes:

• sf → Stack-frame size
• stk → Saved registers and local-variable block sizes
• mem → Memory accesses and read/write flags
• args / ret → Parameter registers and inferred return type
• argc_conf / ret_conf → Confidence levels (high, medium, low) when inferred from ASM rather than declared in headers
• globals → Summary of which global variables this function reads or writes
• flags → Instruction-class indicators (e.g. has_fpu, has_64bit)
• calls[].tail → true for tail calls (j target instead of jal)

Polymorphic args

When ground truth is available from env.ext, args is an array of objects:

"args": [
  {"reg": "a0", "type": "ALCSeq *"},
  {"reg": "a1", "type": "s32"}
]

When inferred heuristically from the ASM, args is a string array and argc_conf is present:

"args": ["a0", "a1"],
"argc_conf": "medium"

---

Why Is This Strictness Required?

The SGI IDO compiler translates different C types into entirely different MIPS instructions.

Examples:

• lb → signed char
• lw → int

The Technical Environment prevents the model from generating incorrect casts that would fail binary matching.

---

4. Generation Parameters

Higher temperatures often produce code that does not compile correctly.

---

Best Practices

• Always provide a Technical Environment
• Use cleaned assembly only
• Prefer greedy decoding
• Keep functions isolated whenever possible
• Preserve exact stack-frame metadata
• Avoid truncated assembly blocks

---

Disclaimer

This model is provided "as is" for research and reverse engineering purposes.

The developers are not responsible for:

• misuse
• copyright infringement
• damages resulting from use of this tool

---

License

This model is released under the Apache 2.0 License.