# Katabatic Documentation

# Katabatic - Routing Toolbox

List of all members | Public Types | Public Member Functions | Static Public Member Functions
KatabaticEngine Class Reference

The Katabatic Tool. More...

Inheritance diagram for KatabaticEngine:
[legend]

## Public Types

typedef set< Net *, NetCompareByName > | NetSet

## Public Member Functions

bool | isGMetal (const Layer *) const
bool | isChip () const
bool | isInDemoMode () const
bool | doWarnOnGCellOverload () const
bool | doDestroyBaseContact () const
bool | doDestroyBaseSegment () const
bool | doDestroyTool () const
virtual const Name & | getName () const
EngineState | getState () const
unsigned int | getFlags (unsigned int mask) const
Configuration * | getKatabaticConfiguration ()
virtual Configuration * | getConfiguration ()
RoutingGauge * | getRoutingGauge () const
RoutingLayerGauge * | getLayerGauge (size_t depth) const
const Layer * | getRoutingLayer (size_t depth) const
Layer * | getContactLayer (size_t depth) const
GCellGrid * | getGCellGrid () const
const NetSet & | getRoutingNets () const
DbU::Unit | getGlobalThreshold () const
float | getSaturateRatio () const
size_t | getSaturateRp () const
DbU::Unit | getExtensionCap () const
const ChipTools & | getChipTools () const
void | xmlWriteGCellGrid (ostream &)
void | xmlWriteGCellGrid (const string &)
void | setState (EngineState state)
void | setFlags (unsigned int)
void | unsetFlags (unsigned int)
void | setGlobalThreshold (DbU::Unit)
void | setSaturateRatio (float)
void | setSaturateRp (size_t)
void | printMeasures (const string &) const
void | refresh (unsigned int flags=KbOpenSession)
virtual void | createDetailedGrid ()
void | makePowerRails ()
virtual void | loadGlobalRouting (unsigned int method)
void | slackenBorder (Box bb, Layer::Mask, unsigned int flags)
void | slackenBlockIos (Instance *core)
bool | moveUpNetTrunk (AutoSegment *, set< Net *> &globalNets, GCell::SetIndex &invalidateds)
void | layerAssign (unsigned int method)
void | computeNetConstraints (Net *)
void | toOptimals (Net *)
virtual void | finalizeLayout ()

## Static Public Member Functions

static KatabaticEngine * | create (Cell *)
static const Name & | staticGetName ()

## Detailed Description

The Katabatic Tool.

# States of KatabaticEngine

During it's lifecycle, the engine go through a serie of states. It only can go forward between states.

- EngineCreation : just after C++ object creation until the global routing is loaded.
- EngineGlobalLoaded : after the global routing has been done. This state must be set by an external tool, Katabatic cannot know by itself when the global routing has been done (see Kite).
- EngineActive : after the global routing has been converted into the Katabatic data structure. At this point the tool is ready to run.
- EngineDriving : during the stage of stripping all the decorations the tool has added over the Hurricane data structure (mostly: AutoContact & AutoSegment).
- EngineGutted : after the tool decorations have been removed. The tool is now useless and can only be destroyed.
- EnginePreDestroying : this special state is reached when going straight from EngineActive to the destructor, that is, skipping the EngineDriving state. That means we do not want to save whatever routing has been done. In that case, not only the tool decorations are destroyeds, but also the Hurricane data-structures they relies on (Contact, Segments).

# KatabaticEngine Implementation Details

Due to the size of the code and the fact that the main body of some methods do not need to be present in the class, the implementation of KatabaticEngine is split in several files. The list below summarize them:

- `KatabaticEngine.cpp` : the core of the class, methods that really need their bodies here.
- `PowerRails.cpp` : utilities to construct an abstract from all the power rails through the hierarchy.
- `LayerAssign.cpp` : layer assignement related methods and helpers.
- `LoadGrByNet.cpp` : global routing loader, transform global routing into Katabatic data-structure.
- `NetConstraints.cpp` : compute the topological constraints of all AutoSegment/AutoContact of a Net.
- `NetOptimals.cpp` : compute the optimal positions of all AutoSegment of a Net.

## Member Typedef Documentation

## ◆ NetSet

set< Net *, NetCompareByName > NetSet

Set of Net to be routed, alphabetically sorteds.

## Member Function Documentation

## ◆ create()

KatabaticEngine * create | ( | Cell * | cell | ) |

static

Create a KatabaticEngine on `cell`.

## ◆ staticGetName()

const Name & staticGetName | ( |  | ) |

static

Returns: The unique string identifier for the KatabaticEngine class of ToolEngine.

## ◆ isGMetal()

bool isGMetal | ( | const Layer * | layer | ) | const

inline

Returns: true if `layer` is one of the special (fake) metals used to build the global routing.

Referenced by AutoSegment::create().

## ◆ isChip()

bool isChip | ( |  | ) | const

inline

Returns: true if the hierarchy top-level of the Cell matches the one of a complete design (i.e. pads and one core instance).

References ChipTools::isChip().

## ◆ isInDemoMode()

bool isInDemoMode | ( |  | ) | const

inline

Returns: true if the tool is in demo mode, that is suppress almost all warning and debug messages.

Referenced by Session::isInDemoMode().

## ◆ doWarnOnGCellOverload()

bool doWarnOnGCellOverload | ( |  | ) | const

inline

Returns: true if the tool should issue a warning when a GCell is overloaded (overload could be transient).

Referenced by Session::doWarnGCellOverload().

## ◆ doDestroyBaseContact()

bool doDestroyBaseContact | ( |  | ) | const

inline

Returns: true if the EngineDestroyBaseContact is set, meaning that when an AutoContact is destroyed, the Contact it decorates is destroyed altogether.

## ◆ doDestroyBaseSegment()

bool doDestroyBaseSegment | ( |  | ) | const

inline

Returns: true if the EngineDestroyBaseSegment is set, meaning that when an AutoSegment is destroyed, the Segment it decorates is destroyed altogether.

## ◆ doDestroyTool()

bool doDestroyTool | ( |  | ) | const

inline

Returns: true if the tool state is beyond EngineStateGutted, that is, only waits for `destroy()` to be called.

References Katabatic::EngineGutted.

## ◆ getName()

const Name & getName | ( |  | ) | const

virtual

Returns: The unique string identifier for the KatabaticEngine class of ToolEngine.

Implements ToolEngine.

## ◆ getState()

EngineState getState | ( |  | ) | const

inline

Returns: The state the tool is currently in.

## ◆ getFlags()

unsigned int getFlags | ( | unsigned int | mask | ) | const

inline

Returns: The anded combination of the tool flags and `mask`.

## ◆ getKatabaticConfiguration()

Configuration * getKatabaticConfiguration | ( |  | ) |

inline

Returns: The Configuration of Katabatic. In this class it is redundant with getConfiguration(), but may be useful in derived classes.

## ◆ getConfiguration()

Configuration * getConfiguration | ( |  | ) |

virtual

Returns: The Configuration of the current ToolEngine.

## ◆ getRoutingGauge()

RoutingGauge * getRoutingGauge | ( |  | ) | const

inline

Returns: The RoutingGauge (Configuration shortcut).

## ◆ getLayerGauge()

RoutingLayerGauge * getLayerGauge | ( | size_t | depth | ) | const

inline

Returns: The RoutingLayerGauge associated to `depth` (Configuration shortcut).

## ◆ getRoutingLayer()

const Layer * getRoutingLayer | ( | size_t | depth | ) | const

inline

Returns: The routing Layer associated to `depth` (Configuration shortcut).

## ◆ getContactLayer()

Layer * getContactLayer | ( | size_t | depth | ) | const

inline

Returns: The contact Layer associated to `depth` (Configuration shortcut).

## ◆ getGCellGrid()

GCellGrid * getGCellGrid | ( |  | ) | const

inline

Returns: The GCellGrid.

Referenced by GCellTopology::doRp_AccessPad(), GCellTopology::doRp_AutoContacts(), and anonymous_namespace{LoadGrByNet.cpp}::singleGCell().

## ◆ getRoutingNets()

const NetSet & getRoutingNets | ( |  | ) | const

inline

Returns: The set of nets to be routeds.

## ◆ getGlobalThreshold()

DbU::Unit getGlobalThreshold | ( |  | ) | const

inline

Returns: The length above which a global wire is moved up in the layer assignment stage (Configuration shortcut).

## ◆ getSaturateRatio()

float getSaturateRatio | ( |  | ) | const

inline

Returns: The ratio above which a GCell is considered to be saturated (Configuration shortcut).

Referenced by Session::getSaturateRatio().

## ◆ getSaturateRp()

size_t getSaturateRp | ( |  | ) | const

inline

Returns: The number of RoutingPad above which a GCell is saturated, causing extras global segments to be moved up. (Configuration shortcut).

Referenced by Session::getSaturateRp().

## ◆ getExtensionCap()

DbU::Unit getExtensionCap | ( |  | ) | const

inline

Returns: The wires extension cap, same for all layers for the time beeing (Configuration shortcut).

## ◆ getChipTools()

const ChipTools & getChipTools | ( |  | ) | const

inline

Returns: The chip tools (for whole designs).

Referenced by KatabaticEngine::createDetailedGrid().

## ◆ xmlWriteGCellGrid() [1/2]

void xmlWriteGCellGrid | ( | ostream & | o | ) |

Write in a stream all informations on the GCells in XML format.

Referenced by KatabaticEngine::xmlWriteGCellGrid().

## ◆ xmlWriteGCellGrid() [2/2]

void xmlWriteGCellGrid | ( | const string & | fileName | ) |

Write in a file all informations on the GCells in XML format.

References KatabaticEngine::xmlWriteGCellGrid().

## ◆ setState()

void setState | ( | EngineState | state | ) |

inline

Force the state of the tool. Must be used with caution, as no sanity checks are performeds. This method is normally invoked from inside the KatabaticEngine various methods.

## ◆ setFlags()

void setFlags | ( | unsigned int | flags | ) |

inline

Set the flags given in `flags`.

Referenced by Session::setKatabaticFlags().

## ◆ unsetFlags()

void unsetFlags | ( | unsigned int | flags | ) |

inline

Reset the flags given in `flags`.

## ◆ setGlobalThreshold()

void setGlobalThreshold | ( | DbU::Unit | threshold | ) |

inline

(Configuration shortcut).

## ◆ setSaturateRatio()

void setSaturateRatio | ( | float | ratio | ) |

inline

(Configuration shortcut).

## ◆ setSaturateRp()

void setSaturateRp | ( | size_t | threshold | ) |

inline

(Configuration shortcut).

## ◆ printMeasures()

void printMeasures | ( | const string & | tag | ) | const

Print memory & time measurement on ``cmess1``. If `tag` is not empty, also adds the measurement to the internal table (with `tag` as label).

Referenced by KatabaticEngine::finalizeLayout().

## ◆ refresh()

void refresh | ( | unsigned int | flags = `KbOpenSession` | ) |

In case the tool is associated with a graphic display, trigger a full redraw of the Cell. Slow the router but allow to see work in progress... If `flags` do not contains `KbOpenSession` the refresh operation will not be enclosed inside it's own session. This assumes that a session is already opened.

References GCellGrid::updateContacts().

## ◆ createDetailedGrid()

void createDetailedGrid | ( |  | ) |

virtual

Allocate the GCellGrid.

References GCellGrid::create(), KatabaticEngine::getChipTools(), BaseGrid::getColumns(), Grid< GCellT >::getGCellsColumn(), Grid< GCellT >::getGCellsRow(), BaseGrid::getRows(), ChipTools::isChip(), and Session::revalidate().

## ◆ makePowerRails()

void makePowerRails | ( |  | ) |

Detect all the aligned segments of same width that compose power rails, unificate them and copy them at the design top level.

## ◆ loadGlobalRouting()

void loadGlobalRouting | ( | unsigned int | method | ) |

virtual

Parameters

  method | the loading algorithm
  nets | the set of nets to route.

Convert the global routing into the initial detailed routing. For the time beeing, only one loading algorithm is available: net by net (EngineLoadGrByNet). Only Net given in `nets` are routeds. If `nets` is empty then all ordinary nets are routeds. In either cases the set of nets to route is pruned from any power, ground or clock signals.

Remark: The tool state must be EngineGlobalLoaded before calling this method
  and will be set to EngineActive on exit.

References Katabatic::EngineActive, and Katabatic::EngineGlobalLoaded.

## ◆ slackenBorder()

void slackenBorder | ( | Box | bb,
|  | Layer::Mask | mask,
|  | unsigned int | flags
| ) |  |

Parameters

  bb | The bounding box, defines the edges.
  mask | Consider only layers that are fully included in that mask.
  flags | Consider only segment in that direction.

Perform a preventive break on all global segments going through the vertical left and right edges of the `bb` box. The set of global segments to be broken could be further restricted using `mask` and `flags`.

The Semantic of `flags` is not clear, must review the code more closely.

References Box::getXMax(), Box::getXMin(), Box::getYMax(), and Box::getYMin().

## ◆ slackenBlockIos()

void slackenBlockIos | ( | Instance * | core | ) |

Perform a preventive break on horizontal segments in the GCell immediatly outside the instance `core` area in the routing layer of index `1`.

This method is too much hardwired to the `SxLib` gauge. It's effect is to break all METAL2 outside the core (in a chip).

References Entity::getBoundingBox(), Instance::getName(), Constant::Horizontal, and Box::inflate().

## ◆ moveUpNetTrunk()

bool moveUpNetTrunk | ( | AutoSegment * | seed,
|  | set< Net *> & | globalNets,
|  | GCell::SetIndex & | invalidateds
| ) |  |

Parameters

  seed | The AutoSegment to take the net from.
  globalNets | The set of nets that has been moved up.
  invalidateds | The set of GCells that have been invalidated. Returns: true if the net trunk have been moved up.

Try to move up a whole net trunk. The net is supplied through the `seed` argument (the segment that triggers the move). If the net is actually moved up, it is added to `globalNets` and all GCells that have been invalidateds are added to `invalidateds`.

An individual AutoSegment of the net is moved up if it's length is greater that `150` lambdas, that is, three times the side of a GCell. This is hard-wired and should be parametrized in the future.

## ◆ layerAssign()

void layerAssign | ( | unsigned int | method | ) |

Perform the layer assignment. The global routing loading stage uses only the two bottom most layers, this method spread them on all the availables routing layers, according to GCell and RoutingPad density criterions.

Two algorithms are availables:

- EngineLayerAssignByLength : the global wires are moved up one by one.
- EngineLayerAssignByTrunk : if one global wire of a net is to be moved up, then all the global trunk of the net is moved along. This methods gives the best results for now.

## ◆ computeNetConstraints()

void computeNetConstraints | ( | Net * | net | ) |

Compute the box constraints on AutoContacts (and therefore those applied to AutoSegments). Constraints comes from AutoContacts anchoreds on RoutingPads and transmitted through AutoContactHTee or AutoContactVTee. Constraints are applied to all AutoContacts of an aligned set.

Remark: The `net` must have been canonized before this function to be called.

## ◆ toOptimals()

void toOptimals | ( | Net * | net | ) |

Move all AutoSegment of `net` so that their axis are inside their optimals interval. If a AutoSegment is already inside the interval is not moved, otherwise it is put on the nearest bound of the optimal interval.

## ◆ finalizeLayout()

void finalizeLayout | ( |  | ) |

virtual

Transform the Katabatic wires into the Hurricane data-structure. Mostly by removing the AutoSegment/AutoContact without removing their Hurricane conterparts. May also fill gaps that may have appeared.

Remark: The tool state must be EngineActive before calling this method
  and will be set to EngineGutted on exit.

References Katabatic::EngineDriving, Katabatic::EngineGutted, and KatabaticEngine::printMeasures().

The documentation for this class was generated from the following files:

- KatabaticEngine.h
- ChipTools.cpp
- LoadGrByNet.cpp
- KatabaticEngine.cpp
- KatabaticEngine.dox