HDL 최소 수리 및 일관성 검사
HDL 설계 버그를 수정하는 가장 작은 안전한 패치를 생성하고, 수정 사항이 하드웨어 계약을 위반하거나 교차 아티팩트 불일치를 남기지 않는지 확인하는 워크플로우입니다.
이 스킬이 다루는 내용
이 스킬은 2단계 파이프라인(로컬라이제이션 → 수리)의 수리 부분입니다. 두 가지 진입 경로를 허용합니다.
- 근본 원인 가설 노트 포함 (
hdl-fault-localization또는 이에 상응하는 것에서) — 노트를 파싱하고, 최상의 가설을 선택한 후 진행합니다. - 기존 수리 의도 포함 — 사용자나 이전 에이전트가 이미 특정 버그 위치, 수정 방향 또는 패치 diff를 제공한 경우, 해당 의도를 임시 가설로 승격시키고 진행합니다.
이 스킬은 다음 네 가지 작업만 수행하며 그 외의 작업은 수행하지 않습니다.
- 최소 패치 계획 — 선택된 가설을 해결하는 가장 작은 변경 집합으로, 관련 없는 수정은 포함하지 않습니다.
- 부작용 스캐너 — 하드웨어 계약 쌍(ready/valid, reset/flush/replay, FSM 전환, 스테일 상태, 파이프라인 순서)을 확인합니다.
- 아티팩트 링크 검사기 — 설정, 생성 파일, 레지스터 설명 및 생성기 스크립트가 일관성을 유지하는지 확인합니다.
- 테스트 검증 — 테스트 스위트를 실행하고 대체 가설을 통해 실패를 처리합니다.
이 스킬은 결함 로컬라이제이션을 수행하지 않습니다. 버그가 로컬라이즈되지 않은 경우, 중단하고 먼저 로컬라이제이션을 요구하십시오.
이 스킬을 사용해야 하는 경우
이 스킬은 문제가 이미 로컬라이즈된 경우에만 활성화됩니다. 다음 중 하나라도 해당되면 진입할 수 있습니다.
- 근본 원인 가설 노트가 제공된 경우 (
hdl-fault-localization또는 이에 상응하는 것에서). - 사용자나 이전 에이전트가 명시적인 버그 위치(파일, 모듈, 신호)와 수정 방향(무엇을 왜 변경할지)을 제공한 경우.
- 사용자가 명확한 수리 의도를 명시한 경우 (예: "이 포인터를 넓힙니다", "스키드 버퍼를 추가합니다", "FSM 전환을 수정합니다").
- 부작용이나 일관성 검토가 필요한 기존 패치 diff가 있는 경우.
이러한 진입 신호가 하나도 없는 경우 — 버그가 로컬라이즈되지 않았고, 가설이 없으며, 승격시킬 특정 수리 의도도 없는 경우 — 중단하고 먼저 로컬라이제이션을 요구하십시오. 버그를 진단하려고 시도하지 마십시오. 이는 별도의 결함 로컬라이제이션 스킬의 책임입니다. "이 버그를 수정하세요", "뭔가 잘못되었습니다", 또는 "내 테스트벤치가 실패합니다"와 같은 로컬라이제이션 정보 없이 모호한 요청은 진입 신호가 아닙니다 — 이 스킬의 수리 전용 범위에 필요한 특이성이 부족합니다.
일반적인 트리거 문구: "수정을 적용하세요", "패치를 만드세요", "수리를 구현하세요", "이 패치의 부작용을 확인하세요", "이 변경 후 하드웨어 계약을 확인하세요", "교차 아티팩트 일관성을 감사하세요".
입력 요구 사항
시작하기 전에 다음 중 하나 이상이 있어야 합니다. 아무것도 없으면, 중단하고 먼저 로컬라이제이션을 요구하십시오.
- 근본 원인 가설 노트 — 각각 증거 강도와 근거가 있는 하나 이상의
가설을 설명하는 파일 또는 인라인 텍스트입니다.
hdl-fault-localization에서 생성된 선호되는 입력입니다. - 명시적 버그 위치 + 수정 방향 — 사용자나 이전 에이전트가 특정 파일, 모듈 또는 신호를 식별하고 어떤 변경을 할지 설명했습니다. 이 수리 의도를 임시 가설로 승격시킵니다.
- 기존 수리 의도 — 명시된 계획 (예: "4비트에서 5비트로 포인터 넓히기") 으로 단일 가설 노트로 처리할 수 있습니다.
- 기존 패치 diff — 부작용과 아티팩트 일관성을 검토할 제안된 코드 변경 사항입니다.
또한 다음을 수집합니다.
- 관련 소스 파일 — 관련된 HDL 모듈, 테스트벤치 및 지원 코드의 경로입니다.
- 테스트 명령 — 테스트 스위트를 실행할 정확한 명령입니다.
- 실패 로그 — 선택 사항이지만 컨텍스트에 권장됩니다.
핵심 워크플로우
다음 단계를 순서대로 따르십시오. 각 단계는 다음 단계로 전달되는 출력을 생성합니다.
0단계: 진입 게이트 확인 (코드 분석 전)
소스 파일, 로그 또는 파형을 읽기 전에 사용자의 메시지에 적어도 하나의 진입 신호가 있는지 확인하십시오. 다음 순서로 확인합니다.
- 근본 원인 가설 노트(파일 경로, 인라인 YAML 또는 레이블이 지정된 가설과 증거가 있는 구조화된 텍스트)가 있습니까?
- 사용자가 구체적인 버그 위치와 수정 방향을 지정했습니까? (특정 파일, 모듈 또는 신호 그리고 어떤 변경을 할지에 대한 설명 — 단순히 "수정하세요" 또는 "뭔가 잘못되었습니다"가 아닙니다)?
- 사용자가 특정 수리 의도를 명시했습니까? (예: "포인터를 5비트로 넓힙니다", "스키드 버퍼를 추가합니다", "FSM 전환을 A에서 B로 변경합니다")?
- 검토할 기존 패치 diff가 있습니까?
이러한 항목이 하나도 없는 경우 — 사용자가 "이 버그를 수정하세요", "내 테스트벤치가 실패합니다", "뭔가 잘못되었습니다" 또는 이와 유사한 로컬라이제이션 없는 모호한 요청만 하는 경우 — 즉시 중단하십시오. 소스 코드를 읽지 마십시오. 버그를 진단하려고 시도하지 마십시오. 다음을 출력합니다.
이 스킬은 사전 로컬라이제이션이 필요합니다. 먼저 결함 로컬라이제이션을 실행하십시오
(hdl-fault-localization), 또는 다음 중 하나를 제공하십시오:
- 근본 원인 가설 노트
- 명시적 버그 위치(파일/모듈/신호) 및 수정 방향
- 특정 수리 의도(무엇을 왜 변경할지)
- 검토할 기존 패치 diff
진입 신호가 있는지 확인한 후에만 1단계로 진행하십시오.
1단계: 수리 가설 수립
공식 근본 원인 가설 노트를 사용할 수 있는 경우, 이를 파싱하여 다음을 추출합니다.
- 레이블이 지정되고 설명된 각 가설.
- 각 가설을 뒷받침하는 증거 (강함, 보통, 약함).
- 각 가설에 대해 제안된 수정 방향.
- 가설 간의 대체 순서 또는 종속성.
노트에 여러 가설이 포함된 경우, 모두 나열하십시오. 하나만 포함된 경우, 선택이 단순화되지만 — 커밋하기 전에 증거 강도를 평가하십시오.
가설 노트가 제공되지 않았지만 수리 의도가 있는 경우 (명시적 버그 위치 + 수정 방향, 명시된 수리 계획 또는 기존 패치 diff), 해당 의도를 임시 가설로 승격시키십시오. 레이블을 지정하고(예: "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 또는 셸 스크립트를 확인하십시오. 패치가 이러한 스크립트가 의존하는 패턴(명명 규칙, 신호 너비, 인터페이스 프로토콜)을 변경하는 경우, 스크립트가 잘못된 출력을 생성할 수 있습니다.
확인된 모든 아티팩트와 발견된 불일치를 문서화하십시오.
패치가 내부 로직만 변경하는 경우(공용 인터페이스, 매개변수, 레지스터 필드, 주소 맵, 생성된 소스 또는 구성에 표시되는 동작 없음), 아티팩트 링크 검사는 "해당 없음 — 교차 아티팩트 영향이 없는 내부 전용 패치"로 축소됩니다. 변경의 영향을 받을 수 없는 아티팩트에 대해 전체 프로젝트 트리를 스캔하지 마십시오. 패치가 위에 나열된 표면 중 하나에 영향을 미치는 경우에만 전체 아티팩트 검색을 실행하십시오.
6단계: 패치 적용 및 테스트 실행
실제 소스 파일에 패치를 적용하십시오. 그런 다음 테스트 명령을 실행하십시오.
- 테스트 스위트를 한 번 실행하십시오.
- 모든 테스트가 통과하면 — 결과를 문서화하고 7단계로 진행하십시오.
- 일부 테스트가 실패하면 — 분석하십시오.
- 실패가 기존에 존재했습니까? 실패 로그를 확인하여 이러한 테스트가 패치 전에 실패했는지 확인하십시오. 기존 실패는 패치의 잘못이 아닙니다 — 기록하되 수정을 차단하지 마십시오.
- 실패가 패치로 인해 발생했습니까? 패치가 새로운 실패를 도입한 경우, 수정이 불완전하거나 올바르지 않습니다. 대체 경로로 이동하십시오.
- 실패가 테스트 버그를 드러냅니까? 테스트 기대값이 잘못되었다는 구체적인 증거가 있는 경우에만 이 결론을 내리십시오. 패치가 동작을 변경했다는 이유만으로 그렇게 하지 마십시오.
7단계: 실패 처리 — 다음 가설로 대체
패치가 패치로 인해 발생한 방식으로 테스트에 실패한 경우 (기존 또는 테스트 버그가 아님):
- 임시 수정으로 패치를 구제하려고 하지 마십시오. 이는 가설 기반 수정을 추측성 작업으로 만듭니다.
- 실행 환경이 완전한 롤백을 지원하는 경우 (예:
git checkout,git stash또는 패치 상태를 관리하는 외부 하네스), 대체 항목을 시도하기 전에 실패한 패치를 되돌리십시오. 롤백이 지원되지 않는 경우, 계속하기 전에 실패한 편집을 명시적으로 검사하고 취소하십시오 — 손상된 패치 위에 새 패치를 쌓지 마십시오. - 가설 노트에서 다음 가설을 선택하십시오 (증거와 위험의 다음으로 좋은 조합을 가진 가설).
- 패치 결정 노트에 문서화하십시오: 어떤 가설이 실패했는지, 왜 (어떤 테스트가 깨졌는지), 그리고 어떤 가설이 시도 중인지.
- 대체 가설을 사용하여 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:
test_command: <실행된 명령>
passed: <통과한 테스트 수>
failed: <실패한 테스트 수>
pre_existing_failures: <예 / 아니오 (해당되는 경우 나열)>
result: <통과 / 실패 — 대체 필요 / 실패 — 가설 소진>
fallback_info:
fallback_attempted: <예 / 아니오>
fallback_hypothesis: <시도된 경우 대체 가설 레이블>
fallback_result: <통과 / 실패>
conclusion: <최종 결과 요약 (1-2 문장)>