Improve 11 low-scoring lessons + add 4 Testbench Essentials lessons

Lesson quality improvements (rubric scores):
- sv/data-types: 21→25  — remove signed-arithmetic section, tighten to 2 concepts
- sv/packed-structs: 21→26 — drop unions, add bit-layout SVG, rename title
- sva/isunknown: 20→25  — expand 1→3 properties, new X-propagation SVG
- sva/immediate-assert: 21→25 — expand 2→4 assertions (add count/simultaneous)
- sva/checker: 21→23    — add data_stable_check (2nd property), reuse SVG
- sva/recursive: 20→23  — expand 1→3 properties, SRAM lock narrative, state-machine SVG
- sva/lec: 20→24        — expand 1-char fix to 3 full expressions, LEC flow SVG

New Testbench Essentials chapter (Part 1):
- sv/classes: mem_item class with fields, constructor, convert2string + handle SVG
- sv/queues-arrays: dynamic array + queue with push/pop + layout SVG
- sv/fork-join: fork...join/join_any/join_none with timing diagram SVG
- sv/randomization: rand fields, constraints, inline with, constraint_mode(0) + SVG

Also: sidebar part-progress fraction, sva/seq-args lesson, UVM scoreboard fixes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: thomasahle

CURRICULUM.md

@@ -16,7 +16,7 @@ const LESSONS = [
   { title: 'Flip-Flops with always_ff',                        slug: 'sv/always-ff',         runner: 'sim'    },
   { title: 'Up-Counter',                                       slug: 'sv/counter',           runner: 'sim'    },
   { title: 'Parameters',                                       slug: 'sv/parameters',        runner: 'sim'    },
-  { title: 'Packed Structs and Unions',                        slug: 'sv/packed-structs',    runner: 'sim'    },
+  { title: 'Packed Structs',                                   slug: 'sv/packed-structs',    runner: 'sim'    },
   { title: 'Interfaces',                                       slug: 'sv/interfaces',        runner: 'sim'    },
   { title: 'Modports',                                          slug: 'sv/modports',          runner: 'sim'    },
   { title: 'Tasks and Functions',                              slug: 'sv/tasks-functions',   runner: 'sim'    },
@@ -25,6 +25,10 @@ const LESSONS = [
   { title: 'covergroup and coverpoint',                        slug: 'sv/covergroup-basics', runner: 'sim'    },
   { title: 'Bins and ignore_bins',                             slug: 'sv/coverpoint-bins',   runner: 'sim'    },
   { title: 'Cross coverage',                                   slug: 'sv/cross-coverage',    runner: 'sim'    },
+  { title: 'Classes and Objects',                              slug: 'sv/classes',           runner: 'sim'    },
+  { title: 'Dynamic Arrays and Queues',                        slug: 'sv/queues-arrays',     runner: 'sim'    },
+  { title: 'Concurrent Processes: fork...join',                slug: 'sv/fork-join',         runner: 'sim'    },
+  { title: 'Constrained Randomization',                        slug: 'sv/randomization',     runner: 'sim'    },
   // ── SystemVerilog Assertions ──────────────────────────────────────────────────
   { title: 'Concurrent Assertions in Simulation',              slug: 'sva/concurrent-sim',   runner: 'sim'    },
   { title: 'Vacuous Pass',                                     slug: 'sva/vacuous-pass',     runner: 'sim'    },

e2e/qa-all-lessons.spec.js

@@ -538,11 +538,14 @@ async function runLesson({ verilog, bmc, work, category, slug, lessonDir, result
   // The new circt-sim.js includes VPI support; use it for all lessons.
   const simTool  = 'circt-sim';
   const topName  = metaTop ?? (isUvm ? 'tb_top' : 'tb');
-  // UVM phase cleanup internally advances ~1 ns; give 10 ns to complete.
-  // sv/sva simulations use a 10 µs (10^10 fs) ceiling to guard against hangs
-  // in XFAIL lessons where $finish is never reached (e.g. tasks-functions).
-  // Normal tests finish in ≪ 1 µs of simulation time.
-  const simExtra = isUvm ? ['--max-time', '10000000'] : ['--max-time', '10000000000'];
+  // Default UVM ceiling: 10 ns (enough for delta-cycle-only tests like
+  // factory-override/ral/sequence/seq-item that complete at t=0).
+  // Clock-driven lessons (driver/env/monitor/…) set meta.simMaxTime (fs)
+  // to get more time without inflating the whole suite.
+  // sv/sva simulations use a 10 µs ceiling to guard against hangs.
+  const uvmDefault = '10000000';
+  const simMaxTime = lessonMeta.simMaxTime ? String(lessonMeta.simMaxTime) : (isUvm ? uvmDefault : '10000000000');
+  const simExtra = ['--max-time', simMaxTime];
 
   let compileSolFiles, compileStartFiles, extraFlags;
 
@@ -610,6 +613,9 @@ async function runLesson({ verilog, bmc, work, category, slug, lessonDir, result
     } else if (xfailReason) {
       process.stdout.write(`  ${Y}sol=XFAIL${X}`);
       results.xfail++;
+      if (process.env.VERBOSE_XFAIL) {
+        console.log('\n' + solSim.output.split('\n').map(l => '    ' + l).join('\n'));
+      }
     } else {
       process.stdout.write(`  ${R}sol=NO_PASS${X}\n`);
       results.failures.push({ label, mode: 'solution', reason: 'no PASS in output', output: solSim.output });
@@ -655,6 +661,10 @@ async function main() {
   }
 }
 
+// Optional lesson filter: node test-all-lessons.mjs uvm/env sv/fsm ...
+const FILTER = process.argv.slice(2).filter(a => !a.startsWith('--'));
+const shouldRun = (label) => FILTER.length === 0 || FILTER.includes(label);
+
 async function run(work) {
   const meta = await loadMeta();
 
@@ -672,6 +682,7 @@ async function run(work) {
 
   // ── sv/ ─────────────────────────────────────────────────────────────────────
   for (const slug of listDir('sv')) {
+    if (!shouldRun(`sv/${slug}`)) continue;
     await runLesson({ verilog, bmc, work, category: 'sv', slug, lessonDir: path.join(LESSONS_DIR, 'sv', slug), results, meta });
   }
 
@@ -680,13 +691,13 @@ async function run(work) {
     const runner = meta[`sva/${slug}`]?.runner;
 
     if (runner === 'lec') {
-      console.log(`  ${D}SKIP  sva/${slug} (lec runner)${X}`);
-      results.skip++;
+      if (shouldRun(`sva/${slug}`)) { console.log(`  ${D}SKIP  sva/${slug} (lec runner)${X}`); results.skip++; }
       continue;
     }
 
     // 'bmc' or 'both' → BMC path; null/undefined → sim
     const category = (runner === 'bmc' || runner === 'both') ? 'sva-bmc' : 'sva-sim';
+    if (!shouldRun(`${category}/${slug}`)) continue;
     await runLesson({ verilog, bmc, work, category, slug, lessonDir: path.join(LESSONS_DIR, 'sva', slug), results, meta });
   }
 
@@ -696,6 +707,7 @@ async function run(work) {
     console.log(`${D}Run: npm run sync:circt${X}\n`);
   } else {
     for (const slug of listDir('uvm')) {
+      if (!shouldRun(`uvm/${slug}`)) continue;
       await runLesson({ verilog, bmc, work, category: 'uvm', slug, lessonDir: path.join(LESSONS_DIR, 'uvm', slug), results, meta });
     }
   }
@@ -706,17 +718,21 @@ async function run(work) {
   {
     const mlirSim = await loadTool('circt-sim');
     for (const slug of listDir('mlir')) {
+      if (!shouldRun(`mlir/${slug}`)) continue;
       await runMlirLesson({ sim: mlirSim, slug, lessonDir: path.join(LESSONS_DIR, 'mlir', slug), results });
     }
   }
 
   // ── cocotb/ ─────────────────────────────────────────────────────────────────
   const cocotbDeps = checkCocotbDeps();
   if (!cocotbDeps.ok) {
-    console.log(`\n${D}Skipping cocotb/ — ${cocotbDeps.reason}${X}\n`);
-    for (const slug of listDir('cocotb')) results.skip++;
+    if (FILTER.length === 0) {
+      console.log(`\n${D}Skipping cocotb/ — ${cocotbDeps.reason}${X}\n`);
+      for (const slug of listDir('cocotb')) results.skip++;
+    }
   } else {
     for (const slug of listDir('cocotb')) {
+      if (!shouldRun(`cocotb/${slug}`)) continue;
       await runCocotbLesson({ slug, lessonDir: path.join(LESSONS_DIR, 'cocotb', slug), results, work });
     }
   }

scripts/test-all-lessons.mjs

@@ -82,6 +82,7 @@ export const parts = [
       { title: 'Interfaces & Procedures', lessons: [L('sv/interfaces'), L('sv/modports'), L('sv/tasks-functions')] },
       { title: 'State Machines',        lessons: [L('sv/enums'), L('sv/fsm')] },
       { title: 'Covergroups',            lessons: [L('sv/covergroup-basics'), L('sv/coverpoint-bins'), L('sv/cross-coverage')] },
+      { title: 'Testbench Essentials',  lessons: [L('sv/classes'), L('sv/queues-arrays'), L('sv/fork-join'), L('sv/randomization')] },
     ],
   },
   {

src/lessons/index.js

@@ -0,0 +1,65 @@
+<p>A <strong><dfn data-card="A class is a blueprint that bundles data fields and the methods that operate on them. Unlike structs, class variables hold handles (pointers) to objects on the heap, not the objects themselves.">class</dfn></strong> bundles data and methods into a single unit:</p>
+<pre>class &lt;name&gt;;
+  &lt;field declarations&gt;
+  function new(&lt;args&gt;);  // constructor
+    &lt;initialization&gt;
+  endfunction
+  function string convert2string(); ... endfunction
+endclass</pre>
+<p>Classes are the foundation of UVM — every sequence item, driver, and monitor extends <code>uvm_object</code> or <code>uvm_component</code>, which are themselves classes.</p>
+
+<h3>Handle semantics</h3>
+<p>A class variable is a <strong><dfn data-card="A handle is a reference (pointer) to an object. Assigning one handle to another makes both variables point to the same object — they do not copy the data.">handle</dfn></strong>, not a value. Assigning one handle to another makes both variables point to the <em>same</em> object:</p>
+
+<svg width="430" height="110" viewBox="0 0 430 110" xmlns="http://www.w3.org/2000/svg" style="display:block;max-width:100%;font-family:'IBM Plex Mono',monospace;font-size:11px;margin:8px auto">
+  <!-- Left panel: t2 = t1 — shared -->
+  <text x="90" y="14" text-anchor="middle" fill="#0d6f72" font-weight="bold" font-size="12">t2 = t1</text>
+  <text x="20" y="42" fill="#1e2a2c">t1</text>
+  <line x1="36" y1="38" x2="70" y2="38" stroke="#1e2a2c" stroke-width="1.5" marker-end="url(#cls-a)"/>
+  <text x="20" y="80" fill="#1e2a2c">t2</text>
+  <line x1="36" y1="76" x2="70" y2="55" stroke="#1e2a2c" stroke-width="1.5" marker-end="url(#cls-a)"/>
+  <rect x="72" y="20" width="110" height="50" rx="4" fill="#e6f5f5" stroke="#0d6f72" stroke-width="1.5"/>
+  <text x="127" y="40" text-anchor="middle" fill="#0d6f72" font-weight="bold">object A</text>
+  <text x="127" y="58" text-anchor="middle" fill="#0d6f72" font-size="10">wdata = A5</text>
+  <text x="90" y="100" text-anchor="middle" fill="#c17d2a" font-size="10">both share the same object</text>
+  <!-- Divider -->
+  <line x1="215" y1="8" x2="215" y2="102" stroke="#ccc" stroke-width="1" stroke-dasharray="4,2"/>
+  <!-- Right panel: t2 = new() — independent -->
+  <text x="320" y="14" text-anchor="middle" fill="#c17d2a" font-weight="bold" font-size="12">t2 = new(...)</text>
+  <text x="224" y="42" fill="#1e2a2c">t1</text>
+  <line x1="240" y1="38" x2="270" y2="38" stroke="#1e2a2c" stroke-width="1.5" marker-end="url(#cls-a)"/>
+  <rect x="272" y="20" width="80" height="30" rx="4" fill="#e6f5f5" stroke="#0d6f72" stroke-width="1.5"/>
+  <text x="312" y="39" text-anchor="middle" fill="#0d6f72" font-size="10">object A</text>
+  <text x="224" y="80" fill="#1e2a2c">t2</text>
+  <line x1="240" y1="76" x2="270" y2="76" stroke="#1e2a2c" stroke-width="1.5" marker-end="url(#cls-a)"/>
+  <rect x="272" y="60" width="80" height="30" rx="4" fill="#fff8ec" stroke="#c17d2a" stroke-width="1.5"/>
+  <text x="312" y="79" text-anchor="middle" fill="#c17d2a" font-size="10">object B</text>
+  <text x="320" y="100" text-anchor="middle" fill="#0d6f72" font-size="10">independent objects</text>
+  <defs>
+    <marker id="cls-a" markerWidth="7" markerHeight="6" refX="7" refY="3" orient="auto">
+      <path d="M0,0 L7,3 L0,6 Z" fill="#1e2a2c"/>
+    </marker>
+  </defs>
+</svg>
+<pre>mem_item t1 = new(1, 4'd5, 8'hA5);
+mem_item t2 = t1;       // t2 and t1 share the object
+t2.wdata = 8'hFF;
+$display(t1.wdata);     // prints FF — same object!</pre>
+<p>To get an independent copy, call <code>new(...)</code> again:</p>
+<pre>t2 = new(0, 4'd3, 8'h00);  // t2 now points to a different object
+// t1.wdata is still 8'hFF</pre>
+
+<h3>The <code>this</code> keyword</h3>
+<p>Inside a constructor, argument names often shadow field names. Use <code>this.field</code> to refer to the field unambiguously:</p>
+<pre>function new(bit we, logic [3:0] addr, ...);
+  this.we   = we;    // 'this.we' is the field; 'we' is the argument
+  this.addr = addr;
+endfunction</pre>
+
+<p>Open <code>mem_item.sv</code> and complete three tasks:</p>
+<ol>
+  <li>Declare four fields: <code>bit we</code>, <code>logic [3:0] addr</code>, <code>logic [7:0] wdata</code>, <code>logic [7:0] rdata</code>.</li>
+  <li>Fill in the constructor body using <code>this.field = arg</code>; leave <code>rdata</code> at its default (0).</li>
+  <li>Implement <code>convert2string</code>: return <code>"WR[&lt;addr&gt;]=&lt;wdata&gt;"</code> for writes, <code>"RD[&lt;addr&gt;]"</code> for reads.</li>
+</ol>
+<p>The testbench (already in the file) demonstrates handle sharing: assigning <code>t2 = t1</code> and then modifying <code>t2.wdata</code> changes <code>t1.wdata</code> too. Then <code>t2 = new(...)</code> creates a fresh object, leaving <code>t1</code> unchanged.</p>

src/lessons/meta.js

@@ -0,0 +1,39 @@
+class mem_item;
+  bit         we;
+  logic [3:0] addr;
+  logic [7:0] wdata;
+  logic [7:0] rdata;
+
+  function new(bit we, logic [3:0] addr, logic [7:0] wdata);
+    this.we    = we;
+    this.addr  = addr;
+    this.wdata = wdata;
+    this.rdata = 8'h00;
+  endfunction
+
+  function string convert2string();
+    if (we)
+      return $sformatf("WR[%0d]=%0h", addr, wdata);
+    else
+      return $sformatf("RD[%0d]", addr);
+  endfunction
+endclass
+
+module mem_item_tb;
+  initial begin
+    mem_item t1, t2;
+
+    t1 = new(1, 4'd5, 8'hA5);
+    $display("t1: %s", t1.convert2string());
+
+    t2 = t1;
+    t2.wdata = 8'hFF;
+    assert (t1.wdata == 8'hFF) else $fatal(1, "FAIL: handle assignment should share the object");
+
+    t2 = new(0, 4'd3, 8'h00);
+    $display("t2: %s", t2.convert2string());
+    assert (t1.wdata == 8'hFF) else $fatal(1, "FAIL: t1 should be unchanged after t2 = new(...)");
+
+    $display("PASS");
+  end
+endmodule

src/lessons/sv/classes/description.html

@@ -0,0 +1,47 @@
+// A class bundles data and methods that operate on it.
+// Unlike structs, classes are reference types: a variable holds a *handle*
+// (pointer) to an object, not the object itself.
+
+class mem_item;
+  // TODO: declare four fields
+  //   bit         we
+  //   logic [3:0] addr
+  //   logic [7:0] wdata
+  //   logic [7:0] rdata
+
+  // Constructor — called with 'new(we, addr, wdata)'
+  function new(bit we, logic [3:0] addr, logic [7:0] wdata);
+    // TODO: store each argument into the matching field using this.field = arg
+    //       leave rdata at its default value (0)
+  endfunction
+
+  // Pretty-print for $display
+  function string convert2string();
+    // TODO: return a formatted string:
+    //   if we: "WR[<addr>]=<wdata>"
+    //   else:  "RD[<addr>]"
+    // Hint: use $sformatf("WR[%0d]=%0h", addr, wdata)
+  endfunction
+endclass
+
+module mem_item_tb;
+  initial begin
+    mem_item t1, t2;
+
+    // Create the first object and verify convert2string
+    t1 = new(1, 4'd5, 8'hA5);
+    $display("t1: %s", t1.convert2string());
+
+    // Assign handle — t2 and t1 point to the SAME object
+    t2 = t1;
+    t2.wdata = 8'hFF;
+    assert (t1.wdata == 8'hFF) else $fatal(1, "FAIL: handle assignment should share the object");
+
+    // Create a new independent object
+    t2 = new(0, 4'd3, 8'h00);
+    $display("t2: %s", t2.convert2string());
+    assert (t1.wdata == 8'hFF) else $fatal(1, "FAIL: t1 should be unchanged after t2 = new(...)");
+
+    $display("PASS");
+  end
+endmodule