netlist_carpentry.io.vcd.parsing ¶

Functions:

get_hierarchy_dict –

Returns a nested dictionary containing all scopes and associated subscopes.
get_scope –

Returns the scope with the given name, if found.
map_names_to_circuit –

Maps all scope names to the corresponding circuit objects, so that for each scope, an associated module exists.
apply_vcd_data –

Applies the VCD data from the given waveform to all wires of the circuit.
equal_toggles –

Returns a dictionary of timestamps and a list of associated VCD vars that toggle on the given timestamps.
filter_signals –

Filters signals from the given VCD waveform based on how often they toggle or how many other signals toggle together with them.
filter_signals_per_scope –

Filters signals from the given VCD waveform based on how often they toggle or how many other signals toggle together with them and orders them by scope.
partition_all_vcd_signals –

Partition all VCD signals from the given files, such that all signals with equal toggling behavior and values are grouped together.
find_matching_signals –

Finds signals in the given VCD files that always have the same value and groups them together.

get_hierarchy_dict ¶

get_hierarchy_dict(wf: VCDWaveform) -> STR_DICT

Returns a nested dictionary containing all scopes and associated subscopes.

For example, if a scope Scope1 contains a scope Scope2, which in turn contains a scope Scope3, the result will be:

{ "Scope1": { "Scope2": { "Scope3": {} } } }

Parameters:

wf ¶
(VCDWaveform) –

The waveform of which the hierarchy should be extracted.

Returns:

STR_DICT ( STR_DICT ) –

A dictionary of all scopes, where for each scope key, a nested dictionary contains all subscopes.

get_scope ¶

get_scope(wf: VCDWaveform, scope_name: str) -> VCDScope

Returns the scope with the given name, if found.

Parameters:

wf ¶
(VCDWaveform) –

A waveform object.
scope_name ¶
(str) –

The name of the scope, where the corresponding object is wanted.

Raises:

VcdLoadingError –

If no scope with the given name was found.

Returns:

VCDScope ( VCDScope ) –

The scope with the given name.

map_names_to_circuit ¶

map_names_to_circuit(
    c: Circuit, wf: VCDWaveform, top_vcd_scope: str
) -> VCD_MAPPING

Maps all scope names to the corresponding circuit objects, so that for each scope, an associated module exists.

Parameters:

c ¶
(Circuit) –

The circuit to map
wf ¶
(VCDWaveform) –

The waveform object with the scopes and signal data.
top_vcd_scope ¶
(str) –

The name of the top-level VCD scope.

Returns:

VCD_MAPPING ( VCD_MAPPING ) –

A mapping of scope names (full paths) to corresponding modules of the given circuit.

apply_vcd_data ¶

apply_vcd_data(
    c: Circuit, wf: VCDWaveform, top_scope: str, scope: VCDScope = None
) -> None

Applies the VCD data from the given waveform to all wires of the circuit.

For each signal from the VCD waveform, a corresponding wire in the circuit is retrieved. This wire's metadata receives a new category vcd, into which the value trace for the signal is stored. With Wire.metadata.vcd, all stored VCD data can be seen afterwards. The vcd category is a dictionary, where the key is the full hierarchical path of the VCD variable. The value is a list of signal value changes as tuples, where the first element is the timestamp, and the second element is the new signal value.

If a module is instantiated multiple times throughout the circuit, the hierarchical path of each VCD variable will keep the VCD data uniquely identifiable. This means, if a module is instantiated twice, the wire's VCD metadata dictionary will contain two entries (if the VCD waveform captured both traces) together with value change list, one for each module instance.

Parameters:

c ¶
(Circuit) –

The circuit, in which the VCD signals should be mapped to the corresponding wires.
wf ¶
(VCDWaveform) –

A VCD waveform that was generated by simulating the given circuit with a certain testbench.
top_scope ¶
(str) –

The name of the top scope. Is required to identify which scope of the VCD waveform matches the top-level module of the circuit.
scope ¶
(VCDScope, default: None ) –

Optionally, a scope can be provided. If provided, only VCD vars inside this scope (and subscopes) are applied to the given circuit. Defaults to None.

equal_toggles ¶

equal_toggles(
    wf: VCDWaveform,
    scope: Optional[VCDScope] = None,
    vcd_vars: Optional[List[Union[str, VCDVar]]] = None,
) -> SIGNAL_TOGGLE_DICT

Returns a dictionary of timestamps and a list of associated VCD vars that toggle on the given timestamps.

Parameters:

wf ¶
(VCDWaveform) –

The waveform in which equally toggling signals should be identified.
scope ¶
(Optional[VCDScope], default: None ) –

A scope in which the signals should be analyzed. Defaults to None, in which case, all scopes (i.e. all vars throughout the whole hierarchy) are analyzed.
vcd_vars ¶
(Optional[List[Union[str, VCDVar]]], default: None ) –

A list of vars (or names of vars) which should be analyzed. Must be a subset of all existing vars within the given scope or the waveform. Defaults to None, in which case the whole scope or the waveform is considered. However, if a list is given and empty, no vars are checked, and the result will be an empty dictionary.

Returns:

SIGNAL_TOGGLE_DICT ( SIGNAL_TOGGLE_DICT ) –

A dictionary, where each key is a tuple of timestamps, and the associated list consists of VCD vars that toggle at the given timestamps.

filter_signals ¶

filter_signals(
    wf: VCDWaveform,
    scope: Optional[VCDScope] = None,
    vcd_vars: Optional[List[Union[str, VCDVar]]] = None,
    min_occurences: PositiveInt = 1,
    min_changes: NonNegativeInt = 0,
) -> SIGNAL_TOGGLE_DICT

Filters signals from the given VCD waveform based on how often they toggle or how many other signals toggle together with them.

Parameters:

wf ¶
(VCDWaveform) –

The waveform in which equally toggling signals should be identified.
scope ¶
(Optional[VCDScope], default: None ) –

The scope in which signals should be filtered. Defaults to None. If set to None, all vars from the waveform are considered and filtered.
vcd_vars ¶
(Optional[List[Union[str, VCDVar]]], default: None ) –

A list of vars (or names of vars) which should be analyzed. Must be a subset of all existing vars within the given scope or the waveform. Defaults to None, in which case the whole scope or the waveform is considered. However, if a list is given and empty, no vars are checked, and the result will be an empty dictionary.
min_occurences ¶
(PositiveInt, default: 1 ) –

The minimal number of equal signals to include. If e.g. set to 2, the resulting dictionary will only contain signal traces, where at least 2 signals always have the same toggling timestamps. Defaults to 1, which means that signals will also be included if they are "unique" regarding their toggling timestamps.
min_changes ¶
(NonNegativeInt, default: 0 ) –

The minimal number of signal changes. If e.g. set to 1, only signals are included that change their value at least once. Defaults to 0.

Returns:

SIGNAL_TOGGLE_DICT ( SIGNAL_TOGGLE_DICT ) –

A dictionary of toggling signals, where each key is a tuple of timestamps, and the associated list consists of VCD vars that toggle at the given timestamps, matching the given criterias.

filter_signals_per_scope ¶

filter_signals_per_scope(
    wf: VCDWaveform,
    scope: Optional[VCDScope],
    signal_dict: Dict[str, SIGNAL_TOGGLE_DICT],
    vcd_vars: Optional[List[Union[str, VCDVar]]] = None,
    min_occurences: PositiveInt = 1,
    min_changes: NonNegativeInt = 0,
) -> None

Filters signals from the given VCD waveform based on how often they toggle or how many other signals toggle together with them and orders them by scope.

This is done by recursively iterating through all subscopes, so that the given signal_dict in populated for every scope. The result then contains alls variables, starting from the given scope and below, so that each subdict only contains matching signals for that specific scope. This is useful to collect signals toggling at the same timestamps within a given module, especially in regards to optimization and simplification of said module.

Parameters:

wf ¶
(VCDWaveform) –

The waveform in which equally toggling signals should be identified.
scope ¶
(Optional[VCDScope]) –

The scope in which signals should be filtered. Defaults to None. If set to None, all vars from the waveform are considered and filtered.
signal_dict ¶
(Dict[str, SIGNAL_TOGGLE_DICT]) –

A dictionary which is updated and expanded in every iteration.
vcd_vars ¶
(Optional[List[Union[str, VCDVar]]], default: None ) –

A list of vars (or names of vars) which should be analyzed. Must be a subset of all existing vars within the given scope or the waveform. Defaults to None, in which case the whole scope or the waveform is considered. However, if a list is given and empty, no vars are checked, and the result will be an empty dictionary.
min_occurences ¶
(PositiveInt, default: 1 ) –

The minimal number of equal signals to include. If e.g. set to 2, the resulting dictionary will only contain signal traces, where at least 2 signals always have the same toggling timestamps. Defaults to 1, which means that signals will also be included if they are "unique" regarding their toggling timestamps.
min_changes ¶
(NonNegativeInt, default: 0 ) –

The minimal number of signal changes. If e.g. set to 1, only signals are included that change their value at least once. Defaults to 0.

Returns:

SIGNAL_TOGGLE_DICT ( None ) –

A dictionary of toggling signals, where each key is a scope name and the value is a dictionary. Within this inner dictionary, the keys are tuples of timestamps (comparable to the results of the equal_toggles and filter_signals functions), and the associated list consists of VCD vars that toggle at the given timestamps, matching the given criterias.

partition_all_vcd_signals ¶

partition_all_vcd_signals(
    vcd_filepaths: List[Union[Path, str]],
) -> Optional[SIGNAL_GROUPS]

Partition all VCD signals from the given files, such that all signals with equal toggling behavior and values are grouped together.

The names of the top-level scopes (i.e. the testbench names) must match in all VCD files, otherwise grouping and matching will not work, as the root names would differ!

Parameters:

vcd_filepaths ¶
(List[Path, str]) –

The paths to the VCD files to analyze and partition.

Returns:

Optional[SIGNAL_GROUPS] –

Optional[List[List[str]]]: A partitioning list of all VCD vars, where each list consists of VCD var names that always have equal values and might thus be logically equivalent.

find_matching_signals ¶

find_matching_signals(vcd_filepaths: List[Union[Path, str]]) -> SIGNAL_GROUPS

Finds signals in the given VCD files that always have the same value and groups them together.

The names of the top-level scopes (i.e. the testbench names) must match in all VCD files, otherwise grouping and matching will not work, as the root names would differ!

Parameters:

vcd_filepaths ¶
(List[Union[Path, str]]) –

List of strings (paths to VCD files).

Returns:

SIGNAL_GROUPS –

List[List[str]]: List of lists of signal names that match perfectly in timing AND value.

netlist_carpentry.io.vcd.parsing ¶

get_hierarchy_dict ¶

`wf` ¶

get_scope ¶

`wf` ¶

`scope_name` ¶

map_names_to_circuit ¶

`c` ¶

`wf` ¶

`top_vcd_scope` ¶

apply_vcd_data ¶

`c` ¶

`wf` ¶

`top_scope` ¶

`scope` ¶

equal_toggles ¶

`wf` ¶

`scope` ¶

`vcd_vars` ¶

filter_signals ¶

`wf` ¶

`scope` ¶

`vcd_vars` ¶

`min_occurences` ¶

`min_changes` ¶

filter_signals_per_scope ¶

`wf` ¶

`scope` ¶

`signal_dict` ¶

`vcd_vars` ¶

`min_occurences` ¶

`min_changes` ¶

partition_all_vcd_signals ¶

`vcd_filepaths` ¶

find_matching_signals ¶

`vcd_filepaths` ¶

netlist_carpentry.io.vcd.parsing ¶

get_hierarchy_dict ¶

wf ¶

get_scope ¶

wf ¶

scope_name ¶

map_names_to_circuit ¶

c ¶

wf ¶

top_vcd_scope ¶

apply_vcd_data ¶

c ¶

wf ¶

top_scope ¶

scope ¶

equal_toggles ¶

wf ¶

scope ¶

vcd_vars ¶

filter_signals ¶

wf ¶

scope ¶

vcd_vars ¶

min_occurences ¶

min_changes ¶

filter_signals_per_scope ¶

wf ¶

scope ¶

signal_dict ¶

vcd_vars ¶

min_occurences ¶

min_changes ¶

partition_all_vcd_signals ¶

vcd_filepaths ¶

find_matching_signals ¶

vcd_filepaths ¶

`wf` ¶

`wf` ¶

`scope_name` ¶

`c` ¶

`wf` ¶

`top_vcd_scope` ¶

`c` ¶

`wf` ¶

`top_scope` ¶

`scope` ¶

`wf` ¶

`scope` ¶

`vcd_vars` ¶

`wf` ¶

`scope` ¶

`vcd_vars` ¶

`min_occurences` ¶

`min_changes` ¶

`wf` ¶

`scope` ¶

`signal_dict` ¶

`vcd_vars` ¶

`min_occurences` ¶

`min_changes` ¶

`vcd_filepaths` ¶

`vcd_filepaths` ¶