Sink gated-clock enables into ops across module boundaries. More...

#include <GatedClockConversion.h>

Collaboration diagram for circt::firrtl::GatedClockConversion:

[legend]

Classes
struct	ClockPairPlan
	(baseClk, enable) pair planned for a clock value. More...

struct	EnableNode
	Enable accumulation DAG node: value(id) = parent == kNoEnable ? term : (value(parent) & term) Nodes are shared by every consumer of a pair, so a cascade of gates emits one `and` per gate no matter how many roots it feeds. More...

struct	InstanceDrive
	Caller-side connects driving a planned input port pair. More...

class	MatRef
	A reference to a clock/enable value that can also name values which do not exist yet (a planned port, a planned wire). More...

struct	PortPairPlan
	(baseClock, enable) port pair to append to a module. More...

struct	RootRewrite
	Root rewrite applied by `applyPlan()`: clock the op by `baseClk` and sink `enableId` into it. More...

struct	WirePairPlan
	Temporary (base clock, enable) carrier wires at the top of `mod`, standing in for a wire/node alias of a gated clock. More...

Public Member Functions
	GatedClockConversion (InstanceGraph &ig)

LogicalResult	addRoot (Operation *op)

LogicalResult	run ()

void	dump () const

Private Types
using	PortPlanKey = std::pair< FModuleOp, unsigned >
	The `(module, clock port index)` key of a `PortPairPlan`.

Private Member Functions
LogicalResult	analyzeFrom (ArrayRef< Value > seeds)

void	computeGatedClocks ()

void	plan ()

Value	processEdge (const ClockEdge &edge, Value srcClk, FModuleOp srcMod, MatRef baseClk, unsigned enableId)

unsigned	newEnableNode (unsigned parent, MatRef term, Location loc, MatRef anchor)

unsigned	newEnableLeaf (MatRef term, Location loc)

LogicalResult	applyPlan ()

void	createPlannedWires ()

void	insertPlannedPorts ()

LogicalResult	emitPlannedIR ()

Value	resolve (MatRef ref)

Value	lower (unsigned enableId)

LogicalResult	rewriteRoot (Operation *op, Value baseClk, Value enable)

Value	gateEnableOf (ClockGateIntrinsicOp gate)

Value	getOrCreateConstU1One (FModuleOp mod)

void	connectMaterializedToInstancePorts (InstanceOp inst, unsigned clkPortIndex, unsigned enPortIndex, Value materializedClk, Value materializedEn)

void	eliminateTemporaryWires ()

Operation *	liveInstance (Operation *inst) const

void	dumpPlan () const

void	planAlias (Value dstClk, FModuleOp srcMod, MatRef baseClk, unsigned enableId)

void	planGate (ClockGateIntrinsicOp gate, Value dstClk, MatRef baseClk, unsigned enableId)

void	planInstancePort (Direction dir, InstanceOp inst, Value dstClk, Value srcClk, MatRef baseClk, unsigned enableId)

void	planMultiplyInstantiatedInput (Value srcClk, MatRef baseClk, unsigned enableId)

std::pair< unsigned, unsigned >	planGatedPorts (InstanceOp inst, FModuleOp childMod, unsigned gatedClkIndex, Direction dir, MatRef baseClk, unsigned enableId)

void	recordInstanceDrive (InstanceOp inst, const PortPairPlan &plan, MatRef baseClk, unsigned enableId)

Private Attributes
InstanceGraph &	ig

SmallVector< std::pair< Operation *, Value > >	roots

DenseSet< Value >	visited

DenseMap< Value, SmallVector< ClockEdge > >	srcToDstClocks

SmallVector< Value >	baseClks

DenseSet< Value >	gatedClocks

DenseMap< Value, ClockPairPlan >	clockEnablePairs

SmallVector< EnableNode >	enableNodes

SmallVector< Value >	plannedWireValues

SmallVector< Value >	loweredEnables

SmallVector< RootRewrite >	rootRewrites

SmallVector< WirePairPlan >	wirePlans

llvm::MapVector< PortPlanKey, PortPairPlan >	portPlans

llvm::MapVector< FModuleOp, SmallVector< PortPlanKey > >	plansPerModule

DenseMap< FModuleOp, unsigned >	nextPortIdx

llvm::MapVector< std::pair< InstanceOp, unsigned >, InstanceDrive >	instanceDrives

DenseMap< ClockGateIntrinsicOp, Value >	gateEnableCache

DenseMap< FModuleOp, Value >	constU1Cache

DenseMap< Operation , Operation >	instClones

SmallVector< InstanceOp >	deadInstances

SmallVector< WireOp >	wireOps

MLIRContext *	context

Type	clockType

Type	u1Type

Static Private Attributes
static constexpr unsigned	kNoEnable = ~0u
	Sentinel `EnableNode` index meaning "no enable at all".

Detailed Description

Sink gated-clock enables into ops across module boundaries.

Backward traversal from each root's clock builds the clock flow graph, a forward pass plans the (base, AND-of-enables) pair of every clock value, and applyPlan() then materializes the whole plan in one shot.

Invariant: analysis and planning never mutate the IR, and no plan record is read after the mutation it describes happened. That is what makes stale value remapping structurally impossible; see MatRef.

Preconditions: run after firrtl-expand-whens, so every clock net and register has a single driver. Clock loops are not diagnosed here; see firrtl-check-comb-loops.

NOT thread-safe: port insertion mutates module signatures globally.

Definition at line 50 of file GatedClockConversion.h.

Member Typedef Documentation

◆ PortPlanKey

using circt::firrtl::GatedClockConversion::PortPlanKey = std::pair<FModuleOp, unsigned>

private

The (module, clock port index) key of a PortPairPlan.

Definition at line 180 of file GatedClockConversion.h.

Constructor & Destructor Documentation

◆ GatedClockConversion()

circt::firrtl::GatedClockConversion::GatedClockConversion ( InstanceGraph & ig )

inlineexplicit

Definition at line 52 of file GatedClockConversion.h.

Member Function Documentation

◆ addRoot()

LogicalResult GatedClockConversion::addRoot ( Operation * op )

Definition at line 229 of file GatedClockConversion.cpp.

References circt::firrtl::clk, and roots.

◆ analyzeFrom()

LogicalResult GatedClockConversion::analyzeFrom ( ArrayRef< Value > seeds )

private

Definition at line 240 of file GatedClockConversion.cpp.

References circt::firrtl::Alias, assert(), baseClks, circt::firrtl::clk, circt::firrtl::Gate, circt::firrtl::getModuleScopedDriver(), ig, circt::firrtl::In, circt::firrtl::InstanceIn, circt::firrtl::InstanceOut, circt::igraph::InstanceGraph::lookup(), srcToDstClocks, and visited.

Referenced by run().

◆ applyPlan()

LogicalResult GatedClockConversion::applyPlan ( )

private

Definition at line 765 of file GatedClockConversion.cpp.

References createPlannedWires(), emitPlannedIR(), and insertPlannedPorts().

Referenced by run().

◆ computeGatedClocks()

void GatedClockConversion::computeGatedClocks ( )

private

Definition at line 566 of file GatedClockConversion.cpp.

References circt::firrtl::clk, circt::firrtl::Gate, gatedClocks, and srcToDstClocks.

Referenced by run().

◆ connectMaterializedToInstancePorts()

void GatedClockConversion::connectMaterializedToInstancePorts	(	InstanceOp	inst,
		unsigned	clkPortIndex,
		unsigned	enPortIndex,
		Value	materializedClk,
		Value	materializedEn
	)

private

Definition at line 209 of file GatedClockConversion.cpp.

References context, and getOrCreateConstU1One().

Referenced by emitPlannedIR().

◆ createPlannedWires()

void GatedClockConversion::createPlannedWires ( )

private

Definition at line 661 of file GatedClockConversion.cpp.

References clockType, plannedWireValues, u1Type, wireOps, and wirePlans.

Referenced by applyPlan().

◆ dump()

void GatedClockConversion::dump ( ) const

Definition at line 884 of file GatedClockConversion.cpp.

References baseClks, and srcToDstClocks.

Referenced by run().

◆ dumpPlan()

void GatedClockConversion::dumpPlan ( ) const

private

Definition at line 912 of file GatedClockConversion.cpp.

References enableNodes, circt::firrtl::In, instanceDrives, kNoEnable, circt::firrtl::Out, portPlans, rootRewrites, and wirePlans.

Referenced by run().

◆ eliminateTemporaryWires()

void GatedClockConversion::eliminateTemporaryWires ( )

private

Definition at line 771 of file GatedClockConversion.cpp.

References wireOps.

Referenced by run().

◆ emitPlannedIR()

LogicalResult GatedClockConversion::emitPlannedIR ( )

private

Definition at line 716 of file GatedClockConversion.cpp.

References connectMaterializedToInstancePorts(), context, instanceDrives, liveInstance(), lower(), circt::firrtl::Out, plannedWireValues, portPlans, resolve(), rewriteRoot(), rootRewrites, and wirePlans.

Referenced by applyPlan().

◆ gateEnableOf()

Value GatedClockConversion::gateEnableOf ( ClockGateIntrinsicOp gate )

private

Definition at line 186 of file GatedClockConversion.cpp.

References gateEnableCache.

Referenced by resolve().

◆ getOrCreateConstU1One()

Value GatedClockConversion::getOrCreateConstU1One ( FModuleOp mod )

private

Definition at line 195 of file GatedClockConversion.cpp.

References constU1Cache, and context.

Referenced by connectMaterializedToInstancePorts().

◆ insertPlannedPorts()

void GatedClockConversion::insertPlannedPorts ( )

private

Definition at line 677 of file GatedClockConversion.cpp.

References assert(), circt::firrtl::GatedClockConversion::PortPairPlan::baseIdx, clockType, context, deadInstances, circt::firrtl::GatedClockConversion::PortPairPlan::dir, circt::firrtl::GatedClockConversion::PortPairPlan::gatedClkIndex, ig, instClones, circt::igraph::InstanceGraph::lookup(), plansPerModule, portPlans, circt::igraph::InstanceGraph::replaceInstance(), and u1Type.

Referenced by applyPlan().

◆ liveInstance()

Operation * circt::firrtl::GatedClockConversion::liveInstance ( Operation * inst ) const

inlineprivate

Definition at line 272 of file GatedClockConversion.h.

References instClones.

Referenced by emitPlannedIR(), and resolve().

◆ lower()

Value GatedClockConversion::lower ( unsigned enableId )

private

Definition at line 147 of file GatedClockConversion.cpp.

References circt::firrtl::GatedClockConversion::EnableNode::anchor, assert(), context, enableNodes, kNoEnable, circt::firrtl::GatedClockConversion::EnableNode::loc, loweredEnables, circt::firrtl::GatedClockConversion::EnableNode::parent, resolve(), and circt::firrtl::GatedClockConversion::EnableNode::term.

Referenced by emitPlannedIR().

◆ newEnableLeaf()

unsigned circt::firrtl::GatedClockConversion::newEnableLeaf	(	MatRef	term,
		Location	loc
	)

inlineprivate

Definition at line 225 of file GatedClockConversion.h.

References kNoEnable, and newEnableNode().

Referenced by planAlias(), and planInstancePort().

◆ newEnableNode()

unsigned GatedClockConversion::newEnableNode	(	unsigned	parent,
		MatRef	term,
		Location	loc,
		MatRef	anchor
	)

private

Definition at line 141 of file GatedClockConversion.cpp.

References enableNodes.

Referenced by newEnableLeaf(), and planGate().

◆ plan()

void GatedClockConversion::plan ( )

private

Definition at line 622 of file GatedClockConversion.cpp.

References assert(), baseClks, clockEnablePairs, kNoEnable, circt::firrtl::GatedClockConversion::MatRef::of(), processEdge(), and srcToDstClocks.

Referenced by planGatedPorts(), recordInstanceDrive(), and run().

◆ planAlias()

void GatedClockConversion::planAlias	(	Value	dstClk,
		FModuleOp	srcMod,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 426 of file GatedClockConversion.cpp.

References clockEnablePairs, kNoEnable, newEnableLeaf(), circt::firrtl::GatedClockConversion::MatRef::plannedWire(), and wirePlans.

Referenced by processEdge().

◆ planGate()

void GatedClockConversion::planGate	(	ClockGateIntrinsicOp	gate,
		Value	dstClk,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 441 of file GatedClockConversion.cpp.

References clockEnablePairs, circt::firrtl::GatedClockConversion::MatRef::gateEnable(), newEnableNode(), and circt::firrtl::GatedClockConversion::MatRef::of().

Referenced by processEdge().

◆ planGatedPorts()

std::pair< unsigned, unsigned > GatedClockConversion::planGatedPorts	(	InstanceOp	inst,
		FModuleOp	childMod,
		unsigned	gatedClkIndex,
		Direction	dir,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 469 of file GatedClockConversion.cpp.

References assert(), circt::firrtl::In, kNoEnable, nextPortIdx, circt::firrtl::Out, plan(), plansPerModule, portPlans, and recordInstanceDrive().

Referenced by planInstancePort().

◆ planInstancePort()

void GatedClockConversion::planInstancePort	(	Direction	dir,
		InstanceOp	inst,
		Value	dstClk,
		Value	srcClk,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 499 of file GatedClockConversion.cpp.

References assert(), clockEnablePairs, gatedClocks, ig, circt::firrtl::GatedClockConversion::MatRef::instResult(), kNoEnable, circt::firrtl::GatedClockConversion::MatRef::moduleArg(), newEnableLeaf(), circt::firrtl::GatedClockConversion::MatRef::of(), circt::firrtl::Out, and planGatedPorts().

Referenced by processEdge().

◆ planMultiplyInstantiatedInput()

void GatedClockConversion::planMultiplyInstantiatedInput	(	Value	srcClk,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 546 of file GatedClockConversion.cpp.

References assert(), ig, portPlans, and recordInstanceDrive().

Referenced by processEdge().

◆ processEdge()

Value GatedClockConversion::processEdge	(	const ClockEdge &	edge,
		Value	srcClk,
		FModuleOp	srcMod,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 588 of file GatedClockConversion.cpp.

References circt::firrtl::Alias, assert(), clockEnablePairs, circt::firrtl::ClockEdge::dst, circt::firrtl::Gate, circt::firrtl::ClockEdge::gate(), circt::firrtl::In, circt::firrtl::ClockEdge::instance(), circt::firrtl::InstanceIn, circt::firrtl::InstanceOut, circt::firrtl::ClockEdge::kind, circt::firrtl::Out, planAlias(), planGate(), planInstancePort(), and planMultiplyInstantiatedInput().

Referenced by plan().

◆ recordInstanceDrive()

void GatedClockConversion::recordInstanceDrive	(	InstanceOp	inst,
		const PortPairPlan &	plan,
		MatRef	baseClk,
		unsigned	enableId
	)

private

Definition at line 450 of file GatedClockConversion.cpp.

References assert(), circt::firrtl::GatedClockConversion::InstanceDrive::baseIdx, circt::firrtl::In, instanceDrives, and plan().

Referenced by planGatedPorts(), and planMultiplyInstantiatedInput().

◆ resolve()

Value GatedClockConversion::resolve ( MatRef ref )

private

Definition at line 121 of file GatedClockConversion.cpp.

Referenced by emitPlannedIR(), and lower().

◆ rewriteRoot()

LogicalResult GatedClockConversion::rewriteRoot	(	Operation *	op,
		Value	baseClk,
		Value	enable
	)

private

Definition at line 363 of file GatedClockConversion.cpp.

Referenced by emitPlannedIR().

◆ run()

LogicalResult GatedClockConversion::run ( )

Definition at line 822 of file GatedClockConversion.cpp.

References analyzeFrom(), applyPlan(), circt::firrtl::clk, clockEnablePairs, clockType, computeGatedClocks(), context, deadInstances, dump(), dumpPlan(), eliminateTemporaryWires(), plan(), rootRewrites, roots, and u1Type.

Member Data Documentation

◆ baseClks

SmallVector<Value> circt::firrtl::GatedClockConversion::baseClks

private

Definition at line 313 of file GatedClockConversion.h.

Referenced by analyzeFrom(), dump(), and plan().

◆ clockEnablePairs

DenseMap<Value, ClockPairPlan> circt::firrtl::GatedClockConversion::clockEnablePairs

private

Definition at line 318 of file GatedClockConversion.h.

Referenced by plan(), planAlias(), planGate(), planInstancePort(), processEdge(), and run().

◆ clockType

Type circt::firrtl::GatedClockConversion::clockType

private

Definition at line 366 of file GatedClockConversion.h.

Referenced by createPlannedWires(), insertPlannedPorts(), and run().

◆ constU1Cache

DenseMap<FModuleOp, Value> circt::firrtl::GatedClockConversion::constU1Cache

private

Definition at line 353 of file GatedClockConversion.h.

Referenced by getOrCreateConstU1One().

◆ context

MLIRContext* circt::firrtl::GatedClockConversion::context

private

Definition at line 364 of file GatedClockConversion.h.

Referenced by connectMaterializedToInstancePorts(), emitPlannedIR(), getOrCreateConstU1One(), insertPlannedPorts(), lower(), and run().

◆ deadInstances

SmallVector<InstanceOp> circt::firrtl::GatedClockConversion::deadInstances

private

Definition at line 359 of file GatedClockConversion.h.

Referenced by insertPlannedPorts(), and run().

◆ enableNodes

SmallVector<EnableNode> circt::firrtl::GatedClockConversion::enableNodes

private

Definition at line 322 of file GatedClockConversion.h.

Referenced by dumpPlan(), lower(), and newEnableNode().

◆ gatedClocks

DenseSet<Value> circt::firrtl::GatedClockConversion::gatedClocks

private

Definition at line 316 of file GatedClockConversion.h.

Referenced by computeGatedClocks(), and planInstancePort().

◆ gateEnableCache

DenseMap<ClockGateIntrinsicOp, Value> circt::firrtl::GatedClockConversion::gateEnableCache

private

Definition at line 350 of file GatedClockConversion.h.

Referenced by gateEnableOf().

◆ ig

InstanceGraph& circt::firrtl::GatedClockConversion::ig

private

Definition at line 303 of file GatedClockConversion.h.

Referenced by analyzeFrom(), insertPlannedPorts(), planInstancePort(), and planMultiplyInstantiatedInput().

◆ instanceDrives

llvm::MapVector<std::pair<InstanceOp, unsigned>, InstanceDrive> circt::firrtl::GatedClockConversion::instanceDrives

private

Definition at line 346 of file GatedClockConversion.h.

Referenced by dumpPlan(), emitPlannedIR(), and recordInstanceDrive().

◆ instClones

DenseMap<Operation *, Operation *> circt::firrtl::GatedClockConversion::instClones

private

Definition at line 356 of file GatedClockConversion.h.

Referenced by insertPlannedPorts(), and liveInstance().

◆ kNoEnable

constexpr unsigned circt::firrtl::GatedClockConversion::kNoEnable = ~0u

staticconstexprprivate

Sentinel EnableNode index meaning "no enable at all".

Definition at line 64 of file GatedClockConversion.h.

Referenced by dumpPlan(), lower(), newEnableLeaf(), plan(), planAlias(), planGatedPorts(), and planInstancePort().

◆ loweredEnables

SmallVector<Value> circt::firrtl::GatedClockConversion::loweredEnables

private

Definition at line 329 of file GatedClockConversion.h.

Referenced by lower().

◆ nextPortIdx

DenseMap<FModuleOp, unsigned> circt::firrtl::GatedClockConversion::nextPortIdx

private

Definition at line 341 of file GatedClockConversion.h.

Referenced by planGatedPorts().

◆ plannedWireValues

SmallVector<Value> circt::firrtl::GatedClockConversion::plannedWireValues

private

Definition at line 326 of file GatedClockConversion.h.

Referenced by createPlannedWires(), emitPlannedIR(), and resolve().

◆ plansPerModule

llvm::MapVector<FModuleOp, SmallVector<PortPlanKey> > circt::firrtl::GatedClockConversion::plansPerModule

private

Definition at line 338 of file GatedClockConversion.h.

Referenced by insertPlannedPorts(), and planGatedPorts().

◆ portPlans

llvm::MapVector<PortPlanKey, PortPairPlan> circt::firrtl::GatedClockConversion::portPlans

private

Definition at line 337 of file GatedClockConversion.h.

Referenced by dumpPlan(), emitPlannedIR(), insertPlannedPorts(), planGatedPorts(), and planMultiplyInstantiatedInput().

◆ rootRewrites

SmallVector<RootRewrite> circt::firrtl::GatedClockConversion::rootRewrites

private

Definition at line 331 of file GatedClockConversion.h.

Referenced by dumpPlan(), emitPlannedIR(), and run().

◆ roots

SmallVector<std::pair<Operation *, Value> > circt::firrtl::GatedClockConversion::roots

private

Definition at line 305 of file GatedClockConversion.h.

Referenced by addRoot(), and run().

◆ srcToDstClocks

DenseMap<Value, SmallVector<ClockEdge> > circt::firrtl::GatedClockConversion::srcToDstClocks

private

Definition at line 311 of file GatedClockConversion.h.

Referenced by analyzeFrom(), computeGatedClocks(), dump(), and plan().

◆ u1Type

Type circt::firrtl::GatedClockConversion::u1Type

private

Definition at line 366 of file GatedClockConversion.h.

Referenced by createPlannedWires(), insertPlannedPorts(), and run().

◆ visited

DenseSet<Value> circt::firrtl::GatedClockConversion::visited

private

Definition at line 309 of file GatedClockConversion.h.

Referenced by analyzeFrom().

◆ wireOps

SmallVector<WireOp> circt::firrtl::GatedClockConversion::wireOps

private

Definition at line 362 of file GatedClockConversion.h.

Referenced by createPlannedWires(), and eliminateTemporaryWires().

◆ wirePlans

SmallVector<WirePairPlan> circt::firrtl::GatedClockConversion::wirePlans

private

Definition at line 333 of file GatedClockConversion.h.

Referenced by createPlannedWires(), dumpPlan(), emitPlannedIR(), and planAlias().

The documentation for this class was generated from the following files:

/home/runner/work/circt-www/circt-www/circt_src/include/circt/Dialect/FIRRTL/GatedClockConversion.h
/home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/FIRRTL/GatedClockConversion.cpp

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

◆ PortPlanKey

Constructor & Destructor Documentation

◆ GatedClockConversion()

Member Function Documentation

◆ addRoot()

◆ analyzeFrom()

◆ applyPlan()

◆ computeGatedClocks()

◆ connectMaterializedToInstancePorts()

◆ createPlannedWires()

◆ dump()

◆ dumpPlan()

◆ eliminateTemporaryWires()

◆ emitPlannedIR()

◆ gateEnableOf()

◆ getOrCreateConstU1One()

◆ insertPlannedPorts()

◆ liveInstance()

◆ lower()

◆ newEnableLeaf()

◆ newEnableNode()

◆ plan()

◆ planAlias()

◆ planGate()

◆ planGatedPorts()

◆ planInstancePort()

◆ planMultiplyInstantiatedInput()

◆ processEdge()

◆ recordInstanceDrive()

◆ resolve()

◆ rewriteRoot()

◆ run()

Member Data Documentation

◆ baseClks

◆ clockEnablePairs

◆ clockType

◆ constU1Cache

◆ context

◆ deadInstances

◆ enableNodes

◆ gatedClocks

◆ gateEnableCache

◆ ig

◆ instanceDrives

◆ instClones

◆ kNoEnable

◆ loweredEnables

◆ nextPortIdx

◆ plannedWireValues

◆ plansPerModule

◆ portPlans

◆ rootRewrites

◆ roots

◆ srcToDstClocks

◆ u1Type

◆ visited

◆ wireOps

◆ wirePlans