Command Line Interface (CLI)

The CLI is the fastest way to use Axion-HDL for quick generation tasks, CI/CD pipelines, and scripting.

Installation

pip install axion-hdl

Basic Usage

axion-hdl -s <source> -o <output> [options]

Quick Start

# Generate all outputs from a YAML file
axion-hdl -s registers.yaml -o ./output --all

# Generate from TOML file
axion-hdl -s registers.toml -o ./output --all

# Generate from VHDL with annotations
axion-hdl -s ./src/my_module.vhd -o ./generated --all

# Generate from SystemVerilog with annotations
axion-hdl -s ./src/my_module.sv -o ./generated --sv

# Start the interactive GUI
axion-hdl -s ./src --gui

---

Command Reference

Source Options

Option	Description
-s, --source PATH	Source file or directory (auto-detects type by extension)
-x, --xml-source PATH	XML source (deprecated, use -s instead)
-c, --config FILE	Load configuration from JSON file

Examples:

# Single file (YAML, TOML, XML, or JSON)
axion-hdl -s controller.yaml -o ./output --all
axion-hdl -s controller.toml -o ./output --all

# Multiple files
axion-hdl -s cpu_regs.yaml -s dma_regs.xml -s spi_regs.toml -o ./output --all

# Entire directory (recursive scan)
axion-hdl -s ./rtl -o ./generated --all

# Mixed files and directories
axion-hdl -s ./rtl -s extra_regs.toml -o ./output --all

Output Options

Option	Description
-o, --output DIR	Output directory (default: ./axion_output)
-e, --exclude PATTERN	Exclude files matching glob pattern

Examples:

# Custom output directory
axion-hdl -s ./src -o ./generated_rtl --all

# Exclude testbenches
axion-hdl -s ./src -e "*_tb.vhd" -o ./output --all

# Multiple exclude patterns
axion-hdl -s ./src -e "*_tb.vhd" -e "test_*" -e "deprecated" -o ./output --all

Generation Flags

Flag	Description
--all	Generate all output types
--vhdl	Generate VHDL register module
--sv, --systemverilog	Generate SystemVerilog register module
--c-header	Generate C header file
--xml	Generate XML register map
--yaml	Generate YAML register map
--json	Generate JSON register map
--doc	Generate Markdown documentation
--doc-format FORMAT	Documentation format: md, html, pdf
--use-axion-types	Use typed t_axi_lite_m2s/t_axi_lite_s2m record ports from axion_common_pkg instead of flat AXI signals (VHDL and SV). Overrides any per-module use_axion_types config value.
--hier FILE	Hierarchy file for centralized base address assignment (YAML, TOML, JSON, or XML). Overrides base_addr in all individual module files. When the same module appears multiple times, the instance field names the output files. Also generates address_map.html.
--python, --py	Generate Python register model file (*_regs.py) for golden model use.

Examples:

# Generate everything
axion-hdl -s regs.yaml -o ./output --all

# Only VHDL and C header
axion-hdl -s regs.yaml -o ./output --vhdl --c-header

# Generate SystemVerilog with Structs
axion-hdl -s regs.yaml -o ./output --sv

# Only documentation in HTML format
axion-hdl -s regs.yaml -o ./docs --doc --doc-format html

# Multiple formats
axion-hdl -s regs.yaml -o ./output --vhdl --c-header --doc --yaml

# Hierarchy: centralized base address assignment
axion-hdl -s ./rtl -o ./output --hier address_map.yaml --all

# Hierarchy: multi-instance (two instances of the same module)
axion-hdl -s ./rtl -o ./output --hier design_hier.toml --sv --c-header

GUI Options

Option	Description
--gui	Start interactive web GUI
--port PORT	GUI server port (default: 5000)

Examples:

# Start GUI with current directory
axion-hdl --gui

# Start GUI with specific source
axion-hdl -s ./rtl --gui

# Start on different port
axion-hdl -s ./rtl --gui --port 8080

Information Options

Option	Description
-v, --version	Show version and exit
-h, --help	Show help message and exit

---

Complete Workflow Examples

1. Single Module Generation

# Input: spi_master.vhd with @axion annotations
# Output: VHDL module, C header, Markdown docs

axion-hdl -s spi_master.vhd -o ./output --vhdl --c-header --doc

Output files:

output/
├── spi_master_axion_reg.vhd    # AXI4-Lite slave module
├── spi_master_regs.h           # C header with macros
└── register_map.md             # Documentation

2. Multi-Module Project

# Process entire RTL directory
axion-hdl -s ./rtl -o ./generated --all -e "*_tb.vhd"

3. SystemVerilog Module

# Input: design.sv with // @axion annotations
# Output: SystemVerilog module, C header, docs
axion-hdl -s design.sv -o ./output --sv --c-header --doc

Output files:

output/
├── design_axion_reg.sv    # AXI4-Lite slave module (SystemVerilog)
├── design_regs.h          # C header with macros
└── register_map.md        # Documentation

# Mix VHDL and SystemVerilog sources, generate both outputs
axion-hdl -s ./rtl -o ./generated --vhdl --sv -e "*_tb.*"

Output files:

generated/
├── module_a_axion_reg.vhd
├── module_a_regs.h
├── module_a_regs.yaml
├── module_b_axion_reg.vhd
├── module_b_regs.h
├── module_b_regs.yaml
├── register_map.md
├── index.html
└── ...

---

CI/CD Integration

Axion-HDL integrates seamlessly with continuous integration pipelines.

GitHub Actions

Create .github/workflows/generate-regs.yml:

name: Generate Register Files

on:
  push:
    paths:
      - 'regs/**'
      - 'rtl/**/*.vhd'
      - 'rtl/**/*.sv'
  pull_request:
    paths:
      - 'regs/**'
      - 'rtl/**/*.vhd'
      - 'rtl/**/*.sv'

jobs:
  generate:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install Axion-HDL
        run: pip install axion-hdl
      
      - name: Generate Register Files
        run: |
          axion-hdl -s ./regs -s ./rtl -o ./generated --all -e "*_tb.vhd"
      
      - name: Upload Generated Files
        uses: actions/upload-artifact@v4
        with:
          name: generated-registers
          path: generated/
      
      - name: Commit Generated Files (optional)
        if: github.ref == 'refs/heads/main'
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add generated/
          git diff --staged --quiet || git commit -m "chore: regenerate register files"
          git push

GitLab CI

Create .gitlab-ci.yml:

stages:
  - generate
  - test

generate-registers:
  stage: generate
  image: python:3.11
  script:
    - pip install axion-hdl
    - axion-hdl -s ./regs -o ./generated --all
  artifacts:
    paths:
      - generated/
    expire_in: 1 week
  only:
    changes:
      - regs/**/*
      - rtl/**/*.vhd

validate-registers:
  stage: test
  image: python:3.11
  script:
    - pip install axion-hdl
    - |
      python3 << 'EOF'
      from axion_hdl import AxionHDL
      from axion_hdl.rule_checker import RuleChecker
      
      axion = AxionHDL()
      axion.add_source("./regs")
      modules = axion.analyze()
      
      checker = RuleChecker()
      results = checker.run_all_checks(modules)
      
      if results["errors"]:
          for e in results["errors"]:
              print(f"ERROR: {e['message']}")
          exit(1)
      print("✓ Validation passed")
      EOF
  only:
    - merge_requests

Makefile Integration

Add to your project’s Makefile:

# Register generation targets
REGS_SRC := ./regs
REGS_OUT := ./generated
AXION := axion-hdl

.PHONY: regs regs-clean regs-check

# Generate all register files
regs:
	$(AXION) -s $(REGS_SRC) -o $(REGS_OUT) --all -e "*_tb.vhd"
	@echo "✓ Register files generated in $(REGS_OUT)"

# Clean generated files
regs-clean:
	rm -rf $(REGS_OUT)
	@echo "✓ Cleaned $(REGS_OUT)"

# Validate without generating
regs-check:
	@python3 -c "\
from axion_hdl import AxionHDL; \
from axion_hdl.rule_checker import RuleChecker; \
a = AxionHDL(); a.add_source('$(REGS_SRC)'); m = a.analyze(); \
r = RuleChecker().run_all_checks(m); \
exit(1) if r['errors'] else print('✓ Validation passed')"

# Watch for changes and regenerate
regs-watch:
	@echo "Watching $(REGS_SRC) for changes..."
	@while true; do \
		inotifywait -qr -e modify $(REGS_SRC) && $(MAKE) regs; \
	done

Usage:

make regs          # Generate all
make regs-clean    # Clean output
make regs-check    # Validate only

Shell Script

Create scripts/generate_regs.sh:

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
OUTPUT_DIR="${PROJECT_DIR}/generated"

echo "=== Axion-HDL Register Generation ==="

# Check if axion-hdl is installed
if ! command -v axion-hdl &> /dev/null; then
    echo "ERROR: axion-hdl not found. Install with: pip install axion-hdl"
    exit 1
fi

# Create output directory
mkdir -p "$OUTPUT_DIR"

# Run generation
echo "Generating from: ${PROJECT_DIR}/regs"
echo "Output to: ${OUTPUT_DIR}"

axion-hdl \
    -s "${PROJECT_DIR}/regs" \
    -s "${PROJECT_DIR}/rtl" \
    -o "$OUTPUT_DIR" \
    --all \
    -e "*_tb.vhd" \
    -e "deprecated"

# Check result
if [ $? -eq 0 ]; then
    echo ""
    echo "✓ Generation successful!"
    echo "Generated files:"
    ls -la "$OUTPUT_DIR"
else
    echo ""
    echo "✗ Generation failed!"
    exit 1
fi

---

Configuration File

Create .axion_conf for project-specific settings:

{
    "src_dirs": ["./rtl"],
    "src_files": ["./top.vhd"],
    "yaml_src_dirs": ["./regs"],
    "exclude_patterns": ["*_tb.vhd", "test_*", "deprecated"],
    "output_dir": "./generated"
}

# Use config file explicitly
axion-hdl --config .axion_conf --all

# Auto-loads .axion_conf if present in current directory
axion-hdl --all

---

Supported File Types

Extension	Format	Description
.vhd, .vhdl	VHDL	Source with -- @axion annotations
.sv, .svh	SystemVerilog	Source with // @axion annotations
.yaml, .yml	YAML	Human-readable register definitions
.json	JSON	Machine-readable register definitions
.xml	XML	IP-XACT style register definitions
.toml	TOML	Human-readable register definitions

---

Exit Codes

Code	Meaning
0	Success
1	Error (invalid input, failed generation, conflicts, or parsing errors)

Note: If any parsing errors are detected during analysis, the generation process will be blocked for safety. You must fix these errors before generating outputs.

---

Tips

1. Use --all for quick generation - generates everything in one command

2. Exclude patterns - great for skipping testbenches and deprecated files

3. Config files - store project-specific settings for consistent generation

4. Combine sources - mix VHDL, SystemVerilog, YAML, TOML, XML, JSON in a single run

5. CI/CD artifacts - upload generated files for downstream jobs

6. Bare annotations - -- @axion (VHDL) or // @axion (SV) with no attributes defaults to RW access and auto-assigned address