File format: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.
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.