# CPU Power and Thermal Management

MontaukOS manages CPU frequency, idle states, and package temperature on
Intel hardware. Without this, a modern many-core laptop part (the reference
target is a TUXEDO Gemini Gen2 with an i9-13900HX, 24 cores / 32 threads)
runs at whatever P-state the firmware left it, never drops below C1 when
idle, and heats until the hardware throttles at TjMax - or until the
embedded controller intervenes (on Clevo boards: forced full-volume beeping,
then a hard power-off).

Everything below is feature-gated by CPUID, so virtual machines (KVM masks
the power bits in CPUID.06H) and non-Intel CPUs skip it safely.

## Components

### HWP frequency scaling (`Hal/CpuPower.cpp`)

`Hal::CpuPower::InitializeBsp()` enables Hardware P-states
(IA32_PM_ENABLE), reads the performance range from IA32_HWP_CAPABILITIES,
and programs IA32_HWP_REQUEST with:

- min = lowest performance level, max = highest
- desired = 0 (fully autonomous hardware frequency selection)
- EPP = 0x80 (balanced; same as Linux "balance_performance")

This is the same mechanism intel_pstate uses on Linux and is the single
biggest thermal win: the CPU idles near its minimum frequency and ramps
only while there is work. APs apply the same request in `ApEntry` via
`InitializeAp()` (HWP request MSRs are per-logical-CPU).

CPUs with EPB but no HWP get IA32_ENERGY_PERF_BIAS = 6 (balanced) instead.

### C1E promotion

MSR_POWER_CTL bit 1 lets HLT-idle drop core voltage/frequency to minimum
(C1E) instead of parking at the current ratio. Set per-core on the BSP and
every AP. Gated on the DTS CPUID bit as a real-hardware heuristic, because
MSR_POWER_CTL is not architectural and hypervisors may not emulate it.

### Thermal governor (`Hal/CpuPower.cpp`)

A closed-loop passive-cooling controller on the BSP, stepped from
`Sched::RunBspMaintenance()` (reached from both the idle loop and the
timer tick, so it keeps running under full load). Every 500 ms it reads
the package digital thermal sensor (IA32_PACKAGE_THERM_STATUS readout
relative to TjMax from MSR_TEMPERATURE_TARGET) and adjusts the HWP
performance ceiling:

- **>= 85 C (passive):** step the ceiling down 2 ratio units (~200 MHz)
- **>= 94 C (hot):** step down 8 units per interval
- **<= 78 C (resume):** step back up 1 unit per interval
- between resume and passive: hold (hysteresis)

The ceiling propagates through a policy epoch counter: each CPU compares
the epoch in `Sched::Tick()` (and the AP idle loop) against the last one
it applied and rewrites its own IA32_HWP_REQUEST when it changed, since
MSR writes only affect the executing core. APs tick every 10 ms, so a
throttle decision reaches all cores within one tick.

Throttle engage/release transitions are logged (WARNING/OK, "CpuPower").

### Deep AP idle (`ACPI/CpuIdle.cpp`)

APs use deep MWAIT C-states while idle; C6 power-gates the core entirely,
which is where most of the idle-heat win lives on many-core parts.

The hint comes from ACPI `_CST` FFH entries (the GAS address low byte is
the MWAIT hint, same convention as Linux), validated against the CPUID.05H
sub-state enumeration and capped at the C6 family (0x2F). With no usable
`_CST`, the deepest CPUID-enumerated hint (up to C6) is used.

**The BSP stays in C1 (HLT).** On some laptops deep MWAIT states freeze
the LAPIC timer even though ARAT is advertised, and the BSP's periodic
1 ms tick is the system timekeeper (see the comment in
`Timekeeping::IdleOnce`). APs have no timekeeping duty: an idle AP is
woken by the reschedule IPI, and its coarse tick resumes on wake.

### S3 wake

IA32_PM_ENABLE, HWP requests, and MSR_POWER_CTL do not survive suspend.
`Hal::CpuPower::ReapplyAfterWake()` runs in the S3 resume path, redoes the
BSP setup, and bumps the policy epoch so every AP re-applies its HWP
request (and re-checks C1E) on its next tick.

## Diagnostics

`SYS_POWERINFO` (149) fills a `PowerInfo` struct: package temperature,
TjMax, HWP state and performance range, the governor's current ceiling,
CPUID base/turbo frequency, the measured average active frequency
(APERF/MPERF over the 500 ms governor window), and the AP idle MWAIT hint.
Returns -1 when the CPU exposes no power features (e.g. under QEMU).

The `power` program (`programs/src/power`) prints it:

```
power             one-shot snapshot
power watch       1 Hz samples for 60 s (temp, avg freq, ceiling)
power watch 300   same, for 300 s
```

Boot log lines to look for (Kernel Log app):

```
[CpuPower] HWP enabled: perf range 4-54, EPP=0x80
[CpuPower] Thermal governor armed: TjMax=100C, passive=85C, hot=94C, ...
[CpuIdle]  AP deep idle: MWAIT hint 0x20
```

## Tuning

The governor constants live at the top of `Hal/CpuPower.cpp`
(`PassiveTempC`, `HotTempC`, `ResumeTempC`, `GovernorIntervalMs`, step
sizes) and were chosen to keep the package well below both TjMax (100 C
on the i9-13900HX) and the Clevo EC's emergency thresholds. If the fans
still spin up aggressively under sustained load, lower `PassiveTempC`
first; if builds feel throttled while cool, raise the recovery rate
instead of the trip points.