AkashGutha/rtl-practice

โ˜… 0Forks 0HTMLGitHub โ†—Compare

Project website โ†—

README

Digital Design Learning Hub

A shared starting point for digital-design learning. CDC, RDC, STA, and FSM are presented as peer subjects rather than making reset domain crossing the default application.

Module Route Availability
Clock Domain Crossing (CDC) #/cdc Available
Reset Domain Crossing (RDC) #/rdc Available
Static Timing Analysis (STA) #/sta Authored learning edition; independent domain review pending
Finite State Machines (FSM) #/fsm Available, including the existing standalone entry

The root #/ opens the module chooser. The shared navigation switches between available modules; each retains its own progress storage. Existing unprefixed RDC bookmarks such as #/tracks and #/challenge/... redirect to their #/rdc/... equivalents without changing learner data. Internal RDC links use the module prefix.

The shared dist\ and bundle.html include CDC, RDC, STA, and FSM. Module descriptors live in src\features\hub\modules.ts; each application remains independently routed and stores its own learning records.

STA module

The Interactive Synthesis STA MasterClass contains 136 authored primary challenges across four tracks (34 per track), plus a separate twenty-question bank serving five-question adaptive diagnostics. Each primary challenge includes progressive hints, a distinct remediation question, and an independent transfer question; these follow-ups do not inflate the primary count.

Study timing fundamentals and path types, NLDM/slew/fanout, SDC clocks and exceptions, and synthesis optimization/MCMM. The browser-local timing engine exposes separate setup and hold critical paths, delay and required-time arithmetic, real synthetic lookup tables, bounded structural transformations, and explicitly simplified variation models. SDC is a nonexecuting supported dialect; Liberty imports use a documented subset rather than silently accepting unsupported syntax.

The slack debugger exports versioned educational JSON reports and imports them as read-only supplied evidence, not independently analyzed netlists or grading evidence. The SDC sandbox sends its normalized document to a constrained timing worker; parsing or matching a lesson's partial constraint objective is not a timing-closure claim.

STA progress uses its own sta-masterclass IndexedDB database, with validated JSON backups, explicit conflict/quota/unsaved states, and content-version-aware attempts and drafts. RDC's existing storage and backup format are unchanged. Study sheets download directly as PDFs using the existing licensed fonts. Completing all current primary challenges enables a local, non-accredited completion record, with assistance and independent-transfer evidence reported separately.

This is authored, review-pending educational content, not professionally reviewed training or ASIC/FPGA sign-off tooling. No arbitrary Tcl/RTL execution, physical routing, unrestricted vendor-report import, full Liberty compliance, or authenticated credential is claimed.

STA documentation:

  • Product, curriculum, interaction, and technical specification: docs\STA-MASTERCLASS-SPEC.md.
  • Content authoring and grading contracts: docs\STA-CONTENT-AUTHORING.md.
  • Model conventions, explicit fixture choices, and release limitations: docs\STA-MODEL-SUPPORT.md.
  • Exact SDC syntax/normalization boundaries: src\hubs\sta\domain\constraints\README.md.
  • Exact Liberty syntax/table/sequential boundaries: src\hubs\sta\domain\liberty\README.md.

Use npm run bundle after source changes to regenerate both static and portable outputs. STA's portable check rejects a stale artifact rather than passing against a previous build.

RDC module

A browser-local learning platform for reset domain crossing in ASIC/SoC design. It includes 120 challenges across four tracks (30 per track): sixteen interactive core lessons and 104 distinct architecture practice cases. A five-question adaptive diagnostic, linked timing/schematic views, constrained RTL inspection, tiered hints, local progress, and notes support the learning flow.

The sandbox includes a bounded reset-synchronizer pin builder and read-only VCD inspection. Study sheets download directly as PDFs, and completing the current catalog unlocks a clearly labeled local, non-accredited completion record.

Educational models, not hardware sign-off. Source-backed, AI-assisted content still requires qualified hardware-owner approval before professional-review claims. There is no shipped arbitrary SystemVerilog compiler, analog metastability simulation, vendor RDC linter, or accredited certification.

Run locally

Requires Node.js 22.12+ (Node.js 24 recommended) and npm.

npm ci
npm run dev

The terminal prints the local application URL. All app routes use hash navigation, so the production build works on static hosts without path rewrite rules.

npm run build
npm run preview

Deploy the contents of dist to a static host. The app has no backend and does not upload notes, progress, or code. External source links are opened only when selected.

Portable artifact

npm run bundle

Open bundle.html directly in a modern browser. JavaScript, CSS, both simulation and VCD workers, and the licensed PDF fonts are inlined; no runtime CDN is needed. The native Vite single-file plugin replaces the skill's Bash/Parcel bundling wrapper on Windows, retaining one toolchain and the same self-contained output requirement.

File-URL storage policies vary by browser. If storage is unavailable, the UI reports in-memory/unsaved progress. Use JSON backup export to retain work. For the most consistent persistence, serve the static build over HTTP.

Learning flow

  • Begin with any track, or take the optional five-question diagnostic. Placement recommends a starting track and does not award mastery.
  • Multiple-choice questions ask for the root cause; waveform questions accept a signal/time selection; RTL exercises inspect exact curated code alternatives.
  • Three hints progress from concept to timing annotation to reference topology.
  • Two incorrect core attempts make a simpler conceptual follow-up available.
  • Core completion is distinct from independent mastery. Mastery requires a correct first unassisted transfer response after completion; replaying an exposed transfer answer does not establish mastery.
  • Search the catalog by topic or case details, or filter it to a single track.
  • Notes and selected completed-lesson snapshots appear on the cheat-sheet page. Download study-sheet PDF generates a file locally; Print / Save as PDF remains a separate browser action.

Study sheets and completion records

Direct study sheets include notes (including archived lesson notes), reference checks, selected vector timing diagrams, assumptions, and sources. The bundled Noto Sans and Noto Sans Math fonts cover the supported Latin, Greek, and mathematical text; their OFL license is included. Unsupported glyphs produce a visible error rather than being dropped. Browser Print can use system font fallback.

Direct exports are bounded to 24 selected diagrams, 100 pages, and 200,000 text characters. Larger diagram sets require an explicit smaller selection; they are never silently truncated. See src\features\exports\README.md for the complete API and limits.

The local completion record requires completion of all current-version challenges. It is based on editable browser progress, does not verify identity or competence, and is not an accredited credential. Independent transfer mastery remains a separate measure.

Sandbox tools

The reset topology builder inspects supported D-pin, clock, asynchronous-clear, and consumer connections. Invalid internal wiring disables its timing preview instead of claiming to simulate an unsupported circuit.

VCD import is read-only and browser-local, supports scalar/vector values and aliases, and preserves X/Z states. Limits are 2 MiB per file, 128 declared signals including aliases, 100,000 value changes, 1,024 bits per signal, and 8 MiB of expanded values. At most sixteen traces are visible at once. Zoom, scrub, signal selection, and a paginated transition table remain available. Unsupported formats and resource limits produce explicit errors. See src\features\vcd\README.md for parser details.

Modeling boundaries

The timing engine uses bounded integer simulation ticks and deterministic digital state transitions. Its risk indicators are not analog measurements, failure probabilities, or MTBF predictions.

Reset-pin recovery/removal checks are separate from data setup/hold hazards produced when an independently reset source changes asynchronously. Such RDC hazards can occur on the same clock. A reset-release synchronizer does not eliminate every data-path or protocol hazard.

Pulse-width requirements are explicit scenario assumptions, not universal two-clock requirements. FIFO, power, isolation, retention, and test-mode examples have narrow declared contracts and do not implement general UPF, full protocol verification, or production DFT flows.

RTL inspection recognizes only curated alternatives while preserving token boundaries. Unsupported input receives an explicit unsupported result. It is never executed as JavaScript or sent to a server. RTL drafts retain code and their last inspected model together; materially changed lessons restore incompatible drafts with a visible notice.

Architecture practice cases reuse their parent concept's illustrative waveform. That waveform is not a simulation of the entire architecture described in the question. The 120 exercises must not be presented as 120 independent circuit simulators.

Data and privacy

Progress is stored in versioned browser-local records. It is not synchronized between devices or accounts. Browser data clearing and private sessions can remove it.

Use My learning > Export backup before clearing data. Imports validate shape and size and require confirmation before replacing progress. Corrupted/unsupported records and storage failures are surfaced rather than silently overwritten. Cross-tab changes stop writes until the user resolves the conflict.

Imported notes render as text, never as HTML. Backup data is a user-controlled learning record, not a tamper-proof credential.

Development

npm test
npm run lint
npx playwright install chromium firefox webkit
npm run test:e2e

The E2E runner starts a local Vite server on port 4173. Target one configured project with npm run test:e2e -- --project=chromium.

Main boundaries:

Directory Responsibility
src\content Validated lessons, challenges, sources, diagnostic bank
src\domain\timing Pure deterministic circuit/timing models
src\domain\evaluation Answer evaluation, placement, mastery
src\workers Off-main-thread scenario execution
src\features Learning pages, waveforms, schematics, notes/export
src\persistence Versioned state, safe import/export, storage conflicts

Theme colors use Clawpilot variables in src\index.css. ?scoutTheme=light and ?scoutTheme=dark select a theme; otherwise the stored preference or OS setting applies.

Content authoring

Core lessons live in src\content\core.ts; the four src\content\expanded\trackN.ts files contain architecture cases assembled by expanded\authoring.ts. catalog.ts exports the combined track-ordered catalog while retaining original core IDs and the diagnostic bank.

Add typed challenge records with stable IDs and versions. Each needs a learning objective, explanatory lesson, valid answers and distractor rationales, three hints, a remediation question, a distinct transfer question, sources, explicit assumptions, and a supported scenario.

Every model needs accepted/failing golden cases and clear boundary semantics. Increase content versions for material changes so old attempts do not silently confer mastery of changed content. Update the catalog tests when intentionally expanding the curriculum; never inflate published counts with parameter-only duplicates.

Remaining release gates and roadmap

Qualified hardware-domain approval is required before promoting this AI-assisted learning edition as professionally reviewed training.

A private feasibility spike demonstrated actual browser-local Icarus/WASM compilation, execution, VCD output, syntax diagnostics, cancellation, and bounded runs. It is not integrated or shipped: exact corresponding-source and reproducible-build provenance for the tested compiler distribution must be resolved first. The examined source-backed alternative targets Node only and requires a maintained browser port and local rebuild; it is not a drop-in replacement. Concurrent SVA was unsupported in the tested backend; immediate assertions require explicit fatal failure handling for reliable exit status.

Real execution must remain a separate capability from educational inspection. No external HDL service, user-code upload, full SVA/UVM support, or silicon sign-off capability is assumed approved.

Issues