jouleclaw-energy: a Mac's whole-machine power from the SMC (EnergyDomain::System, ModelBased) #622

Merged

dcharlot merged 1 commit from jouleclaw-energy/smc-system into main 2026-11-05 04:30:59 -05:00

Conversation 0 Commits 1 Files changed 10 +903 -30

dcharlot commented 2026-11-04 20:00:33 -05:00

Owner

Copy link

On Apple Silicon under macOS 27, IOReport's CPU rails are frozen for an unprivileged reader, so detect_meter falls back to the load-average estimator, a guess graded Estimator. Every Mac still publishes its total power in the SMC key PSTR, and any process can read it through the AppleSMCKeysEndpoint IOKit user client, with no root.

What changes

• New EnergyDomain::System: the whole machine. It covers everything the machine's DC input feeds: the SoC, memory, storage, fans and the rest of the board. It does not cover the power supply's AC-to-DC loss. It contains SocTotal and every other domain.
• New feature smc (macOS), module apple_smc. SmcSystemCounter integrates PSTR over time and grades the result ModelBased. That is the grade NVML's power.draw integral already carries: PSTR is a power reading, not an energy counter, so no liveness probe can vouch for its integral.
  • Sampling. One thread per process polls every 100 ms and integrates the value it holds, so a figure doesn't depend on how often the caller reads. Reads never run backwards.
  • Startup check. PSTR must be a 4-byte float, and the sampler must see it refresh before the counter is available. The first construction in a process waits about a second for that.
  • Bad samples. A sample at or below 0 W, above 1.5 kW, or NaN is discarded and counted.
  • Staleness. If the value holds for 10 s, reads give no figure.
  • Minimum window: 2 s. PSTR refreshes about once a second (median gap 1.0 s on both Macs below), and it lags a step in load by about one refresh.
• detect_meter order on macOS. A live IOReport counter comes first, then the SMC, then the load-average estimator. A figure from the SMC includes whatever else the machine powered, so it can read high for the work but never low.
• mesh-meter. Its exhaustive covers_whole_request match now treats System as covering the whole request.
• SPEC §1.3. The ModelBased row now lists vendor power sampled and integrated over time (Apple SMC PSTR).
• MEASURED_ENERGY.md gets a new section on this meter.
• The energy_probe example supports --features smc and integrates over at least the counter's minimum window.

The feature is opt-in, so existing consumers behave as before until they enable smc.

Measured (macOS 27.2, unprivileged, energy_probe, 2.5 s CPU churn)

Host	Reading
Mac Studio, M3 Ultra (IOReport CPU rails frozen)	299.9 J · 120.0 W, ModelBased, System
MacBook Pro, M5 Max, on AC	160.9 J · 64.4 W, ModelBased, System

• Mac Studio: PSTR equals the DC input (PDTR).
• MacBook Pro: on AC with the battery not charging, it read 51.7 W against 54.9 W at the DC input. So it measures the system's draw, not the input.
• Not established: whether each value averages the preceding second or samples a single point. Other load on the dev Mac hid the test; the grade and the minimum window hold either way.

Tests

• Unit tests drive the integral, monotonic reads, implausible samples, staleness and the sampler's startup with scripted samples and times.
• The hardware test meters a CPU burn from the real SMC and prints apple-smc: measured. A new macOS CI step greps for that line under --features smc and ioreport,smc. The clippy step lints both configurations.
• The existing IOReport fallback test now expects the SMC (ModelBased) where it's built and live, and the estimator otherwise.

Passing:

• M3 Ultra: smc, ioreport,smc and ioreport (both existing CI greps). Clippy clean in default, ioreport, smc and ioreport,smc. mesh-meter with hw-meter-apple.
• Linux x86_64: rapl,nvml, default clippy, and mesh-meter with hw-meter-rapl.

This PR is independent of #618 (RAPL MSR fallback); the two touch different lines.

🤖 Generated with Claude Code

On Apple Silicon under macOS 27, IOReport's CPU rails are frozen for an unprivileged reader, so `detect_meter` falls back to the load-average estimator, a guess graded `Estimator`. Every Mac still publishes its total power in the SMC key `PSTR`, and any process can read it through the `AppleSMCKeysEndpoint` IOKit user client, with no root. ## What changes - **New `EnergyDomain::System`: the whole machine.** It covers everything the machine's DC input feeds: the SoC, memory, storage, fans and the rest of the board. It does not cover the power supply's AC-to-DC loss. It contains `SocTotal` and every other domain. - **New feature `smc` (macOS), module `apple_smc`.** `SmcSystemCounter` integrates `PSTR` over time and grades the result **`ModelBased`**. That is the grade NVML's `power.draw` integral already carries: `PSTR` is a power reading, not an energy counter, so no liveness probe can vouch for its integral. - **Sampling.** One thread per process polls every 100 ms and integrates the value it holds, so a figure doesn't depend on how often the caller reads. Reads never run backwards. - **Startup check.** `PSTR` must be a 4-byte float, and the sampler must see it refresh before the counter is available. The first construction in a process waits about a second for that. - **Bad samples.** A sample at or below 0 W, above 1.5 kW, or NaN is discarded and counted. - **Staleness.** If the value holds for 10 s, reads give no figure. - **Minimum window: 2 s.** `PSTR` refreshes about once a second (median gap 1.0 s on both Macs below), and it lags a step in load by about one refresh. - **`detect_meter` order on macOS.** A live IOReport counter comes first, then the SMC, then the load-average estimator. A figure from the SMC includes whatever else the machine powered, so it can read high for the work but never low. - **`mesh-meter`.** Its exhaustive `covers_whole_request` match now treats `System` as covering the whole request. - **SPEC §1.3.** The `ModelBased` row now lists vendor power sampled and integrated over time (Apple SMC `PSTR`). - **`MEASURED_ENERGY.md`** gets a new section on this meter. - **The `energy_probe` example** supports `--features smc` and integrates over at least the counter's minimum window. The feature is opt-in, so existing consumers behave as before until they enable `smc`. ## Measured (macOS 27.2, unprivileged, `energy_probe`, 2.5 s CPU churn) | Host | Reading | |---|---| | Mac Studio, M3 Ultra (IOReport CPU rails frozen) | 299.9 J · 120.0 W, `ModelBased`, `System` | | MacBook Pro, M5 Max, on AC | 160.9 J · 64.4 W, `ModelBased`, `System` | - **Mac Studio:** `PSTR` equals the DC input (`PDTR`). - **MacBook Pro:** on AC with the battery not charging, it read 51.7 W against 54.9 W at the DC input. So it measures the system's draw, not the input. - **Not established:** whether each value averages the preceding second or samples a single point. Other load on the dev Mac hid the test; the grade and the minimum window hold either way. ## Tests - **Unit tests** drive the integral, monotonic reads, implausible samples, staleness and the sampler's startup with scripted samples and times. - **The hardware test** meters a CPU burn from the real SMC and prints `apple-smc: measured`. A new macOS CI step greps for that line under `--features smc` and `ioreport,smc`. The clippy step lints both configurations. - **The existing IOReport fallback test** now expects the SMC (`ModelBased`) where it's built and live, and the estimator otherwise. Passing: - **M3 Ultra:** `smc`, `ioreport,smc` and `ioreport` (both existing CI greps). Clippy clean in default, `ioreport`, `smc` and `ioreport,smc`. `mesh-meter` with `hw-meter-apple`. - **Linux x86_64:** `rapl,nvml`, default clippy, and `mesh-meter` with `hw-meter-rapl`. This PR is independent of #618 (RAPL MSR fallback); the two touch different lines. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-11-04 20:00:33 -05:00

jouleclaw-energy: a Mac's whole-machine power from the SMC (EnergyDomain::System, ModelBased) ... 45f91fe0f6

On Apple Silicon under macOS 27, IOReport's CPU rails are frozen for an
unprivileged reader, so detect_meter fell back to the load-average estimator:
a guess, graded Estimator. Every Mac still publishes its total power in the SMC
key PSTR, which any process reads through the AppleSMCKeysEndpoint IOKit user
client with no root.

New feature `smc` (macOS), module apple_smc: SmcSystemCounter integrates PSTR
over time.
- Domain: a new EnergyDomain::System, the whole machine (everything its DC
  input feeds: SoC, memory, storage, fans, the rest of the board; not the
  power supply's AC-to-DC loss). It holds SocTotal and every other domain.
- Grade: ModelBased, like NVML's power.draw integral. PSTR is a power reading,
  not an energy counter, so no liveness probe can vouch for its integral.
- Sampling: one thread per process reads PSTR every 100 ms and integrates the
  value it holds, so a figure does not depend on how often its caller reads; a
  read between polls extends the integral at the held value, which the next
  poll integrates over the same time, so readings never run backwards.
- Checks: PSTR must be a 4-byte float and be seen to refresh before the
  counter is available (the first construction waits about a second); samples
  at 0 W or less, above 1.5 kW, or NaN are discarded and counted; a value held
  10 s gives no figure.
- Minimum window 2 s: PSTR refreshes about once a second (median gap 1.0 s on
  an M3 Ultra Mac Studio and an M5 Max MacBook Pro, macOS 27.2) and trails a
  step in load by about one refresh.

detect_meter puts it after a live IOReport counter (a hardware reading over a
narrower domain) and before the load-average estimator. Its figure holds the
work and whatever else the machine powered, so it can read high, never low.
mesh-meter's exhaustive covers_whole_request counts System as covering the
whole request. SPEC 1.3 lists sampled vendor power integrated over time under
ModelBased.

Measured with the energy_probe example (2.5 s CPU churn, unprivileged): the
M3 Ultra Mac Studio 299.9 J, 120.0 W; the M5 Max MacBook Pro on AC 160.9 J,
64.4 W. On the Studio PSTR equals the DC input (PDTR); on the MacBook Pro, on
AC with the battery not charging, it read 51.7 W against 54.9 W at the input.

Tests: the integral, monotonic reads, implausible samples, staleness and the
sampler's start are driven with scripted samples and times; a hardware test
meters a CPU burn from the real SMC and prints "apple-smc: measured", which a
new macOS CI step greps under --features smc and ioreport,smc. The clippy step
lints both. Passing on the M3 Ultra (smc, ioreport,smc, ioreport; clippy clean
in default, ioreport, smc, ioreport,smc; mesh-meter with hw-meter-apple) and on
Linux x86_64 (rapl,nvml; default clippy; mesh-meter with hw-meter-rapl).

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot referenced this pull request 2026-11-04 20:50:16 -05:00

jouledesk-github, Joule Code L3: meter a Mac with the SMC where IOReport is not live (stacked on #622) #624

dcharlot referenced this pull request 2026-11-04 21:30:03 -05:00

mesh-meter: a span shorter than its counter's minimum window is an estimate #630

dcharlot referenced this pull request from a commit 2026-11-04 22:08:38 -05:00

mesh-meter: hw-meter-apple meters a Mac with the SMC's whole-machine power where IOReport is not live

dcharlot referenced this pull request 2026-11-04 22:08:56 -05:00

mesh-meter: hw-meter-apple meters a Mac with the SMC where IOReport is not live (stacked on #622, #630) #631

dcharlot merged commit 097a83ea4e into main 2026-11-05 04:30:59 -05:00

dcharlot referenced this pull request from a commit 2026-11-05 04:31:00 -05:00

Merge pull request 'jouleclaw-energy: a Mac's whole-machine power from the SMC (EnergyDomain::System, ModelBased)' (#622) from jouleclaw-energy/smc-system into main

dcharlot referenced this pull request from a commit 2026-11-05 04:50:34 -05:00

Merge main into mesh-meter/smc (#622 and #630 have landed)

dcharlot referenced this pull request from a commit 2026-11-05 04:52:32 -05:00

Merge pull request 'jouledesk-github, Joule Code L3: meter a Mac with the SMC where IOReport is not live (stacked on #622)' (#624) from jouleclaw-energy/smc-consumers into main

dcharlot referenced this pull request from a commit 2026-11-05 06:13:34 -05:00

Merge pull request 'mesh-meter: hw-meter-apple meters a Mac with the SMC where IOReport is not live (stacked on #622, #630)' (#631) from mesh-meter/smc into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!622

No description provided.