Getting Started

This guide will walk you through installing Axion-HDL and creating your first register interface.

Installation

Axion-HDL is available on PyPI:

pip install axion-hdl

Prerequisites

Python 3.7+
GHDL (Optional, only required for simulations)

Quick Start

Step 1: Define Registers

You can define registers in YAML/TOML files or directly in your VHDL/SystemVerilog source using @axion annotations.

Option A — YAML file led_blinker.yaml:

module: led_blinker
base_addr: "0x0000"
registers:
  - name: control
    addr: "0x00"
    access: RW
    width: 32
    description: "LED control register"

  - name: led_state
    addr: "0x04"
    access: RO
    width: 32
    description: "Current LED state"

  - name: period_ms
    addr: "0x08"
    access: RW
    width: 32
    default: 500
    description: "Blink period in milliseconds"

Option B — TOML file led_blinker.toml:

module = "led_blinker"
base_addr = "0x0000"

[[registers]]
name = "control"
addr = "0x00"
access = "RW"
width = 32
description = "LED control register"

[[registers]]
name = "led_state"
addr = "0x04"
access = "RO"
width = 32
description = "Current LED state"

[[registers]]
name = "period_ms"
addr = "0x08"
access = "RW"
width = 32
default = 500
description = "Blink period in milliseconds"

Option C — SystemVerilog source led_blinker.sv:

module led_blinker (
    input logic clk
);
    logic [31:0] control;   // @axion RW DESC="LED control register"
    logic [31:0] led_state; // @axion RO DESC="Current LED state"
    logic [31:0] period_ms; // @axion RW DEFAULT=500 DESC="Blink period in milliseconds"
endmodule

Bare // @axion (no attributes) is also valid — defaults to RW access and auto-assigned address.

Step 2: Generate Output

# From YAML/TOML
axion-hdl -s led_blinker.yaml -o output --all

# From SystemVerilog source
axion-hdl -s led_blinker.sv -o output --sv --c-header --doc

Step 3: Check Generated Files

The output/ directory will contain:

File	Description
`led_blinker_axion_reg.vhd`	AXI4-Lite slave module (VHDL)
`led_blinker_axion_reg.sv`	AXI4-Lite slave module (SystemVerilog)
`led_blinker_regs.h`	C header with macros
`index.html`	Register documentation (main page)
`html/`	Module documentation pages
`led_blinker_regs.xml`	IP-XACT description
`led_blinker_regs.yaml`	YAML register map
`led_blinker_regs.json`	JSON register map

Step 4: Integrate

Instantiate the generated module in your top-level VHDL:

led_blinker_regs : entity work.led_blinker_axion_reg
    port map (
        axi_aclk    => clk,
        axi_aresetn => rst_n,
        -- AXI4-Lite bus connections
        axi_awaddr  => s_axi_awaddr,
        axi_awvalid => s_axi_awvalid,
        -- ... other AXI signals ...
        -- Register signals
        control     => control_reg,
        led_state   => led_state_sig,
        period_ms   => period_reg
    );

Or instantiate the SystemVerilog module:

led_blinker_axion_reg u_regs (
    .axi_aclk    (clk),
    .axi_aresetn (rst_n),
    // AXI4-Lite bus connections
    .axi_awaddr  (s_axi_awaddr),
    .axi_awvalid (s_axi_awvalid),
    // ... other AXI signals ...
    // Register signals
    .control     (control_reg),
    .led_state   (led_state_sig),
    .period_ms   (period_reg)
);

Next Steps

Data Formats - Learn about all input formats
CLI Usage - Master the command-line
GUI - Interactive web-based register management