VCDWriter Class Reference

Public Member Functions
def	__init__ (self, file, timescale='1 us', date=None, comment='', version='', default_scope_type='module', scope_sep='.', check_values=True, init_timestamp=0)
def	set_scope_type (self, scope, scope_type)
def	register_var (self, scope, name, var_type, size=None, init=None, ident=None)
def	dump_off (self, timestamp)
def	dump_on (self, timestamp)
def	change (self, var, timestamp, value)
def	__enter__ (self)
def	__exit__ (self, exc_type, exc_val, exc_tb)
def	close (self, timestamp=None)
def	flush (self, timestamp=None)

Static Public Attributes
list	SCOPE_TYPES = ['begin', 'fork', 'function', 'module', 'task']
	Valid VCD scope types.
list	VAR_TYPES
	Valid VCD variable types.
list	TIMESCALE_NUMS = [1, 10, 100]
	Valid timescale numbers.
list	TIMESCALE_UNITS = ['s', 'ms', 'us', 'ns', 'ps', 'fs']
	Valid timescale units.

Protected Member Functions
def	_dump_off (self, timestamp)
def	_dump_values (self, keyword)
def	_get_scope_tuple (self, scope)
def	_check_timescale (cls, timescale)
def	_gen_header (self)
def	_finalize_registration (self)

Protected Attributes
	_ofile
	output file
	_header_keywords
	header keywords
	_default_scope_type
	set default_scope_type
	_scope_sep
	set scope_sep
	_check_values
	set check_values
	_registering
	set registering
	_closed
	set closed
	_dumping
	set dumping
	_next_var_id
	set next_var_id
	_scope_var_strs
	set scope_var_strs
	_scope_var_names
	set scope_var_names
	_scope_types
	set scopr_types
	_ident_values
	set ident_values
	_timestamp
	set time_stamp

Detailed Description

Value Change Dump writer.

A VCD file captures time-ordered changes to the value of variables.

:param file file: A file-like object to write the VCD data.
:param timescale:
    Scale of the VCD timestamps. The timescale may either be a string or a
    tuple containing an (int, str) pair.
:type timescale: str, tuple
:param str date: Optional `$date` string used in the VCD header.
:param str comment: Optional `$comment` string used in the VCD header.
:param str version: Optional `$version` string used in the VCD header.
:param str default_scope_type: Scope type for scopes where
        :meth:`set_scope_type()` is not called explicitly.
:param str scope_sep: Separator for scopes specified as strings.
:param int init_timestamp: The initial timestamp. default=0
:raises ValueError: for invalid timescale values

Definition at line 44 of file writer.py.

Constructor & Destructor Documentation

__init__()

def __init__	(		self,
			file,
			timescale = '1 us',
			date = None,
			comment = '',
			version = '',
			default_scope_type = 'module',
			scope_sep = '.',
			check_values = True,
			init_timestamp = 0
	)

Initialization of VCDWriter

Definition at line 79 of file writer.py.

                 check_values=True, init_timestamp=0):
        """Initialization of VCDWriter"""
        
        self._ofile = file
        
        self._header_keywords = {
            '$timescale': self._check_timescale(timescale),
            '$date': str(datetime.datetime.now()) if date is None else date,
            '$comment': comment,
            '$version': version,
        }
        if default_scope_type not in self.SCOPE_TYPES:
            raise ValueError(f'Invalid default scope type ({default_scope_type})')
        
        self._default_scope_type = default_scope_type
        
        self._scope_sep = scope_sep
        
        self._check_values = check_values
        
        self._registering = True
        
        self._closed = False
        
        self._dumping = True
        
        self._next_var_id = 0
        
        self._scope_var_strs = {}
        
        self._scope_var_names = {}
        
        self._scope_types = {}
        
        self._ident_values = OrderedDict()
        
        self._timestamp = int(init_timestamp)
 

Member Function Documentation

__enter__()

def __enter__

(

self

)

enter of VCDWriter

Definition at line 357 of file writer.py.

    def __enter__(self):
        """enter of VCDWriter"""
        return self
 

__exit__()

def __exit__	(		self,
			exc_type,
			exc_val,
			exc_tb
	)

exit of VCDWriter

Definition at line 361 of file writer.py.

    def __exit__(self, exc_type, exc_val, exc_tb):
        """exit of VCDWriter"""
        self.close()
 

_check_timescale()

def _check_timescale (   cls,   timescale  )

protected

check time scale function of the VCDWrite

Definition at line 325 of file writer.py.

    def _check_timescale(cls, timescale):
        """check time scale function of the VCDWrite"""
        if isinstance(timescale, (list, tuple)):
            if len(timescale) == 1:
                num_str = '1'
                unit = timescale[0]
            elif len(timescale) == 2:
                num, unit = timescale
                if num not in cls.TIMESCALE_NUMS:
                    raise ValueError(f'Invalid timescale num {num}')
                num_str = str(num)
            else:
                raise ValueError(f'Invalid timescale {timescale}')
        elif isinstance(timescale, str):
            if timescale in cls.TIMESCALE_UNITS:
                num_str = '1'
                unit = timescale
            else:
                for num in sorted(cls.TIMESCALE_NUMS, reverse=True):
                    num_str = str(num)
                    if timescale.startswith(num_str):
                        unit = timescale[len(num_str):].lstrip(' ')
                        break
                else:
                    raise ValueError(
                        f'Invalid timescale num {timescale}')
        else:
            raise TypeError(f'Invalid timescale type {type(timescale).__name__}')
        if unit not in cls.TIMESCALE_UNITS:
            raise ValueError(f'Invalid timescale unit "{unit}"')
        return ' '.join([num_str, unit])
 

_dump_off()

def _dump_off (   self,   timestamp  )

protected

Stop dumping to VCD file.

Definition at line 238 of file writer.py.

    def _dump_off(self, timestamp):
        """Stop dumping to VCD file."""
        print('#' + str(int(timestamp)), file=self._ofile)
        print('$dumpoff', file=self._ofile)
        for ident, val_str in self._ident_values.items():
            if val_str[0] == 'b':
                print('bx', ident, file=self._ofile)
            elif val_str[0] == 'r':
                pass  # real variables cannot have 'z' or 'x' state
            else:
                print('x', ident, sep='', file=self._ofile)
        print('$end', file=self._ofile)
 

_dump_values()

def _dump_values (   self,   keyword  )

protected

Dump values to VCD file.

Definition at line 259 of file writer.py.

    def _dump_values(self, keyword):
        """Dump values to VCD file."""
        print(keyword, file=self._ofile)
        # TODO: events should be excluded
        print(*self._ident_values.values(),
              sep='\n', file=self._ofile)
        print('$end', file=self._ofile)
 

_finalize_registration()

def _finalize_registration (   self )

protected

finalize registration of VCDWriter

Definition at line 444 of file writer.py.

    def _finalize_registration(self):
        """finalize registration of VCDWriter"""
        assert self._registering
        print(*self._gen_header(), sep='\n', file=self._ofile)
        if self._ident_values:
            print('#' + str(int(self._timestamp)), file=self._ofile)
            self._dump_values('$dumpvars')
            if not self._dumping:
                self._dump_off(self._timestamp)
        self._registering = False
 
        # This state is not needed after registration phase.
        self._header_keywords.clear()
        self._scope_types.clear()
        self._scope_var_names.clear()
 
 

_gen_header()

def _gen_header (   self )

protected

generate header for VCDWriter

Definition at line 404 of file writer.py.

    def _gen_header(self):
        """generate header for VCDWriter"""
        for kwname, kwvalue in sorted(self._header_keywords.items()):
            if not kwvalue:
                continue
            lines = kwvalue.split('\n')
            if len(lines) == 1:
                yield f'{kwname} {lines[0]} $end'
            else:
                yield kwname
                for line in lines:
                    yield '\t' + line
                yield '$end'
 
        prev_scope = []
        for scope in sorted(self._scope_var_strs):
            var_strs = self._scope_var_strs.pop(scope)
 
            for i, (prev, this) in enumerate(zip_longest(prev_scope, scope)):
                if prev != this:
                    for _ in prev_scope[i:]:
                        yield '$upscope $end'
 
                    for j, name in enumerate(scope[i:]):
                        scope_type = self._scope_types.get(
                            scope[:i + j + 1], self._default_scope_type)
                        yield f'$scope {scope_type} {name} $end'
                    break
            else:
                assert scope != prev_scope  # pragma no cover
 
            yield from var_strs
 
            prev_scope = scope
 
        for _ in prev_scope:
            yield '$upscope $end'
 
        yield '$enddefinitions $end'
 

_get_scope_tuple()

def _get_scope_tuple (   self,   scope  )

protected

get scope tuple function of the VCDWrite

Definition at line 315 of file writer.py.

    def _get_scope_tuple(self, scope):
        """get scope tuple function of the VCDWrite"""
        if isinstance(scope, str):
            return tuple(scope.split(self._scope_sep))
        if isinstance(scope, (list, tuple)):
            return tuple(scope)
        else:
            raise TypeError(f'Invalid scope {scope}')
 

change()

def change	(		self,
			var,
			timestamp,
			value
	)

Change variable's value in VCD stream.

This is the fundamental behavior of a :class:`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 :meth:`change()`. It is okay to call :meth:`change()` multiple
times with the same *timestamp*, but never with a past *timestamp*.

.. Note::

    :meth:`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.

:param Variable var: :class:`Variable` instance (i.e. from
                     :meth:`register_var()`).
:param int timestamp: Current simulation time.
:param value:
    New value for *var*. For :class:`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*.
:raises VCDPhaseError: if the timestamp is out of order or the
                       :class:`VCDWriter` instance is closed.

Definition at line 267 of file writer.py.

    def change(self, var, timestamp, value):
        """Change variable's value in VCD stream.
 
        This is the fundamental behavior of a :class:`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 :meth:`change()`. It is okay to call :meth:`change()` multiple
        times with the same *timestamp*, but never with a past *timestamp*.
 
        .. Note::
 
            :meth:`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.
 
        :param Variable var: :class:`Variable` instance (i.e. from
                             :meth:`register_var()`).
        :param int timestamp: Current simulation time.
        :param value:
            New value for *var*. For :class:`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*.
        :raises VCDPhaseError: if the timestamp is out of order or the
                               :class:`VCDWriter` instance is closed.
 
        """
        if timestamp < self._timestamp:
            raise VCDPhaseError(f'Out of order value change ({var})')
        elif self._closed:
            raise VCDPhaseError('Cannot change value after close()')
 
        val_str = var.format_value(value, self._check_values)
        ts_int = int(timestamp)
 
        if ts_int > self._timestamp:
            if self._registering:
                self._finalize_registration()
            if self._dumping:
                print('#', ts_int, sep='', file=self._ofile)
            self._timestamp = ts_int
 
        if self._dumping and not self._registering:
            print(val_str, file=self._ofile)
        else:
            self._ident_values[var.ident] = val_str
 

close()

def close	(		self,
			timestamp = None
	)

Close VCD writer.

Any buffered VCD data is flushed to the output file. After
:meth:`close()`, no variable registration or value changes will be
accepted.

:param int timestamp: 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 :class:`VCDWriter`
    instance is closed.

Definition at line 365 of file writer.py.

    def close(self, timestamp=None):
        """Close VCD writer.
 
        Any buffered VCD data is flushed to the output file. After
        :meth:`close()`, no variable registration or value changes will be
        accepted.
 
        :param int timestamp: 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 :class:`VCDWriter`
            instance is closed.
 
        """
        if not self._closed:
            self.flush(timestamp)
            self._closed = True
 

dump_off()

def dump_off	(		self,
			timestamp
	)

Suspend dumping to VCD file.

Definition at line 231 of file writer.py.

    def dump_off(self, timestamp):
        """Suspend dumping to VCD file."""
        if self._dumping and not self._registering and self._ident_values:
            """set dump_off"""
            self._dump_off(timestamp)
        self._dumping = False
 

dump_on()

def dump_on	(		self,
			timestamp
	)

Resume dumping to VCD file.

Definition at line 251 of file writer.py.

    def dump_on(self, timestamp):
        """Resume dumping to VCD file."""
        if not self._dumping and not self._registering and self._ident_values:
            print('#' + str(int(timestamp)), file=self._ofile)
            """set dump_values"""
            self._dump_values('$dumpon')
        self._dumping = True
 

flush()

def flush	(		self,
			timestamp = None
	)

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.

:param int timestamp: optional timestamp to insert into VCD stream.

Definition at line 386 of file writer.py.

    def flush(self, timestamp=None):
        """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.
 
        :param int timestamp: optional timestamp to insert into VCD stream.
 
        """
        if self._closed:
            raise VCDPhaseError('Cannot flush() after close()')
        if self._registering:
            self._finalize_registration()
        if timestamp is not None and timestamp > self._timestamp:
            print("#", int(timestamp), sep='', file=self._ofile)
        self._ofile.flush()
 

register_var()

def register_var	(		self,
			scope,
			name,
			var_type,
			size = None,
			init = None,
			ident = None
	)

Register a VCD variable and return function to change value.

All VCD variables must be registered prior to any value changes.

.. Note::

    The variable `name` differs from the variable's `ident`
    (identifier). The `name` (also known as `ref`) is meant to refer to
    the variable name in the code being traced and is visible in VCD
    viewer applications.  The `ident`, however, is only used within the
    VCD file and can be auto-generated (by specifying ``ident=None``)
    for most applications.

:param scope: The hierarchical scope that the variable belongs within.
:type scope: str or sequence of str
:param str name: Name of the variable.
:param str var_type: One of :const:`VAR_TYPES`.
:param size:
    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 :meth:`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.
:type size: int or tuple(int) or None
:param init: Optional initial value; defaults to 'x'.
:param str ident: Optional identifier for use in the VCD stream.
:raises VCDPhaseError: if any values have been changed
:raises ValueError: for invalid var_type value
:raises TypeError: for invalid parameter types
:raises KeyError: for duplicate var name
:returns: :class:`Variable` instance appropriate for use with
          :meth:`change()`.

Definition at line 136 of file writer.py.

                     ident=None):
        """Register a VCD variable and return function to change value.
 
        All VCD variables must be registered prior to any value changes.
 
        .. Note::
 
            The variable `name` differs from the variable's `ident`
            (identifier). The `name` (also known as `ref`) is meant to refer to
            the variable name in the code being traced and is visible in VCD
            viewer applications.  The `ident`, however, is only used within the
            VCD file and can be auto-generated (by specifying ``ident=None``)
            for most applications.
 
        :param scope: The hierarchical scope that the variable belongs within.
        :type scope: str or sequence of str
        :param str name: Name of the variable.
        :param str var_type: One of :const:`VAR_TYPES`.
        :param size:
            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 :meth:`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.
        :type size: int or tuple(int) or None
        :param init: Optional initial value; defaults to 'x'.
        :param str ident: Optional identifier for use in the VCD stream.
        :raises VCDPhaseError: if any values have been changed
        :raises ValueError: for invalid var_type value
        :raises TypeError: for invalid parameter types
        :raises KeyError: for duplicate var name
        :returns: :class:`Variable` instance appropriate for use with
                  :meth:`change()`.
 
        """
        if self._closed:
            raise VCDPhaseError('Cannot register after close().')
        elif not self._registering:
            raise VCDPhaseError('Cannot register after time 0.')
        elif var_type not in self.VAR_TYPES:
            raise ValueError(f'Invalid var_type "{var_type}"')
 
        scope_tuple = self._get_scope_tuple(scope)
 
        scope_names = self._scope_var_names.setdefault(scope_tuple, [])
        if name in scope_names:
            raise KeyError(f'Duplicate var {name} in scope {scope}')
 
        if ident is None:
            ident = format(self._next_var_id, 'x')
 
        if size is None:
            if var_type in ['integer', 'real', 'realtime']:
                size = 64
            elif var_type == 'event':
                size = 1
            else:
                raise ValueError(
                    f'Must supply size for {var_type} var_type')
 
        if isinstance(size, Sequence):
            size = tuple(size)
            var_size = sum(size)
        else:
            var_size = size
 
        var_str = f'$var {var_type} {var_size} {ident} {name} $end'
 
        if init is None:
            if var_type == 'real':
                init = 0.0
            elif isinstance(size, tuple):
                init = tuple('x' * len(size))
            else:
                init = 'x'
 
        if size == 1:
            var = ScalarVariable(ident, var_type, size)
        elif var_type == 'real':
            var = RealVariable(ident, var_type, size)
        else:
            var = VectorVariable(ident, var_type, size)
 
        if var_type != 'event':
            self.change(var, self._timestamp, init)
 
        # Only alter state after change_func() succeeds
        self._next_var_id += 1
        self._scope_var_strs.setdefault(scope_tuple, []).append(var_str)
        scope_names.append(name)
 
        return var
 

set_scope_type()

def set_scope_type	(		self,
			scope,
			scope_type
	)

Set the scope_type for a given scope.

The scope's type may be set to one of the valid :const:`SCOPE_TYPES`.
VCD viewer applications may display different scope types differently.

:param scope: The scope to set the type of.
:type scope: str or sequence of str
:param str scope_type: A valid scope type string.
:raises ValueError: for invalid `scope_type`

Definition at line 119 of file writer.py.

    def set_scope_type(self, scope, scope_type):
        """Set the scope_type for a given scope.
 
        The scope's type may be set to one of the valid :const:`SCOPE_TYPES`.
        VCD viewer applications may display different scope types differently.
 
        :param scope: The scope to set the type of.
        :type scope: str or sequence of str
        :param str scope_type: A valid scope type string.
        :raises ValueError: for invalid `scope_type`
 
        """
        if scope_type is not None and scope_type not in self.SCOPE_TYPES:
            raise ValueError(f'Invalid scope_type "{scope_type}"')
        scope_tuple = self._get_scope_tuple(scope)
        self._scope_types[scope_tuple] = scope_type
 

Member Data Documentation

_check_values

_check_values

protected

set check_values

Definition at line 99 of file writer.py.

_closed

_closed

protected

set closed

Definition at line 103 of file writer.py.

_default_scope_type

_default_scope_type

protected

set default_scope_type

Definition at line 95 of file writer.py.

_dumping

_dumping

protected

set dumping

Definition at line 105 of file writer.py.

_header_keywords

_header_keywords

protected

header keywords

Definition at line 86 of file writer.py.

_ident_values

_ident_values

protected

set ident_values

Definition at line 115 of file writer.py.

_next_var_id

_next_var_id

protected

set next_var_id

Definition at line 107 of file writer.py.

_ofile

_ofile

protected

output file

Definition at line 84 of file writer.py.

_registering

_registering

protected

set registering

Definition at line 101 of file writer.py.

_scope_sep

_scope_sep

protected

set scope_sep

Definition at line 97 of file writer.py.

_scope_types

_scope_types

protected

set scopr_types

Definition at line 113 of file writer.py.

_scope_var_names

_scope_var_names

protected

set scope_var_names

Definition at line 111 of file writer.py.

_scope_var_strs

_scope_var_strs

protected

set scope_var_strs

Definition at line 109 of file writer.py.

_timestamp

_timestamp

protected

set time_stamp

Definition at line 117 of file writer.py.

SCOPE_TYPES

list SCOPE_TYPES = ['begin', 'fork', 'function', 'module', 'task']

static

Valid VCD scope types.

Definition at line 66 of file writer.py.

TIMESCALE_NUMS

list TIMESCALE_NUMS = [1, 10, 100]

static

Valid timescale numbers.

Definition at line 74 of file writer.py.

TIMESCALE_UNITS

list TIMESCALE_UNITS = ['s', 'ms', 'us', 'ns', 'ps', 'fs']

static

Valid timescale units.

Definition at line 77 of file writer.py.

VAR_TYPES

list VAR_TYPES

static

Initial value:

=  ['event', 'integer', 'parameter', 'real', 'realtime', 'reg',
                 'supply0', 'supply1', 'time', 'tri', 'triand', 'trior',
                 'trireg', 'tri0', 'tri1', 'wand', 'wire', 'wor']

Valid VCD variable types.

Definition at line 69 of file writer.py.

---

The documentation for this class was generated from the following file:

• trg/scripts/writer.py