smallworld-re 1.0.0__py3-none-any.whl

smallworld/__init__.py

@@ -0,0 +1,35 @@
+from importlib import metadata as __metadata
+
+metadata = __metadata.metadata("smallworld")
+
+__title__ = metadata["name"]
+__description__ = metadata["Summary"]
+__author__ = metadata["Author"]
+__version__ = metadata["version"]
+
+
+from . import (
+    analyses,
+    emulators,
+    exceptions,
+    extern,
+    hinting,
+    instructions,
+    logging,
+    platforms,
+    state,
+)
+from .helpers import *  # noqa: F401, F403
+from .helpers import __all__ as __helpers__
+
+__all__ = __helpers__ + [
+    "analyses",
+    "emulators",
+    "exceptions",
+    "extern",
+    "hinting",
+    "instructions",
+    "logging",
+    "platforms",
+    "state",
+]

smallworld/analyses/__init__.py

@@ -0,0 +1,14 @@
+from .analysis import *  # noqa: F401, F403
+from .analysis import __all__ as __analysis__
+from .colorizer import Colorizer
+from .colorizer_summary import ColorizerSummary
+from .field_detection import FieldDetectionAnalysis, ForcedFieldDetectionAnalysis
+from .forced_exec import ForcedExecution
+
+__all__ = __analysis__ + [
+    "Colorizer",
+    "ColorizerSummary",
+    "FieldDetectionAnalysis",
+    "ForcedFieldDetectionAnalysis",
+    "ForcedExecution",
+]

smallworld/analyses/analysis.py

@@ -0,0 +1,88 @@
+import abc
+import logging
+import typing
+
+from .. import hinting, state, utils
+
+
+class Analysis(utils.MetadataMixin):
+    """An analysis that emits some information about some code, possibly to help with harnessing."""
+
+    @abc.abstractmethod
+    def run(self, machine: state.Machine) -> None:
+        """Run the analysis.
+
+        This function **should not** modify the provided Machine. Instead, it
+        should be coppied before modification.
+
+        Arguments:
+            machine: A machine state object on which this analysis should run.
+        """
+
+        pass
+
+
+class Filter(utils.MetadataMixin):
+    """Analyses that consume and sometimes produce additional hints.
+
+    Filter analyses are analyses that consume some part of the hint
+    stream and possibly emit new higher-level, synthetic hints. These
+    analyses do not inspect machine state directly, they just react to
+    hints from other analyses.
+
+    """
+
+    def __init__(self):
+        self.listeners = []
+
+    def listen(
+        self,
+        hint: typing.Type[hinting.Hint],
+        method: typing.Callable[[hinting.Hint], None],
+    ) -> None:
+        """Register a listener for a particular hint type on the hint stream.
+
+        Arguments:
+            hint: A hint type that should trigger this listener. Note: All
+                subclasses `hint` will trigger the listener.
+            method: The method to call when the given hint type is observed.
+        """
+
+        class Handler(logging.Handler):
+            def emit(self, record):
+                method(record.msg)
+
+        handler = Handler()
+        handler.setLevel(logging.DEBUG)
+        handler.addFilter(hinting.HintSubclassFilter(hint))
+        hinting.root.addHandler(handler)
+
+        self.listeners.append(handler)
+
+    @abc.abstractmethod
+    def activate(self) -> None:
+        """Activate this filter.
+
+        Implementations should make necessary calls to `listen()` here to
+        register hint listener functions. They will be unregistered
+        automatically on destruction or manual call to `deactivate()`.
+        """
+
+        pass
+
+    def deactivate(self) -> None:
+        """Deactivate this filter.
+
+        This is done automatically on destruction of this object - you likely
+        shouldn't need to call this manually.
+        """
+
+        for handler in self.listeners:
+            hinting.root.removeHandler(handler)
+
+    def __del__(self):
+        self.deactivate()
+        # super().__del__()
+
+
+__all__ = ["Analysis", "Filter"]

smallworld/analyses/code_coverage.py

@@ -0,0 +1,31 @@
+import logging
+import typing
+
+from .. import emulators, hinting
+from . import analysis
+
+logger = logging.getLogger(__name__)
+hinter = hinting.get_hinter(__name__)
+
+
+class CodeCoverage(analysis.Analysis):
+    """A simple analysis that logs jumps, calls, and returns."""
+
+    name = "code-coverage"
+    description = ""
+    version = "0.0.1"
+
+    def run(self, machine) -> None:
+        emulator = emulators.UnicornEmulator(machine.get_platform())
+        coverage: typing.Dict[int, int] = {}
+
+        for step in machine.step(emulator):
+            cpu = step.get_cpu()
+            pc = cpu.pc.get_content()
+            if pc in coverage:
+                coverage[pc] += 1
+            else:
+                coverage[pc] = 1
+
+        hint = hinting.CoverageHint(message="Coverage for execution", coverage=coverage)
+        hinter.info(hint)