From 768c1bc703933ca989191473890f082f00b80a6c Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Thu, 12 Jan 2023 04:35:44 -0800
Subject: [PATCH 1/5] Header comments

---
 pipelined/src/fpu/fclassify.sv                |  2 +
 pipelined/src/fpu/fcmp.sv                     |  2 +
 pipelined/src/fpu/fctrl.sv                    |  2 +
 pipelined/src/fpu/fcvt.sv                     |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrt.sv        |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtexpcalc.sv |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtfgen2.sv   |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtfgen4.sv   |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtfsm.sv     |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtiter.sv    |  4 +-
 .../src/fpu/fdivsqrt/fdivsqrtpostproc.sv      |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtpreproc.sv |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtqsel2.sv   |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4.sv   |  2 +
 .../src/fpu/fdivsqrt/fdivsqrtqsel4cmp.sv      |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtstage2.sv  |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtstage4.sv  |  4 +-
 pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc2.sv  |  2 +
 pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc4.sv  |  2 +
 pipelined/src/fpu/fhazard.sv                  |  2 +
 pipelined/src/fpu/fma/fma.sv                  |  2 +
 pipelined/src/fpu/fma/fmaadd.sv               |  2 +
 pipelined/src/fpu/fma/fmaalign.sv             |  2 +
 pipelined/src/fpu/fma/fmaexpadd.sv            |  2 +
 pipelined/src/fpu/fma/fmalza.sv               |  2 +
 pipelined/src/fpu/fma/fmamult.sv              |  2 +
 pipelined/src/fpu/fma/fmasign.sv              |  2 +
 pipelined/src/fpu/fpu.sv                      |  2 +
 pipelined/src/fpu/fregfile.sv                 |  2 +
 pipelined/src/fpu/fsgninj.sv                  |  2 +
 pipelined/src/fpu/postproc/cvtshiftcalc.sv    |  2 +
 pipelined/src/fpu/postproc/divshiftcalc.sv    |  2 +
 pipelined/src/fpu/postproc/flags.sv           |  2 +
 pipelined/src/fpu/postproc/fmashiftcalc.sv    |  2 +
 pipelined/src/fpu/postproc/negateintres.sv    |  2 +
 pipelined/src/fpu/postproc/normshift.sv       |  2 +
 pipelined/src/fpu/postproc/postprocess.sv     |  4 +-
 pipelined/src/fpu/postproc/resultsign.sv      |  2 +
 pipelined/src/fpu/postproc/round.sv           |  2 +
 pipelined/src/fpu/postproc/roundsign.sv       |  2 +
 pipelined/src/fpu/postproc/shiftcorrection.sv |  2 +
 pipelined/src/fpu/postproc/specialcase.sv     |  2 +
 pipelined/src/fpu/unpack.sv                   |  2 +
 pipelined/src/fpu/unpackinput.sv              |  2 +
 pipelined/src/generic/flop/flop.sv            |  3 +-
 pipelined/src/generic/flop/flopen.sv          |  3 +-
 pipelined/src/generic/flop/flopenl.sv         |  3 +-
 pipelined/src/generic/flop/flopenr.sv         |  3 +-
 pipelined/src/generic/flop/flopenrc.sv        |  3 +-
 pipelined/src/generic/flop/flopens.sv         |  3 +-
 pipelined/src/generic/flop/flopr.sv           |  3 +-
 pipelined/src/generic/flop/floprc.sv          |  5 +-
 pipelined/src/generic/flop/synchronizer.sv    |  1 -
 pipelined/src/ieu/comparator.sv               |  2 +
 pipelined/src/ieu/controller.sv               |  2 +
 pipelined/src/ieu/datapath.sv                 |  2 +
 pipelined/src/ieu/extend.sv                   |  4 +-
 pipelined/src/ieu/forward.sv                  |  2 +
 pipelined/src/ieu/ieu.sv                      |  2 +
 pipelined/src/ieu/regfile.sv                  |  2 +
 pipelined/src/ieu/shifter.sv                  |  2 +
 pipelined/src/privileged/csrm.sv              |  5 +-
 pipelined/src/wally/wallypipelinedsoc.sv      | 58 +++++++++----------
 63 files changed, 153 insertions(+), 59 deletions(-)

diff --git a/pipelined/src/fpu/fclassify.sv b/pipelined/src/fpu/fclassify.sv
index 9a6b43073..68cdfcedb 100644
--- a/pipelined/src/fpu/fclassify.sv
+++ b/pipelined/src/fpu/fclassify.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Floating-point classify unit
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fcmp.sv b/pipelined/src/fpu/fcmp.sv
index 758b589e3..e749e9576 100755
--- a/pipelined/src/fpu/fcmp.sv
+++ b/pipelined/src/fpu/fcmp.sv
@@ -7,6 +7,8 @@
 //
 // Purpose: Floating-point comparison unit
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fctrl.sv b/pipelined/src/fpu/fctrl.sv
index b8bb29638..563206134 100755
--- a/pipelined/src/fpu/fctrl.sv
+++ b/pipelined/src/fpu/fctrl.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: floating-point control unit
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fcvt.sv b/pipelined/src/fpu/fcvt.sv
index 41ba1badd..e70947526 100644
--- a/pipelined/src/fpu/fcvt.sv
+++ b/pipelined/src/fpu/fcvt.sv
@@ -7,6 +7,8 @@
 //
 // Purpose: Floating point conversions of configurable size
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // Int component of the Wally configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrt.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrt.sv
index 2fecf769f..c69618f43 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrt.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrt.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Combined Divide and Square Root Floating Point and Integer Unit
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtexpcalc.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtexpcalc.sv
index b78f3f537..07cffa268 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtexpcalc.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtexpcalc.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit
+// Purpose: Exponent caclulation for divide and square root
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen2.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen2.sv
index ae642890e..9c13a91da 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen2.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen2.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 2 F Addend Generator
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen4.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen4.sv
index 4572ba94d..975d58ebd 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen4.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtfgen4.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 4 F Addend Generator
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtfsm.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtfsm.sv
index 476a7c904..81f6a5eed 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtfsm.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtfsm.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit
+// Purpose: divsqrt state machine for multi-cycle operations
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtiter.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtiter.sv
index 9a50679a6..d1cf24354 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtiter.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtiter.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu 
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit
+// Purpose: k stages of divsqrt logic, plus registers
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtpostproc.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtpostproc.sv
index 94b7c043f..44b269355 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtpostproc.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtpostproc.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit
+// Purpose: Divide/Square root postprocessing
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtpreproc.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtpreproc.sv
index 83d3c09de..5d490df28 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtpreproc.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtpreproc.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit
+// Purpose: Divide/Square root preprocessing: integer absolute value and W64, normalization shift
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel2.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel2.sv
index 316e885b8..f18b31f1b 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel2.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel2.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 2 Quotient Digit Selection
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4.sv
index ee5e63a24..3a8a110f0 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 4 Quotient Digit Selection
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4cmp.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4cmp.sv
index 104884fc4..882458106 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4cmp.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtqsel4cmp.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Comparator-based Radix 4 Quotient Digit Selection
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtstage2.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtstage2.sv
index 48d34972e..63ab6c059 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtstage2.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtstage2.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit stage
+// Purpose: radix-2 divsqrt recurrence stage
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtstage4.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtstage4.sv
index 93e809ae1..007dd18bb 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtstage4.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtstage4.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu, me@KatherineParry.com, cturek@hmc.edu
 // Modified:13 January 2022
 //
-// Purpose: Combined Divide and Square Root Floating Point and Integer Unit stage
+// Purpose: radix-4 divsqrt recurrence stage
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc2.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc2.sv
index 46289cd2b..65b8940ac 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc2.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc2.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 2 unified on-the-fly converter
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc4.sv b/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc4.sv
index 5c2168c21..a1416384b 100644
--- a/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc4.sv
+++ b/pipelined/src/fpu/fdivsqrt/fdivsqrtuotfc4.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Radix 4 unified on-the-fly converter
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fhazard.sv b/pipelined/src/fpu/fhazard.sv
index 4ee31f0f6..68c801048 100644
--- a/pipelined/src/fpu/fhazard.sv
+++ b/pipelined/src/fpu/fhazard.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Determine forwarding, stalls and flushes for the FPU
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fma.sv b/pipelined/src/fpu/fma/fma.sv
index b3e1751c0..b4add41dc 100644
--- a/pipelined/src/fpu/fma/fma.sv
+++ b/pipelined/src/fpu/fma/fma.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Floating point multiply-accumulate of configurable size
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Figure 13.7, 9)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmaadd.sv b/pipelined/src/fpu/fma/fmaadd.sv
index 96d81ed2d..20899cc83 100644
--- a/pipelined/src/fpu/fma/fmaadd.sv
+++ b/pipelined/src/fpu/fma/fmaadd.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FMA significand adder
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Figure 13.11)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmaalign.sv b/pipelined/src/fpu/fma/fmaalign.sv
index 2e1218ce0..0f1764b29 100644
--- a/pipelined/src/fpu/fma/fmaalign.sv
+++ b/pipelined/src/fpu/fma/fmaalign.sv
@@ -7,6 +7,8 @@
 //
 // Purpose: FMA alginment shift
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Table 13.10)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmaexpadd.sv b/pipelined/src/fpu/fma/fmaexpadd.sv
index dfee67e1d..dfafa410e 100644
--- a/pipelined/src/fpu/fma/fmaexpadd.sv
+++ b/pipelined/src/fpu/fma/fmaexpadd.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FMA exponent addition
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Table 13.9)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmalza.sv b/pipelined/src/fpu/fma/fmalza.sv
index 90bf1cf1b..0dad87d84 100644
--- a/pipelined/src/fpu/fma/fmalza.sv
+++ b/pipelined/src/fpu/fma/fmalza.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Leading Zero Anticipator
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Figure 13.14)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmamult.sv b/pipelined/src/fpu/fma/fmamult.sv
index 6e3aa442d..62fa5bc11 100644
--- a/pipelined/src/fpu/fma/fmamult.sv
+++ b/pipelined/src/fpu/fma/fmamult.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FMA Significand Multiplier
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Table 13.7)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fma/fmasign.sv b/pipelined/src/fpu/fma/fmasign.sv
index a73e86216..2bf0ee660 100644
--- a/pipelined/src/fpu/fma/fmasign.sv
+++ b/pipelined/src/fpu/fma/fmasign.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FMA Sign Logic
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13 (Table 13.8)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fpu.sv b/pipelined/src/fpu/fpu.sv
index 49d1b982b..66e97f54f 100755
--- a/pipelined/src/fpu/fpu.sv
+++ b/pipelined/src/fpu/fpu.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Floating Point Unit Top-Level Interface
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fregfile.sv b/pipelined/src/fpu/fregfile.sv
index 282e581e2..1a5a2eecf 100644
--- a/pipelined/src/fpu/fregfile.sv
+++ b/pipelined/src/fpu/fregfile.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: 3R1W 4-port register file for FPU
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/fsgninj.sv b/pipelined/src/fpu/fsgninj.sv
index cd425ee72..0348426a2 100755
--- a/pipelined/src/fpu/fsgninj.sv
+++ b/pipelined/src/fpu/fsgninj.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FPU Sign Injection instructions
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/cvtshiftcalc.sv b/pipelined/src/fpu/postproc/cvtshiftcalc.sv
index 5fbe2882e..6c7516fa3 100644
--- a/pipelined/src/fpu/postproc/cvtshiftcalc.sv
+++ b/pipelined/src/fpu/postproc/cvtshiftcalc.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Conversion shift calculation
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/divshiftcalc.sv b/pipelined/src/fpu/postproc/divshiftcalc.sv
index 27db564ce..a8f00b46f 100644
--- a/pipelined/src/fpu/postproc/divshiftcalc.sv
+++ b/pipelined/src/fpu/postproc/divshiftcalc.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Division shift calculation
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/flags.sv b/pipelined/src/fpu/postproc/flags.sv
index 6ec601db0..c1dcab858 100644
--- a/pipelined/src/fpu/postproc/flags.sv
+++ b/pipelined/src/fpu/postproc/flags.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Post-Processing flag calculation
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/fmashiftcalc.sv b/pipelined/src/fpu/postproc/fmashiftcalc.sv
index 79dc1f0dd..f861d9162 100644
--- a/pipelined/src/fpu/postproc/fmashiftcalc.sv
+++ b/pipelined/src/fpu/postproc/fmashiftcalc.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: FMA shift calculation
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/negateintres.sv b/pipelined/src/fpu/postproc/negateintres.sv
index 596ddb308..5b7e7cbfd 100644
--- a/pipelined/src/fpu/postproc/negateintres.sv
+++ b/pipelined/src/fpu/postproc/negateintres.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Negate integer result
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/normshift.sv b/pipelined/src/fpu/postproc/normshift.sv
index d48e97582..8c4405962 100644
--- a/pipelined/src/fpu/postproc/normshift.sv
+++ b/pipelined/src/fpu/postproc/normshift.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: normalization shifter
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/postprocess.sv b/pipelined/src/fpu/postproc/postprocess.sv
index 3906ad57a..f15214457 100644
--- a/pipelined/src/fpu/postproc/postprocess.sv
+++ b/pipelined/src/fpu/postproc/postprocess.sv
@@ -4,8 +4,10 @@
 // Written: me@KatherineParry.com
 // Modified: 7/5/2022
 //
-// Purpose: Post-Processing
+// Purpose: Post-Processing: normalization, rounding, sign, flags, special cases
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/resultsign.sv b/pipelined/src/fpu/postproc/resultsign.sv
index 7ecf3eb66..2ac0ae3c0 100644
--- a/pipelined/src/fpu/postproc/resultsign.sv
+++ b/pipelined/src/fpu/postproc/resultsign.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: calculating the result's sign
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/round.sv b/pipelined/src/fpu/postproc/round.sv
index 62b7d92b7..820b1a92d 100644
--- a/pipelined/src/fpu/postproc/round.sv
+++ b/pipelined/src/fpu/postproc/round.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Rounder
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/roundsign.sv b/pipelined/src/fpu/postproc/roundsign.sv
index e768332aa..40231ecd3 100644
--- a/pipelined/src/fpu/postproc/roundsign.sv
+++ b/pipelined/src/fpu/postproc/roundsign.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Sign calculation for rounding
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/shiftcorrection.sv b/pipelined/src/fpu/postproc/shiftcorrection.sv
index 602e72e72..a86facbcd 100644
--- a/pipelined/src/fpu/postproc/shiftcorrection.sv
+++ b/pipelined/src/fpu/postproc/shiftcorrection.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: shift correction
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/postproc/specialcase.sv b/pipelined/src/fpu/postproc/specialcase.sv
index 9c9663c9c..f87c42f02 100644
--- a/pipelined/src/fpu/postproc/specialcase.sv
+++ b/pipelined/src/fpu/postproc/specialcase.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: special case selection
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/unpack.sv b/pipelined/src/fpu/unpack.sv
index 47eb4fb65..8e6ba2559 100644
--- a/pipelined/src/fpu/unpack.sv
+++ b/pipelined/src/fpu/unpack.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: unpack X, Y, Z floating-point inputs
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/fpu/unpackinput.sv b/pipelined/src/fpu/unpackinput.sv
index 2d88eee4d..9d2b0b6ab 100644
--- a/pipelined/src/fpu/unpackinput.sv
+++ b/pipelined/src/fpu/unpackinput.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: unpack input: extract sign, exponent, significand, characteristics
 // 
+// Documentation: RISC-V System on Chip Design Chapter 13
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/generic/flop/flop.sv b/pipelined/src/generic/flop/flop.sv
index 14b09899b..1e906dca8 100644
--- a/pipelined/src/generic/flop/flop.sv
+++ b/pipelined/src/generic/flop/flop.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// ordinary flip-flop
 module flop #(parameter WIDTH = 8) ( 
   input  logic             clk,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/flopen.sv b/pipelined/src/generic/flop/flopen.sv
index 5987222dd..32e0d7dd3 100644
--- a/pipelined/src/generic/flop/flopen.sv
+++ b/pipelined/src/generic/flop/flopen.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with enable
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with enable
 module flopen #(parameter WIDTH = 8) (
   input  logic             clk, en,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/flopenl.sv b/pipelined/src/generic/flop/flopenl.sv
index b01c5b5b6..094779c74 100644
--- a/pipelined/src/generic/flop/flopenl.sv
+++ b/pipelined/src/generic/flop/flopenl.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with enable and synchronous load
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with enable, synchronous load
 module flopenl #(parameter WIDTH = 8, parameter type TYPE=logic [WIDTH-1:0]) (
   input  logic clk, load, en,
   input  TYPE d,
diff --git a/pipelined/src/generic/flop/flopenr.sv b/pipelined/src/generic/flop/flopenr.sv
index 74cea0cdc..3b8129e40 100644
--- a/pipelined/src/generic/flop/flopenr.sv
+++ b/pipelined/src/generic/flop/flopenr.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with enable, synchronous reset
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with enable, synchronous reset
 module flopenr #(parameter WIDTH = 8) (
   input  logic             clk, reset, en,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/flopenrc.sv b/pipelined/src/generic/flop/flopenrc.sv
index 85fb09bd3..b3d5a1e8e 100644
--- a/pipelined/src/generic/flop/flopenrc.sv
+++ b/pipelined/src/generic/flop/flopenrc.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with enable, synchronous reset, enabled clear
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with enable, synchronous reset, enabled clear
 module flopenrc #(parameter WIDTH = 8) (
   input  logic             clk, reset, clear, en,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/flopens.sv b/pipelined/src/generic/flop/flopens.sv
index 257d28085..1f4c18051 100644
--- a/pipelined/src/generic/flop/flopens.sv
+++ b/pipelined/src/generic/flop/flopens.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with enable, synchronous set
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with enable, synchronous set
 module flopens #(parameter WIDTH = 8) (
   input  logic             clk, set, en,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/flopr.sv b/pipelined/src/generic/flop/flopr.sv
index d3296d926..b2f99b3cd 100644
--- a/pipelined/src/generic/flop/flopr.sv
+++ b/pipelined/src/generic/flop/flopr.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
+// Purpose: D flip-flop with synchronous reset
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with synchronous reset
 module flopr #(parameter WIDTH = 8) ( 
   input  logic             clk, reset,
   input  logic [WIDTH-1:0] d, 
diff --git a/pipelined/src/generic/flop/floprc.sv b/pipelined/src/generic/flop/floprc.sv
index 995cff602..8275a8f96 100644
--- a/pipelined/src/generic/flop/floprc.sv
+++ b/pipelined/src/generic/flop/floprc.sv
@@ -4,8 +4,8 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: various flavors of flip-flops
-// 
+// Purpose: D flip-flop with synchronous reset and clear
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// flop with synchronous reset, synchronous clear
 module floprc #(parameter WIDTH = 8) (
   input  logic clk,
   input  logic reset,
diff --git a/pipelined/src/generic/flop/synchronizer.sv b/pipelined/src/generic/flop/synchronizer.sv
index d5594c99b..f10efaeaf 100644
--- a/pipelined/src/generic/flop/synchronizer.sv
+++ b/pipelined/src/generic/flop/synchronizer.sv
@@ -26,7 +26,6 @@
 
 `include "wally-config.vh"
 
-// ordinary flip-flop
 module synchronizer ( 
   input  logic clk,
   input  logic d, 
diff --git a/pipelined/src/ieu/comparator.sv b/pipelined/src/ieu/comparator.sv
index 27226a6ad..33dbab147 100644
--- a/pipelined/src/ieu/comparator.sv
+++ b/pipelined/src/ieu/comparator.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Branch comparison
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Figure 4.7)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/controller.sv b/pipelined/src/ieu/controller.sv
index abc86da68..57b34b1c5 100644
--- a/pipelined/src/ieu/controller.sv
+++ b/pipelined/src/ieu/controller.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Top level controller module
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Section 4.1.4, Figure 4.8, Table 4.5)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/datapath.sv b/pipelined/src/ieu/datapath.sv
index 0e3e2e81a..4bcd1a60d 100644
--- a/pipelined/src/ieu/datapath.sv
+++ b/pipelined/src/ieu/datapath.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Wally Integer Datapath
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Figure 4.12)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/extend.sv b/pipelined/src/ieu/extend.sv
index 74b6acdfd..808358500 100644
--- a/pipelined/src/ieu/extend.sv
+++ b/pipelined/src/ieu/extend.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: 
+// Purpose: Produce sign-extended immediates from various formats
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Figure 4.3)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/forward.sv b/pipelined/src/ieu/forward.sv
index c76b2355d..8617be826 100644
--- a/pipelined/src/ieu/forward.sv
+++ b/pipelined/src/ieu/forward.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Determine datapath forwarding
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Section 4.2.2.3)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/ieu.sv b/pipelined/src/ieu/ieu.sv
index 9d6d81d46..ba04aa5e4 100644
--- a/pipelined/src/ieu/ieu.sv
+++ b/pipelined/src/ieu/ieu.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Integer Execution Unit: datapath and controller
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Figure 4.12)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/regfile.sv b/pipelined/src/ieu/regfile.sv
index 1680d5bcc..e08c46779 100644
--- a/pipelined/src/ieu/regfile.sv
+++ b/pipelined/src/ieu/regfile.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: 3-port register file
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/ieu/shifter.sv b/pipelined/src/ieu/shifter.sv
index 015cc7808..c03a40cd9 100644
--- a/pipelined/src/ieu/shifter.sv
+++ b/pipelined/src/ieu/shifter.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: RISC-V 32/64 bit shifter
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4 (Figure 4.5, Table 4.3)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/privileged/csrm.sv b/pipelined/src/privileged/csrm.sv
index d100285cd..8b8718380 100644
--- a/pipelined/src/privileged/csrm.sv
+++ b/pipelined/src/privileged/csrm.sv
@@ -7,7 +7,10 @@
 //
 // Purpose: Machine-Mode Control and Status Registers
 //          See RISC-V Privileged Mode Specification 20190608 
-// 
+// Note: the CSRs do not support the following optional features
+//   - Disabling portions of the instruction set with bits of the MISA register
+//   - Changing from RV64 to RV32 by writing the SXL/UXL bits of the STATUS register
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
diff --git a/pipelined/src/wally/wallypipelinedsoc.sv b/pipelined/src/wally/wallypipelinedsoc.sv
index 255009474..bb5094cc9 100644
--- a/pipelined/src/wally/wallypipelinedsoc.sv
+++ b/pipelined/src/wally/wallypipelinedsoc.sv
@@ -4,12 +4,7 @@
 // Written: David_Harris@hmc.edu 6 November 2020
 // Modified: 
 //
-// Purpose: System on chip including pipelined processor and memories
-// Full RV32/64IC instruction set
-//
-// Note: the CSRs do not support the following features
-//- Disabling portions of the instruction set with bits of the MISA register
-//- Changing from RV64 to RV32 by writing the SXL/UXL bits of the STATUS register
+// Purpose: System on chip including pipelined processor and uncore memories/peripherals
 //
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -32,35 +27,36 @@
 `include "wally-config.vh"
 
 module wallypipelinedsoc (
-  input  logic 		   clk, reset_ext, 
-  output logic       reset,
+  input  logic 		            clk, 
+  input  logic                reset_ext, 
+  output logic                reset,
   // AHB Interface
-  input  logic [`AHBW-1:0]  HRDATAEXT,
-  input  logic 		   HREADYEXT, HRESPEXT,
-  output logic 		   HSELEXT,
+  input  logic [`AHBW-1:0]    HRDATAEXT,
+  input  logic 		            HREADYEXT, HRESPEXT,
+  output logic 		            HSELEXT,
   // outputs to external memory, shared with uncore memory
-  output logic 		   HCLK, HRESETn,
+  output logic 		            HCLK, HRESETn,
   output logic [`PA_BITS-1:0] HADDR,
-  output logic [`AHBW-1:0] HWDATA,
-  output logic [`XLEN/8-1:0] HWSTRB,
-  output logic 		   HWRITE,
-  output logic [2:0] 	   HSIZE,
-  output logic [2:0] 	   HBURST,
-  output logic [3:0] 	   HPROT,
-  output logic [1:0] 	   HTRANS,
-  output logic 		   HMASTLOCK,
-  output logic 		   HREADY,
+  output logic [`AHBW-1:0]    HWDATA,
+  output logic [`XLEN/8-1:0]  HWSTRB,
+  output logic 		            HWRITE,
+  output logic [2:0] 	        HSIZE,
+  output logic [2:0] 	        HBURST,
+  output logic [3:0] 	        HPROT,
+  output logic [1:0] 	        HTRANS,
+  output logic 		            HMASTLOCK,
+  output logic 		            HREADY,
   // I/O Interface
-  input  logic       TIMECLK,
-  input logic [31:0] 	   GPIOPinsIn,
-  output logic [31:0] 	   GPIOPinsOut, GPIOPinsEn,
-  input logic 		   UARTSin,
-  output logic 		   UARTSout,
-  input logic 		   SDCCmdIn,
-  output logic 		   SDCCmdOut,
-  output logic 		   SDCCmdOE,			  
-  input logic [3:0] 	   SDCDatIn,
-  output logic 		   SDCCLK			  
+  input  logic                TIMECLK,
+  input  logic [31:0] 	        GPIOPinsIn,
+  output logic [31:0] 	      GPIOPinsOut, GPIOPinsEn,
+  input  logic 		            UARTSin,
+  output logic 		            UARTSout,
+  input  logic 		            SDCCmdIn,
+  output logic 		            SDCCmdOut,
+  output logic 		            SDCCmdOE,			  
+  input  logic [3:0] 	        SDCDatIn,
+  output logic 		            SDCCLK			  
 );
 
   // Uncore signals

From 1ad6ac139338a05c78be468bf6f39c2a6358fea5 Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Thu, 12 Jan 2023 07:15:14 -0800
Subject: [PATCH 2/5] MDU comment cleanup

---
 pipelined/src/mdu/intdivrestoring.sv     | 55 +++++++------
 pipelined/src/mdu/intdivrestoringstep.sv | 17 ++--
 pipelined/src/mdu/mdu.sv                 | 61 +++++++--------
 pipelined/src/mdu/mul.sv                 | 99 ++++++++++++------------
 4 files changed, 121 insertions(+), 111 deletions(-)

diff --git a/pipelined/src/mdu/intdivrestoring.sv b/pipelined/src/mdu/intdivrestoring.sv
index dab3c2d97..0d95233ca 100644
--- a/pipelined/src/mdu/intdivrestoring.sv
+++ b/pipelined/src/mdu/intdivrestoring.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: Restoring integer division using a shift register and subtractor
 // 
+// Documentation: RISC-V System on Chip Design Chapter 12 (Figure 12.19)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -26,32 +28,39 @@
 
 `include "wally-config.vh"
 
-  /* verilator lint_off UNOPTFLAT */
-
-module intdivrestoring (
-  input  logic clk,
-  input  logic reset,
-  input  logic StallM,
-  input  logic FlushE,
-  input  logic DivSignedE, W64E,
-  input  logic IntDivE,
-  //input logic [`XLEN-1:0] 	SrcAE, SrcBE,
-	input logic [`XLEN-1:0] ForwardedSrcAE, ForwardedSrcBE, // *** these are the src outputs before the mux choosing between them and PCE to put in srcA/B
-  output logic DivBusyE, 
-  output logic [`XLEN-1:0] QuotM, RemM
+module intdivrestoring(
+  input  logic             clk,
+  input  logic             reset,
+  input  logic             StallM,
+  input  logic             FlushE,
+  input  logic             IntDivE,                       // integer division/remainder instruction of any type
+  input  logic             DivSignedE,                    // signed division 
+  input  logic             W64E,                          // W-type instructions (divw, divuw, remw, remuw)
+	input  logic [`XLEN-1:0] ForwardedSrcAE, ForwardedSrcBE, // Forwarding mux outputs for Source A and B
+  output logic             DivBusyE,                      // Divide is busy - stall pipeline
+  output logic [`XLEN-1:0] QuotM, RemM                    // Quotient and remainder outputs
  );
 
-  typedef enum logic [1:0] {IDLE, BUSY, DONE} statetype;
+  localparam STEPBITS = $clog2(`XLEN/`IDIV_BITSPERCYCLE); // Number of steps
+
+  typedef enum logic [1:0] {IDLE, BUSY, DONE} statetype;  // division FSM state
   statetype state;
 
-  logic [`XLEN-1:0] W[`IDIV_BITSPERCYCLE:0];
-  logic [`XLEN-1:0] XQ[`IDIV_BITSPERCYCLE:0];
-  logic [`XLEN-1:0] DinE, XinE, DnE, DAbsBE, DAbsB, XnE, XInitE, WnM, XQnM;
-  localparam STEPBITS = $clog2(`XLEN/`IDIV_BITSPERCYCLE);
-  logic [STEPBITS:0] step;
-  logic Div0E, Div0M;
-  logic DivStartE, SignXE, SignDE, NegQE, NegWM, NegQM;
-  logic [`XLEN-1:0] WNext, XQNext;
+  logic [`XLEN-1:0]   W[`IDIV_BITSPERCYCLE:0];            // Residual for each of k steps
+  logic [`XLEN-1:0]   XQ[`IDIV_BITSPERCYCLE:0];           // dividend/quotient for each of k steps
+  logic [`XLEN-1:0]   WNext, XQNext;                      // initialized W and XQ going into registers
+  logic [`XLEN-1:0]   DinE, XinE;                         // divisor & dividend, possibly truncated to 32 bits
+  logic [`XLEN-1:0]   DnE;                                // DnE = ~DinE
+  logic [`XLEN-1:0]   DAbsBE;                             // absolute value of D
+  logic [`XLEN-1:0]   DAbsB;                              // registered absolute value of D, constant during division
+  logic [`XLEN-1:0]   XnE;                                // DXnE = ~XinE
+  logic [`XLEN-1:0]   XInitE;                             // |X|, or original X for divide by 0
+  logic [`XLEN-1:0]   WnM, XQnM;                          // negated residual W and quotient XQ for postprocessing sign correction
+  logic [STEPBITS:0]  step;                               // division step
+  logic               Div0E, Div0M;                       // divide by 0
+  logic               DivStartE;                          // start integer division
+  logic               SignXE, SignDE;                     // sign of dividend and divisor
+  logic               NegQE, NegWM, NegQM;                // negate quotient or residual during postprocessing
  
   //////////////////////////////
   // Execute Stage: prepare for division calculation with control logic, W logic and absolute values, initialize W and XQ
@@ -134,5 +143,3 @@ module intdivrestoring (
       else        state <= IDLE;
     end 
 endmodule 
-
-/* verilator lint_on UNOPTFLAT */
diff --git a/pipelined/src/mdu/intdivrestoringstep.sv b/pipelined/src/mdu/intdivrestoringstep.sv
index 95a26e82f..cc27a7d5b 100644
--- a/pipelined/src/mdu/intdivrestoringstep.sv
+++ b/pipelined/src/mdu/intdivrestoringstep.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu 2 October 2021
 // Modified: 
 //
-// Purpose: Restoring integer division using a shift register and subtractor
+// Purpose: Restoring integer division step.  k steps are used in intdivrestoring
 // 
+// Documentation: RISC-V System on Chip Design Chapter 12 (Figure 12.19)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -29,11 +31,16 @@
 /* verilator lint_off UNOPTFLAT */
 
 module intdivrestoringstep(
-  input  logic [`XLEN-1:0] W, XQ, DAbsB,
-  output logic [`XLEN-1:0] WOut, XQOut);
+  input  logic [`XLEN-1:0] W,     // Residual in
+  input  logic [`XLEN-1:0] XQ,    // bits of dividend X and quotient Q in
+  input  logic [`XLEN-1:0] DAbsB, // complement of absolute value of divisor D (for subtraction)
+  output logic [`XLEN-1:0] WOut,  // Residual out
+  output logic [`XLEN-1:0] XQOut  // bits of dividend and quotient out: discard one bit of X, append one bit of Q
+);
 
-  logic [`XLEN-1:0] WShift, WPrime;
-  logic qi, qib;
+  logic [`XLEN-1:0] WShift;       // Shift W left by one bit, bringing in most significant bit of X
+  logic [`XLEN-1:0] WPrime;       // WShift - D, for comparison and possible result
+  logic qi, qib;                  // Quotient digit and its complement
   
   assign {WShift, XQOut} = {W[`XLEN-2:0], XQ, qi};  // shift W and X/Q left, insert quotient bit at bottom
   adder #(`XLEN+1) wdsub({1'b0, WShift}, {1'b1, DAbsB}, {qib, WPrime}); // effective subtractor, carry out determines quotient bit
diff --git a/pipelined/src/mdu/mdu.sv b/pipelined/src/mdu/mdu.sv
index bb242b75f..4a85bf478 100644
--- a/pipelined/src/mdu/mdu.sv
+++ b/pipelined/src/mdu/mdu.sv
@@ -6,6 +6,8 @@
 //
 // Purpose: M extension multiply and divide
 // 
+// Documentation: RISC-V System on Chip Design Chapter 12 (Figure 12.21)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -26,56 +28,49 @@
 
 `include "wally-config.vh"
 
-module mdu (
-	       input logic 		clk, reset,
-	       // Execute Stage interface
-	       //    input logic [`XLEN-1:0] 	SrcAE, SrcBE,
-		   input logic [`XLEN-1:0] ForwardedSrcAE, ForwardedSrcBE, // *** these are the src outputs before the mux choosing between them and PCE to put in srcA/B
-	       input logic [2:0] 	Funct3E, Funct3M,
-	       input logic 		IntDivE, W64E, 
-	       // Writeback stage
-	       output logic [`XLEN-1:0] MDUResultW,
-	       // Divide Done
-	       output logic 		DivBusyE, 
-	       // hazards
-	       input logic 		StallM, StallW, FlushE, FlushM, FlushW 
-	       );
+module mdu(
+  input  logic 							clk, reset,
+  input  logic 							StallM, StallW, 
+  input  logic							FlushE, FlushM, FlushW,
+	input  logic [`XLEN-1:0] 	ForwardedSrcAE, ForwardedSrcBE, 	// inputs A and B from IEU forwarding mux output
+	input  logic [2:0] 				Funct3E, Funct3M,									// type of MDU operation
+	input  logic 							IntDivE, W64E, 										// Integer division/remainder, and W-type instrutions
+	output logic [`XLEN-1:0] 	MDUResultW,												// multiply/divide result
+	output logic 							DivBusyE													// busy signal to stall pipeline in Execute stage
+);
 
-	logic [`XLEN-1:0] MDUResultM;
-	logic [`XLEN-1:0] PrelimResultM;
-	logic [`XLEN-1:0] QuotM, RemM;
-	logic [`XLEN*2-1:0] ProdM; 
-
-	logic 		     DivSignedE;	
-	logic           W64M; 
+	logic [`XLEN*2-1:0] 			ProdM; 														// double-width product from mul
+	logic [`XLEN-1:0] 				QuotM, RemM;											// quotient and remainder from intdivrestoring
+	logic [`XLEN-1:0] 				PrelimResultM;										// selected result before W truncation
+	logic [`XLEN-1:0] 				MDUResultM;												// result after W truncation
+	logic           					W64M; 														// W-type instruction
 
 	// Multiplier
 	mul mul(.clk, .reset, .StallM, .FlushM, .ForwardedSrcAE, .ForwardedSrcBE, .Funct3E, .ProdM);
 
-	// Divide
+	// Divider
 	// Start a divide when a new division instruction is received and the divider isn't already busy or finishing
-	// When F extensions are supported, use the FPU divider instead
+	// When IDIV_ON_FPU is set, use the FPU divider instead
 	if (`IDIV_ON_FPU) begin  
 	  assign QuotM = 0;
 	  assign RemM = 0;
 	  assign DivBusyE = 0;
 	end else begin
-		assign DivSignedE = ~Funct3E[0];
-		intdivrestoring div(.clk, .reset, .StallM, .FlushE, .DivSignedE, .W64E, .IntDivE, 
+		intdivrestoring div(.clk, .reset, .StallM, .FlushE, .DivSignedE(~Funct3E[0]), .W64E, .IntDivE, 
 							.ForwardedSrcAE, .ForwardedSrcBE, .DivBusyE, .QuotM, .RemM);
 	end
 		
 	// Result multiplexer
 	always_comb
 		case (Funct3M)	   
-			3'b000: PrelimResultM = ProdM[`XLEN-1:0];
-			3'b001: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];
-			3'b010: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];
-			3'b011: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];
-			3'b100: PrelimResultM = QuotM;
-			3'b101: PrelimResultM = QuotM;
-			3'b110: PrelimResultM = RemM;
-			3'b111: PrelimResultM = RemM;
+			3'b000: PrelimResultM = ProdM[`XLEN-1:0];					// mul
+			3'b001: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];		// mulh
+			3'b010: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];		// mulhsu
+			3'b011: PrelimResultM = ProdM[`XLEN*2-1:`XLEN];		// mulhu
+			3'b100: PrelimResultM = QuotM;										// div
+			3'b101: PrelimResultM = QuotM;										// divu
+			3'b110: PrelimResultM = RemM;											// rem
+			3'b111: PrelimResultM = RemM;											// remu
 		endcase 
 
 	// Handle sign extension for W-type instructions
diff --git a/pipelined/src/mdu/mul.sv b/pipelined/src/mdu/mul.sv
index b94ce7993..952b4daf2 100644
--- a/pipelined/src/mdu/mul.sv
+++ b/pipelined/src/mdu/mul.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu 16 February 2021
 // Modified: 
 //
-// Purpose: Multiply instructions
+// Purpose: Integer multiplication
 // 
+// Documentation: RISC-V System on Chip Design Chapter 12 (Figure 12.18)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -26,69 +28,68 @@
 
 `include "wally-config.vh"
 
-module mul (
-  // Execute Stage interface
-  input  logic             clk, reset,
-  input  logic             StallM, FlushM,
-    //    input logic [`XLEN-1:0] 	SrcAE, SrcBE,
-  input logic [`XLEN-1:0] ForwardedSrcAE, ForwardedSrcBE, // *** these are the src outputs before the mux choosing between them and PCE to put in srcA/B
-  input  logic [2:0]       Funct3E,
-  output logic [`XLEN*2-1:0] ProdM
+module mul(
+  input  logic                clk, reset,
+  input  logic                StallM, FlushM,
+  input  logic [`XLEN-1:0]    ForwardedSrcAE, ForwardedSrcBE, // source A and B from after Forwarding mux
+  input  logic [2:0]          Funct3E,                        // type of multiply
+  output logic [`XLEN*2-1:0]  ProdM                           // double-widthproduct
 );
 
-    // Number systems
-    // Let A' = sum(i=0, XLEN-2, A[i]*2^i)
-    // Unsigned: A = A' + A[XLEN-1]*2^(XLEN-1)
-    // Signed:   A = A' - A[XLEN-1]*2^(XLEN-1)
+  // Number systems
+  // Let A' = sum(i=0, XLEN-2, A[i]*2^i)
+  // Unsigned: A = A' + A[XLEN-1]*2^(XLEN-1)
+  // Signed:   A = A' - A[XLEN-1]*2^(XLEN-1)
 
-    // Multiplication: A*B
-    // Let P' = A' * B'
-    //     PA = (A' * B[XLEN-1]) 
-    //     PB = (B' * A[XLEN-1])
-    //     PP = A[XLEN-1] * B[XLEN-1]
-    // Signed * Signed     = P' + (-PA - PB)*2^(XLEN-1) + PP*2^(2XLEN-2)
-    // Signed * Unsigned   = P' + ( PA - PB)*2^(XLEN-1) - PP*2^(2XLEN-2)
-    // Unsigned * Unsigned = P' + ( PA + PB)*2^(XLEN-1) + PP*2^(2XLEN-2)
-
-    logic [`XLEN*2-1:0] PP1E, PP2E, PP3E, PP4E;
-    logic [`XLEN*2-1:0] PP1M, PP2M, PP3M, PP4M;
-    logic [`XLEN-2:0]   PA, PB;
-    logic               PP;
-    logic               MULH, MULHSU;
-    logic [`XLEN-1:0]   Aprime, Bprime;
+  // Multiplication: A*B
+  // Let P' = A' * B'
+  //     PA = (A' * B[XLEN-1]) 
+  //     PB = (B' * A[XLEN-1])
+  //     PP = A[XLEN-1] * B[XLEN-1]
+  // Signed * Signed     = P' + (-PA - PB)*2^(XLEN-1) + PP*2^(2XLEN-2)
+  // Signed * Unsigned   = P' + ( PA - PB)*2^(XLEN-1) - PP*2^(2XLEN-2)
+  // Unsigned * Unsigned = P' + ( PA + PB)*2^(XLEN-1) + PP*2^(2XLEN-2)
 
+  logic [`XLEN-1:0]   Aprime, Bprime;                       // lower bits of source A and B
+  logic               MULH, MULHSU;                         // type of multiply
+  logic [`XLEN-2:0]   PA, PB;                               // product of msb and lsbs
+  logic               PP;                                   // product of msbs
+  logic [`XLEN*2-1:0] PP1E, PP2E, PP3E, PP4E;               // partial products
+  logic [`XLEN*2-1:0] PP1M, PP2M, PP3M, PP4M;               // registered partial proudcts
+ 
   //////////////////////////////
   // Execute Stage: Compute partial products
   //////////////////////////////
 
-    assign Aprime = {1'b0, ForwardedSrcAE[`XLEN-2:0]};
-    assign Bprime = {1'b0, ForwardedSrcBE[`XLEN-2:0]};
-    assign PP1E = Aprime * Bprime;
-    assign PA = {(`XLEN-1){ForwardedSrcAE[`XLEN-1]}} & ForwardedSrcBE[`XLEN-2:0];  
-    assign PB = {(`XLEN-1){ForwardedSrcBE[`XLEN-1]}} & ForwardedSrcAE[`XLEN-2:0];
-    assign PP = ForwardedSrcAE[`XLEN-1] & ForwardedSrcBE[`XLEN-1];
+  assign Aprime = {1'b0, ForwardedSrcAE[`XLEN-2:0]};
+  assign Bprime = {1'b0, ForwardedSrcBE[`XLEN-2:0]};
+  assign PP1E = Aprime * Bprime;
+  assign PA = {(`XLEN-1){ForwardedSrcAE[`XLEN-1]}} & ForwardedSrcBE[`XLEN-2:0];  
+  assign PB = {(`XLEN-1){ForwardedSrcBE[`XLEN-1]}} & ForwardedSrcAE[`XLEN-2:0];
+  assign PP = ForwardedSrcAE[`XLEN-1] & ForwardedSrcBE[`XLEN-1];
 
-    // flavor of multiplication
-    assign MULH   = (Funct3E == 3'b001);
-    assign MULHSU = (Funct3E == 3'b010);
+  // flavor of multiplication
+  assign MULH   = (Funct3E == 3'b001);
+  assign MULHSU = (Funct3E == 3'b010);
 
-    // Handle signs
-    assign PP2E = {2'b00, (MULH | MULHSU) ? ~PA : PA, {(`XLEN-1){1'b0}}};
-    assign PP3E = {2'b00, (MULH) ? ~PB : PB, {(`XLEN-1){1'b0}}};
-    always_comb 
-    if (MULH)        PP4E = {1'b1, PP, {(`XLEN-3){1'b0}}, 1'b1, {(`XLEN){1'b0}}}; 
-    else if (MULHSU) PP4E = {1'b1, ~PP, {(`XLEN-2){1'b0}}, 1'b1, {(`XLEN-1){1'b0}}};
-    else             PP4E = {1'b0, PP, {(`XLEN*2-2){1'b0}}};
+  // Select partial products, handling signed multiplication
+  assign PP2E = {2'b00, (MULH | MULHSU) ? ~PA : PA, {(`XLEN-1){1'b0}}};
+  assign PP3E = {2'b00, (MULH) ? ~PB : PB, {(`XLEN-1){1'b0}}};
+  always_comb 
+  if (MULH)        PP4E = {1'b1, PP, {(`XLEN-3){1'b0}}, 1'b1, {(`XLEN){1'b0}}}; 
+  else if (MULHSU) PP4E = {1'b1, ~PP, {(`XLEN-2){1'b0}}, 1'b1, {(`XLEN-1){1'b0}}};
+  else             PP4E = {1'b0, PP, {(`XLEN*2-2){1'b0}}};
 
   //////////////////////////////
   // Memory Stage: Sum partial proudcts
   //////////////////////////////
 
-	 flopenrc #(`XLEN*2) PP1Reg(clk, reset, FlushM, ~StallM, PP1E, PP1M); 
-	 flopenrc #(`XLEN*2) PP2Reg(clk, reset, FlushM, ~StallM, PP2E, PP2M); 
-	 flopenrc #(`XLEN*2) PP3Reg(clk, reset, FlushM, ~StallM, PP3E, PP3M); 
-	 flopenrc #(`XLEN*2) PP4Reg(clk, reset, FlushM, ~StallM, PP4E, PP4M); 
+  flopenrc #(`XLEN*2) PP1Reg(clk, reset, FlushM, ~StallM, PP1E, PP1M); 
+  flopenrc #(`XLEN*2) PP2Reg(clk, reset, FlushM, ~StallM, PP2E, PP2M); 
+  flopenrc #(`XLEN*2) PP3Reg(clk, reset, FlushM, ~StallM, PP3E, PP3M); 
+  flopenrc #(`XLEN*2) PP4Reg(clk, reset, FlushM, ~StallM, PP4E, PP4M); 
 
-    assign ProdM = PP1M + PP2M + PP3M + PP4M; //ForwardedSrcAE * ForwardedSrcBE;
+  // add up partial products; this multi-input add implies CSAs and a final CPA
+  assign ProdM = PP1M + PP2M + PP3M + PP4M; //ForwardedSrcAE * ForwardedSrcBE;
  endmodule
 

From 93233fbb456f992714769e8c8ba32c554306e44a Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Thu, 12 Jan 2023 07:28:52 -0800
Subject: [PATCH 3/5] Restructured negateintres to avoid lint error, but one
 still shows on shiftcorrection

---
 pipelined/src/fpu/postproc/negateintres.sv | 28 ++++++++++++----------
 pipelined/src/privileged/privileged.sv     | 17 ++++++-------
 2 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/pipelined/src/fpu/postproc/negateintres.sv b/pipelined/src/fpu/postproc/negateintres.sv
index 5b7e7cbfd..939bcc335 100644
--- a/pipelined/src/fpu/postproc/negateintres.sv
+++ b/pipelined/src/fpu/postproc/negateintres.sv
@@ -28,21 +28,23 @@
 `include "wally-config.vh"
 
 module negateintres(
-    input  logic                    Signed,         // is the integer input signed
-    input  logic                    Int64,          // is the integer input 64-bits
-    input  logic                    Plus1,          // should one be added for rounding?
-    input  logic                    Xs,             // X sign
-    input  logic [`NORMSHIFTSZ-1:0] Shifted,        // output from normalization shifter
-    output logic [1:0]              CvtNegResMsbs,  // most signigficant bits of possibly negated result
-    output logic [`XLEN+1:0]        CvtNegRes       // possibly negated integer result
+  input  logic                    Signed,         // is the integer input signed
+  input  logic                    Int64,          // is the integer input 64-bits
+  input  logic                    Plus1,          // should one be added for rounding?
+  input  logic                    Xs,             // X sign
+  input  logic [`NORMSHIFTSZ-1:0] Shifted,        // output from normalization shifter
+  output logic [1:0]              CvtNegResMsbs,  // most signigficant bits of possibly negated result
+  output logic [`XLEN+1:0]        CvtNegRes       // possibly negated integer result
 );
 
-    logic [2:0] CvtNegResMsbs3; // first three msbs of possibly negated result
+  logic [`XLEN+1:0]               CvtPreRes;      // integer result with rounding
+  logic [2:0]                     CvtNegResMsbs3; // first three msbs of possibly negated result
     
-    // round and negate the positive res if needed
-    assign CvtNegRes = Xs ? -({2'b0, Shifted[`NORMSHIFTSZ-1:`NORMSHIFTSZ-`XLEN]}+{{`XLEN+1{1'b0}}, Plus1}) : {2'b0, Shifted[`NORMSHIFTSZ-1:`NORMSHIFTSZ-`XLEN]}+{{`XLEN+1{1'b0}}, Plus1};
+  // round and negate the positive res if needed
+  assign CvtPreRes =  {2'b0, Shifted[`NORMSHIFTSZ-1:`NORMSHIFTSZ-`XLEN]}+{{`XLEN+1{1'b0}}, Plus1};
+  mux2 #(`XLEN+2) resmux(CvtPreRes, -CvtPreRes, Xs, CvtNegRes);
     
-    // select 2 most significant bits
-    mux2 #(3) msb3mux(CvtNegRes[33:31], CvtNegRes[`XLEN+1:`XLEN-1], Int64, CvtNegResMsbs3);
-    mux2 #(2) msb2mux(CvtNegResMsbs3[2:1], CvtNegResMsbs3[1:0], Signed, CvtNegResMsbs);
+  // select 2 most significant bits
+  mux2 #(3) msb3mux(CvtNegRes[33:31], CvtNegRes[`XLEN+1:`XLEN-1], Int64, CvtNegResMsbs3);
+  mux2 #(2) msb2mux(CvtNegResMsbs3[2:1], CvtNegResMsbs3[1:0], Signed, CvtNegResMsbs);
 endmodule
\ No newline at end of file
diff --git a/pipelined/src/privileged/privileged.sv b/pipelined/src/privileged/privileged.sv
index 73ecfada5..0acc8c152 100644
--- a/pipelined/src/privileged/privileged.sv
+++ b/pipelined/src/privileged/privileged.sv
@@ -41,20 +41,21 @@ module privileged (
   output logic             sfencevmaM,
   input  logic             InstrValidM, CommittedM, CommittedF, 
   input  logic             FRegWriteM, LoadStallD,
-  input  logic 		   DirPredictionWrongM,
-  input  logic 		   BTBPredPCWrongM,
-  input  logic 		   RASPredPCWrongM,
-  input  logic 		   PredictionInstrClassWrongM,
+  input  logic 		         DirPredictionWrongM,
+  input  logic 		         BTBPredPCWrongM,
+  input  logic 		         RASPredPCWrongM,
+  input  logic 		          PredictionInstrClassWrongM,
   input  logic [4:0]       InstrClassM,
   input  logic             DCacheMiss,
   input  logic             DCacheAccess,
   input  logic             ICacheMiss,
   input  logic             ICacheAccess,
   input  logic             PrivilegedM,
-  input  logic             InstrPageFaultF, HPTWInstrAccessFaultM, LoadPageFaultM, StoreAmoPageFaultM,
-  input  logic             InstrMisalignedFaultM, IllegalIEUInstrFaultD, IllegalFPUInstrM,
-  input  logic             LoadMisalignedFaultM,
-  input  logic             StoreAmoMisalignedFaultM,
+  input  logic             HPTWInstrAccessFaultM, 
+  input  logic             InstrPageFaultF, LoadPageFaultM, StoreAmoPageFaultM,
+  input  logic             InstrMisalignedFaultM, 
+  input  logic             LoadMisalignedFaultM, StoreAmoMisalignedFaultM,
+  input  logic             IllegalIEUInstrFaultD, IllegalFPUInstrM,
   input  logic             MTimerInt, MExtInt, SExtInt, MSwInt,
   input  logic [63:0]      MTIME_CLINT, 
   input  logic [`XLEN-1:0] IEUAdrM,

From e58879f2d0ba176bf61c81fdb2b6a98bb93744d4 Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Thu, 12 Jan 2023 07:34:37 -0800
Subject: [PATCH 4/5] restructured code for lint error related to CORRSHIFTSZ

---
 pipelined/src/fpu/postproc/shiftcorrection.sv | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/pipelined/src/fpu/postproc/shiftcorrection.sv b/pipelined/src/fpu/postproc/shiftcorrection.sv
index a86facbcd..b7003cf56 100644
--- a/pipelined/src/fpu/postproc/shiftcorrection.sv
+++ b/pipelined/src/fpu/postproc/shiftcorrection.sv
@@ -44,11 +44,13 @@ module shiftcorrection(
     output logic [`CORRSHIFTSZ-1:0] Mf,                     // the shifted sum before LZA correction
     output logic [`NE+1:0]          Qe                      // corrected exponent for divider
 );
-    logic [3*`NF+3:0]           CorrSumShifted; // the shifted sum after LZA correction
-    logic [`CORRSHIFTSZ-1:0]    CorrQmShifted;  // the shifted divsqrt result after one bit shift
-    logic                       ResSubnorm;     // is the result Subnormal
-    logic                       LZAPlus1;       // add one or two to the sum's exponent due to LZA correction
-    logic                       LeftShiftQm;    // should the divsqrt result be shifted one to the left
+
+    logic [3*`NF+3:0]           CorrSumShifted;             // the shifted sum after LZA correction
+    logic [`CORRSHIFTSZ-1:0]    CorrQm0, CorrQm1;           // portions of Shifted to select for CorrQmShifted
+    logic [`CORRSHIFTSZ-1:0]    CorrQmShifted;              // the shifted divsqrt result after one bit shift
+    logic                       ResSubnorm;                 // is the result Subnormal
+    logic                       LZAPlus1;                   // add one or two to the sum's exponent due to LZA correction
+    logic                       LeftShiftQm;                // should the divsqrt result be shifted one to the left
 
     // LZA correction
     assign LZAPlus1 = Shifted[`NORMSHIFTSZ-1];
@@ -61,8 +63,9 @@ module shiftcorrection(
     // correct the shifting of the divsqrt caused by producing a result in (2, .5] range
     //    condition: if the msb is 1 or the exponent was one, but the shifted quotent was < 1 (Subnorm)
     assign LeftShiftQm = (LZAPlus1|(DivQe==1&~LZAPlus1));
-    mux2 #(`CORRSHIFTSZ) divcorrmux(Shifted[`NORMSHIFTSZ-3:`NORMSHIFTSZ-`CORRSHIFTSZ-2], 
-        Shifted[`NORMSHIFTSZ-2:`NORMSHIFTSZ-`CORRSHIFTSZ-1], LeftShiftQm, CorrQmShifted);
+    assign CorrQm0 = Shifted[`NORMSHIFTSZ-3:`NORMSHIFTSZ-`CORRSHIFTSZ-2];
+    assign CorrQm1 = Shifted[`NORMSHIFTSZ-2:`NORMSHIFTSZ-`CORRSHIFTSZ-1];
+    mux2 #(`CORRSHIFTSZ) divcorrmux(CorrQm0, CorrQm1, LeftShiftQm, CorrQmShifted);
     
     // if the result of the divider was calculated to be subnormal, then the result was correctly normalized, so select the top shifted bits
     always_comb

From fdcb1f08ce884fa23e2ab0844044f85c02cb973a Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Thu, 12 Jan 2023 07:41:30 -0800
Subject: [PATCH 5/5] Privileged unit formatting

---
 pipelined/src/privileged/privileged.sv | 89 ++++++++++----------------
 1 file changed, 34 insertions(+), 55 deletions(-)

diff --git a/pipelined/src/privileged/privileged.sv b/pipelined/src/privileged/privileged.sv
index 0acc8c152..1a2b8a320 100644
--- a/pipelined/src/privileged/privileged.sv
+++ b/pipelined/src/privileged/privileged.sv
@@ -30,7 +30,8 @@
 // *** remove signals not needed by PMA/PMP now that it is moved
 module privileged (
   input  logic             clk, reset,
-  input  logic             FlushD, FlushE, FlushM, FlushW, StallD, StallE, StallM, StallW,
+  input  logic             StallD, StallE, StallM, StallW,
+  input  logic             FlushD, FlushE, FlushM, FlushW, 
 (* mark_debug = "true" *)  input  logic             CSRReadM, CSRWriteM,
   input  logic [`XLEN-1:0] SrcAM,
   input  logic [`XLEN-1:0] PCM, PCNext2F,
@@ -44,7 +45,7 @@ module privileged (
   input  logic 		         DirPredictionWrongM,
   input  logic 		         BTBPredPCWrongM,
   input  logic 		         RASPredPCWrongM,
-  input  logic 		          PredictionInstrClassWrongM,
+  input  logic 		         PredictionInstrClassWrongM,
   input  logic [4:0]       InstrClassM,
   input  logic             DCacheMiss,
   input  logic             DCacheAccess,
@@ -101,69 +102,47 @@ module privileged (
   logic       DelegateM;
   logic       wfiM, IntPendingM;
 
-  ///////////////////////////////////////////
   // track the current privilege level
-  ///////////////////////////////////////////
-
   privmode privmode(.clk, .reset, .StallW, .TrapM, .mretM, .sretM, .DelegateM,
-                    .STATUS_MPP, .STATUS_SPP, .NextPrivilegeModeM, .PrivilegeModeW);
+    .STATUS_MPP, .STATUS_SPP, .NextPrivilegeModeM, .PrivilegeModeW);
 
-  ///////////////////////////////////////////
   // decode privileged instructions
-  ///////////////////////////////////////////
+  privdec pmd(.clk, .reset, .StallM, .InstrM(InstrM[31:20]), 
+    .PrivilegedM, .IllegalIEUInstrFaultM, .IllegalCSRAccessM, .IllegalFPUInstrM, 
+    .PrivilegeModeW, .STATUS_TSR, .STATUS_TVM, .STATUS_TW, .IllegalInstrFaultM, 
+    .EcallFaultM, .BreakpointFaultM, .sretM, .mretM, .wfiM, .sfencevmaM);
 
-   privdec pmd(.clk, .reset, .StallM, .InstrM(InstrM[31:20]), 
-              .PrivilegedM, .IllegalIEUInstrFaultM, .IllegalCSRAccessM, .IllegalFPUInstrM, 
-              .PrivilegeModeW, .STATUS_TSR, .STATUS_TVM, .STATUS_TW, .IllegalInstrFaultM, 
-              .EcallFaultM, .BreakpointFaultM,
-              .sretM, .mretM, .wfiM, .sfencevmaM);
-
-  ///////////////////////////////////////////
   // Control and Status Registers
-  ///////////////////////////////////////////
-  csr csr(.clk, .reset,
-          .FlushM, .FlushW,
-          .StallE, .StallM, .StallW,
-          .InstrM, .PCM, .SrcAM, .IEUAdrM, .PCNext2F,
-          .CSRReadM, .CSRWriteM, .TrapM, .mretM, .sretM, .wfiM, .IntPendingM, .InterruptM,
-          .MTimerInt, .MExtInt, .SExtInt, .MSwInt,
-          .MTIME_CLINT, 
-          .InstrValidM, .FRegWriteM, .LoadStallD,
-          .DirPredictionWrongM, .BTBPredPCWrongM, .RASPredPCWrongM, 
-          .PredictionInstrClassWrongM, .InstrClassM, .DCacheMiss, .DCacheAccess, .ICacheMiss, .ICacheAccess,
-          .NextPrivilegeModeM, .PrivilegeModeW,
-          .CauseM, .SelHPTW,
-          .STATUS_MPP,
-          .STATUS_SPP, .STATUS_TSR, .STATUS_TVM,
-          .MEDELEG_REGW, 
-          .SATP_REGW,
-          .MIP_REGW, .MIE_REGW, .MIDELEG_REGW,
-          .STATUS_MIE, .STATUS_SIE,
-          .STATUS_MXR, .STATUS_SUM, .STATUS_MPRV, .STATUS_TW, .STATUS_FS,
-          .PMPCFG_ARRAY_REGW,
-          .PMPADDR_ARRAY_REGW,
-          .SetFflagsM,
-          .FRM_REGW, 
-          .CSRReadValW,.UnalignedPCNextF,
-          .IllegalCSRAccessM, .BigEndianM);
+  csr csr(.clk, .reset, .FlushM, .FlushW, .StallE, .StallM, .StallW,
+    .InstrM, .PCM, .SrcAM, .IEUAdrM, .PCNext2F,
+    .CSRReadM, .CSRWriteM, .TrapM, .mretM, .sretM, .wfiM, .IntPendingM, .InterruptM,
+    .MTimerInt, .MExtInt, .SExtInt, .MSwInt,
+    .MTIME_CLINT, .InstrValidM, .FRegWriteM, .LoadStallD,
+    .DirPredictionWrongM, .BTBPredPCWrongM, .RASPredPCWrongM, 
+    .PredictionInstrClassWrongM, .InstrClassM, .DCacheMiss, .DCacheAccess, .ICacheMiss, .ICacheAccess,
+    .NextPrivilegeModeM, .PrivilegeModeW, .CauseM, .SelHPTW,
+    .STATUS_MPP, .STATUS_SPP, .STATUS_TSR, .STATUS_TVM,
+    .STATUS_MIE, .STATUS_SIE, .STATUS_MXR, .STATUS_SUM, .STATUS_MPRV, .STATUS_TW, .STATUS_FS,
+    .MEDELEG_REGW, .MIP_REGW, .MIE_REGW, .MIDELEG_REGW,
+    .SATP_REGW, .PMPCFG_ARRAY_REGW, .PMPADDR_ARRAY_REGW,
+    .SetFflagsM, .FRM_REGW, 
+    .CSRReadValW,.UnalignedPCNextF, .IllegalCSRAccessM, .BigEndianM);
 
+  // pipeline early-arriving trap sources
   privpiperegs ppr(.clk, .reset, .StallD, .StallE, .StallM, .FlushD, .FlushE, .FlushM,
-                  .InstrPageFaultF, .InstrAccessFaultF, .IllegalIEUInstrFaultD, 
-                  .InstrPageFaultM, .InstrAccessFaultM, .IllegalIEUInstrFaultM);
+    .InstrPageFaultF, .InstrAccessFaultF, .IllegalIEUInstrFaultD, 
+    .InstrPageFaultM, .InstrAccessFaultM, .IllegalIEUInstrFaultM);
 
+  // trap logic
   trap trap(.reset,
-            .InstrMisalignedFaultM, .InstrAccessFaultM, .HPTWInstrAccessFaultM, .IllegalInstrFaultM,
-            .BreakpointFaultM, .LoadMisalignedFaultM, .StoreAmoMisalignedFaultM,
-            .LoadAccessFaultM, .StoreAmoAccessFaultM, .EcallFaultM, .InstrPageFaultM,
-            .LoadPageFaultM, .StoreAmoPageFaultM,
-            .mretM, .sretM, 
-            .PrivilegeModeW, 
-            .MIP_REGW, .MIE_REGW, .MIDELEG_REGW, .MEDELEG_REGW,
-            .STATUS_MIE, .STATUS_SIE,
-            .InstrValidM, .CommittedM, .CommittedF,
-            .TrapM, .RetM, .wfiM,
-            .InterruptM, .IntPendingM, .DelegateM, .WFIStallM,
-            .CauseM);
+    .InstrMisalignedFaultM, .InstrAccessFaultM, .HPTWInstrAccessFaultM, .IllegalInstrFaultM,
+    .BreakpointFaultM, .LoadMisalignedFaultM, .StoreAmoMisalignedFaultM,
+    .LoadAccessFaultM, .StoreAmoAccessFaultM, .EcallFaultM, .InstrPageFaultM,
+    .LoadPageFaultM, .StoreAmoPageFaultM,
+    .mretM, .sretM, .PrivilegeModeW, 
+    .MIP_REGW, .MIE_REGW, .MIDELEG_REGW, .MEDELEG_REGW, .STATUS_MIE, .STATUS_SIE,
+    .InstrValidM, .CommittedM, .CommittedF,
+    .TrapM, .RetM, .wfiM, .InterruptM, .IntPendingM, .DelegateM, .WFIStallM, .CauseM);
 endmodule