MIMOSA: Documentation, log errors

1 files changed, 121 insertions, 78 deletions

diff --git a/lib/dfatool.py b/lib/dfatool.py
index 340a6e5..7d6d5c9 100755
--- a/lib/dfatool.py
+++ b/lib/dfatool.py
@@ -360,7 +360,9 @@ def _preprocess_measurement(measurement):
         'triggers' : len(trigidx),
         'first_trig' : trigidx[0] * 10,
         'calibration' : caldata,
-        'trace' : mim.analyze_states(charges, trigidx, vcalfunc)
+        'trace' : mim.analyze_states(charges, trigidx, vcalfunc),
+        'has_mimosa_error' : mim.is_error,
+        'mimosa_errors' : mim.errors,
     }
 
     return processed_data
@@ -585,6 +587,8 @@ class RawData:
 
         Each filename element corresponds to a measurement run. It must be a tar archive with the following contents:
 
+        Version 0:
+
         * `setup.json`: measurement setup. Must contain the keys `state_duration` (how long each state is active, in ms),
           `mimosa_voltage` (voltage applied to dut, in V), and `mimosa_shunt` (shunt value, in Ohm)
         * `src/apps/DriverEval/DriverLog.json`: PTA traces and parameters for this benchmark.
@@ -1827,33 +1831,53 @@ class MIMOSA:
     MIMOSA log loader for DFA traces with auto-calibration.
 
     Expects a MIMOSA log file generated via dfatool and a dfatool-generated
-    benchmark: There is an automatic calibration step at the start and the
-    trigger pin is high iff a transition is active. The resulting data
-    is a list of state/transition/state/transition/... measurements.
+    benchmark. A MIMOSA log consists of a series of measurements. Each measurement
+    gives the total charge (in pJ) and binary buzzer/trigger value during a 10µs interval.
+    
+    There must be a calibration run consisting of at least two seconds with disconnected DUT,
+    two seconds with 1 kOhm (984 Ohm), and two seconds with 100 kOhm (99013 Ohm) resistor at
+    the start. The first ten seconds of data are reserved for calbiration and must not contain
+    measurements, as trigger/buzzer signals are ignored in this time range.
+    
+    Resulting data is a list of state/transition/state/transition/... measurements.
     """
 
-    def __init__(self, voltage, shunt, verbose = True):
+    def __init__(self, voltage: float, shunt: int, verbose = True):
         """
         Initialize MIMOSA loader for a specific voltage and shunt setting.
 
-        arguments:
-        voltage -- MIMOSA voltage used for measurements
-        shunt -- Shunt value in Ohms
-        verbose -- notify about invalid data and the likes
+        :param voltage: MIMOSA DUT supply voltage (V)
+        :para mshunt: MIMOSA Shunt (Ohms)
+        :param verbose: print notices about invalid data on STDOUT?
         """
         self.voltage = voltage
         self.shunt = shunt
         self.verbose = verbose
         self.r1 = 984 # "1k"
         self.r2 = 99013 # "100k"
+        self.is_error = False
+        self.errors = list()
 
     def charge_to_current_nocal(self, charge):
-        u"""Convert charge per 10µs to mean currents without accounting for calibration."""
+        u"""
+        Convert charge per 10µs (in pJ) to mean currents (in µA) without accounting for calibration.
+        
+        :param charge: numpy array of charges (pJ per 10µs) as returned by `load_data` or `load_file`
+
+        :returns: numpy array of mean currents (µA per 10µs)
+        """
         ua_max = 1.836 / self.shunt * 1000000
         ua_step = ua_max / 65535
         return charge * ua_step
 
     def _load_tf(self, tf):
+        u"""
+        Load MIMOSA log data from an open `tarfile` instance.
+
+        :param tf: `tarfile` instance
+
+        :returns: (numpy array of charges (pJ per 10µs), numpy array of triggers (0/1 int, per 10µs))
+        """
         num_bytes = tf.getmember('/tmp/mimosa//mimosa_scale_1.tmp').size
         charges = np.ndarray(shape=(int(num_bytes / 4)), dtype=np.int32)
         triggers = np.ndarray(shape=(int(num_bytes / 4)), dtype=np.int8)
@@ -1868,19 +1892,37 @@ class MIMOSA:
         return charges, triggers
 
 
-    def load_data(self, raw_data):
-        """Load a MIMOSA log archive from a raw bytestring."""
+    def load_data(self, raw_data, first_is_state = True):
+        u"""
+        Load MIMOSA log data from a MIMOSA log file passed as raw byte string
+
+        :param raw_data: MIMOSA log file, passed as raw byte string
+
+        :returns: (numpy array of charges (pJ per 10µs), numpy array of triggers (0/1 int, per 10µs))
+        """
+        self.first_is_state = first_is_state
         with io.BytesIO(raw_data) as data_object:
             with tarfile.open(fileobj = data_object) as tf:
                 return self._load_tf(tf)
 
     def load_file(self, filename):
-        """Load a MIMOSA log archive from a filename."""
+        u"""
+        Load MIMOSA log data from a MIMOSA log file
+
+        :param filename: MIMOSA log file
+
+        :returns: (numpy array of charges (pJ per 10µs), numpy array of triggers (0/1 int, per 10µs))
+        """
         with tarfile.open(filename) as tf:
             return self._load_tf(tf)
 
     def currents_nocal(self, charges):
-        u"""Convert charge per 10µs to mean currents without accounting for calibration."""
+        u"""
+        Convert charges (pJ per 10µs) to mean currents without accounting for calibration.
+        
+        :param charges: numpy array of charges (pJ per 10µs)
+
+        :returns: numpy array of currents (mean µA per 10µs)"""
         ua_max = 1.836 / self.shunt * 1000000
         ua_step = ua_max / 65535
         return charges.astype(np.double) * ua_step
@@ -1889,41 +1931,45 @@ class MIMOSA:
         """
         Return indexes of trigger edges (both 0->1 and 1->0) in log data.
 
-        arguments:
-        triggers -- trigger array as returned by load_data
-
         Ignores the first 10 seconds, which are used for calibration and may
-        contain bogus triggers due to DUT resets. Returns a list of int.
+        contain bogus triggers due to DUT resets.
+
+        :param triggers: trigger array (int, 0/1) as returned by load_data
+
+        :returns: list of int (trigger indices, e.g. [2000000, ...] means the first trigger appears in charges/currents interval 2000000 -> 20s after start of measurements. Keep in mind that each interval is 10µs long, not 1µs, so index values are not µs timestamps)
         """
         trigidx = []
-        prevtrig = triggers[0]
+        prevtrig = triggers[999999]
+
+        # if the first trigger is high (i.e., trigger/buzzer pin is active before the benchmark starts),
+        # something went wrong and are unable to determine when the first
+        # transition starts.
+        if prevtrig != 0:
+            self.is_error = True
+            self.errors.append('Unable to find start of first transition (log starts with trigger == {} != 0)'.format(prevtrig))
+
         # the device is reset for MIMOSA calibration in the first 10s and may
         # send bogus interrupts -> bogus triggers
         for i in range(1000000, triggers.shape[0]):
             trig = triggers[i]
             if trig != prevtrig:
-                # Due to MIMOSA's integrate-read-reset cycle, the trigger
-                # appears two points (20µs) before the corresponding data
+                # Due to MIMOSA's integrate-read-reset cycle, the charge/current
+                # interval belonging to this trigger comes two intervals (20µs) later
                 trigidx.append(i+2)
             prevtrig = trig
         return trigidx
 
     def calibration_edges(self, currents):
-        """
+        u"""
         Return start/stop indexes of calibration measurements.
 
-        arguments:
-        currents -- uncalibrated currents as reported by MIMOSA. For best results,
+        :param currents: uncalibrated currents as reported by MIMOSA. For best results,
             it may help to use a running mean, like so:
-            currents = running_mean(currents_nocal(..., 10))
-
-        Returns six indexes:
-        - Disconnected start
-        - Disconnected  stop
-        - R1 (1 kOhm) start
-        - R1 (1 kOhm) stop
-        - R2 (100 kOhm) start
-        - R2 (100 kOhm) stop
+            `currents = running_mean(currents_nocal(..., 10))`
+
+        :returns: indices of calibration events in MIMOSA data:
+            (disconnect start, disconnect stop, R1 (1k) start, R1 (1k) stop, R2 (100k) start, R2 (100k) stop)
+            indices refer to charges/currents arrays, so 0 refers to the first 10µs interval, 1 to the second, and so on.
         """
         r1idx = 0
         r2idx = 0
@@ -1940,30 +1986,29 @@ class MIMOSA:
 
     def calibration_function(self, charges, cal_edges):
         u"""
-        Calculate calibration function from previously determined calibration phase.
-
-        arguments:
-        charges -- raw charges from MIMOSA
-        cal_edges -- calibration edges as returned by calibration_edges
-
-        returns (calibration_function, calibration_data):
-        calibration_function -- charge in pJ (float) -> current in uA (float).
-            Converts the amount of charge in a 10 µs interval to the
-            mean current during the same interval.
-        calibration_data -- dict containing the following keys:
-            edges -- calibration points in the log file, in µs
-            offset -- ...
-            offset2 --  ...
-            slope_low -- ...
-            slope_high -- ...
-            add_low -- ...
-            add_high -- ..
-            r0_err_uW -- mean error of uncalibrated data at "∞ Ohm" in µW
-            r0_std_uW -- standard deviation of uncalibrated data at "∞ Ohm" in µW
-            r1_err_uW -- mean error of uncalibrated data at 1 kOhm
-            r1_std_uW -- stddev at 1 kOhm
-            r2_err_uW -- mean error at 100 kOhm
-            r2_std_uW -- stddev at 100 kOhm
+        Calculate calibration function from previously determined calibration edges.
+
+        :param charges: raw charges from MIMOSA
+        :param cal_edges: calibration edges as returned by calibration_edges
+
+        :returns: (calibration_function, calibration_data):
+            calibration_function -- charge in pJ (float) -> current in uA (float).
+                Converts the amount of charge in a 10 µs interval to the
+                mean current during the same interval.
+            calibration_data -- dict containing the following keys:
+                edges -- calibration points in the log file, in µs
+                offset -- ...
+                offset2 --  ...
+                slope_low -- ...
+                slope_high -- ...
+                add_low -- ...
+                add_high -- ..
+                r0_err_uW -- mean error of uncalibrated data at "∞ Ohm" in µW
+                r0_std_uW -- standard deviation of uncalibrated data at "∞ Ohm" in µW
+                r1_err_uW -- mean error of uncalibrated data at 1 kOhm
+                r1_std_uW -- stddev at 1 kOhm
+                r2_err_uW -- mean error at 100 kOhm
+                r2_std_uW -- stddev at 100 kOhm
         """
         dis_start, dis_end, r1_start, r1_end, r2_start, r2_end = cal_edges
         if dis_start < 0:
@@ -2073,27 +2118,25 @@ class MIMOSA:
 
     def analyze_states(self, charges, trigidx, ua_func):
         u"""
-        Split log data into states and transitions and return mean power and duration for each element.
-
-        arguments:
-        charges -- raw charges (each element describes the charge transferred during 10 µs)
-        trigidx -- "charges" indexes corresponding to a trigger edge
-        ua_func -- charge -> current function as returned by calibration_function
-
-        returns a list of (alternating) states and transitions.
-        Each element is a dict containing:
-            - 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
+        Split log data into states and transitions and return duration, energy, and mean power for each element.
+
+        :param charges: raw charges (each element describes the charge in pJ transferred during 10 µs)
+        :param trigidx: "charges" indexes corresponding to a trigger edge, see `trigger_edges`
+        :param ua_func: charge(pJ) -> current(µA) function as returned by `calibration_function`
+
+        :returns: list of states and transitions, starting with a state and ending with a transition.
+            Each element is a dict containing:
+            * `isa`: 'state' or '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
+            if isa == 'transition, it also contains:
+            * `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
         """
         previdx = 0
         is_state = True