utils: general purpose utilities

Also includes a new README.md explaining the code structure to come.

Change-Id: I2725308c3f0dc2cbd88f5f8481555154223e4e97

README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2a6aad0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+# Trace Based Model (TBM)
+
+## Code structure
+
+### Executables:
+
+- gentrace-spike.py - reads a Spike trace and reformat it. We expect to support
+  other functional simulators, each of those will have its own gentrace-*.py
+  file.
+- tbm.py - runs a trace in TBM; the main tool here.
+- merge-counters.py - merges results from multiple runs of TBM.
+
+### Python modules:
+
+**NOTE:** currently TBM includes a single model for each of the building block
+units. The intention is that other models will be added in the future to cover
+uArchs that are not supported by the current models. interfaces.py defines (what
+we expect to be) the API of the building blocks.
+
+- counter.py - performance counters.
+- cpu.py - defines CPU, a cpu model (includes instances of FetchUnit, SchedUnit,
+  ExecUnit, and MemorySystem).
+- disassembler.py - bits we need to elaborate Spike traces.
+- exec_unit.py - defines ExecUnit, an execution unit model (includes instances of
+  ScalarPipe, VectorPipe, scoreboard.Preemptive and scoreboard.VecPreemptive).
+- fetch_unit.py - defines FetchUnit.
+- instruction.fbs - FlatBuffer schema for the Instruction data class (used for
+  saving elaborated traces). The FBInstruction.Instruction module is generated
+  from this file.
+- instruction.py - defines Instruction, a data class representing a single
+  instruction instance in the trace.
+- interfaces.py - defines the internal API. This will be more important when we
+  add different models (i.e. implementations) for the various units.
+- memory_system.py - defines MemorySystem, a main memory and cache hierarchy model.
+- queue.py - defines Queue, FIFO queue model.
+- scalar_pipe.py - defines ScalarPipe, a scalar functional unit model.
+- sched_unit.py - defines SchedUnit, an issue queue model.
+- scoreboard.py - defines Preemptive and VecPreemptive, scoreboard models.
+- tbm_options.py - command line parsing for tbm.py.
+- trace.py - reads a trace (as generated by gentrace-*.py).
+- utilities.py - general purpose constructs.
+- vector_pipe.py - defines VectorPipe, a vector functional unit model.
+
+### Other files:
+
+- config/uarch.schema.json - JSON schema for uArch configuration files.
+- config/default_arch.yaml - a uArch configuration example.

utilities.py

diff --git a/utilities.py b/utilities.py
new file mode 100644
index 0000000..4fdbff3
--- /dev/null
+++ b/utilities.py
@@ -0,0 +1,77 @@
+"""Collection of general purpose utilities."""
+
+import enum
+import itertools
+import logging
+import sys
+import threading
+import time
+from typing import Any, Callable, Iterable, Sequence
+
+
+def logging_config(level: int) -> None:
+    """Configure the root logger to track events starting from `level`.
+
+    If tracked, WARNING events (and above) go to stderr, other events go to
+    stdout.
+    """
+    # Log messages below WARNING go to stdout.
+    stdout_h = logging.StreamHandler(sys.stdout)
+    stdout_h.setLevel(logging.DEBUG)
+    stdout_h.addFilter(lambda record: record.levelno < logging.WARNING)
+
+    # Log messages that are WARNING and above go to stderr.
+    stderr_h = logging.StreamHandler(sys.stderr)
+    stderr_h.setLevel(logging.WARNING)
+
+    formatter = logging.Formatter("[%(asctime)s] %(message)s",
+                                  datefmt="%H:%M:%S'")
+    stdout_h.setFormatter(formatter)
+    stderr_h.setFormatter(formatter)
+
+    logging.basicConfig(handlers=[stdout_h, stderr_h],
+                        level=level)
+
+
+class FileFormat(enum.Enum):
+    FLATBUFFERS = enum.auto()
+    JSON = enum.auto()
+
+
+def flatten(xss: Iterable[Iterable[Any]]) -> Sequence[Any]:
+    return list(itertools.chain.from_iterable(xss))
+
+
+class CallEvery():
+    """Call some function every few seconds.
+
+    `with CallEvery(s, f) as c: ...` calls `f()` every `s` seconds, while inside
+    the with block.
+    """
+
+    def __init__(self, period, f: Callable[[], None]):
+        self.period = period
+        self.f = f
+        self.running = False
+        self.timer = None
+        self.t = None
+
+    def __enter__(self) -> None:
+        self.running = True
+        self.t = time.time() + self.period
+        self.timer = threading.Timer(max(self.t - time.time(), 0), self._run)
+        self.timer.start()
+
+    def __exit__(self, exc_type, exc_value, traceback) -> bool:
+        self.running = False
+        if self.timer:
+            self.timer.cancel()
+        return False
+
+    def _run(self):
+        if self.running:
+            self.f()
+            self.t += self.period
+            self.timer = threading.Timer(max(self.t - time.time(), 0),
+                                         self._run)
+            self.timer.start()