Reader, dumper and comparator for AMD Polaris VBIOS (RX 4xx / RX 5xx - Polaris10/Polaris11/Polaris20/Polaris21) in Rust. Reads the ROM directly through the real AtomBIOS structures and displays everything in the terminal - plain text (CLI), JSON, CSV or an interactive TUI.
The project was developed and verified against a collection of 339 real Polaris BIOS images (39 curated reference ROMs spanning every Polaris family - RX 460 through RX 590 - plus an extended set of 300 ROMs from the same sources). Every command, section and parser is exercised on that whole set during development.
None of this means every ROM in the wild will parse perfectly: vendor VBIOS images are inconsistent, some fields are heuristic, and edge cases exist outside any sampled set. Nothing reads or writes a GPU - this is a file tool only.
Status: maintenance / refactoring. The project is under maintenance and active refactoring. References, features and documentation may be outdated, delayed, out of context or disconnected from each other, since work-in-progress changes are mixed with released versions. This is a deliberate decision to keep the project easy to understand, simple, and free of dead code.
Per-topic docs live in docs/:
| File | Covers |
|---|---|
| docs/dump/README.md | dump - sections, text/JSON/CSV output |
| docs/compare/README.md | compare, compare-all, diff-disasm, scriptable verdicts |
| docs/patch/README.md | patch - guards, --timing, fan curve/TDC/TjMax, JSON profiles + batch --glob, identity/VRAM editing, --set-message |
| docs/suggest-oc/README.md | suggest-oc - guardrailed OC plan generator + JSON profiles |
| docs/baseline/README.md | baseline - per-model PowerPlay statistics over a ROM set |
| docs/similar/README.md | similar - rank ROMs by closeness to a target |
| docs/transplant/README.md | transplant - PCI ROM image swapping between VBIOS files |
| docs/identify/README.md | identify - one-line summary per ROM |
| docs/extract/README.md | extract - dump PCI ROM images to files |
| docs/disasm/README.md | disasm - ATOM command table disassembly |
| docs/tui/README.md | Interactive tui mode + edit wizard (e) + keybindings |
| docs/reference/README.md | check/convert/decode-strap, --reg-names, validation, limitations |
| docs/utility/README.md | list-sections/completions/man/help - utility commands |
| docs/development/README.md | Parsing sources, code structure, license, credits |
patch edits a ROM copy with validated, checksummed changes, but BIOS
modding is inherently risky. Use at your own risk: a badly applied
patch, an over-aggressive clock/voltage, or a wrong checksum can
brick a card, void its warranty and, at worst, corrupt the flash chip.
You are solely responsible for what you flash.
- Never
patchin place - always write a copy with--outand keep a flash-backup of the stock ROM. - Test modified images on a cheap secondary card first, never on the only card you own.
- A tool cannot foresee every oddity; if in doubt, flash the verified stock image and lose nothing.
Requires Rust 1.88+:
cargo build --release
# binary at target/release/polaris-vbiosDependencies: anyhow, serde/serde_json, crossterm, clap, csv,
base64, strip-ansi-escapes.
# Identify all ROMs in a directory
polaris-vbios identify ~/GPU/*.rom
# Full dump of one ROM
polaris-vbios dump ~/GPU/xfx-rx570_original.rom
# Validate a ROM (scriptable exit codes)
polaris-vbios check ~/GPU/xfx-rx570_original.rom
# Compare two ROMs side by side
polaris-vbios compare ~/GPU/XFX.RX480.4096.rom ~/GPU/XFX.RX580.8192.rom
# Interactive TUI (browse + edit wizard with `e`)
polaris-vbios tui ~/GPU/RX570_original.rom ~/GPU/Gigabyte.RX580.8192.rom
# Guardrailed OC plan, applied via patch
polaris-vbios suggest-oc ~/GPU/RX570_original.rom --target balanced --out oc.json
polaris-vbios patch ~/GPU/RX570_original.rom --out RX570_oc.rom --apply oc.json| Command | Description |
|---|---|
dump |
Read one or more ROMs - full detail, JSON or CSV |
compare |
Side-by-side comparison of two ROMs (exit 1 when they differ) |
compare-all |
Matrix comparison of 3+ ROMs (exit 1 when they differ) |
identify |
One-line summary per ROM (or --json) |
patch |
Safe ROM editing (straps, timings, PowerPlay, hex) + checksum fix; JSON profiles (--apply/--dump-profile) and batch --glob/--out-dir |
suggest-oc |
Guardrailed OC plan generator - JSON profile ready for patch --apply, never writes a ROM |
baseline |
Per-model PowerPlay statistics over a ROM set - median/min/max per device ID |
similar |
Rank ROMs by how close they are to a target (identity + PowerPlay numbers) |
transplant |
Transplant PCI ROM images (Legacy/EFI) between VBIOS files |
check |
Run every validation rule, scriptable exit codes (0/1/2); --json manifest with per-PCI-image checksums, --csv matrix |
convert |
Convert a memory timing between cycles and nanoseconds |
decode-strap |
Decode a pasted memory strap register set (no ROM needed) |
extract |
Extract PCI ROM images (Legacy/EFI) to files or JSON metadata |
diff-disasm |
Diff of the ATOM bytecode disassembly of two ROMs |
disasm |
Disassemble ATOM command table bytecode |
tui |
Interactive terminal UI |
list-sections |
List all available section keys |
completions |
Print a shell completion script (bash, elvish, fish, powershell, zsh) |
man |
Print a roff man page |
help / -h |
Show help for any command |
| Flag | Description |
|---|---|
-h, --help |
Print help |
-V, --version |
Print version |
--list-sections |
List available section keys and exit |
| Code | Meaning |
|---|---|
| 0 | Success - no validation warnings |
| 1 | Error (could not read/generate something), or check found findings, or compare/compare-all ROMs differ |
| 2 | Success but validation warnings found on at least one ROM (check uses it when a ROM fails to parse) |
check- scripting contract: 0 clean, 1 findings reported, 2 could not parse a ROM.compare/compare-all- exit 1 exactly when the ROMs differ (text mode: the report's≠marker; JSON mode: structural comparison). If the ROMs are identical but still carry validation warnings, the exit is 2 like every other command.
Workspace with three crates plus a thin facade binary. The layering is
enforced by the compiler: core has no terminal frontend
dependencies, so nothing that wants crossterm/ratatui/clap can
creep into the domain code.
| Crate | Responsibility |
|---|---|
core (polaris-core) |
Domain model and parsing of the VBIOS: rom (reading, types, disassembly, patch), compare (pair-wise and batch matrix), render (terminal-agnostic text), util |
cli (polaris-cli) |
Command-line parsing (clap), help/man/completions, and subcommand orchestration; owns the dispatch (including the tui subcommand, which delegates to polaris-tui) |
tui (polaris-tui) |
Interactive terminal frontend (browse view + edit wizard), rendered from core data |
| root | src/main.rs facade binary that calls polaris_cli::run(); integration tests in tests/ |
The binary entry point only delegates: parsing and dispatch live in
polaris_cli. See the README.md in each crate/module directory for
details.
The TUI renders through ratatui.
polaris_core::render::colorstays incore:Paletteserves the CLI, therender/comparepath and the TUI (which parses its ANSI text viaansi-to-tui), while the pure string helpers (pad,truncate,fit) are terminal-agnostic.

