Difference between revisions of "File format:Vcd"

**vcd**
Name	Value change dump
Status	supported
Source code (in)	vcd.c
Source code (out)	vcd.c
Common extension(s)	.vcd, .wave
MIME type	—
ASCII format	yes
Compression	yes (only stores transitions)
Website	wikipedia.org

Latest revision as of 18:41, 23 June 2023

The VCD (Value change dump) format is ASCII based and thus accessible to both humans and machines alike. It exclusively communicates when values happen to change, thus results in a compact presentation of a set of signals over time. The format is very popular among hardware developers and is often used for simulation or synthesis.

The VCD files can be opened and processed e.g. in a waveform viewer software. The gtkwave application is a popular example.

Format

See Wikipedia for a short overview.

The gtkwave documentation also discusses extensions, and a few alternative formats.

Properties

TODO

Implementation

VCD import

These are the input module's options and their default values:

 $ sigrok-cli -I vcd --show 
 ID: vcd
 Name: VCD
 Description: Value Change Dump data
 Options:
   numchannels: The maximum number of sigrok channels to create for VCD input signals. (default 0)
   downsample: Downsample the input file's samplerate, i.e. divide by the specified factor. (default 1)
   skip: Skip samples until the specified timestamp. By default samples start at the first timestamp in the file. Value 0 creates samples starting at timestamp 0. Values above 0 only start processing at the given timestamp. (default 0)
   compress: Compress idle periods which are longer than the specified number of timescale ticks. (default 0)

Interpretation:

The number of channels gets auto-determined by the software, but can get overridden by user specs (limited to a smaller number).
The sigrok software will use the input file's sample count and timescale values, which _can_ result in excessive memory consumption. Some generators love to specify insane timescales which results in large sample numbers. The downsample option allows to workaround that implementation detail.
By default all input data gets processed, users can specify that a leading part of the input shall get skipped.
The sigrok software will provide lots of samples for extended periods of time when the input signal has these idle periods. Users can request to have these periods shortened.

The sigrok VCD input module supports these features:

Nested scopes translate to sigrok channel names where labels for levels are separated by a period. This visually represents their relation and grouping.
Logic data values gets mapped to the strict set of 0 and 1. Support for tristate or weak or undefined etc is missing. Unknown states are assumed to be 0 (low).
Single bit logic values translate to one logic sigrok channel. Multi bit logic values (bit vectors) span an adjacent set of sigrok channels, their names reflect the relation. Applications may decide to group them or present their aggregate value, that's up to individual applications.
VCD integers (multi-bit values that are assumed to be a number) map to an analog sigrok channel.
Signals of the VCD "real" type map to analog sigrok channels. Precision handling currently is WIP.
The use of the same VCD identifier for several signals is supported.
The VCD file format's inherent limitation of "timescale" values (must be 1/10/100 and a unit) can result in the generation of multiple sigrok samples for a single VCD input value. Staircase artifacts can occur for analog input, which are impossible to avoid.

BEWARE! Internal libsigrok infrastructure assumes that input data forms a stream of sample values of a given rate. A value is kept for each step at this rate. Some VCD file generators unfortunately pick tiny timescale values and corresponding large strides between value changes (we have seen input files with 1fs timescale and 5 million femtoseconds between changes). Either adjust the input file before importing its content, or use the downsample=N option. Otherwise processing the input data can take long periods of time, and even may exceed available resources and can terminate before completion.

VCD export

The output module does not provide options:

 $ sigrok-cli -O vcd --show 
 ID: vcd
 Name: VCD
 Description: Value Change Dump data

The sigrok VCD output module supports these features:

sigrok channel names translate to VCD identifiers in straight forward ways. No check is done for identical content, to re-use an identifier for several signals.
The current implementation of the VCD export is limited to some 18000 signals, but can get extended should the need arise. The first 94 channels stick with single letter identifiers, larger channel counts result in all-letter combinations (strictly alnum) of the required length.
sigrok channels map to either logic or real values. Though sigrok currently has no concept of "integers" or multi-bit vectors. Thus round trips through VCD import and export can result in different presentations of the data. Yet all values should be there, and be correct within the limitations of the VCD support in sigrok.
See the "timescale" limitation which was discussed above.

Examples

Mixed signal data set, generated by the demo device driver:

 $ sigrok-cli -d demo:logic_channels=4:analog_channels=2 --samples 20 -O vcd 
 $date Fri Jul 24 13:51:17 2020 $end
 $version libsigrok 0.6.0-git-c03aaf342c3f $end
 $comment
   Acquisition with 6/6 channels at 200 kHz
 $end
 $timescale 1 us $end
 $scope module libsigrok $end
 $var wire 1 ! D0 $end
 $var wire 1 " D1 $end
 $var wire 1 # D2 $end
 $var wire 1 $ D3 $end
 $var real 64 % A0 $end
 $var real 64 & A1 $end
 $upscope $end
 $enddefinitions $end
 
 #0 1! 0" 0# 1$ r-10 % r0 &
 #5 0! 1" 1# 0$ r3.090169906616211 &
 #10 r5.877852439880371 &
 #15 r8.090169906616211 &
 #20 1! 0" 1$ r9.510564804077148 &
 #25 1" r10 % r10 &
 #30 r9.510564804077148 &
 #35 r8.090169906616211 &
 #40 0! r5.877852439880371 &
 #45 0" 0# 0$ r3.090169906616211 &
 #50 r-10 % r-3.216245298855018e-15 &
 #55 1" 1# 1$ r-3.090169906616211 &
 #60 1! r-5.877852439880371 &
 #65 r-8.090169906616211 &
 #70 r-9.510564804077148 &
 #75 r10 % r-10 &
 #80 0" 0# 0$ r-9.510564804077148 &
 #85 0! 1" 1# 1$ r-8.090169906616211 &
 #90 r-5.877852439880371 &
 #95 0$ r-3.090169906616211 &
 #100

Related/alternative formats

The [GTKWave] project also supports extensions to the VCD format, as well as alternative formats which avoid VCD's limitations, and/or improve performance. The [GTKWave manual] discusses the formats and conversion utilities.

EVCD: (TODO Find the name and short description for this format.)
FST: Fast Signal Trace. This format is a block-based variant of IDX which is designed for very fast sequential and random access.
IDX: VCD Recoder Index File. This format is written by GTKWave when instructed to generate fastload files.
GHW: GHDL Wave file. This is a nine state (“01XZHUWL-”) file format written by the VHDL simulator GHDL.

Resources

@@ Line 12: / Line 12: @@
 }}
-'''vcd''' is an ASCII-based file format that...
+The '''VCD (Value change dump)''' format is ASCII based and thus accessible to both humans and machines alike. It exclusively communicates when values happen to change, thus results in a compact presentation of a set of signals over time. The format is very popular among hardware developers and is often used for simulation or synthesis.
-It can be opened and processed e.g. in a [http://en.wikipedia.org/wiki/Waveform_viewer waveform viewer] software.
+The VCD files can be opened and processed e.g. in a [http://en.wikipedia.org/wiki/Waveform_viewer waveform viewer] software. The '''gtkwave''' application is a popular example.
 == Format ==
 See [http://en.wikipedia.org/wiki/Value_change_dump#Structure.2FSyntax Wikipedia] for a short overview.
+The '''gtkwave''' documentation also discusses extensions, and a few alternative formats.
 == Properties ==
+TODO
 == Implementation ==
+=== VCD import ===
 These are the input module's options and their default values:
-   $ sigrok-cli -I vcd --show
+<small>
+   $ '''sigrok-cli -I vcd --show'''
    ID: vcd
    Name: VCD
    Description: Value Change Dump data
    Options:
-     numchannels: The number of (logic) channels in the data (default 0)
+     numchannels: The maximum number of sigrok channels to create for VCD input signals. (default 0)
-     skip: Skip samples until the specified timestamp; < 0: Skip until first timestamp listed; 0: Don't skip (default -1)
+    downsample: Downsample the input file's samplerate, i.e. divide by the specified factor. (default 1)
-    downsample: Downsample, i.e. divide the samplerate by the specified factor (default 1)
+     skip: Skip samples until the specified timestamp. By default samples start at the first timestamp in the file. Value 0 creates samples starting at timestamp 0. Values above 0 only start processing at the given timestamp. (default 0)
-     compress: Compress idle periods longer than the specified value (default 0)
+     compress: Compress idle periods which are longer than the specified number of timescale ticks. (default 0)
+</small>
 Interpretation:
 * The number of channels gets auto-determined by the software, but can get overridden by user specs (limited to a smaller number).
+* The sigrok software will use the input file's sample count and timescale values, which _can_ result in excessive memory consumption. Some generators love to specify insane timescales which results in large sample numbers. The '''downsample''' option allows to workaround that implementation detail.
 * By default all input data gets processed, users can specify that a leading part of the input shall get skipped.
-* The sigrok software will use the input file's sample count and timescale values, which _can_ result in excessive memory consumption. Some generators love to specify insane timescales which results in large sample numbers. The '''downsample''' option allows to workaround that implementation detail.
 * The sigrok software will provide lots of samples for extended periods of time when the input signal has these idle periods.  Users can request to have these periods shortened.
-There are some limitations in the current VCD input module implementation:
+The sigrok VCD input module supports these features:
+* Nested scopes translate to sigrok channel names where labels for levels are separated by a period. This visually represents their relation and grouping.
+* Logic data values gets mapped to the strict set of 0 and 1. Support for tristate or weak or undefined etc is missing. Unknown states are assumed to be 0 (low).
+* Single bit logic values translate to one logic sigrok channel. Multi bit logic values (bit vectors) span an adjacent set of sigrok channels, their names reflect the relation. Applications may decide to group them or present their aggregate value, that's up to individual applications.
+* VCD integers (multi-bit values that are assumed to be a number) map to an analog sigrok channel.
+* Signals of the VCD "real" type map to analog sigrok channels. Precision handling currently is WIP.
+* The use of the same VCD identifier for several signals is supported.
+* The VCD file format's inherent limitation of "timescale" values (must be 1/10/100 and a unit) can result in the generation of multiple sigrok samples for a single VCD input value. Staircase artifacts can occur for analog input, which are impossible to avoid.
+'''BEWARE!''' Internal libsigrok infrastructure assumes that input data forms a stream of sample values of a given rate. A value is kept for each step at this rate. Some VCD file generators unfortunately pick tiny timescale values and corresponding large strides between value changes (we have seen input files with 1fs timescale and 5 million femtoseconds between changes). Either adjust the input file before importing its content, or use the '''downsample=N''' option. Otherwise processing the input data can take long periods of time, and even may exceed available resources and can terminate before completion.
+=== VCD export ===
+The output module does not provide options:
+<small>
+  $ '''sigrok-cli -O vcd --show'''
+  ID: vcd
+  Name: VCD
+  Description: Value Change Dump data
+</small>
-* Support for nested name spaces is missing ('module' keyword).
+The sigrok VCD output module supports these features:
-* Exclusive support for single-bit logic data ('wire 1' or 'reg 1'). No support for bit vectors, integer or real numbers.
+* sigrok channel names translate to VCD identifiers in straight forward ways. No check is done for identical content, to re-use an identifier for several signals.
-* The total number of channels may be limited (single letter names, which results in some 94 supported names or so).
+* The current implementation of the VCD export is limited to some 18000 signals, but can get extended should the need arise. The first 94 channels stick with single letter identifiers, larger channel counts result in all-letter combinations (strictly alnum) of the required length.
+* sigrok channels map to either logic or real values. Though sigrok currently has no concept of "integers" or multi-bit vectors. Thus round trips through VCD import and export can result in different presentations of the data. Yet all values should be there, and be correct within the limitations of the VCD support in sigrok.
+* See the "timescale" limitation which was discussed above.
 == Examples ==
+Mixed signal data set, generated by the demo device driver:
 <small>
- $date Fri Aug  1 23:46:38 2014 $end
+  $ '''sigrok-cli -d demo:logic_channels=4:analog_channels=2 --samples 20 -O vcd '''
- $version libsigrok 0.3.0 $end
+  $date Fri Jul 24 13:51:17 2020 $end
- $comment
+  $version libsigrok 0.6.0-git-c03aaf342c3f $end
-   Acquisition with 2/8 channels at 500 kHz
+  $comment
- $end
+    Acquisition with 6/6 channels at 200 kHz
- $timescale 1 us $end
+  $end
- $scope module libsigrok $end
+  $timescale 1 us $end
- $var wire 1 ! sda $end
+  $scope module libsigrok $end
- $var wire 1 " scl $end
+  $var wire 1 ! D0 $end
- $upscope $end
+  $var wire 1 " D1 $end
- $enddefinitions $end
+  $var wire 1 # D2 $end
- #0 1! 0"
+  $var wire 1 $ D3 $end
- #40 0!
+  $var real 64 % A0 $end
- #72 1"
+  $var real 64 & A1 $end
- #102 1!
+  $upscope $end
- #144 0!
+  $enddefinitions $end
- #174 0"
- #204 1!
+  #0 1! 0" 0# 1$ r-10 % r0 &
- #246 0!
+  #5 0! 1" 1# 0$ r3.090169906616211 &
- #276 1"
+  #10 r5.877852439880371 &
- #306 1!
+  #15 r8.090169906616211 &
- #348 0!
+  #20 1! 0" 1$ r9.510564804077148 &
- #380 0"
+  #25 1" r10 % r10 &
- #410 1!
+  #30 r9.510564804077148 &
- #452 0!
+  #35 r8.090169906616211 &
- #514 1!
+  #40 0! r5.877852439880371 &
- #566 0!
+  #45 0" 0# 0$ r3.090169906616211 &
- #628 1!
+  #50 r-10 % r-3.216245298855018e-15 &
- #668 0!
+  #55 1" 1# 1$ r-3.090169906616211 &
- #730 1!
+  #60 1! r-5.877852439880371 &
- #770 0!
+  #65 r-8.090169906616211 &
- #832 1!
+  #70 r-9.510564804077148 &
- #872 0!
+  #75 r10 % r-10 &
- #938 1!
+  #80 0" 0# 0$ r-9.510564804077148 &
- #978 0! 1"
+  #85 0! 1" 1# 1$ r-8.090169906616211 &
- #1010 0"
+  #90 r-5.877852439880371 &
- #1040 1!
+  #95 0$ r-3.090169906616211 &
- [...]
+  #100
- #106772 1!
- #106812 0!
- #106844 0"
- #106874 1!
- #106914 1"
- #160000
 </small>
+== Related/alternative formats ==
+The [[http://gtkwave.sourceforge.net/ GTKWave]] project also supports extensions to the VCD format, as well as alternative formats which avoid VCD's limitations, and/or improve performance. The [[http://gtkwave.sourceforge.net/gtkwave.pdf GTKWave manual]] discusses the formats and conversion utilities.
+* EVCD: (TODO Find the name and short description for this format.)
+* FST: Fast Signal Trace.  This format is a block-based variant of IDX which is designed for very fast sequential and random access.
+* IDX: VCD Recoder Index File.  This format is written by GTKWave when instructed to generate fastload files.
+* GHW: GHDL Wave file.  This is a nine state (“01XZHUWL-”) file format written by the VHDL simulator GHDL.
 == Resources ==

Name	Value change dump
Status	supported
Source code (in)	vcd.c
Source code (out)	vcd.c
Common extension(s)	.vcd, .wave
MIME type	—
ASCII format	yes
Compression	yes (only stores transitions)
Website	wikipedia.org