tobi#

ACPI AML decompiler that reads raw AML blobs and DSDT/SSDT tables, skips validated ACPI headers, and builds its own IR while doing conservative CFG recovery over package bounded control operations, then emits pseudocode, opcode disassembly, JSON IR, raw table metadata/Graphviz CFG view

Unsupported bytes stay in the tree as explicit IR nodes with offsets anyway and malformed input goes through diagnostics rather than blowing up whereas the parser keeps bounded reader state as well so hostile or truncated input just fails as data instead of turning into out of bounds reads

Build#

cmake -S . -B build -DTOBI_WERROR=ON -DTOBI_FZ=ON
cmake --build build
ctest --test-dir build --output-on-failure

The recommended validation path before landing parser changes is the sanitised configuration. ASan/UBSan are enabled to surface memory safety violations and UB during parser execution. LSan is intentionally disabled in the default environment because the test harness executes under ptrace and causes LeakSanitizer to abort before it can report meaningful allocation diagnostics:

cmake -S . -B build-san -DCMAKE_C_COMPILER=clang -DTOBI_SAN=ON -DTOBI_WERROR=ON -DTOBI_FZ=ON
cmake --build build-san
ctest --test-dir build-san --output-on-failure
./build-san/fz

Usage#

tobi [opts] <file> [file...]

--dis       print opcode disam
--json      print parsed IR as json
--dot       print recovered CF as Graphviz DOT
--raw       print input/table metadata and AML offsets
--strict    treat malformed/unsupported constructs as hard errors
--plain     disable coloured diagnostics
--help      print usage
--version   print version

Default mode prints pseudocode:

./build/tobi sam/m0.aml

method MTH0(args=1, serialized=false, sync=0) {
    Local0 = 0x2a;
    return Local0;
}

Opcode view:

./build/tobi --dis sam/m0.aml

JSON IR:

./build/tobi --json sam/m0.aml

CFG view:

./build/tobi --dot sam/m1.aml

Multiple AML inputs share one namespace pre pass before parsing:

./build/tobi dsdt.aml ssdt1.aml ssdt2.aml

--dis and --raw still report each input independently because those modes are byte stream oriented and dont need the aggregate IR

Input#

Accepted inputs:

raw AML bytecode
DSDT tables with a 36 byte ACPI header
SSDT tables with a 36 byte ACPI header

For tables it checks the signature and then validates the length at offset 4 before touching the AML body and verifies the ACPI checksum across the declared table length. Bad lengths are errors (obviously) and checksum mismatches are warnings by default and hard errors under --strict

Every IR node stores:

kind
source byte offset
source byte length where known
owned name/path/string payloads
raw opcode for unknown or opcode expression nodes
deterministic child array

Control flow#

AML IfOp, ElseOp, and WhileOp carry package bounded bodies so tobi reconstructs those directly while preserving the original lexical nesting. It doesnt invent higher level source constructs from control bytes whose semantics cant be established with confidence

Any ambiguous branch residue is kept as explicit fallback labels or annotated comments tied to the originating byte offset instead. Break and Continue are only emitted when the surrounding lexical context makes them unambiguously valid loop control operations. Outside loops they remain explicit IR nodes with diagnostics rather than being rewritten into incorrect high level control flow

Samples#

m0   14 0c 4d 54 48 30 01 70 0a 2a 60 a4 60
m1   14 15 49 46 45 30 01 a0 06 68 70 0a 01 60 a1 05 70 0a 02 60 a4 60
m2   14 20 57 4c 4f 30 01 70 0a 03 60 a2 13 60 a0 06 68 70 0a 01 61 a1 05 70 0a 02 61 74 60 01 60 a4 61
dev0 10 31 5c 5f 53 42 5f 5b 82 29 44 45 56 30 5b 80 52 45 47 30 01 0a 10 0a 04 5b 81 0b 52 45 47 30 00 46 4c 44 30 08 14 0b 52 44 4d 30 00 a4 46 4c 44

Limits#

This isnt a full ACPICA replacement. Namespace resolution is enough for method-call arity and readable paths but unresolved names can remain refs. Resource descriptors are recognised before theyre fully decoded. Less-structured AML stays as labelled IR/commentary instead of getting rewritten into invented source constructs. Unknown opcode coverage should shrink by adding metadata and operand parsers, not by special casing sample bytes

Configure Feed