Verilog $dumpfile e $dumpvars: Produzindo formas de onda VCD

A forma de onda que você de fato quer

$display imprime texto. Está bem para uma verificação rápida de sanidade, mas no momento em que você está debugando um contador com problema de timing ou uma máquina de estado que travou, você quer uma imagem: sinais desenhados como tensões ao longo do tempo, roláveis, com zoom, com um cursor que você pode soltar em qualquer transição.

Essa imagem é um arquivo VCD - "value change dump", um formato de texto que o IEEE padronizou na spec original do Verilog. Cada simulador moderno consegue escrever um; cada visualizador de forma de onda moderno consegue ler um. O custo de produzir um é duas linhas no seu testbench.

As duas linhas

Dentro de um bloco initial - geralmente o mesmo que segura seu estímulo - adicione:

$dumpfile("dump.vcd");
$dumpvars(0, test);

• $dumpfile nomeia o arquivo de saída. Passe qualquer caminho; se não tem diretório, cai no diretório de trabalho do simulador.
• $dumpvars(0, test) diz "registre cada sinal no escopo test e em cada sub-escopo, recursivamente, com profundidade ilimitada".

Esse é o setup todo. Rode a simulação e você terá um dump.vcd que pode abrir no GTKWave ou na aba Waveform do editor do navegador.

Um exemplo completo

module counter4(
    input  wire       clk,
    input  wire       reset,
    output reg  [3:0] count
);
    always @(posedge clk) begin
        if (reset) count <= 4'd0;
        else       count <= count + 4'd1;
    end
endmodule

module test;
    reg clk = 0;
    reg reset = 1;
    wire [3:0] count;

    counter4 dut(.clk(clk), .reset(reset), .count(count));

    always #5 clk = ~clk;

    initial begin
        $dumpfile("dump.vcd");
        $dumpvars(0, test);

        #20 reset = 0;
        #100 $finish;
    end
endmodule

Execute. A aba Waveform agora mostra três sinais - clk, reset, count - desenhados ao longo de todo o tempo de simulação. Você pode soltar um cursor em qualquer ponto e ler os valores dos sinais naquele tempo. Pode dar zoom arrastando para inspecionar um único ciclo de clock.

O que o primeiro argumento de $dumpvars faz

$dumpvars(depth, scope) caminha por scope e cada subinstância que ele contém, registrando sinais até depth níveis para dentro. Os valores de profundidade:

• 0 - ilimitado. Cada sinal em scope e em cada submódulo aninhado é registrado.
• 1 - só sinais declarados diretamente em scope. Submódulos não são registrados.
• 2 - scope mais um nível de submódulo.
• N - scope mais N-1 níveis de submódulos.

Na prática, $dumpvars(0, test) é o que quase todo testbench usa. Capturar tudo é barato (VCDs só armazenam transições, não estados estáveis) e você não quer descobrir no meio do debug que o sinal que precisa não foi dumpado.

Se você tem um design realmente grande e o VCD é grande demais, pode dumpar seletivamente:

$dumpvars(0, dut.inner_module);     // so o submodule interessante
$dumpvars(0, dut.regs);             // so o register file

Você pode chamar $dumpvars múltiplas vezes para acumular escopos.

Dumpando sinais específicos

$dumpvars também pode pegar uma lista de sinais específicos em vez de um escopo inteiro:

$dumpvars(0, test.clk, test.reset, dut.count);

Isso registra só esses três sinais. Útil quando o design é enorme e você só se importa com um punhado de sinais. Para designs pequenos, dumpar tudo é mais simples.

Controlando o dump no meio da simulação

Mais duas tasks parceiras de $dumpvars:

• $dumpoff - pausa o dumping. Nenhuma mudança subsequente entra no VCD.
• $dumpon - retoma o dumping.

initial begin
    $dumpfile("dump.vcd");
    $dumpvars(0, test);

    // ... regiao interessante ...

    #1000 $dumpoff;
    // ... longa regiao chata que nao queremos no VCD ...
    #5000 $dumpon;

    // ... outra regiao interessante ...
end

É assim que você pula a parte chata "rodar por um milhão de ciclos" de um teste longo sem produzir um arquivo VCD de 5GB.

Visualizando o resultado

Duas formas principais:

No editor do navegador

O editor desta página renderiza VCDs inline. Rode a simulação; troque para a aba Waveform; os sinais aparecem com a hierarquia à esquerda e um cursor arrastável à direita. Clique em qualquer lugar em um traço para soltar o cursor; ele mostra os valores dos sinais naquele tempo como pílulas ao lado de cada nome de sinal.

No GTKWave

Se você rodou a simulação localmente (iverilog -o sim test.v depois vvp sim), abra o VCD resultante com:

gtkwave dump.vcd

GTKWave carrega o arquivo, apresenta a árvore de escopo à esquerda e espera você arrastar sinais para a área de forma de onda à direita. Clique com o botão direito em um sinal multi-bit para mudar o formato de exibição (binário, hex, decimal, analógico). Use a caixa de busca embaixo para pular para tempos ou transições de sinal específicas.

Padrões comuns

Um pequeno helper de testbench

A maioria dos arquivos de testbench começa com esse bloco exato. Você pode mantê-lo curto combinando tudo em um initial:

initial begin
    $dumpfile("dump.vcd");
    $dumpvars(0, test);

    // ... estimulo ...

    $finish;
end

Dumping condicional

Em um ambiente de teste onde você só quer saída VCD para testes que falham:

initial begin
    if (DUMP_VCD) begin
        $dumpfile("dump.vcd");
        $dumpvars(0, test);
    end
    // ... estimulo ...
end

DUMP_VCD seria um parameter que você seta pela linha de comando ou define dependendo do modo de teste. Economiza espaço em disco em suítes de regressão.

Dumps de memória

Memórias (arrays unpacked) não são dumpadas por $dumpvars por padrão - podem ser enormes. Use $dumpvars(0, dut.memory) explicitamente se as quiser, ou $dumpmem em alguns simuladores.

Erros comuns

Arquivo VCD vazio. Você esqueceu $dumpfile ou $dumpvars, ou a simulação chamou $finish antes que algum sinal mudasse. Rode por pelo menos algumas unidades de tempo depois do setup.

Sinais ausentes da forma de onda. O escopo que você passou não os incluiu. $dumpvars(0, dut) registra apenas o que está dentro de dut; se seu testbench aciona sinais no nível test, esses não vão aparecer. Sempre dumpe a partir do escopo do testbench: $dumpvars(0, test).

Arquivo VCD enorme. Uma simulação longa com sinais largos mudando rapidamente produz muitas linhas de VCD. Três correções: dumpe um escopo mais estreito, use $dumpoff/$dumpon em torno das partes chatas, ou troque para um formato mais compacto como FST (que tanto iverilog quanto GTKWave suportam com flags -fst).

O que vem a seguir

O último doc deste capítulo - Timescale and Delays - explica a diretiva \timescalee como#delay` de fato mapeia para tempo de relógio. Depois disso você completou os docs de ponta a ponta.