
 // -*- C++ -*-


 namespace Katabatic {

 /*! \mainpage     Routing Toolbox Documentation
  *
  *                This documentation adresses two level of explanations :
  *
  *                <ul>
  *                  <li>The \b API description which explains how to use Katabatic,
  *                      thoses parts as flagged as \b API.
  *                  <li>The internal description which details how Katabatic do
  *                      things. It's mostly intended for myself to help me not to
  *                      forget how I've done things when debug time will come...
  *                      It may also be valuable to people who may want to use
  *                      or patch Katabatic for their own purpose (my secret hope).
  *                </ul>
  */


 /*! \namespace    Katabatic
  *  \brief        The namespace dedicated to Katabatic.
  */
 /*! \enum         LoadGRMethod
  *                Lists all avalaible global routing loading methods for
  *                loadGlobalRouting().
  */
 /*! \var          LoadGRMethod LoadGrByNet
  *                The global routing will be loaded net by net.
  */
 /*! \var          LoadGRMethod LoadGrByGCell
  *                The global routing will be loaded GCell by GCell.
  */


 /*! \class        KatabaticEngine
  *  \brief        The Katabatic ToolEngine, routing toolbox (\b API).
  */ 

 /*! \function     KatabaticEngine* KatabaticEngine::create ( const RoutingGauge* gauge, Cell* cell, vector<Net*>& nets );
  *  \param        gauge  The RoutingGauge to use.
  *  \param        cell   The \Cell to be routed.
  *  \param        nets   The subset of \Nets to be routeds. Note that the vector is
  *                       copied inside the KatabaticEngine object, so there's no need to keep
  *                       the parameter.
  *
  *                creates a new KatabaticEngine object. Should never be used, as Katabatic
  *                must be used as the base class for any router, and therefore
  *                created through it. Still avalaible for debugging purposes.
  */

 /*  \function     void  KatabaticEngine::destroy ();
  *                Cleanly destruct the data-base, saves the routing wires in
  *                the \Hurricane data-base (really a call to _preDestroy()).
  *
  *                \see _saveNet().
  */

 /*! \function     GCellGrid* KatabaticEngine::getGCellGrid () const;
  *  \return       The associated GCellGrid.
  */

 /*! \function     const vector<Net*>& KatabaticEngine::getRoutingNets () const;
  *  \return       The subset of \Nets that are to be routed.
  */

 /*! \function     void  KatabaticEngine::loadGlobalRouting ( unsigned int method )
  *  \param        method to specify the algorithm used to perform the loading.
  *
  *                translates a global routing created by Tornado (GCell/GCell data-base)
  *                into an initial detailed routing. Two algorithms are currently
  *                avalaibles :
  *                <ul>
  *                  <li> LoadGrByNet   : load global routing net by net.
  *                  <li> LoadGrByGCell : load global routing GCell by GCell.
  *                </ul>
  *
  *                This method is essentially a switch which calls the appropriate sub-method
  *                _loadGrByNet() or _LoadGRbyGCell(). It relies on the presence of a Nimbus
  *                ToolEngine, if not found, throws an error.
  */

 /*! \function     void  KatabaticEngine::setGlobalThreshold ( DbU::Unit threshold );
  *  \param        threshold The global routing threshold.
  *
  *                The length (in DbU::Unit) from which an AutoSegment will be considered to be
  *                global.
  *
  *  \see          layerAssign(), getGlobalThresold().
  */

 /*! \function     DbU::Unit  KatabaticEngine::getGlobalThreshold () const; 
  *  \return       The value of the global routing thresold.
  *
  *  \see          setGlobalThresold().
  */

 /*! \function     void  KatabaticEngine::_computeNetConstraints ( Net* );
  *                computes the \c AutoSegment constraints (see \ref NetConstraints).
  */

 /*! \function     void  KatabaticEngine::_computeNetOptimals ( Net* );
  *                computes the \c AutoSegment optimal positions (see \ref NetOptimals).
  */

 /*! \function     AutoSegment* KatabaticEngine::_lookup ( Segment* segment ) const;
  *  \param        segment The \c Hurricane segment.
  *
  *                Finds the Katabatic AutoSegment associated to \c segment.
  *                For this function to work, a Katabatic update session must be open.
  *                If not, an exception will be thrown.
  */

 /*! \function     void  KatabaticEngine::_link ( AutoSegment* autoSegment );
  *                adds \b autoSegment to the AutoSegment internal lookup table.
  *                This function does nothing if DoLinkAutoSegment() is \false :
  *                in destruction mode.
  *  \see          _Lookup().
  */

 /*! \function     void  KatabaticEngine::_unlink ( AutoSegment* autoSegment );
  *                removes \b autoSegment AutoSegment internal lookup table.
  *                This function does nothing if DoLinkAutoSegment() is \false :
  *                in destruction mode.
  *  \see          _Lookup().
  */

 /*! \function     void  KatabaticEngine::_destroyAutoSegments ();
  *                clear the internal AutoSegment lookup table. Should be called
  *                only from inside the Katabatic destructor.
  */

 /*! \function     void  KatabaticEngine::_saveNet ( Net* net );
  *  \param        net  The \Net to process.
  *
  *                Revert (partially destruct) the AutoSegment/AutoContact
  *                structure of the \Net to the \Hurricane data-base.
  *                To be used only in the Katabatic destructor...
  *
  *  \see          destroy().
  */


 /*! \function     KatabaticEngine* KatabaticEngine::get ( const Cell* cell )
  *  \brief        Returns the Katabatic ToolEngine attached to the Cell, if any.
  */

 /*! \function     void  KatabaticEngine::refresh ( bool openSession=true );
  *                Force the update of all AutoContact. By default opens a new
  *                update Session. If one is already open, set openSession to
  *                \False.
  */

 /*! \function     void  KatabaticEngine::startMeasures ();
  *                Start memory consumption and timer measurment (reset any
  *                previous one).
  *
  *  \see          stopMeasures(), printMeasures().
  */

 /*! \function     void  KatabaticEngine::stopMeasures ();
  *                compute memory consumption \& time elapsed since the last
  *                call to startMeasures().
  *
  *  \see          startMeasures(), printMeasures().
  */

 /*! \function     void  KatabaticEngine::printMeasures () const;
  *                Display memory consumption \& time elapsed.
  *                
  *  \see          startMeasures(), stopMeasures().
  */

 /*! \function     void  KatabaticEngine::_check ( const char* message=NULL ) const;
  *  \param        message  The message to print.
  *
  *                Perform a coherency complete coherency check of the
  *                data-base. Currently :
  *                <ul>
  *                  <li>No AutoSegment remains invalidated (\ref katabaticSession).
  *                  <li>AutoSegment extentions are coherent.
  *                </ul> 
  */


 //! \addtogroup   collapseCanonical
 //! \{

 /*! \function     void  KatabaticEngine::_canonize ( Net* net );
  *  \param        net  The \Net to canonize.
  *
  *                Find canonical AutoSegments and non-canonicals ones,
  *                sets up the flags accordingly.
  *
  *  \see          AutoSegment::isCanonical().
  */

 //! \}

 }
