# Chip Png Wavedrom Gen

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

- Skill: `zhaixin244-wq/chip-png-wavedrom-gen` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zhaixin244-wq/chip-png-wavedrom-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaixin244-wq/chip-png-wavedrom-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaixin244-wq (https://skillmd.com/u/zhaixin244-wq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhaixin244-wq/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**：
   ```bash
   # 单文件：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. **在文档中引用**：
   ```markdown
   ![描述](wd_xxx.png)
   ```

## Wavedrom JSON 格式规范

### 基本结构
```json
{signal: [
  {name: 'clk',  wave: 'p.......'},
  {name: 'valid', wave: '01..0...'},
  {name: 'data',  wave: 'x222x...', data: ['D0', 'D1', 'D2']},
]}
```

### 信号分组（推荐）
多组并行信号用二维数组，第一项为组名：
```json
{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 符号速查

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

### wave 常用模式

```json
// 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 编号行，便于时序分析：
```json
['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 读延迟
```json
{name: 'req',  wave: '010.....'},
{name: 'rsp',  wave: '0...10..'},
{name: 'data', wave: 'x...22x.', data: ['D0','D1']},
```

#### 多通道交织返回
```json
{name: 'ch0_rsp', wave: '01010...'},
{name: 'ch1_rsp', wave: '0.10.10.'},
{name: 'ch2_rsp', wave: '0..10.10'},
```

#### Back-pressure
```json
{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 标注正确