Metadata-Version: 2.1
Name: vcdvcd
Version: 2.0.0
Summary: Python Verilog value change dump (VCD) parser library + the nifty vcdcat VCD command line viewer
Home-page: https://github.com/cirosantilli/vcdvcd
Author: Ciro Santilli
Author-email: ciro.santilli.contact@gmail.com
License: UNKNOWN
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
        ....
        
Platform: UNKNOWN
Description-Content-Type: text/plain
