coriolis/katabatic/doc/KatabaticEngine.dox

 // -*- 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.

 }