From d5a3fc5bbf5486965482f1876fde973ce429da7c Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Tue, 16 Jul 2019 10:49:51 +0100
Subject: [PATCH] document the FPMUL stack

---
 src/ieee754/fpmul/mulstages.py |  2 +-
 src/ieee754/fpmul/pipeline.py  | 41 +++++++++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/src/ieee754/fpmul/mulstages.py b/src/ieee754/fpmul/mulstages.py
index fbfe8c7c..415ed8ef 100644
--- 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 08c151d0..589d1066 100644
--- 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
-- 
2.30.2