Python Verilog value change dump (VCD) parser library + the nifty vcdcat VCD command line viewer
Project description
= 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
....
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
vcdvcd-2.0.0.tar.gz
(9.8 kB
view hashes)
Built Distribution
vcdvcd-2.0.0-py3-none-any.whl
(8.4 kB
view hashes)