vcd.writer
¶
Write Value Change Dump files.
This module provides VCDWriter
for writing VCD files.
-
class
vcd.writer.
VCDPhaseError
[source]¶ Indicating a
VCDWriter
method was called in the wrong phase.For example, calling
register_var()
afterclose()
will raise this exception.
-
class
vcd.writer.
VCDWriter
(file: IO[str], timescale: Union[vcd.common.Timescale, Tuple[int, str], str] = '1 us', date: Optional[str] = None, comment: str = '', version: str = '', default_scope_type: Union[vcd.common.ScopeType, str] = <ScopeType.module: 'module'>, scope_sep: str = '.', check_values: bool = True, init_timestamp: Union[int, float] = 0)[source]¶ Value Change Dump writer.
A VCD file captures time-ordered changes to the value of variables.
Parameters: - file (file) – A file-like object to write the VCD data.
- timescale (str, tuple) – Scale of the VCD timestamps. The timescale may either be a string or a tuple containing an (int, str) pair.
- date (str) – Optional $date string used in the VCD header.
- comment (str) – Optional $comment string used in the VCD header.
- version (str) – Optional $version string used in the VCD header.
- default_scope_type (str) – Scope type for scopes where
set_scope_type()
is not called explicitly. - scope_sep (str) – Separator for scopes specified as strings.
- init_timestamp (int) – The initial timestamp. default=0
Raises: ValueError – for invalid timescale values
-
set_scope_type
(scope: Union[str, Sequence[str]], scope_type: Union[vcd.common.ScopeType, str]) → None[source]¶ Set the scope_type for a given scope.
The scope’s type may be set to one of the valid
ScopeType
values. VCD viewer applications may display different scope types differently.Parameters: - scope (str or sequence of str) – The scope to set the type of.
- scope_type (str) – A valid scope type string.
Raises: ValueError – for invalid scope_type
-
register_var
(scope: Union[str, Sequence[str]], name: str, var_type: Union[vcd.common.VarType, str], size: Union[int, Sequence[int], None] = None, init: Union[bool, int, float, str, None, Sequence[Union[int, bool, str, None]]] = None) → vcd.writer.Variable[source]¶ Register a new VCD variable.
All VCD variables must be registered prior to any value changes.
Parameters: - scope (str or sequence of str) – The hierarchical scope that the variable belongs within.
- name (str) – Name of the variable.
- var_type (VarType) – Type of the variable.
- size (int or tuple(int) or None) – Size, in bits, of the variable. The size may be expressed as an int or,
for vector variable types, a tuple of int. When the size is expressed as a
tuple, the value passed to
change()
must also be a tuple of same arity as the size tuple. Some variable types (‘integer’, ‘real’, ‘realtime’, and ‘event’) have a default size and thus size may beNone
for those variable types. - init – Optional initial value; defaults to ‘x’.
Raises: - VCDPhaseError – if any values have been changed
- ValueError – for invalid var_type value
- TypeError – for invalid parameter types
- KeyError – for duplicate var name
Returns:
-
register_alias
(scope: Union[str, Sequence[str]], name: str, var: vcd.writer.Variable) → None[source]¶ Register a variable alias.
The same VCD identifier may be associated with multiple reference names (“$var” declarations). This method associates an existing
Variable
instance with a different variable scope and/or name. The alias shares the same identifier, type, size, and value as the reference variable. Because the identifier is shared, callingchange()
withvar
changes the value of of all associated reference names.Parameters: - scope (str or sequence of str) – The hierarchical scope that the variable belongs within.
- name (str) – Name of the variable.
- var (Variable) – Existing variable to alias.
-
change
(var: vcd.writer.Variable, timestamp: Union[int, float], value: Union[bool, int, float, str, None, Sequence[Union[int, bool, str, None]]]) → None[source]¶ Change variable’s value in VCD stream.
This is the fundamental behavior of a
VCDWriter
instance. Each time a variable’s value changes, this method should be called.The timestamp must be in-order relative to timestamps from previous calls to
change()
. It is okay to callchange()
multiple times with the same timestamp, but never with a past timestamp.Note
change()
may be called multiple times before the timestamp progresses past 0. The last value change for each variable will go into the $dumpvars section.Parameters: - var (Variable) –
Variable
instance (i.e. fromregister_var()
). - timestamp (int) – Current simulation time.
- value – New value for var. For
VectorVariable
, if the variable’s size is a tuple, then value must be a tuple of the same arity.
Raises: - ValueError – if the value is not valid for var.
- VCDPhaseError – if the timestamp is out of order or the
VCDWriter
instance is closed.
- var (Variable) –
-
close
(timestamp: Union[int, float, None] = None) → None[source]¶ Close VCD writer.
Any buffered VCD data is flushed to the output file. After
close()
, no variable registration or value changes will be accepted.Parameters: timestamp (int) – optional final timestamp to insert into VCD stream. Note
The output file is not automatically closed. It is up to the user to ensure the output file is closed after the
VCDWriter
instance is closed.
-
flush
(timestamp: Union[int, float, None] = None) → None[source]¶ Flush any buffered VCD data to output file.
If the VCD header has not already been written, calling flush() will force the header to be written thus disallowing any further variable registration.
Parameters: timestamp (int) – optional timestamp to insert into VCD stream.
-
class
vcd.writer.
Variable
(ident: str, type: vcd.common.VarType, size: Union[int, Sequence[int]], init: ValueType)[source]¶ VCD variable details needed to call
VCDWriter.change()
.-
ident
¶ Identifier used in VCD output stream.
-
type
¶ VCD variable type; one of
VCDWriter.VAR_TYPES
.
-
size
¶ Size, in bits, of variable.
-
value
¶ Last value of variable.
-
-
class
vcd.writer.
ScalarVariable
(ident: str, type: vcd.common.VarType, size: Union[int, Sequence[int]], init: ValueType)[source]¶ One-bit VCD scalar.
This is a 4-state variable and thus may have values of 0, 1, ‘z’, or ‘x’.
-
format_value
(value: Union[int, bool, str, None], check: bool = True) → str[source]¶ Format scalar value change for VCD stream.
Parameters: value (str, bool, int, or None) – 1-bit (4-state) scalar value. Raises: ValueError – for invalid value. Returns: string representing value change for use in a VCD stream.
-
-
class
vcd.writer.
RealVariable
(ident: str, type: vcd.common.VarType, size: Union[int, Sequence[int]], init: ValueType)[source]¶ Real (IEEE-754 double-precision floating point) variable.
Values must be numeric and cannot be ‘x’ or ‘z’ states.
-
class
vcd.writer.
VectorVariable
(ident: str, type: vcd.common.VarType, size: Union[int, Sequence[int]], init: ValueType)[source]¶ Bit vector variable type.
This is for the various non-scalar and non-real variable types including integer, register, wire, etc.
-
format_value
(value: Union[int, bool, str, None], check: bool = True) → str[source]¶ Format value change for VCD stream.
Parameters: value – New value for the variable. Types value: int, str, or None Raises: ValueError – for some invalid values. A value of None is the same as ‘z’.
Warning
If value is of type
str
, all characters must be one of ‘01xzXZ’. For the sake of performance, checking is not done to ensure value strings only contain conforming characters. Thus it is possible to produce invalid VCD streams with invalid string values.
-
-
class
vcd.writer.
CompoundVectorVariable
(ident: str, type: vcd.common.VarType, size: Union[int, Sequence[int]], init: ValueType)[source]¶ Bit vector variable type with a compound size.
This is for the various non-scalar and non-real variable types including integer, register, wire, etc.
-
format_value
(value: Sequence[Union[int, bool, str, None]], check: bool = True) → str[source]¶ Format value change for VCD stream.
Parameters: value – Sequence of scalar components of the variable’s value. The sequence must be the same length as the variable’s size tuple. Returns: string representing value change for use in a VCD stream.
-