HDL 最小修復與一致性檢查
一個用於生成修復 HDL 設計錯誤的最小安全修補程式的工作流程,然後驗證該修補程式不會破壞硬體合約或留下跨工件不一致的情況。
此技能涵蓋的內容
此技能是兩個技能管線(定位 → 修復)中的修復部分。它接受兩個進入路徑:
- 附有根因假設註記(來自
hdl-fault-localization或同等工具)— 解析註記,選擇最佳假設,然後繼續。 - 附有現有修復意圖 — 當使用者或先前的代理已經給出特定的錯誤位置、修復方向或修補差異時,將該意圖提升為臨時假設並繼續。
此技能執行四件事,且僅此四件:
- 最小修補計畫 — 解決所選假設的最小變更集,不包含無關的修改。
- 副作用掃描器 — 檢查硬體合約配對(ready/valid、reset/flush/replay、FSM 轉換、過時狀態、管線順序)。
- 工件鏈結檢查器 — 確保配置、生成檔案、暫存器描述和產生器腳本保持一致。
- 測試驗證 — 執行測試套件並透過後備假設處理失敗。
此技能不執行故障定位。如果錯誤尚未被定位,請停止並要求先進行定位。
何時使用此技能
此技能僅在問題已被定位後激活。以下任一條件均足以進入:
- 提供了根因假設註記(來自
hdl-fault-localization或同等工具)。 - 使用者或先前的代理已給出明確的錯誤位置(檔案、模組、訊號)和修復方向(要更改什麼以及為何更改)。
- 使用者已陳述了明確的修復意圖(例如,「加寬此指標」、「新增一個skid buffer」、「修復FSM轉換」)。
- 現有的修補差異需要審查其副作用或一致性。
如果這些進入訊號均不存在 — 錯誤未被定位,沒有假設存在,也沒有特定的修復意圖可提升 — 請停止並要求先進行定位。 不要嘗試診斷錯誤;這是另一個故障定位技能的責任。模糊的請求,例如「修復此錯誤」、「有問題」或「我的測試平台失敗了」,且未提供任何定位資訊,均不構成進入訊號 — 它們缺乏此技能僅限修復範圍所需的具體性。
典型的觸發語句:「套用修復」、「進行修補」、「實作修復」、「檢查此修補程式的副作用」、「驗證此變更後的硬體合約」、「審查跨工件一致性」。
輸入需求
開始前至少必須存在以下其中一項。如果都不存在,請停止並要求先進行定位。
- 根因假設註記 — 描述一個或多個假設的檔案或內嵌文字,每個假設附有證據強度和理由。這是首選輸入,由
hdl-fault-localization產生。 - 明確的錯誤位置 + 修復方向 — 使用者或先前的代理已識別特定的檔案、模組或訊號,並描述了要做什麼變更。將此修復意圖提升為臨時假設。
- 現有的修復意圖 — 一個已陳述的計畫(例如,「將指標從4位元加寬到5位元」),可被視為單一假設的註記。
- 現有的修補差異 — 一個提議的程式碼變更,用於審查其副作用和工件一致性。
此外,收集:
- 相關原始檔 — 相關 HDL 模組、測試平台和支援程式碼的路徑。
- 測試命令 — 執行測試套件的確切命令。
- 失敗日誌 — 可選,但建議提供以了解上下文。
核心工作流程
按順序執行以下步驟。每個步驟的輸出會饋入下一步。
步驟 0:進入門檻檢查(在任何程式碼分析之前)
在閱讀任何原始檔、日誌或波形之前,請驗證使用者的訊息中至少存在一個進入訊號。依此順序檢查:
- 是否有根因假設註記(檔案路徑、內嵌 YAML 或帶有標記假設和證據的結構化文字)?
- 使用者是否指定了具體的錯誤位置和修復方向(特定的檔案、模組或訊號,以及對所做變更的描述 — 不只是「修復它」或「有問題」)?
- 使用者是否陳述了特定的修復意圖(例如,「將指標加寬到5位元」、「新增一個skid buffer」、「將 FSM 轉換從 A 改為 B」)?
- 是否有現有的修補差異需要審查?
如果這些都不存在 — 使用者只說了「修復此錯誤」、「我的測試平台失敗了」、「有問題」或類似模糊請求,且未提供定位資訊 — 立即停止。 不要閱讀原始碼。不要嘗試診斷錯誤。輸出:
此技能需要事先定位。請先執行故障定位(hdl-fault-localization),或提供以下其中一項:
- 根因假設註記
- 明確的錯誤位置(檔案/模組/訊號)和修復方向
- 特定的修復意圖(要做什麼變更以及為何)
- 現有的修補差異以供審查
僅在確認存在進入訊號後,才繼續執行步驟 1。
步驟 1:建立修復假設
如果有正式的根因假設註記可用,請解析它以提取:
- 每個假設,標記並描述。
- 支持每個假設的證據(強、中、弱)。
- 每個假設建議的修復方向。
- 任何假設之間的後備順序或依賴關係。
如果註記包含多個假設,請全部列出。如果它只包含一個,則簡化了選擇 — 但在承諾之前仍應評估其證據強度。
如果未提供假設註記,但存在修復意圖(明確的錯誤位置 + 修復方向、已陳述的修復計畫或現有的修補差異),請將該意圖提升為臨時假設。為它指定一個標籤(例如,「P1-sync-fifo-pointer-widen」),並根據使用者的描述記錄支持它的證據。此臨時假設將被視為步驟 2-7 的唯一假設。不要嘗試生成替代假設或執行故障定位 — 此技能的範圍止於修復執行。
步驟 2:選擇要優先修補的最佳假設
並非所有假設都是平等的。應用以下選擇標準:
- 證據強度 — 優先選擇有具體證據(波形追蹤、日誌模式、可重現條件)的假設,而非推測性的。
- 修補風險 — 優先選擇修復是局部化的(一個或兩個模組,無結構性變更)的假設,而非需要大規模重寫的。
- 可逆性 — 優先選擇修補程式易於還原(如果無效)的假設。
- 依賴順序 — 如果假設 B 依賴於假設 A 正確,則先修補 A。
記錄為何選擇此假設而非其他選項。如果您無法在兩個同樣強烈的假設之間做出決定,請選擇修補風險較低的那個,並將另一個記為主要後備。
步驟 3:生成最小修補計畫
「最小修補」並不意味著「只更改一個檔案」。它意味著:正確解決所選假設的最小變更集,不包含無關的修改。
對於您計畫修改的每個檔案,回答:
- 為什麼這個檔案必須更改? — 追蹤從假設到此特定變更的因果鏈。
- 具體更改了什麼? — 在訊號/邏輯層級描述變更,而非實作細節。
- 為什麼這是最小變更? — 解釋為什麼較小的變更會不足,或較大的變更是不必要的。
拒絕任何以下變更:
- 是表面性的(格式化、重新命名、與錯誤無關的註解更新)。
- 是重構(「趁我在這裡,讓我清理一下」)。
- 硬編碼測試期望值以使測試通過。
- 修改測試檔案而無證據表明測試本身有誤。
步驟 4:執行副作用掃描器
硬體設計在訊號之間有隱含的合約。更改合約的一方通常會破壞另一方。在套用修補程式之前,掃描以下合約違規:
ready/valid 配對
對於已修改模組及其相鄰模組中的每對 ready/valid 握手:
- 修補程式是否更改了
valid被宣告或取消宣告的時間?如果是,消費者的ready邏輯是否仍能正常運作? - 修補程式是否更改了
ready被取樣或驅動的時間?如果是,生產者的valid邏輯是否仍然合理? - 是否仍能正確處理反壓 — 管線能否在不丟失資料的情況下停頓?
reset/flush/replay
對於每個重置、刷新或重播訊號:
- 修補程式是否更改了重置時清除或保留的狀態?
- 刷新路徑是否仍能正確排空或使正在處理的資料無效?
- 重播路徑是否仍能將狀態恢復到正確的檢查點?
FSM 轉換完整性
對於修補程式觸及的每個有限狀態機:
- 所有狀態是否都可從重置到達?
- FSM 是否可能死鎖(狀態中無有效出口)?
- FSM 是否可能活鎖(狀態之間無限循環而無進展)?
- 修補程式是否新增或刪除了任何狀態轉換?如果是,請驗證新的轉換表是否完整。
過時狀態
- 修補程式是否引入了任何暫存器或訊號,這些暫存器或訊號可以在交易或時脈週期中持有過時的值,而它本應被清除?
- 修補程式是否依賴於一個訊號被某個不再正確觸發的機制清除?
管線順序
- 修補程式是否更改了管線中的操作順序?如果是,下游階段是否仍能按預期順序接收資料?
- 修補程式是否更改了管線深度(新增或刪除了階段)?如果是,是否調整了所有旁路和轉發路徑?
記錄每個類別的發現,即使結果是「未發現問題」。
步驟 5:執行工件鏈結檢查器
HDL 專案通常有配置檔案、暫存器映射和生成的程式碼,這些必須與 HDL 原始碼保持同步。檢查這些鏈結:
配置檔案
掃描引用修補程式觸及的訊號、參數或模組的配置檔案(YAML、HJSON、JSON、TOML、INI 或類似格式)。如果修補程式更改了參數值、模組名稱或連接埠列表,請更新配置以匹配。
生成的檔案
檢查專案中是否有任何檔案是自動生成的(由程式碼產生器、腳本或建置步驟生成)。如果修補程式更改了為產生器提供輸入的原始碼,則:
- 重新生成輸出檔案,或
- 標記不一致之處以供手動重新生成。
暫存器描述
如果設計包含暫存器映射(CSV、XML、IP-XACT、SystemRDL 或類似格式),請檢查暫存器欄位位置、寬度和存取類型在修補後是否與 HDL 產生偏差。
產生器腳本
檢查生成 HDL 或配置檔案的 Python、Perl、Tcl 或 shell 腳本。如果修補程式更改了這些腳本依賴的模式(命名約定、訊號寬度、介面協定),腳本可能會產生錯誤的輸出。
記錄所有已檢查的工件以及發現的任何不一致之處。
當修補程式僅更改內部邏輯(無公開介面、參數、暫存器欄位、位址映射、生成的原始碼或配置可見的行為)時,工件鏈結檢查會簡化為「不適用 — 僅內部修補,無跨工件影響」。避免掃描整個專案樹以查找無法受變更影響的工件。僅當修補程式觸及上述列出的表面之一時,才執行完整的工件搜尋。
步驟 6:套用修補程式並執行測試
將修補程式套用至實際的原始檔。然後執行測試命令:
- 執行測試套件一次。
- 如果所有測試都通過 — 記錄結果並繼續執行步驟 7。
- 如果某些測試失敗 — 分析:
- 這些失敗是否早已存在? 檢查失敗日誌以查看這些測試在修補之前是否已失敗。早已存在的失敗並非修補程式的過錯 — 記下它們,但不要阻止修復。
- 這些失敗是否由修補程式引起? 如果修補程式引入了新的失敗,則修復不完整或不正確。轉到後備路徑。
- 這些失敗是否揭示了測試錯誤? 僅在您有具體證據表明測試期望值錯誤時才得出此結論,而不僅僅是因為修補程式更改了行為。
步驟 7:處理失敗 — 退回至下一個假設
如果修補程式以由修補程式引起的方式(非早已存在或測試錯誤)導致測試失敗:
- 不要嘗試透過臨時調整來挽救修補程式。這會將假設驅動的修復變成猜測。
- 如果執行環境支援乾淨的回退(例如,
git checkout、git stash或外部 harness 管理修補狀態),請在嘗試後備方案之前還原失敗的修補程式。如果不支援回退,請在繼續之前明確檢查並撤銷失敗的編輯 — 不要在一個已損壞的修補程式之上疊加一個新的修補程式。 - 選擇下一個假設(來自假設註記中證據與風險組合次佳的那個)。
- 在修補決策註記中記錄:哪個假設失敗了,為什麼(哪個測試被破壞),以及現在正在嘗試哪個假設。
- 使用後備假設返回步驟 2。
如果所有假設都已用盡且沒有修補程式通過測試,請報告假設集合不足 — 根因可能未被任何假設的解釋所捕捉。
輸出:修補決策註記
在工作流程結束時(無論修補成功或失敗),使用以下確切結構產出修補決策註記:
patch_decision_note:
selected_hypothesis: <已修補的假設>
patch_scope: <修補程式變更內容的一句話摘要>
modified_files:
- <檔案路徑>: <此檔案必須更改的理由>
- <檔案路徑>: <此檔案必須更改的理由>
side_effect_scan:
ready_valid: <已檢查項目的狀態或發現>
reset_flush_replay: <已檢查項目的狀態或發現>
fsm_transitions: <已檢查項目的狀態或發現>
stale_state: <已檢查項目的狀態或發現>
pipeline_ordering: <已檢查項目的狀態或發現>
artifact_link_check:
config_files: <已檢查項目的狀態或發現>
generated_files: <已檢查項目的狀態或發現>
register_descriptions: <已檢查項目的狀態或發現>
generator_scripts: <已檢查項目的狀態或發現>
test_results:
status: <passed | failed>
failures_analyzed: <如果失敗,簡要解釋原因>
fallback_info:
was_fallback: <true | false>
fallback_hypothesis: <如果適用,使用的後備假設>
outcome: <success | failed | insufficient_hypotheses>
如果工件鏈結檢查發現任何不一致且無法自動解決,請在修補決策註記中加入 action_required 區段:
action_required:
- <需要手動修復的描述,包括檔案路徑和問題>
如果進入時未發現錯誤(定位後,錯誤已消失,或使用者對行為的描述不準確),請報告「未發現錯誤 — 驗證了設計」。不要強制套用修補程式。
hdl-fault-localization 技能的輸入格式
當與 hdl-fault-localization 技能配對使用時,它會產生此技能作為輸入的根因假設註記。該註記使用以下結構:
hypothesis_note:
bug: <錯誤的簡短名稱或描述>
failing_tests:
- <失敗的測試名稱,附上簡短訊息>
hypotheses:
- label: <唯一假設標籤>
description: <一句話描述錯誤可能的原因>
evidence:
strength: <strong | moderate | weak>
rationale: <證據為何支持此假設的解釋>
fix_direction: <修復此假設需要做什麼變更的描述>
dependencies: <此假設依賴的標籤列表(如果有的話)>
範例:
hypothesis_note:
bug: sync_fifo overflow under backpressure
failing_tests:
- "test_backpressure_overflow: read pointer overtakes write pointer"
- "test_almost_full_flag: asserts one cycle early under backpressure"
hypotheses:
- label: H1-pointer-width
description: Write pointer modulo logic underflows because the pointer
width is insufficient for the FIFO depth.
evidence:
strength: strong
rationale: "FIFO depth is 16, requiring a 5-bit pointer to distinguish
full vs empty. Current pointer is 4 bits, causing wrap-around at 15.
The failing tests both involve the pointer reaching the wrap point."
fix_direction: Widen write and read pointers from 4 to 5 bits. Update
the full/empty comparison logic to use the MSB.
dependencies: []
- label: H2-stall-miscount
description: Backpressure stall counter miscounts due to off-by-one in
the stall tracking logic, causing premature almost_full assertion.
evidence:
strength: moderate
rationale: "The almost_full flag asserts exactly one cycle before the
full condition is reached. This could be an intended behavior or a
miscount. The waveform shows the flag asserting after 14 writes
instead of 15."
fix_direction: Adjust the stall counter threshold from 14 to 15 in the
almost_full generation logic.
dependencies: [H1-pointer-width]