Guided BIOS tuning flow: walk the operator through firmware changes, then re-verify after reboot

[VijitSingh97]

Builds on the BIOS/firmware advisory in #78 and the optimization-target selector in #79.

Gap. #78 makes doctor passively report suboptimal firmware settings. But BIOS tuning is inherently manual — RigForge can't write setup variables from a booted OS (see the feasibility note in #78) and most changes need a reboot — so it doesn't fit the headless, auto-applying tune flow (tune is non-interactive and self-applies in --live; rigforge.sh:1340). What's missing is a guided, resumable walk-through that detects the current firmware state, hands the operator a prioritized, board-specific checklist, and then verifies the changes actually took on the next run.

Proposed approach. An interactive flow — a new bios subcommand (dispatch at rigforge.sh:2115) or a tune --bios mode — that runs a detect → guide → reboot → re-verify loop, reusing the existing read -r -p prompt pattern (rigforge.sh:188, :888):

1. Detect current firmware state via doctor: BIOS/firmware advisory — recommend setup changes from system info (XMP/EXPO, SMT, board/BIOS context) #78's probes (board + BIOS version/date, XMP/EXPO/DOCP on?, SMT on?, RAM channels, boost/power cap).
2. Guide: present a prioritized checklist of the specific BIOS/UEFI changes for the detected hardware — XMP/EXPO/DOCP, SMT, and power/boost settings chosen by the tune: selectable optimization target — raw hashrate vs. hashrate-per-watt (efficiency) #79 target (perf → PBO + max memory profile; efficiency → Eco-Mode/cTDP + Curve-Optimizer undervolt). Walk one item at a time, with the exact setting names.
3. Reboot: instruct the operator to enter BIOS and apply them (RigForge does not and cannot apply them itself).
4. Re-verify: on the next run, re-read the same probes and report which changes took and which are still pending — so the loop converges.

Non-goals. Never writes/flashes BIOS (per #78's feasibility note); strictly guided + advisory. Not part of the automated tune sweep — this is the manual, interactive companion to it.

Acceptance. An interactive flow that walks the operator through the relevant BIOS changes for their detected hardware, respects the #79 optimization target, is honest that the changes are manual, and re-verifies each one after a reboot (reporting what's still pending); documented (docs/operations.md, docs/tuning.md) and tested with fake probes driving both the checklist and the verify pass.

[VijitSingh97]

Fleshing out the UX — what the guided BIOS flow actually looks like for the operator

Now that #78 (the doctor BIOS advisory) and #79 (the perf/efficiency target) have landed, the probes and the target this needs already exist. This comment pins down the operator-facing flow on top of them — the literal terminal session, end to end — so implementation is "wire the existing pieces into a loop" rather than "design a feature."

Command surface

Add a top-level bios verb (dispatch alongside doctor/tune at rigforge.sh:2695). It reads cleaner in usage than a tune --bios mode, and it's honestly not part of the tune sweep — tune is headless and self-applying; bios is interactive and changes nothing itself. It inherits the optimization target the same way tune does, so:

sudo ./rigforge.sh bios                 # uses TUNE_TARGET (default perf)
sudo ./rigforge.sh bios --efficiency    # same flag vocabulary as `tune`
sudo ./rigforge.sh bios --perf

usage line:

  bios       guided, resumable walk-through of the BIOS/UEFI changes for your hardware
             (XMP/EXPO, SMT, PBO/Eco-Mode); detects state, hands you a checklist, and
             re-verifies what took after you reboot. RigForge never writes BIOS itself.

It's stateful and resumable via one small file next to the tune logs — <WORKER_ROOT>/rigforge-bios.json — holding the target, each pending item, and its detected "before" value. That file is what lets the next run say "this one took, this one's still pending." (Worth adding to the backup/restore set at rigforge.sh:2048 alongside tune-overrides.json.)

The loop is detect → guide → reboot → re-verify, and it converges: each run re-reads the same probes and only shows what's still outstanding.

---

Run 1 — detect + guide (first pass)

Reuses the exact probes and ✓ / ! / ∙ markers doctor already prints (_ck_ok/_ck_warn/_ck_info), and the read -r -p prompt pattern from setup/uninstall.

$ sudo ./rigforge.sh bios
[INFO] RigForge guided BIOS tuning — target: perf (raw hashrate)

Reading current firmware state (RigForge can't change these from the OS — it only reads them):
  ∙ Firmware: ASUS ROG STRIX B650E-F GAMING WIFI, BIOS 2611 (2024-09-12), AMD Ryzen 7 7800X3D
  ✓ SMT / Hyper-Threading: enabled
  ✓ RAM: 2 modules across 2 channels (dual-channel)
  ! Memory profile: running at 3600 MT/s, modules rated 6000 MT/s — EXPO/XMP not enabled
  ! CPU boost under load: 4250 MHz = 78% of 5050 MHz max — likely power-capped (PBO not enabled)

2 of 4 items need a BIOS change. I'll walk you through each, then you reboot and apply them.

Then it walks one item at a time (press Enter to advance — paced, not a wall of text), ordered by RandomX impact, each with the exact menu path for the detected board vendor. RigForge keys the path off board_vendor from /sys/class/dmi/id; for vendors not in its small lookup it falls back to a generic "look for …" line.

─── Step 1 of 2 · Enable the memory profile  (biggest single RandomX gain) ─────
  Your kit is rated 6000 MT/s but running at 3600 (JEDEC default — the profile is off).
  On your ASUS board:
      Ai Tweaker ▸ Ai Overclock Tuner ▸ EXPO I
  Typically +10–20% RandomX. Keep this ON for efficiency too — memory speed is free H/s.

  Press Enter when you've noted it (nothing is applied now) …

─── Step 2 of 2 · Lift the power/boost cap (target: perf) ──────────────────────
  The CPU is holding 78% of its rated boost under load — PBO isn't lifting the limit.
      Advanced ▸ AMD Overclocking ▸ Precision Boost Overdrive ▸ Enabled (Advanced)
  (Make sure cooling can keep up — doctor will keep watching the clock-under-load %.)

  Press Enter when you've noted it …

Then it writes state, prints a keep-on-screen checklist for while they're in BIOS, and stops:

[INFO] Saved 2 pending items to <WORKER_ROOT>/rigforge-bios.json.

  Reboot and enter BIOS (ASUS: tap  Del  at the splash). Apply:
    1. Ai Tweaker ▸ Ai Overclock Tuner ▸ EXPO I
    2. Advanced ▸ AMD Overclocking ▸ Precision Boost Overdrive ▸ Enabled (Advanced)
  Save & Exit, boot back up, then run:  sudo ./rigforge.sh bios   (to verify they took)

---

Run 2 — re-verify (after the reboot)

It detects the saved pending items, re-reads the same probes, and reports per-item what moved. An item "took" when its OS-visible fingerprint flips to the desired side (memory spd == rated, smt != off, clock % >= MIN_CLOCK_PCT).

Partial:

$ sudo ./rigforge.sh bios
[INFO] RigForge guided BIOS tuning — target: perf (raw hashrate)
[INFO] Resuming — 2 items were pending from 2026-06-10 21:04.

Re-checking the items you went in to change:
  ✓ Memory profile — now 6000 MT/s (was 3600). EXPO took.
  ! CPU boost — still 79% of max. PBO didn't take; re-check it's "Enabled (Advanced)", not "Auto".

1 of 2 applied, 1 still pending. Reboot into BIOS to finish it, then run `bios` again.

Converged — and it hands off to the natural next step, since the hardware envelope just changed:

Re-checking the items you went in to change:
  ✓ Memory profile — 6000 MT/s. EXPO enabled.
  ✓ CPU boost — 100% of max under load. PBO enabled.

[INFO] All BIOS items applied. Firmware is tuned for: perf.
Next: `sudo ./rigforge.sh tune --live` — retune XMRig against the new memory bandwidth.

Nothing to do (firmware already optimal): it says so and exits without starting a loop —

  ✓ Everything's already set for perf — no BIOS changes needed.

---

Efficiency target — same flow, swapped power items

With --efficiency (or TUNE_TARGET=efficiency), per #79's mapping, the memory step stays but the power step inverts — cap instead of lift:

$ sudo ./rigforge.sh bios --efficiency
[INFO] RigForge guided BIOS tuning — target: efficiency (hashrate-per-watt)
...
─── Step 2 · Cap package power + undervolt  (target: efficiency) ───────────────
      PBO ▸ Eco Mode (65 W TDP)                          ← lower the power ceiling
      Curve Optimizer ▸ All Cores ▸ Negative ▸ 20        ← more clock per watt
  (EXPO stays ON — faster memory is free efficiency.)

---

Honesty & the edge cases that matter

These keep it trustworthy and match the non-goals in the issue:

• Never writes/flashes BIOS. Every item is "you apply this"; the header says so explicitly, reusing doctor's existing wording.
• Only OS-visible items can be auto-verified. Memory profile, SMT, and boost/power have OS fingerprints — those verify automatically. For any item with no OS fingerprint, RigForge must not claim it took: it asks read -r -p "Did you set <item>? (y/N): " and records the operator's answer rather than asserting.
• The boost/PBO item can only be verified while the miner is running — the clock-under-load check is gated on the service being active (rigforge.sh:2602). If the miner's stopped at re-verify time, say so: ! CPU boost — can't verify with the miner stopped; run 'start', let it warm up, then re-run bios. Don't silently pass or fail it.
• This is the one non-headless flow. It needs console keyboard + reboot (or BMC/IPMI/KVM). Call that out up front — the rest of RigForge is headless and auto-applying, so an operator shouldn't expect to drive this over a plain SSH session without out-of-band console access.

---

How little is actually new

Most of this is already in the tree — the value here is the loop and the honesty, not new probing:

Piece	Reuses
Firmware context line, XMP/EXPO + SMT detection	#78 probes in doctor (_dmi, _mem_summary, SMT_CONTROL)
Boost-cap detection	doctor's clock-under-load check (_cpu_eff_khz, MIN_CLOCK_PCT)
✓ / ! / ∙ output, perf-vs-efficiency target	_ck_* helpers + TUNE_TARGET (#79)
Interactive prompts	read -r -p pattern (setup/uninstall)
State file	same shape/location as tune-overrides.json under WORKER_ROOT

Net-new: the resumable rigforge-bios.json state, the per-vendor menu-path lookup, and the detect→guide→reboot→re-verify driver.

Two notes for the acceptance criteria

• Docs: the issue points at docs/tuning.md, but that file doesn't exist — tuning is documented in docs/operations.md (the command table + the tuning section). The bios write-up should land there next to doctor/tune, with a short pointer from docs/getting-started.md.
• Tests: the fake-probe fixtures from the doctor: BIOS/firmware advisory — recommend setup changes from system info (XMP/EXPO, SMT, board/BIOS context) #78/doctor: warn on hashrate-capping hardware (RAM channels/speed, power/boost limits) #67 tests (fake /sys/class/dmi/id, dmidecode with rated≠configured, an SMT control file) drive both passes here — seed them "off" for the guide pass, flip them "on" for the verify pass, and assert the state file transitions an item from pending→applied and that the loop reports convergence.

---

One open call for you: confirm the surface as a top-level bios verb (my recommendation, above) vs. a tune --bios mode. Everything above assumes the verb; if you'd rather fold it under tune, the mockups are identical, just reached via tune --bios.