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

10 min read • View on GitHub • More from zboralski

A lone researcher studies a sealed mechanical vault made of interlocking plates while transparent sheets of binary, disassembly, and a magnifying glass sit on the desk. The scene explains that this project treats Apple’s undocumented GPU ISA as something to be inferred from evidence, not guessed.
`agx` turns an opaque GPU into a research object. The point is not just decoding instructions, but proving what the hardware actually encodes.
Key Takeaways

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.

ViewGoalWhat it preservesWhat it hidesBest use case
CanonicalRead the instruction as a semantic actionMnemonic, operands, likely intentLow-level packing, ambiguity, scheduling detailsFast inspection and comparison
RawInspect the hardware encoding directlyBitfields, modifiers, uncertain slotsReadable intent and convenienceReverse engineering and validation
StructuralSee how the shader behaves as a programCFG, lifetimes, back edges, dominanceSurface prettinessCompiler-style analysis and research

The workflow is a chain of evidence. Raw bits become candidate decodes, then renderings, then structure you can analyze like a compiler pass.

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
}