document the FPMUL stack

diff --git a/src/ieee754/fpmul/mulstages.py b/src/ieee754/fpmul/mulstages.py
index fbfe8c7cb08b9058f4d899a278469b9e71d1cd22..415ed8efdfaad8fe5a4c399a6dbb01b238694e55 100644 (file)
--- a/src/ieee754/fpmul/mulstages.py
+++ b/src/ieee754/fpmul/mulstages.py
@@ -15,7 +15,7 @@ from .mul1 import FPMulStage1Mod
 class FPMulStages(FPState, SimpleHandshake):
 
     def __init__(self, pspec):
-        FPState.__init__(self, "align")
+        FPState.__init__(self, "mulstages")
         self.pspec = pspec
         SimpleHandshake.__init__(self, self) # pipeline is its own stage
         self.m1o = self.ospec()

diff --git a/src/ieee754/fpmul/pipeline.py b/src/ieee754/fpmul/pipeline.py
index 08c151d0020105864724dc8d1505e45c4954480c..589d106663349ffdc39e7fad802f31706eaadb51 100644 (file)
--- a/src/ieee754/fpmul/pipeline.py
+++ b/src/ieee754/fpmul/pipeline.py
@@ -1,6 +1,41 @@
-# IEEE Floating Point Adder (Single Precision)
-# Copyright (C) Jonathan P Dawson 2013
-# 2013-12-12
+"""IEEE Floating Point Multiplier Pipeline
+
+Relevant bugreport: http://bugs.libre-riscv.org/show_bug.cgi?id=77
+
+Stack looks like this:
+
+* scnorm    - FPMulSpecialCasesDeNorm
+* mulstages - FPMulstages
+* normpack  - FPNormToPack
+
+scnorm   - FPDIVSpecialCasesDeNorm ispec FPADDBaseData
+------                             ospec FPSCData
+
+                StageChain: FPMULSpecialCasesMod,
+                            FPAddDeNormMod
+                            FPAlignModSingle
+
+mulstages - FPMulStages            ispec FPSCData
+---------                          ospec FPAddStage1Data
+
+                StageChain: FPMulStage0Mod
+                            FPMulStage1Mod
+
+normpack  - FPNormToPack           ispec FPAddStage1Data
+--------                           ospec FPPackData
+
+                StageChain: Norm1ModSingle,
+                            RoundMod,
+                            CorrectionsMod,
+                            PackMod
+
+This is the *current* stack.  FPMulStage0Mod is where the actual
+mantissa multiply takes place, which in the case of FP64 is a
+single (massive) combinatorial block.  This can be fixed by using
+a multi-stage fixed-point multiplier pipeline, which was implemented
+in #60: http://bugs.libre-riscv.org/show_bug.cgi?id=60
+
+"""
 
 from nmigen import Module
 from nmigen.cli import main, verilog