# dxur/vp-ate architecture

> Architecture diagram of the GitHub repository dxur/vp-ate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dxur/vp-ate
- Repository: https://github.com/dxur/vp-ate

## Overview

This repository combines a Rust VP8 keyframe decoder/debug executable with a SystemVerilog VP8-decoding design. The main Rust workflow reads an IVF file, selects its first keyframe, parses frame and macroblock data, reconstructs pixels, and emits a JSON debug record. The Rust decoder has distinct container, bitstream, frame, macroblock, prediction, and reconstruction stages. RTL paths indicate corresponding hardware functions, but the sampled source does not establish their wiring; those relationships are therefore omitted. The README is empty, and unsampled RTL implementation details are not inferred.

Main entry points: [`src/main.rs`](https://github.com/dxur/vp-ate/blob/main/src/main.rs) (Debug executable), [`src/decode.rs`](https://github.com/dxur/vp-ate/blob/main/src/decode.rs) (Pixel reconstruction), [`src/macroblock.rs`](https://github.com/dxur/vp-ate/blob/main/src/macroblock.rs) (Macroblock decode), [`src/frame.rs`](https://github.com/dxur/vp-ate/blob/main/src/frame.rs) (Frame parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rust_io["Rust Input Output"]
  node_ivf["IVF parser<br/>[container.rs]"]
  node_entry["Debug executable<br/>[main.rs]"]
end

subgraph group_rust_decode["Rust VP8 Decode"]
  node_frame["Frame parser<br/>[frame.rs]"]
  node_bits["Bit decoders<br/>[bit.rs]"]
  node_macroblocks["Macroblock decode<br/>[macroblock.rs]"]
  node_reconstruct["Pixel reconstruction<br/>[decode.rs]"]
  node_prediction["Intra prediction<br/>[prediction.rs]"]
  node_tables["Codec tables<br/>[tables.rs]"]
  node_transforms["Transforms and color<br/>[util.rs]"]
end

subgraph group_rtl_decode["RTL Decode"]
  node_rtl_top["RTL top<br/>[vp_ate.sv]"]
  node_rtl_frame["Frame buffer<br/>[frame_buffer.sv]"]
  node_rtl_syntax["Syntax parsing<br/>[frame.sv]"]
  node_rtl_macroblock["Macroblock syntax<br/>[macroblock.sv]"]
  node_rtl_tokens["Token decoding<br/>[token_decoder.sv]"]
  node_rtl_residue["Residue decoding<br/>[residue_decoder.sv]"]
  node_rtl_bool["Boolean decoding<br/>[bool_decoder.sv]"]
  node_rtl_predict["Prediction<br/>[predictor.sv]"]
  node_rtl_idct["Inverse transform<br/>[idct4x4.sv]"]
  node_rtl_ring["Ring buffer<br/>[ring_buffer.sv]"]
end

node_user(("File provider"))

node_user -->|"supplies IVF path"| node_entry
node_entry -->|"parses container"| node_ivf
node_entry -->|"parses keyframe"| node_frame
node_entry -->|"decodes frame"| node_reconstruct
node_entry -->|"prints JSON"| node_user
node_frame -->|"reads bitstream"| node_bits
node_frame -->|"parses macroblocks"| node_macroblocks
node_macroblocks -->|"uses probabilities"| node_tables
node_macroblocks -->|"decodes tokens"| node_bits
node_reconstruct -->|"uses parsed blocks"| node_macroblocks
node_reconstruct -->|"predicts pixels"| node_prediction
node_reconstruct -->|"reconstructs pixels"| node_transforms

click node_ivf "https://github.com/dxur/vp-ate/blob/main/src/container.rs"
click node_entry "https://github.com/dxur/vp-ate/blob/main/src/main.rs"
click node_frame "https://github.com/dxur/vp-ate/blob/main/src/frame.rs"
click node_bits "https://github.com/dxur/vp-ate/blob/main/src/bit.rs"
click node_macroblocks "https://github.com/dxur/vp-ate/blob/main/src/macroblock.rs"
click node_reconstruct "https://github.com/dxur/vp-ate/blob/main/src/decode.rs"
click node_prediction "https://github.com/dxur/vp-ate/blob/main/src/prediction.rs"
click node_tables "https://github.com/dxur/vp-ate/blob/main/src/tables.rs"
click node_transforms "https://github.com/dxur/vp-ate/blob/main/src/util.rs"
click node_rtl_top "https://github.com/dxur/vp-ate/blob/main/rtl/vp_ate.sv"
click node_rtl_frame "https://github.com/dxur/vp-ate/blob/main/rtl/frame_buffer.sv"
click node_rtl_syntax "https://github.com/dxur/vp-ate/blob/main/rtl/syntax/frame.sv"
click node_rtl_macroblock "https://github.com/dxur/vp-ate/blob/main/rtl/syntax/macroblock.sv"
click node_rtl_tokens "https://github.com/dxur/vp-ate/blob/main/rtl/token_decoder.sv"
click node_rtl_residue "https://github.com/dxur/vp-ate/blob/main/rtl/residue_decoder.sv"
click node_rtl_bool "https://github.com/dxur/vp-ate/blob/main/rtl/bool_decoder.sv"
click node_rtl_predict "https://github.com/dxur/vp-ate/blob/main/rtl/predictor.sv"
click node_rtl_idct "https://github.com/dxur/vp-ate/blob/main/rtl/idct4x4.sv"
click node_rtl_ring "https://github.com/dxur/vp-ate/blob/main/rtl/ring_buffer.sv"

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_ivf,node_entry toneBlue
class node_frame,node_bits,node_macroblocks,node_reconstruct,node_prediction,node_tables,node_transforms toneAmber
class node_rtl_top,node_rtl_frame,node_rtl_syntax,node_rtl_macroblock,node_rtl_tokens,node_rtl_residue,node_rtl_bool,node_rtl_predict,node_rtl_idct,node_rtl_ring toneMint
class node_user toneIndigo
```

## Components

### Rust Input Output

- [IVF parser](https://github.com/dxur/vp-ate/blob/main/src/container.rs): `src/container.rs`
- [Debug executable](https://github.com/dxur/vp-ate/blob/main/src/main.rs): `src/main.rs`

### Rust VP8 Decode

- [Frame parser](https://github.com/dxur/vp-ate/blob/main/src/frame.rs): `src/frame.rs`
- [Bit decoders](https://github.com/dxur/vp-ate/blob/main/src/bit.rs): `src/bit.rs`
- [Macroblock decode](https://github.com/dxur/vp-ate/blob/main/src/macroblock.rs): `src/macroblock.rs`
- [Pixel reconstruction](https://github.com/dxur/vp-ate/blob/main/src/decode.rs): `src/decode.rs`
- [Intra prediction](https://github.com/dxur/vp-ate/blob/main/src/prediction.rs): `src/prediction.rs`
- [Codec tables](https://github.com/dxur/vp-ate/blob/main/src/tables.rs): `src/tables.rs`
- [Transforms and color](https://github.com/dxur/vp-ate/blob/main/src/util.rs): `src/util.rs`

### RTL Decode

- [RTL top](https://github.com/dxur/vp-ate/blob/main/rtl/vp_ate.sv): `rtl/vp_ate.sv`
- [Frame buffer](https://github.com/dxur/vp-ate/blob/main/rtl/frame_buffer.sv): `rtl/frame_buffer.sv`
- [Syntax parsing](https://github.com/dxur/vp-ate/blob/main/rtl/syntax/frame.sv): `rtl/syntax/frame.sv`
- [Macroblock syntax](https://github.com/dxur/vp-ate/blob/main/rtl/syntax/macroblock.sv): `rtl/syntax/macroblock.sv`
- [Token decoding](https://github.com/dxur/vp-ate/blob/main/rtl/token_decoder.sv): `rtl/token_decoder.sv`
- [Residue decoding](https://github.com/dxur/vp-ate/blob/main/rtl/residue_decoder.sv): `rtl/residue_decoder.sv`
- [Boolean decoding](https://github.com/dxur/vp-ate/blob/main/rtl/bool_decoder.sv): `rtl/bool_decoder.sv`
- [Prediction](https://github.com/dxur/vp-ate/blob/main/rtl/predictor.sv): `rtl/predictor.sv`
- [Inverse transform](https://github.com/dxur/vp-ate/blob/main/rtl/idct4x4.sv): `rtl/idct4x4.sv`
- [Ring buffer](https://github.com/dxur/vp-ate/blob/main/rtl/ring_buffer.sv): `rtl/ring_buffer.sv`

### Other components

- **File provider**

## Connections

- File provider → Debug executable: supplies IVF path
- Debug executable → IVF parser: parses container
- Debug executable → Frame parser: parses keyframe
- Debug executable → Pixel reconstruction: decodes frame
- Debug executable → File provider: prints JSON
- Frame parser → Bit decoders: reads bitstream
- Frame parser → Macroblock decode: parses macroblocks
- Macroblock decode → Codec tables: uses probabilities
- Macroblock decode → Bit decoders: decodes tokens
- Pixel reconstruction → Macroblock decode: uses parsed blocks
- Pixel reconstruction → Intra prediction: predicts pixels
- Pixel reconstruction → Transforms and color: reconstructs pixels