`vcd.reader`

Read Value Change Dump (VCD) files.

The primary interface is the tokenize() generator function, parses a binary VCD stream, yielding tokens as they are encountered.

>>> import io
>>> from vcd.reader import TokenKind, tokenize
>>> vcd = b"$date today $end $timescale 1 ns $end"
>>> tokens = tokenize(io.BytesIO(vcd))
>>> token = next(tokens)
>>> assert token.kind is TokenKind.DATE
>>> assert token.date == "today"
>>> token = next(tokens)
>>> assert token.kind is TokenKind.TIMESCALE
>>> assert token.timescale.magnitude == 1
>>> assert token.timescale.unit.value == "ns"

vcd.reader.tokenize(stream: BufferedIOBase | RawIOBase, buf_size: int | None = None) → Iterator[Token][source]

Parse VCD stream into tokens.

The input stream must be opened in binary mode. E.g. with open(path, 'rb').

class vcd.reader.VCDParseError(loc: Location, msg: str)[source]

Catch-all error for any VCD parsing errors.

loc: Location: Location within VCD file where error was detected.

VCD token yielded from tokenize().

These are relatively high-level tokens insofar as each token fully captures an entire VCD declaration, command, or change descriptor.

The kind attribute determines the data type. Various kind-specific properties provide runtime type-checked access to the kind-specific data.

Note

The data attribute may be accessed directly to avoid runtime type checks and thus achieve better runtime performance versus accessing kind-specific properties such as scalar_change.

kind: TokenKind: The kind of token.

span: Span: The start and end location of the token within the file/stream.

data: None | int | str | ScopeDecl | Timescale | VarDecl | ScalarChange | VectorChange | RealChange | StringChange: Data associated with the token. The data type depends on kind.

property attr: str

Unstructured text from an $attrbegin declaration.

Attribute declarations are a nonstandard VCD extension emitted by nvc and GTKWave’s fst2vcd, carrying FST-style attributes such as source locations and VHDL type information.

property comment: str: Unstructured text from a $comment declaration.

property date: str: Unstructured text from a $date declaration.

property scope: ScopeDecl: Scope type and identifier from $scope declaration.

property timescale: Timescale: Magnitude and unit from $timescale declaration.

property var: VarDecl: Details from a $var declaration.

property version: str: Unstructured text from a $version declaration.

property time_change: int: Simulation time change.

property scalar_change: ScalarChange: Scalar value change descriptor.

property vector_change: VectorChange: Vector value change descriptor.

property real_change: RealChange: Real (float) value change descriptor.

property string_change: StringChange: String value change descriptor.

class vcd.reader.TokenKind(*values)[source]

Kinds of VCD tokens.

COMMENT = 1

DATE = 2

ENDDEFINITIONS = 3

SCOPE = 4

TIMESCALE = 5

UPSCOPE = 6

VAR = 7

VERSION = 8

DUMPALL = 9

DUMPOFF = 10

DUMPON = 11

DUMPVARS = 12

END = 13

CHANGE_TIME = 14

CHANGE_SCALAR = 15

CHANGE_VECTOR = 16

CHANGE_REAL = 17

CHANGE_STRING = 18

ATTRBEGIN = 19

ATTREND = 20

class vcd.reader.VarDecl(type_: VarType, size: int, id_code: str, reference: str, bit_index: None | int | tuple[int, int])[source]

VCD variable declaration.

Examples:

$var wire 4 !@# foobar [ 3 : 1 ] $end
$var real 1 aaa foobar $end
$var integer 32 > foobar[8] $end
$var reg 178 /Y mem_array[0] [177:0] $end

type_: VarType: Type of variable

size: int: Size, in bits, of variable

id_code: str

Identifier code of variable.

This code is used in subsequent value change descriptors to map-back to this variable declaration.

reference: str

Reference name of variable.

This human-readable name typically corresponds to the name of a variable in the model that output the VCD.

bit_index: None | int | tuple[int, int]

Optional range of bits to select from the variable.

May select a single bit index, e.g. ref [ 3 ]. Or a range of bits, e.g. from ref [ 7 : 3 ] (MSB index then LSB index).

Only the final bracketed section of a reference is a candidate bit index, and only when its contents are possibly-negative decimal indices. Any earlier bracketed sections belong to reference, as do brackets within an escaped identifier.

Negative indices, e.g. ref[2:-2], are a nonstandard convention for annotating the integer and fractional parts of a fixed-point variable.

class vcd.reader.ScopeDecl(type_: ScopeType, ident: str)[source]

VCD scope declaration.

Examples:

$scope module Foo $end
$scope
   fork alpha_beta
$end

type_: ScopeType: Type of scope

ident: str: Scope name; empty for unnamed scopes

class vcd.reader.ScalarChange(id_code: str, value: str)[source]

Scalar value change descriptor.

A scalar is a single value. IEEE 1800 specifies the four states ‘0’, ‘1’, ‘X’, and ‘Z’. VHDL simulators such as GHDL also emit the nine-state std_logic values, which add ‘U’, ‘W’, ‘L’, ‘H’, and ‘-‘. Letter case is preserved from the VCD stream.

id_code: str: Identifier code of associated variable.

value: str: New value of associated scalar variable.

class vcd.reader.VectorChange(id_code: str, value: int | str)[source]

Vector value change descriptor.

A vector value consists of multiple state values. IEEE 1800 specifies the four states 0, 1, X, and Z; VHDL simulators such as GHDL also emit the nine-state std_logic values, which add U, W, L, H, and -. When a vector value consists entirely of 0 and 1 states, value will be an int. Otherwise value will be a str with letter case preserved from the VCD stream.

id_code: str: Identifier code of associated variable.

value: int | str: New value of associated vector variable.

class vcd.reader.RealChange(id_code: str, value: float)[source]

Real value (floating point) change descriptor.

id_code: str: Identifier code of associated variable.

value: float: New value of associated real variable.

class vcd.reader.StringChange(id_code: str, value: str)[source]

String value change descriptor.

Strings are VCD extension supported by GTKWave.

id_code: str: Identifier code of associated variable.

value: str: New value of associated string variable.

class vcd.reader.Location(line: int, column: int)[source]

Describe location within VCD stream/file.

line: int: Line number

column: int: Column number

class vcd.reader.Span(start: Location, end: Location)[source]

Describe location span within VCD stream/file.

start: Location: Start of span

end: Location: End of span

vcd.reader

`vcd.reader`