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.value == 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 within VCD file where error was detected.

class vcd.reader.Token(kind: TokenKind, span: Span, data: None | int | str | ScopeDecl | Timescale | VarDecl | ScalarChange | VectorChange | RealChange | StringChange)[source]

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 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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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
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
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).

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

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

Scalar value change descriptor.

A scalar is a single 4-state value. The value is one of ‘0’, ‘1’, ‘X’, or ‘Z’.

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 4-state values, where the four states are 0, 1, X, and Z. When a vector value consists entirely of 0 and 1 states, value will be an int. Otherwise value will be a str.

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