RedBear-OS/local/docs/RAPL-IMPLEMENTATION-PLAN.md

# RedBear OS RAPL Power Monitoring — Comprehensive Implementation Plan

**Version:** 1.1 (2026-06-28)
**Status:** Draft — awaiting review
**Linux Reference:** `local/reference/linux-7.1/drivers/powercap/`

## P0 Blocker: Kernel MSR Scheme Does Not Exist

**The `/scheme/sys/msr/{cpu}/0x{msr_hex}` path used by `redbear-power` and
`cpufreqd` is NOT implemented in the kernel.** The kernel's `sys:` scheme handler
has modules for `cpu`, `exe`, `irq`, `block`, `syscall`, `context`, `uname`,
`fdstat`, `iostat`, `log`, `stat` — but NO `msr` module. The kernel uses
`rdmsr`/`wrmsr` internally (via the x86 crate) but never exposes MSRs to userspace.

This is the single blocking gap for ALL RAPL work. Without it:
- `read_msr(0x611)` returns `None` on bare-metal Redox
- `redbear-power` can only read RAPL on Linux hosts via sysfs or `/dev/cpu/*/msr`
- `cpufreqd` cannot write `IA32_PERF_CTL` on Redox bare metal
- `thermald` cannot read thermal status MSRs

**Resolution options (pick one before Phase 1):**
1. **Kernel `sys:msr` handler** — Add `src/scheme/sys/msr.rs` to kernel, expose as `/scheme/sys/msr/{cpu}/0x{msr_hex}`. Requires `CAP_SYS_MSR`.
2. **Userspace `msrd` daemon** — Register `scheme:msr` via `redox-scheme`. More portable, easier to iterate, no kernel rebuild.
3. **Linux-compatible `/dev/cpu/*/msr` device** — Matches what `thermald` already uses. Requires VFS-level char device emulation.

**Recommendation:** Option 2 (userspace daemon). It's the fastest path,
doesn't require kernel changes, and can use `iopl(3)` + `inl`/`outl` for
x86 port-based MSR access, or the `x86` crate's `rdmsr` if ring0 access
is available through a capability scheme.

## Executive Summary

Implement hardware-accurate CPU/package/DRAM power monitoring in RedBear OS
using the Intel RAPL (Running Average Power Limit) and AMD energy counter MSRs.
This replaces the current `redbear-power` approach of relying on P-state table
power estimates (static, inaccurate) and sysfs powercap fallback (Linux-only).

**Total scope:** 3 phases, ~8-12 weeks with 1 developer.
**Prerequisite:** Redox MSR scheme (`/scheme/sys/msr/`) — already functional.

---

## 1. RAPL Architecture (what we're implementing)

### 1.1 Power Domains

Intel RAPL exposes energy counters for 5 domains:

| Domain | MSR (read) | Description | Typical accuracy |
|--------|-----------|-------------|------------------|
| **PKG** (package) | `0x611` | Entire CPU socket/package power | ±2-5% |
| **PP0** (core) | `0x639` | All CPU cores collectively | ±5-10% |
| **PP1** (graphics) | `0x641` | GPU uncore (client CPUs only) | N/A on server |
| **DRAM** | `0x619` | DRAM controller power | ±10-20% |
| **PSys** (platform) | `0x64D` | Entire platform (CPU + PCH + VR losses) | ±5-15% |

Not all domains are available on all CPUs. Server CPUs typically have PKG + DRAM.
Client CPUs typically have PKG + PP0 + PP1. PSys is rare (some server platforms).

### 1.2 Energy Counter Semantics

```
Energy (µJ) = RAW_COUNTER × ENERGY_UNIT

where ENERGY_UNIT = 1.0 / (2 ^ exponent)
      exponent   = (MSR_RAPL_POWER_UNIT >> 8) & 0x1F
```

- **32-bit counter** at each MSR, monotonically increasing
- **Wraps at** 2^32 (at 100W with 15.3µJ unit: ~60 seconds for package, ~days for per-core)
- **Linux mitigation:** hrtimer polls every ~2.5ms to accumulate into 64-bit software counters
  before the 32-bit hardware counter wraps (overflow detection via `max_energy_range_uj`)
- **Read semantics:** poll at interval Δt, compute P = ΔE/Δt
- **Zero overhead:** reads are just an MSR `RDMSR` instruction (~20-50 cycles)

### 1.3 Unit Register (MSR 0x606)

```
MSR_RAPL_POWER_UNIT (0x606):
  Bits [3:0]   — Power unit (Watts = RAW × 2^-exponent)
  Bits [12:8]  — Energy unit (Joules = RAW × 2^-exponent)  
  Bits [19:16] — Time unit (Seconds = RAW × 2^-exponent)

Default values (Sandy Bridge through Alder Lake):
  Power unit:  0.125 W  (exponent = 3)
  Energy unit: 15.3 µJ  (exponent = 16)
  Time unit:   976 µs   (exponent = 10)
```

### 1.4 AMD Energy Counters

AMD Zen 2+ (Family 17h+, Model 30h+) exposes RAPL-compatible MSRs at the SAME
addresses as Intel but with a different unit register:

- `MSR_AMD_RAPL_POWER_UNIT` = `0xC0010299` (AMD-specific unit register)
- Energy counter MSRs at same addresses (`0x611`, `0x619`, `0x639`, `0x641`)
- PKG domain always available on Zen 2+
- PP0 (core) available on Zen 2+  
- No DRAM or PSys on most AMD platforms
- Unit conversion: AMD uses `(raw >> 8) & 0x1F` for energy exponent (same bit layout)

---

## 2. Implementation Plan

### Phase 1: Core RAPL Reader (4-6 weeks)

**Goal:** A userspace daemon (`rapld`) that reads RAPL energy counters and exposes
them through a scheme for consumption by `redbear-power`.

#### 1.1 MSR Access Layer (`local/recipes/drivers/redox-driver-sys/source/src/`)

Add RAPL MSR constants and read helpers to `redox-driver-sys`:

```rust
// New file: src/rapl.rs or extend src/msr.rs

pub const MSR_RAPL_POWER_UNIT: u32 = 0x606;
pub const MSR_PKG_ENERGY_STATUS: u32 = 0x611;
pub const MSR_PKG_PERF_STATUS: u32 = 0x613;
pub const MSR_PKG_POWER_INFO: u32 = 0x614;
pub const MSR_DRAM_ENERGY_STATUS: u32 = 0x619;
pub const MSR_PP0_ENERGY_STATUS: u32 = 0x639;
pub const MSR_PP1_ENERGY_STATUS: u32 = 0x641;
pub const MSR_PLATFORM_ENERGY_STATUS: u32 = 0x64D;
pub const MSR_AMD_RAPL_POWER_UNIT: u32 = 0xC0010299;

pub struct RaplUnit {
    pub power_exponent: u8,   // bits 3:0
    pub energy_exponent: u8,  // bits 12:8
    pub time_exponent: u8,    // bits 19:16
}

pub struct RaplDomain {
    pub name: &'static str,
    pub energy_msr: u32,
    pub last_energy: u64,
    pub last_timestamp: Instant,
    pub power_w: f64,          // computed: ΔE/Δt
    pub available: bool,
}

pub struct RaplPackage {
    pub id: u32,
    pub units: RaplUnit,
    pub domains: Vec<RaplDomain>,
}
```

**Key functions:**
- `rapl_read_unit(lead_cpu: u32) -> Option<RaplUnit>` — reads MSR 0x606 (or 0xC0010299 on AMD)
- `rapl_read_energy(lead_cpu: u32, msr: u32) -> Option<u64>` — reads 32-bit energy counter
- `rapl_detect_domains(cpu: u32, unit: &RaplUnit) -> Vec<RaplDomain>` — probe which MSRs exist
- `rapl_compute_power(domain: &mut RaplDomain, interval: Duration) -> f64` — ΔE/Δt

**AMD detection:** Use CPUID vendor string. If `AuthenticAMD`:
- Use `MSR_AMD_RAPL_POWER_UNIT` instead of `MSR_RAPL_POWER_UNIT`
- MSR 0x611 (PKG) available on Zen 2+ (Family >= 0x17)
- MSR 0x639 (PP0/core) available on Zen 2+
- DRAM/PSys typically absent

**Error handling (crucial for heterogeneous hardware):**
- Attempt to read each MSR; if `#GP(0)` → domain unavailable → mark `available = false`
- On QEMU: RAPL MSRs are typically unimplemented → graceful degradation
- On virtualized guests: RAPL may be passed through or absent → check before assuming
- Wrap detection: if `current < previous` → counter wrapped → `ΔE = (2^32 - prev) + current`

#### 1.2 rapld Daemon (`local/recipes/system/rapld/`)

**Architecture:**
```
rapld (userspace daemon, Rust)
├── MSR polling (every 500ms default, configurable)
├── Energy-to-power delta computation
├── Per-domain statistics (avg, max, min over sliding window)
├── Scheme registration: scheme:power or scheme:rapl
└── Optional D-Bus export for desktop integration
```

**Scheme paths:**
```
/scheme/rapl/package/0/power_w       — current package power in watts
/scheme/rapl/package/0/energy_uj     — cumulative energy in µJ
/scheme/rapl/package/0/max_w         — max observed power
/scheme/rapl/package/0/avg_w         — average over sliding window
/scheme/rapl/core/0/power_w          — PP0 (core) power
/scheme/rapl/dram/0/power_w          — DRAM power
/scheme/rapl/units                   — unit coefficients
```

**Polling cadence:**
- Default 500ms (matches redbear-power refresh rate)
- Configurable via `/scheme/rapl/interval_ms`
- Adaptive: can speed up during high load, slow down during idle

#### 1.3 redbear-power Integration

Modify `local/recipes/system/redbear-power/source/src/` to use rapld data:

1. **Add `rapl_available` flag** to platform probe: try reading `/scheme/rapl/package/0/power_w`
2. **Replace RAPL sysfs fallback** with scheme read:
   ```rust
   // Before: read_rapl_package_energy() → /sys/class/powercap/...
   // After:  read("/scheme/rapl/package/0/power_w") → f64
   ```
3. **Add per-domain display** to System/Info tabs:
   - Package power: always shown
   - Core power: shown if available
   - DRAM power: shown if available
4. **Use `energy_uj` for more accurate power** when available (avoid double-read of power_w + scheme)

**Fallback chain (Linux host):**
```
1. /scheme/rapl/package/0/power_w          (rapld — Redox native)
2. /sys/class/powercap/intel-rapl:0/energy_uj  (RAPL sysfs — current implementation)
3. MSR direct read via /dev/cpu/*/msr           (existing MSR path)
4. P-state table power estimate                  (current fallback, inaccurate)
```

**Fallback chain (bare metal Redox):**
```
1. /scheme/rapl/package/0/power_w    (rapld)
2. MSR direct read via /scheme/sys/msr/ (existing MSR scheme)
3. P-state table power estimate
```

---

### Phase 2: Power Limiting & Thermal Integration (4-6 weeks)

**Goal:** Expose RAPL power limits for read/write and integrate with thermald.

#### 2.1 Power Limit Registers

| Register | MSR | Bits | Description |
|----------|-----|------|-------------|
| PKG_POWER_LIMIT | 0x610 | [14:0] PL1, [46:32] PL2 | Package long/short-term power limits |
| PP0_POWER_LIMIT | 0x638 | [14:0] PL1 | Core power limit |
| PL1_ENABLE | — | Bit 15 | Enable PL1 enforcement |
| PL1_CLAMP | — | Bit 16 | Allow frequency clamping below OS request |
| TIME_WINDOW1 | — | [23:17] | PL1 averaging window (in time units) |
| POWER_LIMIT_LOCK | — | Bit 63 | Hardware lock (write-once) |

#### 2.2 rapld Power Limit Extension

Add scheme paths for power limit control:
```
/scheme/rapl/package/0/limit1_w         — PL1 (long-term) power limit in watts (RW)
/scheme/rapl/package/0/limit2_w         — PL2 (short-term) power limit in watts (RW)
/scheme/rapl/package/0/time_window1_s   — PL1 time window in seconds (RW)
/scheme/rapl/package/0/locked           — true if limits are hardware-locked (RO)
```

**Safety guards:**
- CAP_SYS_MSR required for writes
- Validate against `PKG_POWER_INFO` (max/min power, max time window)
- Never write below `THERMAL_SPEC_POWER` unless explicitly forced
- Log all limit changes

#### 2.3 thermald Integration

Modify `thermald` (already exists in base drivers) to:
1. Read current package power from `/scheme/rapl/package/0/power_w`
2. If power exceeds configurable threshold (default: TDP), lower P-state or trigger PL1 clamp
3. Use `energy_uj` counter for accurate long-term energy accounting
4. Expose thermal + power budget decisions via scheme

**Integration point:** thermald already reads `/scheme/thermal` for temperature.
Add `/scheme/rapl/` as a secondary data source for power-aware throttling.

---

### Phase 3: redbear-power Full Integration (2-4 weeks)

**Goal:** Complete redbear-power RAPL integration with real-time power graphs.

#### 3.1 Per-CPU Power Column

The current `PkgW` column shows P-state power estimate (or n/a). Replace with:
```
  CPU   Freq/MHz  PkgW(W)  CoreW(W)  DRAM(W)  Temp°C
▶ E0    2436      65.2      42.1      8.3      67
```

**Data flow:**
```
rapld (polls MSR 0x611 every 500ms)
  → writes to /scheme/rapl/package/0/power_w
    → redbear-power reads scheme (one syscall per refresh, not per-CPU)
      → displays single PKG value replicated across all CPU rows
```

Package power is socket-wide, so the value is the same for all CPU rows but
the column stays for visual consistency. Core power (PP0) can be shown as
a per-package aggregate or normalized per-core.

#### 3.2 Power History Graph

Add a mini sparkline for package power (like the load sparkline):
```
PkgW(W) History (30s)
████▇▇▆▅▅▄▄▃ 65.2
```

Store last 30 samples of power_w in a `VecDeque<f64>` and render as Unicode
block characters, normalized against max observed power.

#### 3.3 System Tab Power Summary

Add to the System tab:
```
Power:
  Package:  65.2 W (avg: 58.1, max: 89.4)
  Cores:    42.1 W (avg: 38.2, max: 55.0)
  DRAM:      8.3 W
  Limit PL1: 95 W (TDP)
  Limit PL2: 125 W (boost)
```

---

## 3. CPU Support Matrix

### 3.1 Intel

| Generation | Arch | PKG | PP0 | PP1 | DRAM | PSys | Notes |
|------------|------|-----|-----|-----|------|------|-------|
| Sandy Bridge (2nd) | SNB | ✅ | ✅ | ❌ | ❌ | ❌ | First RAPL implementation |
| Ivy Bridge (3rd) | IVB | ✅ | ✅ | ❌ | ❌ | ❌ | |
| Haswell (4th) | HSW | ✅ | ✅ | ✅ | ✅ | ❌ | Client: PKG+PP0+PP1, Server: PKG+DRAM |
| Broadwell (5th) | BDW | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Skylake (6th) | SKL | ✅ | ✅ | ✅ | ✅ | ✅ | PSys on server only |
| Kaby Lake (7th) | KBL | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Coffee Lake (8-9th) | CFL | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Comet Lake (10th) | CML | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Ice Lake (10th) | ICL | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Tiger Lake (11th) | TGL | ✅ | ✅ | ✅ | ✅ | ❌ | |
| Alder Lake (12th) | ADL | ✅ | ✅ | ✅ | ✅ | ✅ | Hybrid: PKG covers P+E cores |
| Raptor Lake (13-14th) | RPL | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Meteor Lake (Ultra) | MTL | ✅ | ✅ | ❌ | ✅ | ❌ | New SoC architecture |
| Sapphire Rapids | SPR | ✅ | ✅ | ❌ | ✅ | ✅ | Server: different PL bit layout |

### 3.2 AMD

| Generation | Family | PKG | PP0 | Notes |
|------------|--------|-----|-----|-------|
| Zen 1 (Ryzen 1000) | 17h | ❌ | ❌ | No RAPL support |
| Zen+ (Ryzen 2000) | 17h | ❌ | ❌ | |
| Zen 2 (Ryzen 3000) | 17h | ✅ | ✅ | RAPL via MSR 0x611/0x639 |
| Zen 3 (Ryzen 5000) | 19h | ✅ | ✅ | |
| Zen 4 (Ryzen 7000) | 19h | ✅ | ✅ | |
| Zen 5 (Ryzen 9000) | 1Ah | ✅ | ✅ | |

AMD uses `MSR_AMD_RAPL_POWER_UNIT` (0xC0010299) for unit conversion instead
of Intel's `MSR_RAPL_POWER_UNIT` (0x606). Energy counter MSR addresses are
the same as Intel.

**⚠️ Critical AMD vs Intel difference**: AMD reports core energy **per-core**
(MSR 0xC001029A), while Intel reports PP0 as **all-cores aggregate** (MSR 0x639).
This means AMD core energy must be summed across all cores to get equivalent
PP0 data, while Intel returns the total directly. The `amd_energy` driver on
Linux runs a kernel thread every 100 seconds to accumulate per-core counters
into 64-bit software counters to handle 32-bit wrap-around.

### 3.3 QEMU / Virtualized

- QEMU: RAPL MSRs typically unimplemented → **#GP(0)** → graceful "n/a"
- KVM with `-overcommit cpu-pm=on`: may expose RAPL to guest (rare)
- VMware/Hyper-V: no RAPL passthrough known

**Detection strategy:** Try reading MSR 0x611 from CPU 0. If it returns an error
(#GP fault), RAPL is unavailable. Cache this result so subsequent reads skip
the MSR access entirely.

---

## 4. File Layout & Implementation Order

### New files to create:

```
local/recipes/drivers/redox-driver-sys/source/src/rapl.rs     ← RAPL MSR constants + read primitives
local/recipes/system/rapld/                                    ← New RAPL daemon
local/recipes/system/rapld/recipe.toml                        ← Cargo template, depends: redox-driver-sys
local/recipes/system/rapld/source/Cargo.toml                  
local/recipes/system/rapld/source/src/main.rs                 ← Daemon: poll MSRs, serve scheme
local/recipes/system/rapld/source/src/units.rs                ← Unit conversion (power/energy/time)
local/recipes/system/rapld/source/src/domains.rs              ← Domain detection + power computation
local/recipes/system/rapld/source/src/scheme.rs               ← Scheme:power handler
local/docs/RAPL-IMPLEMENTATION-PLAN.md                        ← This document

local/recipes/system/redbear-power/source/src/rapl.rs         ← RAPL integration for redbear-power
```

### Files to modify:

```
local/recipes/system/redbear-power/source/src/acpi.rs         ← Replace read_rapl_package_energy()
local/recipes/system/redbear-power/source/src/app.rs          ← Add rapl_domains, pkg_power_w from scheme
local/recipes/system/redbear-power/source/src/render.rs       ← Add CoreW/DRAM columns, power history
local/recipes/system/redbear-power/source/src/main.rs         ← Wire keybindings for power view
config/redbear-full.toml                                       ← Add rapld to [packages]
config/redbear-mini.toml                                       ← Optionally add rapld
```

### Implementation order:

1. **Week 1-2:** `rapl.rs` in redox-driver-sys — MSR constants, read/write primitives, unit parsing
2. **Week 3-4:** `rapld` daemon — scheme server, domain detection, energy polling
3. **Week 5-6:** redbear-power integration — scheme reader, per-domain columns, power history
4. **Week 7-8:** Power limiting + thermald integration (Phase 2)
5. **Week 9-12:** Testing on real hardware (Intel + AMD), QEMU graceful degradation, polish

---

## 5. Testing Strategy

### 5.1 Unit Tests (host, no hardware needed)

```rust
// Test unit conversion from known MSR values
fn test_rapl_unit_parsing() {
    // MSR_RAPL_POWER_UNIT = 0x000A1003
    // Power exponent = 3, Energy exponent = 0x10 = 16, Time exponent = 0xA = 10
    let unit = RaplUnit::from_msr(0x000A1003);
    assert_eq!(unit.power_exponent, 3);
    assert_eq!(unit.energy_exponent, 16);
    assert_eq!(unit.time_exponent, 10);
}

// Test energy-to-power conversion
fn test_energy_delta() {
    let prev = (1_000_000u64, Instant::now() - Duration::from_secs(1));
    let curr = (1_065_200u64, Instant::now());
    // ΔE = 65200 µJ over ~1 second = 65.2 W
    let (w, _) = rapl_power_watts(curr, prev);
    assert!((w - 65.2).abs() < 0.1);
}

// Test counter wrap
fn test_energy_wrap() {
    let prev = (0xFFFF_FFF0u64, Instant::now() - Duration::from_secs(1));
    let curr = (0x0000_0010u64, Instant::now());
    // ΔE = (2^32 - 0xFFFFFFF0) + 0x10 = 16 + 16 = 32 µJ
    let (w, _) = rapl_power_watts_wrap(curr, prev);
    assert!(w > 0.0);
}
```

### 5.2 Integration Tests (QEMU)

```bash
# Test graceful degradation when RAPL unavailable (QEMU default)
make qemu CONFIG_NAME=redbear-full
# Inside guest: rapld should start, detect no RAPL, serve scheme with "n/a"
cat /scheme/rapl/package/0/power_w  # Expected: "unavailable\n"

# Test with RAPL-capable host (bare metal only)
# On bare metal Intel/AMD:
cat /scheme/rapl/package/0/power_w  # Expected: "65.2\n" (or similar)
```

### 5.3 Hardware Validation Matrix

| Platform | CPU | RAPL domains expected |
|----------|-----|----------------------|
| Desktop Intel 12th-gen | i5-12600K | PKG, PP0, PP1, DRAM |
| Desktop Intel 13th-gen | i9-13900K | PKG, PP0, PP1, DRAM |
| Laptop Intel 11th-gen | i7-1165G7 | PKG, PP0, PP1, DRAM |
| Desktop AMD Zen 3 | Ryzen 5950X | PKG, PP0 |
| Desktop AMD Zen 4 | Ryzen 7950X | PKG, PP0 |
| Server Intel Xeon | SPR | PKG, PP0, DRAM, PSys |
| QEMU (any) | — | None (graceful n/a) |

---

## 6. Risks & Mitigations

| Risk | Likelihood | Mitigation |
|------|-----------|------------|
| MSR #GP fault on unsupported CPU | High | Catch fault, mark domain unavailable, cache decision |
| Energy counter wraps between polls | Low (60s at 100W) | Wrap detection in delta computation |
| Multi-socket power aggregation wrong | Medium | Per-package MSR reads on lead CPU of each package |
| AMD energy unit different from Intel | High | Auto-detect via CPUID vendor, use correct unit MSR |
| Kernel MSR scheme latency | Medium | Batch reads (read all domains in one scheme transaction) |
| Power limit writes brick hardware | Low | Validate against PKG_POWER_INFO; never write below THERMAL_SPEC |
| thermald + rapld race on MSR writes | Low | rapld owns energy reads; thermald owns limit writes; use scheme as synchronization point |

---

## 7. References

### Linux Kernel Source (local/reference/linux-7.1/)

| File | Lines | Content |
|------|-------|---------|
| `include/linux/intel_rapl.h` | 269 | Core data structures, domain/primitive enums |
| `drivers/powercap/intel_rapl_common.c` | ~2000 | Domain definitions, powercap zone registration, energy read |
| `drivers/powercap/intel_rapl_msr.c` | 602 | MSR-based RAPL access (most CPUs use this) |
| `drivers/powercap/intel_rapl_tpmi.c` | ~300 | TPMI-based RAPL (newer Intel platforms) |
| `drivers/powercap/powercap_sys.c` | ~600 | Powercap framework (sysfs interface) |
| `arch/x86/include/asm/msr-index.h` | L490-522 | MSR address definitions |
| `arch/x86/events/rapl.c` | ~800 | Perf events RAPL PMU |

### Intel Documentation

- Intel SDM Volume 3, Chapter 14.9: "Running Average Power Limit (RAPL)"
- Intel SDM Volume 4: MSR definitions (0x606, 0x610-0x619, 0x638-0x641, 0x64D)

### Existing RedBear Infrastructure

| File | Content |
|------|---------|
| `local/recipes/system/redbear-power/source/src/msr.rs` | MSR read/write via `/scheme/sys/msr/` + `/dev/cpu/*/msr` |
| `local/recipes/system/redbear-power/source/src/acpi.rs` | `read_rapl_package_energy()` — current sysfs fallback |
| `local/recipes/system/redbear-power/source/src/app.rs` | `pkg_power_w`, `rapl_prev` — current RAPL state |
| `local/recipes/system/redbear-power/source/src/platform.rs` | Platform probe (Redox vs Linux MSR backend selection) |
| `local/recipes/system/cpufreqd/source/src/main.rs` | MSR 0x199 writes via `/scheme/sys/msr/` |
| `local/recipes/system/thermald/source/src/main.rs` | MSR 0x19C/0x1A2 via Linux `/dev/cpu/*/msr` only |

### External References

| Source | Key Insight |
|--------|------------|
| Intel SDM Vol.3B §14.9 | Domain hierarchy, unit register layout, power limit semantics |
| Intel SDM Vol.4 | All MSR addresses (0x606-0x64D) and bit-field definitions |
| Fuchsia RFC-0203 | Microkernel energy monitoring via `zx_system_energy_info()` syscall — kernel owns MSR access, userspace gets cooked µJ values |
| Schöne et al. 2021 | AMD Zen 2 RAPL accuracy analysis: package domain ±5%, 1ms update rate |
| `rapl-read.c` (deater/uarch-configure) | Reference userspace RAPL reader: unit parsing, counter wrap detection |
| AMD `amd_energy` driver README | Per-core accumulation thread, 100s wake interval, SMT dedup |

---

## 8. Deliverables

| Phase | Deliverable | Success Criteria |
|-------|------------|------------------|
| 1 | `rapld` daemon serving `/scheme/rapl/` | Reads PKG energy on real Intel/AMD hardware, serves power in watts |
| 1 | redbear-power reads from rapld | PkgW column shows real hardware power (not n/a) on supported CPUs |
| 1 | Graceful degradation on QEMU | RAPL domain "unavailable" instead of crash |
| 2 | Power limit read/write | `/scheme/rapl/package/0/limit1_w` returns TDP; writable with CAP_SYS_MSR |
| 2 | thermald power-aware throttling | thermald reads RAPL power, throttles when exceeding configurable threshold |
| 3 | redbear-power multi-domain display | PKG, Core, DRAM columns with real values |
| 3 | Power history sparkline | 30-sample power history visible in Per-CPU tab |