feat(macos): read Pro/Max CPU power from raw SMC keys (IOReport reports 0)

On Pro/Max/Ultra the IOReport energy model reports 0 for CPU — verified,
powermetrics returns "CPU Power: 0 mW" with the cores pegged — so power.cpu was
Unavailable there. But the power is still in the SMC under the per-cluster keys
(PC02 + PC42 on an M3 Max, the same source Stats reads). Sum them and report a
real power.cpu tagged "P-cores (SMC)" — ~11W under load, verified live on this
M3 Max.

IOReport stays the first source so base dies (M4) are unchanged; SMC fills
Pro/Max; only a chip whose keys we haven't mapped falls back to Unavailable.
Generalized the SMC reader to read any float key, and moved the read out of
assembleApplePower (injected as a param) so the unit tests stay hardware-free.

So Apple didn't screw it — the standard energy APIs just don't surface it on
Pro/Max, but the raw SMC does. Guide 13 rewritten to match.

Author: kinncj

CHANGELOG.md

@@ -7,6 +7,20 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-07-02
+
+### Added
+- **Apple Silicon Pro/Max CPU power, via raw SMC keys.** On Pro/Max/Ultra dies
+  the IOReport energy model reports `0` for CPU (verified — `powermetrics` does
+  too), so `power.cpu` used to read Unavailable there. But the per-domain power is
+  still in the SMC under the per-cluster keys (`PC02` + `PC42` on an M3 Max — the
+  same source Stats reads). Heimdall now sums those and reports a real `power.cpu`
+  tagged `P-cores (SMC)` — **~11 W under load, verified live on an M3 Max**.
+  IOReport stays the first source, so base dies (e.g. M4) are unchanged; the SMC
+  keys fill Pro/Max, and only a chip whose keys aren't mapped yet falls back to
+  `no per-domain CPU power (IOReport + SMC)`. The SMC reader was generalized to
+  read any AppleSMC float key.
+
 ## [2.4.3] - 2026-07-02
 
 ### Fixed

app/internal/helper/collect.go

@@ -27,13 +27,14 @@ func PrivilegedMetrics(ctx context.Context) []domain.Metric {
 	if runtime.GOOS == "darwin" {
 		cpu, gpu, ane, gpuUtil, ioOK := ioReportPower(200)
 		smcPkg, smcOK := smcSystemPower()
+		smcCPU, smcCPUOK := smcCPUPower()
 		// powermetrics (root only) fills GPU utilisation and any power the energy
 		// counters did not expose.
 		var pm []domain.Metric
 		if text, err := runPowermetrics(ctx); err == nil {
 			pm = parsePowermetrics(text)
 		}
-		out = append(out, assembleApplePower(cpu, gpu, ane, gpuUtil, ioOK, smcPkg, smcOK, pm)...)
+		out = append(out, assembleApplePower(cpu, gpu, ane, gpuUtil, ioOK, smcPkg, smcOK, smcCPU, smcCPUOK, pm)...)
 	}
 	// Linux privileged sources (RAPL power, hwmon temps); no-op off Linux.
 	out = mergeByName(out, linuxPrivileged(ctx))
@@ -140,7 +141,7 @@ func powerMetric(name string, w float64) domain.Metric {
 // Silicon Pro/Max chips IOReport reports 0 for CPU/ANE and only a sub-watt GPU
 // figure, so the energy-sum is a phantom — it must never shadow a real SMC or
 // powermetrics reading. pm is the parsed powermetrics output (may be nil).
-func assembleApplePower(cpu, gpu, ane, gpuUtil float64, ioOK bool, smcPkg float64, smcOK bool, pm []domain.Metric) []domain.Metric {
+func assembleApplePower(cpu, gpu, ane, gpuUtil float64, ioOK bool, smcPkg float64, smcOK bool, smcCPU float64, smcCPUOK bool, pm []domain.Metric) []domain.Metric {
 	var out []domain.Metric
 	if ioOK {
 		// CPU and ANE: a 0 reading means the channel is *unavailable* on Pro/Max
@@ -182,14 +183,18 @@ func assembleApplePower(cpu, gpu, ane, gpuUtil float64, ioOK bool, smcPkg float6
 			out = append(out, powerMetric("power.total", sum))
 		}
 	}
-	// Apple Pro/Max SoCs expose no per-domain CPU power — IOReport and powermetrics
-	// both report 0 for the CPU/ANE channels (only the SMC whole-system total is
-	// real). Base M-series populate it. Say why rather than leaving power.cpu a
-	// silent blank; power.total still carries the real whole-machine figure.
+	// On Pro/Max the IOReport energy model reports 0 for CPU, but the raw SMC
+	// per-cluster keys still carry it (the source Stats reads) — try those before
+	// giving up. Base M-series already set power.cpu above from IOReport.
+	if smcCPUOK && !hasName(out, "power.cpu") {
+		out = append(out, domain.Metric{Name: "power.cpu", Unit: "watts", Status: domain.StatusOK, Gauge: smcCPU, Detail: "P-cores (SMC)"})
+	}
+	// If neither IOReport nor the SMC keys yielded CPU power, say why rather than
+	// leaving a silent blank; power.total still carries the whole-machine figure.
 	if ioOK && !hasName(out, "power.cpu") {
 		out = append(out, domain.Metric{
 			Name: "power.cpu", Status: domain.StatusUnavailable,
-			Detail: "Pro/Max: no per-domain CPU power",
+			Detail: "no per-domain CPU power (IOReport + SMC)",
 		})
 	}
 	// Apple Silicon is unified memory — there is no discrete VRAM to read. Report

app/internal/helper/parse_gpu_vram_test.go

@@ -86,7 +86,7 @@ func TestEnsureNPUUtil(t *testing.T) {
 // Apple Silicon has unified memory and no discrete VRAM to report; gpu.vram must
 // be Unavailable with a reason rather than absent, so the panel explains the dash.
 func TestAssembleApplePower_VRAMUnavailableWithReason(t *testing.T) {
-	got := byName(assembleApplePower(5, 2, 0, 30, true, 22, true, nil))
+	got := byName(assembleApplePower(5, 2, 0, 30, true, 22, true, 0, false, nil))
 	m, ok := got["gpu.vram"]
 	if !ok || m.Status != domain.StatusUnavailable {
 		t.Fatalf("gpu.vram = %+v, want unavailable", m)

app/internal/helper/smc_darwin.go

@@ -10,11 +10,13 @@ package helper
 #include <IOKit/IOKitLib.h>
 #include <string.h>
 #include <stdint.h>
+#include <stdlib.h>
 
 // AppleSMC key access. PSTR ("System Total Power", IEEE float, watts) is the
-// whole-system power rail mactop/btop/iStat read without root — and the only
-// power figure populated on Apple Silicon Pro/Max chips, whose IOReport energy
-// channels report 0 for CPU/ANE.
+// whole-system power rail mactop/btop/iStat read without root. The per-domain
+// keys (PCPC "CPU Package", PCTR "CPU Total", PG0C "GPU", …) carry CPU/GPU power
+// even on Apple Silicon Pro/Max, whose IOReport energy channels report 0 — the
+// same raw SMC keys Stats reads. All are IEEE floats in watts.
 typedef struct { char major, minor, build, reserved[1]; uint16_t release; } smc_vers_t;
 typedef struct { uint16_t version, length; uint32_t cpuPLimit, gpuPLimit, memPLimit; } smc_plim_t;
 typedef struct { uint32_t dataSize, dataType; char dataAttributes; } smc_kinfo_t;
@@ -35,11 +37,13 @@ static uint32_t smc_str2key(const char *s) {
 	return ((uint32_t)s[0] << 24) | ((uint32_t)s[1] << 16) | ((uint32_t)s[2] << 8) | (uint32_t)s[3];
 }
 
-// smc_read_pstr opens AppleSMC, reads PSTR as a float, and returns watts. The
-// connection is opened and closed per call; this runs at the collector cadence
-// (hundreds of ms), so the open cost is negligible and we avoid holding a port.
-// Returns 0 on any failure (no AppleSMC, key absent, wrong type).
-static double smc_read_pstr(void) {
+// smc_read_key opens AppleSMC, reads the given 4-char key as a float, and returns
+// watts. *found is set to 1 when the key exists and was read as a float (the
+// value may legitimately be 0), else 0 — so callers can tell an absent key from a
+// genuine zero. The connection is opened/closed per call; at the collector
+// cadence the open cost is negligible and we avoid holding a port.
+static double smc_read_key(const char *k, int *found) {
+	*found = 0;
 	io_service_t svc = IOServiceGetMatchingService(0, IOServiceMatching("AppleSMC"));
 	if (!svc) return 0;
 	io_connect_t conn = 0;
@@ -49,7 +53,7 @@ static double smc_read_pstr(void) {
 	}
 	IOObjectRelease(svc);
 
-	uint32_t key = smc_str2key("PSTR");
+	uint32_t key = smc_str2key(k);
 	double watts = 0;
 
 	smc_kd_t in = {0}, out = {0};
@@ -73,6 +77,7 @@ static double smc_read_pstr(void) {
 				float f;
 				memcpy(&f, ro.bytes, 4);
 				watts = (double)f;
+				*found = 1;
 			}
 		}
 	}
@@ -82,13 +87,42 @@ static double smc_read_pstr(void) {
 */
 import "C"
 
-// smcSystemPower reads the SMC PSTR ("System Total Power") rail in watts. No root
-// required. ok is false when AppleSMC or the key is unavailable, or the reading
-// is non-positive, so callers fall back to IOReport / powermetrics.
+import "unsafe"
+
+// smcReadFloat reads a 4-char AppleSMC float key in watts. ok is true when the
+// key exists and read as a float (value may be 0); false when absent or the wrong
+// type. No root required.
+func smcReadFloat(key string) (float64, bool) {
+	ck := C.CString(key)
+	defer C.free(unsafe.Pointer(ck))
+	var found C.int
+	w := float64(C.smc_read_key(ck, &found))
+	return w, found != 0
+}
+
+// smcSystemPower reads the SMC PSTR ("System Total Power") rail in watts. ok is
+// false when AppleSMC or the key is unavailable, or the reading is non-positive,
+// so callers fall back to IOReport / powermetrics.
 func smcSystemPower() (watts float64, ok bool) {
-	w := float64(C.smc_read_pstr())
-	if w <= 0 {
+	w, found := smcReadFloat("PSTR")
+	if !found || w <= 0 {
 		return 0, false
 	}
 	return w, true
 }
+
+// smcCPUPower sums the raw SMC P-core cluster power keys, which carry CPU power
+// on Apple Silicon Pro/Max even where the IOReport energy model reports 0. On the
+// M3 Max these are PC02 + PC42 (the two 6-core P-clusters) — verified live; the
+// aggregate keys (PCPC/PCTR) that exist on some chips are absent there. Returns
+// the cluster sum when at least one key is present (0 at idle is a real reading);
+// absent on chips that expose none, so the caller falls back to Unavailable.
+func smcCPUPower() (watts float64, ok bool) {
+	for _, k := range []string{"PC02", "PC42"} {
+		if w, found := smcReadFloat(k); found {
+			watts += w
+			ok = true
+		}
+	}
+	return watts, ok
+}

app/internal/helper/smc_other.go

@@ -8,3 +8,7 @@ package helper
 // smcSystemPower is macOS-only; off Apple Silicon or in CGO-free builds it
 // reports no value and callers fall back to IOReport / powermetrics.
 func smcSystemPower() (watts float64, ok bool) { return 0, false }
+
+// smcCPUPower is macOS-only; off Apple Silicon or in CGO-free builds it reports
+// no value.
+func smcCPUPower() (watts float64, ok bool) { return 0, false }

app/internal/helper/smc_power_test.go

@@ -13,7 +13,7 @@ import (
 // only a sub-watt GPU figure. SMC PSTR ("System Total Power") is the real number.
 // power.total must come from SMC, not the ~0.1W IOReport sum.
 func TestAssembleApplePower_SMCWinsOverPhantomIOReport(t *testing.T) {
-	got := byName(assembleApplePower(0, 0.1, 0, 5, true /*ioOK*/, 42.0, true /*smcOK*/, nil))
+	got := byName(assembleApplePower(0, 0.1, 0, 5, true /*ioOK*/, 42.0, true /*smcOK*/, 0, false, nil))
 	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 42.0 {
 		t.Errorf("power.total = %+v, want 42W from SMC", m)
 	}
@@ -30,11 +30,23 @@ func TestAssembleApplePower_SMCWinsOverPhantomIOReport(t *testing.T) {
 	}
 }
 
+// On Pro/Max IOReport gives no CPU power (0), but the raw SMC P-core cluster keys
+// do — power.cpu is filled from SMC then, tagged so its source is clear.
+func TestAssembleApplePower_SMCCPUFillsProMax(t *testing.T) {
+	got := byName(assembleApplePower(0 /*ioreport cpu 0*/, 0.1, 0, 5, true, 42, true, 10.6 /*smcCPU*/, true, nil))
+	if m := got["power.cpu"]; m.Status != domain.StatusOK || m.Gauge != 10.6 {
+		t.Fatalf("power.cpu = %+v, want 10.6W from SMC", m)
+	}
+	if got["power.cpu"].Detail == "" {
+		t.Error("SMC-sourced power.cpu should be labelled")
+	}
+}
+
 // GPU power is always a valid IOReport channel on Apple Silicon, so it must be
 // reported even at idle (~0 W) — dropping it made a base M4 look like it "has no
 // GPU" while a Pro/Max (whose CPU/ANE channels genuinely read 0) showed the GPU.
 func TestAssembleApplePower_ShowsIdleGPU(t *testing.T) {
-	got := byName(assembleApplePower(0.5, 0 /*gpu idle*/, 0, 3, true /*ioOK*/, 20, true, nil))
+	got := byName(assembleApplePower(0.5, 0 /*gpu idle*/, 0, 3, true /*ioOK*/, 20, true, 0, false, nil))
 	if m, ok := got["power.gpu"]; !ok || m.Status != domain.StatusOK || m.Gauge != 0 {
 		t.Fatalf("power.gpu = %+v (present=%v), want a 0 W reading at idle", m, ok)
 	}
@@ -44,7 +56,7 @@ func TestAssembleApplePower_ShowsIdleGPU(t *testing.T) {
 // reading (the old mergeByName poisoning).
 func TestAssembleApplePower_PowermetricsBeatsPhantomIOReport(t *testing.T) {
 	pm := []domain.Metric{{Name: "power.total", Unit: "watts", Status: domain.StatusOK, Gauge: 12.7}}
-	got := byName(assembleApplePower(0, 0.1, 0, -1, true, 0, false /*no smc*/, pm))
+	got := byName(assembleApplePower(0, 0.1, 0, -1, true, 0, false /*no smc*/, 0, false, pm))
 	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 12.7 {
 		t.Errorf("power.total = %+v, want 12.7W from powermetrics", m)
 	}
@@ -53,15 +65,15 @@ func TestAssembleApplePower_PowermetricsBeatsPhantomIOReport(t *testing.T) {
 // With neither SMC nor powermetrics, a meaningful IOReport sum is still used as a
 // last resort (back-compat for chips that do expose per-domain energy).
 func TestAssembleApplePower_IOReportSumLastResort(t *testing.T) {
-	got := byName(assembleApplePower(8, 3, 0, -1, true, 0, false, nil))
+	got := byName(assembleApplePower(8, 3, 0, -1, true, 0, false, 0, false, nil))
 	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 11 {
 		t.Errorf("power.total = %+v, want 11W from IOReport sum", m)
 	}
 }
 
 // No sources at all: no power.total emitted (caller renders Unavailable).
 func TestAssembleApplePower_NoSources(t *testing.T) {
-	got := byName(assembleApplePower(0, 0, 0, -1, false, 0, false, nil))
+	got := byName(assembleApplePower(0, 0, 0, -1, false, 0, false, 0, false, nil))
 	if _, ok := got["power.total"]; ok {
 		t.Errorf("power.total should be absent when no source yields a value")
 	}

docs/guides/13-privileged-macos.md

@@ -43,39 +43,42 @@ This ordering exists because of the Pro/Max quirk below.
 > first is what keeps an M3 Max from reporting 0 W. The variable is the **SoC,
 > not the Heimdall version**. See [ADR 0020](../architecture/0020-hlidskjalf-top-view-and-npu-rename.md).
 
-> **CPU package-power gap**: some M-series SoCs expose no CPU package-power
-> counter at all — neither IOReport nor `powermetrics` reports it. `power.cpu`
-> reads `unavailable` there. A hardware limit, not a misconfiguration.
-
-## Why a base M4 shows CPU power but an M3 Max doesn't (and both show GPU)
-
-This trips people up, so to be explicit — it's **the chip tier, not the macOS
-version, and not a Heimdall bug**:
-
-| Rail | Base (M1–M4) | Pro / Max / Ultra |
-|---|---|---|
-| `power.cpu` | **reported** — IOReport exposes per-domain CPU energy | **`unavailable`** — the CPU (and ANE) energy channels read **0** |
-| `power.gpu` | reported (idles at a few mW) | reported |
-| `power.total` | SMC `PSTR`, whole-system | SMC `PSTR`, whole-system |
-
-On **Pro/Max/Ultra** dies the SoC's "Energy Model" simply does not surface
-per-domain **CPU** or **ANE** power — both IOReport *and* `powermetrics` return
-`CPU Power: 0 mW` even with the cores pegged. So `power.cpu` is honestly
-`unavailable` (`Pro/Max: no per-domain CPU power`), while the true whole-machine
-draw still comes through `power.total` (SMC). Base dies expose the per-domain CPU
-figure, so they show a real `power.cpu`.
-
-**GPU** power is a valid IOReport channel on *every* Apple Silicon SoC, so it is
-always reported — including a few milliwatts at idle. (Heimdall used to drop a
-zero-valued GPU rail, which made an idle base M4 look like it "had no GPU"; since
-v2.4.3 the idle GPU shows as `0 W` instead.)
-
-Verified across two SoCs and macOS builds:
-
-| Machine | SoC | macOS (Darwin) | `power.cpu` | `power.gpu` |
+> **CPU power on Pro/Max**: IOReport and `powermetrics` report `0` for CPU on
+> Pro/Max/Ultra, but the raw SMC per-cluster keys still carry it — Heimdall reads
+> those (see the next section). `power.cpu` only stays `unavailable` on a chip
+> whose SMC keys aren't mapped yet.
+
+## How CPU/GPU power is read on Apple Silicon (base vs Pro/Max)
+
+Heimdall reads Apple power from two unprivileged sources and layers them:
+
+1. **IOReport** "Energy Model" — per-domain CPU/GPU/ANE. On **base** dies (M1–M4)
+   this populates `power.cpu`. On **Pro/Max/Ultra** the CPU and ANE channels read
+   **0** (both IOReport *and* `powermetrics` return `CPU Power: 0 mW` with the
+   cores pegged) — so IOReport alone can't give CPU power there.
+2. **Raw SMC keys** — the same source Stats reads. Pro/Max dies still expose CPU
+   power under the per-cluster power keys (`PC02` + `PC42` = the two 6-core
+   P-clusters on an M3 Max), even though the energy model reports 0. When IOReport
+   gives no CPU figure, Heimdall sums those SMC cluster keys and reports
+   `power.cpu` tagged `P-cores (SMC)`.
+
+So `power.cpu` is **real on both tiers** now — from IOReport on base dies, from
+the SMC cluster keys on Pro/Max. It only falls back to
+`no per-domain CPU power (IOReport + SMC)` when *neither* source responds (a chip
+whose SMC cluster keys we haven't mapped — the keys are reverse-engineered and can
+differ per generation, exactly like the temperature keys). `power.total` (SMC
+`PSTR`) always carries the whole-machine draw regardless.
+
+**GPU** power is a valid IOReport channel on every Apple Silicon SoC, so it is
+always reported — including a few milliwatts at idle (since v2.4.3 the idle GPU
+shows as `0 W` instead of being dropped).
+
+Verified live across two SoCs and macOS builds:
+
+| Machine | SoC | macOS (Darwin) | `power.cpu` source | value |
 |---|---|---|---|---|
-| Mac mini | Apple **M4** (base) | 26.6 / Darwin 25.6 | real (~0.5 W idle) | reported (idle → 0 W) |
-| MacBook Pro | Apple **M3 Max** | 27.0 / Darwin 27.0 | `unavailable` (Pro/Max) | reported |
+| Mac mini | Apple **M4** (base) | 26.6 / Darwin 25.6 | IOReport | ~0.5 W idle |
+| MacBook Pro | Apple **M3 Max** | 27.0 / Darwin 27.0 | **SMC `PC02`+`PC42`** | ~11 W under load |
 
 ## Build note — IOReport needs CGO