Chip Png Wavedrom Gen

Chip PNG Wavedrom Generator

任务

为芯片模块生成 Wavedrom 格式的时序图 JSON 源文件，通过 wavedrom-cli + playwright 编译为 PNG。

依赖

• Node.js
• 依赖包：见 requirements.txt（npm install）
• D2 CLI（如需处理 .d2 文件）：见 chip-png-d2-gen/requirements.txt
• 工具路径：chromium 路径通过 CHROME_PATH 环境变量或脚本内默认值配置

执行步骤

1. 编写 JSON 源文件：将 .json 文件写入项目输出目录，命名规则：wd_{描述}.json

2. 生成 PNG：

   # 单文件：wavedrom-cli 生成 SVG，playwright 截图生成 PNG
   npx wavedrom --input <output_dir>/wd_xxx.json > <output_dir>/wd_xxx.svg
   
   # 批量（通过 gen_wavedrom.js，处理所有 wd_*.json + wd_*.d2）
   node .claude/skills/chip-png-wavedrom-gen/gen_wavedrom.js <output_dir>
   

   <output_dir> 为项目中存放图表源文件和输出 PNG 的目录。

3. 在文档中引用：

   ![描述](wd_xxx.png)
   

Wavedrom JSON 格式规范

基本结构

{signal: [
  {name: 'clk',  wave: 'p.......'},
  {name: 'valid', wave: '01..0...'},
  {name: 'data',  wave: 'x222x...', data: ['D0', 'D1', 'D2']},
]}

信号分组（推荐）

多组并行信号用二维数组，第一项为组名：

{signal: [
  ['上游请求',
    {name: 'clk',   wave: 'p.......'},
    {name: 'req',   wave: '010.....'},
    {name: 'data',  wave: 'x22x....', data: ['D0']},
  ],
  ['下游响应',
    {name: 'clk',   wave: 'p.......'},
    {name: 'rsp',   wave: '0..10...'},
  ],
  ['cycle',
    {name: '',      wave: '2222222', data: ['0','1','2','3','4','5','6']},
  ]
]}

wave 符号速查

wave 常用模式

// Valid-Ready 握手
{name: 'valid', wave: '01...0.'},
{name: 'ready', wave: '0.1..0.'},
{name: 'data',  wave: 'x222x..', data: ['D0','D1','D2']},

// 脉冲请求（单周期）
{name: 'req',   wave: '010.....'},

// 多周期等待
{name: 'req',   wave: '010.....'},
{name: 'rsp',   wave: '0...10..'},

// 流水线（多级重叠）
{name: 's0_vld', wave: '01.01.0.'},
{name: 's1_vld', wave: '0.1.01.0'},
{name: 's2_vld', wave: '0..1.01.'},

// 地址-数据分离（读）
{name: 'arvalid', wave: '010......'},
{name: 'araddr',  wave: 'x22x.....', data: ['A0']},
{name: 'rvalid',  wave: '0...10...'},
{name: 'rdata',   wave: 'x...22x..', data: ['D0','D1']},

cycle 标注行（推荐）

在最后一组添加 cycle 编号行，便于时序分析：

['cycle',
  {name: '', wave: '222222222222', data: ['0','1','2','3','4','5','6','7','8','9','10','11']},
]

编写技巧

分组策略

• 按功能域分组：上游请求、下游响应、内部状态、cycle编号
• 每组独立 clk，避免信号跨组混乱
• 3-5 个信号/组最佳，过多拆分

命名规范

• 信号名用 Verilog 风格：req_vld, rsp_data, sram_rd_en
• 组名用中文简述功能：SRAM读请求, SRAM返回 & 输出, 输出(零气泡切换)

数据标注

• {name: 'signal', wave: 'x222x...', data: ['A0', 'D1', 'D2']}
• data 数组对应 wave 中每个 2 的位置
• 地址用 A0/A1，数据用 D0/D1，状态用 IDLE/BUSY

常见时序场景模板

3-cycle SRAM 读延迟

{name: 'req',  wave: '010.....'},
{name: 'rsp',  wave: '0...10..'},
{name: 'data', wave: 'x...22x.', data: ['D0','D1']},

多通道交织返回

{name: 'ch0_rsp', wave: '01010...'},
{name: 'ch1_rsp', wave: '0.10.10.'},
{name: 'ch2_rsp', wave: '0..10.10'},

Back-pressure

{name: 'valid',  wave: '01..1.0.'},
{name: 'ready',  wave: '0.10.10.'},
{name: 'bp',     wave: '0.10....'},

使用示例

示例 1：

• 用户：「为 data_adpt 的 AXI 读通道生成时序图」
• 行为：编写 wd_axi_read.json（arvalid/araddr/rvalid/rdata 信号 + cycle 标注），执行 wavedrom-cli + playwright 生成 PNG

示例 2：

• 用户：「帮我画 buf_mgr 的 Valid-Ready 握手时序」
• 行为：编写 wd_buf_mgr_handshake.json（valid/ready/data 信号 + 握手波形），编译为 PNG

异常处理

检查点

检查前：

• 确认 Node.js 和 wavedrom-cli 可用
• 确认 playwright/chromium 可用
• 确认输出目录存在

检查后：

• 确认 .json 源文件已保存
• 确认 .png 文件已生成且非空
• 确认信号分组和 cycle 标注正确