anlogic-code-design

name	anlogic-code-design
description	安路 FPGA 代码设计 skill。Use when: 需要把已分析清楚的需求落成一致风格的 RTL，规范接口、简化 primitive 引脚连接、保持可扩展可移植，并形成交给 anlogic-testbench 的设计交付。

Anlogic FPGA Code Design Skill

角色

负责把 anlogic-needs-analysis 的工程输入级结论落成可验证、可综合、可交接的 RTL 设计交付。

输入

• 最新的 doc/stage-S0-summary.md
• 上游需求分析结论
• 器件、接口、时钟复位、带宽与 CDC 风险
• primitive / hard IP / wrapper / TD IP 建议

边界

• 不直接生成 testbench
• 不直接运行 ModelSim
• 不直接创建 TD 工程
• 不用本阶段去补需求分析遗漏

输出

• RTL 设计交付
• 交给 anlogic-testbench 的固定输入
• doc/stage-S1-summary.md

不做什么

• 不重复解释完整全流程背景
• 不跳过固定 summary 字段

2026-05-06 Rule: Coding Style Must Be A Design Gate

• The coding rules in this skill are not documentation-only suggestions. They are a release gate for the design handoff.
• If the user or project has explicitly requested register initialization style, initial usage, or "single-register assignment block" structure, the stage conclusion must explicitly say whether the delivered RTL complies.
• Functional progress is not enough to waive style-gate violations. If the code is intentionally left non-compliant for schedule reasons, the stage conclusion must say the design is not style-released and name the remaining cleanup.
• For hard-IP based top-levels, also state whether the top module is limited to interconnect and binding duties or whether business logic has leaked upward into top-level RTL.

上游输入

优先来自 anlogic-needs-analysis：

• 推荐器件型号或候选型号
• 资源预算与接口资源判断
• 模块划分、逻辑框架和数据流
• 对 primitive / hard IP / wrapper / TD IP 的建议
• 时钟、复位、带宽、缓存与 CDC 风险

如果这些输入还不完整，先回到 anlogic-needs-analysis，不要在代码层盲目展开。

负责内容

• 统一 RTL 代码风格、命名和层次结构
• 设计顶层模块与子模块边界
• 规范接口命名、方向、位宽、时钟域和复位约定
• 优先采用简单、清晰、可验证的 primitive 引脚连接方式
• 明确何处用 primitive、wrapper、TD IP 或普通 RTL
• 保持设计可扩展、可移植、可复用
• 显式标出 CDC、时序、缓存深度、带宽和 backpressure 风险
• 形成交给 anlogic-testbench 的固定设计交付

不负责内容

• 不直接生成 testbench
• 不直接运行 ModelSim
• 不直接创建 TD 工程
• 不代替综合、布局布线、bitgen 或下载

强制代码规范

以下规则是 anlogic-code-design 的硬门禁，不是可选建议：

1. 所有寄存器必须显式初始化，默认值为 0。
2. 若项目约定使用 initial 初始化，则 initial 值必须与复位后的目标值一致；若用户或协议另有指定，以明确需求为准。
3. 每个寄存器默认放在独立的 always 块中控制；一个 always 块只保留一组主 begin/end，避免在同一时序块里堆叠多个无关寄存器职责。
4. 工程交付代码必须可综合，不允许把不可综合结构带入项目 RTL。按本 skill 约定，避免在工程 .v 中使用 function、task、fork/join、wait、force/release、#delay 等结构；确有仿真需求时，应放入 testbench，而不是工程 RTL。
5. 所有工程 .v 文件统一放在 src/ 目录下管理。
6. 每个 .v 文件只放一个主模块，文件名必须与模块名高度对应，并通过模块前缀或功能后缀区分不同模块，便于用户搜索和维护。
7. 顶层模块以互联为主，不在顶层堆积业务逻辑；复杂 primitive 接口优先下沉到 wrapper。

默认流程

1. 读取 anlogic-needs-analysis 的输入结论
2. 确认顶层模块、子模块、公共模块和 src/ 文件组织方式
3. 固化接口协议、时钟/复位和 primitive 使用边界
4. 形成一致风格、满足硬门禁的 RTL 设计方案
5. 输出交给 anlogic-testbench 的验证输入
6. 若仿真失败，再根据 anlogic-modelsim 结论回修代码设计

对 anlogic-testbench 的交付要求

至少输出：

• 顶层模块与子模块清单
• src/ 下的文件清单、文件命名规则和模块映射
• 每个关键接口的方向、位宽、时序关系和握手语义
• 时钟/复位策略，以及寄存器默认初始化策略
• 关键 primitive / wrapper / hard IP 使用点
• 关键状态机、FIFO、DMA、缓存或数据路径说明
• 必须覆盖的场景、边界条件和观察点
• 需要重点检查的 CDC、带宽、时延、初始化或复位风险
• 固定 summary 字段：
  • current_stage
  • goal
  • confirmed_constraints
  • artifacts
  • decision
  • blocking_reason
  • next_action

联动规则

• 需求、型号、资源、接口还不清楚：联动 anlogic-needs-analysis
• 需要生成 stimulus、checker 和通过判定：联动 anlogic-testbench
• 仿真失败需要定位代码层问题：读取 anlogic-modelsim 结论后回修本阶段
• 需要 TD 工程和文件组织：在仿真通过后交给 anlogic-project-creation
• 需要复杂 IP 集成或打包：联动 anlogic-ip-tooling

输出要求

至少输出：

• 代码结构、模块边界和 src/ 目录组织
• 接口规范、时钟/复位规范与寄存器初始化口径
• primitive / wrapper / hard IP 使用建议
• 风格一致性、可移植性和可扩展性说明
• 交给 anlogic-testbench 的验证场景、检查点和风险点
• 若当前不放行，最小回修动作是什么

参考资料

• references/rtl-style-guide.md
• references/primitive-interface-guidelines.md
• references/rtl-init-defaults.md
• references/handoff-to-testbench-template.md