chemmy-11/vivado-revision-control

Hinweise zur lokalen Anpassung (nicht AMD-Original; 2026-10-18 durch DSH-Konversation hinzugefügt)

• Toolchain-Unterschied: Lokal wird drittanbieter vivado-mcp verwendet (aktuelle Installation <vivado-mcp>, 32 Tools), nicht der offizielle vivado-mcp-server; der <EIF-Repository>\vivado-mcp im Repository ist eine unveränderte Mitnahme-Kopie, keine laufende Instanz (der Client muss explizit PYTHONPATH=<vivado-mcp>\site setzen, sonst trifft _mcp_pilot_paths.pth der venv auf einen chinesischen Pfad im .mcp-pilot und start_session schlägt leise fehl).
• Tool-Mapping: 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 (nur runme.log) oder 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.
• Falls keine MCP-Tools in der Sitzung bereitstehen, wird die CLI-Brücke verwendet: python <vivado-mcp>\mcp_ctl.py session "<mehrzeiliges Tcl>" (äquivalent zu run_tcl), call <tool> --args-file <json>, list. Ein Aufruf erzeugt einen MCP-Prozess; mehrschrittige Sitzungen müssen als einzelner session-Aufruf formuliert werden. (2026-10-24 wurden im Desktop-Profil mcp__vivado__* konfiguriert; Neustart des Hosts erforderlich; falls nicht wirksam, bleibt die CLI-Brücke der einzige Weg.)
• Versionsfakten: Vivado 2023.1 (offizielle Baseline 2026.1); Python verwendet <Python-Interpreter: siehe config.yml unter python (install.ps1 schreibt tatsächlichen Wert)>.
• Dokumentensuche: Lokal kein vivado_doc_search verfügbar; stattdessen web_fetch (docs.amd.com / offizielle Doku) oder <project_root>\docs dieses Projekts verwenden.
• Harte Einschränkung: Der MCP-Installationspfad muss rein ASCII sein (chinesische Pfade werden durch die GBK-Dekodierung von Vivado Tcl beschädigt); Vivado-Sitzungen und Synthese/Implementierung/Simulation sind global seriell.

Fähigkeit zur Vivado-Revisionskontrolle

Diese Fähigkeit automatisiert die Einrichtung der Revisionskontrolle für Vivado-Projekte durch eine 5-stufige Pipeline, plus einen optionalen interaktiven Schritt 2.5 zum Erhalten vorhandener generierter Ausgaben. Sie funktioniert mit Standard-RTL-Projekten, IPI Block Designs (einschließlich Block Design Containers), DFX (Partielle Rekonfiguration) und Versal segmentierten Konfigurationsprojekten.

Die Pipeline erkennt den Projekttyp, analysiert Quellpfade, exportiert Komponenten, erfasst Einstellungen und generiert ein Build-Skript – und erzeugt so ein eigenständiges Verzeichnis, das das Projekt von Grund auf neu erstellen kann.

Wann diese Fähigkeit verwendet werden sollte

• Einrichten der Versionskontrolle für ein beliebiges Vivado-Projekt
• Portabelmachen eines Projekts für Teammitglieder oder CI/CD
• Exportieren und Organisieren aller Projektquellen
• Erstellen automatisierter Build-Skripte für reproduzierbare Builds
• Handhabung der Revisionskontrolle für DFX, BDC oder segmentierte Konfiguration

Wann diese Fähigkeit NICHT verwendet werden sollte

• Das Projekt wurde noch nicht erstellt (es existiert keine .xpr-Datei)
• Es muss lediglich ein vorhandenes Build-Skript geändert werden (direkt bearbeiten)
• Zeitanalyse oder Design-Debugging erforderlich (Baseline- oder andere Fähigkeiten verwenden)

Voraussetzungen

Vor der Ausführung muss das Vivado-Projekt geöffnet sein mit:

• Einer gültigen PART-Eigenschaft
• Zum Projekt hinzugefügte Quelldateien
• Konfiguriertem TOP-Modul
• Für DFX: PR_FLOW-Eigenschaft aktiviert
• Für segmentierte Konfiguration: SEGMENTED_CONFIGURATION-Eigenschaft gesetzt (oder Versal Gen2-Gerät)

5-Stufen-Pipeline (+ optionaler Schritt 2.5)

Alle Tcl-Prozeduren befinden sich in helper-procedures/helper_scripts.tcl. Diese Datei zuerst in Vivado einbinden, dann jeden Schritt nacheinander ausführen.

source <skill-path>/helper-procedures/helper_scripts.tcl

Schritt 1: Projektablauf erkennen

detect_project_flow ausführen, um den Projekttyp zu identifizieren. Dies gibt ein flow_info-Dictionary zurück, das von Schritt 3 benötigt wird.

set flow_info [detect_project_flow]
set flow_type [dict get $flow_info flow_type]

Gibt einen der folgenden Werte zurück: "Standard", "DFX (Partial Reconfiguration)", "Segmented Configuration", "DFX + Segmented Configuration" - mit optionalem Suffix "+ IPI BDC" wenn Block Design Containers erkannt werden.

Details zur Erkennungslogik und Grenzfällen finden Sie in detect-project-flow/REFERENCE.md.

Schritt 2: Quellorte analysieren

analyze_source_locations ausführen, um Quellen als Push Button (alle lokal), Remote (alle extern) oder Gemischt zu klassifizieren.

set scenario_info [analyze_source_locations]
set scenario [dict get $scenario_info scenario]

Wenn scenario "Remote" ist, Schritt 3 vollständig überspringen – Quellen befinden sich in externen Repositories und sollten nicht dupliziert werden.

Details finden Sie in analyze-source-locations/REFERENCE.md.

Schritt 2.5: Generierte Ausgaben erhalten? (optional, interaktiv)

Fragen, ob vorhandene .gen-Ausgaben für ausgewählte IPs/BDs behalten werden sollen, anstatt sie bei einem Neubuild vollständig aus Tcl neu generieren zu lassen. Dieser Schritt existiert in älteren Versionen dieser Fähigkeit nicht und ist vollständig optional. Die Ausführung hängt davon ab, wer die Pipeline steuert:

Mensch, der direkt in eine live Vivado-Sitzung eingibt (GUI-Tcl-Konsole oder manuell gesteuerte Batch-Sitzung mit echtem tty) – Stand 2026-09-21 ist nichts Besonderes erforderlich: Wenn Schritt 3 (export_all_sources) aufgerufen wird, ohne dass diese Frage bereits beantwortet wurde, erkennt die Funktion ein echtes tty auf stdin und fragt bei berechtigten Projekten automatisch nach, bevor sie fortfährt. prompt_preserve_outputs kann dennoch explizit vorher aufgerufen werden, um den genauen Zeitpunkt der Abfrage zu steuern:

set preserve_selection [prompt_preserve_outputs]

• Antwort "n" (oder einfach Enter) gibt {enabled 0 ips {} bds {} cache_dir {}} zurück – Schritte 3 und 5 verhalten sich dann genau wie vor Einführung dieser Funktion.
• Antwort "y" listet jede berechtigte eigenständige IP und jedes benutzererstellte BD auf (über list_preservable_outputs) – einschließlich XCIs, die außerhalb eines Block Designs leben – und ermöglicht die Auswahl, welche erhalten werden sollen (all oder eine Komma-getrennte Liste). Diese Auswahl ist gemischt/teilweise über separate übergeordnete Elemente (einige eigenständige IPs/BDs erhalten, andere nicht) – das ist der primär unterstützte Fall. Sie ist nicht teilweise innerhalb eines einzelnen BD: Ein BD wird als gesamte Einheit erhalten, und es können nicht einzelne darin angepasste IPs ausgewählt werden, die erhalten vs. regeneriert werden sollen (bestätigt als beabsichtigter Scope-Cut, kein Fehler – als mögliche Q4-Verbesserung markiert).
• Wenn ein ausgewähltes Element noch keine .gen-Ausgabe hat (nie generiert/synthetisiert), gibt export_all_sources eine Warnung aus und exportiert es normal, statt es zu erhalten – nichts zu erhalten ist kein schwerwiegender Fehler, erzeugt aber auch nicht stillschweigend einen unvollständigen Cache-Eintrag.
• Das Erhalten unterstützt nur einen Remote-Cache: ein Verzeichnis außerhalb dieses Projekts. Nach der Auswahl von IPs/BDs wird nach dem absoluten Pfad dieses Cache-Verzeichnisses gefragt. Ein ungültiger Pfad (relativ, leer oder innerhalb des Projekts verschachtelt) deaktiviert das Erhalten für diesen Export.

Diese Prozedur blockiert bei gets stdin, funktioniert also nur mit einem echten tty – genau das ist die Bedingung, die export_all_sources jetzt prüft (_rc_stdin_is_tty), bevor sie automatisch aufgerufen wird.

Automatisierte CI-/Regression-Pipelines (run_pipeline.tcl-artige Harness) - diesen Schritt vollständig überspringen und {} (die Voreinstellung) an Schritte 3 und 5 übergeben. Das erhält das alte vollautomatische 5-Stufen-Verhalten unverändert.

Agentic (ein KI-Agent, der Vivado über Bash/Batch-Modus-Tcl-Aufrufe steuert und mit einem Menschen chat) – prompt_preserve_outputs NICHT aufrufen: Dessen gets stdin hat kein echtes tty zum Blockieren und wird einfach EOF lesen, wodurch das Erhalten stillschweigend ohne sichtbare Eingabeaufforderung deaktiviert wird. Stattdessen:

1. list_preservable_outputs aufrufen (reine Abfrage, kein stdin) um zu sehen, was berechtigt ist.
2. Wenn IPs oder BDs zurückgegeben werden, den Menschen direkt im Gespräch fragen, welche (falls überhaupt) erhalten werden sollen, UND nach einem absoluten Pfad zu einem Cache-Verzeichnis außerhalb des Projekts, um die erhaltenen Ausgaben zu speichern.
3. build_preserve_selection $chosen_ips $chosen_bds $cache_dir mit den Antworten des Menschen aufrufen, um das preserve_selection-Dict zu erhalten.
4. Wenn list_preservable_outputs nichts zurückgibt, nicht fragen – es gibt nichts zu erhalten.

set items [list_preservable_outputs]
# ... den Menschen im Gespräch fragen, dann:
set preserve_selection [build_preserve_selection $chosen_ips $chosen_bds $cache_dir]

Das zurückgegebene preserve_selection an Schritt 3 (export_all_sources) übergeben. Details finden Sie in helper-procedures/REFERENCE.md.

Schritt 3: Alle Quellen exportieren (bedingt)

Diesen Schritt überspringen, wenn Schritt 2 "Remote" zurückgegeben hat. Andernfalls RTL, Constraints, IP (als Tcl über write_ip_tcl), Block Designs (als Tcl über write_bd_tcl), Simulationsdateien und Datendateien in ein organisiertes Verzeichnis exportieren.

flow_info aus Schritt 1 übergeben, um DFX-/segmentierte Konfiguration-spezifische Exporte (pblocks, DCPs, NoC-Lösungen) zu ermöglichen. preserve_selection aus Schritt 2.5 übergeben (oder weglassen), um die Erhaltung von Ausgaben pro IP/BD zu steuern. Wenn es weggelassen wird und stdin ein echtes tty ist, fragt export_all_sources selbst danach (siehe Schritt 2.5 oben), anstatt das Erhalten stillschweigend zu überspringen. Für jede IP/jedes BD, das in preserve_selection genannt ist, wird dessen eigener .srcs/.gen-Teilbaum (nichts anderes) in das externe cache_dirkopiert, das die Auswahl angibt – niemals inexport_dir/RevisionControl/` selbst.

if {$scenario ne "Remote"} {
    export_all_sources "RevisionControl" $flow_info $preserve_selection
}

Details zu Filterregeln, BD-IP-Behandlung und DFX-Exporten finden Sie in export-all-sources/REFERENCE.md.

Schritt 4: Projekteinstellungen erfassen

Alle nicht standardmäßigen Projekteigenschaften in einem Tcl-Skript speichern, das sie beim Neubuild wiederherstellen kann.

file mkdir RevisionControl/Scripts
capture_project_settings "RevisionControl/Scripts/project_settings.tcl"

Erfasst: PART, BOARD_PART, TARGET_LANGUAGE, PR_FLOW, SEGMENTED_CONFIGURATION, TOP, VERILOG_DEFINE, Synthese-/Implementierungs- Direktiven und dateispezifische Eigenschaften (VHDL LIBRARY, IS_GLOBAL_INCLUDE).

Details finden Sie in capture-project-settings/REFERENCE.md.

Schritt 5: Build-Skript generieren

build.tcl zur Projekterstellung mit einem Befehl erstellen.

generate_build_script "RevisionControl/Scripts/build.tcl" "RevisionControl" $scenario_info

Das generierte Skript verwendet relative Pfade, importiert lokale Quellen (import_files), referenziert Remote-Quellen direkt (add_files), erstellt IP und BD aus Tcl-Skripten nach, erzeugt OOC-IP-Runs, generiert BD-Ziele, bindet project_settings.tcl ein und finalisiert die Kompilierungsreihenfolge. Für jede IP/jedes BD, das in Schritt 2.5 erhalten wurde, stellt es stattdessen den .srcs/.gen-Teilbaum dieses Elements aus dem externen Cache-Verzeichnis wieder her und verwendet add_files/read_ip/read_bddirekt – keinewrite_ip_tcl/write_bd_tcl`- Wiedergabe, keine Neusynthese – während jede nicht erhaltene IP/jedes nicht erhaltene BD weiterhin den Standard-Tcl-Regenerationspfad durchläuft. Diese Verzweigung erfolgt pro IP/BD, niemals global für das gesamte Projekt. Fehlt das Cache-Verzeichnis (oder die Daten eines bestimmten erhaltenen Elements darin) zum Zeitpunkt des Neubuilds, führt das generierte Skript zu einem harten Fehler, anstatt stillschweigend auf Regeneration zurückzufallen.

Details zur DFX-RM-Reihenfolge und Behandlung fehlender .gen-Ausgaben finden Sie in generate-build-script/REFERENCE.md.

Pipeline-Datenfluss

Schritt 1: detect_project_flow
  → flow_info-Dict (an Schritt 3 übergeben)

Schritt 2: analyze_source_locations
  → scenario ("Push Button" / "Remote" / "Mixed")
  → Wenn Remote: Schritt 3 überspringen

Schritt 2.5: prompt_preserve_outputs (optional, nur interaktiv)
  → preserve_selection-Dict {enabled, ips, bds, cache_dir} (an Schritt 3 übergeben)
  → weggelassen/abgelehnt ⇒ {} ⇒ Schritte 3 und 5 verhalten sich genau wie vorher
  → weggelassen UND stdin ist echtes tty UND etwas ist berechtigt ⇒ Schritt 3
    ruft dies automatisch auf (hinzugefügt 2026-09-21) anstatt stillschweigend
    auf keine Erhaltung zu setzen – kein tty (CI/Agentic) ⇒ unverändert
  → cache_dir muss ein absoluter Pfad AUSSERHALB des Projekts (nur Remote-Cache)
    sein – ein ungültiger/fehlender Pfad deaktiviert das Erhalten für diesen Export

Schritt 3: export_all_sources(dir, flow_info, preserve_selection)
  → Sources/-Verzeichnis mit RTL, IP, BD, Constraints (dir selbst ändert seine
    Form nie basierend auf preserve_selection)
  → (nur wenn preserve_selection etwas ausgewählt hat) Eigener .srcs/.gen-Teilbaum
    jedes erhaltenen Elements wird in cache_dir kopiert – niemals in dir selbst

Schritt 4: capture_project_settings(file)
  → project_settings.tcl

Schritt 5: generate_build_script(file, dir, scenario_info)
  → build.tcl (automatisierter Neubuild; stellt bei Neubuild den .srcs/.gen jedes
    erhaltenen Elements aus cache_dir wieder her – harter Fehler, wenn cache_dir
    oder die Daten eines erhaltenen Elements darin fehlen)

Ausgabestruktur

RevisionControl/ wird neben das aktive Vivado-Projekt exportiert und seine Form ändert sich nie basierend darauf, ob die Erhaltung aus Schritt 2.5 verwendet wurde – es enthält niemals <proj>.gen/, <proj>.srcs/ oder <proj>.xpr aus dem ursprünglichen Projekt (diese bleiben unberührt, wo sie sind), und XPR wird in keinem Ablauf versioniert.

project_1.gen/            # aktives ursprüngliches Vivado-Projekt – nebengeordnet, unberührt
project_1.srcs/
project_1.xpr

RevisionControl/
├── Sources/
│   ├── RTL/              # Verilog/SV/VHDL-Quellen
│   ├── Constraints/      # XDC-Dateien (+ pblocks.xdc für DFX)
│   ├── IP/               # write_ip_tcl-Skripte – nur nicht erhaltene eigenständige
│   │                     # IPs (kein .xci kopiert); erhaltene IPs werden hier
│   │                     # vollständig übersprungen (siehe unten)
│   ├── BD/               # write_bd_tcl-Skripte – nur nicht erhaltene BDs
│   │                     # (kein .bd kopiert); erhaltene BDs werden hier
│   │                     # vollständig übersprungen, ohne Tcl-Fallback (siehe unten)
│   ├── Simulation/       # Testbenches
│   ├── Data/             # .mem, .coe, .mif, .hex, .elf, .csv-Dateien
│   ├── Scripts/          # Tcl-Pre/Post-Hook-Skripte
│   ├── Checkpoints/      # (nur DFX) gesperrte statische DCPs
│   └── NoC/              # (nur segmentierte Konfiguration) .ncr-Dateien
└── Scripts/
    ├── project_settings.tcl
    └── build.tcl

Erhaltene Ausgaben (Schritt 2.5 mit "Ja" beantwortet, ≥1 IP/BD ausgewählt)

Wenn Schritt 2.5 etwas erhalten hat, ist das einzige Artefakt ein externes Remote-Cache- Verzeichnis – ein Pfad außerhalb des Projekts, den der Benutzer angegeben hat (cache_dir in preserve_selection), niemals in RevisionControl/ kopiert und niemals git-verfolgt:

<cache_dir>/
└── project_1/
    ├── ip/
    │   └── <ip_name>/
    │       ├── srcs/     # Kopie des eigenen .srcs-Verzeichnisses dieser IP (das .xci
    │       │             # und alle zugehörigen Quelldateien)
    │       └── gen/      # Kopie des eigenen .gen-Verzeichnisses dieser IP (alle
    │                     # generierten Ausgaben, Syntheseergebnisse usw.)
    └── bd/
        └── <bd_name>/
            ├── srcs/     # Kopie des eigenen .srcs-Verzeichnisses dieses BD
            └── gen/      # Kopie des eigenen .gen-Verzeichnisses dieses BD

Alle nicht erhaltenen IPs/BDs folgen dem normalen Tcl-Regenerationspfad. Dies ist keine binäre Entscheidung für das gesamte Projekt – es ist pro IP/BD.

Nächste Schritte

Nachdem die Pipeline abgeschlossen ist:

1. Überprüfen Sie das exportierte RevisionControl/ auf Vollständigkeit
2. Initialisieren Sie ein Git-Repository im Projektverzeichnis (wenn nicht vorhanden):

   git init
   git add RevisionControl/
   git commit -m "Initialer Revisionskontrolle-Export für <Projektname>"
   

   Wichtig: Stellen Sie sicher, dass project_1.gen/, project_1.srcs/ und project_1.xpr in .gitignore ausgeschlossen sind – diese gehören nicht in die Versionskontrolle. Das Remote-Cache-Verzeichnis aus Schritt 2.5 (falls verwendet) sollte ebenfalls in .gitignore aufgenommen oder in einem separaten, nicht versionierten Speicherort verwaltet werden.
3. Testen Sie den Neubuild mit dem generierten Skript:

   vivado -mode batch -source RevisionControl/Scripts/build.tcl