From 89fbb7c5b4ec33f7174bd29f214dc358cee6dffd Mon Sep 17 00:00:00 2001 From: em2machine <92717390+em2machine@users.noreply.github.com> Date: Mon, 22 Dec 2025 13:10:42 +0100 Subject: [PATCH] cleaned up comments --- src/V3UndrivenCapture.cpp | 7 ++++--- src/V3UndrivenCapture.h | 26 ++++++++++++++++---------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/src/V3UndrivenCapture.cpp b/src/V3UndrivenCapture.cpp index 958810c10..0b9e8af20 100644 --- a/src/V3UndrivenCapture.cpp +++ b/src/V3UndrivenCapture.cpp @@ -156,8 +156,7 @@ const std::vector& V3UndrivenCapture::computeWriteSummar UINFO(DBG, "undriven capture recursion detected at " << taskNameQ(taskp) << " returning directWrites size=" << info.directWrites.size()); - // Cycle detected. Simple behaviour: - // return directWrites only to guarantee termination. + // Cycle detected. return directWrites only to guarantee termination. if (info.writeSummary.empty()) info.writeSummary = info.directWrites; sortUniqueVars(info.writeSummary); return info.writeSummary; @@ -168,18 +167,20 @@ const std::vector& V3UndrivenCapture::computeWriteSummar // Start with direct writes info.writeSummary = info.directWrites; - // Union in callees + // Need callees for (FTask calleep : info.callees) { if (m_info.find(calleep) == m_info.end()) continue; const std::vector& sub = computeWriteSummary(calleep); info.writeSummary.insert(info.writeSummary.end(), sub.begin(), sub.end()); } + // Remove duplicates and sort because grabbing all of the callees can result in duplicates sortUniqueVars(info.writeSummary); UINFO(DBG, "undriven capture writeSummary computed size=" << info.writeSummary.size() << " for " << taskNameQ(taskp)); + // We are done, so set the m_info state correctly and return the vector of variables info.state = State::DONE; return info.writeSummary; } diff --git a/src/V3UndrivenCapture.h b/src/V3UndrivenCapture.h index e3803af6b..0c33bd199 100644 --- a/src/V3UndrivenCapture.h +++ b/src/V3UndrivenCapture.h @@ -32,6 +32,9 @@ public: using Var = AstVar*; // DFS computation state for writeSummary propagation. + // UNVISITED: write summary not computed yet + // VISITING: currently computing on the call stack - used to detect cycles + // DONE: write summary computed enum class State : uint8_t { UNVISITED, VISITING, DONE }; struct FTaskInfo final { @@ -39,24 +42,25 @@ public: std::vector directWrites; // Direct resolved callees from this task/function body. std::vector callees; - // 'write through write' writeSummary for the given task/function. + // 'write through write' writeSummary for the given task/function. Meaning ultimately everything that this function/task writes to. std::vector writeSummary; // state for writeSummary computation. State state = State::UNVISITED; }; + // Enable writeSummary computation. If disabled, then the existing V3Undriven behaviour is used. static bool enableWriteSummary; private: - // Per-task/function capture info keyed by resolved AstNodeFTask* identity. + // Per-task/function capture info keyed by resolved AstNodeFTask* identity (FTask = function or task). This is our 'graph' of tasks/functions. Each node has a list of direct callees and a list of variables written in the function body. There are methods to remove duplicates otherwise this could explode. std::unordered_map m_info; - // Sort and remove duplicates from a vector of variables. + // Sort and remove duplicates from a vector of variables. This is called after a task/function write summary is computed. writeSummary can accumulate duplicates if a variable is written in multiple tasks/functions. static void sortUniqueVars(std::vector& vec); - // Sort and remove duplicates from a vector of callees. + // Sort and remove duplicates from a vector of callees. The visitor can record the same callee multiple times (multiple call sites, branches, etc). static void sortUniqueFTasks(std::vector& vec); - // Collect direct writes and call edges for all tasks/functions. + // Collect direct writes and call edges for all tasks/functions. Run one time when UndrivenCapture is created. This runs the visitor over the tree. void gather(AstNetlist* netlistp); // Compute (and cache) 'write through write' writeSummary for the given task/function. const std::vector& computeWriteSummary(FTask taskp); @@ -65,18 +69,20 @@ public: // Build capture database and precompute writeSummary for all discovered tasks/functions. explicit V3UndrivenCapture(AstNetlist* netlistp); - // Lookup task/function capture info (nullptr if unknown). + // Lookup task/function capture info (nullptr if unknown). This is currently only used for the debug helper. const FTaskInfo* find(FTask taskp) const; - // Get write through write through write, etc (call chain) writeSummary for a task/function - // (creates empty entry if needed). + // Get write through write through write, etc (call chain) writeSummary for a task/function (creates empty entry if needed). This returns a vector of variables that a particular task/function writes to, including all variables written by functions called by this task/function, and so on. const std::vector& writeSummary(FTask taskp); - // used by the capture visitor + // used by the capture visitor to record information about tasks/functions and their statements and callees. + // noteTask() makes sure there is an entry for the given taskp. void noteTask(FTask taskp); + // inside the body of taskp there is a write to variable varp void noteDirectWrite(FTask taskp, Var varp); + // inside the body of callerp there is a call to calleep, this is needed so we can create a summary that includes all variables written by functions called by this task/function, and so on. void noteCallEdge(FTask callerp, FTask calleep); - // Optional: dump one task's summary (for debug bring-up). + // dump one task's summary for debugging. leaving this in, in case need to debug future functionality. void debugDumpTask(FTask taskp, int level = 9) const; };