# 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

```sh
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:

```sh
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

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

```text
--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:

```sh
./build/tobi sam/m0.aml
```

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

Opcode view:

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

JSON IR:

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

CFG view:

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

Multiple AML inputs share one namespace pre pass before parsing:

```sh
./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:

```text
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:

```text
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

```text
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 
```