diff --git a/bpf_instrumentation/README.md b/bpf_instrumentation/README.md
new file mode 100644
index 0000000..8011a30
--- /dev/null
+++ b/bpf_instrumentation/README.md
@@ -0,0 +1,227 @@
+# Dokumentation der eBPF-Instrumentierung zur Analyse des konstanten Offset-Verhaltens in Clocksource-Traces
+
+## Purpose
+
+Dokumentation der eingesetzten eBPF-Instrumentierung zur Analyse und Reproduktion eines konstanten Offsets von 1,111 s in Kernel-Trace-Daten.
+
+**Problemstellung:** In BPF-Trace-Daten wurde ein konstanter ≈1,111 s‑Offset beobachtet. Ziel ist, die Quelle dieses Offsets innerhalb des Kernelzeitpfads nachzuweisen.
+
+**Ziele:**
+- Erfassung präziser Traces für do_clocksource_switch, read und baseline_recalc
+- Identifizierung des Zeitabschnitts, in dem der konstante Offset entsteht
+- Validierung durch Vergleich von Host und VM mit GPS‑1PPS als Referenz
+
+## Kontext & Hintergrund
+
+300 Runs pro Session, high-resolution time_ns-Timestamps und GPS‑1PPS‑Referenzsignale; Traces gesammelt mit eBPF-Probes an Kernel‑Funktionen.
+
+**Gruppierung:**
+- Hostsystem
+- virtuelle Maschine (KVM)
+
+**Trace-Metadaten / zusätzliche Tags:**
+- Session-ID
+- Probe timestamps
+- Delta-Chains (Entry→first_read, first_read→baseline_recalc)
+
+**Domänenkontext:**
+- Kernel-Timing
+- Clocksource-Mechanismus
+- eBPF-Tracing
+- Zeitabweichungsdiagnose
+
+**Outlier-Definition:**
+- Methode: Standardabweichung der Delta-Kette
+- Beschreibung: Runs mit mehr als ±3σ Abweichung vom Median gelten als Ausreißer und werden verworfen.
+- Metrik: Δ(do_clocksource_switch_entry → first_read)
+
+**Motivation:**
+- Reproduzierbarkeit der Zeitpfade zwischen Host und VM sicherstellen
+- Verifikation der Stabilität von eBPF gegenüber kprobe-basierten Messungen
+- Eingrenzen, ob Scheduling oder Virtualisierung den Offset verursacht
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Erfassung der Traces mittels eBPF entry/exit‑Probes an do_clocksource_switch, clocksource->read() und baseline_recalc
+- Auswertung mit Python-Skript trace_agg.py zur Bildung von Delta‑Ketten
+- Vergleich der Host‑ und VM‑Messungen für Stabilität und Offsetverhalten
+
+**Algorithmen / Verfahren:**
+- Zeitstempelung aller Probes mit time_ns
+- Berechnung von Δ(entry→first_read) und Δ(first_read→baseline_recalc)
+- Bestimmung von Median und Varianz pro Session
+- Bootstrap‑Resampling über 300 Runs zur Stabilitätsanalyse
+
+### Bootstrap-Übersicht
+
+Nichtparametrisches Bootstrap über Run‑Mittelwerte, 300 Stichproben pro Umgebung.
+
+**Zielgrößen:**
+- Median‑Stabilität
+- Varianz‑Abschätzung
+- Konfidenzintervalle der Delta‑Kette
+
+### Resampling-Setup
+
+- Hostsystem
+- VM (KVM)
+
+**Stichprobeneinheit:** Einzelne Trace‑Sessions mit vollständiger Delta‑Kette
+
+**Resampling-Schema:**
+- Bootstrap mit Zurücklegen
+- B=500 Wiederholungen
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: Percentile Bootstrap CI
+- Ableitung: Quantilbasiert aus resample‑Verteilung
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Nicht zutreffend für zeitkontinuierliche Metriken
+
+**Risk Ratio:**
+- Definition: Nicht relevant — es wird kein Dichotomie‑Outcome analysiert
+
+### C-State-Kontrolle
+
+**Ziel:** Überprüfung, ob CPU‑Schlafzustände (C‑States) den Offset beeinflussen.
+
+**Vorgehen:**
+- Tests mit intel_idle.max_cstate=1 auf Host und VM
+- Vergleich der Δ(entry→first_read)‑Verteilungen
+- Bewertung der Varianzänderung bei konstant bleibendem Median
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- x86_64 Hostsystem mit aktivierbarem KVM
+- GPS‑1PPS‑Signalquelle
+
+**Software:**
+- Linux Kernel ≥5.x mit eBPF-Unterstützung
+- bcc/eBPF‑Toolchain
+- Python ≥3.8 mit Pandas/Numpy
+
+**Konfiguration:**
+- root-Zugriff für eBPF‑Probes
+- Symbolzugriff auf Kernel‑Funktionen
+- synchrone System‑Clocks (chronyd oder ptp4l)
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp_ns
+- probe_name
+- session_id
+- cpu_id
+- delta_chain_id
+
+**Formatbeispiele:**
+- 171223.534912180 do_clocksource_switch_entry
+- 171224.645912321 first_read
+
+**Trace-Daten:**
+- Format: CSV oder JSON‑Lines mit Nanosekundenauflösung
+- Hinweis: Jede Kette wird in der Aggregationsstufe zu einer Delta‑Kombination (entry→first_read etc.) verdichtet.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Median‑Δ
+- Standardabweichung
+- Bootstrap‑Konfidenzintervall
+
+**Vergleichsausgaben:**
+- Hostsystem vs VM
+
+- C-State-Korrelation: Negativ, keine signifikante Abhängigkeit zum Offset erkannt.
+- Trace-Muster: Stabile 1,111 s‑Kette in beiden Umgebungen; kein Anstieg der Varianz außer in I/O‑Phasen.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- eBPF‑Probes deployen (entry/exit‑Hooks an Ziel‑Funktionen)
+- Traces aufnehmen über 300 Runs pro Umgebung
+- trace_agg.py ausführen zur Delta‑Berechnung
+- Ergebnisse aggregieren und mit GPS‑1PPS synchronisieren
+- Bootstrap‑Analyse und Varianzbewertung durchführen
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Sicherstellung einheitlicher Trace‑Struktur für Host und VM.
+
+**Erforderliche Tags & Metadaten:**
+- session_id
+- probe_name
+- timestamp_ns
+- cpu_id
+
+**trace-cmd-Setup:**
+- BPF‑Skripte mit sudo ausführen
+- BPF‑Ringbuffergröße auf ≥64 MB einstellen
+- Zeitsynchronisation zwingend per NTP/PPS
+
+**Run-Design für Contributors:**
+- Mindestens 300 vollständige Runs pro Testfall
+- VM‑Konfiguration dokumentieren (CPU, Scheduler, Kernel‑Version)
+- Aggregationsergebnisse als Histogramneinträge exportieren
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Konstanter Offset von 1,111 s zwischen entry und erstem read unabhängig von Umgebung
+- Erhöhte Stabilität durch eBPF gegenüber kprobe‑basierter Messung
+- C‑State‑Verhalten hat keinen Einfluss auf den Offset
+
+**Implikationen für Experimente:**
+- Die Hauptlatenz entsteht vor dem ersten clocksource->read(), wahrscheinlich im Scheduler‑ oder KVM‑Entry‑Pfad
+- Weitere Tracepunkte erforderlich zur genauen Lokalisierung
+
+**Planungsziel:**
+- Ziel: Isolation des Prozesses, der den konstanten Offset verursacht.
+- Vorgehen:
+  - Ausweitung der BPF‑Probes auf scheduler_wake, hrtimer_expire, kvm_entry/kvm_exit
+  - Einführung per‑chain‑Histogramme in trace_agg.py
+  - Analyse mit mindestens 500 Runs unter identischen Bedingungen
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Mögliche Ungenauigkeit bei nicht synchronisierten Host‑VM‑Clocks
+- Abhängigkeit von Verfügbarkeit der Kernel‑Symbole
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap‑CI ungenau bei geringer Run‑Zahl (<100)
+- Nichtparametrische Annahme kann systematische Zeitversätze nicht kompensieren
+
+**Kausalität & Generalisierbarkeit:**
+- Beobachtete Latenz kann host‑spezifisch sein
+- Ergebnisse nicht zwangsläufig auf Nicht‑KVM‑Setups übertragbar
+
+**Praktische Fallstricke:**
+- Overhead durch eBPF‑Instrumentation kann marginale Zeitverschiebung erzeugen
+- Unzureichende PPS‑Verbindung verfälscht Referenzalignment
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Einführung weiterer Probes für scheduler_wake, hrtimer_expire, kvm_entry, kvm_exit
+- Erweiterung um IRQ‑ und Softirq‑Pfade
+
+**Analyseziele:**
+- Validierung, ob Scheduling‑Latenz den Offset vollständig erklärt
+- Quantifizierung der Interferenz zwischen Host und VM
+
+**Regression & Modellierung:**
+- Bootstrap‑Regression zur Modellierung des Einflusses einzelner Pfadsegmente
+- Vergleich mit analytischer Latenz aus Tracegraph‑Modellen
+
+**Community-Beiträge:**
+- Tests auf unterschiedlichen KVM‑/QEMU‑Umgebungen durch Community
+- Bereitstellung von Histogrammen kvm_entry→first_read zur Vergleichanalyse