SVW Wave Bridge

SVW Wave Bridge is an independent, open-source interoperability component. It is a user-built dynamic library that serves bounded, read-only waveform data over its host process standard input and standard output. The library is built by the user against a separately obtained and properly licensed reader SDK. No SDK header, library, example, documentation, or waveform database is included in this repository or its releases.

The current backend reads .fsdb waveform files. That format name is used only to identify compatibility. This project is not affiliated with, endorsed by, or sponsored by any SDK provider. All third-party names and rights belong to their respective owners.

Requirements

• A C++11 compiler and make.
• Python 3 for repository audits and Git hooks.
• A locally installed reader SDK that the user is entitled to use.

The bridge itself uses only the C++ standard library. The SDK include path and link flags must be supplied explicitly; the build never searches the machine, downloads dependencies, or copies SDK files.

Build

Use the include directory and linker flags documented for your local SDK:

make READER_INCLUDE=/absolute/path/to/reader/include \
     READER_LDFLAGS='-L/absolute/path/to/reader/lib -Wl,-rpath,/absolute/path/to/reader/lib' \
     READER_LIBS='SDK_LINK_FLAGS_FROM_YOUR_LOCAL_DOCUMENTATION'

The resulting build/libsvw-wave-bridge.so (or platform-equivalent dynamic library) is a local artifact. Do not redistribute it unless the applicable SDK agreement expressly permits that action. Activate it explicitly for SVW:

export SVW_FSDB_BRIDGE=/absolute/path/to/build/libsvw-wave-bridge.so
svw waveform.fsdb

SVW loads only this user-selected library in an isolated internal host process. The distributed SVW binary has no direct SDK dependency and does not search for the bridge or reader libraries.

Current SVW distributions always include the generic bridge client and its commands. There is no FSDB-specific SVW build switch: setting SVW_FSDB_BRIDGE is the user's explicit runtime activation step. If it is not set, SVW reports that activation is required and does not search the machine.

Protocol

The exported svw_wave_bridge_entry_v1 function emits this handshake at startup:

SVW_WAVE_BRIDGE 1 CAPABILITIES 7376772d776176652d627269646765

Requests and responses are ASCII lines. Text and paths are lowercase hex-encoded bytes. Every request carries a decimal request ID:

SVW1 ID OPEN HEX_PATH
SVW1 ID INFO
SVW1 ID SIGNALS OFFSET LIMIT
SVW1 ID TYPE SIGNAL_ID
SVW1 ID CHANGES SIGNAL_ID START_TICK END_TICK OFFSET LIMIT
SVW1 ID LOOKUP SIGNAL_ID TICK SEQUENCE_OR_DASH
SVW1 ID NEIGHBOR SIGNAL_ID TICK DIRECTION
SVW1 ID STATS MODE START_TICK END_TICK SIGNAL_ID...
SVW1 ID RECORDS SIGNAL_ID START_TICK END_TICK OFFSET LIMIT
SVW1 ID ASSERTION_DEBUG SIGNAL_ID RECORD_ID
SVW1 ID RUNTIME_INFO
SVW1 ID RUNTIME_WRITES TICK OFFSET LIMIT
SVW1 ID CLOSE
SVW1 ID QUIT

Paged requests return BEGIN, a bounded sequence of typed data lines, then END. TYPE transports dimensions, enum literals, and packed members. RECORDS transports transaction, assertion, and event records with typed attributes, tags, and relations. ASSERTION_DEBUG transports local values and an assertion phase timeline. Limits are bounded by the implementation, pagination is explicit, and the bridge provides no general command-execution operation. Times are integer native ticks. The INFO response carries the exact decimal timescale factor and base-ten exponent.

Hierarchy discovery is demand-driven after OPEN returns. While discovery is in progress, its declaration count is a safe upper-bound hint; the producer pauses at the requested SIGNALS page boundary and resumes only when another page is requested. A final page uses - as its cursor and establishes the exact readable declaration count. The implementation uses an independent read-only hierarchy handle, so value and type queries for an admitted signal do not force the remaining hierarchy to be enumerated.

CAPABILITIES is an eight-digit lowercase hexadecimal bit mask. The required base operations use 0000001f. Bit 00000020 optionally declares the format-neutral runtime-write operations. RUNTIME_INFO returns whether the opened waveform contains a complete stream and, when complete, the versioned semantic-design snapshot identity used to capture it. A consumer must require an exact snapshot match. A backend must return false for partial, inferred, truncated, stale, or uncorrelated evidence. RUNTIME_WRITES pages the records for one tick and preserves signal-local sequence, delta, global order, schedule region, semantic process/object identifiers, and canonical bit range. Existing backends that do not override these optional C++ methods continue to advertise 0000001f and remain protocol-compatible.

Bit 00000040 optionally declares indexed waveform queries. LOOKUP returns the last value at or before a tick, optionally bounded by a same-tick sequence. NEIGHBOR returns the first strictly earlier or later change time for direction -1 or 1. Together with the existing bounded CHANGES window, these operations let a consumer query only the visible time region. The operations are format-neutral: a backend may advertise them for any waveform reader that can provide complete indexed results. Consumers must fall back to the base CHANGES operation when the capability is absent.

Bit 00000080 optionally declares batch transition summaries. STATS accepts one to 32 signal identifiers and a presence, changes, or directions mode. The modes respectively answer whether the range contains records, count actual value changes with one-bit edges, or include full per-bit direction coverage. This lets a consumer request only the work needed for an analysis. The result is format-neutral, read-only, and optional; consumers fall back to indexed or bounded base queries when the capability is absent.

Only lines beginning with SVW_WAVE_BRIDGE or SVW1 are protocol frames. A client must treat every other line from the local SDK as untrusted diagnostics and must never parse it as a response. The ABI has one exported C symbol; all C++ types remain private to the user-built library.

Development and commit gate

python3 tools/install_hooks.py
make test
python3 tools/commit_gate.py --worktree

The installer selects the versioned hooks on current Git and also installs the same bytes into .git/hooks/ for older Git versions. It refuses to overwrite an unrelated existing hook. The pre-commit hook audits the exact staged tree and tests a temporary snapshot of that tree. The pre-push hook rejects every commit or annotated tag whose author, committer, or tagger email is absent from .githooks/allowed-emails. The gate rejects non-C++ product sources, nonstandard dependencies, third-party assets or branding, executable build artifacts, missing MIT headers, unsafe Git modes, whitespace errors, and protocol test failures.

License

SVW Wave Bridge is licensed under the MIT License. See LICENSE.