Interactive GUI

Axion-HDL includes a web-based graphical user interface for managing your register maps visually. The GUI provides a complete workflow for viewing, editing, validating, and generating register interfaces.

Installation

The GUI requires Flask. Install with GUI support:

pip install axion-hdl[gui]

Or install Flask separately:

pip install flask>=2.0

Starting the GUI

Basic Launch

axion-hdl --gui

This starts a local web server at http://127.0.0.1:5000 and opens your default browser.

With Source Files

axion-hdl -s ./rtl --gui

Pre-loads source files before starting the GUI.

Custom Port

axion-hdl -s ./rtl --gui --port 8080

Use a different port (useful when 5000 is occupied).

Dashboard

The main dashboard (/) provides an overview of all parsed modules.

Statistics Cards

Card	Description
Modules	Total number of parsed modules
Registers	Total register count across all modules
CDC Enabled	Number of modules with CDC synchronizers
Source Files	Number of input files loaded

Module Cards

Each module is displayed as a card showing:

Module Name - Click to open editor
Base Address - Hex address (e.g., 0x1000)
Register Count - Number of registers
Source File - Input file name
CDC Badge - Shown if CDC is enabled
Register Preview - First 5 registers listed

Empty State

When no modules are loaded, the dashboard shows:

Instructions for adding sources
Link to configuration page

Module Editor

The editor page (/module/<name>) allows full editing of module properties and registers.

Module Properties

Property	Description
Base Address	Module base address (hex input)
CDC Enable	Toggle for clock domain crossing
CDC Stages	Number of sync stages (2-5), visible when CDC enabled

Register Table

Interactive table with columns:

Column	Description	Editable
Name	Register/signal name	Yes
Width	Bit width (1-1024)	Yes
Access	RO, WO, or RW (color-coded dropdown)	Yes
Default	Reset value (hex format)	Yes
Description	Documentation text	Yes
Address	Calculated address	No (auto)
R_STROBE	Read strobe checkbox	Yes
W_STROBE	Write strobe checkbox	Yes
Actions	Edit, Duplicate, Delete buttons	-

Register Actions

Button	Action
Add Register	Add new blank register row
Duplicate	Copy selected register
Delete	Remove register (with confirmation)
Review & Save	Open diff view before saving

Validation

Invalid inputs show visual error indication:

Empty register names
Invalid width values
Malformed hex addresses

Diff & Review

Before saving changes, the diff page (/diff/<module>) shows:

Views

View	Description
Unified	Single view with additions (green) and deletions (red)
Side-by-Side	Original and modified versions side-by-side

Toggle between views using the view toggle button.

Actions

Button	Action
Confirm & Save	Apply changes to source file
Cancel	Return to editor without saving

Color Coding

Color	Meaning
Green	Added lines
Red	Deleted lines
Default	Unchanged context

Output Generation

The generate page (/generate) allows batch output generation.

Output Directory

Text input showing current output path
Default: ./axion_output
Browse button for folder selection (where supported)

Format Toggles

All formats are enabled by default:

Toggle	Output
VHDL Modules	`_axion_reg.vhd` files
C Headers	`_regs.h` files
Markdown Docs	`register_map.md`
HTML Docs	HTML pages with styling
XML Map	`_regs.xml` files
YAML Map	`_regs.yaml` files
JSON Map	`_regs.json` files

Generation Process

Click Generate Files
Watch the Activity Log for progress
Status Badge shows: Idle → Running → Success/Error
Generated files appear in output directory

Activity Log

Real-time log showing:

Files being generated
Success/error messages
File paths and sizes

Rule Check

The rule check page (/rule-check) validates your register definitions.

Running Checks

Click Run Rule Check to validate all modules.

Check Categories

Category	Description
Address Overlap	Detects overlapping module address ranges
Address Alignment	Warns on non-4-byte aligned addresses
Naming Convention	Validates VHDL identifier rules
Reserved Keywords	Detects VHDL reserved word usage
Duplicate Names	Finds duplicate register names within modules
Duplicate Modules	Detects multiple modules with same name
Default Values	Validates default values fit register width
Format Issues	Reports YAML/JSON/XML syntax problems

Results Display

Severity	Color	Description
Error	Red	Must fix before generation
Warning	Yellow	Should review but may be acceptable
Pass	Green	All checks passed

Summary

Shows total counts:

Number of errors
Number of warnings
Pass/fail indicator

Configuration

The configuration page (/config) manages sources and settings.

Source Management

Action	Description
Add Directory	Scan directory recursively for source files
Add File	Add individual source file
Remove	Remove source from list

Exclude Patterns

Configure glob patterns to exclude files:

*_tb.vhd - Testbenches
*_sim.vhd - Simulation files
generated/* - Generated output

Settings

Setting	Description
Output Directory	Default generation path
Auto-reload	Automatically refresh on file changes

Apply Changes

Click Apply & Re-analyze to:

Re-scan source directories
Parse all source files
Update module list
Return to dashboard

Configuration File (`.axion_conf`)

The GUI can save/load configuration from .axion_conf in your project root.

File Format (JSON)

{
  "sources": [
    "./rtl",
    "./ip/registers.yaml"
  ],
  "excludes": [
    "*_tb.vhd",
    "*_sim.vhd"
  ],
  "output_dir": "./output"
}

Behavior

Auto-loaded on GUI startup if present
Saved when configuration is modified
Add to .gitignore for local-only settings

Navigation

Breadcrumbs

Editor pages show breadcrumbs for navigation:

Dashboard > Module Name

Keyboard Shortcuts

Shortcut	Action
`Ctrl+S`	Save changes (in editor)
`Escape`	Cancel current action

Unsaved Changes

The GUI tracks unsaved changes and provides warnings:

Scenario	Behavior
Navigate away	Confirmation dialog
Close browser	`beforeunload` warning
Return from diff	Changes preserved
After save	Indicator clears

Visual indicator appears in navbar when unsaved changes exist.

Troubleshooting

Flask Not Found

Error: Flask is required for GUI mode. Install with: pip install flask

Solution: Install Flask: pip install flask>=2.0

Port Already in Use

Error: Address already in use

Solution: Use different port: axion-hdl --gui --port 8080

Browser Doesn’t Open

Solution: Manually navigate to http://127.0.0.1:5000

Changes Not Saving

Possible causes:

File permissions
File in use by another process
Invalid VHDL syntax after modification

Check the activity log for error messages.

File Modification Behavior

The GUI modifies source files differently based on format:

Format	Behavior
YAML	Preserves comments and structure
JSON	Preserves structure, updates only changed fields
XML	Preserves comments and attributes
TOML	Preserves comments and structure
VHDL	Minimal edits, only changed signals updated
SystemVerilog	Minimal edits, only changed signals updated

Note

VHDL and SystemVerilog modification is currently experimental and mainly supports appending new signals. Renaming existing registers is restricted.

Link	Page
Axion-HDL GUI	Dashboard (home)
Modules	Dashboard
Rule Check	Validation page
Generate	Output generation
Config	Configuration settings