Clocklevel refuses a net at full rate

[mchitre]

A block that samples a clock at that clock's own edge has no settled level in the hardware, and the two models disagreed on one such read: a falling-edge block reading a divide-by-one PLL output saw it high in the Verilog, where the stand-in drops it a step after the pin, and low in Julia.

Rather than pick a value for a race, clocklevel on a net at the rate of the design's own clock pins is now an error. The manual already said the read was only meaningful for a much slower clock. A mux of full-rate sources is refused with its sources; its edges are still counted.

The package's own reads of a net's level, a part's clock output forwarded as a port and a mux's source at a switch, keep treating a full-rate clock as low, as it is at every sample point.

Not breaking: while a design that read a full-rate net with clocklevel got false before and errors now, the old behavior was not a contract but an accidental behavior. In hardware, such an operation is undefined.

Suite green with iverilog. Manual rendered.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.42%. Comparing base (b2ab77c) to head (a53e42c).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master       #7   +/-   ##
=======================================
  Coverage   88.41%   88.42%           
=======================================
  Files          41       41           
  Lines        6519     6524    +5     
=======================================
+ Hits         5764     5769    +5     
  Misses        755      755           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🟡 Changes recommended

Add forwarded-clock simulation coverage and update remaining contradictory black-box and generated documentation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Regenerate API and search documentation for clockout read behavior · New

What changed in this PR

This PR rejects ambiguous clocklevel reads on full-rate clocks while preserving internal clock-tree behavior and edge counting.

Changes:

• Adds full-rate detection and refusal logic.
• Preserves internal forwarded-clock and mux level reads.
• Updates tests and documentation.

File	Summary
test/​runtests.jl	Updates full-rate clock and mux behavior tests.
src/​core/​ports.jl	Uses internal level reads for forwarded clocks.
src/​core/​blackbox.jl	Implements full-rate detection and errors.
qdocs/​wires.qmd	Documents the new restriction.
docs/​wires.html	Updates rendered wires documentation.
docs/​sitemap.xml	Updates documentation metadata.
docs/​search.json	Updates searchable documentation content.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.