Python VCD File Support

0.4.1 · active · verified Fri Apr 17

pyvcd is a Python library designed for working with Value Change Dump (VCD) files. It provides functionalities for both reading and writing these standard files used to record signal activity in digital logic simulations. The current version is 0.4.1, and releases are generally made on an as-needed basis for bug fixes or minor enhancements.

Common errors

```
ValueError: Cannot change unknown variable.
```
cause Attempting to change a signal's value that has not yet been defined within the current or parent scope using `scope.var()`.

fix Before calling `writer.change()`, ensure the variable has been defined with `scope.var('signal_name', 'wire', width)` and that the returned variable object is used.
```
IOError: [Errno 9] Bad file descriptor
```
cause Attempting to write to the VCD file after the file object or the `VCDWriter` has been closed (e.g., after the `with` block exits, or if `writer.close()` was explicitly called too early).

fix Ensure all `writer.change()` calls and other write operations happen within the `with VCDWriter(...) as writer:` block, or that the file object passed to `VCDWriter` remains open for the duration of writing.
```
VCD file appears empty or truncated when opened in a viewer.
```
cause The file stream or the `VCDWriter` was not properly closed, leading to unwritten buffered data not being flushed to disk.

fix Always use `VCDWriter` within a `with` statement: `with VCDWriter(open('my.vcd', 'w'), ...) as writer:`. This ensures `close()` is called automatically, flushing all buffers.

Warnings

gotcha Forgetting to use `VCDWriter` in a `with` statement or manually `close()` the writer can lead to incomplete or corrupted VCD files, as internal buffers might not be flushed to disk.
Fix: Always use `VCDWriter` as a context manager: `with VCDWriter(open('file.vcd', 'w'), ...) as writer:`
gotcha The `timescale` argument to `VCDWriter` is crucial for the correct interpretation of timestamps by VCD viewers. Missetting it (e.g., '1ps' when the simulation operates in '1ns' increments) will result in incorrect timing displays.
Fix: Ensure `timescale` (e.g., '1 ns', '1 ps', '1 us') accurately reflects the time units used for your simulation data.
gotcha Signal values are expected to be integers for `wire` types by default. Providing non-integer values without proper conversion can lead to `TypeError` or `ValueError` or incorrect data representation in the VCD file.
Fix: Ensure values passed to `writer.change()` for `wire` types are integers. For bit-string representations, consider converting to integer or ensuring your VCD viewer handles them correctly.

Install

pip install pyvcd Install pyvcd

Imports

VCDWriter
```
from pyvcd import VCDWriter
```
VCDReader
```
from pyvcd import VCDReader
```

Quickstart

This example demonstrates how to create a VCD file, define a module scope, declare signals (wires), and record their value changes over time using `VCDWriter`.

from datetime import datetime
from pyvcd import VCDWriter

# Create a VCD file named 'test.vcd'
with VCDWriter(open('test.vcd', 'w'), timescale='1 ns', date=datetime.now()) as writer:
    # Enter a scope named 'top' of type 'module'
    scope = writer.scope_stack.enter_scope('top', 'module')
    
    # Define a 1-bit 'clk' wire and change its value over time
    writer.change(scope.var('clk', 'wire', 1), 0, 0)   # At time 0, clk is 0
    writer.change(scope.var('clk', 'wire', 1), 1, 100) # At time 100 ns, clk is 1
    writer.change(scope.var('clk', 'wire', 1), 0, 200) # At time 200 ns, clk is 0
    
    # Define another 1-bit 'rst_n' wire
    writer.change(scope.var('rst_n', 'wire', 1), 1, 0)
    writer.change(scope.var('rst_n', 'wire', 1), 0, 100)
    writer.change(scope.var('rst_n', 'wire', 1), 1, 200)
    
    # Leave the current scope
    writer.scope_stack.leave_scope()

print("VCD file 'test.vcd' generated successfully.")

view raw JSON →