`agx`: Reverse-Engineering Apple’s Hidden GPU Language, One Bit at a Time
A Go toolkit that decodes, re-encodes, and structurally emulates Apple’s AGX3 shaders, exposing the gap between raw hardware fields and human-readable meaning.
- `agx` is less a disassembler than a method for proving how an undocumented Apple GPU instruction set behaves.
- The project keeps canonical meaning and raw hardware encoding side by side, which preserves uncertainty instead of flattening it away.
- Its real edge is structural analysis, where decoded shaders become control-flow graphs and compiler-like evidence.
- The result is a durable research tool that can keep pace with new Apple GPU generations without pretending the ISA is fully known.
The GPU Apple Never Explained
Apple’s recent AGX GPUs ship with a fixed-width VLIW instruction set that is powerful, compact, and largely undocumented. `agx` treats that opacity as the problem to solve, not a nuisance to paper over. It is a reverse-engineering lens for turning raw shader bytes into something you can test, compare, and reason about.
That framing matters. If you start by assuming the instruction means what the mnemonic suggests, you miss the point of the machine. `agx` starts from evidence: stable bit patterns, observed opcode families, and the limits of what can be known from binary alone.
Why Raw Bits Matter More Than Pretty Names
The project’s smartest move is to keep two views alive at once. Canonical mode gives you the clean human-readable instruction. Raw mode shows the packed fields the GPU actually sees. That split is not cosmetic. It is the difference between explanation and inference.
| View | Goal | What it preserves | What it hides | Best use case |
|---|---|---|---|---|
| Canonical | Read the instruction as a semantic action | Mnemonic, operands, likely intent | Low-level packing, ambiguity, scheduling details | Fast inspection and comparison |
| Raw | Inspect the hardware encoding directly | Bitfields, modifiers, uncertain slots | Readable intent and convenience | Reverse engineering and validation |
| Structural | See how the shader behaves as a program | CFG, lifetimes, back edges, dominance | Surface prettiness | Compiler-style analysis and research |
A small excerpt of the core model
type InstFields struct {
Top8 uint8
Reg0 uint8
Reg1 uint8
Reg2 uint8
Cond uint8
Mod uint8
// Flat, zero-allocation storage for every form the decoder can populate.
}
type Inst struct {
Raw uint32
Fields InstFields
Form Form
Op Op
}





