# edmcman/nvdisasm-re architecture

> Architecture diagram of the GitHub repository edmcman/nvdisasm-re, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edmcman/nvdisasm-re
- Repository: https://github.com/edmcman/nvdisasm-re

## Overview

nvdisasm-re reverse engineers NVIDIA SASS machine descriptions and uses them to build decoding, assembly, instruction semantics, native emulation, and a Ghidra processor. The main workflow is to decode cubin or raw instruction words using architecture descriptions, then inspect, assemble, lift, evaluate, or execute SASS. The graph preserves those distinct capabilities; some Ghidra and machine-description relationships are based on README statements because their implementation was not sampled.

Main entry points: [`src/sass/decode/pydecode.py`](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/pydecode.py) (Reference decoder), [`src/sass/sleigh/gen.py`](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/gen.py) (SLEIGH generator), [`src/sass/decode/ir.py`](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/ir.py) (Decode IR), [`src/sass/semantics/family.py`](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/family.py) (Semantics families)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_descriptions["Machine descriptions"]
  node_md_data["Architecture data"]
  node_md_ir["Decode IR<br/>[ir.py]"]
end

subgraph group_instruction_tools["Instruction tools"]
  node_decoder["Reference decoder<br/>[pydecode.py]"]
  node_cubin["Cubin reader<br/>[cubin.py]"]
  node_assembler["SASS assembler<br/>[instruction.py]"]
end

subgraph group_semantics["Semantics"]
  node_sem_family["Semantics families<br/>[family.py]"]
  node_bitvec["Bitvector IR<br/>[bitvec.py]"]
  node_ordered["Ordered semantics<br/>[ordered.py]"]
  node_lifter["Instruction lifter<br/>[lifter.py]"]
  node_evaluator["Concrete evaluator<br/>[evaluate.py]"]
end

subgraph group_emulation["Native emulation"]
  node_native_codegen["C++ code generation<br/>[codegen.py]"]
  node_native_machine["Native machine<br/>[machine.py]"]
end

subgraph group_ghidra["Ghidra processor"]
  node_sleigh_gen["SLEIGH generator<br/>[gen.py]"]
  node_sleigh_lower["Semantic lowering<br/>[lower.py]"]
  node_sleigh_build["Language builder<br/>[build.py]"]
  node_ghidra_bridge["Ghidra bridge<br/>[ghidra_emulate.py]"]
  node_cubin_loader["Cubin loader"]
  node_kernel_args["Kernel arguments"]
end

node_engineer(("Engineer"))
node_cuda_tools["CUDA tools"]
node_ghidra_app["Ghidra"]

node_engineer -->|"decodes instructions"| node_decoder
node_engineer -->|"assembles SASS"| node_assembler
node_engineer -->|"runs kernels"| node_native_machine
node_engineer -->|"builds processor"| node_sleigh_build
node_md_data -->|"defines classes"| node_md_ir
node_md_ir -->|"drives decoding"| node_decoder
node_cubin -->|"provides words"| node_decoder
node_decoder -->|"supplies instruction IR"| node_assembler
node_md_ir -->|"provides class facts"| node_sem_family
node_sem_family -->|"builds expressions"| node_bitvec
node_sem_family -->|"emits statements"| node_ordered
node_decoder -->|"provides decoded instruction"| node_lifter
node_lifter -->|"produces semantic IR"| node_ordered
node_ordered -->|"evaluates statements"| node_evaluator
node_sleigh_gen -->|"loads decode IR"| node_md_ir
node_sleigh_gen -->|"reuses rendering"| node_decoder
node_sleigh_gen -->|"delegates lowering"| node_sleigh_lower
node_sleigh_build -->|"generates language"| node_sleigh_gen
node_sleigh_build -->|"uses compiler"| node_ghidra_app
node_ghidra_app -->|"loads extension"| node_cubin_loader
node_ghidra_bridge -->|"decodes instructions"| node_decoder
node_ghidra_bridge -.->|"analyzes arguments"| node_kernel_args
node_decoder -->|"provides instruction decode"| node_native_codegen
node_lifter -->|"provides semantics"| node_native_codegen
node_native_codegen -->|"compiles kernels"| node_native_machine
node_native_machine -->|"requires C++ compiler"| node_cuda_tools

click node_md_data "https://github.com/edmcman/nvdisasm-re/tree/main/src/sass/md/data"
click node_md_ir "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/ir.py"
click node_decoder "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/pydecode.py"
click node_cubin "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/cubin.py"
click node_assembler "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/assemble/instruction.py"
click node_sem_family "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/family.py"
click node_bitvec "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/bitvec.py"
click node_ordered "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/ordered.py"
click node_lifter "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/lifter.py"
click node_evaluator "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/evaluate.py"
click node_sleigh_gen "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/gen.py"
click node_sleigh_lower "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/lower.py"
click node_sleigh_build "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/build.py"
click node_ghidra_bridge "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/ghidra_bridge/ghidra_emulate.py"
click node_cubin_loader "https://github.com/edmcman/nvdisasm-re/blob/main/processor/SASS/src/main/java/sass/SassCubinLoader.java"
click node_kernel_args "https://github.com/edmcman/nvdisasm-re/blob/main/processor/SASS/src/main/java/sass/SassKernelArgumentsAnalyzer.java"
click node_native_codegen "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/emulate/codegen.py"
click node_native_machine "https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/emulate/machine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_md_data,node_md_ir toneBlue
class node_decoder,node_cubin,node_assembler toneAmber
class node_sem_family,node_bitvec,node_ordered,node_lifter,node_evaluator toneMint
class node_native_codegen,node_native_machine toneRose
class node_sleigh_gen,node_sleigh_lower,node_sleigh_build,node_ghidra_bridge,node_cubin_loader,node_kernel_args,node_engineer,node_cuda_tools,node_ghidra_app toneIndigo
```

## Components

### Machine descriptions

- [Architecture data](https://github.com/edmcman/nvdisasm-re/tree/main/src/sass/md/data): `src/sass/md/data`
- [Decode IR](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/ir.py): `src/sass/decode/ir.py`

### Instruction tools

- [Reference decoder](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/pydecode.py): `src/sass/decode/pydecode.py`
- [Cubin reader](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/decode/cubin.py): `src/sass/decode/cubin.py`
- [SASS assembler](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/assemble/instruction.py): `src/sass/assemble/instruction.py`

### Semantics

- [Semantics families](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/family.py): `src/sass/semantics/family.py`
- [Bitvector IR](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/bitvec.py): `src/sass/semantics/bitvec.py`
- [Ordered semantics](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/ordered.py): `src/sass/semantics/ordered.py`
- [Instruction lifter](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/lifter.py): `src/sass/semantics/lifter.py`
- [Concrete evaluator](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/semantics/evaluate.py): `src/sass/semantics/evaluate.py`

### Native emulation

- [C++ code generation](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/emulate/codegen.py): `src/sass/emulate/codegen.py`
- [Native machine](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/emulate/machine.py): `src/sass/emulate/machine.py`

### Ghidra processor

- [SLEIGH generator](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/gen.py): `src/sass/sleigh/gen.py`
- [Semantic lowering](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/lower.py): `src/sass/sleigh/lower.py`
- [Language builder](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/sleigh/build.py): `src/sass/sleigh/build.py`
- [Ghidra bridge](https://github.com/edmcman/nvdisasm-re/blob/main/src/sass/ghidra_bridge/ghidra_emulate.py): `src/sass/ghidra_bridge/ghidra_emulate.py`
- [Cubin loader](https://github.com/edmcman/nvdisasm-re/blob/main/processor/SASS/src/main/java/sass/SassCubinLoader.java): `processor/SASS/src/main/java/sass/SassCubinLoader.java`
- [Kernel arguments](https://github.com/edmcman/nvdisasm-re/blob/main/processor/SASS/src/main/java/sass/SassKernelArgumentsAnalyzer.java): `processor/SASS/src/main/java/sass/SassKernelArgumentsAnalyzer.java`

### Other components

- **Engineer**
- **CUDA tools**
- **Ghidra**

## Connections

- Engineer → Reference decoder: decodes instructions (evidence: `README.md`)
- Engineer → SASS assembler: assembles SASS (evidence: `README.md`)
- Engineer → Native machine: runs kernels (evidence: `README.md`)
- Engineer → Language builder: builds processor (evidence: `README.md`)
- Architecture data → Decode IR: defines classes (evidence: `README.md`)
- Decode IR → Reference decoder: drives decoding (evidence: `src/sass/decode/pydecode.py`)
- Cubin reader → Reference decoder: provides words (evidence: `src/sass/decode/pydecode.py`)
- Reference decoder → SASS assembler: supplies instruction IR (evidence: `src/sass/assemble/instruction.py`)
- Decode IR → Semantics families: provides class facts (evidence: `src/sass/semantics/family.py`)
- Semantics families → Bitvector IR: builds expressions (evidence: `src/sass/semantics/family.py`)
- Semantics families → Ordered semantics: emits statements (evidence: `src/sass/semantics/family.py`)
- Reference decoder → Instruction lifter: provides decoded instruction (evidence: `README.md`)
- Instruction lifter → Ordered semantics: produces semantic IR (evidence: `README.md`)
- Ordered semantics → Concrete evaluator: evaluates statements (evidence: `src/sass/semantics/evaluate.py`)
- SLEIGH generator → Decode IR: loads decode IR (evidence: `src/sass/sleigh/gen.py`)
- SLEIGH generator → Reference decoder: reuses rendering (evidence: `src/sass/sleigh/gen.py`)
- SLEIGH generator → Semantic lowering: delegates lowering (evidence: `src/sass/sleigh/gen.py`)
- Language builder → SLEIGH generator: generates language (evidence: `README.md`)
- Language builder → Ghidra: uses compiler (evidence: `README.md`)
- Ghidra → Cubin loader: loads extension (evidence: `README.md`)
- Ghidra bridge → Reference decoder: decodes instructions (evidence: `README.md`)
- Ghidra bridge → Kernel arguments: analyzes arguments
- Reference decoder → C++ code generation: provides instruction decode (evidence: `src/sass/emulate/codegen.py`)
- Instruction lifter → C++ code generation: provides semantics (evidence: `src/sass/emulate/codegen.py`)
- C++ code generation → Native machine: compiles kernels (evidence: `src/sass/emulate/machine.py`)
- Native machine → CUDA tools: requires C++ compiler (evidence: `README.md`)
