From 25631b1a2427241971f6c4900e0d9f5fc94d750d Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Thu, 1 Jul 2021 13:26:00 +0100
Subject: [PATCH] remap.py code-comments

---
 openpower/sv/remap.py      | 21 ++++++++++++++++-----
 openpower/sv/remapyield.py |  2 --
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/openpower/sv/remap.py b/openpower/sv/remap.py
index 2b5c4f373..387b90ae2 100644
--- a/openpower/sv/remap.py
+++ b/openpower/sv/remap.py
@@ -1,3 +1,7 @@
+# Finite State Machine version of the REMAP system.  much more likely
+# to end up being actually used in actual hardware
+
+# up to three dimensions permitted
 xdim = 3
 ydim = 2
 zdim = 1
@@ -5,17 +9,20 @@ zdim = 1
 VL = xdim * ydim * zdim # set total (can repeat, e.g. VL=x*y*z*4)
 
 lims = [xdim, ydim, zdim]
-idxs = [0,0,0] # starting indices
-order = [1,0,2] # experiment with different permutations, here
-offset = 0     # experiment with different offsetet, here
-invxyz = [0,1,0]
+idxs = [0,0,0]   # starting indices
+order = [1,0,2]  # experiment with different permutations, here
+offset = 0       # experiment with different offsetet, here
+invxyz = [0,1,0] # inversion allowed
 
+# pre-prepare the index state: run for "offset" times before
+# actually starting.  this algorithm can also be used for re-entrancy
+# if exceptions occur and a REMAP has to be started from where the
+# interrupt left off.
 for idx in range(offset):
     for i in range(3):
         idxs[order[i]] = idxs[order[i]] + 1
         if (idxs[order[i]] != lims[order[i]]):
             break
-        print
         idxs[order[i]] = 0
 
 break_count = 0 # for pretty-printing
@@ -32,6 +39,10 @@ for idx in range(VL):
     if break_count == lims[order[0]]:
         print ("")
         break_count = 0
+    # this is the exact same thing as the pre-preparation stage
+    # above.  step 1: count up to the limit of the current dimension
+    # step 2: if limit reached, zero it, and allow the *next* dimension
+    # to increment.  repeat for 3 dimensions.
     for i in range(3):
         idxs[order[i]] = idxs[order[i]] + 1
         if (idxs[order[i]] != lims[order[i]]):
diff --git a/openpower/sv/remapyield.py b/openpower/sv/remapyield.py
index ff492f444..c3a5f5301 100644
--- a/openpower/sv/remapyield.py
+++ b/openpower/sv/remapyield.py
@@ -15,7 +15,6 @@ order = [1,0,2]  # experiment with different permutations, here
 offset = 0       # experiment with different offset, here
 invxyz = [0,1,0] # inversion if desired
 
-
 # python "yield" can be iterated. use this to make it clear how
 # the indices are generated by using natural-looking nested loops
 def iterate_indices():
@@ -39,7 +38,6 @@ def iterate_indices():
                     # construct the (up to) 3D remap schedule
                     yield (x + y * xd + z * xd * yd)
 
-
 # enumerate over the iterator function, getting new indices
 for idx, new_idx in enumerate(iterate_indices()):
     if idx < offset:
-- 
2.30.2