coriolis/katabatic/doc/man/man3/Katabatic_KatabaticEngine.3

.TH "KatabaticEngine" 3 "Mon Apr 27 2020" "Version 1.0" "Katabatic - Routing Toolbox" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KatabaticEngine \- The \fBKatabatic\fP Tool\&.  

.SH SYNOPSIS
.br
.PP
.PP
Inherits \fBToolEngine\fP\&.
.SS "Public Types"

.in +1c
.ti -1c
.RI "typedef set< \fBNet\fP *, NetCompareByName > \fBNetSet\fP"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "bool \fBisGMetal\fP (const \fBLayer\fP *) const"
.br
.ti -1c
.RI "bool \fBisChip\fP () const"
.br
.ti -1c
.RI "bool \fBisInDemoMode\fP () const"
.br
.ti -1c
.RI "bool \fBdoWarnOnGCellOverload\fP () const"
.br
.ti -1c
.RI "bool \fBdoDestroyBaseContact\fP () const"
.br
.ti -1c
.RI "bool \fBdoDestroyBaseSegment\fP () const"
.br
.ti -1c
.RI "bool \fBdoDestroyTool\fP () const"
.br
.ti -1c
.RI "virtual const \fBName\fP & \fBgetName\fP () const"
.br
.ti -1c
.RI "\fBEngineState\fP \fBgetState\fP () const"
.br
.ti -1c
.RI "unsigned int \fBgetFlags\fP (unsigned int mask) const"
.br
.ti -1c
.RI "Configuration * \fBgetKatabaticConfiguration\fP ()"
.br
.ti -1c
.RI "virtual Configuration * \fBgetConfiguration\fP ()"
.br
.ti -1c
.RI "\fBRoutingGauge\fP * \fBgetRoutingGauge\fP () const"
.br
.ti -1c
.RI "\fBRoutingLayerGauge\fP * \fBgetLayerGauge\fP (size_t depth) const"
.br
.ti -1c
.RI "const \fBLayer\fP * \fBgetRoutingLayer\fP (size_t depth) const"
.br
.ti -1c
.RI "\fBLayer\fP * \fBgetContactLayer\fP (size_t depth) const"
.br
.ti -1c
.RI "\fBGCellGrid\fP * \fBgetGCellGrid\fP () const"
.br
.ti -1c
.RI "const \fBNetSet\fP & \fBgetRoutingNets\fP () const"
.br
.ti -1c
.RI "\fBDbU::Unit\fP \fBgetGlobalThreshold\fP () const"
.br
.ti -1c
.RI "float \fBgetSaturateRatio\fP () const"
.br
.ti -1c
.RI "size_t \fBgetSaturateRp\fP () const"
.br
.ti -1c
.RI "\fBDbU::Unit\fP \fBgetExtensionCap\fP () const"
.br
.ti -1c
.RI "const \fBChipTools\fP & \fBgetChipTools\fP () const"
.br
.ti -1c
.RI "void \fBxmlWriteGCellGrid\fP (ostream &)"
.br
.ti -1c
.RI "void \fBxmlWriteGCellGrid\fP (const string &)"
.br
.ti -1c
.RI "void \fBsetState\fP (\fBEngineState\fP state)"
.br
.ti -1c
.RI "void \fBsetFlags\fP (unsigned int)"
.br
.ti -1c
.RI "void \fBunsetFlags\fP (unsigned int)"
.br
.ti -1c
.RI "void \fBsetGlobalThreshold\fP (\fBDbU::Unit\fP)"
.br
.ti -1c
.RI "void \fBsetSaturateRatio\fP (float)"
.br
.ti -1c
.RI "void \fBsetSaturateRp\fP (size_t)"
.br
.ti -1c
.RI "void \fBprintMeasures\fP (const string &) const"
.br
.ti -1c
.RI "void \fBrefresh\fP (unsigned int flags=\fBKbOpenSession\fP)"
.br
.ti -1c
.RI "virtual void \fBcreateDetailedGrid\fP ()"
.br
.ti -1c
.RI "void \fBmakePowerRails\fP ()"
.br
.ti -1c
.RI "virtual void \fBloadGlobalRouting\fP (unsigned int method)"
.br
.ti -1c
.RI "void \fBslackenBorder\fP (\fBBox\fP bb, \fBLayer::Mask\fP, unsigned int flags)"
.br
.ti -1c
.RI "void \fBslackenBlockIos\fP (\fBInstance\fP *core)"
.br
.ti -1c
.RI "bool \fBmoveUpNetTrunk\fP (\fBAutoSegment\fP *, set< \fBNet\fP *> &globalNets, \fBGCell::SetIndex\fP &invalidateds)"
.br
.ti -1c
.RI "void \fBlayerAssign\fP (unsigned int method)"
.br
.ti -1c
.RI "void \fBcomputeNetConstraints\fP (\fBNet\fP *)"
.br
.ti -1c
.RI "void \fBtoOptimals\fP (\fBNet\fP *)"
.br
.ti -1c
.RI "virtual void \fBfinalizeLayout\fP ()"
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static \fBKatabaticEngine\fP * \fBcreate\fP (\fBCell\fP *)"
.br
.ti -1c
.RI "static const \fBName\fP & \fBstaticGetName\fP ()"
.br
.in -1c
.SH "Detailed Description"
.PP 
The \fBKatabatic\fP Tool\&. 


.SH "States of KatabaticEngine"
.PP
During it's lifecycle, the engine go through a serie of states\&. It only can go forward between states\&.
.IP "\(bu" 2
\fBEngineCreation\fP : just after C++ object creation until the global routing is loaded\&.
.IP "\(bu" 2
\fBEngineGlobalLoaded\fP : \fIafter\fP the global routing has been done\&. This state must be set by an external tool, \fBKatabatic\fP cannot know by itself when the global routing has been done (see Kite)\&.
.IP "\(bu" 2
\fBEngineActive\fP : \fIafter\fP the global routing has been converted into the \fBKatabatic\fP data structure\&. At this point the tool is ready to run\&.
.IP "\(bu" 2
\fBEngineDriving\fP : \fIduring\fP the stage of stripping all the decorations the tool has added over the Hurricane data structure (mostly: \fBAutoContact\fP & \fBAutoSegment\fP)\&.
.IP "\(bu" 2
\fBEngineGutted\fP : \fIafter\fP the tool decorations have been removed\&. The tool is now useless and can only be destroyed\&.
.IP "\(bu" 2
\fBEnginePreDestroying\fP : this special state is reached when going straight from EngineActive to the destructor, that is, skipping the EngineDriving state\&. That means we \fIdo not\fP want to save whatever routing has been done\&. In that case, not only the tool decorations are destroyeds, but also the Hurricane data-structures they relies on (Contact, Segments)\&.
.PP
.SH "KatabaticEngine Implementation Details"
.PP
Due to the size of the code and the fact that the main body of some methods do not need to be present in the class, the implementation of \fBKatabaticEngine\fP is split in several files\&. The list below summarize them:
.IP "\(bu" 2
\fCKatabaticEngine\&.cpp\fP : the core of the class, methods that really need their bodies here\&.
.IP "\(bu" 2
\fCPowerRails\&.cpp\fP : utilities to construct an abstract from all the power rails through the hierarchy\&.
.IP "\(bu" 2
\fCLayerAssign\&.cpp\fP : layer assignement related methods and helpers\&.
.IP "\(bu" 2
\fCLoadGrByNet\&.cpp\fP : global routing loader, transform global routing into \fBKatabatic\fP data-structure\&.
.IP "\(bu" 2
\fCNetConstraints\&.cpp\fP : compute the topological constraints of all AutoSegment/AutoContact of a Net\&.
.IP "\(bu" 2
\fCNetOptimals\&.cpp\fP : compute the optimal positions of all \fBAutoSegment\fP of a Net\&. 
.PP

.SH "Member Typedef Documentation"
.PP 
.SS "set< \fBNet\fP *, NetCompareByName > \fBNetSet\fP"
Set of Net to be routed, alphabetically sorteds\&. 
.SH "Member Function Documentation"
.PP 
.SS "\fBKatabaticEngine\fP * create (\fBCell\fP * cell)\fC [static]\fP"
Create a \fBKatabaticEngine\fP on \fCcell\fP\&. 
.SS "const \fBName\fP & staticGetName ()\fC [static]\fP"
\fBReturns:\fP The unique string identifier for the \fBKatabaticEngine\fP class of ToolEngine\&. 
.SS "bool isGMetal (const \fBLayer\fP * layer) const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if \fClayer\fP is one of the special (fake) metals used to build the global routing\&. 
.PP
Referenced by AutoSegment::create()\&.
.SS "bool isChip () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the hierarchy top-level of the Cell matches the one of a complete design (i\&.e\&. pads and one core instance)\&. 
.PP
References ChipTools::isChip()\&.
.SS "bool isInDemoMode () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the tool is in demo mode, that is suppress almost all warning and debug messages\&. 
.PP
Referenced by Session::isInDemoMode()\&.
.SS "bool doWarnOnGCellOverload () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the tool should issue a warning when a \fBGCell\fP is overloaded (overload could be transient)\&. 
.PP
Referenced by Session::doWarnGCellOverload()\&.
.SS "bool doDestroyBaseContact () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the EngineDestroyBaseContact is set, meaning that when an \fBAutoContact\fP is destroyed, the Contact it decorates is destroyed altogether\&. 
.SS "bool doDestroyBaseSegment () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the EngineDestroyBaseSegment is set, meaning that when an \fBAutoSegment\fP is destroyed, the Segment it decorates is destroyed altogether\&. 
.SS "bool doDestroyTool () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if the tool state is beyond EngineStateGutted, that is, only waits for \fC\fBdestroy()\fP\fP to be called\&. 
.PP
References Katabatic::EngineGutted\&.
.SS "const \fBName\fP & getName () const\fC [virtual]\fP"
\fBReturns:\fP The unique string identifier for the \fBKatabaticEngine\fP class of ToolEngine\&. 
.PP
Implements \fBToolEngine\fP\&.
.SS "\fBEngineState\fP getState () const\fC [inline]\fP"
\fBReturns:\fP The state the tool is currently in\&. 
.SS "unsigned int getFlags (unsigned int mask) const\fC [inline]\fP"
\fBReturns:\fP The \fIanded\fP combination of the tool flags and \fCmask\fP\&. 
.SS "Configuration * getKatabaticConfiguration ()\fC [inline]\fP"
\fBReturns:\fP The Configuration of \fBKatabatic\fP\&. In this class it is redundant with \fBgetConfiguration()\fP, but may be useful in derived classes\&. 
.SS "Configuration * getConfiguration ()\fC [virtual]\fP"
\fBReturns:\fP The Configuration of the current ToolEngine\&. 
.SS "\fBRoutingGauge\fP * getRoutingGauge () const\fC [inline]\fP"
\fBReturns:\fP The RoutingGauge (Configuration shortcut)\&. 
.SS "\fBRoutingLayerGauge\fP * getLayerGauge (size_t depth) const\fC [inline]\fP"
\fBReturns:\fP The RoutingLayerGauge associated to \fCdepth\fP (Configuration shortcut)\&. 
.SS "const \fBLayer\fP * getRoutingLayer (size_t depth) const\fC [inline]\fP"
\fBReturns:\fP The routing Layer associated to \fCdepth\fP (Configuration shortcut)\&. 
.SS "\fBLayer\fP * getContactLayer (size_t depth) const\fC [inline]\fP"
\fBReturns:\fP The contact Layer associated to \fCdepth\fP (Configuration shortcut)\&. 
.SS "\fBGCellGrid\fP * getGCellGrid () const\fC [inline]\fP"
\fBReturns:\fP The \fBGCellGrid\fP\&. 
.PP
Referenced by GCellTopology::doRp_AccessPad(), GCellTopology::doRp_AutoContacts(), and anonymous_namespace{LoadGrByNet\&.cpp}::singleGCell()\&.
.SS "const \fBNetSet\fP & getRoutingNets () const\fC [inline]\fP"
\fBReturns:\fP The set of nets to be routeds\&. 
.SS "\fBDbU::Unit\fP getGlobalThreshold () const\fC [inline]\fP"
\fBReturns:\fP The length above which a global wire is moved up in the layer assignment stage (Configuration shortcut)\&. 
.SS "float getSaturateRatio () const\fC [inline]\fP"
\fBReturns:\fP The ratio above which a \fBGCell\fP is considered to be saturated (Configuration shortcut)\&. 
.PP
Referenced by Session::getSaturateRatio()\&.
.SS "size_t getSaturateRp () const\fC [inline]\fP"
\fBReturns:\fP The number of RoutingPad above which a \fBGCell\fP is saturated, causing extras global segments to be moved up\&. (Configuration shortcut)\&. 
.PP
Referenced by Session::getSaturateRp()\&.
.SS "\fBDbU::Unit\fP getExtensionCap () const\fC [inline]\fP"
\fBReturns:\fP The wires extension cap, same for all layers for the time beeing (Configuration shortcut)\&. 
.SS "const \fBChipTools\fP & getChipTools () const\fC [inline]\fP"
\fBReturns:\fP The chip tools (for whole designs)\&. 
.PP
Referenced by KatabaticEngine::createDetailedGrid()\&.
.SS "void xmlWriteGCellGrid (ostream & o)"
Write in a stream all informations on the GCells in XML format\&. 
.PP
Referenced by KatabaticEngine::xmlWriteGCellGrid()\&.
.SS "void xmlWriteGCellGrid (const string & fileName)"
Write in a file all informations on the GCells in XML format\&. 
.PP
References KatabaticEngine::xmlWriteGCellGrid()\&.
.SS "void setState (\fBEngineState\fP state)\fC [inline]\fP"
Force the state of the tool\&. Must be used with caution, as no sanity checks are performeds\&. This method is normally invoked from inside the \fBKatabaticEngine\fP various methods\&. 
.SS "void setFlags (unsigned int flags)\fC [inline]\fP"
Set the flags given in \fCflags\fP\&. 
.PP
Referenced by Session::setKatabaticFlags()\&.
.SS "void unsetFlags (unsigned int flags)\fC [inline]\fP"
Reset the flags given in \fCflags\fP\&. 
.SS "void setGlobalThreshold (\fBDbU::Unit\fP threshold)\fC [inline]\fP"
(Configuration shortcut)\&. 
.SS "void setSaturateRatio (float ratio)\fC [inline]\fP"
(Configuration shortcut)\&. 
.SS "void setSaturateRp (size_t threshold)\fC [inline]\fP"
(Configuration shortcut)\&. 
.SS "void printMeasures (const string & tag) const"
Print memory & time measurement on ``cmess1``\&. If \fCtag\fP is not empty, also adds the measurement to the internal table (with \fCtag\fP as label)\&. 
.PP
Referenced by KatabaticEngine::finalizeLayout()\&.
.SS "void refresh (unsigned int flags = \fC\fBKbOpenSession\fP\fP)"
In case the tool is associated with a graphic display, trigger a full redraw of the Cell\&. Slow the router but allow to see work in progress\&.\&.\&. If \fCflags\fP \fIdo not\fP contains \fCKbOpenSession\fP the refresh operation will not be enclosed inside it's own session\&. This assumes that a session is already opened\&. 
.PP
References GCellGrid::updateContacts()\&.
.SS "void createDetailedGrid ()\fC [virtual]\fP"
Allocate the \fBGCellGrid\fP\&. 
.PP
References GCellGrid::create(), KatabaticEngine::getChipTools(), BaseGrid::getColumns(), Grid< GCellT >::getGCellsColumn(), Grid< GCellT >::getGCellsRow(), BaseGrid::getRows(), ChipTools::isChip(), and Session::revalidate()\&.
.SS "void makePowerRails ()"
Detect all the aligned segments of same width that compose power rails, unificate them and copy them at the design top level\&. 
.SS "void loadGlobalRouting (unsigned int method)\fC [virtual]\fP"

.PP
\fBParameters:\fP
.RS 4
\fImethod\fP the loading algorithm 
.br
\fInets\fP the set of nets to route\&.
.RE
.PP
Convert the global routing into the initial detailed routing\&. For the time beeing, only one loading algorithm is available: \fInet by net\fP (EngineLoadGrByNet)\&. Only Net given in \fCnets\fP are routeds\&. If \fCnets\fP is empty then all ordinary nets are routeds\&. In either cases the set of nets to route is pruned from any power, ground or clock signals\&.
.PP
\fBRemark: The tool state must be \fBEngineGlobalLoaded\fP \fIbefore\fP calling this method\fP
.RS 4
and will be set to \fBEngineActive\fP on exit\&. 
.RE
.PP

.PP
References Katabatic::EngineActive, and Katabatic::EngineGlobalLoaded\&.
.SS "void slackenBorder (\fBBox\fP bb, \fBLayer::Mask\fP mask, unsigned int flags)"

.PP
\fBParameters:\fP
.RS 4
\fIbb\fP The bounding box, defines the edges\&. 
.br
\fImask\fP Consider only layers that are fully included in that mask\&. 
.br
\fIflags\fP Consider only segment in that direction\&.
.RE
.PP
Perform a preventive break on all global segments going through the \fIvertical\fP left and right edges of the \fCbb\fP box\&. The set of global segments to be broken could be further restricted using \fCmask\fP and \fCflags\fP\&.
.PP
The Semantic of \fCflags\fP is not clear, must review the code more closely\&. 
.PP
References Box::getXMax(), Box::getXMin(), Box::getYMax(), and Box::getYMin()\&.
.SS "void slackenBlockIos (\fBInstance\fP * core)"
Perform a preventive break on horizontal segments in the \fBGCell\fP immediatly \fIoutside\fP the instance \fCcore\fP area in the routing layer of index \fC1\fP\&.
.PP
This method is too much hardwired to the \fCSxLib\fP gauge\&. It's effect is to break all \fBMETAL2\fP outside the core (in a chip)\&. 
.PP
References Entity::getBoundingBox(), Instance::getName(), Constant::Horizontal, and Box::inflate()\&.
.SS "bool moveUpNetTrunk (\fBAutoSegment\fP * seed, set< \fBNet\fP *> & globalNets, \fBGCell::SetIndex\fP & invalidateds)"

.PP
\fBParameters:\fP
.RS 4
\fIseed\fP The \fBAutoSegment\fP to take the net from\&. 
.br
\fIglobalNets\fP The set of nets that has been moved up\&. 
.br
\fIinvalidateds\fP The set of GCells that have been invalidated\&. \fBReturns:\fP \fBtrue\fP if the net trunk have been moved up\&.
.RE
.PP
Try to move up a whole net trunk\&. The net is supplied through the \fCseed\fP argument (the segment that triggers the move)\&. If the net is actually moved up, it is added to \fCglobalNets\fP and all GCells that have been invalidateds are added to \fCinvalidateds\fP\&.
.PP
An individual \fBAutoSegment\fP of the net is moved up if it's length is greater that \fC150\fP lambdas, that is, three times the side of a \fBGCell\fP\&. This is hard-wired and should be parametrized in the future\&. 
.SS "void layerAssign (unsigned int method)"
Perform the layer assignment\&. The global routing loading stage uses only the two bottom most layers, this method spread them on all the availables routing layers, according to \fBGCell\fP and RoutingPad density criterions\&.
.PP
Two algorithms are availables:
.IP "\(bu" 2
\fBEngineLayerAssignByLength\fP : the global wires are moved up one by one\&.
.IP "\(bu" 2
\fBEngineLayerAssignByTrunk\fP : if one global wire of a net is to be moved up, then all the global trunk of the net is moved along\&. This methods gives the best results for now\&. 
.PP

.SS "void computeNetConstraints (\fBNet\fP * net)"
Compute the box constraints on AutoContacts (and therefore those applied to AutoSegments)\&. Constraints comes from AutoContacts anchoreds on RoutingPads and transmitted through \fBAutoContactHTee\fP or \fBAutoContactVTee\fP\&. Constraints are applied to all AutoContacts of an aligned set\&.
.PP
\fBRemark: The \fCnet\fP must have been canonized before this function to be called\&. \fP
.RS 4

.RE
.PP

.SS "void toOptimals (\fBNet\fP * net)"
Move all \fBAutoSegment\fP of \fCnet\fP so that their axis are inside their optimals interval\&. If a \fBAutoSegment\fP is already inside the interval is not moved, otherwise it is put on the nearest bound of the optimal interval\&. 
.SS "void finalizeLayout ()\fC [virtual]\fP"
Transform the \fBKatabatic\fP wires into the Hurricane data-structure\&. Mostly by removing the AutoSegment/AutoContact \fIwithout\fP removing their Hurricane conterparts\&. May also fill gaps that may have appeared\&.
.PP
\fBRemark: The tool state must be \fBEngineActive\fP \fIbefore\fP calling this method\fP
.RS 4
and will be set to \fBEngineGutted\fP on exit\&. 
.RE
.PP

.PP
References Katabatic::EngineDriving, Katabatic::EngineGutted, and KatabaticEngine::printMeasures()\&.

.SH "Author"
.PP 
Generated automatically by Doxygen for Katabatic - Routing Toolbox from the source code\&.