axion-hdl

name	axion-hdl
description	当用户想要使用 axion-hdl 从 YAML 或 HDL 注释生成 AXI4-Lite 寄存器接口，或使用 axion-hdl GUI 模式的时候，使用该技能。

Axion 使用指南

前提条件

• Python 3.7+
• GHDL（可选，仅仿真时需要）
• 已激活 axion-hdl 专用的虚拟环境，或当前环境中已安装 axion-hdl
• 可通过 pip list + grep 查看是否已安装，或直接执行 axion -h 测试是否报错

何时使用此技能

• 用户需要生成 AXI4-Lite 寄存器接口
• 用户提供了 YAML / JSON 格式的寄存器定义，或 HDL 代码中包含 @axion 注释
• 用户需要使用 axion-hdl GUI 模式

本指南将带您完成 Axion-HDL 的安装，并帮助您创建第一个寄存器接口。

安装依赖

Axion-HDL 可从 PyPI 获取：

pip install axion-hdl[gui]

快速入门

步骤 1：定义寄存器

您可以在 YAML/TOML 文件中定义寄存器，也可以直接在 VHDL/SystemVerilog 源代码中使用 @axion 注释来定义。

方式 A — YAML 文件 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"

方式 B — TOML 文件 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"

方式 C — SystemVerilog 源代码 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

注意：仅写 // @axion（不带任何属性）也是合法的——默认采用 RW 访问模式，并自动分配地址。

步骤 2：生成输出文件

# 从 YAML/TOML 文件生成
axion-hdl -s led_blinker.yaml -o output --all

# 从 SystemVerilog 源代码生成
axion-hdl -s led_blinker.sv -o output --sv --c-header --doc

步骤 3：查看生成的文件

output/ 目录中将包含以下文件：

文件名	说明
led_blinker_axion_reg.vhd	AXI4-Lite 从机模块（VHDL）
led_blinker_axion_reg.sv	AXI4-Lite 从机模块（SystemVerilog）
led_blinker_regs.h	包含宏定义的 C 头文件
index.html	寄存器文档主页
html/	各模块的文档页面
led_blinker_regs.xml	IP-XACT 格式描述
led_blinker_regs.yaml	YAML 格式寄存器映射
led_blinker_regs.json	JSON 格式寄存器映射

步骤 4：集成到设计

在顶层 VHDL 设计中实例化生成的模块：

led_blinker_regs : entity work.led_blinker_axion_reg
    port map (
        axi_aclk    => clk,
        axi_aresetn => rst_n,
        -- AXI4-Lite 总线信号
        axi_awaddr  => s_axi_awaddr,
        axi_awvalid => s_axi_awvalid,
        -- ... 其他 AXI 信号 ...
        -- 寄存器信号连接
        control     => control_reg,
        led_state   => led_state_sig,
        period_ms   => period_reg
    );

或在 SystemVerilog 中实例化：

led_blinker_axion_reg u_regs (
    .axi_aclk    (clk),
    .axi_aresetn (rst_n),
    // AXI4-Lite 总线信号
    .axi_awaddr  (s_axi_awaddr),
    .axi_awvalid (s_axi_awvalid),
    // ... 其他 AXI 信号 ...
    // 寄存器信号连接
    .control     (control_reg),
    .led_state   (led_state_sig),
    .period_ms   (period_reg)
);

参考文档

如需了解更多用法细节，请参阅 references/ 目录下的文件：

• cli-usage.md — axion-hdl 命令行模式用法
• gui.md — axion-hdl GUI 模式用法
• outputs.md — axion-hdl 输出文件说明