skills-win/simulink_rtl_dev/SKILL.md

---
name: simulink_rtl_dev
description: >
  Simulink→RTL 的设计规矩与闸门:凡是要生成 RTL 的子系统,它及其所有下级模块**必须用能直接
  生成 RTL 的 Simulink 模块搭建,不允许用嵌入式 m 语言(MATLAB Function)实现**;确实非用 m 代码
  不可的,必须**指定具体的 Xilinx IP 来替代,并通过仿真确认 cycle-true**,再登记豁免。提供审计脚本
  (audit_hdl_blocks.m 盘点 RTL 子树里的 m 代码块)、豁免闸门(check_exemptions.py)、原生模块查库
  (hdl_block_search.m)、HDL 兼容性检查(check_hdl_support.m)与 m 代码→原生模块对照表。
  触发词:simulink 设计规范、要生成RTL的模块、MATLAB Function 能不能用、嵌入式m语言、HDL 子系统审计、
  m代码豁免、cycle-true 豁免、hdl_block_search、audit_hdl_blocks、makehdl 前检查、新建 Simulink 模块。
  适用于任何 Simulink→RTL 工程。IP 替换与 cycle-true 对比由 rtl-ip-replace skill 执行。
---

# simulink_rtl_dev — 要生成 RTL 的 Simulink 设计规矩

> 系统级 skill,适用于任何 Simulink→RTL 工程。
> 本文中的模型名、子系统名一律是**占位示例**;各工程的具体规格、豁免登记与实测基线,
> 放在该工程自己的任务书与 Notes 下,不写进本 skill。

## 〇、本 skill 的安装位置

脚本位于:

```
~/.claude/skills/simulink_rtl_dev/scripts/
```

Windows 上即 `%USERPROFILE%\.claude\skills\simulink_rtl_dev\scripts\`。
下文所有 `addpath` 与 `python` 调用都按此路径给出。

## 一、两条铁律

1. **在 Simulink 设计中,如果明确指定某个模块是要生成 RTL 的,那么这个模块及下属的所有子模块,
   原则上都不允许使用嵌入式 m 语言的模块来实现,必须使用可以直接生成 RTL 的 Simulink 模块来搭建。**
2. **如果一定要使用嵌入式 m 语言来实现的模块,那么必须指定明确的 Xilinx 的 IP 模块来替代,
   并且在替换过程中一定要通过仿真来确认 cycle true。**

推论(本 skill 的执行口径):

- 铁律 1 的判定对象是**"要生成 RTL 的子系统"整棵子树**——`makehdl` 的目标以及它下面的一切,
  与之无关的仿真件(信道、PA 模型、激励源)不受此规矩约束。
- 铁律 2 的"指定 Xilinx IP"不是口头指定:必须落到工程的豁免登记文件
  (建议 `Notes/<model>_mcode_exemptions.json`),写明**哪个 IP**、**覆盖范围**、
  **cycle-true 证据文件**(`rtl-ip-replace` 的 `cmp_result.txt`,首行须为 PASS)、批准人与日期。
  没有证据的豁免 = 违规。
- 违规不是"警告",是**闸门**:`check_exemptions.py` 返回非 0 时不得 `makehdl`、不得进综合。

## 二、先确定"要生成 RTL 的子树"

按优先级:

1. 用户/任务书明确指定;
2. 工程脚本里的 `makehdl` 调用 —— `grep -rn "makehdl" matlab/**/*.m`
   (形如 `makehdl('<model>/<HDL 顶层>','TargetLanguage','Verilog')`);
3. 模型参数 `hdlget_param(model,'HDLSubsystem')`;
4. 命名约定 `*_HDL` 子系统。

**不要**默认整个模型都是 RTL 目标。信道模型、功放模型、载波/延迟注入、激励源这类**纯仿真件**
天生允许用 m 代码,把它们算进审计范围只会制造假违规。
接入本 skill 时,先在工程任务书里把"RTL 子树"与"纯仿真件"两份清单写清楚。

## 三、流程 A:新建 / 修改一个要生成 RTL 的模块(默认路径)

1. **先查库,再动手**(MATLAB 里):
   ```matlab
   addpath(fullfile(getenv('USERPROFILE'),'.claude','skills','simulink_rtl_dev','scripts'));
   hdl_block_search('lms')        % 关键字搜 HDL Coder + DSP HDL + Wireless/Vision HDL 库
   ```
   查到就必须用库里的模块;查不到再看 `reference/block_substitutions.md` 能不能用基础模块拼。
   **拼得出来就不许写 MATLAB Function。**
2. 搭好后跑 HDL 兼容性检查:
   ```matlab
   check_hdl_support('<model>/<HDL 顶层>', 'Out', 'hdl_support.txt')
   ```
3. 跑本 skill 的政策审计 + 闸门(见 §五)。
4. 功能仿真复验(收敛/MER 等系统指标不劣化)→ `makehdl` → 交给 **rtl-ip-replace** 做 IP 化与
   cycle-true 对比 → 进综合。

## 四、流程 B:确实非 m 代码不可(铁律 2 的唯一合法出口)

1. 写清**为什么原生模块搭不出来**(算法结构/时序/资源,不接受"太麻烦");
2. **指定具体 Xilinx IP**(名字 + 版本 + 覆盖范围),而不是"以后再换";
3. 用 **rtl-ip-replace** skill 完成替换,并跑双 DUT 逐拍对比,拿到 `cmp/cmp_result.txt` 首行 PASS;
4. 把上述内容登记进工程的豁免文件
   (格式见 `scripts/exemptions.example.json`,字段缺一不可);
5. 重跑闸门,必须显示 `[EXEMPT]` 且 `GATE: PASS`。

> 位级逐拍等价确实做不到时(典型:CORDIC 内部舍入),按 rtl-ip-replace 的**消费点契约**放宽,
> 但差异幅度与性能复验结论必须写进 Result 文档,并在豁免条目的 `evidence_kind` 里注明。

## 五、审计与闸门(每次改完模型、`makehdl` 之前跑)

MATLAB 侧(经 matlab MCP 运行):
```matlab
addpath(fullfile(getenv('USERPROFILE'),'.claude','skills','simulink_rtl_dev','scripts'));
audit_hdl_blocks('<model>/<HDL 顶层>', ...
    'Exemptions','Notes/<model>_mcode_exemptions.json', ...
    'Out','Notes/<model>_hdl_audit.json');
```

Shell 侧(闸门,退出码即结论):
```
python "%USERPROFILE%\.claude\skills\simulink_rtl_dev\scripts\check_exemptions.py" ^
       Notes\<model>_hdl_audit.json Notes\<model>_mcode_exemptions.json
```

审计如何分级:

| 级别 | 命中的东西 | 处理 |
|---|---|---|
| `VIOLATION` | MATLAB Function、Truth Table、MATLAB System、S-Function、`Fcn` | 必须改成原生模块,或走流程 B 豁免 |
| `EXEMPT` | 已登记且证据齐全的 m 代码块 | 放行(闸门仍会核对证据文件首行是否 PASS) |
| `WARN` | Stateflow Chart / State Transition Table | 允许,但**只能做控制**,不许放数据通路算术 |

审计顺带给出迁移所需信息:脚本行数、是否有 `persistent`、是否有循环、输入输出端口数,
以及按关键字给出的**原生模块建议**(sin/cos→NCO、atan2→Complex to Magnitude-Angle、
persistent 数组→RAM/Tapped Delay 等)。

MATLAB Function 块内部那个 ` SFunction ` 子块是实现细节,审计会自动折叠,不会重复报。

## 六、新工程接入本 skill

1. 在工程任务书里写明**"RTL 子树"清单**与**"纯仿真件"清单**(§二);
2. 跑一次全量审计,把结果作为**基线**记进工程 Notes——**如实记录,不要粉饰**:
   历史欠账(早于本规矩写成的 m 代码块)照实列出,标明闸门当前是 BLOCKED 还是 PASS;
3. 对每个已有违规块,给出**原生模块出路**(查 `hdl_block_search` 与 `block_substitutions.md`)
   与**迁移优先级**——有现成库块的先换(如 LMS Filter、Farrow Rate Converter),
   最大最复杂的建议拆成几个子系统分批换;
4. 从此**新代码一律按铁律 1 办**,不许再往违规块里追加 m 代码;
5. 已完成的局部 IP 化可作为**部分豁免**依据,但 `ip_scope` 必须写清
   "IP 只覆盖这几处,其余 m 代码仍是欠账",不得整块标 PASS。

不在当前 `makehdl` 目标里的 m 代码块(如仅用于仿真的源),暂不受闸门约束;
哪天要给它生成 RTL,先跑一次本 skill 的审计。

## 七、脚本清单

| 文件 | 作用 |
|---|---|
| `scripts/audit_hdl_blocks.m` | 政策审计:遍历 RTL 子树,列出所有 m 代码块 + 迁移度量 + 原生模块建议,写 JSON;支持豁免文件 |
| `scripts/check_exemptions.py` | 铁律 2 闸门:每个 m 代码块必须有 IP 名 + cycle-true 证据(首行 PASS)+ 批准人/日期,否则退出码 1 |
| `scripts/hdl_block_search.m` | 在 HDL Coder / DSP HDL / Wireless HDL / Vision HDL 库里按关键字找可直接生成 RTL 的模块 |
| `scripts/check_hdl_support.m` | `checkhdl` 封装:抓出根本无法生成 RTL 的模块 |
| `scripts/exemptions.example.json` | 豁免登记模板(字段缺一不可) |
| `reference/block_substitutions.md` | m 代码惯用法 → 原生模块对照表(库名/块名在 R2025b 核对过) |

## 八、与其它 skill 的分工

- **本 skill**:模型侧的规矩与闸门(不许写 m 代码;要写就得有 IP + cycle-true 证据)。
- **rtl-ip-replace**:`makehdl` 之后 RTL 侧的 IP 化(ROM/RAM/CORDIC/FIFO/**定抽头**滤波器)
  与双 DUT cycle-true 对比 —— 铁律 2 的证据就是它产出的 `cmp_result.txt`。
- **sim-rtl-flow**:把整条 Simulink→RTL→硬件的流程编排起来,本 skill 是其中"模块怎么搭"的一环。
- 滤波器口径三者一致:**只有固定抽头的滤波器才做 IP 替换**;LMS/Farrow/运行时参考抽头的
  相关器不替换 —— 但在模型侧,它们照样必须用原生模块(LMS Filter / Farrow Rate Converter)搭。