Controle de Revisão para Projetos Vivado

Nota de Adaptação Local (não é texto original da AMD; 2026-10-18, adicionado por sessão DSH)

• Cadeia de ferramentas diferente: Esta máquina usa o vivado-mcp de terceiros (instalação atual <vivado-mcp>, 32 ferramentas), não o oficial vivado-mcp-server; dentro do repositório <EIF repo>\vivado-mcp é uma cópia intacta do repositório, não é a instância em execução (o cliente deve definir explicitamente PYTHONPATH=<vivado-mcp>\site, caso contrário o _mcp_pilot_paths.pth do venv encontrará a cópia chinesa em .mcp-pilot → start_session falha silenciosamente).
• Mapeamento de ferramentas: 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 (apenas runme.log) ou 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.
• Se a sessão não tiver ferramentas MCP montadas, usa a ponte CLI: python <vivado-mcp>\mcp_ctl.py session "<Tcl multilinha>" (equivalente a run_tcl), call <tool> --args-file <json>, list. Uma chamada por processo MCP; sessões de múltiplas etapas devem ser escritas como uma única session. (2026-10-24, o perfil desktop foi configurado com mcp__vivado__*; é necessário reiniciar o host para ativar; se não ativo, a ponte CLI ainda é o único caminho.)
• Fatos da versão: Vivado 2023.1 (linha de base oficial 2026.1); Python use <interpretador Python: veja python no config.yml (install.ps1 escreve o valor real)>.
• Pesquisa de documentação: Esta máquina não tem vivado_doc_search; use web_fetch (docs.amd.com / docs oficiais) ou este projeto <project_root>\docs.
• Restrição rígida: O caminho de instalação do MCP deve ser puramente ASCII (caminhos chineses são corrompidos pela decodificação GBK do Tcl do Vivado); as sessões do Vivado e síntese/implementação/simulação são globalmente seriais.

Skill de Controle de Revisão para Vivado

Esta skill automatiza a configuração de controle de revisão para projetos Vivado por meio de um pipeline de 5 etapas, mais uma Etapa 2.5 opcional para preservar saídas geradas existentes. Funciona com projetos padrão somente RTL, Block Designs IPI (incluindo Block Design Containers), DFX (Reconfiguração Parcial) e projetos de Configuração Segmentada Versal.

O pipeline detecta o tipo de projeto, analisa a localização das fontes, exporta componentes, captura configurações e gera um script de build — produzindo um diretório autocontido que pode recriar o projeto do zero.

Quando usar esta skill

• Configurar controle de versão para qualquer projeto Vivado
• Tornar um projeto portátil para membros da equipe ou CI/CD
• Exportar e organizar todas as fontes do projeto
• Criar scripts de build automatizados para builds reproduzíveis
• Lidar com controle de revisão de DFX, BDC ou Configuração Segmentada

Quando NÃO usar esta skill

• O projeto ainda não foi criado (nenhum arquivo .xpr existe)
• Apenas precisa modificar um script de build existente (edite-o diretamente)
• Precisa de análise de timing ou depuração de design (use habilidades de baselining ou outras)

Pré-requisitos

Antes de executar, o projeto Vivado deve estar aberto com:

• Uma propriedade PART válida definida
• Arquivos de origem adicionados ao projeto
• Módulo TOP configurado
• Para DFX: propriedade PR_FLOW ativada
• Para Configuração Segmentada: propriedade SEGMENTED_CONFIGURATION definida (ou dispositivo Versal Gen2)

Pipeline de 5 Etapas (+ Etapa 2.5 Opcional)

Todos os procedimentos Tcl residem em helper-procedures/helper_scripts.tcl. Carregue este arquivo primeiro no Vivado e, em seguida, execute cada etapa sequencialmente.

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

Etapa 1: Detectar Fluxo do Projeto

Execute detect_project_flow para identificar o tipo de projeto. Isso retorna um dicionário flow_info necessário para a Etapa 3.

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

Retorna um de: "Standard", "DFX (Partial Reconfiguration)", "Segmented Configuration", "DFX + Segmented Configuration" — com sufixo opcional "+ IPI BDC" se Block Design Containers forem detectados.

Para detalhes sobre a lógica de detecção e casos extremos, leia detect-project-flow/REFERENCE.md.

Etapa 2: Analisar Localizações das Fontes

Execute analyze_source_locations para classificar as fontes como Push Button (todas locais), Remoto (todas externas) ou Misto.

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

Se scenario for "Remote", pule a Etapa 3 completamente — as fontes residem em repositórios externos e não devem ser duplicadas.

Para detalhes, leia analyze-source-locations/REFERENCE.md.

Etapa 2.5: Preservar Saídas Geradas? (opcional, interativa)

Pergunte se deve manter as saídas .gen existentes para IPs/BDs selecionados em vez de deixá-los ser totalmente regenerados a partir do Tcl durante a reconstrução. Esta etapa não existe em versões anteriores desta skill e é totalmente opcional. Como executá-la depende de quem está conduzindo o pipeline:

Humano digitando diretamente em uma sessão Vivado ativa (console Tcl GUI ou uma sessão em lote manual com um tty real) — a partir de 2026-09-21, você não precisa fazer nada especial: se você chamar a Etapa 3 (export_all_sources) sem já ter respondido isso, ela detecta um tty real no stdin e, se o projeto tiver algo elegível, solicita automaticamente antes de prosseguir. Você ainda pode chamar prompt_preserve_outputs explicitamente antes, se preferir controlar exatamente quando o prompt ocorre:

set preserve_selection [prompt_preserve_outputs]

• Responder "n" (ou apenas pressionar Enter) retorna {enabled 0 ips {} bds {} cache_dir {}} — as Etapas 3 e 5 então se comportam exatamente como antes deste recurso existir.
• Responder "y" lista todos os IPs independentes elegíveis e BDs criados pelo usuário (via list_preservable_outputs) — incluindo XCIs que vivem fora de qualquer Block Design — e permite que você escolha quais preservar (all ou uma lista separada por vírgula). Esta seleção é mista/parcial entre itens de nível superior separados (alguns IPs/BDs independentes preservados, outros não) — este é o caso principal suportado. Não é parcial dentro de um único BD: um BD é preservado como uma unidade inteira, e você não pode escolher quais IPs personalizados dentro dele serão preservados vs. regenerados (confirmado como um corte de escopo intencional, não um bug — sinalizado como possível melhoria no Q4).
• Se um item selecionado não tiver saída .gen ainda (nunca foi gerado/sintetizado), export_all_sources avisa e o exporta normalmente em vez de preservá-lo — nada para preservar ainda não é uma falha grave, mas também não cria silenciosamente uma entrada de cache incompleta.
• A preservação suporta apenas um cache remoto: um diretório fora deste projeto. Após escolher IPs/BDs, você é solicitado a fornecer o caminho absoluto desse diretório de cache. Um caminho inválido (relativo, vazio ou aninhado dentro do projeto) desabilita a preservação para esta exportação.

Este procedimento bloqueia em gets stdin, portanto, só funciona com um tty real anexado — que é exatamente a condição que export_all_sources agora verifica (_rc_stdin_is_tty) antes de invocá-lo automaticamente.

CI / pipelines de regressão automatizados (harnesses do estilo run_pipeline.tcl) — pule esta etapa completamente e passe {} (o padrão) para as Etapas 3 e 5. Isso preserva o comportamento antigo totalmente automatizado de 5 etapas inalterado.

Agente (um agente de IA conduzindo o Vivado via chamadas Bash/Tcl em modo lote, conversando com um humano) — não chame prompt_preserve_outputs: seu gets stdin não tem tty real para bloquear e apenas lerá EOF, desabilitando silenciosamente a preservação sem nenhum prompt visível. Em vez disso:

1. Chame list_preservable_outputs (consulta pura, sem stdin) para ver o que é elegível.
2. Se retornar algum IP ou BD, pergunte diretamente ao humano na conversa quais (se houver) eles desejam preservar, E um caminho absoluto para um diretório de cache fora do projeto para armazenar as saídas preservadas.
3. Chame build_preserve_selection $chosen_ips $chosen_bds $cache_dir com as respostas do humano para obter o dicionário preserve_selection.
4. Se list_preservable_outputs não retornar nada, pule a pergunta — não há nada a preservar.

set items [list_preservable_outputs]
# ... pergunte ao humano na conversa, então:
set preserve_selection [build_preserve_selection $chosen_ips $chosen_bds $cache_dir]

Passe o preserve_selection retornado para a Etapa 3 (export_all_sources). Para detalhes, leia helper-procedures/REFERENCE.md.

Etapa 3: Exportar Todas as Fontes (condicional)

Pule esta etapa se a Etapa 2 retornou "Remote". Caso contrário, exporte RTL, constraints, IP (como Tcl via write_ip_tcl), Block Designs (como Tcl via write_bd_tcl), arquivos de simulação e arquivos de dados para um diretório organizado.

Passe flow_info da Etapa 1 para habilitar exportações específicas de DFX/Configuração Segmentada (pblocks, DCPs, soluções NoC). Passe preserve_selection da Etapa 2.5 (ou omita) para controlar a preservação de saída por IP/BD. Se você omitir e stdin for um tty real, export_all_sources solicitará por conta própria (veja Etapa 2.5 acima) em vez de pular silenciosamente a preservação. Para qualquer IP/BD nomeado em preserve_selection, sua própria subárvore .srcs/.gen (nada mais) é copiada para o cache_dir externo que a seleção especifica — nunca para o próprio export_dir/RevisionControl/.

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

Para detalhes sobre regras de filtragem, manipulação de BD-IP e exportações DFX, leia export-all-sources/REFERENCE.md.

Etapa 4: Capturar Configurações do Projeto

Salve todas as propriedades não padrão do projeto em um script Tcl que possa restaurá-las durante a reconstrução.

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, diretivas de síntese/implementação e propriedades específicas de arquivo (VHDL LIBRARY, IS_GLOBAL_INCLUDE).

Para detalhes, leia capture-project-settings/REFERENCE.md.

Etapa 5: Gerar Script de Build

Crie build.tcl para recriação do projeto com um único comando.

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

O script gerado usa caminhos relativos, importa fontes locais (import_files), referencia fontes remotas in-loco (add_files), recria IP e BD a partir de scripts Tcl, cria runs OOC de IP, gera targets de BD, carrega project_settings.tcl e finaliza a ordem de compilação. Para qualquer IP/BD preservado na Etapa 2.5, ele, em vez disso, restaura a subárvore .srcs/.gen desse item do diretório de cache externo e add_files/read_ip/read_bd diretamente — sem repetição de write_ip_tcl/write_bd_tcl, sem ressíntese — enquanto todo IP/BD não preservado ainda passa pelo caminho padrão de regeneração Tcl. Essa ramificação é por IP/BD, nunca global para todo o projeto. Se o diretório de cache (ou os dados de um item preservado específico dentro dele) estiver ausente no momento da reconstrução, o script gerado gera erro fatal em vez de cair silenciosamente na regeneração.

Para detalhes, ordenação RM do DFX e manipulação de .gen ausente, leia generate-build-script/REFERENCE.md.

Fluxo de Dados do Pipeline

Etapa 1: detect_project_flow
  → dicionário flow_info (passado para Etapa 3)

Etapa 2: analyze_source_locations
  → cenário ("Push Button" / "Remote" / "Mixed")
  → Se Remote: pular Etapa 3

Etapa 2.5: prompt_preserve_outputs (opcional, apenas interativa)
  → dicionário preserve_selection {enabled, ips, bds, cache_dir} (passado para Etapa 3)
  → omitido/recusado ⇒ {} ⇒ Etapas 3 e 5 se comportam exatamente como antes
  → se omitido E stdin for um tty real E algo for elegível, Etapa 3 o chama
    automaticamente (adicionado em 2026-09-21) em vez de padronizar silenciosamente
    para nenhuma preservação — sem tty (CI/agente) ⇒ inalterado
  → cache_dir deve ser um caminho absoluto FORA do projeto (apenas cache remoto)
    — um caminho inválido/ausente desabilita a preservação para esta exportação

Etapa 3: export_all_sources(dir, flow_info, preserve_selection)
  → diretório Sources/ com RTL, IP, BD, Constraints (o próprio dir nunca muda de forma
    com base em preserve_selection)
  → (apenas se preserve_selection selecionou algo) a própria subárvore .srcs/.gen de
    CADA item preservado é copiada para cache_dir — nunca para o próprio dir

Etapa 4: capture_project_settings(file)
  → project_settings.tcl

Etapa 5: generate_build_script(file, dir, scenario_info)
  → build.tcl (reconstrução automatizada; restaura .srcs/.gen de qualquer item
    preservado de cache_dir no momento da reconstrução — erro fatal se cache_dir ou
    dados de um item preservado dentro dele estiverem ausentes)

Estrutura de Saída

RevisionControl/ é exportado ao lado do projeto Vivado ativo e sua própria forma nunca muda com base no uso da preservação da Etapa 2.5 — ele nunca contém <proj>.gen/, <proj>.srcs/ ou <proj>.xpr do projeto original (eles permanecem intocados onde estão), e o XPR nunca é versionado em nenhum fluxo.

project_1.gen/            # projeto Vivado original ativo — irmão, intocado
project_1.srcs/
project_1.xpr

RevisionControl/
├── Sources/
│   ├── RTL/              # fontes Verilog/SV/VHDL
│   ├── Constraints/      # arquivos XDC (+ pblocks.xdc para DFX)
│   ├── IP/               # scripts write_ip_tcl — apenas IPs independentes
│   │                     # não preservados (nenhum .xci copiado); IPs preservados
│   │                     # são pulados aqui completamente (veja abaixo)
│   ├── BD/               # scripts write_bd_tcl — apenas BDs não preservados
│   │                     # (nenhum .bd copiado); BDs preservados são pulados aqui
│   │                     # completamente, sem fallback Tcl (veja abaixo)
│   ├── Simulation/       # Testbenches
│   ├── Data/             # arquivos .mem, .coe, .mif, .hex, .elf, .csv
│   ├── Scripts/          # scripts Tcl de hook pré/pós
│   ├── Checkpoints/      # (apenas DFX) DCPs estáticos bloqueados
│   └── NoC/              # (apenas Configuração Segmentada) arquivos .ncr
└── Scripts/
    ├── project_settings.tcl
    └── build.tcl

Saídas Preservadas (Etapa 2.5 respondida "Sim", ≥1 IP/BD selecionado)

Se a Etapa 2.5 preservou algo, o único artefato é um diretório de cache remoto externo — um caminho fora do projeto que o usuário forneceu (cache_dir em preserve_selection), nunca copiado para RevisionControl/ e nunca rastreado pelo git:

<cache_dir>/
└── project_1/
    ├── ip/
    │   └── <ip_name>/
    │       ├── srcs/     # cópia do diretório .srcs desse IP (o arquivo .xci
    │       └── gen/      # e suas saídas geradas / synth)
    └── bd/
        └── <bd_name>/
            ├── srcs/     # cópia do diretório .srcs desse BD (o arquivo .bd
            └── gen/      # e suas saídas geradas)

Nenhum write_ip_tcl/write_bd_tcl é emitido para esses itens em build.tcl—em vez disso, o script gerado usa add_files/read_ip/read_bd diretamente do cache. Se o cache estiver ausente durante a reconstrução (build.tcl executado sem ele), o script gera um erro fatal (error "Cache directory ... not found") e para — não há fallback para regeneração Tcl.

---

Referências

• Visão Geral do Detectar Fluxo do Projeto
• Visão Geral do Analisar Localizações das Fontes
• Visão Geral do Exportar Todas as Fontes
• Visão Geral do Capturar Configurações do Projeto
• Visão Geral do Gerar Script de Build
• Referência dos Procedimentos Auxiliares

Licenciamento

Copyright (C) 2026, Advanced Micro Devices, Inc. Todos os direitos reservados.
SPDX-License-Identifier: MIT