wavekit 0.8.0__cp313-cp313-pyemscripten_2025_0_wasm32.whl

wavekit/__init__.py

@@ -0,0 +1,73 @@
+"""Clock-synchronised analysis for VCD, FST, and FSDB waveforms."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version('wavekit')
+except metadata.PackageNotFoundError:
+    __version__ = 'unknown'
+
+from .readers.clock_domain import ClockDomain as ClockDomain
+from .readers.fst.reader import FstReader as FstReader
+from .readers.hierarchy import Node as Node
+from .readers.hierarchy import Scope as Scope
+from .readers.hierarchy import Signal as Signal
+from .readers.hierarchy import SignalCompositeType as SignalCompositeType
+from .readers.matcher import BraceCapture as BraceCapture
+from .readers.matcher import Capture as Capture
+from .readers.matcher import ExactCapture as ExactCapture
+from .readers.matcher import RegexCapture as RegexCapture
+from .readers.matcher import WildcardCapture as WildcardCapture
+from .readers.range import Range as Range
+from .readers.vcd.reader import VcdReader as VcdReader
+from .waveform import Waveform as Waveform
+
+__all__ = [
+    'Waveform',
+    'VcdReader',
+    'FsdbReader',
+    'FstReader',
+    'ClockDomain',
+    'Node',
+    'Scope',
+    'Range',
+    'Signal',
+    'SignalCompositeType',
+    'Capture',
+    'ExactCapture',
+    'BraceCapture',
+    'RegexCapture',
+    'WildcardCapture',
+    'has_fsdb_support',
+]
+
+try:
+    from .readers.fsdb.npi_fsdb_reader import fsdb_runtime_available as _fsdb_runtime_available
+    from .readers.fsdb.reader import FsdbReader as FsdbReader
+except Exception as _fsdb_import_error:
+    _fsdb_available = False
+
+    def has_fsdb_support() -> bool:
+        """Check whether the Verdi FSDB runtime is available."""
+        return False
+
+    class _FsdbReaderStub:
+        """Placeholder that raises an error when the Verdi FSDB runtime is unavailable."""
+
+        def __init__(self, *args, **kwargs):
+            raise RuntimeError(
+                'FsdbReader requires the Verdi FSDB runtime (libNPI.so).\n\n'
+                'Set WAVEKIT_NPI_LIB to the library path, set VERDI_HOME to the Verdi '
+                'installation directory, or ensure libNPI.so is in LD_LIBRARY_PATH.\n\n'
+                f'Import error: {_fsdb_import_error}'  # noqa: F821
+            )
+
+    FsdbReader = _FsdbReaderStub  # type: ignore[assignment]
+else:
+    _fsdb_available = True
+
+    def has_fsdb_support() -> bool:
+        """Check whether the Verdi FSDB runtime library is installed."""
+        return _fsdb_runtime_available()

wavekit/expression.py

@@ -0,0 +1,165 @@
+"""Parsing and evaluating WaveKit waveform expressions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from lark import Lark, Transformer
+
+_EXPRESSION_GRAMMAR = r"""
+?start: expr
+?expr: bit_or
+?bit_or: bit_xor | bit_or VBAR bit_xor
+?bit_xor: bit_and | bit_xor CIRCUMFLEX bit_and
+?bit_and: comparison | bit_and AMPERSAND comparison
+?comparison: shift
+           | comparison EQEQ shift
+           | comparison NEQ shift
+           | comparison LE shift
+           | comparison LT shift
+           | comparison GE shift
+           | comparison GT shift
+?shift: sum | shift LSHIFT sum | shift RSHIFT sum
+?sum: product | sum PLUS product | sum MINUS product
+?product: unary
+        | product STAR unary
+        | product SLASH unary
+        | product FLOOR unary
+        | product PERCENT unary
+        | product POWER unary
+?unary: TILDE unary | PLUS unary | MINUS unary | atom
+?atom: call | path | NUMBER | group
+group: LPAR expr RPAR
+call: NAME LPAR [expr (COMMA expr)*] RPAR
+path: segment (DOT segment)* SUBSCRIPT*
+segment: segment_text | WILDCARD
+segment_text: segment_piece+
+?segment_piece: NAME | MODULE | BRACE | REGEX
+
+MODULE: /\${1,2}/
+BRACE: /\{[^{}]*\}/
+WILDCARD.3: "**" | "*"
+REGEX: /\/(?:\\.|[^\/\\])*\//
+SUBSCRIPT: /\[\d+(?::\d+)?\]/
+NAME: /[A-Za-z_][A-Za-z0-9_]*/
+HEX_NUMBER.2: /0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*/
+BIN_NUMBER.2: /0[bB][01](?:_?[01])*/
+OCT_NUMBER.2: /0[oO][0-7](?:_?[0-7])*/
+DECIMAL_FLOAT_NUMBER.2: /(?:\d(?:_?\d)*)?\.(?:\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/
+EXP_NUMBER.2: /\d(?:_?\d)*[eE][+-]?\d(?:_?\d)*/
+DEC_NUMBER.1: /\d(?:_?\d)*/
+NUMBER: HEX_NUMBER | BIN_NUMBER | OCT_NUMBER | DECIMAL_FLOAT_NUMBER | EXP_NUMBER | DEC_NUMBER
+
+VBAR: "|"
+CIRCUMFLEX: "^"
+AMPERSAND: "&"
+EQEQ: "=="
+NEQ: "!="
+LE: "<="
+LT: "<"
+GE: ">="
+GT: ">"
+LSHIFT: "<<"
+RSHIFT: ">>"
+PLUS: "+"
+MINUS: "-"
+STAR: "*"
+SLASH: "/"
+FLOOR: "//"
+PERCENT: "%"
+POWER: "**"
+TILDE: "~"
+LPAR: "("
+RPAR: ")"
+COMMA: ","
+DOT: "."
+
+%import common.WS_INLINE
+%ignore WS_INLINE
+"""
+
+_EXPRESSION_PARSER = Lark(
+    _EXPRESSION_GRAMMAR,
+    parser='lalr',
+    lexer='contextual',
+)
+_EXPRESSION_FUNCTIONS: dict[str, Callable[..., Any]] = {}
+
+
+def expression_function(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Register a Waveform method as callable from an expression string."""
+    _EXPRESSION_FUNCTIONS[func.__name__] = func
+    return func
+
+
+class ExpressionTransformer(Transformer):
+    def __init__(self, *, function_names: set[str]):
+        super().__init__()
+        self.function_names = function_names
+        self.path_entries: list[tuple[str, str]] = []
+
+    @staticmethod
+    def join(items: list[Any]) -> str:
+        return ''.join(str(item) for item in items)
+
+    def call(self, items: list[Any]) -> str:
+        name = str(items[0])
+        if name not in self.function_names:
+            raise ValueError(f'unknown expression function {name!r}')
+        return self.join(items)
+
+    def path(self, items: list[Any]) -> str:
+        path = self.join(items)
+        placeholder = f'__wave_{len(self.path_entries)}__'
+        self.path_entries.append((placeholder, path))
+        return placeholder
+
+    def __default__(self, data: str, children: list[Any], meta: Any) -> Any:
+        return self.join(children)
+
+    def __default_token__(self, token: Any) -> str:
+        return str(token)
+
+
+def parse_expression(expr: str) -> tuple[str, list[tuple[str, str]]]:
+    """Parse an expression and replace each signal path with a placeholder.
+
+    Parameters
+    ----------
+    expr:
+        WaveKit expression containing physical signal paths.
+
+    Returns
+    -------
+    tuple[str, list[tuple[str, str]]]
+        The substituted expression and ordered ``(placeholder, path)`` entries.
+    """
+    tree = _EXPRESSION_PARSER.parse(expr)
+    transformer = ExpressionTransformer(
+        function_names=set(_EXPRESSION_FUNCTIONS),
+    )
+    result = transformer.transform(tree)
+    return str(result), transformer.path_entries
+
+
+def evaluate_expression(expr: str, namespace: dict[str, Any]) -> Any:
+    """Evaluate an already-parsed expression against preloaded Waveforms.
+
+    Parameters
+    ----------
+    expr:
+        The substituted expression returned by ``parse_expression``.
+        Physical paths must be resolved and replaced before calling this
+        function.
+    namespace:
+        Names available to the expression, normally Waveform objects.
+
+    Returns
+    -------
+    Any
+        The result produced by the Waveform expression.
+    """
+    evaluation_namespace = {**_EXPRESSION_FUNCTIONS, **namespace}
+    code = compile(expr, '<wavekit-expression>', 'eval')
+    return eval(code, {'__builtins__': {}}, evaluation_namespace)  # noqa: S307

wavekit/pattern/__init__.py

@@ -0,0 +1,23 @@
+"""Protocol pattern matching for waveform analysis."""
+
+from .dsl import Pattern as Pattern
+from .dsl import collect as collect
+from .dsl import match as match
+from .errors import PatternError as PatternError
+from .result import MatchPoint as MatchPoint
+from .result import MatchRecord as MatchRecord
+from .result import MatchRecords as MatchRecords
+from .result import MatchStatus as MatchStatus
+from .steps import Channel as Channel
+
+__all__ = [
+    'Pattern',
+    'match',
+    'collect',
+    'MatchPoint',
+    'MatchRecord',
+    'MatchRecords',
+    'MatchStatus',
+    'PatternError',
+    'Channel',
+]

wavekit/pattern/compiler.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from typing import Any
+
+from ..waveform import Waveform
+from .errors import PatternError
+from .runtime import PatternContext
+from .steps import (
+    BranchStep,
+    CaptureStep,
+    Channel,
+    ChannelValue,
+    Condition,
+    ConsumeStep,
+    DelayStep,
+    IntValue,
+    LoopStep,
+    MessageValue,
+    RepeatStep,
+    RequireStep,
+    SignalValue,
+    Step,
+    WaitStep,
+)
+
+
+def infer_declarative_axis(steps: list[Step]) -> Waveform | None:
+    """Infer a minimal first-static-waveform scan axis hint from steps."""
+    # Axis inference is intentionally minimal.  It only finds a static waveform
+    # so start/end_cycle can be translated to indices; full cycle-axis alignment
+    # validation remains lazy in PatternRuntime.note_waveform().
+    for step in steps:
+        if isinstance(step, (WaitStep, ConsumeStep)):
+            if isinstance(step.cond, Waveform):
+                return step.cond
+            if isinstance(step.require, Waveform):
+                return step.require
+        elif isinstance(step, DelayStep):
+            if isinstance(step.require, Waveform):
+                return step.require
+        elif isinstance(step, CaptureStep):
+            if isinstance(step.signal, Waveform):
+                return step.signal
+        elif isinstance(step, RequireStep):
+            if isinstance(step.cond, Waveform):
+                return step.cond
+        elif isinstance(step, LoopStep):
+            if isinstance(step.until, Waveform):
+                return step.until
+            if isinstance(step.when, Waveform):
+                return step.when
+            waveform = infer_declarative_axis(step.body_template)
+            if waveform is not None:
+                return waveform
+        elif isinstance(step, RepeatStep):
+            waveform = infer_declarative_axis(step.body_template)
+            if waveform is not None:
+                return waveform
+        elif isinstance(step, BranchStep):
+            if isinstance(step.cond, Waveform):
+                return step.cond
+            if step.true_body:
+                waveform = infer_declarative_axis(step.true_body)
+                if waveform is not None:
+                    return waveform
+            if step.false_body:
+                waveform = infer_declarative_axis(step.false_body)
+                if waveform is not None:
+                    return waveform
+    return None
+
+
+def compile_declarative_pattern(steps: list[Step]) -> Callable[[PatternContext], Any]:
+    """Compile declarative pattern steps into a program body."""
+
+    def eval_condition(cond: Condition, ctx: PatternContext) -> bool:
+        if isinstance(cond, Waveform):
+            return bool(ctx.value(cond))
+        if isinstance(cond, bool):
+            return cond
+        if callable(cond):
+            return bool(cond(ctx.index, ctx.captures))
+        raise PatternError(
+            f'condition must be a Waveform, bool, or callable, got {type(cond).__name__}'
+        )
+
+    def eval_signal(signal: SignalValue, ctx: PatternContext) -> Any:
+        if isinstance(signal, Waveform):
+            return ctx.value(signal)
+        if callable(signal):
+            return signal(ctx.index, ctx.captures)
+        raise PatternError(f'signal must be a Waveform or callable, got {type(signal).__name__}')
+
+    def eval_int(value: IntValue, ctx: PatternContext) -> int:
+        if callable(value):
+            value = value(ctx.index, ctx.captures)
+        if isinstance(value, int):
+            return value
+        raise PatternError(f'integer value must be an int or callable, got {type(value).__name__}')
+
+    def eval_message(message: MessageValue | None, ctx: PatternContext) -> str | None:
+        if message is None or isinstance(message, str):
+            return message
+        if callable(message):
+            return str(message(ctx.index, ctx.captures))
+        raise PatternError(f'message must be a str or callable, got {type(message).__name__}')
+
+    def adapt_message(message: MessageValue | None, ctx: PatternContext):
+        if message is None:
+            return None
+        return lambda message=message: eval_message(message, ctx)
+
+    def adapt_channel(
+        channel: ChannelValue, ctx: PatternContext
+    ) -> Channel | Hashable | Callable[[], Channel | Hashable]:
+        if callable(channel):
+            return lambda channel=channel: channel(ctx.index, ctx.captures)
+        return channel
+
+    def run_steps(ctx: PatternContext, step_list: list[Step]) -> None:
+        for step in step_list:
+            if isinstance(step, WaitStep):
+                ctx.wait(
+                    lambda step=step: eval_condition(step.cond, ctx),
+                    require=None
+                    if step.require is None
+                    else lambda step=step: eval_condition(step.require, ctx),
+                    require_message=adapt_message(step.require_message, ctx),
+                )
+            elif isinstance(step, ConsumeStep):
+                ctx.consume(
+                    lambda step=step: eval_condition(step.cond, ctx),
+                    channel=adapt_channel(step.channel, ctx),
+                    require=None
+                    if step.require is None
+                    else lambda step=step: eval_condition(step.require, ctx),
+                    require_message=adapt_message(step.require_message, ctx),
+                )
+            elif isinstance(step, DelayStep):
+                ctx.delay(
+                    eval_int(step.n, ctx),
+                    require=None
+                    if step.require is None
+                    else lambda step=step: eval_condition(step.require, ctx),
+                    require_message=adapt_message(step.require_message, ctx),
+                )
+            elif isinstance(step, CaptureStep):
+                ctx.capture(step.name, eval_signal(step.signal, ctx), mode=step.mode)
+            elif isinstance(step, RequireStep):
+                ctx.require(
+                    lambda step=step: eval_condition(step.cond, ctx),
+                    message=adapt_message(step.message, ctx),
+                )
+            elif isinstance(step, BranchStep):
+                if eval_condition(step.cond, ctx):
+                    if step.true_body:
+                        run_steps(ctx, step.true_body)
+                elif step.false_body:
+                    run_steps(ctx, step.false_body)
+            elif isinstance(step, RepeatStep):
+                count = eval_int(step.n, ctx)
+                if count < 0:
+                    raise PatternError(f'repeat count must be non-negative, got {count}')
+                for _ in range(count):
+                    run_steps(ctx, step.body_template)
+            elif isinstance(step, LoopStep):
+                if step.when is not None:
+                    while eval_condition(step.when, ctx):
+                        ctx._guard_operation()
+                        run_steps(ctx, step.body_template)
+                elif step.until is not None:
+                    while True:
+                        ctx._guard_operation()
+                        run_steps(ctx, step.body_template)
+                        if eval_condition(step.until, ctx):
+                            break
+                else:
+                    raise PatternError("loop step must specify either 'until' or 'when'")
+            else:
+                raise PatternError(f'Unknown step type: {type(step).__name__}')
+
+    def body(ctx: PatternContext) -> object:
+        first_step = steps[0] if steps else None
+        if isinstance(first_step, WaitStep):
+            # The first blocking step selects candidate start cycles; later
+            # blocking steps describe timing inside a matched transaction.
+            if not eval_condition(first_step.cond, ctx):
+                if first_step.require is not None:
+                    ctx.require(
+                        lambda first_step=first_step: eval_condition(first_step.require, ctx),
+                        message=adapt_message(first_step.require_message, ctx),
+                    )
+                return None
+            run_steps(ctx, steps[1:])
+        elif isinstance(first_step, ConsumeStep):
+            if not ctx.try_consume(
+                lambda first_step=first_step: eval_condition(first_step.cond, ctx),
+                adapt_channel(first_step.channel, ctx),
+            ):
+                if first_step.require is not None:
+                    ctx.require(
+                        lambda first_step=first_step: eval_condition(first_step.require, ctx),
+                        message=adapt_message(first_step.require_message, ctx),
+                    )
+                return None
+            run_steps(ctx, steps[1:])
+        else:
+            run_steps(ctx, steps)
+        return ctx.OK
+
+    return body