skills-win/simulink_rtl_dev/SKILL.md

name, description

name

description

simulink_rtl_dev

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 里):

   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 兼容性检查:

   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 运行):

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)搭。