# parsevcd

> VCD file parser with Java, Python, Tcl support

- Catalog id: `Parsevcd`; bundle: `parsevcd`; latest version 20261018
- Documentation page: https://edautils.com/VCDFileParser.html
- Keywords: VCD parser, value change dump, waveform parser, IEEE 1364 VCD, Java API
- Terms: as stated on edautils.com, EDAUtils tools are free for commercial and academic use, with no license server. The bundle's own metadata says: "Free to evaluate with the bundled licence; commercial licences from help@edautils.com". Licence prerequisites per tool are under "How an agent runs it".
- This file: https://edautils.com/capabilities/parsevcd.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Parsevcd (latest file `parsevcd-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/parsers-liberty-upf-sdc-vcd/files/parsevcd/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/parsevcd-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

Reads a VCD (Value Change Dump, IEEE 1364/1800, including extended/eVCD `$dumpports` files) and
writes it back out as an equivalent VCD file (default `output.vcd`), optionally restricted to
selected signals and time windows, and optionally with a per-signal activity report. It streams:
multi-gigabyte dumps parse in a modest heap. The VCD parser's Java API is the other deliverable
of the bundle (javadoc in `doc/html`). Main class: `com.eu.miscedautils.vcdparser.ReadVCDAndPrintBack`
(jar `lib/vcdparser.jar`; the `.bat` launcher and the designplayer-shell bundle's `bin/parsevcd`
use the same class).

### Where it ships

Its own bundle, `parsevcd.tar.gz` (flow `parsevcd`; release tree `release_scripts/parsevcd/1.0`),
and as a point tool in the **designplayer-shell** bundle (`bin/parsevcd` running the shell's jar;
this guide as `tools/parsevcd/AGENTS.md`, examples under `tools/parsevcd/examples/`).

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`). Use Java 11 or newer (Java 21 recommended: the
  release is built and regression-tested with OpenJDK 21); the bundled JAXB and Eclipse libraries
  are class-file version 55, so a Java 8 runtime fails with `UnsupportedClassVersionError`.
- `EDAUTILS_ROOT` = the unpacked bundle directory (must contain `bin/` and `lib/`). The
  launcher exits 1 with "Environment variable EDAUTILS_ROOT is not set" otherwise.
  `source setup_env.sh` (or `setup_env.csh`) from the bundle root sets `EDAUTILS_ROOT`,
  prepends `bin/` to `PATH` and sets
  `CLASSPATH=$EDAUTILS_ROOT/lib/vcdparser.jar`. It does **not** set `EDAUTILS_LICENSE_FILE`;
  set it yourself (the bundle ships `edautils.lic` at its root).
- Licence: a valid licence file (none: exit status 10, messages 6037/6405) and feature
  `VCDFILEPARSER` (the bundle's licence carries it). If the feature is missing,
  `Error: 6404: Failed to checkout LICENSE for the feature : VCDFILEPARSER` is logged, nothing is
  parsed or written, and the exit status is still 0. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`.
- Optional environment: `JAVA_FLAGS` (passed to the JVM; with no heap option in it the launcher adds `-Xmx` sized to the machine (`bin/eu_heap.sh`: the largest of 64/32/16/12/8/4 GB within 3/4 of physical or cgroup memory, else 2 GB; `EDAUTILS_MAX_HEAP_GB` caps it); the regression gate parses a 200 MB
  dump with `-Xmx768m`), `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the
  second appends), `EDAUTILS_DISABLE_USAGE_TRACKING=true`, `EDAUTILS_PRINT_STACK_TRACE` (stack
  traces on internal exceptions). No tool-specific environment variables are read.
- No external tools needed.

### Invocation

```
parsevcd -in <file.vcd> [-out <file>] [-activity <file>] [-config <file.yaml>]
         [-signal <path|leaf|pattern>]... [-regex <regex>]... [-time_window <start>:<end>]...
         [-dumpports] [-user <email>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | VCD file to read (mandatory) |
| `-out <file>` | Output VCD file (default `output.vcd`) |
| `-activity <file>` | Also write a per-signal activity report (off by default) |
| `-signal <s>` | Populate only this signal: full hierarchical path (`top.cpu.clk`), a leaf name that matches at every level (`clk`), or a pattern where `*` matches within one level, `**` across levels, `?` one character. Repeatable |
| `-regex <re>` | Populate only signals whose full hierarchical path matches this Java regular expression. Repeatable |
| `-time_window <a>:<b>` | Populate activity only between these simulation times; either bound may be omitted (`1000:`, `:2000`). Repeatable. Default: all of time |
| `-config <file>` (alias `-yaml`) | Read the same selection from a YAML file (below) |
| `-dumpports` | Accepted and recorded, but the flag is read by no code; eVCD files parse without it |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and return (`-h` is not recognised) |

With no selection option every signal and all of time is populated. Selections are a union:
a signal is populated if any `-signal`/`-regex`/config entry selects it, and a time is kept if
any window contains it.

YAML config (`-config`), read before the dump; see `tests/parsevcd/yamlselect/select.yaml`:

```
signals:
  - top.cpu.**
  - top.data
regex:
  - ^top\.pads\.pad_a$
time_windows:
  - 0:2000
  - start: 5000
    end: 8000
```

There is no `-nobanner`, `-quiet` or `-suppress`. Any other option prints Error 7030
"Unrecognized option : <opt>" followed by the usage. A malformed `-time_window` prints Error 7031
"Time window '<w>' is not of the form <start>:<end> ..." and the usage. With no arguments, or
without `-in`, the usage is printed. In all these cases nothing is parsed and the exit status is 0.

### Inputs / Outputs

- Reads: the `-in` VCD (as ISO-8859-1) and the `-config` file if given.
- Writes: `-out` (default `output.vcd` in the current directory), streamed from the model,
  holding only the populated signals and the value changes inside the time windows. `-activity`
  if given: a `# signal  idcode  width  changes  toggles` header, then one line per populated
  signal. Neither is written if the parse fails.
- Log: `ParseVCD.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (syntax errors, missing input
  file, missing licence feature, usage errors). 10 = no valid licence file.
  1 = `EDAUTILS_ROOT` missing/invalid (launcher).
- Message format: `ParseVCD: <Severity>: <id>: <text>` (the prefix is `ParseVCD`, not
  `parsevcd`); `<id>` is a 5-digit message number. Usage lines have no severity or id.
- Key messages: `File '<f>' not found ...` (Error, for `-in` and for `-config`), the ANTLR
  syntax error text (Error; nothing written), `No signal of '<f>' matches the pattern '<p>' ...`
  (Warning -- almost always a typo in a path), `Ignoring signal pattern '<p>' : it is not a
  valid pattern` (Error), `Skipping the line '<l>' at <config>:<n>` (Warning),
  `Populated N signal(s), M value change(s) over T simulation time(s), ...`,
  `Written decompiled VCD in file : <out>`,
  `Written the per signal activity report in file : <activity>`.
- A run that parses ends with `ParseVCD: Note: <id>: Found N error(s) and M warning(s) ...`.
  The usage paths return before that summary.

### Examples

Shipped:
- `examples/simple_vcd/` -- `runme.csh` runs `parsevcd -in simple_vcd.vcd` (writes
  `output.vcd`). The release self-test runs it and requires `Found 0 error(s)` in `ParseVCD.log`.
- `examples/Example_Aplication/` -- Java source (`src/ReadVCDAndPrint.java`) and a `Makefile`
  showing API use: `make clean; make`. No `runme.csh`.

From the regression suite (reference: `tests.edautilscommandline/tests/parsevcd/*/runme.csh`,
most via `../runme_common.csh`; golden `decompiled.vcd.gld`):

```
parsevcd -in example.vcd -out decompiled.vcd
parsevcd -in signalselect.vcd -out decompiled.vcd -signal top.cpu.reset -signal clk -time_window 1000:5000
parsevcd -in yamlselect.vcd -out decompiled.vcd -config select.yaml
parsevcd -in activityreport.vcd -out decompiled.vcd -activity activity.rpt
```

The large-input case is `tests.edautilscommandline/tests/bigparse/bigvcd/runme.csh` (a generated
200 MB dump, `parsevcd -in $infile -out decompiled.vcd` under a 768 MB heap).

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and default output into the current directory: give each parallel run its
  own working directory (or distinct `-out` and `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` **and** the `-out`
  file exists. With a selection, also check for the `No signal ... matches the pattern`
  warning: an unmatched pattern still gives a clean run.
- The output is equivalent, not byte-identical: header sections keep their text but are laid
  out one keyword per line (`$date` / text / `$end`). Compare outputs with a
  whitespace-insensitive diff (`diff -w -B -b`, as the regression suite does).

### See also

API docs in `doc/html/index.html`; designplayer-shell (also ships `parsevcd`).
