sigmap: comments

kernel/sigtools.h

@@ -229,6 +229,13 @@ using sort_by_name_id_guard = typename std::enable_if<std::is_same<T,RTLIL::Cell
 template<typename T>
 class SigSet<T, sort_by_name_id_guard<T>> : public SigSet<T, RTLIL::sort_by_name_id<typename std::remove_pointer<T>::type>> {};
 
+/**
+ * SigMap wraps a union-find "database"
+ * to map SigBits of a module to canonical representative SigBits.
+ * SigBits that are connected share a set in the underlying database.
+ * If a SigBit has a const state (impl: bit.wire is nullptr),
+ * it's promoted to a representative.
+ */
 struct SigMap
 {
 	mfp<SigBit> database;
@@ -249,6 +256,7 @@ struct SigMap
 		database.clear();
 	}
 
+	// Rebuild SigMap for all connections in module
 	void set(RTLIL::Module *module)
 	{
 		int bitcount = 0;
@@ -262,6 +270,7 @@ struct SigMap
 			add(it.first, it.second);
 	}
 
+	// Add connections from "from" to "to", bit-by-bit
 	void add(const RTLIL::SigSpec& from, const RTLIL::SigSpec& to)
 	{
 		log_assert(GetSize(from) == GetSize(to));
@@ -287,6 +296,7 @@ struct SigMap
 		}
 	}
 
+	// Add sig as disconnected from anything
 	void add(const RTLIL::SigBit &bit)
 	{
 		const auto &b = database.find(bit);
@@ -302,6 +312,7 @@ struct SigMap
 
 	inline void add(Wire *wire) { return add(RTLIL::SigSpec(wire)); }
 
+	// Modify bit to its representative
 	void apply(RTLIL::SigBit &bit) const
 	{
 		bit = database.find(bit);
@@ -332,6 +343,7 @@ struct SigMap
 		return sig;
 	}
 
+	// All non-const bits
 	RTLIL::SigSpec allbits() const
 	{
 		RTLIL::SigSpec sig;