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 thedata
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 asscalar_change
.- 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 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
- 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. fromref [ 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
- 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. Otherwisevalue
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.