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

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.

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

$date Fri Aug  1 23:46:38 2014 $end
$version libsigrok 0.3.0 $end
$comment
  Acquisition with 2/8 channels at 500 kHz
$end
$timescale 1 us $end
$scope module libsigrok $end
$var wire 1 ! sda $end
$var wire 1 " scl $end
$upscope $end
$enddefinitions $end
#0 1! 0"
#40 0!
#72 1"
#102 1!
#144 0!
#174 0"
#204 1!
#246 0!
#276 1"
#306 1!
#348 0!
#380 0"
#410 1!
#452 0!
#514 1!
#566 0!
#628 1!
#668 0!
#730 1!
#770 0!
#832 1!
#872 0!
#938 1!
#978 0! 1"
#1010 0"
#1040 1!
[...]
#106772 1!
#106812 0!
#106844 0"
#106874 1!
#106914 1"
#160000

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

• Wikipedia: Value change dump
• beyondttl.com: Value Change Dump (VCD)