Create a \b secondary contact, so that both the original
+ * and the secondary abide by the two layers rule.
+ *
Create new AutoSegments to connect original to secondary.
+ * There could be one or two segments created according to
+ * the layers distance.
+ *
Re-attach the AutoSegments to the right AutoContact.
+ * The rule being that an AutoSegment is attached to the
+ * lowest AutoContact containing it's Layer.
+ *
The orignal & secondary contact are passed trough
+ * the connexity restauration procedure.
+ *
+ *
+ * Importants Points
+ *
+ *
+ *
In the second step: the new AutoSegments must be put on
+ * axis so that after resizing original and secondary AutoContact,
+ * the AutoSegments do not extend outside their previous extension.
+ *
Constraints splitting: the constraints on the splitted
+ * AutoSegment mustn't be more restrictive than thoses on the
+ * original one. For example, two AutoSegments that weren't
+ * HAligneds must not become so.
+ *
+ *
+ * Special Cases
+ *
+ *
The AutoContact is anchored on a \c METAL1 terminal, then
+ * there is only one \c M4 AutoSegment to be re-connected, we
+ * simply create a two-VIA dog leg.
+ *
The AutoContact still have connect two connex Layers, just
+ * changes the AutoContact Layer.
+ *
+ *
+ * \image html AutoContact-12.png
+ * \image html AutoContact-13.png
+ * \image html AutoContact-14.png
+ * \image html AutoContact-15.png
+ * \image latex AutoContact-12.pdf
+ * \image latex AutoContact-13.pdf
+ * \image latex AutoContact-14.pdf
+ * \image latex AutoContact-15.pdf
+ */
+
+ /* \var GCell* AutoContact::_gcell
+ * \brief The GCell into which the AutoContact is located.
+ */
+
+ /*! \function AutoContact* AutoContact::fromRp ( GCell* gcell, RoutingPad* routingPad, const Layer* layer, Point point, DbU::Unit width, DbU::Unit height, bool fixed=false );
+ * \param gcell The GCell in which to create the AutoContact.
+ * \param routingPad The RoutingPad on which to anchor the AutoContact.
+ * \param layer The AutoContact's layer.
+ * \param point The absolute position of the AutoContact.
+ * \param width AutoContact's width.
+ * \param height AutoContact's height.
+ * \param fixed The AutoContact cannot be moved.
+ * \return Newly created AutoContact.
+ *
+ * create an AutoContact anchored on a \c RoutingPad. The AutoContact can
+ * be moved along the \c RoutingPad but not outside it.
+ *
+ * A remark on the \c point parameter : it must be absolute coordinates, but
+ * as we uses the \c RoutingPad as an anchor they are translated into an
+ * offset from the \c RoutingPad (see how \c Hurricane handles coordinates
+ * through anchoring). It is also assumed that the AutoContact is to be
+ * electrically connected to the \c RoutingPad (no disconnection).
+ * So, we will faces three cases, depending on the \c RoutingPad
+ * underlying \c Entity :
+ *
+ *
The \c Entity is an horizontal segment :
+ * the Y coordinate is sets to zero, the X coordinate is kept.
+ *
The \c Entity is a vertical segment :
+ * keep the Y coordinate, the X coordinate is sets to zero.
+ *
The \c Entity is a \c Contact or a \c Pin :
+ * both X and Y are sets to zero.
+ *
+ */
+
+ /*! \function AutoContact* AutoContact::create ( GCell* gcell, Net* net, const Layer* layer, bool hAlignate=false, bool vAlignate=false )
+ * \param gcell The GCell into which the AutoContact will be put.
+ * \param net The AutoContact's owner Net.
+ * \param layer The AutoContact's layer.
+ * \param hAlignate Keeps alignate (all) horizontal segments.
+ * \param vAlignate Keeps alignate (all) vertical segments.
+ * \return A new AutoContact.
+ *
+ * As AutoContact are Contacts restricted to, at best, two adjacent
+ * routing layers, the layer argument is either a single routing
+ * contact or a two metals only VIA.
+ */
+
+ /*! \function AutoContact* AutoContact::create ( GCell* gcell, RoutingPad* rp, const Layer* layer, const DbU::Unit dx, const DbU::Unit dy, const DbU::Unit width, const DbU::Unit height, bool hAlignate=false, bool vAlignate=false, bool fixed=false );
+ * \param gcell The GCell into which the AutoContact will be put.
+ * \param rp The RoutingPad anchor.
+ * \param layer The AutoContact's layer.
+ * \param dx Horizontal offset to the component.
+ * \param dy Vertical offset to the component.
+ * \param width Width of the AutoContact.
+ * \param height Height of the AutoContact.
+ * \param hAlignate Keeps alignate (all) horizontal segments.
+ * \param vAlignate Keeps alignate (all) vertical segments.
+ * \param fixed The AutoContact cannot be moved.
+ * \return A new AutoContact.
+ *
+ * create an AutoContact anchored on a component : the component must
+ * be a \RoutingPad, sets the isTerminal() flag.
+ *
+ * As AutoContact are Contacts restricted to, at best, two adjacent
+ * routing layers, the layer argument is either a single routing
+ * contact or a two metals only VIA.
+ */
+
+ /*! \function GCell* AutoContact::getGCell() const
+ * \brief Returns the GCell into which the AutoContact is located.
+ */
+
+ /*! \function void AutoContact::updateGeometry()
+ * \brief Perform the segment resizing.
+ *
+ * As it will resizes Hurricane components, this function call must
+ * be enclosed into an updateSession.
+ */
+
+ /*! \function AutoContacts AutoContact::getCollapseds ( unsigned int direction );
+ * \param direction restrict the search to that direction.
+ * \return The \c Collection of AutoContact that are collapsed on this one,
+ * that is, linked through collapsed AutoSegment of type
+ * \c direction.
+ */
+
+ /*! \function bool AutoContact::isTerminal () const;
+ * \return \true if the AutoContact is anchored on a terminal.
+ */
+
+ /*! \function bool AutoContact::isHAlignate () const;
+ * \return \true if the horizontal AutoSegment anchored on the AutoContact
+ * must be kept aligned.
+ * \see \ref collapseCanonical
+ */
+
+ /*! \function bool AutoContact::isVAlignate () const;
+ * \return \true if the vertical AutoSegment anchored on the AutoContact
+ * must be kept aligned.
+ * \see \ref collapseCanonical
+ */
+
+ /*! \function void AutoContact::getLengths ( DbU::Unit* lengths, set& segments );
+ * \return Increment the table of lengths for the lengths of segments of
+ * this AutoContact and inside it's owning GCell.
+ */
+
+ /*! \function void AutoContact::setTerminal ( bool isTerminal );
+ * \param isTerminal set the terminal flag.
+ */
+
+ /*! \function bool AutoContact::isHExtended ();
+ * \return \true if the \b privileged direction of the AutoContact is horizontal.
+ *
+ * To be privileged in horizontal direction means that the \c Y coordinates
+ * of all horizontals of the AutoContact are the same and imposed in either
+ * of the following ways:
+ *
+ *
Have a horizontal global (i.e. stem). The AutoContact could
+ * be non-punctual along the horizontal axis.
+ *
All it's horizontals are kept aligneds.
+ *
+ * \note An AutoContact can be neither horizontally extended nor vertically
+ * extended. In which case it is punctual.
+ *
+ * \image html AutoContact-10.png
+ * \image latex AutoContact-10.pdf
+ */
+
+ /*! \function bool AutoContact::isVExtended ();
+ * \return \true if the \b privileged direction of the AutoContact is vertical.
+ *
+ * To be privileged in vertical direction means that the \c X coordinates
+ * of all verticals of the AutoContact are the same and imposed in either
+ * the following way:
+ *
+ *
Have a vertical global (i.e. stem). The AutoContact could
+ * be non-punctual along the vertical axis.
+ *
All it's vertical are kept aligneds.
+ *
+ * \note An AutoContact can be neither horizontally extended nor vertically
+ * extended. In which case it is punctual.
+ *
+ * \image html AutoContact-11.png
+ * \image latex AutoContact-11.pdf
+ */
+
+ /*! \function void AutoContact::setHAlignate ( bool hAlignate );
+ * \param hAlignate The new horizontal alignement mode.
+ *
+ * When horizontal aligment mode is active, all horizontals of the
+ * AutoContact are kept aligned (on the same \b Y coordinate).
+ * \see \ref collapseCanonical
+ */
+
+ /*! \function void AutoContact::setVAlignate ( bool vAlignate );
+ * \param vAlignate The new vertical alignement mode.
+ *
+ * When vertical aligment mode is active, all verticals of the
+ * AutoContact are kept aligned (on the same \b X coordinate).
+ * \see \ref collapseCanonical
+ */
+
+ /*! \function void AutoContact::restoreHConnexity ( DbU::Unit y, bool split=false );
+ * \param y When splitting, the coordinate of the vertical strap segments.
+ * \param split Wether to separate the various horizontals or not.
+ *
+ * Ensure that there is no gap between horizontals of this AutoContact.
+ *
+ *
The default behavior (split=false) is simply to sets the
+ * H Alignate flags, thus forcing the alignment on the same \c Y.
+ *
To allow the horizontals to be on different axis, we can split
+ * them on differents AutoContacts aligneds vertically. The AutoSegments
+ * created between thoses secondary contacts are calleds "straps" and
+ * sets on the \c Y axis.
+ *
+ * In case of splitting, all the verticals are kept on the original AutoContact.
+ */
+
+ /*! \function void AutoContact::restoreVConnexity ( DbU::Unit x, bool split=false );
+ * \param x When splitting, the coordinate of the horizontal strap segments.
+ * \param split Wether to separate the various verticals or not.
+ *
+ * Ensure that there is no gap between verticals of this AutoContact.
+ *
+ *
The default behavior (split=false) is simply to sets the
+ * V Alignate flags, thus forcing the alignment on the same \c X.
+ *
To allow the verticals to be on different axis, we can split
+ * them on differents AutoContacts aligneds horizontally. The AutoSegments
+ * created between thoses secondary contacts are calleds "straps" and
+ * sets on the \c X axis.
+ *
+ * In case of splitting, all the horizontals are kept on the original AutoContact.
+ */
+
+ /*! \function void AutoContact::invalidate ();
+ * Put this AutoContact into the invalidated set (see \ref katabaticSession).
+ */
+
+
+ //! \addtogroup katabaticSession
+ //! \{
+
+ /*! \function bool AutoContact::isInvalidated () const;
+ * \return \True if the AutoContact is invalidated, i.e. in the
+ * Katabatic Session, one or more of it's anchored AutoSegment
+ * being moved.
+ *
+ * \see autoInvalidate().
+ */
+
+ /*! \function bool AutoContact::setInvalidated ( bool state );
+ * \param state set the state of the AutoContact regarding the
+ * Katabatic Session.
+ *
+ * \see autoInvalidate().
+ */
+
+ /*! \function Box AutoContact::getNativeConstraintBox () const;
+ * Return the native constraint box, that is, the \Box of the
+ * owning GCell or the bounding box of the terminal it's anchored
+ * upon.
+ */
+
+ /*! \function DbU::Unit AutoContact::getCBXMin () const;
+ * \return The X coordinate of the lower left corner.
+ */
+
+ /*! \function DbU::Unit AutoContact::getCBYMin () const;
+ * \return The Y coordinate of the lower left corner.
+ */
+
+ /*! \function DbU::Unit AutoContact::getCBXMax () const;
+ * \return The X coordinate of the upper right corner.
+ */
+
+ /*! \function DbU::Unit AutoContact::getCBYMax () const;
+ * \return The Y coordinate of the upper right corner.
+ */
+
+ /*! \function Box AutoContact::getConstraintBox () const;
+ * \return The current constraint box.
+ */
+
+ /*! \function Box& AutoContact::intersectConstraintBox ( Box& box ) const;
+ * \param box The box to intersect width.
+ * \return A reference on the the box given as argument.
+ *
+ * Do the intersection of the constraint box and the one given
+ * as argument. Store the result in place.
+ */
+
+ /*! \function void AutoContact::restoreNativeConstraintBox ();
+ * reset the constraint box to the native constraint box.
+ */
+
+ /*! \function void AutoContact::setConstraintBox ( const Box& box );
+ * \param box The new constraint box.
+ *
+ * sets the constraint box.
+ */
+
+ /*! \function void AutoContact::restrictConstraintBox ( DbU::Unit constraintMin, DbU::Unit constraintMax, unsigned int direction );
+ * \param constraintMin The constraint lower bound.
+ * \param constraintMax The constraint upper bound.
+ * \param direction The direction into which apply the constraint.
+ *
+ * restrict the constraint box in one direction.
+ */
+
+ /*! \function void AutoContact::setCBXMin ( DbU::Unit xMin );
+ * \param xMin The X cooordinate of the lower left corner.
+ *
+ * sets the X coordinate of the lower left corner.
+ */
+
+ /*! \function void AutoContact::setCBYMin ( DbU::Unit yMin );
+ * \param yMin The Y cooordinate of the lower left corner.
+ *
+ * sets the Y coordinate of the lower left corner.
+ */
+
+ /*! \function void AutoContact::setCBXMax ( DbU::Unit xMax );
+ * \param xMax The X cooordinate of the upper right corner.
+ *
+ * sets the X coordinate of the upper right corner.
+ */
+
+ /*! \function void AutoContact::setCBYMax ( DbU::Unit yMax );
+ * \param yMax The Y cooordinate of the upper right corner.
+ *
+ * sets the Y coordinate of the upper right corner.
+ */
+
+ //! \}
+
+ }
+
+
+ namespace {
+
+ }
diff --git a/katabatic/doc/AutoSegment.dox b/katabatic/doc/AutoSegment.dox
new file mode 100644
index 00000000..ae35d17c
--- /dev/null
+++ b/katabatic/doc/AutoSegment.dox
@@ -0,0 +1,677 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \class AutoSegment
+ * \brief Self-sizing segment (\b API).
+ *
+ * AutoSegment provide an uniform way of accessing AutoHorizontal
+ * and AutoVertical self-sizing segments. AutoSegments mainly contains
+ * a pointer to the associated Horizontal/Vertical Hurricane segment.
+ * This is the Hurricane segment which is part of the ring of the
+ * AutoContact. Thus we can directly access the Hurricane segment
+ * from the AutoSegment, but for the othey around we uses a lookup
+ * table in the Katabatic \c ToolEngine (see the
+ * Katabatic::_Lookup() member function).
+ *
+ * In order to inform the router of an AutoSegment state change,
+ * a callback function SegmentRevalidateCB can be positionned.
+ *
+ * \c Segment associated to AutoSegment are automatically oriented
+ * in such a way that the source \c Hook is always \e lower than
+ * the target \c hook. For an Horizontal segment it means that
+ * the abcissa of the source is inferior to the abcsissa of the
+ * target. It goes the same way for Vertical segment with the
+ * ordinate.
+ *
+ * KatabaticSession mechanism : this is fairly similar to the
+ * \c Hurricane updateSession one. When a segment is either moved
+ * by the router or resized by it's AutoContact it is invalidated
+ * with autoInvalidate() and put into the set of invalidated
+ * segments. When the KatabaticSession is closed the onRevalidate()
+ * member function is called on each segment, which in turn calls
+ * the router's callback. See Session::open(), Session::revalidate(),
+ * Session::close() and \ref katabaticSession.
+ *
+ * \remark As this object uses the decorator Design Pattern, almost all
+ * functions are pure virtuals. Implementation take place in a
+ * derived class \c AutoSegmentConcrete which is not documented,
+ * (same specifications as AutoSegment).
+ *
+ * \see AutoSegmentDecorator class.
+ */
+
+ /*! \typedef AutoSegment::RevalidateCb_t ( AutoSegment* )
+ * Function type for the router callback. See AutoSegment::setRevalidateCb().
+ */
+
+ /* \function static AutoSegment::RevalidateCb_t* AutoSegment::setRevalidateCb ( RevalidateCb_t* cb );
+ * \param cb The new router callback to install.
+ * \return The previous router callback.
+ *
+ * Install the callback to call when an AutoSegment is revalidated,
+ * The callback is called by onRevalidate() on closing the Katabatic
+ * update session.
+ */
+
+ /*! \function bool AutoSegment::isHorizontal () const;
+ * \return \true if the AutoSegment is horizontal.
+ */
+
+ /*! \function bool AutoSegment::isVertical () const;
+ * \return \true if the AutoSegment is vertical.
+ */
+
+ /*! \function bool AutoSegment::isGlobal () const;
+ * \return \true if the AutoSegment is global : source and target
+ * AutoContact are not in the same GCell.
+ */
+
+ /*! \function bool AutoSegment::isLocal () const;
+ * \return \true if the AutoSegment is local : source and target
+ * belongs to the same GCell.
+ */
+
+ /*! \function bool AutoSegment::isTerminal () const;
+ * \return \true if the AutoSegment is terminal : the only way
+ * to access a terminal AutoContact (may not be directly
+ * achored on that terminal).
+ */
+
+ /*! \function bool AutoSegment::isCollapsed () const;
+ * \return \true if the AutoSegment is collapsed : kept to zero-length.
+ */
+
+ /*! \function bool AutoSegment::isCanonical () const;
+ * \return \true if the AutoSegment is canonical that is, the leftmost
+ * (for horizontal) or lowest (for vertical) segment of a set
+ * of collapsed segments. The canonical segment must be used
+ * as the unique representant for the collapsed set.
+ */
+
+ /*! \function bool AutoSegment::isFixed () const;
+ * \return \true if the AutoSegment cannot be moved (through setAxis()).
+ */
+
+ /*! \function bool AutoSegment::isAccountable () const;
+ * \return \true if the AutoSegment is canonical and not collapsed.
+ * Normally those flags are mutually exclusives, but better safe
+ * than sorry.
+ *
+ */
+
+ /*! \function virtual GCell* AutoSegment::getGCell () const;
+ * \return The GCell owning the source AutoContact.
+ */
+
+ /*! \function Net* AutoSegment::getNet () const;
+ * \return The net this AutoSegment is part of.
+ */
+
+ /*! \function Layer* AutoSegment::getLayer () const;
+ * \return The layer of the AutoSegment.
+ */
+
+ /*! \function virtual Segment* AutoSegment::getSegment ();
+ * \return The associated \c Hurricane segment.
+ */
+
+ /*! \function virtual Segment* AutoSegment::getSegment () const;
+ * \return The associated \c Hurricane segment.
+ *
+ * This function is for use in const members.
+ */
+
+ /*! \function virtual Segment* AutoSegment::getHorizontal ();
+ * \return If the the associated segment is horizontal, returns it.
+ * Otherwise (vertical) returns \c NULL.
+ */
+
+ /*! \function virtual Segment* AutoSegment::getVertical ();
+ * \return If the the associated segment is vertical, returns it.
+ * Otherwise (horizontal) returns \c NULL.
+ */
+
+ /*! \function DbU::Unit AutoSegment::getAxis () const;
+ * \return The segment axis : Y for horizontals and X for verticals.
+ */
+
+ /*! \function AutoContact* AutoSegment::getSource () const;
+ * \return The source AutoContact.
+ */
+
+ /*! \function AutoContact* AutoSegment::getTarget () const;
+ * \return The target AutoContact.
+ */
+
+ /*! \function DbU::Unit AutoSegment::getSourcePosition () const;
+ * \return The lower bound of the segment into the routing track, equal
+ * the source coordinate minus the half pitch.
+ */
+
+ /*! \function DbU::Unit AutoSegment::getTargetPosition () const;
+ * \return The upper bound of the segment into the routing track, equal
+ * the target coordinate plus the half pitch.
+ */
+
+ /*! \function virtual void AutoSegment::setAxis ( DbU::Unit axis, bool realignate=false, set* processeds=NULL );
+ * \param axis New coordinate of the axis. For an horizontal segment
+ * it will change the Y coordinate and for a vertical,
+ * the X coordinate.
+ * \param realignate It set to true, the new axis position will be propagated
+ * to all collapsed segments, even if the current AutoSegment
+ * don't need to be moved.
+ * \param processeds The set of already processeds aligneds AutoSegments.
+ *
+ * setAxis is the API frontend to the alignate function. It actually
+ * only checks if the segment has to be moved and if the move is to
+ * be propagated to the aligned AutoSegments.
+ */
+
+ /*! \function virtual void AutoSegment::orient ();
+ * sets the source and target \c Hook of the Hurricane segment so
+ * the source is always lower than the target.
+ */
+
+ /*! \function virtual void AutoSegment::invalidate ();
+ * adds the AutoSegment to the invalidate session. This will happens
+ * whenever a segment is moved by the router through setAxis() or
+ * resized by it's AutoContact.
+ */
+
+ /* \function virtual void AutoSegment::onRevalidate ();
+ * This function is called at the time the AutoUpdate session is closed
+ * and calls the router's callback.
+ */
+
+ /*! \function virtual void AutoSegment::getConstraints ( DbU::Unit& constraintMin, DbU::Unit& constraintMax ) const;
+ * \param constraintMin Where to store the constraint lower bound.
+ * \param constraintMax Where to store the constraint upper bound.
+ * \return Always \true (don't remember why...).
+ *
+ * Constraints are deduced from the constraint box of the source
+ * AutoContact.
+ *
+ * \see \ref NetConstraints
+ */
+
+ /*! \function virtual void AutoSegment::getConstraints ( Interval& i ) const;
+ * \param i The constraint interval.
+ * \return Always \true (don't remember why...).
+ *
+ * \see getConstraints(), \ref NetConstraints
+ */
+
+ /*! \function DbU::Unit AutoSegment::getSlack () const;
+ * \return The length of the constraint interval.
+ *
+ * \see \ref NetOptimals
+ */
+
+ /*! \function DbU::Unit AutoSegment::getOptimalMin () const;
+ * \return The lower bound of the optimal interval.
+ *
+ * \see \ref NetOptimals
+ */
+
+ /*! \function DbU::Unit AutoSegment::getOptimalMax () const;
+ * \return The upper bound of the optimal interval.
+ *
+ * \see \ref NetOptimals
+ */
+
+ /*! \function Interval& AutoSegment::getOptimal ( Interval& i ) const;
+ * \param i The optimal interval.
+ * \return The interval given as argument.
+ *
+ * \see \ref NetOptimals
+ */
+
+ /*! \function DbU::Unit AutoSegment::getCost ( DbU::Unit axis ) const;
+ * \param axis An axis coordinate.
+ * \return The distance from the nearest optimal interval bound.
+ *
+ * \see \ref NetOptimals
+ */
+
+ /*! \function AutoSegment* AutoSegment::getCanonical ( DbU::Unit& sourcePosition, DbU::Unit& targetPosition );
+ * \param sourcePosition Lower bound of the super-AutoSegment.
+ * \param targetPosition Upper bound of the super-AutoSegment.
+ * \return The canonical AutoSegment of the super-AutoSegment.
+ *
+ * A super-AutoSegment is the set of all AutoSegment which have been
+ * bound together through (perpandicular) collapsed AutoSegment.
+ * They behave like one big AutoSegment. For algorithmic purpose we
+ * needs a canonical representant : it will be the lower AutoSegment
+ * (the one with the lower source coordinates).
+ * We also needs to know the real extend of the super-AutoSegment : it's
+ * returned through \c sourcePosition and \c targetPosition parameters.
+ */
+
+ /*! \function AutoSegment* AutoSegment::getCanonical ( Interval& i );
+ * \param i interval of the super-AutoSegment.
+ * \return The canonical AutoSegment of the super-AutoSegment.
+ *
+ * \see AutoSegment::getCanonical().
+ */
+
+ /*! \function AutoSegments AutoSegment::getCollapseds ( bool withPerpand=false );
+ * \return The \Collection of AutoSegment that are collapsed to this one
+ * (i.e. linked through perpandicual collapsed ones). Together
+ * they forms one big virtual AutoSegment.
+ */
+
+ /*! \function AutoSegments AutoSegment::getCollapsedPerpandiculars ();
+ * \return The \Collection of AutoSegment that are perpandicular to this
+ * one and it's collapsed fellows.
+ *
+ * Note that this \Collection contains only \b GLOBAL perpandicular
+ * AutoSegment and \b Terminal perpandicular AutoSegment.
+ */
+
+ /*! \function void AutoSegment::setCanonical ( bool state );
+ * \param state sets the isCanonical() flag to this value.
+ */
+
+ /*! \function void AutoSegment::setTerminal ( bool state );
+ * \param state sets the isTerminal() flag to this value.
+ */
+
+ /*! \function void AutoSegment::setLayer ( const Layer* layer );
+ * \param layer Changes the \Hurricane segment layer.
+ */
+
+ /*! \function void AutoSegment::setPositions ();
+ * compute the positions of the AutoSegment into the routing track,
+ * from the \Hurricane segment extentions and the half-pitch.
+ *
+ * \see getSourcePosition() & getTargetPosition().
+ */
+
+ /*! \function void AutoSegment::collapse ();
+ * sets the AutoSegment into collapsed state (zero-length).
+ */
+
+ /*! \function void AutoSegment::expand ();
+ * Uncollapse the AutoSegment, re-compute the constraints on
+ * the splitted sets.
+ */
+
+ /*! \function bool AutoSegment::toConstraintAxis ( set* processeds=NULL );
+ * \return \True if the AutoSegment axis has been moved.
+ *
+ * If the segment axis is outside the constraint interval, set it
+ * the nearest constraint interval bound.
+ */
+
+ /*! \function bool AutoSegment::toOptimalAxis ( set* processeds=NULL );
+ * \return \True if the AutoSegment axis has been moved.
+ *
+ * If the segment axis is outside the optimal interval, set it
+ * the nearest optimal interval bound.
+ */
+
+ /*! \function void AutoSegment::alignate ( DbU::Unit axis );
+ * \param axis New axis's coordinate.
+ *
+ * Move the segment axis to a new position. Adjust positions
+ * of the supporting Contact whenever they are anchored on terminals
+ * (i.e. RoutingPad).
+ * This function is atomic and should not be called directly
+ * but rather through setAxis(). It's implemented in the
+ * derived classes AutoHorizontal & AutoVertical.
+ */
+
+ /*! \function void AutoSegment::setOptimalMin ( DbU::Unit oMin );
+ * \param oMin sets the lower bound of the optimal interval.
+ *
+ * \see getOptimalMin(), getOptimalMax(), getCost().
+ */
+
+ /*! \function void AutoSegment::setOptimalMax ( DbU::Unit oMin );
+ * \param oMin sets the upper bound of the optimal interval.
+ *
+ * \see getOptimalMin(), getOptimalMax(), getCost().
+ */
+
+ /*! \function void AutoSegment::checkPositions () const;
+ * check the coherency between the locally shadowed values
+ * of source \& target position and the real ones. If a discrepancy
+ * is found issue an error (but do not stop the program).
+ *
+ * Note that discrepancies are legal while the AutoSegment is
+ * invalidated (see \ref katabaticSession).
+ */
+
+ /*! \function void AutoSegment::checkInvalidated () const;
+ * issue an error if the AutoSegment is invalidated. Mainly used
+ * to debug the Katabatic Session mechanism (\ref katabaticSession).
+ */
+
+
+ //! \addtogroup NetOptimals
+ //! \{
+
+ /*! \function virtual void AutoSegment::computeOptimal ( set* processeds=NULL );
+ * compute the AutoSegment optimal position interval.
+ */
+
+ /*! \function virtual DbU::Unit AutoSegment::getOrigin () const;
+ * \return The lower bound of the GCell in which the AutoSegment is
+ * (\c YMin for horizontals, \c XMin for verticals).
+ */
+
+ /*! \function virtual DbU::Unit AutoSegment::getExtremity () const;
+ * \return The upper bound of the GCell in which the AutoSegment is
+ * (\c YMax for horizontals, \c XMax for verticals).
+ */
+
+ //! \}
+
+
+ //! \addtogroup katabaticSession
+ //! \{
+
+ /*! \function bool AutoSegment::isInvalidated () const;
+ * \return \True if the AutoSegment is invalidated, i.e. in the
+ * Katabatic Session, it's axis having being moved by the
+ * router.
+ *
+ * \see autoInvalidate().
+ */
+
+ /*! \function bool AutoSegment::setInvalidated ( bool state );
+ * \param state set the state of the AutoSegment regarding the
+ * Katabatic Session.
+ *
+ * \see autoInvalidate().
+ */
+
+ //! \}
+
+
+ /*! \class AutoHorizontal
+ * \brief Horizontal AutoSegment (\b API).
+ */
+
+ /*! \function static AutoHorizontal* AutoHorizontal::create ( Horizontal* horizontal, int type, bool terminal=false, bool collapsed=false );
+ * \param horizontal The associated \c Hurricane segment.
+ * \param type Global, local or guessed kind.
+ * \param terminal Whether the segment is tightly linked to a terminal.
+ * \param collapsed Whether the segment must be kept of null length.
+ * \return The newly created AutoSegment.
+ */
+
+ /*! \function static AutoHorizontal* AutoHorizontal::create ( AutoContact* source, AutoContact* target, const Layer* layer, DbU::Unit y, DbU::Unit width, int type, bool terminal=false, bool collapsed=false );
+ * \param source The source \c Component.
+ * \param target The target \c Component.
+ * \param layer The segment's layer.
+ * \param y The segment's Y coordinate.
+ * \param width The segment's width.
+ * \param type Global, local or guessed kind.
+ * \param terminal Whether the segment is tightly linked to a terminal.
+ * \param collapsed Whether the segment must be kept of null length.
+ * \return The newly created AutoSegment.
+ *
+ * Allocate both \c Hurricane segment and Katabatic AutoSegment.
+ */
+
+
+ /*! \class AutoVertical
+ * \brief Vertical AutoSegment (\b API).
+ */
+
+ /*! \function static AutoVertical* AutoVertical::create ( Vertical* vertical, int type, bool terminal=false, bool collapsed=false );
+ * \param vertical The associated \c Hurricane segment.
+ * \param type Global, local or guessed kind.
+ * \param terminal Whether the segment is tightly linked to a terminal.
+ * \param collapsed Whether the segment must be kept of null length.
+ * \return The newly created AutoSegment.
+ */
+
+ /*! \function static AutoVertical* AutoVertical::create ( AutoContact* source, AutoContact* target, const Layer* layer, DbU::Unit x, DbU::Unit width, int type, bool terminal=false, bool collapsed=false );
+ * \param source The source \c Component.
+ * \param target The target \c Component.
+ * \param layer The segment's layer.
+ * \param x The segment's X coordinate.
+ * \param width The segment's width.
+ * \param type Global, local or guessed kind.
+ * \param terminal Whether the segment is tightly linked to a terminal.
+ * \param collapsed Whether the segment must be kept of null length.
+ * \return The newly created AutoSegment.
+ *
+ * Allocate both \c Hurricane segment and Katabatic AutoSegment.
+ */
+
+
+ /*! \function AutoSegment* AutoSegment::create ( AutoContact* source, AutoContact* target, unsigned int dir, int type, bool terminal=false, bool collapsed=false );
+ * \param source The source AutoContact.
+ * \param target The target AutoContact.
+ * \param dir The AutoSegment direction (\b H / \b V).
+ * \param type Whether the AutoSegment is \b LOCAL, \b GLOBAL or must be guessed.
+ * \param terminal The AutoSegment is used to connect a terminal.
+ * \param collapsed The AutoSegment is collapsed.
+ * \return A new AutoSegment.
+ *
+ * create the AutoSegment between \c source and \c target, update the GCell
+ * density if needed.
+ *
+ * If the \c dir parameter do not contains the \b HORIZONTAL or \b VERTICAL
+ * boolean flags an error will be thrown.
+ */
+
+
+ /*! \enum AutoSegment::Type
+ * This enumeration is used to hints AutoSegment constructor about
+ * the kind of segment we are about to create. Once created, the
+ * kind of AutoSegment is stored in a single boolean telling
+ * wether it's \b GLOBAL or \b LOCAL (see AutoSegment::isGlobal()).
+ *
+ * It is always best to avoid using AutoSegment::Guess as it implies findind
+ * and checking source and target anchors (through ring access).
+ * And in most cases we already known the kind of segment because
+ * we created the source and target AutoContact just before...
+ * See GCellConfiguration related functions.
+ */
+
+ /*! \var AutoSegment::Global
+ * The AutosSegment crosses at least one GCell boundary (i.e.
+ * source and target AutoContact do not belong to the same GCell).
+ */
+
+ /*! \var AutoSegment::Local
+ * The AutoSegment is fully included in one GCell.
+ */
+
+ /*! \var AutoSegment::Guess
+ * The AutoSegment constructor will guess the kind of AutoSegment
+ * by examining source and target anchors.
+ */
+
+ /*! \defgroup collapseCanonical 3. AutoSegment collapse & Canonical (internal)
+ *
+ * \section AlignedAS Collapsing AutoSegment
+ *
+ * A set of AutoSegment can be aligned together. The set will
+ * behave like one big AutoSegment, especially, moving one
+ * AutoSegment through setAxis() will move the whole set.
+ *
+ * For each set of aligned AutoSegment, we provide a canonical
+ * AutoSegment : the leftmost (for horizontal) or lowermost for
+ * verticals.
+ *
+ * There are two ways AutoSegments could be aligned :
+ *
+ *
Through a collapsed perpandicular AutoSegment.
+ *
Through a locked AutoContact.
+ *
+ *
+ * \subsection AlignedByCollapsed Aligned through collapsed AutoSegment
+ *
+ * When an AutoSegment is collapsed, all perpandicular AutoSegment
+ * to it's source and target AutoContact are aligneds. Collapsing
+ * an AutoSegment means that it should be kept to zero length and
+ * thus not managed by the overlying router.
+ *
+ * \image html AutoSegmentCollapse-5.png "collapse by AutoSegment"
+ * \image latex AutoSegmentCollapse-5.pdf "collapse by AutoSegment" width=0.4\textwidth
+ *
+ * \subsection AlignedByAutoContact Aligned through collapsed AutoContact
+ *
+ * With the setHAlignate() and setVAlignate() the alignment of
+ * horizontal (resp. vertical) AutoSegment of an AutoContact can be
+ * forced.
+ *
+ * \image html AutoSegmentCollapse-6.png "collapse by AutoContact"
+ * \image latex AutoSegmentCollapse-6.pdf "collapse by AutoContact" width=0.4\textwidth
+ *
+ * \subsection collapsedExample An example of collapse/alignment
+ *
+ * \image html AutoSegmentCollapse-1.png "collapse - Step 1"
+ * \image latex AutoSegmentCollapse-1.pdf "collapse - Step 1" width=0.4\textwidth
+ *
+ * \image html AutoSegmentCollapse-2.png "collapse - Step 2"
+ * \image latex AutoSegmentCollapse-2.pdf "collapse - Step 2" width=0.4\textwidth
+ *
+ * \image html AutoSegmentCollapse-3.png "collapse - Step 3"
+ * \image latex AutoSegmentCollapse-3.pdf "collapse - Step 3" width=0.4\textwidth
+ *
+ * \image html AutoSegmentCollapse-4.png "collapse - Step 4"
+ * \image latex AutoSegmentCollapse-4.pdf "collapse - Step 4" width=0.4\textwidth
+ */
+
+
+ //! \addtogroup collapseCanonical
+ //! \{
+
+ /*! \enum AutoSegment::PerpandicularState
+ * set of flags used to build the state of two AutoSegment.
+ * \see getPerpandicularState().
+ */
+
+ /*! \var AutoSegment::PerpandicularAny
+ * The \e current AutoSegment is perpandicular to the \e master.
+ * May it be or not through collapsed perpandiculars.
+ */
+
+ /*! \var AutoSegment::PerpandicularIndirect
+ * The \e current AutoSegment is perpandicular to the \e master
+ * through at least one collapsed perpandicular.
+ */
+
+ /*! \var AutoSegment::ParallelOrExpanded
+ * The \e current AutoSegment is not part of the aligned set,
+ * it's either parallel but not aligned (no constraint on the
+ * AutoContact) or perpandicular and not collapsed.
+ */
+
+ /*! \var AutoSegment::ParallelAndLayerChange
+ * The \e current AutoSegment is parallel to the master but not on
+ * the same layer as the \e source (the \e master by transitivity).
+ */
+
+ /*! \function unsigned int AutoSegment::getPerpandicularState ( AutoContact* contact, AutoSegment* source, AutoSegment* current, bool isHorizontalMaster, const Layer* masterLayer=NULL )
+ * \param contact The AutoContact shared by source \& current.
+ * \param source The AutoSegment from where we came.
+ * \param current The AutoSegment we are exploring.
+ * \param isHorizontalMaster The direction of the reference AutoSegment.
+ * \param masterLayer The \Layer of the reference AutoSegment.
+ * \return A composite value telling the position of current relative to
+ * source and reference.
+ *
+ * Locators of \Collections like AutoSegment::getCollapseds() or
+ * AutoSegment::getCollapsedPerpandiculars() are built on this
+ * function. Any \Collection manipulating aligned sets must uses
+ * this function which is the keystone of the aligned set walk-through.
+ *
+ * The return value is a combination of binary flags from the
+ * AutoSegment::PerpandicularState enumeration. The function
+ * compute the following boolean values :
+ *
+ *
\e sourcePerpandicular : \True if the \e source is perpandicular
+ * to the \e master AutoSegment.
+ *
\e currentPerpandicular : \True if the \e current is perpandicular
+ * to the \e master AutoSegment.
+ *
\e contactAlignate : \True if the alignment constraint on the
+ * AutoContact (if any) applies to \e source \& \e current. For instance
+ * it will be \True if both source and current are horizontal
+ * \b and AutoContact::isHAlignate() is \True.
+ *
+ * Then the return value is computed as follow :
+ *
+ *
If \e current is parallel to \e master \b but not on the same
+ * layer.
+ *
+ * sets the AutoSegment::AutoSegment::ParallelAndLayerChange flag.
+ *
If \e current is perpandicular to \e master \b and not
+ * collapsed, it is perpandicular to the aligned set of the
+ * \e master.
+ *
+ * sets the AutoSegment::AutoSegment::PerpandicularAny flag.
+ *
\e source is perpandicular to \e master. There is an implicit
+ * context : the only way a perpandicular segment gets took into
+ * account, is to be collapsed. Then if the \e current AutoSegment
+ * is also perpandicular \b and \b not collapsed, it means
+ * that it's a perpandicular to the aligned set of the \e master,
+ * The difference with the previous case, is that it's through at
+ * least one collapsed perpandicular.
+ *
+ * sets the AutoSegment::AutoSegment::PerpandicularIndirect flag.
+ *
\e source is parallel to \e master. Then we check for
+ * disconnection in the aligned set. Disconnection arises
+ * if the \e contactAlignate flag is \false (either no
+ * alignment constraint on the AutoContact or different
+ * directions), \b and the \e current segment is not a
+ * collapsed perpandicular.
+ *
+ * sets the AutoSegment::AutoSegment::ParallelOrExpanded flag.
+ *
+ * The \b zero return value means that the \e current AutoSegment
+ * belong to the same aligned set as the \e master \b or is a
+ * perpandicular collapsed AutoSegment.
+ *
+ * The figures below demonstrate all thoses case :
+ *
+ * \image html PerpandicularState-1.png "Simple Perpandicular (case 2)"
+ * \image latex PerpandicularState-1.pdf "Simple Perpandicular (case 2)" width=0.8\textwidth
+ *
+ * \image html PerpandicularState-2.png "Indirect Perpandicular (case 3)"
+ * \image latex PerpandicularState-2.pdf "Indirect Perpandicular (case 3)" width=0.8\textwidth
+ *
+ * \image html PerpandicularState-3.png "Parallel (case 4.1)"
+ * \image latex PerpandicularState-3.pdf "Parallel (case 4.1)" width=0.8\textwidth
+ *
+ * \image html PerpandicularState-4.png "Aligned through AutoContact (case 4.2)"
+ * \image latex PerpandicularState-4.pdf "Aligned through AutoContact (case 4.2)" width=0.8\textwidth
+ */
+
+ /*! \function unsigned int AutoSegment::getPerpandicularState ( AutoContact* contact, AutoSegment* source, AutoSegment* current, AutoSegment* master )
+ * \param contact The AutoContact shared by source \& current.
+ * \param source The AutoSegment from where we came.
+ * \param current The AutoSegment we are exploring.
+ * \param master The reference AutoSegment.
+ * \return A composite value telling the position of current relative to
+ * source and reference.
+ */
+
+ /*! \function bool AutoSegment::arePerpandiculars ( AutoSegment* a, AutoSegment* b );
+ * \param a First AutoSegment.
+ * \param b Second AutoSegment.
+ * \return true if a \& b have perpandicular directions.
+ */
+
+ /*! \function bool AutoSegment::areAligneds ( AutoSegment* a, AutoSegment* b );
+ * \param a First AutoSegment.
+ * \param b Second AutoSegment.
+ * \return true if a \& b have same directions.
+ */
+
+ /*! \function bool AutoSegment::arePerpandiculars ( bool isHorizontalA, AutoSegment* b );
+ * \param isHorizontalA is the A AutoSegment horizontal.
+ * \param b Second AutoSegment.
+ * \return true if a \& have perpandicular directions.
+ */
+
+ }
diff --git a/katabatic/doc/CMakeLists.txt b/katabatic/doc/CMakeLists.txt
new file mode 100644
index 00000000..75bc8217
--- /dev/null
+++ b/katabatic/doc/CMakeLists.txt
@@ -0,0 +1,12 @@
+
+ set ( htmlInstallDir /share/doc/en/html/katabatic )
+ set ( latexInstallDir /share/doc/en/latex/katabatic )
+
+ add_custom_target ( doc ALL cd ${KATABATIC_SOURCE_DIR}/doc && ${DOXYGEN_EXECUTABLE} doxyfile )
+
+ install ( DIRECTORY html/ DESTINATION ${htmlInstallDir} )
+ install ( FILES customHierarchy.html DESTINATION ${htmlInstallDir} )
+ install ( FILES customSummary.html DESTINATION ${htmlInstallDir} )
+
+ install ( DIRECTORY latex/ DESTINATION ${latexInstallDir} )
+ install ( FILES asimbook.cls DESTINATION ${latexInstallDir} )
diff --git a/katabatic/doc/GCell.dox b/katabatic/doc/GCell.dox
new file mode 100644
index 00000000..64d9433a
--- /dev/null
+++ b/katabatic/doc/GCell.dox
@@ -0,0 +1,179 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \class GCell
+ * \brief Global Routing cell (\b API).
+ *
+ * \attention This class can only be allocated through a GCellGrid thus
+ * Constructors/Destructors are protecteds.
+ *
+ * \remark As this object uses the decorator Design Pattern, almost all
+ * functions are pure virtuals. Implementation take place in a
+ * derived class \c GCellConcrete which is not documented,
+ * (same specifications as GCell).
+ *
+ * \see GCellDecorator class.
+ */
+
+ /*! \function GCellGrid* GCell::getGCellGrid () const;
+ * \return The GCellGrid to which the GCell belongs.
+ */
+
+ /*! \function unsigned int GCell::getIndex () const;
+ * \return The linear index of this GCell inside the GCellGrid GCell table.
+ */
+
+ /*! \function unsigned int GCell::getRow () const;
+ * \return The GCell's row inside the GCellGrid (this is a Y coordinate).
+ */
+
+ /*! \function unsigned int GCell::getColumn () const;
+ * \return The GCell's row inside the GCellGrid (this is a X coordinate).
+ */
+
+ /*! \function Point GCell::getCenter () const;
+ * \return The center of the GCell.
+ */
+
+ /*! \function DbU::Unit GCell::getX () const;
+ * \return The X coordinate of the GCell's lower left corner (\b XMin).
+ */
+
+ /*! \function DbU::Unit GCell::getY () const;
+ * \return The Y coordinate of the GCell's lower left corner (\b YMin).
+ */
+
+ /*! \function DbU::Unit GCell::getXMax () const;
+ * \return The X coordinate of the GCell's upper right corner.
+ */
+
+ /*! \function DbU::Unit GCell::getYMax () const;
+ * \return The Y coordinate of the GCell's lower upper right corner.
+ */
+
+ /*! \function Box GCell::getBoundingBox () const;
+ * \return The GCell bounding box.
+ */
+
+ /*! \function GCell* GCell::getLeft () const;
+ * \return The CCell's left neighbour (may be \c NULL if first of the row).
+ */
+
+ /*! \function GCell* GCell::getRight () const;
+ * \return The CCell's right neighbour (may be \c NULL if last of the row).
+ */
+
+ /*! \function GCell* GCell::getUp () const;
+ * \return The CCell's up neighbour (may be \c NULL if top of the column).
+ */
+
+ /*! \function GCell* GCell::getDown () const;
+ * \return The CCell's down neighbour (may be \c NULL if bottom of the column).
+ */
+
+ /*! \function unsigned int GCell::getDensity ( unsigned int depth ) const;
+ * \return The density of vertical wires going through this GCell.
+ * \see updateDensity()
+ */
+
+ /*! \function unsigned int GCell::getCDensity () const;
+ * \return The AutoContact density.
+ * \see updateDensity()
+ */
+
+ /*! \function unsigned int GCell::getDensity () const;
+ * \return The average of horizontal and vertical density.
+ * \see updateDensity()
+ */
+
+ /*! \function vector* GCell::getVSegments ();
+ * \return All vertical AutoSegment, starting, ending or crossing this GCell.
+ */
+
+ /*! \function vector* GCell::getHSegments ();
+ * \return All horizontal AutoSegment, starting, ending or crossing this GCell.
+ */
+
+ /*! \function vector* GCell::getContacts ();
+ * \return All AutoContact belonging to this GCell.
+ */
+
+ /*! \function AutoSegments GCell::getVStartSegments ();
+ * \return All vertical AutoSegment starting from this GCell.
+ */
+
+ /*! \function AutoSegments GCell::getHStartSegments ();
+ * \return All horizontal AutoSegment starting from this GCell.
+ */
+
+ /*! \function AutoSegments GCell::getVStopSegments ();
+ * \return All vertical AutoSegment ending in this GCell.
+ */
+
+ /*! \function AutoSegments GCell::getHStopSegments ();
+ * \return All horizontal AutoSegment ending in this GCell.
+ */
+
+ /*! \function AutoSegments GCell::getStartSegments ( unsigned int direction );
+ * \param direction The selected direction.
+ * \return All AutoSegment starting from this GCell in \b direction.
+ */
+
+ /*! \function AutoSegments GCell::getStopSegments ( unsigned int direction );
+ * \param direction The selected direction.
+ * \return All AutoSegment ending in this GCell in \b direction.
+ */
+
+ /*! \function void GCell::addVSegment ( AutoSegment* segment );
+ * \param segment A vertical AutoSegment.
+ *
+ * Indicate that the vertical \c segment is going straigh through this
+ * GCell (no AutoContact).
+ */
+
+ /*! \function void GCell::addHSegment ( AutoSegment* segment );
+ * \param segment An horizontal AutoSegment.
+ *
+ * Indicate that the horizontal \c segment is going straigh through this
+ * GCell (no AutoContact).
+ */
+
+ /*! \function void GCell::addContact ( AutoContact* contact );
+ * \param contact An AutoContact.
+ *
+ * Indicate that the \c contact is owned by this GCell. This means that
+ * either it's a branching point or there are terminals in the GCell.
+ * The AutoContact is geometrically bound by the GCell bounding box.
+ */
+
+ /*! \function void GCell::updateContacts ();
+ * Force the geometrical recalculation of all AutoContact owned by
+ * this GCell.
+ */
+
+ /*! \function void GCell::updateDensity ();
+ * Recompute the horizontal, vertical, global and contact of
+ * this GCell.
+ *
+ * The horizontal density is computed as follow : the sum of the length
+ * of all horizontal wires divided by the the total length of horizontal
+ * wires (the width of the GCell times the number of horizontal tracks).
+ * A density equal to one means a totally saturated GCell, and greater
+ * than one an overloaded GCell (unroutable).
+ *
+ * The vertical density is computed in a similar way to the horizontal
+ * one.
+ *
+ * The global density is the average of horizontal and vertical
+ * density.
+ *
+ * AutoContact density is the ratio of number of contact with length of
+ * the diagonal of the GCell multiplied by two. This is a rough approximate.
+ *
+ * \see GCellGrid::updateDensity().
+ */
+
+ }
diff --git a/katabatic/doc/GCellGrid.dox b/katabatic/doc/GCellGrid.dox
new file mode 100644
index 00000000..d8fa9960
--- /dev/null
+++ b/katabatic/doc/GCellGrid.dox
@@ -0,0 +1,21 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \class GCellGrid
+ * \brief Routing Grid (\b API).
+ *
+ * \attention This class is can only be allocated through a Katabatic
+ * \c ToolEngine thus Constructors/Destructors are protecteds.
+ *
+ * \section GCellGridImplementation GCellGrid Implementation Details
+ */
+
+ /*! \function void GCellGrid::updateDensity ();
+ * \return Recompute the density of each GCell in the grid.
+ * \see GCell::updateDensity().
+ */
+
+ }
diff --git a/katabatic/doc/Grid.dox b/katabatic/doc/Grid.dox
new file mode 100644
index 00000000..49da96dd
--- /dev/null
+++ b/katabatic/doc/Grid.dox
@@ -0,0 +1,114 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \class BaseGrid
+ * \brief Grid Common Skeleton (\b API).
+ *
+ * \attention Provide a non-template common skeleton for the Grid class
+ * template. Specifically manage the axis graduation, the geometric
+ * search functions and the indexes computation (assuming a linear
+ * storage of the grid elements).
+ *
+ *
+ * \section BaseGridImplementation Grid Implementation Details
+ *
+ * The matrix of GCell is stored in a linear vector of GCell's pointer,
+ * row by row. The Grid class provide convenient functions to
+ * convert a linear index into row / column and the other way around.
+ */
+
+ /*! \function unsigned int BaseGrid::getColumns () const;
+ * \return The number of columns of the GCell matrix.
+ */
+
+ /*! \function unsigned int BaseGrid::getRows () const;
+ * \return The number of rows of the GCell matrix.
+ */
+
+ /*! \function unsigned int BaseGrid::getRawSize () const;
+ * \return The size of the vector holding the GCell matrix.
+ */
+
+ /*! \function unsigned int BaseGrid::getIndex ( unsigned int column, unsigned int row ) const;
+ * \param column The GCell's column.
+ * \param row The GCell's row.
+ * \return The linear index of the GCell at (column,row).
+ */
+
+ /*! \function unsigned int BaseGrid::getRow ( unsigned int index ) const;
+ * \param index A linear index.
+ * \return extract the row number from the linear index.
+ */
+
+ /*! \function unsigned int BaseGrid::getColumn ( unsigned int index ) const;
+ * \param index A linear index.
+ * \return extract the column number from the linear index.
+ */
+
+ /*! \class Grid
+ * \brief Routing Grid (\b API).
+ *
+ * \attention This class is can only be allocated through a Katabatic
+ * \c ToolEngine thus Constructors/Destructors are protecteds.
+ *
+ * \section GridImplementation Grid Implementation Details
+ *
+ * The matrix of GCell is stored in a linear vector of GCell's pointer,
+ * row by row. The Grid class provide convenient functions to
+ * convert a linear index into row / column and the other way around.
+ */
+
+
+ /*! \function GCell* Grid::getGCell ( const Point p1, const Point p2 ) const;
+ * \param p1 First point.
+ * \param p2 Second point.
+ * \return Returns the GCell enclosing both points.
+ *
+ * When we build a Net's routing wires, and the Net span more than one
+ * GCell, we can always find the appropriate GCell through the
+ * \c Hook, \c GCell and GCell association.
+ *
+ * Problem arises for a Net fully contained inside one GCell, in this
+ * case there is no SplitterContact telling us where we are. We have
+ * to guess the GCell by only using RoutingPad's positions. And unfortunatly
+ * \c RoutingPad can be on the edge of one GCell so we cannot tell if
+ * it belongs to the left or the right. To solve this problem we guess
+ * the GCell from two (different) \c RoutingPad positions.
+ *
+ * Note that if there is only one \c RoutingPad, there is no problem at
+ * all : we are dealing with a one \c Plug \c Net...
+ *
+ * If points do not belongs to one GCell (too far appart), strange
+ * results may occurs.
+ */
+
+ /*! \function GCell* Grid::getGCell ( unsigned int index ) const;
+ * \param index A linear index.
+ * \return The GCell at the given index.
+ *
+ * Be aware that no check is performed if the index is out of bound,
+ * this may leads to catastrophic results.
+ */
+
+ /*! \function vector Grid::getGCellVector ();
+ * \return The \vector holding all GCells.
+ */
+
+ /*! \function GCells Grid::getGCellsColumn ( unsigned int column, unsigned int rowStart, unsigned int rowStop );
+ * \param column The column index.
+ * \param rowStart The start row index inside the column.
+ * \param rowStop The stop row index inside the column.
+ * \return The \c Collection of a partial row.
+ */
+
+ /*! \function GCells Grid::getGCellsRow ( unsigned int row, unsigned int columnStart, unsigned int columnStop );
+ * \param row The row index.
+ * \param columnStart The start column index inside the row.
+ * \param columnStop The stop column index inside the row.
+ * \return The \c Collection of a partial column.
+ */
+
+ }
diff --git a/katabatic/doc/KatabaticEngine.dox b/katabatic/doc/KatabaticEngine.dox
new file mode 100644
index 00000000..7e09fa3e
--- /dev/null
+++ b/katabatic/doc/KatabaticEngine.dox
@@ -0,0 +1,202 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \mainpage Routing Toolbox Documentation
+ *
+ * This documentation adresses two level of explanations :
+ *
+ *
+ *
The \b API description which explains how to use Katabatic,
+ * thoses parts as flagged as \b API.
+ *
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).
+ *
+ */
+
+
+ /*! \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& 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& 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 :
+ *
+ *
LoadGrByNet : load global routing net by net.
+ *
LoadGrByGCell : load global routing GCell by GCell.
+ *
+ *
+ * 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 :
+ *
+ *
No AutoSegment remains invalidated (\ref katabaticSession).
+ *
AutoSegment extentions are coherent.
+ *
+ */
+
+
+ //! \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().
+ */
+
+ //! \}
+
+ }
diff --git a/katabatic/doc/LayerAssign.dox b/katabatic/doc/LayerAssign.dox
new file mode 100644
index 00000000..ce8526d8
--- /dev/null
+++ b/katabatic/doc/LayerAssign.dox
@@ -0,0 +1,143 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \defgroup layerAssign 4. Layer Assignment (internal)
+ *
+ * This modules documents how layer assignment is performed. It is intented
+ * for developpers only.
+ *
+ * Layer Assignment functions works in two steps :
+ *
+ *
For a given net, go through the \c AutoSegment and migrate them
+ * to upper (global) layers if needed.
+ *
For each \c AutoContact of which at least one \c AutoSegment has been
+ * migrated, split the \c AutoContact (with SplitAutoContact()).
+ *
+ *
+ * SplitAutoContact() relies on the hypothesis that the split occurs
+ * between two sets of \b HV layers. For example between \b M2/M3 and
+ * \b M4/M5 but not between \b M2/M3 and \b M6/M7.
+ *
+ * The following figures shows all possible configurations, except for
+ * the most obvious : when all \c AutoSegment are migrated from \b M2/M3 to
+ * \b M4/M5 we just change the layer of the \c AutoContact from \b C23 to \b C34.
+ * SplitAutoContact() compute the layer span of the AutoContact,
+ * that is, the distance between the lowest layer and the higher one (it
+ * cannot exceed 3 as from \b M2 to \b M5). Then it detach the higher
+ * \c AutoSegment and re-attach them to a newly created \c AutoContact.
+ * In turn this new \c AutoContact is connected to the previous one.
+ *
+ *
The span is 3 (\b M2 to \b M5) : creates 2 \c AutoContact and
+ * 2 \c AutoSegment.
+ *
The span is 2 (\b M2 to \b M4 or \b M3 to \b M5) : creates one
+ * \c AutoContact and one \c AutoSegment.
+ *
The span is 1 (\b M3 to \b M4) : just change the layer of the
+ * \c AutoContact to \b C34.
+ *
+ * Simpler rules could be formulated : if \b M2 is present creates the
+ * \b M3 additionnal \c AutoSegment. If \b M5 is present, created the
+ * \b M4 additionnal \c AutoSegment.
+ *
+ * In M2+M3+M4+M5, M3+M4+M5 and M2+M3+M4 configurations
+ * two separates \b M4 \c AutoSegment (resp. \b M3 \c AutoSegment) are needed
+ * to avoid the incomplete AutoContact wiring problem
+ * (see \ref ssecFaultyTopologies).
+ *
+ * \image html SplitAutoContact-1.png "Full Configuration"
+ * \image latex SplitAutoContact-1.pdf "Full Configuration" width=0.4\textwidth
+ * \image html SplitAutoContact-2.png "No M3 Configuration"
+ * \image latex SplitAutoContact-2.pdf "No M3 Configuration" width=0.4\textwidth
+ * \image html SplitAutoContact-3.png "No M3,M4 Configuration"
+ * \image latex SplitAutoContact-3.pdf "No M3,M4 Configuration" width=0.4\textwidth
+ * \image html SplitAutoContact-4.png "No M2 Configuration (degenerate)"
+ * \image latex SplitAutoContact-4.pdf "No M2 Configuration (degenerate)" width=0.4\textwidth
+ * \image html SplitAutoContact-5.png "No M5 Configuration (degenerate)"
+ * \image latex SplitAutoContact-5.pdf "No M5 Configuration (degenerate)" width=0.4\textwidth
+ * \image html SplitAutoContact-6.png "No M2,M5 Configuration (degenerate)"
+ * \image latex SplitAutoContact-6.pdf "No M2,M5 Configuration (degenerate)" width=0.4\textwidth
+ */
+
+
+ /*! \enum LayerAssignMethod
+ * List all avalaible global layer assignment algorithm avalaible for
+ * layerAssign().
+ */
+
+ /*! \var LayerAssign LayerAssignByLength
+ * See layerAssign().
+ */
+
+ /*! \var LayerAssign LayerAssignByTrunk
+ * See layerAssign().
+ */
+
+
+ /*! \function void KatabaticEngine::layerAssign ( unsigned int method )
+ * \param method specify the algorithm used to perform the layer assignement.
+ *
+ * The loadGlobalRouting() method build a topology for each net using only the
+ * two first routing layers avalaibles (usually \e metal2 and \e metal3).
+ * To use upper routing layer we needs to go through a layer assignment
+ * step. The layerAssign() method provides two simples approaches to do so :
+ *
+ *
layerAssignByLength : every global AutoSegment which
+ * length is superior to the global threshold is moved to the upper layer.
+ *
layerAssignByTrunk : if any AutoSegment of a net
+ * exceed the global threshold, then all the global wiring of this
+ * net is put into the upper layers.
+ *
+ *
+ * This method is a switch to _layerAssignByLength() or _layerAssignByTrunk().
+ *
+ * The global threshold is to be sets using the setGlobalThreshold()
+ * method.
+ */
+
+
+ //! \addtogroup layerAssign
+ //! \{
+
+
+ /*! \function void KatabaticEngine::_layerAssignByLength ( unsigned long& total, unsigned long& global, set& globalNets );
+ *
+ * Perform the layer assignment on all nets, using the
+ * layerAssignByLength algorithm. See layerAssign().
+ */
+
+ /*! \function void KatabaticEngine::_layerAssignByLength ( Net* net, unsigned long& total, unsigned long& global, set& globalNets );
+ * \param net The net to process.
+ * \param total The total number of AutoSegment.
+ * \param global The number of AutoSegment that have been sets global.
+ * \param globalNets Set of global Nets.
+ *
+ * Perform the layer assignment on one net, using the
+ * layerAssignByLength algorithm. See layerAssign().
+ */
+
+ /*! \function void KatabaticEngine::_layerAssignByTrunk ( unsigned long& total, unsigned long& global, set& globalNets );
+ *
+ * Perform the layer assignment on all nets, using the
+ * layerAssignByTrunk algorithm. See layerAssign().
+ */
+
+ /*! \function void KatabaticEngine::_layerAssignByTrunk ( Net* net, unsigned long& total, unsigned long& global, set& globalNets );
+ * \param net The net to process.
+ * \param total The total number of AutoSegment.
+ * \param global The number of AutoSegment that have been sets global.
+ * \param globalNets Set of global Nets.
+ *
+ * Perform the layer assignment on one net, using the
+ * layerAssignByTrunk algorithm. See layerAssign().
+ */
+
+ //! \}
+
+}
+
+
+ namespace {
+
+ }
diff --git a/katabatic/doc/LoadGrByNet.dox b/katabatic/doc/LoadGrByNet.dox
new file mode 100644
index 00000000..786d9c62
--- /dev/null
+++ b/katabatic/doc/LoadGrByNet.dox
@@ -0,0 +1,27 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \function void KatabaticEngine::_loadGrByNet ()
+ * Load the global routing from the Nimbus structure (built by the Tornado
+ * global router) into the Katabatic ToolEngine.
+ */
+
+ /*! \function void KatabaticEngine::_loadNetGlobalRouting ( Net* net )
+ * \param net The net for which to build the final routing.
+ *
+ * Load the global routing from the Nimbus structure. Do a recursive
+ * walk through the GCells. Recursivity is handled with the
+ * ForkStack stack.
+ */
+
+ }
+
+
+
+
+ namespace {
+
+ }
diff --git a/katabatic/doc/NetConstraints.dox b/katabatic/doc/NetConstraints.dox
new file mode 100644
index 00000000..534f7555
--- /dev/null
+++ b/katabatic/doc/NetConstraints.dox
@@ -0,0 +1,128 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \defgroup NetConstraints 5. Constraints Computations (internal)
+ *
+ * This module documents how constraints computation are performed.
+ * It is intented for developpers only.
+ *
+ * Constraints gives the absolute minimal and maximal position an
+ * \c AutoSegment axis can be set. They materialize the bounds over
+ * which we may have an electrical disconnection.
+ *
+ * Practically, due to the magic of \c AutoContact, disconnections
+ * can only occurs on \c AutoContact anchored on \c RoutingPad :
+ * if they go outside the \c RoutingPad area, we are in trouble.
+ * Those \c AutoContact can be spotted either by the fact they have
+ * an anchor or the AutoContact::isTerminal() flag is set.
+ *
+ *
+ * \section secConstraintsOrgan Organisation
+ *
+ * Due to algorithmic consideration, instead of storing constraint
+ * interval (one axis) in \c AutoSegment, we store constraint \c Box
+ * (both axis) in \c AutoContact. They are easier to propagate during the
+ * computation stage and should takes less memory as \c AutoContact
+ * are often shared by more than two \c AutoSegment.
+ *
+ * To spare memory, each coordinate of the constraint \c Box is expressed
+ * as a strictly positive offset in \e lambdas from the lower left corner
+ * of the \c FCell owning the \c AutoContact. Offsets are 8 bits unsigned int,
+ * thus a \c Box takes one word (32 bits). This leads to two restrictions :
+ *
+ *
A \c FCell side cannot be greater than 256 \e lambdas.
+ *
The constraint \c Box minimal precision is the \e lambda.
+ *
+ * In all cases I can foresee, none of them should be a problem.
+ *
+ * Constraint interval on \c AutoSegment can be deduced from any of
+ * the source or target \c AutoContact. For an horizontal \c AutoSegment
+ * we take the constraint \c Box vertical interval and for a vertical,
+ * the horizontal interval.
+ *
+ *
+ * \section secNativeConstraints Native Constraints
+ *
+ * Before the contraints computation starts, we needs to initialize
+ * each \c AutoContact \c Box to a reasonable default : the
+ * Native Constraint Box. Wich is :
+ *
+ *
For an anchored/passive \c AutoContact : the bounding box
+ * of the underlying terminal.
+ *
For any other \c AutoContact : the bounding box of the
+ * \c FCell owner.
+ *
+ *
+ *
+ * \section secConstraintsPropagation Constraints Propagation
+ *
+ * The only source of constraints being the anchored \c AutoContact
+ * we do a full propagation from each of them. Propagation is done
+ * through \c AutoSegment as follow :
+ *
+ * Obviously, any constraint diseapear after we have gone through
+ * exactly one horizontal and one vertical, thus the propagation is
+ * somewhat limited.
+ *
+ * Case of collapsed \c AutoSegment : those are to be kept at
+ * zero-length, thus they act as a bypass between two \c AutoContact.
+ * Their source and target can be considered as stacked
+ * and propagate both vertical and horizontal constraint (that is :
+ * the whole constraint \c Box).
+ *
+ *
+ * \section secCollapseUncollapse Collapsing & Uncollapsing
+ *
+ * Only local \c AutoSegment can be collapsed, as a global
+ * \c AutoSegment crosses the boundary of at least one \c FCell
+ * it can't have a null length.
+ *
+ * When collapsing a new \c AutoSegment, we can do an incremental
+ * constraint computation as it will result in a further increase
+ * of constraint (if any).
+ *
+ * When uncollapsing an \c AutoSegment we may have to slacken the
+ * constraint, but we do not know to which extend. So to make it
+ * simple we fully recompute constraints from scratch.
+ *
+ * Note that collapsing/uncollapsing are exceptionnal operations,
+ * so we can afford losing a little time there.
+ *
+ *
+ * \section secCollapseExample progressive Collapsing Example
+ *
+ * In this set of example we show how constraints propagate along the
+ * \c AutoSegment, depending on the collapsed ones. We starts we no
+ * collapse and ends with all \e local \c AutoSegment collapseds.
+ *
+ * \image html NetConstraints-1.png "Fully expanded"
+ * \image latex NetConstraints-1.pdf "Fully expanded" width=0.4\textwidth
+ * \image html NetConstraints-2.png "After One Vertical collapse"
+ * \image latex NetConstraints-2.pdf "After One Vertical collapse" width=0.4\textwidth
+ * \image html NetConstraints-3.png "After Horizontal collapse"
+ * \image latex NetConstraints-3.pdf "After Horizontal collapse" width=0.4\textwidth
+ * \image html NetConstraints-4.png "Fully collapsed"
+ * \image latex NetConstraints-4.pdf "Fully collapsed" width=0.4\textwidth
+ */
+
+
+ //! \addtogroup NetConstraints
+ //! \{
+
+ /*! \function void KatabaticEngine::_computeNetConstraints ( Net* net );
+ * \param net The net for which to compute constraints.
+ *
+ * compute constraints on a net.
+ */
+
+ //! \}
+
+ }
diff --git a/katabatic/doc/NetOptimals.dox b/katabatic/doc/NetOptimals.dox
new file mode 100644
index 00000000..25109761
--- /dev/null
+++ b/katabatic/doc/NetOptimals.dox
@@ -0,0 +1,59 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \defgroup NetOptimals 6. AutoSegment Optimal Placement (internal)
+ *
+ * This modules documents how \c AutoSegment optimal placement are computed.
+ * It is intented for developpers only.
+ *
+ * The principle is quite simple : for any given \c AutoSegment, for example
+ * a vertical one (\b A), we want to find the optimal position so the wire
+ * length of \c AutoSegment perpandicular to \b A would be minimal. This
+ * optimal position is an interval of X positions, possibly reduced to a
+ * point.
+ *
+ * Given an \c AutoSegment, we will take into account :
+ *
+ *
Perpandicular global \c AutoSegment.
+ *
Terminals linked to the \c AutoSegment through any number of
+ * local \c AutoSegment (collapsed or not).
+ *
+ *
+ * How to find the optimal interval :
+ *
+ * First we build an histogram in the direction perpandicular to the
+ * \c AutoSegment. For \b A : in horizontal direction. We populate the
+ * histogram with the axis coordinate of global \c AutoSegment and
+ * terminals linked to \b A. Note that for global \c AutoSegment the
+ * "axis" coordinate is the position of the side of the \c FCell.
+ * For terminal depending on their orientation relative to \b A we
+ * add either their axis or their two extremities.
+ *
+ * The optimal interval is then the median interval of the histogram.
+ *
+ * The set of examples below shows some representative cases.
+ *
+ * \image html NetOptimals-1.png "Multiple Verticals Terminals"
+ * \image latex NetOptimals-1.pdf "Multiple Verticals Terminals" width=0.6\textwidth
+ * \image html NetOptimals-2.png "Globals Only"
+ * \image latex NetOptimals-2.pdf "Globals Only" width=0.6\textwidth
+ * \image html NetOptimals-3.png "One Horizontal Terminal"
+ * \image latex NetOptimals-3.pdf "One Horizontal Terminal" width=0.6\textwidth
+ */
+
+
+ //! \addtogroup NetOptimals
+ //! \{
+
+ /*! \function void KatabaticEngine::_computeNetOptimals ( Net* net );
+ * \param net The net for which to compute optimal placement.
+ *
+ * compute optimal placement of all net's AutoSegment.
+ */
+
+ //! \}
+
+ }
diff --git a/katabatic/doc/Session.dox b/katabatic/doc/Session.dox
new file mode 100644
index 00000000..8fd7e15f
--- /dev/null
+++ b/katabatic/doc/Session.dox
@@ -0,0 +1,153 @@
+
+ // -*- C++ -*-
+
+
+ namespace Katabatic {
+
+ /*! \defgroup katabaticSession 7. Katabatic update Session Mechanism (internal)
+ *
+ * This module documents the Katabatic update Session Mechanism.
+ * It is intented for developpers only.
+ *
+ *
+ * \section secSessionGoal Goal of The Katabatic::Session
+ *
+ * Due to obvious performance issue, we do not recompute the
+ * geometry of source and target of a Katabatic::AutoSegment
+ * each time it's moved by the router. Instead we uses a simple
+ * queuing mechanism : the Katabatic::Session.
+ *
+ * Note that, most of the time, the router only moves segments,
+ * that is, never modifies directly Katabatic::AutoContact.
+ * The only exceptions being during the initial building stage
+ * or when the router decide to change the topology of a net.
+ *
+ * The router knows which Katabatic::AutoSegment it has moved,
+ * but during the update of a Katabatic::AutoContact geometry
+ * more segments will be modified. The modification being a
+ * change in their soure and/or target extention. And of thoses
+ * the router will not know about. To solve this problem,
+ * the router has to set a callback Katabatic::SegmentRevalidateCB
+ * which will be called for each modificated Katabatic::AutoSegment.
+ *
+ * Note that, in order to uniformize the procedure, this callback
+ * will also be run on Katabatic::AutoSegment modificated by
+ * the router.
+ *
+ *
+ * \section secSectionLookup The lookup function.
+ *
+ * To find a Katabatic::AutoSegment from it's associated \Hurricane
+ * segment, we build a simple \STL map in the Katabatic \c ToolEngine.
+ * This lookup table, can be accessed through the Session lookup()
+ * function, once the session is open.
+ *
+ *
+ * \section secSessionRevalidate The Revalidate procedure
+ *
+ * The sequence of calls is as follow :
+ *
+ *
The Router modifies some Katabatic::AutoSegment by moving
+ * their axis. For example, horizontal segments in an horizontal
+ * routing channel.
+ *
The Katabatic::AutoSegment is then invalidated : put in the
+ * invalidated segment set. It's Katabatic::AutoContact anchors
+ * are also invalidated and put in the set of invalidated contacts.
+ *
At some point, a global revalidation is performed :
+ * Katabatic::Session::revalidate(). Says, when the channel
+ * is successfully routed.
+ *
Katabatic::updateGeometry() is called and update the
+ * geometry of all invalided Katabatic::AutoContact. Doing so
+ * almost surely leads to the invalidation of more Katabatic::AutoSegment
+ * which are added to the invalidated set. In this example, as
+ * we moved horizontal segments, the new invalidated segments
+ * will be vertical ones incident to the formers.
+ *
Finally we call Katabatic::AutoSegment::onRevalidate()
+ * fonction for each Katabatic::AutoSegment.
+ * This function encapsulate the callback from the router, so it
+ * can take into account the segment extension change.
+ *
+ *
+ * \image html AutoInvalidate-1.png "Revalidate Procedure"
+ * \image latex AutoInvalidate-1.pdf "Revalidate Procedure" width=0.9\textwidth
+ *
+ *
+ * \section secStaticAccess The Static Member choice
+ *
+ * Almost all Session function members are \c static, this is
+ * because they refers to the currently opened Session which is
+ * kept entirely internal to the \c KatabaticSession module.
+ * This avoid carrying a global variable for the Session object.
+ */
+
+
+ /*! \class Session
+ * \brief Katabatic update Session (\b API).
+ *
+ * The Katabatic Session is mandatory before any AutoSegment /
+ * AutoContact to be modified (supposedly by a router).
+ *
+ * Unlike \Hurricane \c update \c Session only one session
+ * can be opened at a time (no stacking mechanism). Opening a
+ * Katabatic update Session also opens an \Hurricane \c update
+ * \c Session.
+ *
+ * For details on how Katabatic Sessions works, have a look to
+ * \ref katabaticSession.
+ */
+
+ /*! \function static Session* Session::get ();
+ * \return The currently opened session, \c NULL if no session has
+ * been opened.
+ */
+
+ /*! \function static Katabatic* Session::getKatabatic ();
+ * \return The Katabatic ToolEngine associated to the current update
+ * session.
+ */
+
+ /*! \function static AutoSegment* Session::lookup ( Segment* segment );
+ * \param segment An \Hurricane segment.
+ * \return The associated Katabatic AutoSegment.
+ *
+ * For this function to work, a Katabatic Session must be opened
+ * as it's a simple bypass to the Katabatic::_Lookup() member.
+ */
+
+ /*! \function static Session* Session::open ( KatabaticEngine* ktbt );
+ * \param ktbt A Katabatic ToolEngine on which to work.
+ *
+ * Open a new Katabatic update Session on the \c ktbt \c ToolEngine.
+ * At this point only one session can be opened at a time. Attempt
+ * to open a second one will result in an exception.
+ */
+
+ /*! \function static size_t Session::close ();
+ * \return The number of AutoContact / AutoSegment that have been revalidateds.
+ *
+ * Ends an update Session. This functions made a call to Revalidate to
+ * ensure that no AutoContact / AutoSegment remains invalidated.
+ */
+
+ /*! \function static size_t Session::revalidate ();
+ * \return The number of AutoContact / AutoSegment that have been revalidateds.
+ *
+ * Revalidate all AutoContact / AutoSegment currently in the queue :
+ * that is, update the AutoContact geometry and AutoSegment extentions.
+ */
+
+ /*! \function void Session::invalidate ( AutoSegment* segment );
+ * \param segment An AutoSegment that has been moved.
+ *
+ * The invalidated AutoSegment are stored into a \STL set,
+ * so it can be added multiples times without problems.
+ */
+
+ /*! \function void Session::invalidate ( AutoContact* contact );
+ * \param contact An AutoContact of which a AutoSegment has been moved.
+ *
+ * The invalidated AutoContact are stored into a \STL set,
+ * so it can be added multiples times without problems.
+ */
+
+ }
diff --git a/katabatic/doc/asimbook.cls b/katabatic/doc/asimbook.cls
new file mode 100644
index 00000000..54270780
--- /dev/null
+++ b/katabatic/doc/asimbook.cls
@@ -0,0 +1,798 @@
+%%
+%% This is file `book.cls',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% classes.dtx (with options: `book')
+%%
+%% This is a generated file.
+%%
+%% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001
+%% The LaTeX3 Project and any individual authors listed elsewhere
+%% in this file.
+%%
+%% This file was generated from file(s) of the LaTeX base system.
+%% --------------------------------------------------------------
+%%
+%% It may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.2
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.2 or later is part of all distributions of LaTeX
+%% version 1999/12/01 or later.
+%%
+%% This file may only be distributed together with a copy of the LaTeX
+%% base system. You may however distribute the LaTeX base system without
+%% such generated files.
+%%
+%% The list of all files belonging to the LaTeX base distribution is
+%% given in the file `manifest.txt'. See also `legal.txt' for additional
+%% information.
+%%
+%% \CharacterTable
+%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%% Digits \0\1\2\3\4\5\6\7\8\9
+%% Exclamation \! Double quote \" Hash (number) \#
+%% Dollar \$ Percent \% Ampersand \&
+%% Acute accent \' Left paren \( Right paren \)
+%% Asterisk \* Plus \+ Comma \,
+%% Minus \- Point \. Solidus \/
+%% Colon \: Semicolon \; Less than \<
+%% Equals \= Greater than \> Question mark \?
+%% Commercial at \@ Left bracket \[ Backslash \\
+%% Right bracket \] Circumflex \^ Underscore \_
+%% Grave accent \` Left brace \{ Vertical bar \|
+%% Right brace \} Tilde \~}
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{asimbook}
+ [2005/11/21 v1.0
+ ASIM LaTeX document class]
+\newcommand\@ptsize{}
+\newif\if@restonecol
+\newif\if@titlepage
+\@titlepagetrue
+\newif\if@openright
+\newif\if@mainmatter \@mainmattertrue
+\if@compatibility\else
+\DeclareOption{a4paper}
+ {\setlength\paperheight {297mm}%
+ \setlength\paperwidth {210mm}}
+\DeclareOption{a5paper}
+ {\setlength\paperheight {210mm}%
+ \setlength\paperwidth {148mm}}
+\DeclareOption{b5paper}
+ {\setlength\paperheight {250mm}%
+ \setlength\paperwidth {176mm}}
+\DeclareOption{letterpaper}
+ {\setlength\paperheight {11in}%
+ \setlength\paperwidth {8.5in}}
+\DeclareOption{legalpaper}
+ {\setlength\paperheight {14in}%
+ \setlength\paperwidth {8.5in}}
+\DeclareOption{executivepaper}
+ {\setlength\paperheight {10.5in}%
+ \setlength\paperwidth {7.25in}}
+\DeclareOption{landscape}
+ {\setlength\@tempdima {\paperheight}%
+ \setlength\paperheight {\paperwidth}%
+ \setlength\paperwidth {\@tempdima}}
+\fi
+\if@compatibility
+ \renewcommand\@ptsize{0}
+\else
+\DeclareOption{10pt}{\renewcommand\@ptsize{0}}
+\fi
+\DeclareOption{11pt}{\renewcommand\@ptsize{1}}
+\DeclareOption{12pt}{\renewcommand\@ptsize{2}}
+\if@compatibility\else
+\DeclareOption{oneside}{\@twosidefalse \@mparswitchfalse}
+\fi
+\DeclareOption{twoside}{\@twosidetrue \@mparswitchtrue}
+\DeclareOption{draft}{\setlength\overfullrule{5pt}}
+\if@compatibility\else
+\DeclareOption{final}{\setlength\overfullrule{0pt}}
+\fi
+\DeclareOption{titlepage}{\@titlepagetrue}
+\if@compatibility\else
+\DeclareOption{notitlepage}{\@titlepagefalse}
+\fi
+\if@compatibility
+\@openrighttrue
+\else
+\DeclareOption{openright}{\@openrighttrue}
+\DeclareOption{openany}{\@openrightfalse}
+\fi
+\if@compatibility\else
+\DeclareOption{onecolumn}{\@twocolumnfalse}
+\fi
+\DeclareOption{twocolumn}{\@twocolumntrue}
+\DeclareOption{leqno}{\input{leqno.clo}}
+\DeclareOption{fleqn}{\input{fleqn.clo}}
+\DeclareOption{openbib}{%
+ \AtEndOfPackage{%
+ \renewcommand\@openbib@code{%
+ \advance\leftmargin\bibindent
+ \itemindent -\bibindent
+ \listparindent \itemindent
+ \parsep \z@
+ }%
+ \renewcommand\newblock{\par}}%
+}
+\ExecuteOptions{letterpaper,10pt,twoside,onecolumn,final,openright}
+\ProcessOptions
+\input{bk1\@ptsize.clo}
+\setlength\lineskip{1\p@}
+\setlength\normallineskip{1\p@}
+\renewcommand\baselinestretch{}
+\setlength\parskip{0\p@ \@plus \p@}
+\@lowpenalty 51
+\@medpenalty 151
+\@highpenalty 301
+\setcounter{topnumber}{2}
+\renewcommand\topfraction{.7}
+\setcounter{bottomnumber}{1}
+\renewcommand\bottomfraction{.3}
+\setcounter{totalnumber}{3}
+\renewcommand\textfraction{.2}
+\renewcommand\floatpagefraction{.5}
+\setcounter{dbltopnumber}{2}
+\renewcommand\dbltopfraction{.7}
+\renewcommand\dblfloatpagefraction{.5}
+%%%% Select Chapter font.
+\newcommand \textchapter [1] {\textsf{\textbf{#1}}}
+\newcommand \fontchapter {\sffamily \bfseries}
+\if@twoside
+ \def\ps@headings{%
+ \let\@oddfoot\@empty\let\@evenfoot\@empty
+ \def\@evenhead{\thepage\hfil\slshape\leftmark}%
+ \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
+ \let\@mkboth\markboth
+ \def\chaptermark##1{%
+ \markboth {\MakeUppercase{%
+ \ifnum \c@secnumdepth >\m@ne
+ \if@mainmatter
+ \@chapapp\ \thechapter. \ %
+ \fi
+ \fi
+ ##1}}{}}%
+ \def\sectionmark##1{%
+ \markright {\MakeUppercase{%
+ \ifnum \c@secnumdepth >\z@
+ \thesection. \ %
+ \fi
+ ##1}}}}
+\else
+ \def\ps@headings{%
+ \let\@oddfoot\@empty
+ \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
+ \let\@mkboth\markboth
+ \def\chaptermark##1{%
+ \markright {\MakeUppercase{%
+ \ifnum \c@secnumdepth >\m@ne
+ \if@mainmatter
+ \@chapapp\ \thechapter. \ %
+ \fi
+ \fi
+ ##1}}}}
+\fi
+\def\ps@myheadings{%
+ \let\@oddfoot\@empty\let\@evenfoot\@empty
+ \def\@evenhead{\thepage\hfil\slshape\leftmark}%
+ \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
+ \let\@mkboth\@gobbletwo
+ \let\chaptermark\@gobble
+ \let\sectionmark\@gobble
+ }
+ \if@titlepage
+ \newcommand\maketitle{\begin{titlepage}%
+ \let\footnotesize\small
+ \let\footnoterule\relax
+ \let \footnote \thanks
+ \null\vfil
+ \vskip 60\p@
+ \begin{center}%
+ {\LARGE \@title \par}%
+ \vskip 3em%
+ {\large
+ \lineskip .75em%
+ \begin{tabular}[t]{c}%
+ \@author
+ \end{tabular}\par}%
+ \vskip 1.5em%
+ {\large \@date \par}% % Set date in \large size.
+ \end{center}\par
+ \@thanks
+ \vfil\null
+ \end{titlepage}%
+ \setcounter{footnote}{0}%
+ \global\let\thanks\relax
+ \global\let\maketitle\relax
+ \global\let\@thanks\@empty
+ \global\let\@author\@empty
+ \global\let\@date\@empty
+ \global\let\@title\@empty
+ \global\let\title\relax
+ \global\let\author\relax
+ \global\let\date\relax
+ \global\let\and\relax
+}
+\else
+\newcommand\maketitle{\par
+ \begingroup
+ \renewcommand\thefootnote{\@fnsymbol\c@footnote}%
+ \def\@makefnmark{\rlap{\@textsuperscript{\normalfont\@thefnmark}}}%
+ \long\def\@makefntext##1{\parindent 1em\noindent
+ \hb@xt@1.8em{%
+ \hss\@textsuperscript{\normalfont\@thefnmark}}##1}%
+ \if@twocolumn
+ \ifnum \col@number=\@ne
+ \@maketitle
+ \else
+ \twocolumn[\@maketitle]%
+ \fi
+ \else
+ \newpage
+ \global\@topnum\z@ % Prevents figures from going at top of page.
+ \@maketitle
+ \fi
+ \thispagestyle{plain}\@thanks
+ \endgroup
+ \setcounter{footnote}{0}%
+ \global\let\thanks\relax
+ \global\let\maketitle\relax
+ \global\let\@maketitle\relax
+ \global\let\@thanks\@empty
+ \global\let\@author\@empty
+ \global\let\@date\@empty
+ \global\let\@title\@empty
+ \global\let\title\relax
+ \global\let\author\relax
+ \global\let\date\relax
+ \global\let\and\relax
+}
+\def\@maketitle{%
+ \newpage
+ \null
+ \vskip 2em%
+ \begin{center}%
+ \let \footnote \thanks
+ {\LARGE \@title \par}%
+ \vskip 1.5em%
+ {\large
+ \lineskip .5em%
+ \begin{tabular}[t]{c}%
+ \@author
+ \end{tabular}\par}%
+ \vskip 1em%
+ {\large \@date}%
+ \end{center}%
+ \par
+ \vskip 1.5em}
+\fi
+\newcommand*\chaptermark[1]{}
+\setcounter{secnumdepth}{2}
+\newcounter {part}
+\newcounter {chapter}
+\newcounter {section}[chapter]
+\newcounter {subsection}[section]
+\newcounter {subsubsection}[subsection]
+\newcounter {paragraph}[subsubsection]
+\newcounter {subparagraph}[paragraph]
+\renewcommand \thepart {\@Roman\c@part}
+\renewcommand \thechapter {\@arabic\c@chapter}
+\renewcommand \thesection {\thechapter.\@arabic\c@section}
+\renewcommand\thesubsection {\thesection.\@arabic\c@subsection}
+\renewcommand\thesubsubsection{\thesubsection .\@arabic\c@subsubsection}
+\renewcommand\theparagraph {\thesubsubsection.\@arabic\c@paragraph}
+\renewcommand\thesubparagraph {\theparagraph.\@arabic\c@subparagraph}
+\newcommand\@chapapp{\chaptername}
+\newcommand\frontmatter{%
+ \cleardoublepage
+ \@mainmatterfalse
+ \pagenumbering{roman}}
+\newcommand\mainmatter{%
+ \cleardoublepage
+ \@mainmattertrue
+ \pagenumbering{arabic}}
+\newcommand\backmatter{%
+ \if@openright
+ \cleardoublepage
+ \else
+ \clearpage
+ \fi
+ \@mainmatterfalse}
+\newcommand\part{%
+ \if@openright
+ \cleardoublepage
+ \else
+ \clearpage
+ \fi
+ \thispagestyle{plain}%
+ \if@twocolumn
+ \onecolumn
+ \@tempswatrue
+ \else
+ \@tempswafalse
+ \fi
+ \null\vfil
+ \secdef\@part\@spart}
+
+\def\@part[#1]#2{%
+ \ifnum \c@secnumdepth >-2\relax
+ \refstepcounter{part}%
+ \addcontentsline{toc}{part}{\thepart\hspace{1em}#1}%
+ \else
+ \addcontentsline{toc}{part}{#1}%
+ \fi
+ \markboth{}{}%
+ {\centering
+ \interlinepenalty \@M
+ \normalfont
+ \ifnum \c@secnumdepth >-2\relax
+ \huge\bfseries \partname\nobreakspace\thepart
+ \par
+ \vskip 20\p@
+ \fi
+ \Huge \bfseries #2\par}%
+ \@endpart}
+\def\@spart#1{%
+ {\centering
+ \interlinepenalty \@M
+ \normalfont
+ \Huge \bfseries #1\par}%
+ \@endpart}
+\def\@endpart{\vfil\newpage
+ \if@twoside
+ \if@openright
+ \null
+ \thispagestyle{empty}%
+ \newpage
+ \fi
+ \fi
+ \if@tempswa
+ \twocolumn
+ \fi}
+\newcommand\chapter{\if@openright\cleardoublepage\else\clearpage\fi
+ \thispagestyle{plain}%
+ \global\@topnum\z@
+ \@afterindentfalse
+ \secdef\@chapter\@schapter}
+\def\@chapter[#1]#2{\ifnum \c@secnumdepth >\m@ne
+ \if@mainmatter
+ \refstepcounter{chapter}%
+ \typeout{\@chapapp\space\thechapter.}%
+ \addcontentsline{toc}{chapter}%
+ {\protect\numberline{\thechapter}#1}%
+ \else
+ \addcontentsline{toc}{chapter}{#1}%
+ \fi
+ \else
+ \addcontentsline{toc}{chapter}{#1}%
+ \fi
+ \chaptermark{#1}%
+ \addtocontents{lof}{\protect\addvspace{10\p@}}%
+ \addtocontents{lot}{\protect\addvspace{10\p@}}%
+ \if@twocolumn
+ \@topnewpage[\@makechapterhead{#2}]%
+ \else
+ \@makechapterhead{#2}%
+ \@afterheading
+ \fi}
+%%%%\def\@makechapterhead#1{%
+%%%% \vspace*{50\p@}%
+%%%% {\parindent \z@ \raggedright \normalfont
+%%%% \ifnum \c@secnumdepth >\m@ne
+%%%% \if@mainmatter
+%%%% \huge\bfseries \@chapapp\space \thechapter
+%%%% \par\nobreak
+%%%% \vskip 20\p@
+%%%% \fi
+%%%% \fi
+%%%% \interlinepenalty\@M
+%%%% \Huge \bfseries #1\par\nobreak
+%%%% \vskip 40\p@
+%%%% }}
+ \newlength \titlewidth
+ \setlength \titlewidth {\textwidth}
+ \addtolength \titlewidth {\marginparwidth}
+ \addtolength \titlewidth {\marginparsep}
+ \def\@makechapterhead#1{%
+ \vspace*{50\p@}%
+ {\parindent \z@ \raggedleft \fontchapter
+ \ifnum \c@secnumdepth >\m@ne
+ \if@mainmatter
+ \huge \@chapapp\space \thechapter
+ \par\nobreak
+ \vskip 20\p@
+ \fi
+ \fi
+ \interlinepenalty\@M
+ \hsize=\titlewidth
+ \Huge #1 \par\nobreak
+ \hsize=\textwidth
+ \vskip 40\p@
+ }}
+\def\@schapter#1{\if@twocolumn
+ \@topnewpage[\@makeschapterhead{#1}]%
+ \else
+ \@makeschapterhead{#1}%
+ \@afterheading
+ \fi}
+%%%%\def\@makeschapterhead#1{%
+%%%% \vspace*{50\p@}%
+%%%% {\parindent \z@ \raggedright
+%%%% \normalfont
+%%%% \interlinepenalty\@M
+%%%% \Huge \bfseries #1\par\nobreak
+%%%% \vskip 40\p@
+%%%% }}
+ \def\@makeschapterhead#1{%
+ \vspace*{50\p@}%
+ {\parindent \z@ \raggedright
+ \normalfont
+ \interlinepenalty\@M
+ \hsize=\titlewidth
+ \flushright
+ \Huge \bfseries #1\par\nobreak
+ \hsize=\textwidth
+ \vskip 40\p@
+ }}
+\newcommand\section{\@startsection {section}{1}{\z@}%
+ {-3.5ex \@plus -1ex \@minus -.2ex}%
+ {2.3ex \@plus.2ex}%
+ {\normalfont\Large\bfseries}}
+\newcommand\subsection{\@startsection{subsection}{2}{\z@}%
+ {-3.25ex\@plus -1ex \@minus -.2ex}%
+ {1.5ex \@plus .2ex}%
+ {\normalfont\large\bfseries}}
+\newcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}%
+ {-3.25ex\@plus -1ex \@minus -.2ex}%
+ {1.5ex \@plus .2ex}%
+ {\normalfont\normalsize\bfseries}}
+\newcommand\paragraph{\@startsection{paragraph}{4}{\z@}%
+ {3.25ex \@plus1ex \@minus.2ex}%
+ {-1em}%
+ {\normalfont\normalsize\bfseries}}
+\newcommand\subparagraph{\@startsection{subparagraph}{5}{\parindent}%
+ {3.25ex \@plus1ex \@minus .2ex}%
+ {-1em}%
+ {\normalfont\normalsize\bfseries}}
+\if@twocolumn
+ \setlength\leftmargini {2em}
+\else
+ \setlength\leftmargini {2.5em}
+\fi
+\leftmargin \leftmargini
+\setlength\leftmarginii {2.2em}
+\setlength\leftmarginiii {1.87em}
+\setlength\leftmarginiv {1.7em}
+\if@twocolumn
+ \setlength\leftmarginv {.5em}
+ \setlength\leftmarginvi {.5em}
+\else
+ \setlength\leftmarginv {1em}
+ \setlength\leftmarginvi {1em}
+\fi
+\setlength \labelsep {.5em}
+\setlength \labelwidth{\leftmargini}
+\addtolength\labelwidth{-\labelsep}
+\@beginparpenalty -\@lowpenalty
+\@endparpenalty -\@lowpenalty
+\@itempenalty -\@lowpenalty
+\renewcommand\theenumi{\@arabic\c@enumi}
+\renewcommand\theenumii{\@alph\c@enumii}
+\renewcommand\theenumiii{\@roman\c@enumiii}
+\renewcommand\theenumiv{\@Alph\c@enumiv}
+\newcommand\labelenumi{\theenumi.}
+\newcommand\labelenumii{(\theenumii)}
+\newcommand\labelenumiii{\theenumiii.}
+\newcommand\labelenumiv{\theenumiv.}
+\renewcommand\p@enumii{\theenumi}
+\renewcommand\p@enumiii{\theenumi(\theenumii)}
+\renewcommand\p@enumiv{\p@enumiii\theenumiii}
+\newcommand\labelitemi{\textbullet}
+\newcommand\labelitemii{\normalfont\bfseries \textendash}
+\newcommand\labelitemiii{\textasteriskcentered}
+\newcommand\labelitemiv{\textperiodcentered}
+\newenvironment{description}
+ {\list{}{\labelwidth\z@ \itemindent-\leftmargin
+ \let\makelabel\descriptionlabel}}
+ {\endlist}
+\newcommand*\descriptionlabel[1]{\hspace\labelsep
+ \normalfont\bfseries #1}
+\newenvironment{verse}
+ {\let\\\@centercr
+ \list{}{\itemsep \z@
+ \itemindent -1.5em%
+ \listparindent\itemindent
+ \rightmargin \leftmargin
+ \advance\leftmargin 1.5em}%
+ \item\relax}
+ {\endlist}
+\newenvironment{quotation}
+ {\list{}{\listparindent 1.5em%
+ \itemindent \listparindent
+ \rightmargin \leftmargin
+ \parsep \z@ \@plus\p@}%
+ \item\relax}
+ {\endlist}
+\newenvironment{quote}
+ {\list{}{\rightmargin\leftmargin}%
+ \item\relax}
+ {\endlist}
+\if@compatibility
+\newenvironment{titlepage}
+ {%
+ \cleardoublepage
+ \if@twocolumn
+ \@restonecoltrue\onecolumn
+ \else
+ \@restonecolfalse\newpage
+ \fi
+ \thispagestyle{empty}%
+ \setcounter{page}\z@
+ }%
+ {\if@restonecol\twocolumn \else \newpage \fi
+ }
+\else
+\newenvironment{titlepage}
+ {%
+ \cleardoublepage
+ \if@twocolumn
+ \@restonecoltrue\onecolumn
+ \else
+ \@restonecolfalse\newpage
+ \fi
+ \thispagestyle{empty}%
+ \setcounter{page}\@ne
+ }%
+ {\if@restonecol\twocolumn \else \newpage \fi
+ \if@twoside\else
+ \setcounter{page}\@ne
+ \fi
+ }
+\fi
+\newcommand\appendix{\par
+ \setcounter{chapter}{0}%
+ \setcounter{section}{0}%
+ \gdef\@chapapp{\appendixname}%
+ \gdef\thechapter{\@Alph\c@chapter}}
+\setlength\arraycolsep{5\p@}
+\setlength\tabcolsep{6\p@}
+\setlength\arrayrulewidth{.4\p@}
+\setlength\doublerulesep{2\p@}
+\setlength\tabbingsep{\labelsep}
+\skip\@mpfootins = \skip\footins
+\setlength\fboxsep{3\p@}
+\setlength\fboxrule{.4\p@}
+\@addtoreset {equation}{chapter}
+\renewcommand\theequation
+ {\ifnum \c@chapter>\z@ \thechapter.\fi \@arabic\c@equation}
+\newcounter{figure}[chapter]
+\renewcommand \thefigure
+ {\ifnum \c@chapter>\z@ \thechapter.\fi \@arabic\c@figure}
+\def\fps@figure{tbp}
+\def\ftype@figure{1}
+\def\ext@figure{lof}
+\def\fnum@figure{\figurename\nobreakspace\thefigure}
+\newenvironment{figure}
+ {\@float{figure}}
+ {\end@float}
+\newenvironment{figure*}
+ {\@dblfloat{figure}}
+ {\end@dblfloat}
+\newcounter{table}[chapter]
+\renewcommand \thetable
+ {\ifnum \c@chapter>\z@ \thechapter.\fi \@arabic\c@table}
+\def\fps@table{tbp}
+\def\ftype@table{2}
+\def\ext@table{lot}
+\def\fnum@table{\tablename\nobreakspace\thetable}
+\newenvironment{table}
+ {\@float{table}}
+ {\end@float}
+\newenvironment{table*}
+ {\@dblfloat{table}}
+ {\end@dblfloat}
+\newlength\abovecaptionskip
+\newlength\belowcaptionskip
+\setlength\abovecaptionskip{10\p@}
+\setlength\belowcaptionskip{0\p@}
+\long\def\@makecaption#1#2{%
+ \vskip\abovecaptionskip
+ \sbox\@tempboxa{#1: #2}%
+ \ifdim \wd\@tempboxa >\hsize
+ #1: #2\par
+ \else
+ \global \@minipagefalse
+ \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}%
+ \fi
+ \vskip\belowcaptionskip}
+\DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
+\DeclareOldFontCommand{\sf}{\normalfont\sffamily}{\mathsf}
+\DeclareOldFontCommand{\tt}{\normalfont\ttfamily}{\mathtt}
+\DeclareOldFontCommand{\bf}{\normalfont\bfseries}{\mathbf}
+\DeclareOldFontCommand{\it}{\normalfont\itshape}{\mathit}
+\DeclareOldFontCommand{\sl}{\normalfont\slshape}{\@nomath\sl}
+\DeclareOldFontCommand{\sc}{\normalfont\scshape}{\@nomath\sc}
+\DeclareRobustCommand*\cal{\@fontswitch\relax\mathcal}
+\DeclareRobustCommand*\mit{\@fontswitch\relax\mathnormal}
+\newcommand\@pnumwidth{1.55em}
+\newcommand\@tocrmarg{2.55em}
+\newcommand\@dotsep{4.5}
+\setcounter{tocdepth}{2}
+\newcommand\tableofcontents{%
+ \if@twocolumn
+ \@restonecoltrue\onecolumn
+ \else
+ \@restonecolfalse
+ \fi
+ \chapter*{\contentsname
+ \@mkboth{%
+ \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}%
+ \@starttoc{toc}%
+ \if@restonecol\twocolumn\fi
+ }
+\newcommand*\l@part[2]{%
+ \ifnum \c@tocdepth >-2\relax
+ \addpenalty{-\@highpenalty}%
+ \addvspace{2.25em \@plus\p@}%
+ \setlength\@tempdima{3em}%
+ \begingroup
+ \parindent \z@ \rightskip \@pnumwidth
+ \parfillskip -\@pnumwidth
+ {\leavevmode
+ \large \bfseries #1\hfil \hb@xt@\@pnumwidth{\hss #2}}\par
+ \nobreak
+ \global\@nobreaktrue
+ \everypar{\global\@nobreakfalse\everypar{}}%
+ \endgroup
+ \fi}
+%%%%\newcommand*\l@chapter[2]{%
+%%%% \ifnum \c@tocdepth >\m@ne
+%%%% \addpenalty{-\@highpenalty}%
+%%%% \vskip 1.0em \@plus\p@
+%%%% \setlength\@tempdima{1.5em}%
+%%%% \begingroup
+%%%% \parindent \z@ \rightskip \@pnumwidth
+%%%% \parfillskip -\@pnumwidth
+%%%% \leavevmode \bfseries
+%%%% \advance\leftskip\@tempdima
+%%%% \hskip -\leftskip
+%%%% #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
+%%%% \penalty\@highpenalty
+%%%% \endgroup
+%%%% \fi}
+\newcommand\l@chapter[2]{%
+ \ifnum \c@tocdepth >\m@ne
+ \addpenalty{-\@highpenalty}%
+ \vskip 1.0em \@plus\p@
+ \setlength\@tempdima{1.5em}%
+ \begingroup
+ \parindent \z@ \rightskip \@pnumwidth
+ \parfillskip -\@pnumwidth
+ \leavevmode \fontchapter
+ \advance\leftskip\@tempdima
+ \hskip -\leftskip
+ #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
+ \penalty\@highpenalty
+ \endgroup
+ \fi}
+\newcommand*\l@section{\@dottedtocline{1}{1.5em}{2.3em}}
+\newcommand*\l@subsection{\@dottedtocline{2}{3.8em}{3.2em}}
+\newcommand*\l@subsubsection{\@dottedtocline{3}{7.0em}{4.1em}}
+\newcommand*\l@paragraph{\@dottedtocline{4}{10em}{5em}}
+\newcommand*\l@subparagraph{\@dottedtocline{5}{12em}{6em}}
+\newcommand\listoffigures{%
+ \if@twocolumn
+ \@restonecoltrue\onecolumn
+ \else
+ \@restonecolfalse
+ \fi
+ \chapter*{\listfigurename}%
+ \@mkboth{\MakeUppercase\listfigurename}%
+ {\MakeUppercase\listfigurename}%
+ \@starttoc{lof}%
+ \if@restonecol\twocolumn\fi
+ }
+\newcommand*\l@figure{\@dottedtocline{1}{1.5em}{2.3em}}
+\newcommand\listoftables{%
+ \if@twocolumn
+ \@restonecoltrue\onecolumn
+ \else
+ \@restonecolfalse
+ \fi
+ \chapter*{\listtablename}%
+ \@mkboth{%
+ \MakeUppercase\listtablename}%
+ {\MakeUppercase\listtablename}%
+ \@starttoc{lot}%
+ \if@restonecol\twocolumn\fi
+ }
+\let\l@table\l@figure
+\newdimen\bibindent
+\setlength\bibindent{1.5em}
+\newenvironment{thebibliography}[1]
+ {\chapter*{\bibname}%
+ \@mkboth{\MakeUppercase\bibname}{\MakeUppercase\bibname}%
+ \list{\@biblabel{\@arabic\c@enumiv}}%
+ {\settowidth\labelwidth{\@biblabel{#1}}%
+ \leftmargin\labelwidth
+ \advance\leftmargin\labelsep
+ \@openbib@code
+ \usecounter{enumiv}%
+ \let\p@enumiv\@empty
+ \renewcommand\theenumiv{\@arabic\c@enumiv}}%
+ \sloppy
+ \clubpenalty4000
+ \@clubpenalty \clubpenalty
+ \widowpenalty4000%
+ \sfcode`\.\@m}
+ {\def\@noitemerr
+ {\@latex@warning{Empty `thebibliography' environment}}%
+ \endlist}
+\newcommand\newblock{\hskip .11em\@plus.33em\@minus.07em}
+\let\@openbib@code\@empty
+\newenvironment{theindex}
+ {\if@twocolumn
+ \@restonecolfalse
+ \else
+ \@restonecoltrue
+ \fi
+ \columnseprule \z@
+ \columnsep 35\p@
+ \twocolumn[\@makeschapterhead{\indexname}]%
+ \@mkboth{\MakeUppercase\indexname}%
+ {\MakeUppercase\indexname}%
+ \thispagestyle{plain}\parindent\z@
+ \parskip\z@ \@plus .3\p@\relax
+ \let\item\@idxitem}
+ {\if@restonecol\onecolumn\else\clearpage\fi}
+\newcommand\@idxitem{\par\hangindent 40\p@}
+\newcommand\subitem{\@idxitem \hspace*{20\p@}}
+\newcommand\subsubitem{\@idxitem \hspace*{30\p@}}
+\newcommand\indexspace{\par \vskip 10\p@ \@plus5\p@ \@minus3\p@\relax}
+\renewcommand\footnoterule{%
+ \kern-3\p@
+ \hrule\@width.4\columnwidth
+ \kern2.6\p@}
+\@addtoreset{footnote}{chapter}
+\newcommand\@makefntext[1]{%
+ \parindent 1em%
+ \noindent
+ \hb@xt@1.8em{\hss\@makefnmark}#1}
+\newcommand\contentsname{Contents}
+\newcommand\listfigurename{List of Figures}
+\newcommand\listtablename{List of Tables}
+\newcommand\bibname{Bibliography}
+\newcommand\indexname{Index}
+\newcommand\figurename{Figure}
+\newcommand\tablename{Table}
+\newcommand\partname{Part}
+\newcommand\chaptername{Chapter}
+\newcommand\appendixname{Appendix}
+\def\today{\ifcase\month\or
+ January\or February\or March\or April\or May\or June\or
+ July\or August\or September\or October\or November\or December\fi
+ \space\number\day, \number\year}
+\setlength\columnsep{10\p@}
+\setlength\columnseprule{0\p@}
+\pagestyle{headings}
+\pagenumbering{arabic}
+\if@twoside
+\else
+ \raggedbottom
+\fi
+\if@twocolumn
+ \twocolumn
+ \sloppy
+ \flushbottom
+\else
+ \onecolumn
+\fi
+\endinput
+%%
+%% End of file `book.cls'.
diff --git a/katabatic/doc/customHierarchy.html b/katabatic/doc/customHierarchy.html
new file mode 100644
index 00000000..2b27d725
--- /dev/null
+++ b/katabatic/doc/customHierarchy.html
@@ -0,0 +1,110 @@
+
+
+
+
+
+ Katabatic Documentation
+
+
+
Global Routing Loading.
+ How the Knik global routing is loaded into Katabatic data-base.
+ Details the wiring topologies used to complete the routing to the
+ terminals.
+