add some data documentation

3 files changed, 100 insertions, 0 deletions

diff --git a/doc/MIMOSA b/doc/MIMOSA
new file mode 100644
index 0000000..d4582d3
--- /dev/null
+++ b/doc/MIMOSA
@@ -0,0 +1,32 @@
+calibration_functio#caldata:
+- edges: [int(us)] Position der Kalibrierungsflanken in us seit Messbeginn
+- offset: int Null-Offset der Rohwerte (Mittlerer Rohwert ohne Verbrauch)
+- offset2: int Rohwert bei R2 als Last
+- slope_low: int Funktionssteigung zwischen 0 und R2
+- slope_high: int Funktionssteigung zwischen R2 und R1
+- add_low: Funktionsoffset zwischen 0 und R2
+- add_high: Funktionsoffset zwischen R2 und R1
+- r0_err_uW: int(uW) Mittlerer Messfehler der unkalibrierten Daten ohne Verbrauch
+- r0_std_uW: int Standardabweichung des Messfehlers der unkalibrierten Daten ohne Verbrauch
+- r1_err_uW: int(uW) Mittlerer Messfehler der unkalibrierten Daten an R1
+- r1_std_uW: int Standardabweichung des Messfehlers der unkalibrierten Daten an R1
+- r2_err_uW: int(uW) Mittlerer Messfehler der unkalibrierten Daten an R2
+- r2_std_uW: int Standardabweichung des Messfehlers der unkalibrierten Daten an R2
+
+analyze_states:
+[... Ein Element pro Trace-Part, begrenzt durch Triggerflanken.
+     Jedes Element stellt also einen Zustand oder eine Transition dar.
+
+	- isa: 'state' oder 'transition'
+	- clip_rate: range(0..1) Anteil an Clipping im Energieverbrauch
+	- raw_mean: Mittelwert der Rohwerte
+	- raw_std: Standardabweichung der Rohwerte
+	- uW_mean: Mittelwert der (kalibrierten) Leistungsaufnahme
+	- uW_std: Standardabweichung der (kalibrierten) Leistungsaufnahme
+	- us: Dauer
+
+	Nur falls isa 'transition':
+	- timeout: Dauer des vorherigen Zustands
+	- uW_mean_delta_prev: Differenz zwischen uW_mean und uW_mean des vorherigen Zustands
+	- uW_mean_delta_next: Differenz zwischen uW_mean und uW_mean des Folgezustands
+]
diff --git a/doc/RawData b/doc/RawData
new file mode 100644
index 0000000..863b92b
--- /dev/null
+++ b/doc/RawData
@@ -0,0 +1,59 @@
+get_preprocessed_data:
+[ ... Liste von einzelnen Läufen (d.h. eine Zustands- und Transitionsfolge UNINITIALIZED -> foo -> FOO -> bar -> BAR -> ...)
+	Jeder Lauf:
+	- id: int Nummer des Laufs, beginnend bei 1
+	- trace: [ ... Liste von Zuständen und Transitionen
+		Jeweils:
+		- name: str Name
+		- isa: str state // transition
+		- parameter: { ... globaler Parameter: aktueller wert. null falls noch nicht eingestellt }
+		- plan:
+			Falls isa == 'state':
+			- power: int(uW?)
+			- time: int(us) geplante Dauer
+			- energy: int(pJ?)
+			Falls isa == 'transition':
+			- timeout: int(us) oder null
+			- energy: int (pJ?)
+			- level: str 'user' 'epilogue'
+		- offline_aggregates:
+			- power: [float(uW)] Mittlere Leistung während Zustand/Transitions
+			- power_std: [float(uW^2)] Standardabweichung der Leistung
+			- duration: [int(us)] Dauer
+			- energy: [float(pJ)] Energieaufnahme des Zustands / der Transition
+			- clip_rate: [float(0..1)] Clipping
+			- paramkeys: [[str]] Name der berücksichtigten Parameter
+			- param: [int // str] Parameterwerte. Quasi-Duplikat von 'parameter' oben
+			Falls isa == 'transition':
+			- timeout: [int(us)] Dauer des vorherigen Zustands
+			- rel_energy_prev: [int(pJ)]
+			- rel_energy_next: [int(pJ)]
+		- offline: [ ... Während der Messung von MIMOSA o.ä. gemessene Werte
+			-> siehe doc/MIMOSA analyze_states
+			- isa: 'state' oder 'transition'
+			- clip_rate: range(0..1) Anteil an Clipping im Energieverbrauch
+			- raw_mean: Mittelwert der Rohwerte
+			- raw_std: Standardabweichung der Rohwerte
+			- uW_mean: Mittelwert der (kalibrierten) Leistungsaufnahme
+			- uW_std: Standardabweichung der (kalibrierten) Leistungsaufnahme
+			- us: Dauer
+			Nur falls isa 'transition':
+			- timeout: Dauer des vorherigen Zustands
+			- uW_mean_delta_prev
+			- uW_mean_delta_next
+		]
+		- online: [ ... Während der Messung vom Betriebssystem bestimmte Daten
+			Falls isa == 'state':
+			- power: int(uW?)
+			- time: int(us) geplante Dauer
+			- energy: int(pJ?)
+			Falls isa == 'transition':
+			- timeout: int(us) oder null
+			- energy: int (pJ?)
+			- level: str ('user' oder 'epilogue')
+		]
+		Falls isa == 'transition':
+		- code: [str] Name und Argumente der aufgerufenen Funktion
+		- args: [str] Argumente der aufgerufenen Funktion
+	]
+]
diff --git a/doc/setup b/doc/setup
new file mode 100644
index 0000000..b9ad13d
--- /dev/null
+++ b/doc/setup
@@ -0,0 +1,9 @@
+- trigger_pin: int
+- state_duration: int(ms)
+- trace_revisit: int
+- trace_filter: [...]
+- excluded_states: [...]
+- mimosa_shunt: int(ohm)
+- mimosa_offset: int(?)
+- ignore_nested: bool
+- mimosa_voltage: float(V)