Merge pull request #3 from PaoloRondot/main

Update documentation and fix the waveforms crashing

Author: thomasnormal

scripts/toolchain.lock.sh

@@ -11,4 +11,4 @@ readonly CIRCT_REF_LOCKED="8bcd565479190e5cc512a254d10cde513b2c123c"
 readonly CIRCT_LLVM_SUBMODULE_REF_LOCKED="aa3d6b37c7945bfb4c261dd994689de2a2de25bf"
 
 readonly SURFER_ARTIFACT_URL_LOCKED="https://gitlab.com/surfer-project/surfer/-/jobs/artifacts/main/download?job=pages_build"
-readonly SURFER_ARTIFACT_SHA256_LOCKED="2a684122436e7a7729cc4e57062fdc2ce8ec5fa096d84ca383dd59011012b873"
+readonly SURFER_ARTIFACT_SHA256_LOCKED="abf8d4c3415d445bf86edb39dda9ec9f37d20ccddf4069ec925acb608dcb661b"

src/lessons/sv/always-ff/description.html

@@ -25,6 +25,20 @@
 </pre>
 <blockquote><p>
    We use <strong><dfn data-card="Non-blocking assignment (<=) schedules the update to happen after all right-hand sides in the current time step are evaluated. This means two flip-flops can swap values correctly: a <= b; b <= a; works as expected. Blocking assignment (=) takes effect immediately, like a variable assignment in C — correct for combinational logic but causes races in sequential logic.">non-blocking assignment</dfn></strong> (<code>&lt;=</code>) inside <code>always_ff</code>. It works in two steps: first, all right-hand sides are sampled using current values; then all left-hand sides update simultaneously. So <code>out</code> always captures the value <code>mem</code> held <em>before</em> this edge — creating a true one-cycle delay, not a zero-delay pass-through. The same rule is why <code>a &lt;= b; b &lt;= a;</code> correctly swaps two flip-flops.</p></blockquote>
+
+<p>The names describe how each operator behaves in the flow of your procedural code — whether the assignment <strong>blocks</strong> (pauses) execution until it completes.</p>
+<p><strong>Blocking <code>=</code></strong> — execution stops and waits. The assignment completes immediately, in place, before the next line runs. Think of it like hand-delivering a letter: the recipient has it before you walk away.</p>
+<pre>
+a = b;  // a gets b's value RIGHT NOW
+c = a;  // c sees the new value of a
+</pre>
+<p><strong>Non-blocking <code>&lt;=</code></strong> — execution continues without waiting. The assignment schedules a write for later and immediately moves on. Think of it like dropping a letter in a mailbox: you keep walking and it gets delivered later, when the NBA update region runs.</p>
+<pre>
+a &lt;= b;  // schedules a write to a, but doesn't apply it yet
+c &lt;= a;  // c gets a's OLD value — the write above hasn't happened yet
+</pre>
+<p>All right-hand sides are evaluated first, then all writes happen together at the end of the time step. This is what makes <code>always_ff</code> correctly model real hardware, where all flip-flops in a clocked stage sample their inputs and update simultaneously.</p>
+
 <p>
 An SRAM is an array of flip-flops — one per bit — indexed by address.
 We'll need a slightly more advanced pattern to model that array.
@@ -78,4 +92,4 @@
 </ul>
 <blockquote><p>The read is <em>registered</em>: drive <code>addr</code> on cycle N and <code>rdata</code> reflects that address on cycle N+1. This is the standard synchronous-read SRAM model.</p></blockquote>
 <h2>Testbench</h2>
-<p><code>tb.sv</code> writes three values to addresses 2, 7, and 0, then reads them back one cycle later. Each read prints <code>PASS</code> or <code>FAIL</code> — run it before solving to see all three fail, then again after to confirm they all pass. Open the <strong>Waves</strong> tab to see <code>clk</code>, <code>we</code>, <code>addr</code>, <code>wdata</code>, and <code>rdata</code> over time.</p>
+<p><code>tb.sv</code> writes three values to addresses 2, 7, and 0, then reads them back one cycle later. Each read prints <code>PASS</code> or <code>FAIL</code> — run it before solving to see all three fail, then again after to confirm they all pass. Open the <strong>Waves</strong> tab to see <code>clk</code>, <code>we</code>, <code>addr</code>, <code>wdata</code>, and <code>rdata</code> over time.</p>

src/lessons/sv/tasks-functions/description.html

@@ -8,8 +8,8 @@
    // task body
 endtask</code></pre>
 <p>
-Here <code>automatic</code> means the task is re-entrant: it can be called recursively or from multiple places without interference.
-Non-automatic tasks share state across calls.
+Here <code>automatic</code> means the task is re-entrant: it can be called recursively or from multiple places without interference — just like a normal C/C++ function whose local variables live on the stack, with a fresh copy created for each call.
+A non-<code>automatic</code> (static) task behaves like a C function where every local variable is declared <code>static</code>: all calls share the same memory, so concurrent calls will overwrite each other's state.
 </p>
 <p>
 Calling a task <code>write_word(addr, data)</code> is blocking.
@@ -21,6 +21,9 @@
    <li><code>write_word(vif, addr, data)</code> — a task that drives one write transaction: assert <code>we</code>, set <code>addr</code> and <code>wdata</code>, wait one clock edge, then de-assert <code>we</code>.</li>
    <li><code>read_word(vif, addr, data)</code> — a task that drives one read transaction: set <code>addr</code>, wait one clock edge, then capture <code>rdata</code>.</li>
 </ul>
+<blockquote><p>
+  Waiting for <code>@(posedge clk)</code> is not enough on its own. The testbench and the DUT are both sensitive to the same edge, so driving or sampling signals <em>at</em> the edge puts you in a race against the simulator's scheduler. The safe pattern is to wait for the edge and then advance a small delta — <code>@(posedge clk); #1;</code> — so that your assignments land in a quiet moment after the DUT has already reacted to the clock.
+</p></blockquote>
 <blockquote><p>These are the exact helper routines a UVM driver uses internally. In Part 3 the driver wraps them in a class method that pulls transactions from a sequencer — but the core protocol logic is the same.</p></blockquote>
 <h2>Testbench structure</h2>
 <p>The <code>initial</code> block calls <code>write_word</code> and <code>read_word</code> using the shared <code>mem_if</code> virtual interface, then checks the parity of the returned data with <code>parity_check</code>.</p>

src/runtime/circt-adapter.js

@@ -170,11 +170,21 @@ function needsUvmLibrary(files) {
 function removeInlinedPortsFromVcd(vcd) {
   if (typeof vcd !== 'string') return vcd;
   const lines = vcd.split('\n');
-  const skipIds = new Set();
+  const topLevelIds = new Set();   // ids used by non-dotted (top-level) signals
+  const dottedIds = new Map();     // id → true for dotted signal names
 
   for (const line of lines) {
     const m = line.match(/\$var\s+\S+\s+\d+\s+(\S+)\s+(\S+)(?:\s+\[\S+\])?\s+\$end/);
-    if (m && m[2].includes('.')) skipIds.add(m[1]);
+    if (!m) continue;
+    if (m[2].includes('.')) dottedIds.set(m[1], true);
+    else topLevelIds.add(m[1]);
+  }
+  // Only skip dotted signals whose VCD id is already claimed by a top-level
+  // signal (i.e. inlined port duplicates). Keep interface member signals that
+  // have their own unique id.
+  const skipIds = new Set();
+  for (const id of dottedIds.keys()) {
+    if (topLevelIds.has(id)) skipIds.add(id);
   }
   if (skipIds.size === 0) return vcd;
 
@@ -243,8 +253,9 @@ function fixLlhdVcdEncoding(vcd) {
         for (let i = 0; i < svWidth; i++) {
           decoded += flagBits[i] === '1' ? 'x' : valBits[i];
         }
-        // 1-bit results use the compact scalar form.
-        return (svWidth === 1 ? decoded : 'b' + decoded) + ' ' + id;
+        // 1-bit results use the compact scalar form (no space before id).
+        if (svWidth === 1) return decoded + id;
+        return 'b' + decoded + ' ' + id;
       }
     }