From 47db0fc7fe59d4a9cf356ee0caf7c3ce143f8683 Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Fri, 5 Jul 2019 12:08:31 +0100
Subject: [PATCH] add in more comments

---
 src/ieee754/div_rem_sqrt_rsqrt/core.py | 11 +++++++----
 src/ieee754/fpdiv/div0.py              | 14 ++++++++++++--
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/src/ieee754/div_rem_sqrt_rsqrt/core.py b/src/ieee754/div_rem_sqrt_rsqrt/core.py
index 1227f11f..dd1fdf91 100644
--- a/src/ieee754/div_rem_sqrt_rsqrt/core.py
+++ b/src/ieee754/div_rem_sqrt_rsqrt/core.py
@@ -90,6 +90,8 @@ class DivPipeCoreInputData:
         self.dividend = Signal(core_config.bit_width + core_config.fract_width,
                                reset_less=True)
         self.divisor_radicand = Signal(core_config.bit_width, reset_less=True)
+
+        # FIXME: this goes into (is replaced by) self.ctx.op
         self.operation = DivPipeCoreOperation.create_signal(reset_less=True)
 
         return # TODO: needs a width argument and a pspec
@@ -105,7 +107,7 @@ class DivPipeCoreInputData:
         """ Get member signals. """
         yield self.dividend
         yield self.divisor_radicand
-        yield self.operation
+        yield self.operation # FIXME: delete.  already covered by self.ctx
         return
         yield self.z
         yield self.out_do_z
@@ -116,7 +118,7 @@ class DivPipeCoreInputData:
         """ Assign member signals. """
         return [self.dividend.eq(rhs.dividend),
                 self.divisor_radicand.eq(rhs.divisor_radicand),
-                self.operation.eq(rhs.operation)]
+                self.operation.eq(rhs.operation)] # FIXME: delete.
         # TODO: and these
         return [self.out_do_z.eq(i.out_do_z), self.oz.eq(i.oz),
                 self.ctx.eq(i.ctx)]
@@ -152,6 +154,7 @@ class DivPipeCoreInterstageData:
         """ Create a ``DivPipeCoreInterstageData`` instance. """
         self.core_config = core_config
         self.divisor_radicand = Signal(core_config.bit_width, reset_less=True)
+        # XXX FIXME: delete.  already covered by self.ctx.op
         self.operation = DivPipeCoreOperation.create_signal(reset_less=True)
         self.quotient_root = Signal(core_config.bit_width, reset_less=True)
         self.root_times_radicand = Signal(core_config.bit_width * 2,
@@ -169,7 +172,7 @@ class DivPipeCoreInterstageData:
     def __iter__(self):
         """ Get member signals. """
         yield self.divisor_radicand
-        yield self.operation
+        yield self.operation # XXX FIXME: delete.  already in self.ctx.op
         yield self.quotient_root
         yield self.root_times_radicand
         yield self.compare_lhs
@@ -183,7 +186,7 @@ class DivPipeCoreInterstageData:
     def eq(self, rhs):
         """ Assign member signals. """
         return [self.divisor_radicand.eq(rhs.divisor_radicand),
-                self.operation.eq(rhs.operation),
+                self.operation.eq(rhs.operation), # FIXME: delete.
                 self.quotient_root.eq(rhs.quotient_root),
                 self.root_times_radicand.eq(rhs.root_times_radicand),
                 self.compare_lhs.eq(rhs.compare_lhs),
diff --git a/src/ieee754/fpdiv/div0.py b/src/ieee754/fpdiv/div0.py
index f128ff82..fb2bccd6 100644
--- a/src/ieee754/fpdiv/div0.py
+++ b/src/ieee754/fpdiv/div0.py
@@ -46,6 +46,7 @@ class FPDivStage0Mod(Elaboratable):
         return FPSCData(self.width, self.id_wid, False)
 
     def ospec(self):
+        # XXX TODO: replace with DivPipeCoreInputData, here
         return FPDivStage0Data(self.width, self.id_wid)
 
     def process(self, i):
@@ -65,10 +66,14 @@ class FPDivStage0Mod(Elaboratable):
         # *begins* the processing phase (enters the massive DIV
         # pipeline chain) - see ospec.
 
+        # INPUT SPEC: FPSCData
+        # OUTPUT SPEC: DivPipeCoreInputData
+
         # NOTE: this stage does *NOT* do *ACTUAL* DIV processing,
         # it is PURELY the *ENTRY* point into the chain, performing
-        # "preparation" work
+        # "preparation" work.
 
+        # delete this
         # store intermediate tests (and zero-extended mantissas)
         am0 = Signal(len(self.i.a.m)+1, reset_less=True)
         bm0 = Signal(len(self.i.b.m)+1, reset_less=True)
@@ -76,8 +81,11 @@ class FPDivStage0Mod(Elaboratable):
                      am0.eq(Cat(self.i.a.m, 0)),
                      bm0.eq(Cat(self.i.b.m, 0))
                     ]
-        # same-sign (both negative or both positive) div mantissas
+
         with m.If(~self.i.out_do_z):
+            # do conversion here, of both self.i.a and self.i.b,
+            # into DivPipeCoreInputData dividend and divisor.
+
             m.d.comb += [self.o.z.e.eq(self.i.a.e + self.i.b.e + 1),
                          # TODO: no, not product, first stage Q and R etc. etc.
                          # go here.
@@ -85,9 +93,11 @@ class FPDivStage0Mod(Elaboratable):
                          self.o.z.s.eq(self.i.a.s ^ self.i.b.s)
                 ]
 
+        # these are required and must not be touched
         m.d.comb += self.o.oz.eq(self.i.oz)
         m.d.comb += self.o.out_do_z.eq(self.i.out_do_z)
         m.d.comb += self.o.ctx.eq(self.i.ctx)
+
         return m
 
 
-- 
2.30.2