Skip to main content
= vcdvcd
:idprefix:
:idseparator: -
:sectanchors:
:sectlinks:
:sectnumlevels: 6
:sectnums:
:toc: macro
:toclevels: 6
:toc-title:

Python Verilog value change dump (VCD) parser library + the nifty <<vcdcat>> VCD command line pretty printer.

toc::[]

== Installation

Install the latest release:

....
python -m pip install --user vcdvcd
....

Install master directly from this repository for development with `--editable`:

....
git clone https://github.com/cirosantilli/vcdvcd
python -m pip install --editable . --user
....

This allows you to direcly edit the source code here and see updates to importers from anywhere as shown at: https://stackoverflow.com/questions/35064426/when-would-the-e-editable-option-be-useful-with-pip-install/63353319#63353319[].

Use <<vcdcat>> directly from this repo without installing:

....
./vcdcat -h
....

== vcdcat

Nifty terminal CLI VCD pretty printer:

....
./vcdcat -h
....

Dump all signal values:

....
./vcdcat counter_tb.vcd
....

Output:

....
0 time
1 counter_tb.clock
2 counter_tb.enable
3 counter_tb.out[1:0]
4 counter_tb.reset
5 counter_tb.top.out[1:0]

0 1 2 3 4 5
===========
0 1 0 x 0 x
1 0 0 x 1 x
2 1 0 0 1 0
3 0 0 0 0 0
4 1 0 0 0 0
5 0 1 0 0 0
6 1 1 1 0 1
7 0 1 1 0 1
8 1 1 2 0 2
9 0 1 2 0 2
10 1 1 3 0 3
11 0 1 3 0 3
12 1 1 0 0 0
13 0 1 0 0 0
14 1 1 1 0 1
15 0 1 1 0 1
16 1 1 2 0 2
17 0 1 2 0 2
18 1 1 3 0 3
19 0 1 3 0 3
20 1 1 0 0 0
21 0 1 0 0 0
22 1 1 1 0 1
23 0 1 1 0 1
24 1 1 2 0 2
25 0 0 2 0 2
....

Dump only a some of the signals:

....
./vcdcat counter_tb.vcd top.enable top.reset
....

Output:

....
0 time
1 counter_tb.top.enable
2 counter_tb.top.reset

0 1 2
=====
0 0 0
1 0 1
3 0 0
5 1 0
25 0 0
....

Only times for which at least one signal changed are shown.

=== `vcdcat --deltas`

Only print the signals that changed for each time.

If no signals changed at a given time, don't print anything for that time.

This will potentially make the output much much smaller for large VCD files.

Example:

....
./vcdcat -d counter_tb.vcd
....

Output excerpt:

....
0 x counter_tb.top.out[1:0]
0 0 counter_tb.reset
0 0 counter_tb.enable
0 1 counter_tb.clock
0 x counter_tb.out[1:0]
1 0 counter_tb.clock
1 1 counter_tb.reset
2 0 counter_tb.out[1:0]
2 0 counter_tb.top.out[1:0]
2 1 counter_tb.clock
3 0 counter_tb.clock
3 0 counter_tb.reset
4 1 counter_tb.clock
....

Where for example the line:

....
0 x counter_tb.top.out[1:0]
....

means that:

* at time `0`
* the signal `counter_tb.top.out[1:0]`
* had value `x`

== API usage

Library usage examples can be seen at link:example.py[] and run with:

....
./examples.py
....

By default, data is parsed at once into a per-signal format that allows for efficient random access, for example:

....
from vcdvcd import VCDVCD
vcd = VCDVCD('counter_tb.vcd')
signal = vcd['counter_tb.top.out[1:0]']
print(signal[0])
print(signal[1])
print(signal[3])
....

But you can also use this library in a puerly stream callback fashion as shown in the examples by doing something like:

....
class MyStreamParserCallbacks(vcdvcd.StreamParserCallbacks):
def value(
self,
vcd,
time,
value,
identifier_code,
cur_sig_vals,
):
print('{} {} {}'.format(time, value, identifier_code))
vcd = VCDVCD('counter_tb.vcd', callbacks=MyStreamParserCallbacks(), store_tvs=False)
....

`store_tvs` instructs the library to not store its own signal data, which would likely just take up useless space in your streaming application.

== About this repository

The VCD format is defined by the Verilog standard, and can be generated with `$dumpvars`.

This repo was originally forked from Sameer Gauria's version, which is currently only hosted on PyPI with email patches and no public bug tracking: link:https://pypi.python.org/pypi/Verilog_VCD[]. There is also a read-only mirror at: link:https://github.com/zylin/Verilog_VCD[].

Another stream implementation can be seen at: link:https://github.com/GordonMcGregor/vcd_parser[].

== Release procedure

Ensure that basic tests don't blow up:

....
./examples.py
./test.py
./vcdcat counter_tb.py
./vcdcat -d counter_tb.py
....

Update the `version` field in `setup.py`:

....
vim setup.py
....

Create a tag and push it:

....
v=v1.0.1
git add setup.py
git commit -m $v $v
git tag -a $v -m $v
git push --follow-tags
....

Push to PyPi:

....
python -m pip install --user setuptools wheel twine
python setup.py sdist bdist_wheel
twine upload dist/*
rm -rf build dist *.egg-info
....


Metadata

Release files for vcdvcd 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcdvcd 2.0.0
File Size Uploaded Provenance Actions
vcdvcd-2.0.0.tar.gz 9.8 kB Without provenance Details for vcdvcd-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcdvcd 2.0.0
File Interpreter ABI Platform Actions
vcdvcd-2.0.0-py3-none-any.whl Python 3 none any Details for vcdvcd-2.0.0-py3-none-any.whl

Total release size: 18.2 kB

Release files / vcdvcd-2.0.0.tar.gz

Download URL vcdvcd-2.0.0.tar.gz
Size 9.8 kB
Tags Source
SHA-256 checksum
How to use checksums
9d5d187db9bd4d5440a515773405c7b55f7822ad32443f33a633a4387ff61bcc
BLAKE2b-256 checksum
How to use checksums
fc6cd4ceaaea307979c9a3d8260053d704af93af3641ad9164d1aa570d3bbd22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.3.0 requests-toolbelt/0.8.0 tqdm/4.46.0 CPython/3.8.2

Release files / vcdvcd-2.0.0-py3-none-any.whl

Download URL vcdvcd-2.0.0-py3-none-any.whl
Size 8.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
71550aaaff2d1d4b6afb74ebc22dd540dfab6995f4327eb0530345ee0be62695
BLAKE2b-256 checksum
How to use checksums
d5903cc51f873e39c72362ddc5bf95a86dd989182c8bc591bf3b4c27dd2e09e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.3.0 requests-toolbelt/0.8.0 tqdm/4.46.0 CPython/3.8.2

Security for vcdvcd 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page