Add doctor and framework depth modules

Author: manishklach

README.md

@@ -15,14 +15,16 @@ CPUOpt-Kernel translates vendor CPU performance controls into safe Linux policy
 prefers existing kernel interfaces over raw register writes and treats thermal and fan
 control as platform concerns, not as a shortcut for unsafe CPU tuning.
 
-Version `v0.1` is intentionally conservative:
+Version `v0.2` remains intentionally conservative:
 
 - Intel-first, user-space-first implementation
 - No raw MSR writes
 - No thermal protection bypass
 - No voltage or overclock manipulation
 - Reversible sysfs writes with snapshot/restore
 - Dry-run support for every profile application
+- `doctor`, `explain`, `intel-hwp`, and compare/telemetry-oriented depth commands
+- Read-only Intel MSR telemetry decoder with no write path
 
 ## Why this exists
 
@@ -42,6 +44,11 @@ The first release focuses on safe Intel profile application through sysfs:
 - `discover` and `status` report CPUFreq, `intel_pstate`, EPP, EPB, turbo, cpuidle,
   thermal, cooling, hwmon, SMT, topology, and NUMA metadata when present
 - `profile` maps high-level policies to existing sysfs knobs
+- `doctor` highlights problems, opportunities, and safety constraints before tuning
+- `explain` documents profile intent, tradeoffs, and safety limits
+- `intel-hwp` reports Intel HWP/EPP exposure and optional read-only telemetry availability
+- `msr-read --intel --safe` decodes a small read-only allowlist of Intel MSRs
+- `compare` provides a safe benchmark/comparison scaffold without automatic package install
 - `monitor` provides lightweight live telemetry
 - `restore` replays the last reversible snapshot
 
@@ -65,10 +72,16 @@ cpuopt-kernel/
 python3 cpuoptctl/cpuoptctl.py status
 python3 cpuoptctl/cpuoptctl.py discover --json
 sudo python3 cpuoptctl/cpuoptctl.py profile performance --dry-run
+sudo python3 cpuoptctl/cpuoptctl.py profile performance --dry-run --diff
 sudo python3 cpuoptctl/cpuoptctl.py profile balanced
 sudo python3 cpuoptctl/cpuoptctl.py profile latency --allow-idle-tuning
 sudo python3 cpuoptctl/cpuoptctl.py profile quiet
 sudo python3 cpuoptctl/cpuoptctl.py profile ai-inference
+python3 cpuoptctl/cpuoptctl.py doctor
+python3 cpuoptctl/cpuoptctl.py explain performance
+python3 cpuoptctl/cpuoptctl.py intel-hwp
+sudo python3 cpuoptctl/cpuoptctl.py msr-read --intel --safe
+python3 cpuoptctl/cpuoptctl.py compare balanced performance --benchmark stress-ng --duration 30
 sudo python3 cpuoptctl/cpuoptctl.py monitor --interval 2
 sudo python3 cpuoptctl/cpuoptctl.py restore
 python3 cpuoptctl/cpuoptctl.py export-json
@@ -86,14 +99,31 @@ python3 -m unittest
 
 - CPUOpt prefers existing kernel interfaces over raw register writes.
 - Every write validates path existence, writability intent, and candidate value selection.
+- Dry-run performs zero filesystem modifications.
 - Unknown sysfs paths are skipped, not guessed.
 - Failed writes are logged and are non-fatal.
 - Modified values are snapshotted to `last_state.json` before application.
-- v0.1 never writes `/dev/cpu/*/msr`, firmware registers, BIOS settings, or BMC controls.
+- `msr-read` is read-only telemetry only and never writes `/dev/cpu/*/msr`.
+- CPUOpt never writes firmware registers, BIOS settings, or BMC controls.
 - Fan writes are intentionally unimplemented in v0.1 even if fan inspection is enabled.
 
 See [docs/SAFETY.md](C:\Users\ManishKL\Documents\Playground\cpuopt-kernel\docs\SAFETY.md) for the full model.
 
+## Demo
+
+```bash
+cpuoptctl doctor
+cpuoptctl profile performance --dry-run --diff
+cpuoptctl monitor
+```
+
+Demo assets:
+
+- [assets/cpuopt-status-demo.txt](C:\Users\ManishKL\Documents\Playground\cpuopt-kernel\assets\cpuopt-status-demo.txt)
+- [assets/cpuopt-doctor-demo.txt](C:\Users\ManishKL\Documents\Playground\cpuopt-kernel\assets\cpuopt-doctor-demo.txt)
+- [assets/cpuopt-dry-run-demo.txt](C:\Users\ManishKL\Documents\Playground\cpuopt-kernel\assets\cpuopt-dry-run-demo.txt)
+- [assets/cpuopt-monitor-demo.txt](C:\Users\ManishKL\Documents\Playground\cpuopt-kernel\assets\cpuopt-monitor-demo.txt)
+
 ## Example status output
 
 ```text
@@ -120,9 +150,10 @@ Warnings:
 - Optional kernel module under `/sys/kernel/cpuopt/`
 - Read-only MSR decoding with model-aware guardrails
 - Model-specific write allowlists only after documentation and fallback validation
+- Workload presets, benchmark compare, and richer doctor/explain flows
 
 ## Project metadata
 
 - License: `GPL-2.0-only`
-- Current target release: `v0.1.0`
+- Current target release: `v0.2.0`
 - CI: GitHub Actions runs Python compile checks and `unittest`

assets/cpuopt-doctor-demo.txt

@@ -0,0 +1,13 @@
+CPUOpt Doctor
+-------------
+[OK] intel_pstate active
+[OK] EPP exposed
+[WARN] turbo disabled
+[OK] performance governor available
+[INFO] 1 thermal zones detected
+[INFO] hwmon fan sensors detected, write disabled by policy
+[WARN] deepest C-state has high exit latency; latency profile may benefit from --allow-idle-tuning
+[INFO] no restore snapshot available
+[WARN] not running as root; write operations may fail
+[INFO] MSR device not available for read-only telemetry
+[INFO] no uncore frequency interface detected

assets/cpuopt-dry-run-demo.txt

@@ -0,0 +1,13 @@
+Planned CPUOpt changes
+----------------------
+/sys/devices/system/cpu/cpufreq/policy0/scaling_governor
+  current: powersave
+  new:     performance
+
+/sys/devices/system/cpu/cpufreq/policy0/energy_performance_preference
+  current: balance_performance
+  new:     performance
+
+/sys/devices/system/cpu/intel_pstate/no_turbo
+  current: 1
+  new:     0

assets/cpuopt-monitor-demo.txt

@@ -0,0 +1,9 @@
+timestamp=2026-06-28T13:00:00+00:00
+avg_current_freq=1800000
+min_current_freq=1800000
+max_current_freq=1800000
+package_temp=51000
+hottest_zone=x86_pkg_temp
+turbo_status=1
+boost_status=1
+policy=policy0 governor=powersave epp=balance_performance current_freq=1800000

assets/cpuopt-status-demo.txt

@@ -0,0 +1,14 @@
+## CPUOpt Status
+
+Vendor: GenuineIntel
+Model: Intel(R) Core(TM) i7-1280P
+Kernel: 6.8.0-test
+Scaling driver: intel_pstate
+HWP/EPP exposed: yes
+Turbo control: intel_pstate/no_turbo
+Policies:
+  policy0 CPUs=0-7 governor=powersave min=400000 max=4700000 epp=balance_performance
+Thermals:
+  x86_pkg_temp temp=51000
+Warnings:
+  Fan control is platform-specific; not directly controlled unless safely exposed.

cpuoptctl/cpuopt_compare.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+try:
+    from .cpuopt_telemetry import collect_sample
+except ImportError:
+    from cpuopt_telemetry import collect_sample
+
+
+BENCHMARKS: dict[str, list[str]] = {
+    "stress-ng": ["stress-ng", "--cpu", "1", "--timeout", "10", "--metrics-brief"],
+    "sysbench": ["sysbench", "cpu", "--time=10", "run"],
+}
+
+
+def compare_profiles(
+    profile_a: str,
+    profile_b: str,
+    benchmark: str,
+    duration: int,
+    sysfs_root: str = "/sys",
+) -> dict[str, Any]:
+    if benchmark not in BENCHMARKS:
+        return {"ok": False, "reason": f"unsupported benchmark: {benchmark}"}
+    binary = shutil.which(BENCHMARKS[benchmark][0])
+    if binary is None:
+        return {"ok": False, "reason": f"benchmark not installed: {benchmark}"}
+
+    before = collect_sample(sysfs_root=sysfs_root)
+    benchmark_result = _run_benchmark(benchmark, duration)
+    after = collect_sample(sysfs_root=sysfs_root)
+    return {
+        "ok": True,
+        "profile_a": profile_a,
+        "profile_b": profile_b,
+        "benchmark": benchmark,
+        "duration": duration,
+        "samples": {
+            profile_a: before,
+            profile_b: after,
+        },
+        "benchmark_result": benchmark_result,
+    }
+
+
+def format_compare_report(result: dict[str, Any]) -> str:
+    if not result.get("ok"):
+        return f"Profile comparison unavailable: {result.get('reason')}"
+    profile_a = result["profile_a"]
+    profile_b = result["profile_b"]
+    sample_a = result["samples"][profile_a]
+    sample_b = result["samples"][profile_b]
+    lines = ["Profile comparison", "------------------", f"Workload: {result['benchmark']}", f"Duration: {result['duration']}s", ""]
+    lines.append(f"{'Metric':<24}{profile_a:<14}{profile_b:<14}")
+    lines.append(f"{'Avg frequency':<24}{_fmt_freq(sample_a.get('avg_current_freq')):<14}{_fmt_freq(sample_b.get('avg_current_freq')):<14}")
+    lines.append(f"{'Max temperature':<24}{_fmt_temp(sample_a.get('package_temp')):<14}{_fmt_temp(sample_b.get('package_temp')):<14}")
+    lines.append(f"{'Thermal throttling':<24}{'unknown':<14}{'unknown':<14}")
+    lines.append(f"{'Elapsed time':<24}{str(result['duration']) + 's':<14}{str(result['duration']) + 's':<14}")
+    return "\n".join(lines)
+
+
+def _run_benchmark(benchmark: str, duration: int) -> dict[str, Any]:
+    cmd = list(BENCHMARKS[benchmark])
+    if benchmark == "stress-ng":
+        cmd = ["stress-ng", "--cpu", "1", "--timeout", str(duration), "--metrics-brief"]
+    if benchmark == "sysbench":
+        cmd = ["sysbench", "cpu", f"--time={duration}", "run"]
+    completed = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    return {"returncode": completed.returncode, "stdout": completed.stdout, "stderr": completed.stderr}
+
+
+def _fmt_freq(value: Any) -> str:
+    if not isinstance(value, int):
+        return "n/a"
+    return f"{value / 1_000_000:.1f} GHz"
+
+
+def _fmt_temp(value: Any) -> str:
+    if not isinstance(value, int):
+        return "n/a"
+    return f"{value / 1000:.0f} C"

cpuoptctl/cpuopt_doctor.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+
+def build_doctor_report(
+    discovery: dict[str, Any],
+    state_dir: str,
+    dev_root: str = "/dev",
+    is_root: bool | None = None,
+) -> list[tuple[str, str]]:
+    findings: list[tuple[str, str]] = []
+    policies = discovery.get("policies", [])
+    intel_pstate = discovery.get("intel_pstate", {})
+    if intel_pstate.get("status") == "active":
+        findings.append(("OK", "intel_pstate active"))
+    elif any(policy.get("scaling_driver") for policy in policies):
+        findings.append(("INFO", f"scaling driver detected: {policies[0].get('scaling_driver')}"))
+    else:
+        findings.append(("WARN", "no scaling driver detected"))
+
+    has_epp = any(policy.get("energy_performance_preference") for policy in policies)
+    findings.append(("OK" if has_epp else "WARN", "EPP exposed" if has_epp else "EPP not exposed"))
+
+    turbo_disabled = intel_pstate.get("no_turbo") == "1" or discovery.get("cpufreq_boost") == "0"
+    findings.append(("WARN" if turbo_disabled else "OK", "turbo disabled" if turbo_disabled else "turbo enabled"))
+
+    has_perf_governor = any("performance" in policy.get("available_governors", []) for policy in policies)
+    findings.append(
+        ("OK" if has_perf_governor else "WARN", "performance governor available" if has_perf_governor else "performance governor unavailable")
+    )
+
+    zone_count = len(discovery.get("thermal", {}).get("thermal_zones", []))
+    findings.append(("INFO", f"{zone_count} thermal zones detected"))
+
+    hwmon = discovery.get("hwmon", [])
+    fan_detected = any(
+        any(name.startswith("fan") for name in device.get("sensors", {}))
+        for device in hwmon
+    )
+    if fan_detected:
+        findings.append(("INFO", "hwmon fan sensors detected, write disabled by policy"))
+    else:
+        findings.append(("INFO", "no hwmon fan sensors detected"))
+
+    deepest = _deepest_state(discovery)
+    if deepest is not None and (deepest.get("latency") or 0) >= 100:
+        findings.append(
+            (
+                "WARN",
+                "deepest C-state has high exit latency; latency profile may benefit from --allow-idle-tuning",
+            )
+        )
+    elif deepest is not None:
+        findings.append(("INFO", "cpuidle states detected with modest deepest-state latency"))
+    else:
+        findings.append(("INFO", "no cpuidle states detected"))
+
+    findings.append(
+        ("INFO", "restore snapshot available" if (Path(state_dir) / "last_state.json").exists() else "no restore snapshot available")
+    )
+
+    root_state = is_root if is_root is not None else (_safe_is_root())
+    findings.append(("OK" if root_state else "WARN", "running with root privileges" if root_state else "not running as root; write operations may fail"))
+
+    msr_path = Path(dev_root) / "cpu" / "0" / "msr"
+    findings.append(("INFO", "MSR device available for read-only telemetry" if msr_path.exists() else "MSR device not available for read-only telemetry"))
+
+    findings.append(("INFO", "no uncore frequency interface detected"))
+    return findings
+
+
+def format_doctor_report(findings: list[tuple[str, str]]) -> str:
+    lines = ["CPUOpt Doctor", "-------------"]
+    for level, message in findings:
+        lines.append(f"[{level}] {message}")
+    return "\n".join(lines)
+
+
+def _safe_is_root() -> bool:
+    try:
+        return os.geteuid() == 0
+    except AttributeError:
+        return False
+
+
+def _deepest_state(discovery: dict[str, Any]) -> dict[str, Any] | None:
+    states = discovery.get("cpuidle_states", [])
+    if not states:
+        return None
+    return max(states, key=lambda state: state.get("latency") or -1)