chemmy-11/vivado-revision-control

Nota de adaptación local (no es texto original de AMD; añadido el 18-10-2026 por sesión DSH)

• Diferencia de cadena de herramientas: Esta máquina utiliza vivado-mcp de terceros (instalación activa <vivado-mcp>, 32 herramientas), no el oficial vivado-mcp-server; el repositorio <repositorio EIF>\vivado-mcp es una copia sin cambios dentro del repositorio, no es una instancia en ejecución (el cliente debe establecer explícitamente PYTHONPATH=<vivado-mcp>\site, de lo contrario _mcp_pilot_paths.pth del venv apuntará a la copia de ruta china de .mcp-pilot → start_session falla silenciosamente).
• Mapeo de herramientas: 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 (solo runme.log) o 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.
• Cuando la sesión no tiene herramientas MCP montadas, se usa el puente CLI: python <vivado-mcp>\mcp_ctl.py session "<Tcl multilínea>" (equivalente a run_tcl), call <tool> --args-file <json>, list. Una llamada ejecuta un proceso MCP, las sesiones de varios pasos deben escribirse como una sola session. (24-10-2026: ya configurado en el perfil de escritorio como mcp__vivado__*, necesita reiniciar el host para que surta efecto; si no funciona, el puente CLI sigue siendo la única vía).
• Versión real: Vivado 2023.1 (línea base oficial 2026.1); Python usa <intérprete de Python: ver python en config.yml (install.ps1 escribe el valor real)>.
• Búsqueda de documentación: Esta máquina no tiene vivado_doc_search, se usa web_fetch (docs.amd.com / docs oficiales) o este proyecto <project_root>\docs.
• Restricción estricta: La ruta de instalación de MCP debe ser puramente ASCII (las rutas chinas se dañan con la decodificación GBK de Vivado Tcl); las sesiones de Vivado son globalmente seriales para síntesis, implementación y simulación.

Habilidad de Control de Revisiones Vivado

Esta habilidad automatiza la configuración de control de revisiones para proyectos Vivado mediante un pipeline de 5 pasos, más un paso interactivo opcional (Paso 2.5) para preservar salidas generadas existentes. Funciona con proyectos RTL estándar, IPI Block Designs (incluyendo Block Design Containers), DFX (Reconfiguración Parcial) y proyectos de Configuración Segmentada Versal.

El pipeline detecta el tipo de proyecto, analiza las ubicaciones de las fuentes, exporta componentes, captura configuraciones y genera un script de compilación, produciendo un directorio autocontenido que puede recrear el proyecto desde cero.

Cuándo usar esta habilidad

• Configurar control de versiones para cualquier proyecto Vivado
• Hacer que un proyecto sea portátil para miembros del equipo o CI/CD
• Exportar y organizar todas las fuentes del proyecto
• Crear scripts de compilación automatizados para compilaciones reproducibles
• Manejar control de revisiones para DFX, BDC o Configuración Segmentada

Cuándo NO usar esta habilidad

• El proyecto aún no se ha creado (no existe un archivo .xpr)
• Solo se necesita modificar un script de compilación existente (edítelo directamente)
• Se necesita análisis de temporización o depuración del diseño (use habilidades de referencia u otras)

Prerrequisitos

Antes de ejecutar, el proyecto Vivado debe estar abierto con:

• Una propiedad PART válida establecida
• Archivos fuente agregados al proyecto
• Módulo TOP configurado
• Para DFX: propiedad PR_FLOW habilitada
• Para Configuración Segmentada: propiedad SEGMENTED_CONFIGURATION establecida (o dispositivo Versal Gen2)

Pipeline de 5 Pasos (+ Paso 2.5 opcional)

Todos los procedimientos Tcl residen en helper-procedures/helper_scripts.tcl. Fuente este archivo primero en Vivado, luego ejecute cada paso secuencialmente.

source <ruta-habilidad>/helper-procedures/helper_scripts.tcl

Paso 1: Detectar Flujo del Proyecto

Ejecute detect_project_flow para identificar el tipo de proyecto. Esto devuelve un diccionario flow_info necesario para el Paso 3.

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

Devuelve uno de: "Standard", "DFX (Partial Reconfiguration)", "Segmented Configuration", "DFX + Segmented Configuration" — con el sufijo opcional "+ IPI BDC" si se detectan Block Design Containers.

Para más detalles sobre la lógica de detección y casos límite, lea detect-project-flow/REFERENCE.md.

Paso 2: Analizar Ubicaciones de Fuentes

Ejecute analyze_source_locations para clasificar las fuentes como Push Button (todas locales), Remote (todas externas) o Mixed.

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

Si scenario es "Remote", omita completamente el Paso 3 — las fuentes residen en repositorios externos y no deben duplicarse.

Para más detalles, lea analyze-source-locations/REFERENCE.md.

Paso 2.5: ¿Preservar Salidas Generadas? (opcional, interactivo)

Pregunte si se deben mantener las salidas .gen existentes para IPs/BDs seleccionados en lugar de permitir que se regeneren completamente desde Tcl en la reconstrucción. Este paso no existe en versiones anteriores de esta habilidad y es completamente optativo. Cómo ejecutarlo depende de quién esté impulsando el pipeline:

Humano escribiendo directamente en una sesión Vivado activa (consola Tcl de GUI, o una sesión por lotes con un tty real) — a partir del 21-09-2026, no necesita hacer nada especial: si llama al Paso 3 (export_all_sources) sin haber respondido esto usted mismo, detecta un tty real en stdin y, si el proyecto tiene algo elegible, le solicita automáticamente antes de continuar. Aún puede llamar a prompt_preserve_outputs explícitamente de antemano si prefiere controlar exactamente cuándo ocurre la solicitud:

set preserve_selection [prompt_preserve_outputs]

• Responder "n" (o simplemente presionar Enter) devuelve {enabled 0 ips {} bds {} cache_dir {}} — los Pasos 3 y 5 se comportan exactamente igual que antes de que existiera esta funcionalidad.
• Responder "y" lista cada IP independiente elegible y BD creado por el usuario (a través de list_preservable_outputs) — incluyendo XCIs que viven fuera de cualquier Block Design — y le permite elegir cuáles preservar (all o una lista separada por comas). Esta selección es mixta/parcial entre elementos de nivel superior separados (algunas IPs/BDs independientes preservadas, otras no) — ese es el caso principal soportado. No es parcial dentro de un solo BD: un BD se preserva como una unidad completa, y no puede elegir qué IPs personalizadas dentro de él se preservan vs. regeneran (confirmado como un límite de alcance intencional, no un error — señalado como posible mejora para Q4).
• Si un elemento seleccionado no tiene salida .gen aún (nunca generado/sintetizado), export_all_sources advierte y lo exporta normalmente en lugar de preservarlo — no hay nada que preservar aún, no es un fallo grave, pero tampoco crea silenciosamente una entrada de caché incompleta.
• La preservación solo admite un caché remoto: un directorio fuera de este proyecto. Después de elegir IPs/BDs, se le solicita la ruta absoluta de ese directorio de caché. Una ruta no válida (relativa, vacía o anidada dentro del proyecto) deshabilita la preservación para esta exportación.

Este procedimiento se bloquea en gets stdin, por lo que solo funciona con un tty real adjunto — que es exactamente la condición que export_all_sources ahora verifica (_rc_stdin_is_tty) antes de invocarlo automáticamente.

CI automatizado / pipelines de regresión (infraestructuras de estilo run_pipeline.tcl) — omita este paso por completo y pase {} (el valor predeterminado) a los Pasos 3 y 5. Esto preserva el comportamiento antiguo completamente automatizado de 5 pasos sin cambios.

Agéntico (un agente de IA que impulsa Vivado a través de llamadas Bash/Tcl en modo por lotes, chateando con un humano) — no llame a prompt_preserve_outputs: su gets stdin no tiene ningún tty real en el que bloquearse y simplemente leerá EOF, deshabilitando silenciosamente la preservación sin ninguna solicitud visible. En su lugar:

1. Llame a list_preservable_outputs (consulta pura, sin stdin) para ver qué es elegible.
2. Si devuelve algunas IPs o BDs, pregúntele directamente al humano en la conversación cuáles (si alguno) desea preservar, Y una ruta absoluta a un directorio de caché fuera del proyecto para almacenar las salidas preservadas.
3. Llame a build_preserve_selection $chosen_ips $chosen_bds $cache_dir con las respuestas del humano para obtener el diccionario preserve_selection.
4. Si list_preservable_outputs no devuelve nada, omita preguntar — no hay nada que preservar.

set items [list_preservable_outputs]
# ... preguntar al humano en la conversación, luego:
set preserve_selection [build_preserve_selection $chosen_ips $chosen_bds $cache_dir]

Pase el preserve_selection devuelto al Paso 3 (export_all_sources). Para más detalles, lea helper-procedures/REFERENCE.md.

Paso 3: Exportar Todas las Fuentes (condicional)

Omita este paso si el Paso 2 devolvió "Remote". De lo contrario, exporte RTL, restricciones, IP (como Tcl a través de write_ip_tcl), Block Designs (como Tcl a través de write_bd_tcl), archivos de simulación y archivos de datos a un directorio organizado.

Pase flow_info del Paso 1 para habilitar exportaciones específicas de DFX/Configuración Segmentada (pblocks, DCPs, soluciones NoC). Pase preserve_selection del Paso 2.5 (u omítalo) para controlar la preservación de salidas por IP/BD. Si lo omite y stdin es un tty real, export_all_sources lo solicita por sí mismo (consulte el Paso 2.5 anterior) en lugar de omitir silenciosamente la preservación. Para cualquier IP/BD nombrada en preserve_selection, su propio subárbol .srcs/.gen (nada más) se copia en el cache_dir externo que especifica la selección — nunca en el propio export_dir/RevisionControl/.

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

Para más detalles sobre reglas de filtrado, manejo de BD-IP y exportaciones DFX, lea export-all-sources/REFERENCE.md.

Paso 4: Capturar Configuraciones del Proyecto

Guarde todas las propiedades del proyecto no predeterminadas en un script Tcl que pueda restaurarlas durante la reconstrucción.

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

Captura: PART, BOARD_PART, TARGET_LANGUAGE, PR_FLOW, SEGMENTED_CONFIGURATION, TOP, VERILOG_DEFINE, directivas de síntesis/implementación y propiedades específicas de archivos (VHDL LIBRARY, IS_GLOBAL_INCLUDE).

Para más detalles, lea capture-project-settings/REFERENCE.md.

Paso 5: Generar Script de Compilación

Cree build.tcl para la recreación del proyecto con un solo comando.

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

El script generado usa rutas relativas, importa fuentes locales (import_files), hace referencia a fuentes remotas en su lugar (add_files), recrea IP y BD a partir de scripts Tcl, crea ejecuciones OOC IP, genera objetivos BD, fuentea project_settings.tcl y finaliza el orden de compilación. Para cualquier IP/BD preservada en el Paso 2.5, en su lugar restaura el .srcs/.gen de ese elemento desde el directorio de caché externo y add_files/read_ip/read_bds directamente — sin reproducción de write_ip_tcl/write_bd_tcl, sin resíntesis — mientras que cada IP/BD no preservada aún pasa por la ruta estándar de regeneración Tcl. Esta ramificación es por IP/BD, nunca global para todo el proyecto. Si el directorio de caché (o los datos de un elemento preservado específico dentro de él) falta en el momento de la reconstrucción, el script generado genera un error grave en lugar de recurrir silenciosamente a la regeneración.

Para más detalles, ordenamiento RM de DFX y manejo de .gen faltante, lea generate-build-script/REFERENCE.md.

Flujo de Datos del Pipeline

Paso 1: detect_project_flow
  → diccionario flow_info (pasado al Paso 3)

Paso 2: analyze_source_locations
  → escenario ("Push Button" / "Remote" / "Mixed")
  → Si es Remote: omitir Paso 3

Paso 2.5: prompt_preserve_outputs (opcional, solo interactivo)
  → diccionario preserve_selection {enabled, ips, bds, cache_dir} (pasado al Paso 3)
  → omitido/rechazado ⇒ {} ⇒ Pasos 3 y 5 se comportan exactamente como antes de que existiera
  → si se omite Y stdin es un tty real Y algo es elegible, el Paso 3
    lo llama automáticamente en su nombre (añadido el 21-09-2026) en lugar de
    predeterminarse silenciosamente a sin preservación — sin tty (CI/agéntico) ⇒ sin cambios
  → cache_dir debe ser una ruta absoluta FUERA del proyecto (solo caché remoto)
    — una ruta no válida/faltante deshabilita la preservación para esta exportación

Paso 3: export_all_sources(dir, flow_info, preserve_selection)
  → directorio Sources/ con RTL, IP, BD, Restricciones (el directorio en sí nunca
    cambia de forma basado en preserve_selection)
  → (solo si preserve_selection seleccionó algo) el subárbol .srcs/.gen de CADA elemento
    preservado se copia en cache_dir — nunca en el propio dir

Paso 4: capture_project_settings(file)
  → project_settings.tcl

Paso 5: generate_build_script(file, dir, scenario_info)
  → build.tcl (reconstrucción automatizada; restaura el .srcs/.gen de cualquier elemento
    preservado desde cache_dir en el momento de la reconstrucción — error grave si falta
    cache_dir o los datos de un elemento preservado dentro de él)

Estructura de Salida

RevisionControl/ se exporta junto a el proyecto Vivado activo y su propia forma nunca cambia según si se usó la preservación del Paso 2.5 — nunca contiene <proj>.gen/, <proj>.srcs/ o <proj>.xpr del proyecto original (esos permanecen intactos donde están), y el XPR nunca está bajo control de revisiones en ningún flujo.

project_1.gen/            # proyecto Vivado original activo — hermano, intacto
project_1.srcs/
project_1.xpr

RevisionControl/
├── Sources/
│   ├── RTL/              # fuentes Verilog/SV/VHDL
│   ├── Constraints/      # archivos XDC (+ pblocks.xdc para DFX)
│   ├── IP/               # scripts write_ip_tcl — solo IPs independientes no
│   │                     # preservadas (no se copia .xci); las IPs preservadas se
│   │                     # omiten aquí por completo (ver más abajo)
│   ├── BD/               # scripts write_bd_tcl — solo BDs no preservados
│   │                     # (no se copia .bd); los BDs preservados se omiten aquí
│   │                     # por completo, sin respaldo Tcl (ver más abajo)
│   ├── Simulation/       # Testbenches
│   ├── Data/             # archivos .mem, .coe, .mif, .hex, .elf, .csv
│   ├── Scripts/          # scripts Tcl de hook pre/post
│   ├── Checkpoints/      # (solo DFX) DCPs estáticos bloqueados
│   └── NoC/              # (solo Configuración Segmentada) archivos .ncr
└── Scripts/
    ├── project_settings.tcl
    └── build.tcl

Salidas preservadas (Paso 2.5 respondió "Sí", ≥1 IP/BD seleccionados)

Si el Paso 2.5 preservó algo, el único artefacto es un directorio de caché remoto externo — una ruta fuera del proyecto que el usuario proporcionó (cache_dir en preserve_selection), nunca copiada en RevisionControl/ y nunca rastreada por git:

<cache_dir>/
└── project_1/
    ├── ip/
    │   └── <nombre_ip>/
    │       ├── srcs/     # copia del directorio .srcs de esa IP (el .xci

... [truncado para traducción]