Add powersave_logging/README.md

powersave_logging/README.md

@@ -0,0 +1,234 @@
+# Dokumentation des Powersave- und C-State-Loggings
+
+## Purpose
+
+Dokumentation der Erfassung und Auswertung von Powersave-Zuständen (C-States) zur Beurteilung des Governor-Effekts und dessen Abhängigkeit von C3-Residency.
+
+**Problemstellung:** Unklar war, ob der Governor-bedingte Jitter aus elektrischen Störungen stammt oder durch Aktivität in tiefen CPU-Schlafzuständen (C3) vermittelt wird. Ziel war, über Logging und Aggregation der C-State-Daten diesen Zusammenhang nachzuweisen.
+
+**Ziele:**
+- Präzise Logging- und Analysebasis für C-State-bezogene Outlier-Erkennung schaffen
+- Differenzierung von Effekten zwischen normalem und limitiertem Powersave-Modus ermöglichen
+- Reproduzierbare CSV-Exporte mit allen relevanten Trace-Feldern bereitstellen
+
+## Kontext & Hintergrund
+
+120 Micro-Benchmarks pro Modus (normaler powersave vs. powersave mit C3-Sperre).
+
+**Gruppierung:**
+- normal
+- restricted
+
+**Trace-Metadaten / zusätzliche Tags:**
+- C-State-Residency
+- clocksource_switch Events
+- Outlier-Flag
+- EM-Probe-Daten
+
+**Domänenkontext:**
+- CPU-Governor-Analyse
+- C-State-Transition-Logging
+- BPF-Trace-Datenerhebung
+- Energiemanagementmessungen
+
+**Outlier-Definition:**
+- Methode: Benchmarkabweichung
+- Beschreibung: Runs mit signifikant erhöhter Latenz oder Variabilität gegenüber dem Median
+- Metrik: Outlier-Rate pro Modus in Prozent
+
+**Motivation:**
+- Aufklärung des Zusammenhangs zwischen Governor-Verhalten und C3-Eintritt
+- Eliminierung nicht-elektrischer Einflüsse durch kontrolliertes Power-State-Limit
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Vergleich zweier Powersave-Konfigurationen mit identischer Benchmark-Last.
+- Erfassung von C-State-Residencies, clocksource_switch-Ereignissen und EM-Traces.
+- Bootstrap-Auswertung zur Bestimmung der Vertrauensintervalle und Signifikanz.
+
+**Algorithmen / Verfahren:**
+- pro Modus 120 Benchmarks sammeln
+- C-State-Residency summieren und Outlier markieren
+- Bootstrap-Resampling mit 10.000 Iterationen, 95%-Konfidenzintervall
+- Berechnung der Differenz in Outlier-Proportionen und Risk Ratio
+
+### Bootstrap-Übersicht
+
+Non-parametrisches Resampling zur Abschätzung der Schwankung der Outlier-Rate.
+
+**Zielgrößen:**
+- Differenz der Outlier-Anteile
+- Risk Ratio zwischen Modi
+
+### Resampling-Setup
+
+- normal
+- restricted
+
+**Stichprobeneinheit:** Benchmark-Run
+
+**Resampling-Schema:**
+- 10000-faches Resampling pro Modus
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: percentile
+- Ableitung: durch Bootstrap-Verteilung
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Prozentuale Differenz der Outlier-Raten zwischen beiden Modi.
+- Bootstrap: Zur Abschätzung der Unsicherheit des Effekts.
+
+**Risk Ratio:**
+- Definition: Verhältnis der Outlier-Wahrscheinlichkeit im normalen gegenüber restringiertem Modus.
+- Bootstrap: 95%-CI aus Bootstrap-Sampling.
+
+### C-State-Kontrolle
+
+**Ziel:** Einfluss tiefer C-States auf den Governor-Effekt prüfen.
+
+**Vorgehen:**
+- C3-Zugriff über Kernelparameter intel_idle.max_cstate=1 einschränken
+- Residency-Verteilungen vergleichen
+- Auswirkung auf clocksource_switch-Frequenz beobachten
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Intel-basierte CPU mit Idle-States bis C3
+- EM-Probe
+- Referenz-Benchmark-Rig
+
+**Software:**
+- Linux-Kernel mit BPF-Support
+- trace_agg.py
+- Shell-/Python-Umgebung
+
+**Konfiguration:**
+- intel_idle.max_cstate=1 oder höher
+- aktive BPF-Traces auf clocksource_switch
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- mode
+- outlier_flag
+- c0_time
+- c1_time
+- c3_time
+- clocksource_switch_count
+- em_trace_sum
+
+**Formatbeispiele:**
+- normal,42,False,81.2,15.4,3.4,15,0.98
+
+**Trace-Daten:**
+- Format: CSV aus trace_agg.py
+- Hinweis: Spaltenbezeichner müssen exakt dem im Repository definierten Schema folgen
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- C3-Residency-Mittelwert
+- Outlier-Anteil
+- CI-Grenzen
+
+**Vergleichsausgaben:**
+- normal vs restricted
+  - Δ: -18.3%
+  - CI(Δ): [3.1, 11.8]
+  - RR: ≈3.7
+  - CI(RR): [2.0, 8.4]
+  - Tests: ≈0.002
+
+- C-State-Korrelation: starke positive Korrelation zwischen hoher C3-Residency und Outlier-Häufigkeit
+- Trace-Muster: clocksource_switch-Events korrelieren mit Outlier-Phasen
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Benchmarks ausführen unter normalem und limitiertem Powersave
+- Traces erfassen (BPF, EM, C-State)
+- trace_agg.py zur Aggregation verwenden
+- Bootstrap-Analyse der Resultate ausführen
+- Vergleich der Resultate dokumentieren
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Standardisierte Traces für Replikation und Vergleich ermöglichen.
+
+**Erforderliche Tags & Metadaten:**
+- mode
+- run_id
+- c_state_times
+- outlier_flag
+- clocksource_switch_count
+
+**trace-cmd-Setup:**
+- bpftrace -e 'tracepoint:power:cpu_idle { ... }'
+- Aufzeichnungszeit synchronisieren
+
+**Run-Design für Contributors:**
+- mindestens 100 Testläufe pro Konfiguration
+- identische Benchmark-Workload verwenden
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Outlier-Rate sinkt drastisch, sobald C3 gesperrt ist.
+- C3-Residency korreliert mit Jitter-Ausreißern.
+- clocksource_switch-Events treten im eingeschränkten Modus kaum auf.
+
+**Implikationen für Experimente:**
+- Governor-Verhalten stark durch tiefe Idle-States beeinflusst.
+- Reproduktion ohne elektrische Einflussfaktoren möglich.
+- C-State-Begrenzung als Kontrollvariable für Governor-Vergleiche geeignet.
+
+**Planungsziel:**
+- Ziel: Nachweis des CPU-internen Ursprungs des Governor-Effekts.
+- Vorgehen:
+  - systematische Sperrung von C3
+  - Erhebung und Aggregation aller Trace-Daten mit trace_agg.py
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Outlier-Definition abhängig von Benchmark-Charakteristik
+- BPF-Trace-Zeitauflösung begrenzend für feine Latenzen
+
+**Bootstrap-spezifische Limitationen:**
+- Annahmen zu Unabhängigkeit zwischen Runs erforderlich
+- geringe Stichprobenzahlen können CI verbreitern
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnisse primär für Intel Idle-Governor gültig
+- Übertragbarkeit auf ARM- oder AMD-Plattformen unbestätigt
+
+**Praktische Fallstricke:**
+- unkonsistente Trace-Formate verhindern Aggregation
+- fehlende Metadata (Spacer, Hardware) limitieren Vergleichbarkeit
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Langzeitvergleich über 24 h zwischen performance und powersave+C0/C1
+- Spacer-Sweep-Test (0 → 0,5 → 1 mm)
+- Unit-Test-Integration für trace_agg.py
+
+**Analyseziele:**
+- Validierung der Stabilität des Governor-Clocksource-Offsets
+- Quantifizierung der Outlier-Stabilität über Zeit
+
+**Regression & Modellierung:**
+- Modellierung der C-State-Auswirkungen auf Latenzverteilung
+- Vorbereitung linearer Mixed-Effects-Modelle für Governor-Zustände
+
+**Community-Beiträge:**
+- Einreichen von Remote-Traces unter intel_idle.max_cstate=1
+- Bereitstellung von Hardware- und Spacer-Metadaten zur Meta-Analyse