Add README.md

README.md

@@ -0,0 +1,85 @@
+# TSC Stability Logging
+
+## Überblick
+Dieses Repository dokumentiert das Experiment **tsc_stability_logging**. Es untersucht die Stabilität des Time Stamp Counters (TSC) während des Bootvorgangs unter Linux-Systemen. Ziel ist die automatisierte Erfassung, Analyse und Bewertung der TSC-Verlässlichkeit verschiedener Hardware- und Virtualisierungsumgebungen.
+
+**Link zum Artikel:** [https://donau2space.de/tag-111-1359-bedeckt-ueber-passau-und-ich-frage-jeden-boot-bist-du-ein-stabiler-tsc-oder-nur-ein-versprechen/](https://donau2space.de/tag-111-1359-bedeckt-ueber-passau-und-ich-frage-jeden-boot-bist-du-ein-stabiler-tsc-oder-nur-ein-versprechen/)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.
+
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko. Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+Dieses Repository enthält zwei Python-Artefakte zur Erfassung und Auswertung von TSC-Stabilitätsdaten.
+
+### 1. artifact.boot_logger
+- **Art (Kind):** python_script  
+- **Ziel (Target):** Linux-Userspace  
+- **Programmiersprache:** Python  
+- **Zweck:** Erfassung von Kernelinformationen zum TSC während des Bootvorgangs. Speichert die Daten als JSON-Datei zur späteren Analyse.
+
+**API-Funktionen:**
+- `collect_tsc_data()` – Erfasst TSC-bezogene Bootdaten und liefert ein JSON-Objekt mit Informationen zu `boot_id`, `host_vm`, `pinned`, `governor` und `tsc_status`.
+
+**Datenstruktur:**
+- **BootData (JSON):**
+  - Felder: `boot_id`, `host_vm`, `pinned`, `governor`, `tsc_status`
+
+### 2. artifact.trace_agg_integration
+- **Art (Kind):** python_script  
+- **Ziel (Target):** Linux-Userspace  
+- **Programmiersprache:** Python  
+- **Zweck:** Integration und statistische Auswertung der erfassten TSC-Daten in bestehende Trace-Aggregationssysteme.
+
+**API-Funktionen:**
+- `compare_ts_data(data_file, p95_p99)` – Führt statistische Vergleiche der TSC-Daten durch und liefert Ergebnisse zur Stabilitätsbewertung (z. B. 95. und 99. Perzentil).
+
+**Datenstruktur:**
+- **TraceResult (JSON):**
+  - Felder: `p95`, `p99`, `comparison_summary`
+
+## Installation & Nutzung
+1. Voraussetzungen: Linux-Umgebung mit Python ≥ 3.8
+2. Klonen des Repositories:
+   
+   ```bash
+   git clone <repository-url>
+   cd tsc_stability_logging
+   ```
+
+3. Installation der Abhängigkeiten:
+   
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Nutzung der Skripte:
+   
+   **Beispiel:**
+   
+   ```bash
+   python boot_logger.py
+   python trace_agg_integration.py --input data/boot_data.json
+   ```
+
+## Typische Use-Cases
+- Automatisierte Sammlung von TSC-Stabilitätsmetriken über mehrere Boots hinweg.
+- Integration der Ergebnisse in bestehende Trace- und Monitoring-Systeme.
+- Vergleich von TSC-Stabilität zwischen physischen und virtuellen Hosts.
+- Untersuchen des Einflusses von CPU-Governor-Settings auf TSC-Konstanz.
+
+## Struktur & mögliche Erweiterungen
+- **scripts/** – enthält die Python-Skripte `boot_logger.py` und `trace_agg_integration.py`.
+- **data/** – speichert die generierten JSON-Daten und Analyseergebnisse.
+- **docs/** – Dokumentation der Schnittstellen und Datenstrukturen.
+
+**Erweiterungsmöglichkeiten:**
+- Unterstützung weiterer Plattformen (z. B. BSD, Windows Subsystem for Linux).
+- Ergänzung einer Web-API zur Live-Auswertung.
+- Erweiterung der Analysefunktionen um Machine-Learning-basierte Stabilitätsmetriken.
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+
+**Hinweis:** Diese Inhalte wurden automatisch durch eine KI erzeugt. Verwendung und Weiterentwicklung erfolgen auf eigenes Risiko.