wavekit 0.5.0__tar.gz → 0.5.2__tar.gz

{wavekit-0.5.0 → wavekit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavekit
-Version: 0.5.0
+Version: 0.5.2
 Summary: a fundamental package for digital circuit waveform analysis
 License-File: LICENSE
 Author: cxzzzz

{wavekit-0.5.0 → wavekit-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.5.0"
+version = "0.5.2"
 description = "a fundamental package for digital circuit waveform analysis"
 authors = ["cxzzzz <cxz19961010@outlook.com>"]
 readme = "README.md"

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/__init__.py

@@ -20,6 +20,7 @@ from .pattern import PatternError as PatternError
 from .readers.vcd.reader import VcdReader as VcdReader
 from .scope import Scope as Scope
 from .signal import Signal as Signal
+from .signal import SignalCompositeType as SignalCompositeType
 from .waveform import Waveform as Waveform
 
 __all__ = [
@@ -28,6 +29,7 @@ __all__ = [
     'FsdbReader',
     'Scope',
     'Signal',
+    'SignalCompositeType',
     'Pattern',
     'MatchResult',
     'MatchStatus',

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/readers/base.py

@@ -38,7 +38,7 @@ class Reader:
     If the bit-range suffix is omitted and the file stores the signal with a
     range, the range is appended automatically.
 
-    Pattern syntax (used by :meth:`get_matched_signals`,
+    Pattern syntax (used by :meth:`get_matched_signals`, :meth:`get_matched_scopes`,
     :meth:`load_matched_waveforms`, :meth:`eval`)
     -------------------------------------------------
     * ``{a,b,c}``     — matches ``a``, ``b``, or ``c``; captures each as a key.
@@ -233,7 +233,7 @@ class Reader:
             )
         return matched_signals
 
-    def get_matched_scope(
+    def get_matched_scopes(
         self,
         pattern: str,
         root_scope: Scope | None = None,
@@ -270,7 +270,7 @@ class Reader:
         ::
 
             # Find all fifo_N sub-scopes under tb.dut
-            scopes = reader.get_matched_scope("tb.dut.fifo_{0..3}")
+            scopes = reader.get_matched_scopes("tb.dut.fifo_{0..3}")
             for (idx,), scope in scopes.items():
                 waves = reader.load_matched_waveforms(
                     "w_ptr[2:0]", clock_pattern="clk", root_scope=scope

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/readers/fsdb/npi_fsdb_reader.pyx

@@ -3,155 +3,170 @@ import math
 import sys
 import numpy as np
 cimport numpy as np
-#from cpython import PyBytes_FromString
 import cython
 from libcpp.vector cimport vector
 from libc.stdlib cimport malloc, free
 from libc.string cimport strcpy, strlen
 from .npi_fsdb cimport *
 
+NPI_FSDB_CT_ARRAY        = <int>npiFsdbSigCtArray
+NPI_FSDB_CT_STRUCT       = <int>npiFsdbSigCtStruct
+NPI_FSDB_CT_UNION        = <int>npiFsdbSigCtUnion
+NPI_FSDB_CT_TAGGED_UNION = <int>npiFsdbSigCtTaggedUnion
+NPI_FSDB_CT_RECORD       = <int>npiFsdbSigCtRecord
 
-cdef class NpiFsdbScope:
-    pass
 
+cdef class NpiFsdbSignal:
+    """Wraps a npiFsdbSigHandle — a single signal (leaf or composite) in the FSDB hierarchy."""
+    cdef npiFsdbSigHandle sig_handle
+
+    @staticmethod
+    cdef init(npiFsdbSigHandle sig_handle):
+        sig = NpiFsdbSignal()
+        sig.sig_handle = sig_handle
+        return sig
+
+    def __init__(self):
+        self.sig_handle = NULL
+
+    def name(self) -> str:
+        assert self.sig_handle != NULL
+        name = npi_fsdb_sig_property_str(npiFsdbSigName, self.sig_handle).decode('ascii')
+        # NPI returns fully-qualified names like "tb.dut.field"; take only the last component.
+        # Array elements are named "a[0]", "a[0][1]" etc. — splitting by "." is safe since
+        # brackets cannot contain ".".
+        name = name.split(".")
+        name = name[len(name)-1]
+        return name
+
+    def has_member(self) -> bool:
+        assert self.sig_handle != NULL
+        cdef int has_member
+        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member):
+            return has_member != 0
+        return False
+
+    def composite_type(self):
+        """Return the npiFsdbSigCompositeType_e int value, or None if not composite."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int ct
+        if not (npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member):
+            return None
+        if npi_fsdb_sig_property(npiFsdbSigCompositeType, self.sig_handle, &ct):
+            return ct
+        return None
+
+    def width(self) -> int:
+        """Return the total bit-width of this signal (sum of all leaf members for composites)."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int w
+        cdef npiFsdbSigIter sub_signal_iter
+        cdef npiFsdbSigHandle sub_signal
+        assert npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member)
+        if has_member == 0:
+            assert npi_fsdb_sig_property(npiFsdbSigRangeSize, self.sig_handle, &w)
+            return w
+        else:
+            sub_signal_iter = npi_fsdb_iter_member(self.sig_handle)
+            assert sub_signal_iter != NULL
+            w = 0
+            while (sub_signal := npi_fsdb_iter_sig_next(sub_signal_iter)):
+                w += NpiFsdbSignal.init(sub_signal).width()
+            return w
+
+    def range(self):
+        """Return the (high, low) bit-range tuple, or None for non-array composites."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef int ct
+        cdef int left_range, right_range
+        assert npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member)
+        assert npi_fsdb_sig_property(npiFsdbSigLeftRange, self.sig_handle, &left_range)
+        assert npi_fsdb_sig_property(npiFsdbSigRightRange, self.sig_handle, &right_range)
+        if has_member != 0:
+            assert npi_fsdb_sig_property(npiFsdbSigCompositeType, self.sig_handle, &ct)
+            if ct == <int>npiFsdbSigCtArray:
+                return (left_range, right_range)
+            return None
+        return None
+
+    def member_list(self) -> list:
+        """Return direct member NpiFsdbSignal objects for composite signals."""
+        assert self.sig_handle != NULL
+        cdef int has_member
+        cdef npiFsdbSigIter member_iter
+        cdef npiFsdbSigHandle member_handle
 
-cdef class NpiFsdbNormalScope(NpiFsdbScope):
+        res = []
+        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
+            member_iter = npi_fsdb_iter_member(self.sig_handle)
+            while True:
+                member_handle = npi_fsdb_iter_sig_next(member_iter)
+                if member_handle == NULL:
+                    break
+                res.append(NpiFsdbSignal.init(member_handle))
+            npi_fsdb_iter_sig_stop(member_iter)
+        return res
+
+
+cdef class NpiFsdbScope:
+    """Wraps a npiFsdbScopeHandle — a scope node (module/block) in the FSDB hierarchy."""
     cdef npiFsdbScopeHandle scope_handle
 
     @staticmethod
     cdef init(npiFsdbScopeHandle scope_handle):
-        scope = NpiFsdbNormalScope()
+        scope = NpiFsdbScope()
         scope.scope_handle = scope_handle
         return scope
 
     def __init__(self):
         self.scope_handle = NULL
 
-    def child_scope_list(self, include_signal_scope:bool = True) -> list[NpiFsdbScope]:
+    def child_scope_list(self) -> list:
+        """Return direct child NpiFsdbScope nodes (not signals)."""
         assert self.scope_handle != NULL
         res = []
         child_scope_handle_iter = npi_fsdb_iter_child_scope(self.scope_handle)
-        
+
         cdef npiFsdbScopeHandle child_scope_handle
         while True:
             child_scope_handle = npi_fsdb_iter_scope_next(child_scope_handle_iter)
             if child_scope_handle == NULL:
                 break
-            res.append(NpiFsdbNormalScope.init(child_scope_handle))
+            res.append(NpiFsdbScope.init(child_scope_handle))
         npi_fsdb_iter_scope_stop(child_scope_handle_iter)
-
-
-        cdef npiFsdbSigHandle child_sig_handle
-        if include_signal_scope:
-            child_sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
-            while True:
-                child_sig_handle = npi_fsdb_iter_sig_next(child_sig_handle_iter)
-                if child_sig_handle == NULL:
-                    break
-                res.append(NpiFsdbSignalScope.init(child_sig_handle))
-            npi_fsdb_iter_sig_stop(child_sig_handle_iter)
         return res
 
-    def signal_list(self) -> list[str]:
+    def signal_list(self) -> list:
+        """Return direct child NpiFsdbSignal objects declared in this scope."""
         assert self.scope_handle != NULL
-
         res = []
-        sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
-        cdef npiFsdbSigHandle sig_handle
-        cdef const char* c_str
+        child_sig_handle_iter = npi_fsdb_iter_sig(self.scope_handle)
+
+        cdef npiFsdbSigHandle child_sig_handle
         while True:
-            sig_handle = npi_fsdb_iter_sig_next(sig_handle_iter)
-            if sig_handle == NULL:
+            child_sig_handle = npi_fsdb_iter_sig_next(child_sig_handle_iter)
+            if child_sig_handle == NULL:
                 break
-            c_str = npi_fsdb_sig_property_str(npiFsdbSigName, sig_handle)
-            name = c_str.decode('ascii')
-            res.append(name)
-        npi_fsdb_iter_sig_stop(sig_handle_iter)
-
+            res.append(NpiFsdbSignal.init(child_sig_handle))
+        npi_fsdb_iter_sig_stop(child_sig_handle_iter)
         return res
 
     def name(self) -> str:
         assert self.scope_handle != NULL
-        name = npi_fsdb_scope_property_str(npiFsdbScopeName, self.scope_handle).decode('ascii')
-        return name
+        return npi_fsdb_scope_property_str(npiFsdbScopeName, self.scope_handle).decode('ascii')
 
     def type(self) -> str:
         assert self.scope_handle != NULL
-        type_str = npi_fsdb_scope_property_str(npiFsdbScopeType, self.scope_handle).decode('ascii')
-        return type_str
+        return npi_fsdb_scope_property_str(npiFsdbScopeType, self.scope_handle).decode('ascii')
 
     def def_name(self) -> str:
         assert self.scope_handle != NULL
-        def_name = npi_fsdb_scope_property_str(npiFsdbScopeDefName, self.scope_handle).decode('ascii')
-        return def_name
-
-cdef class NpiFsdbSignalScope(NpiFsdbScope):
-    cdef npiFsdbSigHandle sig_handle
-
-    @staticmethod
-    cdef init(npiFsdbSigHandle sig_handle):
-        scope = NpiFsdbSignalScope()
-        scope.sig_handle = sig_handle
-        return scope
-
-    def __init__(self):
-        self.sig_handle = NULL
-
-    def child_scope_list(self, include_signal_scope:bool = True) -> list[NpiFsdbScope]:
-        assert self.sig_handle != NULL
-
-        cdef int has_member
-        cdef npiFsdbSigIter member_iter
-        cdef npiFsdbSigHandle member_handle
-
-        res = []
-        if include_signal_scope:
-            if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
-                member_iter = npi_fsdb_iter_member(self.sig_handle)
-                while True:
-                    member_handle = npi_fsdb_iter_sig_next(member_iter)
-                    if member_handle == NULL:
-                        break
-                    res.append(NpiFsdbSignalScope.init(member_handle))
-                npi_fsdb_iter_sig_stop(member_iter)
-        return res
-
-    def signal_list(self) -> list[str]:
-        assert self.sig_handle != NULL
-
-        cdef const char* c_str
-        cdef npiFsdbSigIter member_iter
-        cdef npiFsdbSigHandle member_handle
-        cdef int has_member
-        res = []
-
-        if npi_fsdb_sig_property(npiFsdbSigHasMember, self.sig_handle, &has_member) and has_member:
-            member_iter = npi_fsdb_iter_member(self.sig_handle)
-            while True:
-                member_handle = npi_fsdb_iter_sig_next(member_iter)
-                if member_handle == NULL:
-                    break
-                c_str = npi_fsdb_sig_property_str(npiFsdbSigName, member_handle)
-                name = c_str.decode('ascii')
-                name = name.split(".")
-                name = name[len(name)-1]
-                res.append(name)
-            npi_fsdb_iter_sig_stop(member_iter)
-        return res
+        return npi_fsdb_scope_property_str(npiFsdbScopeDefName, self.scope_handle).decode('ascii')
 
-    def name(self) -> str:
-        assert self.sig_handle != NULL
-        name = npi_fsdb_sig_property_str(npiFsdbSigName, self.sig_handle).decode('ascii')
-        #TODO: this only works for non-array type (array's name is like data[0],can't be split by ".")
-        name = name.split(".")
-        name = name[len(name)-1]
-        return name
-
-    def type(self) -> str:
-        raise NotImplementedError("type property of signal scope is not supported")
 
-    def def_name(self) -> str:
-        raise NotImplementedError("def_name property of signal scope is not supported")
 @cython.boundscheck(False)  # 关闭边界检查以提升性能
 @cython.wraparound(False)   # 关闭负索引检查以提升性能
 cdef inline cstr_to_ull(char* str, unsigned int xz_value, int max_bit_num = 2147483647):
@@ -186,88 +201,6 @@ cdef inline cstr_to_bit(char* str, unsigned int xz_value):
         value = xz_value
     return value
 
-cdef inline fsdb_read_value_change(vct_handle: npiFsdbVctHandle, begin_time, end_time, width:int, xz_value:int):
-
-    cdef npiFsdbTime cur_time
-    cdef npiFsdbValue cur_value
-    cdef int stat
-
-    cdef vector[unsigned long long] time_array
-
-    cdef int value_array_num = math.ceil(width/64)
-    assert width <= 64*64
-    cdef vector[unsigned long long] value_array[64]
-
-    cdef int first = 1
-    cdef int i,j
-    cdef unsigned long long cur_int_value
-    while True:
-        if first:
-            if begin_time is None:
-                stat = npi_fsdb_goto_first(vct_handle)
-            else:
-                stat = npi_fsdb_goto_time(vct_handle,  <npiFsdbTime> begin_time)
-        else:
-            stat = npi_fsdb_goto_next(vct_handle)
-        if stat == 0:
-            break
-
-        cur_value.format = npiFsdbBinStrVal
-        npi_fsdb_vct_time(vct_handle, &cur_time)
-        npi_fsdb_vct_value(vct_handle, &cur_value)
-        if cur_time > end_time:
-            break
-
-        time_array.push_back(cur_time)
-        if width == 1: # opt for clk
-            value_array[0].push_back(cstr_to_bit(<char*>cur_value.value.str, xz_value))
-        else:
-            cur_lllint_value = 0
-            for i in range(value_array_num):
-                value_array[i].push_back(cstr_to_ull(<char*>cur_value.value.str + 64*i, xz_value, 64))
-
-    result = np.zeros((value_array[0].size(), 2), dtype=np.uint64 if width <= 64 else np.object_)  # 创建一个 (n, 2) 的二维数组，dtype 为 int32
-    for j in range(value_array[0].size()):
-        result[j][0] = time_array[j]
-        if width <= 64:
-            result[j][1] = value_array[0][j]
-        else:
-            for i in range(value_array_num):
-                result[j][1] = (result[j][1] << 64) + value_array[i][j]
-
-    return result
-
-cdef get_signal_handle_width(npiFsdbSigHandle signal_handle):
-    cdef int has_member
-    cdef int width
-    cdef npiFsdbSigIter sub_signal_iter
-    cdef npiFsdbSigHandle sub_signal
-    assert(npi_fsdb_sig_property(npiFsdbSigHasMember, signal_handle, &has_member))
-    if(has_member == 0):
-        assert(npi_fsdb_sig_property(npiFsdbSigRangeSize, signal_handle, &width))
-        return width
-    else:
-        sub_signal_iter = npi_fsdb_iter_member(signal_handle)
-        assert(sub_signal_iter != NULL)
-        width = 0
-        while(sub_signal := npi_fsdb_iter_sig_next(sub_signal_iter)):
-            width += get_signal_handle_width(sub_signal)
-        return width
-
-cdef get_signal_handle_range(npiFsdbSigHandle signal_handle):
-    cdef int has_member
-    cdef int type
-    cdef int left_range, right_range
-    assert(npi_fsdb_sig_property(npiFsdbSigHasMember, signal_handle, &has_member))
-    assert(npi_fsdb_sig_property(npiFsdbSigLeftRange, signal_handle, &left_range))
-    assert(npi_fsdb_sig_property(npiFsdbSigRightRange, signal_handle, &right_range))
-    return (left_range, right_range)
-
-    if(has_member != 0):
-        assert(npi_fsdb_sig_property(npiFsdbSigCompositeType, signal_handle, &type))
-        if(type == <int>npiFsdbSigCtArray):
-            return (left_range, right_range)
-    return None
 
 cdef class NpiFsdbReader:
     cdef npiFsdbFileHandle fsdb_handle
@@ -275,69 +208,36 @@ cdef class NpiFsdbReader:
 
     def __init__(self, str file):
         import os
-        
+
         # 检查VERDI_HOME环境变量
         verdi_home = os.environ.get('VERDI_HOME')
         if verdi_home:
             npi_lib_path = os.path.join(verdi_home, 'share/NPI/lib/LINUX64/libNPI.so')
-        
-        #cdef int argc = len(sys.argv)
-        #cdef char** argv = <char**>malloc((argc + 1) * sizeof(char*))
-
-        #for i in range(argc):
-        #    argv[i] = <char*>malloc(strlen(sys.argv[i].encode('ascii')))
-        #    strcpy(argv[i], sys.argv[i].encode('ascii'))
-        #argv[argc] = NULL  # Null-terminate the array
 
-        #npi_init(argc, argv)
-        #self.file = file
-        #free(argv)
-
-        #cdef npiFsdbFileHandle fsdb_handle
         file_str = file.encode('utf-8')
         cdef char* file_s = file_str
         self.fsdb_handle = npi_fsdb_open(file_s)
         if(self.fsdb_handle == NULL):
             raise OSError(f"Failed to open fsdb file :{file_str}")
 
-
-
-    def get_signal_width(
-        self,
-        str signal
-    ) -> int:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
+    def get_signal(self, str signal) -> NpiFsdbSignal:
+        """Look up a signal by its full hierarchical path and return an NpiFsdbSignal handle."""
+        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle, signal.encode('ascii'), NULL)
         assert signal_handle != NULL, f"can't find signal: {signal}"
-        
-        cdef int width = get_signal_handle_width(signal_handle)
-        return width
-
-    def get_signal_range(
-        self,
-        str signal
-    ) -> tuple[int,int]:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
-        assert signal_handle != NULL, f"can't find signal: {signal}"
-
-        return get_signal_handle_range(signal_handle)
+        return NpiFsdbSignal.init(signal_handle)
 
     @cython.boundscheck(False)  # 关闭边界检查以提升性能
     @cython.wraparound(False)   # 关闭负索引检查以提升性能
     def load_value_change(
         self,
-        str signal,
+        NpiFsdbSignal signal,
         unsigned long long begin_time,
         unsigned long long end_time,
         int xz_value
     ) -> np.ndarray:
-        
-        cdef npiFsdbSigHandle signal_handle = npi_fsdb_sig_by_name(self.fsdb_handle,  signal.encode('ascii'), NULL)
-        assert signal_handle != NULL, f"can't find signal: {signal}"
-        cdef int width = get_signal_handle_width(signal_handle)
 
-        cdef npiFsdbVctHandle signal_vct_handle = npi_fsdb_create_vct(signal_handle)
+        cdef int width = signal.width()
+        cdef npiFsdbVctHandle signal_vct_handle = npi_fsdb_create_vct(signal.sig_handle)
         cdef npiFsdbTime cur_time
         cdef npiFsdbValue cur_value
         cdef int stat
@@ -358,7 +258,7 @@ cdef class NpiFsdbReader:
                     stat = npi_fsdb_goto_time(signal_vct_handle,  <npiFsdbTime> begin_time)
             else:
                 stat = npi_fsdb_goto_next(signal_vct_handle)
-            
+
             if stat == 0:
                 break
 
@@ -398,11 +298,7 @@ cdef class NpiFsdbReader:
                 result_object[:,1] = (result_object[:,1] << shift) + value_np_array
             return result_object
 
-        #npi_fsdb_release_vct(signal_vct_handle)
-        #npi_fsdb_unload_vc(self.fsdb_handle)
-        #return result
-
-    def top_scope_list(self) -> list[NpiFsdbScope]:
+    def top_scope_list(self) -> list:
         cdef npiFsdbScopeIter top_scope_iter
         cdef npiFsdbScopeHandle top_scope_handle
 
@@ -412,7 +308,7 @@ cdef class NpiFsdbReader:
             top_scope_handle = npi_fsdb_iter_scope_next(top_scope_iter)
             if top_scope_handle == NULL:
                 break
-            res.append(NpiFsdbNormalScope.init(top_scope_handle))
+            res.append(NpiFsdbScope.init(top_scope_handle))
         npi_fsdb_iter_scope_stop(top_scope_iter)
         return res
 

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/readers/fsdb/reader.py

@@ -3,65 +3,114 @@ from __future__ import annotations
 import importlib
 from collections import defaultdict
 from collections.abc import Sequence
+from dataclasses import dataclass, field
 from functools import cached_property
 from typing import Any
 
 import numpy as np
 
 from ...scope import Scope
-from ...signal import Signal
+from ...signal import Signal, SignalCompositeType
 from ...waveform import Waveform
 from ..base import Reader
-from .npi_fsdb_reader import NpiFsdbReader, NpiFsdbScope, NpiFsdbSignalScope
+from .npi_fsdb_reader import (
+    NPI_FSDB_CT_ARRAY,
+    NPI_FSDB_CT_RECORD,
+    NPI_FSDB_CT_STRUCT,
+    NPI_FSDB_CT_TAGGED_UNION,
+    NPI_FSDB_CT_UNION,
+    NpiFsdbReader,
+    NpiFsdbScope,
+    NpiFsdbSignal,
+)
+
+
+@dataclass
+class FsdbSignal(Signal):
+    """FSDB-backed :class:`~wavekit.signal.Signal` with lazy member loading.
+
+    Extends :class:`~wavekit.signal.Signal` by holding an NPI signal handle
+    directly, enabling on-demand loading of composite members without any
+    reader reference.  Construct via :meth:`from_handle`.
+    """
+
+    _npi_signal: NpiFsdbSignal | None = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def from_handle(cls, npi_sig: NpiFsdbSignal, full_name: str) -> FsdbSignal:
+        """Build an :class:`FsdbSignal` from an NPI signal handle and its full path."""
+        _npi_ct_to_enum = {
+            NPI_FSDB_CT_ARRAY: SignalCompositeType.ARRAY,
+            NPI_FSDB_CT_STRUCT: SignalCompositeType.STRUCT,
+            NPI_FSDB_CT_UNION: SignalCompositeType.UNION,
+            NPI_FSDB_CT_TAGGED_UNION: SignalCompositeType.TAGGED_UNION,
+            NPI_FSDB_CT_RECORD: SignalCompositeType.RECORD,
+        }
+        ct_raw = npi_sig.composite_type()
+        if ct_raw is None:
+            composite_type = None
+        elif ct_raw in _npi_ct_to_enum:
+            composite_type = _npi_ct_to_enum[ct_raw]
+        else:
+            raise ValueError(f"Unknown NPI composite type value: {ct_raw} for signal '{full_name}'")
+        return cls(
+            name=npi_sig.name(),
+            full_name=full_name,
+            width=npi_sig.width(),
+            range=npi_sig.range(),
+            composite_type=composite_type,
+            _npi_signal=npi_sig,
+        )
+
+    @cached_property
+    def member_list(self) -> list[Signal] | None:
+        if self.composite_type is None:
+            return None
+        assert self._npi_signal is not None
+        npi_members = self._npi_signal.member_list()
+        if self.composite_type == SignalCompositeType.ARRAY:
+            # Array members' NPI names already include the array base name at every
+            # level, e.g. parent "a" has members "a[0]", "a[1]", and "a[0]" further
+            # has members "a[0][0]", "a[0][1]", etc.  The member name is therefore an
+            # extension of the parent name with no extra "." separator, so we must NOT
+            # prepend full_name (which would produce "tb.dut.a.a[0]").  Instead we use
+            # the parent scope path (full_name minus the signal's own local name) as
+            # the base, giving "tb.dut.a[0]", "tb.dut.a[0][1]", etc.
+            scope_path = self.full_name[: -(len(self.name) + 1)]
+            return [FsdbSignal.from_handle(m, f'{scope_path}.{m.name()}') for m in npi_members]
+        else:
+            return [FsdbSignal.from_handle(m, f'{self.full_name}.{m.name()}') for m in npi_members]
 
 
 class FsdbScope(Scope):
     def __init__(self, handle: NpiFsdbScope, parent_scope: FsdbScope | None, reader: FsdbReader):
         super().__init__(name=handle.name())
-        self.handle = handle
+        self._npi_scope = handle
         self.parent_scope = parent_scope
         self.reader = reader
 
     @cached_property
     def signal_list(self) -> Sequence[Signal]:
         full_scope_name = self.full_name()
-        signals = []
-        for s in self.handle.signal_list():
-            signal_path = f'{full_scope_name}.{s}'
-            width = self.reader._get_signal_width(signal_path)
-            rng = self.reader._get_signal_range(signal_path)
-            signals.append(
-                Signal(
-                    name=s,
-                    full_name=signal_path,
-                    width=width,
-                    range=rng,
-                    signed=False,
-                )
-            )
-        return signals
+        return [
+            FsdbSignal.from_handle(npi_sig, f'{full_scope_name}.{npi_sig.name()}')
+            for npi_sig in self._npi_scope.signal_list()
+        ]
 
     @cached_property
     def child_scope_list(self) -> Sequence[Scope]:
-        return [FsdbScope(c, self, self.reader) for c in self.handle.child_scope_list()]
-
-    @cached_property
-    def child_normal_scope_list(self) -> Sequence[Scope]:
-        return [
-            FsdbScope(c, self, self.reader)
-            for c in self.handle.child_scope_list(include_signal_scope=False)
-        ]
+        return [FsdbScope(c, self, self.reader) for c in self._npi_scope.child_scope_list()]
 
     @property
     def type(self) -> str:
         if not hasattr(self, '_type'):
-            self._type = self.handle.type()
+            self._type = self._npi_scope.type()
         return self._type
 
     @property
     def def_name(self) -> str | None:
         if not hasattr(self, '_def_name'):
-            self._def_name = self.handle.def_name()
+            self._def_name = self._npi_scope.def_name()
         return self._def_name
 
     def find_scope_by_module(self, module_name: str, depth: int = 0) -> list[Scope]:
@@ -70,11 +119,8 @@ class FsdbScope(Scope):
         return self._preloaded_module_scope[module_name]
 
     def preload_module_scope(self):
-        if isinstance(self.handle, NpiFsdbSignalScope):
-            return {}
-
         preloaded_module_scope = defaultdict(list)
-        for c in self.child_normal_scope_list:
+        for c in self.child_scope_list:
             for module_name, module_scope_list in c.preload_module_scope().items():
                 preloaded_module_scope[module_name].extend(module_scope_list)
 
@@ -123,9 +169,21 @@ class FsdbReader(Reader):
         signal_path = signal.full_name if isinstance(signal, Signal) else signal
         clock_path = clock.full_name if isinstance(clock, Signal) else clock
 
+        # Resolve NPI signal handles — reuse the handle if already available
+        npi_signal = (
+            signal._npi_signal
+            if isinstance(signal, FsdbSignal) and signal._npi_signal is not None
+            else self.file_handle.get_signal(signal_path)
+        )
+        npi_clock = (
+            clock._npi_signal
+            if isinstance(clock, FsdbSignal) and clock._npi_signal is not None
+            else self.file_handle.get_signal(clock_path)
+        )
+
         # Always load the full clock to compute absolute cycle numbers
         all_clock_changes = self.file_handle.load_value_change(
-            clock_path,
+            npi_clock,
             begin_time=0,
             end_time=2**64 - 1,
             xz_value=0,
@@ -156,7 +214,7 @@ class FsdbReader(Reader):
         # Load signal within the requested window only (FSDB NPI provides the
         # correct initial value at begin_time even if the last change was earlier)
         signal_value_change = self.file_handle.load_value_change(
-            signal_path,
+            npi_signal,
             begin_time=begin_time_actual,
             end_time=end_time_actual,
             xz_value=xz_value,
@@ -165,7 +223,7 @@ class FsdbReader(Reader):
         full_wave = self.value_change_to_waveform(
             signal_value_change,
             windowed_clock_changes,
-            width=self.file_handle.get_signal_width(signal_path),
+            width=npi_signal.width(),
             signed=signed,
             sample_on_posedge=sample_on_posedge,
             signal=signal_path,
@@ -186,12 +244,6 @@ class FsdbReader(Reader):
             ]
         return self._top_scope_list
 
-    def _get_signal_width(self, signal: str) -> int:
-        return self.file_handle.get_signal_width(signal)
-
-    def _get_signal_range(self, signal: str) -> tuple[int, int]:
-        return self.file_handle.get_signal_range(signal)
-
     @property
     def begin_time(self) -> str:
         return self.file_handle.min_time()

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/readers/vcd/reader.py

@@ -75,9 +75,6 @@ class VcdReader(Reader):
     def end_time(self) -> int:
         return self.file_handle.endtime
 
-    def _get_signal_width(self, signal: str) -> int:
-        return int(self.file_handle[signal].size)
-
     def load_waveform(
         self,
         signal: Signal | str,

{wavekit-0.5.0 → wavekit-0.5.2}/src/wavekit/scope.py

@@ -11,7 +11,7 @@ from .readers.pattern_parser import (
     PatternMap,
     split_by_range_expr,
 )
-from .signal import Signal
+from .signal import Signal, SignalCompositeType
 
 T = TypeVar('T')
 
@@ -84,6 +84,12 @@ class Scope:
         raise NotImplementedError()
 
 
+def _prepend_scope_name(value: Any, scope_name: str) -> Any:
+    if isinstance(value, Signal):
+        return dataclasses.replace(value, full_name=f'{scope_name}.{value.full_name}')
+    return value
+
+
 def _traverse_scope_tree(
     scope: Scope,
     descendant_scope_pattern_list: list[PatternMap],
@@ -111,11 +117,6 @@ def _traverse_scope_tree(
     dict mapping expansion key tuples to values produced by *leaf_fn*.
     """
 
-    def prepend_scope_name(value: Any, scope_name: str) -> Any:
-        if isinstance(value, Signal):
-            return dataclasses.replace(value, full_name=f'{scope_name}.{value.full_name}')
-        return value
-
     res: dict[tuple[Any, ...], T] = {}
     if len(descendant_scope_pattern_list) == 0:
         return res
@@ -144,11 +145,11 @@ def _traverse_scope_tree(
                 for lk, lv in leaf_fn(scope, remaining).items():
                     key = (scope.name,) + lk
                     assert key not in res
-                    res[key] = prepend_scope_name(lv, scope.name)
+                    res[key] = _prepend_scope_name(lv, scope.name)
 
                 for child_scope in scope.child_scope_list:
                     for ck, cv in _traverse_scope_tree(child_scope, remaining, leaf_fn).items():
-                        res[(scope.name,) + ck] = prepend_scope_name(cv, scope.name)
+                        res[(scope.name,) + ck] = _prepend_scope_name(cv, scope.name)
             else:
                 for child_scope in module_scopes:
                     for ck, cv in _traverse_scope_tree(
@@ -159,7 +160,7 @@ def _traverse_scope_tree(
                             raise ValueError('parent scope is None')
                         parent_name = parent_scope.full_name(scope)
                         key = (f'{parent_name}.{ck[0]}',) + ck[1:]
-                        res[key] = prepend_scope_name(cv, parent_name)
+                        res[key] = _prepend_scope_name(cv, parent_name)
         else:
             # Exact or regex match against current scope name
             matched = False
@@ -181,14 +182,14 @@ def _traverse_scope_tree(
                     key = new_k + lk
                     if key in res:
                         raise Exception(f'pattern {p} match more than one result')
-                    res[key] = prepend_scope_name(lv, scope.name)
+                    res[key] = _prepend_scope_name(lv, scope.name)
 
                 for child_scope in scope.child_scope_list:
                     for ck, cv in _traverse_scope_tree(child_scope, remaining, leaf_fn).items():
                         key = new_k + ck
                         if key in res:
                             raise Exception(f'pattern {p} match more than one result')
-                        res[key] = prepend_scope_name(cv, scope.name)
+                        res[key] = _prepend_scope_name(cv, scope.name)
     return res
 
 
@@ -204,55 +205,94 @@ def match_signals(
     objects whose ``full_name`` is the complete hierarchical path.
     """
 
-    def match_signals_in_scope(
-        scope: Scope, signal_pattern_list: list[PatternMap]
+    def _match_signals_in_list(
+        signals: Sequence[Signal], pattern_list: list[PatternMap]
     ) -> dict[tuple[Any, ...], Signal]:
-        def range_str_to_tuple(range_str: str) -> tuple[int, int] | None:
-            if not range_str:
-                return None
-            last = re.search(r'\[(\d+)(?::(\d+))?\]$', range_str)
-            if last is None:
-                return None
-            high = int(last.group(1))
-            low = int(last.group(2)) if last.group(2) is not None else high
-            return (high, low)
+        """Match *pattern_list* against *signals*, recursing into composite members.
+
+        The first element of *pattern_list* is matched against signal names in
+        *signals*.  When more patterns remain and the matched signal is composite
+        (``signal.member_list is not None``), the function recurses into those
+        members with the remaining patterns, allowing patterns to address
+        struct/union members across multiple levels.
+
+        **Array signals** require special treatment because NPI reports each
+        element's name as an extension of the parent name with no ``"."``
+        separator.  For example, signal ``a`` (ARRAY) has members ``a[0]``,
+        ``a[1]``, which in turn have members ``a[0][0]``, ``a[0][1]``, etc.
+        A user pattern like ``a[10][0]`` therefore cannot be resolved by a
+        single exact-name match at the top level.  Instead, for ARRAY signals
+        we check whether the signal name is a string prefix of the pattern:
+        if yes, we recurse into members with the **same** pattern (not
+        advancing to the next element), letting each member self-select by the
+        same prefix rule until an exact match is found.
+        """
+        if not pattern_list:
+            return {}
+
+        def resolve_leaf(sig: Signal, sig_bare: str, range_suffix: str) -> Signal:
+            if range_suffix:
+                # Extract (high, low) from the innermost bracket of range_suffix,
+                # e.g. "[7:0]" → (7, 0), "[3]" → (3, 3).
+                m = re.search(r'\[(\d+)(?::(\d+))?\]$', range_suffix)
+                assert m is not None
+                h = int(m.group(1))
+                low = int(m.group(2)) if m.group(2) is not None else h
+                new_range: tuple[int, int] | None = (h, low)
+            else:
+                new_range = sig.range
+            return dataclasses.replace(
+                sig,
+                full_name=f'{sig_bare}{range_suffix}' if range_suffix else sig.name,
+                range=new_range,
+            )
 
         res: dict[tuple[Any, ...], Signal] = {}
-        if len(signal_pattern_list) != 1:
-            return res
-        for signal in scope.signal_list:
-            sig_bare, _ = split_by_range_expr(signal.name)
-            for k, p in signal_pattern_list[0].items():
+        for sig in signals:
+            sig_bare, _ = split_by_range_expr(sig.name)
+            for k, p in pattern_list[0].items():
                 if p[0] == '@':
                     name_regex, range_suffix = split_by_range_expr(p[1:])
-                    if match := re.fullmatch(name_regex, signal.name):
+                    if match := re.fullmatch(name_regex, sig.name):
                         assert len(k) == 0
                         key = (match.groups(),)
-                        if key in res:
-                            raise Exception(f'pattern {name_regex} match more than one signal')
-                        if range_suffix:
-                            new_local = f'{sig_bare}{range_suffix}'
-                            new_range = range_str_to_tuple(range_suffix)
-                        else:
-                            new_local = signal.name
-                            new_range = signal.range
-                        res[key] = dataclasses.replace(signal, full_name=new_local, range=new_range)
+                        if len(pattern_list) == 1:
+                            assert (
+                                key not in res
+                            ), f'pattern {name_regex} matches more than one signal'
+                            res[key] = resolve_leaf(sig, sig_bare, range_suffix)
+                        elif sig.member_list is not None:
+                            for ck, cv in _match_signals_in_list(
+                                sig.member_list, pattern_list[1:]
+                            ).items():
+                                res[key + ck] = _prepend_scope_name(cv, sig.name)
                 else:
                     p_bare, range_suffix = split_by_range_expr(p)
                     if p_bare != sig_bare:
                         continue
                     key = k
-                    assert key not in res
-                    if range_suffix:
-                        new_local = f'{sig_bare}{range_suffix}'
-                        new_range = range_str_to_tuple(range_suffix)
-                    else:
-                        new_local = signal.name
-                        new_range = signal.range
-                    res[key] = dataclasses.replace(signal, full_name=new_local, range=new_range)
+                    if sig.composite_type == SignalCompositeType.ARRAY and range_suffix:
+                        if sig.member_list is not None:
+                            for ck, cv in _match_signals_in_list(
+                                sig.member_list, pattern_list
+                            ).items():
+                                res[key + ck] = cv
+                    elif len(pattern_list) == 1:
+                        assert key not in res
+                        res[key] = resolve_leaf(sig, sig_bare, range_suffix)
+                    elif sig.member_list is not None:
+                        for ck, cv in _match_signals_in_list(
+                            sig.member_list, pattern_list[1:]
+                        ).items():
+                            res[key + ck] = _prepend_scope_name(cv, sig.name)
                     break
         return res
 
+    def match_signals_in_scope(
+        scope: Scope, signal_pattern_list: list[PatternMap]
+    ) -> dict[tuple[Any, ...], Signal]:
+        return _match_signals_in_list(scope.signal_list, signal_pattern_list)
+
     return _traverse_scope_tree(scope, descendant_scope_pattern_list, match_signals_in_scope)
 
 

wavekit-0.5.2/src/wavekit/signal.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from functools import cached_property
+
+
+class SignalCompositeType(Enum):
+    """Composite (non-leaf) signal type as reported by the waveform backend.
+
+    Not all backends support composite signals.  When a backend does not
+    distinguish composite types the field is ``None``.
+    """
+
+    ARRAY = 'array'
+    STRUCT = 'struct'
+    UNION = 'union'
+    TAGGED_UNION = 'tagged_union'
+    RECORD = 'record'
+
+
+@dataclass
+class Signal:
+    """Metadata descriptor for a single hardware signal.
+
+    Stores the signal's local name, full hierarchical path, bit-width,
+    declared bit-range, and signedness.  For composite signals (structs,
+    unions, arrays) the ``composite_type`` and ``member_list`` fields carry
+    the internal structure.
+
+    Attributes
+    ----------
+    name:
+        Local signal identifier as it appears within its parent scope,
+        matching the form used in the waveform file.  May include a range
+        suffix when the file stores the signal with one, e.g. ``"data[7:0]"``
+        or ``"mem[3][7:0]"``.  Scalar signals have no suffix, e.g. ``"clk"``.
+        Invariant: ``full_name == parent_scope_path + "." + name``.
+    full_name:
+        Complete hierarchical signal path, e.g. ``"tb.dut.data[7:0]"`` or
+        ``"tb.dut.mem[3][7:0]"``.  Equal to ``parent_scope_path + "." + name``.
+        Pass this directly to :meth:`~wavekit.readers.base.Reader.load_waveform`.
+    width:
+        Bit-width of the signal, e.g. ``8`` for ``[7:0]``.  ``None`` if not
+        yet resolved.
+    range:
+        The innermost (last) bit-range of the signal as a ``(high, low)``
+        integer tuple.  For a plain vector ``data[7:0]`` this is ``(7, 0)``;
+        for a multi-dimensional signal ``mem[3][7:0]`` this is ``(7, 0)``
+        (the ``[3]`` dimension index is encoded in ``name``/``full_name`` only).
+        For a single-bit index ``[n]`` this is ``(n, n)``.
+        ``None`` if the signal is scalar, composite, or the format does not
+        expose range information.
+    signed:
+        Whether the signal value should be interpreted as a two's-complement
+        signed integer.  Defaults to ``False``.
+    composite_type:
+        ``None`` for leaf (non-composite) signals.  For composite signals
+        (struct, union, array, …) this holds the :class:`SignalCompositeType`
+        value describing the kind of composite.  Not all backends populate
+        this field; backends that do not support composite introspection leave
+        it as ``None`` (e.g. VCD).
+    member_list:
+        ``None`` for leaf signals.  For composite signals this is the list of
+        direct member :class:`Signal` objects, populated in the same order the
+        backend reports them.  Always ``None`` when ``composite_type`` is
+        ``None``, and always a list (possibly empty) when ``composite_type``
+        is set.  Lazily evaluated on first access; backend-specific subclasses
+        override the ``member_list`` cached property to provide the actual loading logic.
+    """
+
+    name: str
+    full_name: str
+    width: int | None
+    range: tuple[int, int] | None
+    signed: bool = False
+    composite_type: SignalCompositeType | None = None
+
+    @cached_property
+    def member_list(self) -> list[Signal] | None:
+        return None
+
+    def __str__(self) -> str:
+        return (
+            f"Signal(name='{self.name}', full_name='{self.full_name}', "
+            f'width={self.width}, signed={self.signed}, range={self.range})'
+        )

wavekit-0.5.0/src/wavekit/signal.py

@@ -1,49 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-
-@dataclass
-class Signal:
-    """Metadata descriptor for a single hardware signal.
-
-    Stores the signal's local name, full hierarchical path, bit-width,
-    declared bit-range, and signedness.
-
-    Attributes
-    ----------
-    name:
-        Local signal identifier as it appears within its parent scope,
-        matching the form used in the waveform file.  May include a range
-        suffix when the file stores the signal with one, e.g. ``"data[7:0]"``
-        or ``"mem[3][7:0]"``.  Scalar signals have no suffix, e.g. ``"clk"``.
-        Invariant: ``full_name == parent_scope_path + "." + name``.
-    full_name:
-        Complete hierarchical signal path, e.g. ``"tb.dut.data[7:0]"`` or
-        ``"tb.dut.mem[3][7:0]"``.  Equal to ``parent_scope_path + "." + name``.
-        Pass this directly to :meth:`~wavekit.readers.base.Reader.load_waveform`.
-    width:
-        Bit-width of the signal, e.g. ``8`` for ``[7:0]``.  ``None`` if not
-        yet resolved.
-    range:
-        The declared or user-requested bit-range of the signal as a
-        ``(high, low)`` integer tuple, e.g. ``(7, 0)`` for ``[7:0]``.
-        For single-bit selection ``[n]`` this is stored as ``(n, n)``.
-        ``None`` if the signal is scalar or the format does not expose
-        range information.
-    signed:
-        Whether the signal value should be interpreted as a two's-complement
-        signed integer.  Defaults to ``False``.
-    """
-
-    name: str
-    full_name: str
-    width: int | None
-    range: tuple[int, int] | None
-    signed: bool = False
-
-    def __str__(self) -> str:
-        return (
-            f"Signal(name='{self.name}', full_name='{self.full_name}', "
-            f'width={self.width}, signed={self.signed}, range={self.range})'
-        )