Improve fusion documentation

slothy/core/slothy.py

@@ -354,7 +354,17 @@ def _fusion_core(self, pre, body, post, logger, ssa=True):
         return body
 
     def fusion_region(self, start, end, **kwargs):
-        """Run fusion callbacks on straightline code"""
+        """ Run fusion callbacks on straightline code replacing certain
+        instruction (sequences) with an alternative. These replacements are
+        defined in the architectural model by setting an instruction class'
+        global_fusion_cb.
+        
+        Args:
+            start: The label marking the beginning of the part of the code to
+                  apply fusion to.
+            end: The label marking the end of the part of the code to apply
+                  fusion to.
+        """
         logger = self.logger.getChild(f"ssa_{start}_{end}")
         pre, body, post = AsmHelper.extract(self.source, start, end)
 
@@ -365,7 +375,13 @@ def fusion_region(self, start, end, **kwargs):
         assert SourceLine.is_source(self.source)
 
     def fusion_loop(self, loop_lbl, **kwargs):
-        """Run fusion callbacks on loop body"""
+        """Run fusion callbacks on loop body replacing certain instruction
+        (sequences) with an alternative. These replacements are defined in the
+        architectural model by setting an instruction class' global_fusion_cb.
+        
+        Args:
+            loop_lbl: Label of loop to which the fusions are applied to. 
+        """
         logger = self.logger.getChild(f"ssa_loop_{loop_lbl}")
 
         pre , body, post, _, other_data, loop = \

slothy/targets/aarch64/aarch64_neon.py

@@ -3176,10 +3176,13 @@ def core(inst,t,log=None):
 
     return core
 
-# TODO: Test only...
-# veor.global_fusion_cb  = eor3_fusion_cb()
-
 def eor3_splitting_cb():
+    """
+    Example for a splitting call back. Allows to split one eor instruction with
+    three inputs into two eors with two inputs. Such technique can help perform
+    transformations in case of differences between uArchs. 
+    Note: This is not used in any real (crypto) example. This is merely a PoC.
+    """
     def core(inst,t,log=None):
 
         d = inst.args_out[0]
@@ -3219,6 +3222,7 @@ def core(inst,t,log=None):
 
     return core
 
+# Can alternatively set veor3.global_fusion_cb to eor3_fusion_cb() here
 veor3.global_fusion_cb  = eor3_splitting_cb()
 
 def iter_aarch64_instructions():