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() after close() 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 be None 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:

Variable instance appropriate for use with change().

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, calling change() with var 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.
dump_off(timestamp: Union[int, float]) → None[source]

Suspend dumping to VCD file.

dump_on(timestamp: Union[int, float]) → None[source]

Resume dumping to VCD file.

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 call change() 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. from register_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.
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.

format_value(value: ValueType, check: bool = True) → str[source]

Format value change for use in VCD stream.

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.

format_value(value: Union[float, int], check: bool = True) → str[source]

Format real value change for VCD stream.

Parameters:
  • value – Numeric changed value.
  • type – float or int
Raises:

ValueError – for invalid real value.

Returns:

string representing value change for use in a VCD stream.

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.