Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CURRICULUM.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,11 @@ Flag numbers identify the weak dimension(s): 1=Concept Focus, 2=Starter Calibrat
|---|---|---|---|---|---|
| `sv/wide-readmem` | Wide Four-State Memory Loading | ✅ | — | `sv/always-ff` | `$readmemh`, address ranges, and non-power-of-two four-state packed words |

### Chapter: Coverage Option Text (October 2026)
| Slug | Title | Status | Score | Prereqs | Teaches |
|---|---|---|---|---|---|
| `sv/coverage-option-text` | Coverage Option Text | ✅ | — | `sv/covergroup-basics` | default and procedural assignment of a covergroup instance's `option.comment` |

### Chapter: Introduction
| Slug | Title | Status | Score | Prereqs | Teaches |
|---|---|---|---|---|---|
Expand Down
19 changes: 17 additions & 2 deletions artifacts/tutorial/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ One commit per issue, each with the test that fails before it and passes after:

### Landed capability chapters

Added seven one-lesson chapters for user-facing SystemVerilog capabilities
Added eight one-lesson chapters for user-facing SystemVerilog capabilities
landed in Mox between September 22 and October 1, 2026. The UDP chapter
tracks landing tip `36b040f6190c`, and the virtual-provider chapter tracks
`3bc88e77921e`; the pinned browser WASM remains unchanged.
Expand All @@ -104,6 +104,7 @@ tracks landing tip `36b040f6190c`, and the virtual-provider chapter tracks
| `sv/sequential-udp-init` | §§29.3.2, 29.6, 29.7 | starter FAIL; solution PASS in interpreter and compile modes | starter both_fail; solution PASS; output equal | `artifacts/tutorial/capability-receipts/*sequential-udp-init*` |
| `sv/virtual-provider-closure` | §§8.20, 8.22 | starter FAIL; solution PASS in interpreter and compile modes | starter both_fail; solution both_pass; output equal | `artifacts/tutorial/virtual-provider-closure/*` |
| `sv/wide-readmem` | §§21.4, 21.4.1 | starter FAIL; solution PASS in interpreter and compile modes | starter both_fail; solution both_pass; output equal | `artifacts/tutorial/wide-readmem/*` |
| `sv/coverage-option-text` | §19.7, Table 19-1 | starter FAIL; solution PASS in interpreter and compile modes | starter both_fail; solution both_pass; output equal | `artifacts/tutorial/coverage-option-text/*` |

The capability receipt summaries are in
`artifacts/tutorial/capability-receipts/{summary,final-summary}.tsv`.
Expand All @@ -113,7 +114,7 @@ receipt are recorded in

## Receipt coverage on origin/main

The 80 registered lesson slugs are now accounted for by either the original
The 84 registered lesson slugs are now accounted for by either the original
generic receipts, a capability-specific bundle, or the missing-matrix bundle
at `artifacts/tutorial/receipts/20261001-missing/`. That matrix records the
18 previously uncovered slugs: native Mox passes for both RTL lessons and all
Expand Down Expand Up @@ -173,6 +174,20 @@ The focused browser run is 1/1 through the pinned interpreter-backed WASM
fallback, not native AOT. Receipts and the Mox landing provenance are under
`artifacts/tutorial/wide-readmem/`.

### Coverage option text chapter

`sv/coverage-option-text` teaches the empty default for a covergroup instance's
`option.comment` and its procedural assignment under IEEE 1800-2023 §19.7 and
Table 19-1. The starter deliberately rejects the empty default; the solution
passes native interpreter and compile modes. Xcelium and Mox agree on the
starter `both_fail` and solution `both_pass` receipts. The focused browser run
is an explicit expected failure for the pinned WASM's unlinked coverage runtime
host-allocation call and is interpreter-only until a WASM rebuild; native AOT is
not claimed. The corrected refdiff receipts retain separate source hashes and
cache keys even when `reference_cached` is true. Receipts and the b481 landing
provenance are under
`artifacts/tutorial/coverage-option-text/`.

## WASM rebuild (done locally, NOT published; release `mox-wasm` is unchanged)
Built with emsdk 4.0.21 from Mox main `9c5418532b9` (and landing `ea0fcd2`): mox-verilog, mox-sim, mox-bmc and
mox-lec. Mox has no wasm target for mox-run (GAPS TUT-WASM-MOXRUN), so two more commits went in:
Expand Down
10 changes: 5 additions & 5 deletions artifacts/tutorial/content-census.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ tutorial's runnable coverage for the landed readmem behavior.

## New landed-capability chapters

These nine short chapters correspond to the user-facing Mox capabilities present
These ten short chapters correspond to the user-facing Mox capabilities present
on the current `origin/main` by October 1, 2026. The compile-mode status page is
listed separately below because it reports qualification status rather than
teaching a new language capability. Every solution passes Mox in both
Expand All @@ -39,14 +39,14 @@ attempts decryption without a key.
| `sv/clocking-sampler-retention` | `3b1760ff2030378cfde16ca319e2c1b806ab9d31`, `test/Tools/mox-sim/mq93-m2-clock-sampler.sv` | §§14.3, 14.13: default `1step` samples before the clock event; explicit `#0` samples in Observed and retains the sample through same-slot re-entry. | solution PASS; starter FAIL | solution PASS; starter FAIL | both PASS / both FAIL, output equal | added an explicit-`#0` sampler-retention exercise |
| `sv/protected-envelope-boundary` | `c3799f427f1e51abcd389dcf15771150223cae75`, `test/Conversion/ImportVerilog/protected-comment-callback.sv` | §§34.2, 34.3, 34.4, 34.5.3–34.5.4: protected text is transformed before analysis and delimiters close the envelope; this lesson does not claim decryption. | solution PASS; starter FAIL | solution PASS; starter FAIL | `reference_only_fail` for solution; Xcelium attempts unkeyed decryption | added same-buffer opaque callback-boundary exercise |
| `sv/wide-readmem` | `e7da9630dcd`, `test/Tools/mox-sim/aot-readmem-wide-fourstate.sv` | §§21.4, 21.4.1: `$readmemh` accepts optional address bounds and loads packed elements of an unpacked memory, preserving four-state digits. | solution PASS; starter FAIL | solution PASS; starter FAIL | starter `both_fail`; solution `both_pass`, output equal | added a width-calibration readmem exercise |
| `sv/coverage-option-text` | `b481355f9fe`, `test/Tools/mox-sim/coverage-covergroup-option-comment-assignment.sv` | §19.7 and Table 19-1: an instance-specific covergroup `comment` defaults to `""` and may be assigned procedurally after instantiation. | solution PASS; starter FAIL | solution PASS; starter FAIL | starter `both_fail`; solution `both_pass`, output equal | added a default-and-assignment coverage-option exercise |

The remaining current-main capability commits are queued for their own short
chapters and are not silently folded into an existing lesson: coverage-option
string preservation (`b481355f9fe`), VPI system-function argument marshalling
(`d83c4b1dde8`), and interface-method `%m` receiver scope plus parenthesized
chapters and are not silently folded into an existing lesson: VPI system-function
argument marshalling (`d83c4b1dde8`), and interface-method `%m` receiver scope plus parenthesized
virtual-interface receivers (`ed441eb5b58`).

This census covers every lesson in `src/lessons/` (meta.js, 73 lessons) and CURRICULUM.md, checked against
This census covers every lesson in `src/lessons/` (meta.js, 84 lessons) and CURRICULUM.md, checked against
IEEE 1800-2023 (`spec/ieee-1800-2023.txt`) and IEEE 1800.2-2020 (UVM).

Each row gives: lesson | claim/example | what is wrong | IEEE clause | evidence | proposed fix | severity.
Expand Down
69 changes: 69 additions & 0 deletions artifacts/tutorial/coverage-option-text/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Coverage option text receipt

This receipt supports `sv/coverage-option-text`. The lesson teaches the
instance-specific `option.comment` default and a procedural assignment on a
covergroup instance. The starter deliberately rejects the standard empty
default; the solution accepts it, assigns the runtime comment, samples one
value, and prints `PASS`.

## Standard and landing basis

IEEE 1800-2023 §19.7 and Table 19-1 define instance-specific coverage
options. The `comment` option defaults to `""`, is associated with the
covergroup instance, and may be assigned procedurally after instantiation.
The lesson does not claim that a simulator's coverage-report formatting is
portable.

The native capability landed in Mox commit `b481355f9fe`
(`b481355f9fe63237a9a5f6307accb8a0133e1e77`), recorded by
`/var/tmp/thomas-ahle/fleet/artifacts/landing/push-b481355f9fe.md`. The exact-
tip qualification established the nine named Chapter-19 controls at 9/9.
The native receipt uses `/var/tmp/thomas-ahle/wt/landing/build-dev-fast` at
`35ec19ea7f9398d76cf704252703ae731dad04d5`, which contains b481 as an
ancestor. No Mox worktree was modified.

## Native runs

The native runs use CPUs `0-79` and a 30-second wall guard. The logs use
`mox-verilog` plus `mox-sim`; the build also has no `mox-run` binary.

| variant | mode | exit | first result line |
|---|---:|---:|---|
| starter | interpret | 0 | `FAIL: starter rejected the empty default comment` |
| starter | compile | 0 | `FAIL: starter rejected the empty default comment` |
| solution | interpret | 0 | `PASS` |
| solution | compile | 0 | `PASS` |

Both compile logs report `AOT interpreter invocations total: 0`. The committed
logs are the six `*-{import,interpret,compile}.log` files in this directory.

## Differential runs

`refdiff` was run on each committed fixture against the same native build:

```text
/var/tmp/thomas-ahle/fleet/bin/refdiff src/lessons/sv/coverage-option-text/coverage_option_text.sv --build-dir /var/tmp/thomas-ahle/wt/landing/build-dev-fast
/var/tmp/thomas-ahle/fleet/bin/refdiff src/lessons/sv/coverage-option-text/coverage_option_text.sol.sv --build-dir /var/tmp/thomas-ahle/wt/landing/build-dev-fast
```

- `starter-refdiff.json`: `both_fail`; both engines reject the deliberate
wrong expectation of a nonempty default.
- `solution-refdiff.json`: `both_pass`; normalized outputs are equivalent.
- The committed refdiff JSON `sha256` field is the exact committed source
hash; `refdiff_cache_key` is the separate 64-hex receipt cache identity.
The receipts were regenerated from the committed fixtures with the commands
above. `starter-source.sha256` and `solution-source.sha256` independently
repeat the source binding. Both corrected receipts record
`reference_cached: true`; the cache key preserves provenance but does not
claim a fresh independent Xcelium run. Standing ruling — `general: refdiff
cache identity is receipt provenance, not a runtime performance cache`.

## Browser qualification

The browser result is recorded in `browser-qa.md`. It is an expected pinned-WASM
failure caused by the unlinked coverage runtime host-allocation call
`__mox_sim_register_host_allocation`; the explicit `test.fail` remains until a
WASM rebuild. Native Mox passes. Browser qualification is interpreter-only
until that linkage is rebuilt, and does not qualify native AOT. Standing ruling
— `general: pinned interpreter fallback is an explicitly scoped browser
compatibility path`.
15 changes: 15 additions & 0 deletions artifacts/tutorial/coverage-option-text/browser-qa.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Browser QA receipt

Command:

```text
npx playwright test e2e/qa-all-lessons.spec.js --grep 'Coverage Option Text' --reporter=line
```

Result: `1 passed` as an expected failure (`e2e/qa-all-lessons.spec.js:67:5`,
lesson `[32]`, `run`), wall time `33.6s`.

The pinned browser WASM route fails with the known unlinked coverage runtime
host-allocation call (`__mox_sim_register_host_allocation`); native Mox passes.
The entry is an explicit `test.fail` for a WASM rebuild, not a tutorial-source
failure and not native AOT qualification.
Loading
Loading