From 39ff4425fe8f631fc1ea871acd2c747c1aba0d6f Mon Sep 17 00:00:00 2001
From: Akash Levy <akash@silimate.com>
Date: Fri, 20 Dec 2024 13:21:25 -0800
Subject: [PATCH] Small muxadd comments

---
 passes/pmgen/peepopt_muxadd.pmg | 32 ++++++++++++++++++++------------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/passes/pmgen/peepopt_muxadd.pmg b/passes/pmgen/peepopt_muxadd.pmg
index f534dd42df5..931aa0701fb 100644
--- a/passes/pmgen/peepopt_muxadd.pmg
+++ b/passes/pmgen/peepopt_muxadd.pmg
@@ -13,12 +13,18 @@ state <IdString> add_a_id add_b_id mux_a_id mux_b_id
 match add
 	// Select adder
 	select add->type == $add
+
+	// Set ports, allowing A and B to be swapped
 	choice <IdString> A {\A, \B}
 	define <IdString> B (A == \A ? \B : \A)
-	set add_y port(add, \Y)
 	set add_a port(add, A)
 	set add_b port(add, B)
+	set add_y port(add, \Y)
+
+	// Get signedness
 	set add_a_signed param(add, (A == \A) ? \A_SIGNED : \B_SIGNED)
+
+	// Choice ids
 	set add_a_id A
 	set add_b_id B
 endmatch
@@ -27,15 +33,15 @@ code add_y add_a add_b add_a_ext
 	// Get adder signals
 	add_a_ext = SigSpec(port(add, add_a_id));
 	add_a_ext.extend_u0(GetSize(add_y), add_a_signed.as_bool());
+
 	// Fanout of each adder Y bit should be 1 (no bit-split)
 	if (nusers(add_y) != 2)
 		reject;
-
 endcode
 
 match mux 
-	// Select mux of form s ? (a + b) : a, allow leading 0s when A_WIDTH != Y_WIDTH
-	// or s ? a : (a + b)
+	// Select mux of form: s ? (a + b) : a
+	// Allow leading 0s when A_WIDTH != Y_WIDTH or s ? a : (a + b)
 	select mux->type == $mux
 	choice <IdString> AB {\A, \B}
 	define <IdString> BA (AB == \A ? \B : \A)
@@ -56,13 +62,14 @@ code add_y add_a add_b add_a_ext add_a_id add_b_id  mux_y mux_a mux_b mux_a_id m
 		adder_y_name = add_y.as_wire()->name.c_str();
 	else
 		adder_y_name = add_y.as_string();
-	
-	// Rewire
 
-	// Start by renaming the lhs of an eventual assign stmt where the rhs is the adder output (That is getting rewired).
-	// Renaming the signal allows equiv_opt to function as it would otherwize try to match the functionality witch would fail
-	// as the lhs signal has indeed changed function.
-	// Adder output could be assigned...
+	// Start by renaming the LHS of an eventual assign statement
+	// where the RHS is the adder output (that is getting rewired).
+	// Renaming the signal allows equiv_opt to function as it would
+	// otherwise try to match the functionality which would fail
+	// as the LHS signal has indeed changed function.
+
+	// Adder output could be assigned
 	for (auto it = module->connections().begin(); it != module->connections().end(); ++it) {
 		RTLIL::SigSpec rhs = it->second;
 		const std::string& rhs_name = rhs.as_wire()->name.c_str();
@@ -73,7 +80,7 @@ code add_y add_a add_b add_a_ext add_a_id add_b_id  mux_y mux_a mux_b mux_a_id m
 			break;
 		}
 	}
-	// ...or the port name could be a wire name
+	// Alternatively, the port name could be a wire name
 	if (add_y.is_wire()) {
 		if (adder_y_name.size()) {
 			if (adder_y_name[0] != '$') {
@@ -94,6 +101,7 @@ code add_y add_a add_b add_a_ext add_a_id add_b_id  mux_y mux_a mux_b mux_a_id m
 	// Create new mid wire
 	mid = module->addWire(NEW_ID, GetSize(add_b));
 
+	// Connect ports
 	add->setPort(add_b_id, mid);
 	add->setPort(add_a_id, add_a);
 	add->setPort(\Y, add_y);
@@ -101,11 +109,11 @@ code add_y add_a add_b add_a_ext add_a_id add_b_id  mux_y mux_a mux_b mux_a_id m
 	mux->setPort(mux_b_id, add_b);
 	mux->setPort(\Y, mid);
 	module->connect(mux_y, add_y);
+
 	// Log, fixup, accept
 	log("muxadd pattern in %s: mux=%s, add=%s\n", log_id(module), log_id(mux), log_id(add));
 	add->fixup_parameters();
 	mux->fixup_parameters();
 	did_something = true;
 	accept;
-	
 endcode