fNET 0.1.0

An allocation-free, iced-style .NET CIL and Mono extension disassembler
Documentation
"""Generate the catalogue offline from pinned .NET runtime opcode.def snapshots.

Run: python tools/generate.py; cargo fmt
--check compares a rustfmt-normalized temporary file to the committed catalogue.
Only Python's standard library and rustfmt are needed. Builds need neither.
"""
import argparse
import csv
import pathlib
import re
import subprocess
import tempfile

ROOT = pathlib.Path(__file__).resolve().parents[1]


def parse(path):
    result = []
    for line in path.read_text(encoding="utf-8-sig").splitlines():
        if line.startswith("OPDEF("):
            fields = [v.strip().strip('"') for v in line[6:line.index(")")].split(",")]
            if fields[6] in ("1", "2") and fields[7].startswith("0x"):
                result.append(fields)
    return result


def variant(name):
    return "".join(p[0].upper() + p[1:] for p in re.split(r"[._]", name) if p)


def canonical(name):
    if name.endswith(".s"):
        return name[:-2]
    if re.fullmatch(r"(?:ldarg|ldloc|stloc)\.[0-3]", name):
        return name.rsplit(".", 1)[0]
    if name.startswith("ldc.i4."):
        return "ldc.i4"
    return name


rows = [r for r in parse(ROOT / "research/dotnet-opcode.def")
        if "UNUSED" not in r[0] and r[0] != "CEE_PREFIX1"]
# ECMA III.2.2 defines no.; CoreCLR does not expose it in Reflection.Emit.
rows.append(["CEE_NO", "no.", "Pop0", "Push0", "ShortInlineI", "IPrefix", "2", "0xFE", "0x19", "META"])
rows += [r for r in parse(ROOT / "research/mono-opcode.def") if r[0].startswith("CEE_MONO_")]
for legacy in parse(ROOT / "research/mono-legacy-opcode.def"):
    if legacy[0] in ("CEE_MONO_JIT_ATTACH", "CEE_MONO_JIT_DETACH"):
        legacy[5] = "IMonoLegacy"
        rows.append(legacy)
rows.sort(key=lambda r: int(r[8], 16) if r[6] == "1" else int(r[7], 16) * 256 + int(r[8], 16))
assert len(rows) == 263, len(rows)  # 219 standard, 7 reserved, 35 current + 2 retired Mono
assert len({r[1] for r in rows}) == len(rows)
assert len({(r[6], r[7], r[8]) for r in rows}) == len(rows)
modern_rows = rows[:]
maps = {}
for const, path, count in [
    ("EARLY_MONO_OPCODES", "mono-early2002-opcode.def", 12),
    ("JULY2002_MONO_OPCODES", "mono-july2002-opcode.def", 7),
    ("MAY2004_MONO_OPCODES", "mono-may2004-opcode.def", 15),
    ("LEGACY_MONO_OVERRIDES", "mono-legacy-getter-opcode.def", 1),
]:
    entries = [r for r in parse(ROOT / "research" / path) if r[0].startswith("CEE_MONO_")]
    if const == "LEGACY_MONO_OVERRIDES":
        entries = [r for r in entries if r[1] == "mono_get_last_error"]
    assert len(entries) == count, (const, len(entries))
    maps[const] = entries
extra_rows = []
seen_names = {r[1] for r in rows}
for const, entries in maps.items():
    for entry in entries:
        if entry[1] not in seen_names:
            r = entry.copy()
            r[5] = "IMonoLegacy" if const == "LEGACY_MONO_OVERRIDES" else "IMonoEarly"
            extra_rows.append(r)
            seen_names.add(r[1])
rows += extra_rows
extra_ids = {r[1]: 0xE100 + i for i, r in enumerate(extra_rows)}
with (ROOT / "research/mono-opcode-history-audit.tsv").open(encoding="utf-8-sig") as history:
    historical_rows = list(csv.DictReader(history, delimiter="\t"))
known_names = {r[1] for r in rows}
assert {r["name"] for r in historical_rows} <= known_names, "uncovered historical Mono identity"
available_maps = [modern_rows] + [entries for name, entries in maps.items() if name != "LEGACY_MONO_OVERRIDES"]
for historical in historical_rows:
    # Every historical identity/encoding pair must exist in an explicit map.
    # Declarations of payload widths are audited separately against consumers.
    encoding = (int(historical["first"], 16), int(historical["second"], 16))
    if historical["name"] == "mono_get_last_error":
        candidates = maps["LEGACY_MONO_OVERRIDES"]
    else:
        candidates = [r for entries in available_maps for r in entries]
    assert any(r[1] == historical["name"] and (int(r[7], 16), int(r[8], 16)) == encoding for r in candidates), historical
# Consumer/emitter audit corrects two upstream Mono table metadata bugs.
for r in rows:
    if r[1] == "mono_dyn_call":
        r[2:4] = ["PopI+PopI", "Push0"]
    if r[1] in ("mono_dyn_call", "mono_icall"):
        r[9] = "CALL"
    if r[1] == "mono_ldnativeobj":
        r[9] = "NEXT"

out = ["// @generated by tools/generate.py; do not edit.",
       "// Derived from .NET runtime (MIT); revision and notices in research/ and NOTICE.",
       "use crate::op_code::{FlowControl, OpCodeInfo, OpCodeKind, OperandKind};"]

for col, enum in [(2, "StackBehaviourPop"), (3, "StackBehaviourPush")]:
    values = sorted({r[col] for r in rows})
    out += ["/// ECMA static stack behaviour; variable effects depend on signatures.",
            "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]", f"pub enum {enum} {{"]
    out += [f"    {v.replace('+', '')}," for v in values]
    out += ["}", f"impl {enum} {{", "    /// Number of stack values, or None for a signature-dependent effect.",
            "    pub const fn count(self) -> Option<u8> {", "        match self {"]
    for v in values:
        count = "None" if v.startswith("Var") else f"Some({0 if v.endswith('0') else len(v.split('+'))})"
        out.append(f"            Self::{v.replace('+', '')} => {count},")
    out += ["        }", "    }", "}"]

mnemonics = list(dict.fromkeys(canonical(r[1]) for r in rows))
out += ["/// Canonical operation, with macro and short forms normalized.",
        "#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]",
        "pub enum Mnemonic {", "    #[default]", "    Invalid,", "    Custom,"]
out += [f"    {variant(n)}," for n in mnemonics]
out += ["}", "impl Mnemonic {", "    pub const fn as_str(self) -> &'static str {", "        match self {",
        '            Self::Invalid => "invalid",', '            Self::Custom => "custom",']
out += [f'            Self::{variant(n)} => "{n}",' for n in mnemonics]
out += ["        }", "    }", "}"]

out += ["/// Exact operation identity. Historical-only identities use internal E100 IDs.",
        "#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]",
        "#[repr(u16)]", "pub enum Code {", "    #[default]", "    Invalid = 0xFFFF,", "    Custom = 0xFFFE,"]
for r in rows:
    val = extra_ids.get(r[1], int(r[8], 16) if r[6] == "1" else int(r[7], 16) * 256 + int(r[8], 16))
    out += [f"    {variant(r[1])} = 0x{val:04X},"]
out += ["}", f"pub const OPCODE_COUNT: usize = {len(rows)};", "/// All operation identities across dialects, including reserved marker descriptors.",
        "pub const ALL_CODES: [Code; OPCODE_COUNT] = ["]
out += [f"    Code::{variant(r[1])}," for r in rows]
out += ["];", "impl Code {", "    /// Stable operation ID. Use Instruction::encoding() for the selected dialect's bytes.", "    pub const fn value(self) -> u16 { self as u16 }",
        "    /// Modern/retired map only. Select a decoder dialect for the early Mono map.",
        "    pub const fn from_encoding(value: u16) -> Option<Self> {", "        match value {"]
out += [f"            0x{int(r[8], 16) if r[6] == '1' else int(r[7], 16)*256+int(r[8], 16):04X} => Some(Self::{variant(r[1])})," for r in modern_rows]
out += ["            _ => None,", "        }", "    }", "    pub fn from_name(name: &str) -> Option<Self> {", "        match name {"]
out += [f'            "{r[1]}" => Some(Self::{variant(r[1])}),' for r in rows]
aliases = []
source = (ROOT / "research/dotnet-opcode.def").read_text(encoding="utf-8-sig")
ids = {r[0]: variant(r[1]) for r in rows}
for a, name, target in re.findall(r'OPALIAS\((\w+),\s*"([^"]+)",\s*(\w+)\)', source):
    if name not in {r[1] for r in rows}:
        aliases.append((variant(name), name, ids[target]))
out += [f'            "{name}" => Some(Self::{target}),' for _, name, target in aliases]
out += ["            _ => None,", "        }", "    }"]
for v, name, target in aliases:
    if v not in {variant(r[1]) for r in rows}:
        out += [f'    /// Alias `{name}`.', "    #[allow(non_upper_case_globals)]", f"    pub const {v}: Self = Self::{target};"]
out += ["    pub const fn name(self) -> &'static str { self.op_code().name }",
        "    pub const fn mnemonic(self) -> Mnemonic { self.op_code().mnemonic }",
        "    pub const fn is_prefix(self) -> bool { self.op_code().is_prefix() }",
        "    pub const fn canonical(self) -> Self {", "        match self {"]
out += [f"            Self::{variant(r[1])} => Self::{variant(canonical(r[1]))}," for r in rows if canonical(r[1]) != r[1]]
out += ["            other => other,", "        }", "    }",
        "    pub const fn implied_variable(self) -> Option<u16> {", "        match self {"]
out += [f"            Self::{variant(r[1])} => Some({r[1][-1]})," for r in rows if re.fullmatch(r"(?:ldarg|ldloc|stloc)\.[0-3]", r[1])]
out += ["            _ => None,", "        }", "    }", "    pub const fn implied_i32(self) -> Option<i32> {", "        match self {"]
out += [f"            Self::{variant(r[1])} => Some({-1 if r[1].endswith('m1') else r[1][-1]})," for r in rows if re.fullmatch(r"ldc\.i4\.(?:m1|[0-8])", r[1])]
out += ["            _ => None,", "        }", "    }", "    pub const fn op_code(self) -> &'static OpCodeInfo {", "        match self {"]
flows = {"NEXT": "Next", "BREAK": "Break", "CALL": "Call", "RETURN": "Return", "BRANCH": "Branch", "COND_BRANCH": "CondBranch", "THROW": "Throw", "ERROR": "Throw", "META": "Meta"}
for r in [["INVALID", "invalid", "Pop0", "Push0", "InlineNone", "IPrimitive", "0", "0xFF", "0xFF", "NEXT"],
          ["CUSTOM", "custom", "VarPop", "VarPush", "InlineNone", "ICustom", "0", "0xFF", "0xFE", "NEXT"]] + rows:
    name = r[1]
    v = variant(name)
    kind = "MonoEarly" if r[5] == "IMonoEarly" else "MonoLegacy" if r[5] == "IMonoLegacy" else "Mono" if r[0].startswith("CEE_MONO_") else "Reserved" if name.startswith("prefix") else r[5][1:]
    flow = flows[r[9]]
    if name == "jmp":
        flow = "Call"  # Match Reflection.Emit and distinguish method transfer from IL branch.
    val = 0xFFFF if name == "invalid" else 0xFFFE if name == "custom" else int(r[8], 16) if r[6] == "1" else int(r[7], 16)*256+int(r[8], 16)
    out += [f"            Self::{v} => &OpCodeInfo {{ code: Self::{v}, mnemonic: Mnemonic::{variant(canonical(name))}, name: \"{name}\", encoding: 0x{val:04X}, size: {r[6]}, operand: OperandKind::{r[4]}, pop: StackBehaviourPop::{r[2].replace('+','')}, push: StackBehaviourPush::{r[3].replace('+','')}, flow_control: FlowControl::{flow}, kind: OpCodeKind::{kind} }},"]
out += ["        }", "    }", "}"]
for const, entries in maps.items():
    out += ["/// Audited historical Mono map/overrides; select the corresponding decoder dialect.", f"pub const {const}: [OpCodeInfo; {len(entries)}] = ["]
    for r in entries:
        flow = "Next" if r[1] == "mono_ldnativeobj" else flows[r[9]]
        kind = "MonoLegacy" if const == "LEGACY_MONO_OVERRIDES" else "MonoEarly"
        out += [f'    OpCodeInfo {{ code: Code::{variant(r[1])}, mnemonic: Mnemonic::{variant(r[1])}, name: "{r[1]}", encoding: 0xF0{int(r[8],16):02X}, size: 2, operand: OperandKind::{r[4]}, pop: StackBehaviourPop::{r[2].replace("+", "")}, push: StackBehaviourPush::{r[3].replace("+", "")}, flow_control: FlowControl::{flow}, kind: OpCodeKind::{kind} }},']
    out += ["]; "]

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--check", action="store_true")
    args = parser.parse_args()
    text = "\n".join(out) + "\n"
    dest = ROOT / "src/generated.rs"
    if args.check:
        with tempfile.TemporaryDirectory() as directory:
            path = pathlib.Path(directory) / "generated.rs"
            path.write_text(text, encoding="utf-8", newline="\n")
            subprocess.run(["rustfmt", "--edition", "2024", str(path)], check=True)
            if path.read_text(encoding="utf-8") != dest.read_text(encoding="utf-8"):
                raise SystemExit("catalogue is stale; run python tools/generate.py and cargo fmt")
        print("catalogue verified: 219 standard + 7 reserved + 43 Mono identities, five dialect selections")
    else:
        dest.write_text(text, encoding="utf-8", newline="\n")
        print(f"generated {len(rows)} opcodes")


if __name__ == "__main__":
    main()