`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: Union[io.BufferedIOBase, io.RawIOBase], buf_size: Optional[int] = None) → Iterator[vcd.reader.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: vcd.reader.Location, msg: str)[source]¶

Catch-all error for any VCD parsing errors.

loc = None¶: Location within VCD file where error was detected.

class vcd.reader.Token[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¶: The kind of token.

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

data¶: Data associated with the token. The data type depends on kind.

comment¶: Unstructured text from a $comment declaration.

date¶: Unstructured text from a $date declaration.

scope¶: Scope type and identifier from $scope declaration.

timescale¶: Magnitude and unit from $timescale declaration.

var¶: Details from a $var declaration.

version¶: Unstructured text from a $version declaration.

time_change¶: Simulation time change.

scalar_change¶: Scalar value change descriptor.

vector_change¶: Vector value change descriptor.

real_change¶: Real (float) value change descriptor.

string_change¶: String value change descriptor.

class vcd.reader.TokenKind[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[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_¶: Type of variable

size¶: Size, in bits, of variable

id_code¶

Identifer code of variable.

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

reference¶

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¶

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[source]¶

VCD scope declaration.

Examples:

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

type_¶: Type of scope

ident¶: Scope name

class vcd.reader.ScalarChange[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¶: Identifier code of associated variable.

value¶: New value of associated scalar variable.

class vcd.reader.VectorChange[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¶: Identifier code of associated variable.

value¶: New value of associated vector variable.

class vcd.reader.RealChange[source]¶

Real value (floating point) change descriptor.

id_code¶: Identifier code of associated variable.

value¶: New value of associated real variable.

class vcd.reader.StringChange[source]¶

String value change descriptor.

Strings are VCD extension supported by GTKWave.

id_code¶: Identifier code of associated variable.

value¶: New value of associated string variable.

class vcd.reader.Location[source]¶

Describe location within VCD stream/file.

line¶: Line number

column¶: Column number

class vcd.reader.Span[source]¶

Describe location span within VCD stream/file.

start¶: Start of span

end¶: End of span

vcd.reader¶

`vcd.reader`¶