docs(blog): three bits, each one necessary - CLK_PERF2 on silicon

[gHashTag]

A blog post on the CLK_PERF2 board results, and two recorded terminal sessions for the t27.ai/term/ gallery that the post embeds.

The post — three-bits-each-necessary (EN + RU), dated 2026-10-04:

• With the PERF2 rows on prjxray-db master, a counter clocked through CLK_PERF2 does not run on the AX7203 (XC7A200T). With the rows proposed in cmt, hclk_cmt: CLK_PERF and PHSR_PERFCLK rows with all their bits openXC7/prjxray-db#30 (c030ed6), it runs.
• The two bitstreams differ in three bits. Clearing any one of the three stops the counter again, so each one is necessary.
• The edit-to-board loop went from about 104–111 s to about 19–28 s.
• Limits are stated up front: one clock path, one board, LEDs read by eye, no counter readback, and a nextpnr-xilinx 115 commits behind main with one merged fix applied locally.

The recordings — tri cast record → scrub → check → publish:

• term/perf2-knockouts/ — perf2.py diff names the three bits. perf2.py knockout rebuilds the three knockout frames files; each is byte-identical to the one that was flashed, and each knockout .bit differs from the working one in 3 bytes past the sync word.
• term/perf2-loop/ — perf2.py loop --flash: router1, bitwalk, xc7frames2bit and an SRAM load, 19.06 s in total at a load average of about 110. The output is identical past the sync word to the build that ran on the board.

The two loop numbers that differ from the post's table (P&R 5.95 s vs 13.2 s, frames→bit 2.11 s vs 0.8 s) are called out in the post as load variance. They are not presented as a better estimate.

Only the bytes printed are real. The prompt and the typing are staged, and silences over 2 s are shortened. All board commands load SRAM only; SPI flash is never written.

{
  "version": 1,
  "head_sha": "ca3d3c9e029e68dbf8232ea55d245f964f8cc0d6",
  "summary": "Adds the blog post 'Three bits, each one necessary' on the CLK_PERF2 board results (EN + RU) and two recorded terminal sessions, perf2-knockouts and perf2-loop, published to the t27.ai/term/ gallery and embedded in the post.",
  "changes": [
    "New post three-bits-each-necessary: body in bodies/three-bits-each-necessary.ts, metadata with 11 receipts and 3 open questions in index.ts, registration in posts.ts.",
    "Two recordings published with tri cast publish under public/term/perf2-knockouts/ and public/term/perf2-loop/ (session.cast, session.gif, card.png, index.html, meta.json).",
    "The gallery page public/term/index.html is regenerated with tri cast gallery after the rebase onto main 292d827aa, not merged by hand; it lists 32 recordings, and its og:image stays the newest one, tri-x7-refs, which comes from main.",
    "casts.ts gains PERF2_KNOCKOUTS and PERF2_LOOP, with EN and RU captions that quote only numbers printed in each recording."
  ],
  "tests": [
    {
      "command": "npm run typecheck:ratchet (apps/website)",
      "status": "not_run",
      "result": "The local run after the rebase is void and is not counted: the worktree had no node_modules, so `npx tsc` resolved to the unrelated npm package named tsc, and the ratchet read its banner as zero errors. The real run is the typecheck ratchet step of the Website checks workflow on this head, which runs npm ci first.",
      "evidence": "Before the rebase, ce1399b49 gave 179 errors across 26 files against a baseline of 179 across 26. The rebase changed no file under apps/website/src."
    },
    {
      "command": "npm run check:tools-site (apps/website)",
      "status": "passed",
      "result": "All 607 tool cards open (544 qualified).",
      "evidence": "Local run on ca3d3c9e0, rebased onto origin/main 292d827aa."
    },
    {
      "command": "npm run check:tools-coverage (apps/website)",
      "status": "passed",
      "result": "Every tri command has a card.",
      "evidence": "Local run on ca3d3c9e0."
    },
    {
      "command": "npm run test:tri-commands (apps/website)",
      "status": "passed",
      "result": "10 of 10 tests pass.",
      "evidence": "Local run on ca3d3c9e0."
    },
    {
      "command": "tri cast check perf2-knockouts.cast; tri cast check perf2-loop.cast",
      "status": "passed",
      "result": "Both recordings check OK: perf2-knockouts 130 events, perf2-loop 72 events.",
      "evidence": "Local run on ca3d3c9e0 against the session.cast files committed under public/term/."
    },
    {
      "command": "lefthook pre-commit and commit-msg hooks",
      "status": "passed",
      "result": "explorer-language and queen-language contracts and the English-only commit message check pass.",
      "evidence": "The pre-commit and commit-msg hooks ran on git commit for ce1399b49 and were not bypassed. The rebase kept the message and changed only the gallery page, so they did not run again; the pre-push branch-name hook ran on the push of ca3d3c9e0."
    },
    {
      "command": "vite build (apps/website)",
      "status": "not_run",
      "result": "Not run locally; the production build is left to the website CI checks on this PR.",
      "evidence": "The laptop was at a load average of about 110 from other jobs, and heavy builds go to CI here."
    }
  ],
  "limitations": [
    "The script the recordings run (perf2.py), the bitstreams, the frames files and the logs live on one laptop and are not published, so a reader cannot rerun the recordings.",
    "The LEDs that show whether the counter runs are not in either recording; the board results in the post were read by eye.",
    "The loop recording was made at a load average of about 110 on 8 cores, so its timings differ from the post's table by up to a factor of two in both directions.",
    "Everything was measured on one clock path of one AX7203 board, with a nextpnr-xilinx 115 commits behind main and one merged fix applied locally."
  ],
  "tags": [
    "FPGA",
    "OpenToolchain",
    "Verification",
    "prjxray"
  ],
  "blog": {
    "title": "Three bits, each one necessary: the MMCM's performance clock on silicon",
    "summary": "With the CLK_PERF2 rows on prjxray-db master, a counter clocked through the MMCM's performance-clock path does not run on an XC7A200T; with the rows proposed in openXC7/prjxray-db#30 it runs, and the two bitstreams differ in three bits, each of which is necessary.",
    "outline": [
      "What was measured, and the probe: a counter clocked through the CLK_PERF2 path on one AX7203 board.",
      "The A/B: one route, two databases, and two bitstreams that differ in exactly three bits, frame ECC aside.",
      "Knockouts: each of the three bits is cleared alone, loaded into SRAM, and stops the counter again.",
      "The decode agrees with the board, and what the open toolchain ships today with nextpnr-xilinx main.",
      "How the build was set up, which parts were stale, and an edit-to-board loop cut from about 104 s to 19-28 s.",
      "What this does not show: one path, one board, LEDs read by eye, no counter readback, and the open questions."
    ],
    "cast": "term/perf2-knockouts/session.cast"
  }
}

🤖 Generated with Claude Code

[github-actions]

X Brain Health Check

Score: 100.0/100
Status: 🟢 HEALTHY
Threshold: 80/100

X Brain is above merge threshold

[github-actions]

🚨 CRITICAL: Brain Health Below Threshold

The brain health CI gate has failed. This PR cannot be merged until:

1. All brain region unit tests pass
2. Integration tests pass
3. Stress test score >= 270/300
4. Brain health score >= 80/100

Please review the failed job logs and fix the issues.