// -*- C++ -*-
namespace Katabatic {
/*! \class KatabaticEngine
*
* \brief The Katabatic Tool
*
*
* \section secEngineStates States of KatabaticEngine
*
* During it's lifecycle, the engine go through a serie of states.
* It only can go forward between states.
* - \b EngineCreation : just after C++ object creation until
* the global routing is loaded.
* - \b EngineGlobalLoaded : \e after the global routing has
* been done. This state must be set by an external tool,
* Katabatic cannot know by itself when the global routing
* has been done (see Kite).
* - \b EngineActive : \e after the global routing has been
* converted into the Katabatic data structure. At this point
* the tool is ready to run.
* - \b EngineDriving : \e during the stage of stripping all
* the decorations the tool has added over the Hurricane data
* structure (mostly: AutoContact & AutoSegment).
* - \b EngineGutted : \e after the tool decorations have been
* removed. The tool is now useless and can only be destroyed.
* - \b EnginePreDestroying : this special state is reached when
* going straight from EngineActive to the destructor, that is,
* skipping the EngineDriving state. That means we <em>do not</em>
* 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).
*
*
* \section secEngineImpl KatabaticEngine Implementation Details
*
* 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 KatabaticEngine is split in several
* files. The list below summarize them:
* - \c KatabaticEngine.cpp : the core of the class, methods that really
* need their bodies here.
* - \c PowerRails.cpp : utilities to construct an abstract from all
* the power rails through the hierarchy.
* - \c LayerAssign.cpp : layer assignement related methods and helpers.
* - \c LoadGrByNet.cpp : global routing loader, transform global routing
* into Katabatic data-structure.
* - \c NetConstraints.cpp : compute the topological constraints of all
* AutoSegment/AutoContact of a Net.
* - \c NetOptimals.cpp : compute the optimal positions of all AutoSegment
* of a Net.
*/
//! \enum EngineState
//! Describe the current state of the KatabaticEngine.
//! \var EngineCreation
//! The tool is created, but still in the \c _postCreate stage.
//! \var EngineGlobalLoaded
//! The global routing has been loaded from Knik.
//! \var EngineActive
//! The Engine is in normal running mode (routing ordinary wires).
//! \var EngineDriving
//! The Engine is transforming the AutoContact/AutoSegment into
//! normal Contact/Segment (prior to tool deletion).
//! \var EnginePreDestroying
//! This state is used whenever the tool is destroyed without passing
//! through the EngineDriving state.
//! \var EngineGutted
//! After the EngineDriving state, all the working structures are
//! removed and the tool can no longer be used. It only awaits clean
//! destruction.
//! \typedef set<Net*, NetCompareByName> KatabaticEngine::NetSet;
//! Set of Net to be routed, alphabetically sorteds.
//! \function KatabaticEngine* KatabaticEngine::create ( Cell* cell );
//! Create a KatabaticEngine on \c cell.
//! \function const Name& KatabaticEngine::staticGetName ();
//! \sreturn The unique string identifier for the KatabaticEngine class of ToolEngine.
//! \function bool KatabaticEngine::isGMetal ( const Layer* layer ) const;
//! \sreturn \true if \c layer is one of the special (fake) metals used to build
//! the global routing.
//! \function bool KatabaticEngine::isChip () const;
//! \sreturn \true if the hierarchy top-level of the Cell matches the one of a complete
//! design (i.e. pads and one core instance).
//! \function bool KatabaticEngine::isInDemoMode () const;
//! \sreturn \true if the tool is in demo mode, that is suppress almost all warning
//! and debug messages.
//! \function bool KatabaticEngine::doWarnOnGCellOverload () const;
//! \sreturn \true if the tool should issue a warning when a GCell is overloaded
//! (overload could be transient).
//! \function bool KatabaticEngine::doDestroyBaseContact () const;
//! \sreturn \true if the EngineDestroyBaseContact is set, meaning that when an
//! AutoContact is destroyed, the Contact it decorates is destroyed
//! altogether.
//! \function bool KatabaticEngine::doDestroyBaseSegment () const;
//! \sreturn \true if the EngineDestroyBaseSegment is set, meaning that when an
//! AutoSegment is destroyed, the Segment it decorates is destroyed
//! altogether.
//! \function bool KatabaticEngine::doDestroyTool () const;
//! \sreturn \true if the tool state is beyond EngineStateGutted, that is, only
//! waits for \c destroy() to be called.
//! \function const Name& KatabaticEngine::getName () const;
//! \sreturn The unique string identifier for the KatabaticEngine class of ToolEngine.
//! \function EngineState KatabaticEngine::getState () const;
//! \sreturn The state the tool is currently in.
//! \function unsigned int KatabaticEngine::getFlags ( unsigned int mask ) const;
//! \sreturn The \e anded combination of the tool flags and \c mask.
//! \function Configuration* KatabaticEngine::getKatabaticConfiguration ();
//! \sreturn The Configuration of Katabatic. In this class it is redundant with
//! getConfiguration(), but may be useful in derived classes.
//! \function Configuration* KatabaticEngine::getConfiguration ();
//! \sreturn The Configuration of the current ToolEngine.
//! \function RoutingGauge* KatabaticEngine::getRoutingGauge () const;
//! \sreturn The RoutingGauge (Configuration shortcut).
//! \function RoutingLayerGauge* KatabaticEngine::getLayerGauge ( size_t depth ) const;
//! \sreturn The RoutingLayerGauge associated to \c depth (Configuration shortcut).
//! \function const Layer* KatabaticEngine::getRoutingLayer ( size_t depth ) const;
//! \sreturn The routing Layer associated to \c depth (Configuration shortcut).
//! \function Layer* KatabaticEngine::getContactLayer ( size_t depth ) const;
//! \sreturn The contact Layer associated to \c depth (Configuration shortcut).
//! \function DbU::Unit KatabaticEngine::getGlobalThreshold () const;
//! \sreturn The length above which a global wire is moved up in the layer assignment
//! stage (Configuration shortcut).
//! \function float KatabaticEngine::getSaturateRatio () const;
//! \sreturn The ratio above which a GCell is considered to be saturated
//! (Configuration shortcut).
//! \function DbU::Unit KatabaticEngine::getExtensionCap () const;
//! \sreturn The wires extension cap, same for all layers for the time beeing
//! (Configuration shortcut).
//! \function size_t KatabaticEngine::getSaturateRp () const;
//! \sreturn The number of RoutingPad above which a GCell is saturated, causing
//! extras global segments to be moved up.
//! (Configuration shortcut).
//! \function GCellGrid* KatabaticEngine::getGCellGrid () const;
//! \sreturn The GCellGrid.
//! \function const NetSet& KatabaticEngine::getRoutingNets () const;
//! \sreturn The set of nets to be routeds.
//! \function const ChipTools& KatabaticEngine::getChipTools () const;
//! \sreturn The chip tools (for whole designs).
//! \function void KatabaticEngine::xmlWriteGCellGrid ( ostream& );
//! Write in a stream all informations on the GCells in XML format.
//! \function void KatabaticEngine::xmlWriteGCellGrid ( const string& );
//! Write in a file all informations on the GCells in XML format.
//! \function void KatabaticEngine::setState ( EngineState state );
//! 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 KatabaticEngine various methods.
//! \function void KatabaticEngine::setFlags ( unsigned int flags );
//! Set the flags given in \c flags.
//! \function void KatabaticEngine::unsetFlags ( unsigned int flags );
//! Reset the flags given in \c flags.
//! \function void KatabaticEngine::setGlobalThreshold ( DbU::Unit );
//! (Configuration shortcut).
//! \function void KatabaticEngine::setSaturateRatio ( float );
//! (Configuration shortcut).
//! \function void KatabaticEngine::setSaturateRp ( size_t );
//! (Configuration shortcut).
//! \function void KatabaticEngine::startMeasures ();
//! Starts memory consuption & time measurements.
//! \function void KatabaticEngine::stopMeasures ();
//! Stops memory consuption & time measurements. Recorded measures are
//! kept until the next call to Katabatic::startMeasures().
//! \function void KatabaticEngine::printMeasures ( const string& tag ) const;
//! Print memory & time measurement on ``cmess1``. If \c tag is not empty,
//! also adds the measurement to the internal table (with \c tag as label).
//! \function void KatabaticEngine::refresh ( unsigned int flags=KbOpenSession );
//! 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 \c flags <em>do not</em> contains \c KbOpenSession
//! the refresh operation will not be enclosed inside it's own session.
//! This assumes that a session is already opened.
//! \function void KatabaticEngine::makePowerRails ();
//! Detect all the aligned segments of same width that compose power
//! rails, unificate them and copy them at the design top level.
//! \function void KatabaticEngine::createDetailedGrid ();
//! Allocate the GCellGrid.
//! \function void KatabaticEngine::loadGlobalRouting ( unsigned int method, NetSet& nets );
//! \param method the loading algorithm
//! \param nets the set of nets to route.
//!
//! Convert the global routing into the initial detailed routing. For the
//! time beeing, only one loading algorithm is available: <em>net by net</em>
//! (EngineLoadGrByNet). Only Net given in \c nets are routeds. If \c nets 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.
//!
//! \remark The tool state must be \b EngineGlobalLoaded \e before calling this method
//! and will be set to \b EngineActive on exit.
//! \function void KatabaticEngine::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 GCell and RoutingPad density criterions.
//!
//! Two algorithms are availables:
//! - \b EngineLayerAssignByLength : the global wires are moved up one by
//! one.
//! - \b EngineLayerAssignByTrunk : 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.
//! \function void KatabaticEngine::finalizeLayout ();
//! Transform the Katabatic wires into the Hurricane data-structure.
//! Mostly by removing the AutoSegment/AutoContact \e without removing
//! their Hurricane conterparts. May also fill gaps that may have appeared.
//!
//! \remark The tool state must be \b EngineActive \e before calling this method
//! and will be set to \b EngineGutted on exit.
//! \function void KatabaticEngine::slackenBorder ( Box bb, Layer::Mask mask, unsigned int flags );
//! \param bb The bounding box, defines the edges.
//! \param mask Consider only layers that are fully included in that mask.
//! \param flags Consider only segment in that direction.
//!
//! Perform a preventive break on all global segments going through the
//! \e vertical left and right edges of the \c bb box. The set of global
//! segments to be broken could be further restricted using \c mask and
//! \c flags.
//!
//! <span class="red">The Semantic of \c flags is not clear, must review the
//! code more closely.</span>
//! \function void KatabaticEngine::slackenBlockIos ( Instance* core );
//! Perform a preventive break on horizontal segments in the GCell immediatly
//! \e outside the instance \c core area in the routing layer of index \c 1.
//!
//! \red{This method is too much hardwired to the \c SxLib gauge. It's effect is to break all \b METAL2 outside the core (in a chip).}
//! \function bool KatabaticEngine::moveUpNetTrunk ( AutoSegment* seed, set<Net*>& globalNets, GCell::SetIndex& invalidateds );
//! \param seed The AutoSegment to take the net from.
//! \param globalNets The set of nets that has been moved up.
//! \param invalidateds The set of GCells that have been invalidated.
//! \sreturn \true if the net trunk have been moved up.
//!
//! Try to move up a whole net trunk. The net is supplied through the \c seed
//! argument (the segment that triggers the move). If the net is actually moved
//! up, it is added to \c globalNets and all GCells that have been invalidateds
//! are added to \c invalidateds.
//!
//! <span class="red">An individual AutoSegment of the net is moved up if it's length
//! is greater that \c 150 lambdas, that is, three times the side of a GCell. This is
//! hard-wired and should be parametrized in the future.</span>
//! \function void KatabaticEngine::computeNetConstraints ( Net* net );
//! Compute the box constraints on AutoContacts (and therefore those applied to
//! AutoSegments). Constraints comes from AutoContacts anchoreds on RoutingPads
//! and transmitted through AutoContactHTee or AutoContactVTee. Constraints are
//! applied to all AutoContacts of an aligned set.
//!
//! \remark The \c net must have been canonized before this function to be called.
//! \function void KatabaticEngine::toOptimals ( Net* net );
//! Move all AutoSegment of \c net so that their axis are inside their
//! optimals interval. If a AutoSegment is already inside the interval is
//! not moved, otherwise it is put on the nearest bound of the optimal
//! interval.
}