Skip to content

About

[BETA] CLI utility for reading, dumping, comparing and analyzing AMD Polaris (RX 400/500) VBIOS ROMs. Parses real AtomBIOS structures - and outputs plain text, JSON, CSV or an interactive TUI.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

72 Commits

Folders and files

Repository files navigation

Polaris VBIOS CLI

Project Status CI MSRV GitHub Tag GitHub Downloads (all assets) License

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.

Overview TUI

Documentation

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 warning

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 patch in place - always write a copy with --out and 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.

Build

Requires Rust 1.88+:

cargo build --release
# binary at target/release/polaris-vbios

Dependencies: anyhow, serde/serde_json, crossterm, clap, csv, base64, strip-ansi-escapes.

Quick start

# 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

Commands

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

Global options

Flag Description
-h, --help Print help
-V, --version Print version
--list-sections List available section keys and exit

Exit codes

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.

Architecture

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::color stays in core: Palette serves the CLI, the render/compare path and the TUI (which parses its ANSI text via ansi-to-tui), while the pure string helpers (pad, truncate, fit) are terminal-agnostic.

About

[BETA] CLI utility for reading, dumping, comparing and analyzing AMD Polaris (RX 400/500) VBIOS ROMs. Parses real AtomBIOS structures - and outputs plain text, JSON, CSV or an interactive TUI.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages