// -*- C++ -*-
namespace KNIK {
/*! \class Edge
* \brief A routing graph edge.\n
* - \ref EdgeAttributes "Attributes"
* - \ref EdgeAccessors "Accessors"
* - \ref EdgeModifiers "Modifiers"
* - \ref EdgePredicates "Predicates"
*
* The Edge was written to be a light object which simplifies the way the routing graph is covered.
* Edges are thus separated into two sub-classes : VEdge and HEdge respectively representing vertical edge and
* horizontal edge.
*
* Considering one vertex \b V, we define 4 types of edge :
* <ul>
* <li> HEdgeOut: a Horizontal Edge linking \b V to a vertex \e w
* <li> VEdgeOut: a Vertical Edge linking \b V to a vertex \e x
* <li> HEdgeIn: a Horizontal Edge linking a vertex \e y to \b V
* <li> VEdgeIn: a Vertical Edge linking a vertex \e z to \b V
* </ul>
*
* \section secEdgeImplementation Edge Implementation
* The Global Router CEngine uses a technique based on routing graph and thus relies on another
* CEngine : Nimbus.
*/
/*! \anchor EdgeAttributes Attributes
* \name
*/
// \{
/*! \var Fence* Edge::_fence
* The corresponding fence in the partitionning
*
* \Initial by constructor
*/
/*! \var Splitter* Edge::_splitter
* The fence may already have a splitter associted with current net
*
* \Initial \NULL
*/
/*! \var Vertex* Edge::_from
* The source vertex
*
* \Initial by constructor
*/
/*! \var Edge* Edge::_nextFrom
* Next edge of the same type and with the same source vertex
*
* \Initial \NULL
*/
/*! \var Vertex* Edge::_to
* The target vertex
*
* \Initial by constructor
*/
/*! \var Edge* Edge::_nextTo
* Next edge of the same type and with the same target vertex
*
* \Initial \NULL
*/
/*! \var int Edge::_connexID
* The identification flag for connex component
*
* \Initial \p -1
* \see \ref grpConnexID
*/
/*! \var float Edge::_cost
* The cost of the edge
*
* \Initial \p 0.0
* \see Edge::GetCost
*/
/*! \var unsigned Edge::_capacity
* The capacity of the edge which is the copy of the fence capacity based on the routing ressources
*
* \Initial \p 0
*/
/*! \var unsigned Edge::_realOccupancy
* The occupancy of the edge based on the routed nets
*
* \Initial \p 0
*/
/*! \var float Edge::_estimateOccupancy
* The estimated occupancy of the edge based on the estimation technique
*
* \Initial \p 0.0
* \see Graph::UpdateEstimateCongestion
*/
/*! \var unsigned Edge::_netStamp
* The net stamp associated with the current net
*
* \Initial \p 0
* \see \ref grpNetStamp
*/
// \}
/*! \anchor EdgeAccessors Accessors
* \name
*/
// \{
/*! \function Nimbus::Fence* Edge::GetFence();
* \Return The corresponding Fence in the partitionning.
*/
/*! \function Vertex* Edge::GetFrom() const;
* \Return The source vertex of the edge.
*/
/*! \function Edge* Edge::GetNextFrom() const;
* \Return The next edge of the same type with the same source vertex if one exists, \NULL else.
*/
/*! \function Vertex* Edge::GetTo() const;
* \Return The target vertex of the edge.
*/
/*! \function Edge* Edge::GetNextTo() const;
* \Return The next edge of the same type with the same target vertex if one exists, \NULL else.
*/
/*! \function Edge* Edge::GetSplitter() const;
* \Return The splitter associated with the edge if one exists, \NULL else.
*/
/*! \function int* Edge::GetConnexID() const;
* \Return The ConnexID of the edge.
*/
/*! \function float* Edge::GetCapacity() const;
* \Return The capacity of the edge.
*/
/*! \function unsigned Edge::GetRealOccupancy() const;
* \return The occupancy of the edge based on the class member Edge::_realOccupancy
* \exception assert that Edge::_realOccupancy equals Edge::_fence->GetOccupancy()
*/
/*! \function unsigned Edge::GetNetStamp() const;
* \return The netStamp of the edge
* \see \ref grpNetStamp
*/
/*! \function Vertex* Edge::GetOpposite(const Vertex* v) const;
* \return The opposite vertex of the edge considering the one given as argument.
* \param v is the vertex of which we want to get the opposite one
* \exception assert that \e v is one of the 2 vertexes of the edge
*/
/*! \function float Edge::GetEstimateOccupancy() const;
* \return The estimated occupancy of the edge
* \note Althought the Edge::_realOccupancy is an \p unsigned \p int, the Edge::_estimateOccupancy is a \p float.
* \see Edge::GetCost
*/
/*! \function float Edge::GetCost ( Edge* arrivalEdge );
* \param arrivalEdge
* \return The cost of the edge Edge::_cost
*
* Edge::_cost is computed considering several variables:
* <ul>
* <li>\ref KNIK_USECONGESTION "__USE_CONGESTION__"
* <li>\ref KNIK_USESTATIC "__USE_STATIC_PRECONGESTION__"
* <li>\ref KNIK_USEDYNAMIC "__USE_DYNAMIC_PRECONGESTION__"
* </ul>
*
* <b>1st case: </b> None of the previous variables is defined :
*
* \code _cost = 1.0
* \endcode
*
* For <b>2nd</b> and <b>3rd case</b> the \ref KNIK_USECONGESTION "__USE_CONGESTION__" variable is defined which means that when
* computing the Edge::_cost the existing congestion is taken into account.
*
* The Edge::_cost is so computed according to a cost function such as the following exemple :
* \image html FonctionCout.png "Cost function for _cost"
* \image latex FonctionCout.pdf "Cost function for _cost" width=0.7\textwidth
*
* The corresponding code:
* \code
* float edge_capacity =(float)1.0;
* float edge_occupancy;
* float h = 9.0;
* float k = 30.0;
* ...
* _cost = 1.0 + (h / (1.0 + exp(-k * (edge_occupancy - edge_capacity))));
* \endcode
* The way \p edge_occupancy is computed depends on the variables defined :
*
* <b>2nd case: </b> only \ref KNIK_USECONGESTION "__USE_CONGESTION__" is defined :
* \code edge_occupancy = (float)GetRealOccupancy() / (float)_capacity;
* \endcode
*
* <b>3rd case: </b> \ref KNIK_USESTATIC "__USE_STATIC_PRECONGESTION__"
* or \ref KNIK_USEDYNAMIC "__USE_DYNAMIC_PRECONGESTION__" is defined :
* \code edge_occupancy = ((float)GetRealOccupancy() + GetEstimateOccupancy()) / (float)_capacity;
* \endcode
*
*/
/*! \function virtual Hook* Edge::GetSplitterHook ( Vertex* vertex ) = 0;
* \param vertex the vertex of the edge from which we want to get the splitter's hook
* \return The splitter's hook of the specified vertex
* \exception assert that Edge::_splitter exists
* \exception assert that the given vertex is Edge::_from or Edge::_to
* \note This function is pure virtual.
*/
// \}
/*! \anchor EdgeModifiers Modifiers
* \name
*/
// \{
/*! \function void Edge::SetNextFrom ( Edge* edge );
* \param edge is the next edge of the same type with the same source vertex
*/
/*! \function void Edge::SetNextTo ( Edge* edge );
* \param edge is the next edge of the same type with the same target vertex
*/
/*! \function void Edge::SetSplitter ( Splitter* splitter );
* \param splitter is the splitter associated to the edge for the current net
*/
/*! \function void Edge::SetConnexID ( int connexID );
* \param connexID is the connexID of the edge
* \see \ref grpConnexID
*/
/*! \function void Edge::SetCost ( float cost );
* \param cost is the new cost for the edge
*/
/*! \function void Edge::IncCost ( float inc );
* \param inc is an increment, it is added to the current Edge::_cost
*/
/*! \function void Edge::SetNetStamp ( unsigned netStamp );
* \param netStamp is the netStamp of the edge for the current net
* \see \ref grpNetStamp
*/
/*! \function void Edge::AddSubEstimateOccupancy ( float increment, bool add );
* \param increment is the value added / substracted to the estimate occupancy
* \param add is a boolean : if set to \True an addition is performed whether if set to \False a substraction is performed
*/
/*! \function virtual void Edge::CreateSplitter ( Net* net ) = 0;
* \param net the current net for which we want to create a splitter on the Edge
* \note This function is pure virtual.
*/
// \}
/*! \anchor EdgePredicates Predicates
* \name
*/
// \{
/*! \function virtual bool Edge::IsVertical ();
* \return Return \True if the edge is a vertical edge, else \False
* \note This function is pure virtual.
*/
/*! \function virtual bool Edge::IsHorizontal ();
* \return Return \True if the edge is a horizontal edge, else \False
* \note This function is pure virtual.
*/
// \}
/*! \defgroup grpConnexComponent What is a Connex Component ?
*
* \section secDefinition Definition
*
* A connex component is a set of vertexes and edges representing a connex part of a net, such as :
* <ul>
* <li> a connector contained in a GCell
* <li> a connector spread over several GCells
* <li> a pre-routed part of a net
* <li> an already routed part of a net (by previous steps)
* </ul>
*
* \image html ConnexComp.png "Connex components exemples for connectors (left) and a routed net (right)"
* \image latex ConnexComp.pdf "Connex components exemples for connectors (left) and a routed net (right)" width=0.7\textwidth
*
* It is also important to note that a connex component has a treelike topology, i.e without any cycle.
*
* \section secUse Use
* Global routing a net consists in transforming a list of several connex components into a unique connex component.
*
* \see \ref grpConnexID
*/
/*! \defgroup grpConnexID What is a ConnexID ?
*
* \section secDefinition Definition
*
* A ConnexID is closely linked with the Connex Component concept.
* In fact, for a given net, each connex component has its own ConnexID
*
* \section secImplementation Implementation
*
* A ConnexID is represented as an \p int. All positive values from 0, may represent a connex component, whereas a connexID
* set to \p -1 means that the element (vertex or edge) isn't part of any connex component.
*
* By construction each element has its connexID set to \p -1
*
* \section secUse Use
* When global routing and thus merging connex components it is always the smaller ConnexID that is kept.
* This implies that the last unique connex component will have a ConnexID equal to 0 (when global routing is finished
* for the net)
*
* \see \ref grpConnexComponent
*
*/
/*! \defgroup grpNetStamp What is a netStamp ?
*
* \section secDefinition Definition
*
* blablabla
*
*
*
*/
}