cpu-performance-modeling - SKILL.md Agent Skill

name: cpu-performance-modeling description: 由 CPU 性能模拟器建模经验蒸馏而成的行为级建模规范。强调高性能实现、参数化资源模型、细粒度/粗粒度取舍、控制流抽象、复杂度约束和 stats 驱动验证。适用于新增或修改性能模型、把 RTL 机制抽象成模拟器模型、设计参数化微结构模型、决定哪些行为需要细粒度建模、评审 AI 生成的 CPU 性能模拟代码时。

CPU 性能建模

基本立场

本 skill 规定 CPU 性能模型的建模流程和评审标准。任何模型都应先明确同一条因果链：

workload event -> abstract control/resource state -> contention/backpressure
    -> latency/retry/progress -> observable stats

建模目标是复现真实性能后果，而非逐信号复刻 RTL。模型可以在明确说明误差边界的前提下牺牲少量拍级细节，以换取模拟速度和可参数化能力；关键瓶颈、参数趋势和 stats 归因必须保留。

工作流

做新增、修改或评审前，按顺序执行：

读现有模型：调研同类资源的本地实现，提取状态、队列、token、参数、stats 和 debug 输出；RTL 信号映射仅作为后续校验材料。
写建模合同：在方案或最终答复中明确合同；非平凡改动必须先形成合同。
判定粒度：把行为分成必须细建、参数化粗建、只保功能正确三类。
选算法：实现前确定热路径复杂度和数据结构。
落参数和 stats：所有性能相关行为必须有参数入口和可观测结果。
验证趋势：用最小 workload、debug trace、stats 或 A/B 参数变化证明模型保留了性能因果链。

建模合同

合同必须具体到能指导代码结构，至少包含：

性能问题：模型要反映吞吐、延迟、端口竞争、队列占用、replay、flush、miss/hit、bank conflict、turnaround、公平性中的哪几类。
外部症状：用户或上游模块能观察到什么变化，例如发射受阻、请求被拒、响应提前、load replay、store drain、queue full、prefetch 被丢弃。
控制状态机：列出状态和转移，例如 ready -> selected -> issued -> blocked -> replayed -> completed -> released。
资源 token：列出瓶颈资源，例如 issue port、read/write port、pipeline slot、queue entry、MSHR、bank、tag path、store buffer line、command window。
参数面：列出宽度、深度、延迟、阈值、策略、开关、dequeue rate、window size；默认值必须说明是否保持旧行为。
粒度选择：逐项说明哪些细粒度建模，哪些合并为 latency/token/queue/threshold/window，哪些只维护功能正确。
算法复杂度：说明每周期、每请求、每完成事件的复杂度上界；热路径不能依赖无界扫描。
可观测性：列出 stats/debug/minimal workload；新增 blocked/replay/merge/drop/evict 原因必须可观测。

六条硬原则

1. 高性能建模

模拟器热点应使用固定容量队列、readyTime 排序、bitset、索引表、有限枚举、事件驱动和每周期 quota。高频路径应避免复制 RTL 的大规模组合搜索。

必须做到：

对队列、窗口、端口、bank、MSHR 这类资源给出容量和访问复杂度。
用 head/tail、ready list、free list、hash index、busy bitmap 表达资源可用性。
每周期处理量由参数限制，例如 issue width、completion width、dequeue width、command bandwidth。
队头未就绪时通过 readyTime 或事件重调度等待，而不是每拍扫描所有 entry。

评审检查项：

新增信号级临时状态必须对应新的性能后果。
每周期遍历必须有上界或早停条件。
debug/统计数据不得扩大热路径主结构的复杂度。

2. 参数化建模

性能相关行为必须由微结构语义参数控制，而不是硬编码常量或 RTL 信号名。

必须参数化：

宽度：fetch/decode/rename/commit/issue/load/store/writeback/completion。
深度：ROB、IQ、LQ、SQ、RAR/RAW queue、MSHR、write buffer、store buffer。
延迟：前后级 TimeBuffer、pipeline stage、cache access、frontend/backend memory latency、turnaround。
带宽和窗口：port token、dequeue per cycle、bank/tag access、command window、min reads/writes per switch。
策略和开关：调度策略、replay 策略、bank conflict check、miss replay、strict wait、prefetch admission。

参数默认值的规则：

默认值优先保持旧行为或当前配置的性能趋势。
参数名描述模拟器语义，例如 LoadCompletionWidth；避免使用 RTL wire 名。
新参数必须在配置入口、构造函数、stats 解释之间能串起来。

3. 细粒度和粗粒度的平衡

细粒度给关键控制流，粗粒度给不决定性能的内部细节。

必须细建的行为：

会改变发射、唤醒、提交、请求发送、响应返回、replay、flush、drain 的转移。
会造成主瓶颈的资源竞争，例如端口、bank、MSHR、队列满、读写切换。
会决定是否提前返回、是否 full/partial forward、是否 merge/drop、是否 backpressure 上游。
会显著改变 stats 趋势或 benchmark 排名的行为。

应粗建的行为：

只改变内部流水分拍，但不改变对外可见的阻塞、完成、重试或带宽。
多个 RTL 信号共同产生同一种性能后果，可合并成枚举原因。
数据搬运细节不影响 forwarding、ordering、异常或功能正确时，可压成 id/mask/block/age/sequence。

粒度判定算法：

写出该机制所有外部后果。
标出会改变后果的最小控制条件。
若条件会频繁触发且影响 IPC/latency，细建。
若条件只改变等待时间或吞吐上限，用参数化 latency/bandwidth/threshold/window 吸收。
若条件只影响内部 debug 或数据内容，保留最小功能状态。
对每个被粗建的点说明损失了什么拍级细节，以及为什么不影响目标趋势。

4. 行为级性能建模

行为级模型以性能后果为目标，不以 1:1 RTL 复刻为目标。

高准确度标准：准确度来自保留关键因果链，而不是更像 RTL：

参数变化应产生合理趋势：更深队列减少 full stall，更大带宽减少 busy，更长 latency 增加等待，更高阈值改变 drain/turnaround。
不同 replay/blocked 原因若等待行为不同，必须区分；若外部后果相同，可以合并。
读写请求的 merge、forward、drop、early response 必须保留，因为它们直接改变队列压力和响应时间。
每个关键性能变化都应能被 queue occupancy、port busy、replay reason、latency sample 或 bandwidth/window stats 解释。
若为了速度牺牲拍级细节，必须说明保留了哪些控制结果，损失了哪些内部时序。

评审时重点问：

模型是否解释了性能变化。
A/B 改参数时，趋势是否可预测且可用 stats 归因。
新增状态是否影响 progress、stall、retry、latency 或 bandwidth。

5. 控制流优先于数据流

性能模拟器先建控制流，再保留最小数据。

优先保留：

请求 identity：inst seq、thread id、request id、block address、QoS、age/order。
覆盖关系：byte mask、split chunk、full/partial coverage、newer/older。
时序关系：readyTime、entryTick、nextReqTime、busy bitmap、completion index。
控制原因：blocked/replay/forward/merge/drop/evict/turnaround reason。

只在这些情况保留数据内容：

store-to-load forwarding 或 store buffer forwarding 需要判断完整/部分覆盖。
atomic/LLSC、异常、device/local access、functional correctness 需要真实数据。
debug 或 golden memory 需要最终写入内容。

其余数据流应压缩为 mask、block、burst、age、sequence、枚举或统计计数。

6. 算法设计优先

建模不是信号翻译，是约束下的算法设计。

优先选择这些模式：

端口 token + busy bitmap：适合 issue/FU/cache port。
readyTime queue：适合 MSHR、write buffer、memory request queue。
completion index + dequeue quota：适合有序完成、RAR/RAW、commit/drain。
hash index + LRU/free list：适合 store buffer/write queue merge/forward。
有限 replay reason：适合 bank/tag/MSHR/cache blocked/nuke/RAW/RAR。
window/threshold state machine：适合 memory controller、drain、读写切换。

复杂度要求：

热路径目标是 O(1)、O(log N) 或 O(k)，其中 k 是参数化小上限。
扫描必须有自然边界，例如 queue depth、source operands、burst chunks、active priorities。
若扫描可能很大，增加索引、ready list、age pointer、completion index 或缓存上次结果。
stats 不能改变模型行为，也不能迫使热路径做额外大扫描。

参考示例

需要具体伪代码时读取 references/modeling-examples.md。其中包含高性能端口仲裁、LSQ replay、RAR/RAW 队列、store buffer merge/forward、cache/MSHR readyTime、memory controller window/threshold 调度等可迁移模板。

输出要求

使用本 skill 完成代码任务时，最终说明必须包含：

建模合同摘要。
细粒度/粗粒度取舍，尤其是关键路径和非关键路径的分界。
参数列表、默认值和配置入口。
核心数据结构和复杂度。
新增或复用的 stats/debug。
准确度论证：保留了哪些性能因果链，损失了哪些拍级或数据流细节，为什么可接受。
验证命令和结果；不能验证时说明剩余风险。

评审 AI 生成代码时，优先指出以下问题：关键瓶颈缺失、不可参数化、热路径无界扫描、stats 不可归因、RTL 信号机械映射、数据流过重、缺少 A/B 趋势验证。