본机适配注记（非 AMD 原文；2026-10-18 由 DSH 会话追加）
- 工具链不同：本机用第三方 vivado-mcp（现役安装
<vivado-mcp>，32 个工具），不是官方vivado-mcp-server；仓库内<EIF 仓库>\vivado-mcp是零改动随仓副本、不是运行实例（客户端必须显式设PYTHONPATH=<vivado-mcp>\site，否则 venv 的_mcp_pilot_paths.pth会命中.mcp-pilot中文路径副本 →start_session静默失败）。- 工具映射：
vivadoExecute/vivado_execute→run_tcl/safe_tcl；vivado_start→start_session；vivado_stop→stop_session；vivado_list_sessions→list_sessions；vivado_status→get_run_progress；vivado_log_messages→get_critical_warnings（仅 runme.log）或read/grep；read_file→read；create_file→write；replace_string_in_file→edit；file_search→glob；grep_search→grep；run_in_terminal→pwsh；runSubagent→subagent。- 会话没挂 MCP 工具时走 CLI 桥：
python <vivado-mcp>\mcp_ctl.py session "<多行 Tcl>"（等价 run_tcl）、call <tool> --args-file <json>、list。一次调用一个 MCP 进程，多步会话必须写成单次session。（2026-10-24 已在 desktop profile 配置mcp__vivado__*，需重启宿主生效；未生效时 CLI 桥仍是唯一通路。）- 版本事实：Vivado 2023.1（官方基线 2026.1）；Python 用
<python 解释器：见 config.yml 的 python（install.ps1 写入实际值）>。- 文档检索：本机无
vivado_doc_search，改用web_fetch（docs.amd.com / 官方 docs）或本项目<project_root>\docs。- 硬约束：MCP 安装路径必须纯 ASCII（中文路径经 Vivado Tcl GBK 解码会坏）；Vivado 会话与综合/实现/仿真全局串行。
Vivado 리비전 관리 스킬
이 스킬은 5단계 파이프라인(선택적 대화형 2.5단계 포함)을 통해 Vivado 프로젝트의 리비전 관리를 자동화합니다. 표준 RTL 전용 프로젝트, IPI 블록 디자인(블록 디자인 컨테이너 포함), DFX(부분 재구성), Versal 세그먼트 구성 프로젝트에서 작동합니다.
파이프라인은 프로젝트 유형을 감지하고, 소스 위치를 분석하며, 구성 요소를 내보내고, 설정을 캡처하고, 빌드 스크립트를 생성하여, 프로젝트를 처음부터 재생성할 수 있는 자체 포함 디렉토리를 생성합니다.
이 스킬을 사용해야 하는 경우
- Vivado 프로젝트의 버전 관리 설정
- 팀원 또는 CI/CD를 위해 프로젝트 이식성 확보
- 모든 프로젝트 소스 내보내기 및 구성
- 재현 가능한 빌드를 위한 자동화된 빌드 스크립트 생성
- DFX, BDC 또는 세그먼트 구성 리비전 관리 처리
이 스킬을 사용하지 말아야 하는 경우
- 프로젝트가 아직 생성되지 않은 경우(.xpr 파일 없음)
- 기존 빌드 스크립트만 수정하면 되는 경우(직접 편집)
- 타이밍 분석 또는 설계 디버깅이 필요한 경우(기준 설정 또는 다른 스킬 사용)
사전 요구 사항
실행 전에 Vivado 프로젝트가 다음 조건을 만족해야 합니다.
- 유효한 PART 속성 설정
- 프로젝트에 소스 파일 추가
- TOP 모듈 구성
- DFX: PR_FLOW 속성 활성화
- 세그먼트 구성: SEGMENTED_CONFIGURATION 속성 설정(Versal Gen2 장치)
5단계 파이프라인 (+ 선택적 2.5단계)
모든 Tcl 프로시저는 helper-procedures/helper_scripts.tcl에 있습니다. 먼저 이 파일을 Vivado에서 소스로 불러온 후 각 단계를 순차적으로 실행하십시오.
source <skill-path>/helper-procedures/helper_scripts.tcl
1단계: 프로젝트 흐름 감지
detect_project_flow를 실행하여 프로젝트 유형을 식별합니다. 3단계에 필요한 flow_info 딕셔너리를 반환합니다.
set flow_info [detect_project_flow]
set flow_type [dict get $flow_info flow_type]
다음 중 하나를 반환합니다: "Standard", "DFX (Partial Reconfiguration)", "Segmented Configuration", "DFX + Segmented Configuration" — 블록 디자인 컨테이너가 감지되면 선택적 "+ IPI BDC" 접미사가 추가됩니다.
감지 로직 및 경계 사례에 대한 자세한 내용은 detect-project-flow/REFERENCE.md를 참조하십시오.
2단계: 소스 위치 분석
analyze_source_locations를 실행하여 소스를 Push Button(모두 로컬), Remote(모두 외부), 또는 Mixed(혼합)로 분류합니다.
set scenario_info [analyze_source_locations]
set scenario [dict get $scenario_info scenario]
scenario가 "Remote"인 경우 3단계를 건너뜁니다. 소스가 외부 저장소에 있으며 복제되어서는 안 됩니다.
자세한 내용은 analyze-source-locations/REFERENCE.md를 참조하십시오.
2.5단계: 생성된 출력물 보존? (선택적, 대화형)
일부 IP/BD의 기존 .gen 출력물을 재빌드 시 Tcl에서 완전히 재생성되도록 두지 않고 유지할지 묻습니다. 이 단계는 이 스킬의 이전 버전에는 없으며 완전히 선택 사항입니다. 실행 방법은 파이프라인을 누가 구동하는지에 따라 다릅니다.
Vivado 세션에 직접 명령을 입력하는 인간 (GUI Tcl 콘솔 또는 실제 tty가 있는 수동 배치 세션) — 2026-09-21 기준으로 특별한 작업이 필요하지 않습니다: 3단계(export_all_sources)를 호출하기 전에 직접 응답하지 않은 경우, stdin에 실제 tty가 있는지 감지하여 프로젝트에 적격 항목이 있으면 진행하기 전에 자동으로 프롬프트를 표시합니다. 프롬프트가 발생하는 정확한 시점을 제어하려면 사전에 prompt_preserve_outputs를 명시적으로 호출할 수도 있습니다.
set preserve_selection [prompt_preserve_outputs]
- "n"(또는 Enter만 누름) 응답은
{enabled 0 ips {} bds {} cache_dir {}}을 반환합니다. 3단계와 5단계는 이 기능이 존재하기 전과 정확히 동일하게 작동합니다. - "y" 응답은 적격한 모든 독립형 IP 및 사용자 생성 BD(블록 디자인 외부에 있는 XCI 포함)를
list_preservable_outputs를 통해 나열하고, 보존할 항목을 선택하도록 합니다(all또는 쉼표로 구분된 목록). 이 선택은 별개의 최상위 항목에 걸쳐 혼합/부분적입니다(일부 독립형 IP/BD는 보존되고 다른 항목은 그렇지 않음) — 이것이 기본 지원 사례입니다. 단일 BD 내부에서는 부분적이지 않습니다: BD는 하나의 전체 단위로 보존되며, BD 내부에서 사용자 지정된 IP 중 어떤 것은 보존하고 어떤 것은 재생성할지 선택할 수 없습니다(의도적인 범위 제한으로 확인됨, 버그가 아님 — Q4 개선 사항으로 표시됨). - 선택한 항목에 아직
.gen출력물이 없는 경우(생성/합성되지 않음),export_all_sources는 경고하고 보존하지 않고 정상적으로 내보냅니다. 아직 보존할 것이 없는 것은 심각한 오류가 아니지만, 불완전한 캐시 항목을 자동으로 생성하지도 않습니다. - 보존은 원격 캐시만 지원합니다: 이 프로젝트 외부의 디렉토리입니다. IP/BD를 선택한 후 해당 캐시 디렉토리의 절대 경로를 입력하라는 메시지가 표시됩니다. 잘못된 경로(상대 경로, 빈 경로, 또는 프로젝트 내부에 중첩된 경로)는 이 내보내기에 대해 보존을 비활성화합니다.
이 프로시저는 gets stdin에서 차단되므로 실제 tty가 연결된 경우에만 작동합니다. 이것이 바로 export_all_sources가 이제 자동 호출 전에 확인하는 조건(_rc_stdin_is_tty)입니다.
자동화된 CI / 회귀 파이프라인 (run_pipeline.tcl 스타일 하네스) — 이 단계를 완전히 건너뛰고 3단계와 5단계에 {}(기본값)을 전달하십시오. 이렇게 하면 완전히 자동화된 기존 5단계 동작이 변경되지 않고 유지됩니다.
에이전트 기반 (AI 에이전트가 Bash/배치 모드 Tcl 호출을 통해 Vivado를 구동하고, 사람과 대화하는 경우) — prompt_preserve_outputs를 호출하지 마십시오: gets stdin이 차단될 실제 tty가 없으므로 EOF만 읽고 보존을 자동으로 비활성화하며 표시되는 프롬프트가 없습니다. 대신:
list_preservable_outputs(순수 쿼리, stdin 없음)를 호출하여 적격 항목을 확인합니다.- IP 또는 BD를 반환하면 대화에서 인간에게 보존할 항목(있는 경우)과 보존된 출력물을 저장할 프로젝트 외부 캐시 디렉토리의 절대 경로를 직접 묻습니다.
build_preserve_selection $chosen_ips $chosen_bds $cache_dir을 인간의 답변으로 호출하여preserve_selection딕셔너리를 얻습니다.list_preservable_outputs가 아무것도 반환하지 않으면 묻지 마십시오. 보존할 것이 없습니다.
set items [list_preservable_outputs]
# ... 대화에서 인간에게 물어본 후:
set preserve_selection [build_preserve_selection $chosen_ips $chosen_bds $cache_dir]
반환된 preserve_selection을 3단계(export_all_sources)에 전달하십시오. 자세한 내용은 helper-procedures/REFERENCE.md를 참조하십시오.
3단계: 모든 소스 내보내기 (조건부)
2단계에서 "Remote"가 반환되면 이 단계를 건너뜁니다. 그렇지 않으면 RTL, 제약 조건, IP(write_ip_tcl을 통한 Tcl), 블록 디자인(write_bd_tcl을 통한 Tcl), 시뮬레이션 파일, 데이터 파일을 구성된 디렉토리로 내보냅니다.
DFX/세그먼트 구성 관련 내보내기(pblocks, DCP, NoC 솔루션)를 활성화하려면 1단계의 flow_info를 전달하십시오. 2.5단계의 preserve_selection을 전달하거나 생략하여 IP/BD별 출력물 보존을 제어하십시오. 생략하고 stdin이 실제 tty인 경우, export_all_sources가 보존을 자동으로 건너뛰지 않고 자체적으로 프롬프트를 표시합니다(위 2.5단계 참조). preserve_selection에 지정된 IP/BD의 경우, 해당 항목의 .srcs/.gen 하위 트리(그 외에는 없음)만 선택 항목이 지정한 외부 cache_dir로 복사됩니다. 절대 export_dir/RevisionControl/ 자체로 복사되지 않습니다.
if {$scenario ne "Remote"} {
export_all_sources "RevisionControl" $flow_info $preserve_selection
}
필터링 규칙, BD-IP 처리, DFX 내보내기에 대한 자세한 내용은 export-all-sources/REFERENCE.md를 참조하십시오.
4단계: 프로젝트 설정 캡처
모든 기본값이 아닌 프로젝트 속성을 재빌드 시 복원할 수 있는 Tcl 스크립트로 저장합니다.
file mkdir RevisionControl/Scripts
capture_project_settings "RevisionControl/Scripts/project_settings.tcl"
캡처 항목: PART, BOARD_PART, TARGET_LANGUAGE, PR_FLOW, SEGMENTED_CONFIGURATION, TOP, VERILOG_DEFINE, 합성/구현 지시어, 파일별 속성(VHDL_LIBRARY, IS_GLOBAL_INCLUDE).
자세한 내용은 capture-project-settings/REFERENCE.md를 참조하십시오.
5단계: 빌드 스크립트 생성
한 번의 명령으로 프로젝트를 재생성하는 build.tcl을 생성합니다.
generate_build_script "RevisionControl/Scripts/build.tcl" "RevisionControl" $scenario_info
생성된 스크립트는 상대 경로를 사용하고, 로컬 소스를 가져오며(import_files), 원격 소스를 제자리에서 참조하고(add_files), Tcl 스크립트에서 IP와 BD를 재생성하고, OOC IP 실행을 생성하고, BD 대상을 생성하고, project_settings.tcl을 소스로 불러오고, 컴파일 순서를 마무리합니다. 2.5단계에서 보존된 IP/BD의 경우, 대신 해당 항목의 .srcs/.gen을 외부 캐시 디렉토리에서 복원하고 add_files/read_ip/read_bd로 직접 추가합니다. write_ip_tcl/write_bd_tcl 재생이 없고 재합성도 없으며, 보존되지 않은 모든 IP/BD는 여전히 표준 Tcl 재생성 경로를 거칩니다. 이 분기는 IP/BD별로 이루어지며, 전체 프로젝트에 대해 전역적으로 적용되지 않습니다. 재빌드 시 캐시 디렉토리(또는 그 안의 특정 보존 항목 데이터)가 없으면 생성된 스크립트는 자동으로 재생성으로 대체하지 않고 하드 오류를 발생시킵니다.
DFX RM 순서 및 .gen 누락 처리에 대한 자세한 내용은 generate-build-script/REFERENCE.md를 참조하십시오.
파이프라인 데이터 흐름
1단계: detect_project_flow
→ flow_info 딕셔너리 (3단계로 전달)
2단계: analyze_source_locations
→ 시나리오 ("Push Button" / "Remote" / "Mixed")
→ Remote인 경우: 3단계 건너뜀
2.5단계: prompt_preserve_outputs (선택적, 대화형 전용)
→ preserve_selection 딕셔너리 {enabled, ips, bds, cache_dir} (3단계로 전달)
→ 생략/거절됨 ⇒ {} ⇒ 3단계와 5단계는 이 기능이 존재하기 전과 정확히 동일하게 작동
→ 생략되고 stdin이 실제 tty이며 적격 항목이 있는 경우, 3단계가 자동으로 호출
(2026-09-21 추가) 보존 없음을 자동으로 기본값으로 설정하는 대신 사용자를 대신함
— tty 없음(CI/에이전트) ⇒ 변경 없음
→ cache_dir은 프로젝트 외부의 절대 경로여야 함(원격 캐시 전용)
— 잘못된/누락된 경로는 이 내보내기에 대해 보존을 비활성화함
3단계: export_all_sources(dir, flow_info, preserve_selection)
→ Sources/ 디렉토리 (RTL, IP, BD, 제약 조건 포함; dir 자체는 preserve_selection에
따라 모양이 변경되지 않음)
→ (preserve_selection이 항목을 선택한 경우에만) 각 보존된 항목의 자체 .srcs/.gen
하위 트리가 cache_dir로 복사됨 — dir 자체로 복사되지 않음
4단계: capture_project_settings(file)
→ project_settings.tcl
5단계: generate_build_script(file, dir, scenario_info)
→ build.tcl (자동화된 재빌드; 재빌드 시 cache_dir에서 보존된 항목의 .srcs/.gen을
복원함 — cache_dir 또는 그 안의 보존된 항목 데이터가 없으면 하드 오류 발생)
출력 구조
RevisionControl/은 라이브 Vivado 프로젝트 옆에 내보내지며, 2.5단계 보존 사용 여부에 따라 자체 구조가 변경되지 않습니다. 원본 프로젝트의 <proj>.gen/, <proj>.srcs/ 또는 <proj>.xpr를 포함하지 않으며(해당 파일들은 원래 위치에 그대로 유지됨), XPR은 어떤 흐름에서도 리비전 관리되지 않습니다.
project_1.gen/ # 라이브 원본 Vivado 프로젝트 — 형제, 수정되지 않음
project_1.srcs/
project_1.xpr
RevisionControl/
├── Sources/
│ ├── RTL/ # Verilog/SV/VHDL 소스
│ ├── Constraints/ # XDC 파일 (+ DFX용 pblocks.xdc)
│ ├── IP/ # write_ip_tcl 스크립트 — 보존되지 않은 독립형 IP만
│ │ # (.xci 복사 없음); 보존된 IP는 여기에서 완전히 제외됨
│ ├── BD/ # write_bd_tcl 스크립트 — 보존되지 않은 BD만
│ │ # (.bd 복사 없음); 보존된 BD는 여기에서 완전히 제외되며
│ │ # Tcl 대체 경로 없음
│ ├── Simulation/ # 테스트벤치
│ ├── Data/ # .mem, .coe, .mif, .hex, .elf, .csv 파일
│ ├── Scripts/ # Tcl 사전/사후 후크 스크립트
│ ├── Checkpoints/ # (DFX 전용) 잠긴 정적 DCP
│ └── NoC/ # (Segmented Config 전용) .ncr 파일
└── Scripts/
├── project_settings.tcl
└── build.tcl
보존된 출력물 (2.5단계에서 "예" 응답, ≥1개 IP/BD 선택)
2.5단계에서 항목을 보존한 경우, 유일한 산출물은 외부의 원격 캐시 디렉토리입니다. 사용자가 제공한 프로젝트 외부 경로(preserve_selection의 cache_dir)이며, RevisionControl/에 복사되지 않고 Git에서 추적되지 않습니다.
<cache_dir>/
└── project_1/
├── ip/
│ └── <ip_name>/
│ ├── srcs/ # 해당 IP의 자체 .srcs 디렉토리 복사본 (.xci 및 관련 파일)
│ └── gen/ # 해당 IP의 자체 .gen 디렉토리 복사본 (OOC 합성 출력물)
└── bd/
└── <bd_name>/
├── srcs/ # 해당 BD의 자체 .srcs 디렉토리 복사본 (.bd, IP 사용자 지정 등)
└── gen/ # 해당 BD의 자체 .gen 디렉토리 복사본 (OOC 합성 출력물)
재빌드 시 build.tcl은 캐시에서 이러한 보존된 출력물을 복원하고, write_ip_tcl/write_bd_tcl 재생성 대신 add_files/read_ip/read_bd를 통해 직접 추가합니다. 캐시 디렉토리(또는 보존된 항목의 데이터)가 없으면 하드 오류가 발생합니다. 이 캐시 디렉토리는 Git에서 추적되어서는 안 됩니다. 권장되는 CI/CD 워크플로는 파이프라인 아티팩트로 보존하거나 네트워크 공유 위치에 보관하는 것입니다.
참조 자료
| 문서 | 설명 |
|---|---|
| detect-project-flow/REFERENCE.md | 감지 로직, 장치 속성, DFX/BDC/세그먼트 구성 감지 경계 사례 |
| analyze-source-locations/REFERENCE.md | 소스 분류 규칙, Remote 시나리오 감지, IPI BDC 참조 처리 |
| helper-procedures/REFERENCE.md | 2.5단계 보존 API, list_preservable_outputs, build_preserve_selection, 에이전트 워크플로 |
| export-all-sources/REFERENCE.md | 내보내기 규칙, 필터링, BD-IP 처리, DFX/세그먼트 구성 전용 내보내기, 보존 통합 |
| capture-project-settings/REFERENCE.md | 캡처된 속성의 전체 목록, 파일별 속성 처리, 예외 |
| generate-build-script/REFERENCE.md | 생성된 스크립트 구조, DFX RM 순서, 보존된 항목을 위한 캐시 복원 경로, 오류 처리 |