chip-png-wavedrom-gen

name	chip-png-wavedrom-gen
description	Use when generating Wavedrom timing diagrams as PNG images. Triggers on '时序图', 'wavedrom', 'timing diagram', '波形图', '时序分析图', 'generate wavedrom'. Compiles Wavedrom JSON to PNG using wavedrom-cli.

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 ''''''''''''''
  

wave 符号速查

符号	含义	用途
p	时钟上升沿	时钟信号
P	时钟下降沿	低有效时钟
n	低电平	低有效信号
0	低电平/无效	默认状态
1	高电平/有效	有效状态
2	数据值	数据传输
3	高阻态	三态总线
x	无关	未关心值
.	保持前值	连续有效
=	数据标签	配合 data 数组
-	空/未画	跳过该区域

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 '.'
name 's1_vld' wave ''
name 's2_vld' wave '.'


name 'arvalid' wave '.....'
name 'araddr'  wave 'x22x.....' data 'A0'
name 'rvalid'  wave '....'
name 'rdata'   wave 'x..x..' 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

异常处理

场景	触发条件	处理动作
JSON 格式错误	.json 语法问题	输出解析错误信息，定位错误位置
wavedrom-cli 不可用	Node.js 或依赖包缺失	暂停，提示 npm install
playwright 无 chromium	浏览器未安装	提示安装 chromium 或配置 CHROME_PATH
wave 符号数量不匹配	data 数组与 wave 中 2 数量不一致	标注不匹配信号，提示修正

检查点

检查前：

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

检查后：

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