556 lines
38 KiB
HTML
556 lines
38 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>1. Introduction — Coriolis 2 documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../_static/SoC.css" type="text/css" />
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="index" title="Index"
|
|
href="../genindex.html"/>
|
|
<link rel="search" title="Search" href="../search.html"/>
|
|
<link rel="top" title="Coriolis 2 documentation" href="../index.html"/>
|
|
<link rel="up" title="Hurricane Python/C++ API Tutorial" href="index.html"/>
|
|
<link rel="next" title="2. Basic File Structure and CMake configuration" href="Configuration.html"/>
|
|
<link rel="prev" title="Hurricane Python/C++ API Tutorial" href="index.html"/>
|
|
|
|
|
|
<script src="_static/js/modernizr.min.js"></script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-nav-search">
|
|
|
|
|
|
|
|
<a href="../index.html" class="icon icon-home"> Coriolis
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="../UsersGuide/index.html">Coriolis User’s Guide</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/LicenseCredits.html">Credits & License</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/Releases.html">Release Notes</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-1-0-1475">Release 1.0.1475</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-1-0-1963">Release 1.0.1963</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-1-0-2049">Release 1.0.2049</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-v2-0-1">Release v2.0.1</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-v2-1">Release v2.1</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Releases.html#release-v2-2"><strong>Release v2.2</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/Installation.html">Installation</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Installation.html#fixed-directory-tree">Fixed Directory Tree</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Installation.html#building-coriolis">Building Coriolis</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/Installation.html#building-the-devel-branch">Building the Devel Branch</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/Installation.html#additionnal-requirement-under-macos">Additionnal Requirement under <span class="sc">MacOS</span></a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Installation.html#packaging-coriolis">Packaging Coriolis</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Installation.html#hooking-up-into-alliance">Hooking up into <span class="sc">Alliance</span></a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Installation.html#setting-up-the-environment-coriolisenv-py">Setting up the Environment (coriolisEnv.py)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/Configuration.html">Coriolis Configuration & Initialisation</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Configuration.html#general-software-architecture">General Software Architecture</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Configuration.html#first-stage-technology-selection">First Stage: Technology Selection</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Configuration.html#second-stage-technology-configuration-loading">Second Stage: Technology Configuration Loading</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Configuration.html#configuration-helpers">Configuration Helpers</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/Configuration.html#alliance-helper"><span class="sc">Alliance</span> Helper</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/Configuration.html#tools-configuration-helpers">Tools Configuration Helpers</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/Configuration.html#hacking-the-configuration-files">Hacking the Configuration Files</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/ViewerTools.html">CGT - The Graphical Interface</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/ViewerTools.html#viewer-tools">Viewer & Tools</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#stratus-netlist-capture"><span class="sc">Stratus</span> Netlist Capture</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-hurricane-data-base">The <span class="sc">Hurricane</span> Data-Base</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#synthetizing-and-loading-a-design">Synthetizing and loading a design</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#etesian-placer">Etesian – Placer</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#knik-global-router">Knik – Global Router</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#kite-detailed-router">Kite – Detailed Router</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#executing-python-scripts-in-cgt">Executing Python Scripts in Cgt</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#printing-snapshots">Printing & Snapshots</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#memento-of-shortcuts-in-graphic-mode">Memento of Shortcuts in Graphic Mode</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#cgt-command-line-options">Cgt Command Line Options</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#miscellaneous-settings">Miscellaneous Settings</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-controller">The Controller</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-look-tab">The Look Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-filter-tab">The Filter Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-layers-go-tab">The Layers&Go Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-netlist-tab">The Netlist Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-selection-tab">The Selection Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-inspector-tab">The Inspector Tab</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ViewerTools.html#the-settings-tab">The Settings Tab</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html">Python Interface for <span class="sc">Hurricane</span> / <span class="sc">Coriolis</span></a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html#plugins">Plugins</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html#chip-placement">Chip Placement</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html#clock-tree">Clock Tree</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html#recursive-save-rsave">Recursive-Save (RSave)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../UsersGuide/ScriptsPlugins.html#a-simple-example-am2901">A Simple Example: AM2901</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../PythonTutorial/index.html">Hurricane Python Tutorial</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/Introduction.html">1. Introduction</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Introduction.html#generalities">1.1 Generalities</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Introduction.html#various-kinds-of-constructors">1.2 Various Kinds of Constructors</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/Environment.html">2. Setting up the Environment</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Environment.html#setting-up-the-pathes">2.1 Setting up the Pathes</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Environment.html#user-s-configurations-file">2.2 User’s Configurations File</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/Environment.html#the-techno-py-file">2.2.1 The <span class="cb">techno.py</span> File</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/Environment.html#the-settings-py-file">2.2.2 The <span class="cb">settings.py</span> File</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html">3. Creating Cell, Net and Component</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#the-allianceframework-crl-core">3.1 The AllianceFramework (CRL Core)</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#session-mechanism-hurricane">3.2 Session Mechanism (Hurricane)</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#creating-a-new-cell-crl-core">3.3 Creating a new Cell (CRL Core)</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#the-dbu-measurement-unit">3.4 The DbU Measurement Unit</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#setting-up-the-abutment-box">3.5 Setting up the Abutment Box</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#adding-nets-and-components">3.6 Adding Nets and Components</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#getting-a-layer">3.6.1 Getting a Layer</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#creating-a-net">3.6.2 Creating a Net</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#creating-a-component">3.6.3 Creating a Component</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CellNetComponent.html#saving-to-disk-crl-core">3.7 Saving to Disk (CRL Core)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/Collections.html">4. Manipulating Cells, Nets and Components</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Collections.html#hurricane-collections">4.1 Hurricane Collections</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="../PythonTutorial/Collections.html#restrictions-about-using-collections">4.1.1 Restrictions about using Collections</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/Collections.html#loading-a-cell-with-allianceframework">4.2 Loading a Cell with AllianceFramework</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/CgtScript.html">5. Make a script runnable through <span class="cb">cgt</span></a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../PythonTutorial/CgtScript.html#using-breakpoints">5.1 Using Breakpoints</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../PythonTutorial/CgtScript.html#the-complete-example-file">6. The Complete Example File</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Stratus/Stratus.html">Stratus Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../DpGen/DpGen.html">DpGen Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Patterns/Patterns.html">Patterns Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Hurricane/Hurricane.html">Hurricane Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Viewer/Viewer.html">Viewer Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../CrlCore/CrlCore.html">CRL Core Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Katabatic/Katabatic.html">Katabatic Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Kite/Kite.html">Kite Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../Unicorn/Unicorn.html">Unicorn Reference</a></li>
|
|
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Hurricane Python/C++ API Tutorial</a><ul class="current">
|
|
<li class="toctree-l2 current"><a class="current reference internal" href="#">1. Introduction</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#first-a-disclaimer">1.1 First, A Disclaimer</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#about-technical-choices">1.2 About Technical Choices</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#botched-design">1.3 Botched Design</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="Configuration.html">2. Basic File Structure and CMake configuration</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="DBoStandalone.html">3. Case 1 - DBo Derived, Standalone</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoStandalone.html#class-associated-header-file">3.1 Class Associated Header File</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoStandalone.html#class-associated-file">3.2 Class Associated File</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="DBoStandalone.html#head-of-the-file">3.2.1 Head of the file</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="DBoStandalone.html#the-python-module-part">3.2.2 The Python Module Part</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="DBoStandalone.html#python-type-linking">3.2.3 Python Type Linking</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="DBoStandalone.html#the-shared-library-part">3.2.4 The Shared Library Part</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoStandalone.html#python-module-c-namespace">3.3 Python Module (C++ namespace)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="DBoHierarchy.html">4. Case 2 - Hierarchy of DBo Derived Classes</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#base-class-header">4.1 Base Class Header</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#base-class-file">4.2 Base Class File</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#intermediate-class-header">4.3 Intermediate Class Header</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#intermediate-class-file">4.4 Intermediate Class File</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#terminal-class-header">4.5 Terminal Class Header</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#terminal-class-file">4.6 Terminal Class File</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="DBoHierarchy.html#python-module">4.8 Python Module</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="NonDBo.html">5. Case 3 - Non-DBo Standalone Classe</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="NonDBo.html#class-header">5.1 Class Header</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="NonDBo.html#class-file">5.2 Class File</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="NonDBo.html#id1">5.2 Class File</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="DbU.html">6. Encapsulating DbU</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="Name.html">7. No C++ Hurricane::Name encapsulation</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../RDS/index.html">Symbolic to Real Conversion in Alliance</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="../RDS/RDSpage.html">Symbolic Layout</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#symbolic-components">Symbolic Components</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#symbolic-segments">Symbolic Segments</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="../RDS/RDSpage.html#the-rds-file">The RDS File</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#physical-grid-lambda-value">Physical Grid & Lambda Value</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#the-mbk-to-rds-segment-table">The <code class="docutils literal"><span class="pre">MBK_TO_RDS_SEGMENT</span></code> table</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#the-mbk-to-rds-via-table">The <code class="docutils literal"><span class="pre">MBK_TO_RDS_VIA</span></code> table</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#the-mbk-to-rds-bigvia-hole-table">The <code class="docutils literal"><span class="pre">MBK_TO_RDS_BIGVIA_HOLE</span></code> table</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#the-mbk-to-rds-bigvia-metal-table">The <code class="docutils literal"><span class="pre">MBK_TO_RDS_BIGVIA_METAL</span></code> table</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../RDS/RDSpage.html#the-mbk-wiresetting-table">The <code class="docutils literal"><span class="pre">MBK_WIRESETTING</span></code> table</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../lefapi/lefapi.html">LEF API Reference</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="../lefapi/lefapi.html#implementation-notes">Implementation Notes</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="../lefapi/lefapi.html#understanding-units">Understanding Units</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="../lefapi/lefapi.html#callback-calling-order">Callback Calling Order</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../defapi/defapi.html">DEF API Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../lefdef/lefdef.html">LEF/DEF Language Reference</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="../index.html">Coriolis</a>
|
|
</nav>
|
|
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="../index.html">Docs</a> »</li>
|
|
|
|
<li><a href="index.html">Hurricane Python/C++ API Tutorial</a> »</li>
|
|
|
|
<li>1. Introduction</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document">
|
|
|
|
<div class="section" id="introduction">
|
|
<h1>1. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
|
|
<ul class="simple">
|
|
<li>This document is written for people already familiar with the
|
|
<a class="reference external" href="https://docs.python.org/2/c-api/index.html">Python/C API Reference Manual</a>.</li>
|
|
<li>The macros provided by the Hurricane Python/C API are written using
|
|
the standard Python C/API. That is, you may not use them and write
|
|
directly your functions with the original API or any mix between.
|
|
You only have to respect some naming convention.</li>
|
|
<li>Coriolis is build against Python 2.7.</li>
|
|
</ul>
|
|
<div class="section" id="first-a-disclaimer">
|
|
<h2>1.1 First, A Disclaimer<a class="headerlink" href="#first-a-disclaimer" title="Permalink to this headline">¶</a></h2>
|
|
<p>The Hurricane Python/C++ API has been written about ten years ago, at a time
|
|
my mastering of template programming was less than complete. This is why this
|
|
interface is build with old fashioned C macro instead of C++ template.</p>
|
|
<p>It is my hope that at some point in the future I will have time to completly
|
|
rewrite it, borrowing the interface from <code class="docutils literal"><span class="pre">boost::python</span></code>.</p>
|
|
</div>
|
|
<div class="section" id="about-technical-choices">
|
|
<h2>1.2 About Technical Choices<a class="headerlink" href="#about-technical-choices" title="Permalink to this headline">¶</a></h2>
|
|
<p>Some would say, why not use <em>off the shelf</em> wrappers like <code class="docutils literal"><span class="pre">swig</span></code>
|
|
or <code class="docutils literal"><span class="pre">boost::python</span></code>, here are some clues.</p>
|
|
<ol class="arabic">
|
|
<li><p class="first"><strong>Partial exposure of the C++ class tree.</strong> We expose at Python level
|
|
C++ base classes, only if they provides common methods that we want
|
|
to see. Otherwise, we just show them as base classes under Python.
|
|
For instance <code class="docutils literal"><span class="pre">Library</span></code> is derived from <code class="docutils literal"><span class="pre">DBo</span></code>, but we won’t see
|
|
it under Python.</p>
|
|
</li>
|
|
<li><p class="first"><strong>Bi-directional communication.</strong> When a Python object is deleted, the
|
|
wrapper obviously has a pointer toward the underlying C++ object and
|
|
is able to delete it. But, the reverse case can occurs, meaning that
|
|
you have a C++ object wrapped in Python and the database delete the
|
|
underlying object. The wrapped Python object <em>must</em> be informed that
|
|
it no longer refer a valid C++ one. Moreover, as we do not control
|
|
when Python objects gets deleteds (that is, when their reference count
|
|
reaches zero), we can have valid Python object with a dangling
|
|
C++ pointer. So our Python objects can be warned by the C++ objects
|
|
that they are no longer valid and any other operation than the
|
|
deletion should result in a severe non-blocking error.</p>
|
|
<p>To be precise, this apply to persistent object in the C++ database,
|
|
like <code class="docutils literal"><span class="pre">Cell</span></code>, <code class="docutils literal"><span class="pre">Net</span></code>, <code class="docutils literal"><span class="pre">Instance</span></code> or <code class="docutils literal"><span class="pre">Component</span></code>. Short lived
|
|
objects like <code class="docutils literal"><span class="pre">Box</span></code> or <code class="docutils literal"><span class="pre">Point</span></code> retains the classic Python behavior.</p>
|
|
<p>Another aspect is that, for all derived <code class="docutils literal"><span class="pre">DBo</span></code> objects, one and only
|
|
one Python object is associated. For one given <code class="docutils literal"><span class="pre">Instance</span></code> object we
|
|
will always return the <em>same</em> <code class="docutils literal"><span class="pre">PyInstance</span></code> object, thanks to the
|
|
bi-directional link. Obviously, the <em>reference count</em> of the
|
|
<code class="docutils literal"><span class="pre">PyInstance</span></code> is managed accordingly. This mechanism is implemented
|
|
by the <code class="docutils literal"><span class="pre">PyInstance_Link()</span></code> function.</p>
|
|
</li>
|
|
<li><p class="first"><strong>Linking accross modules.</strong> As far as I understand, the wrappers
|
|
are for monolithic libraries. That is, you wrap the entire library
|
|
in one go. But Hurricane has a modular design, the core database
|
|
then various tools. We do not, and cannot, have one gigantic wrapper
|
|
that would encompass all the libraries in one go. We do one Python
|
|
module for one C++ library.</p>
|
|
<p>This brings another issue, at Python level this time. The Python
|
|
modules for the libraries have to share some functions. Python
|
|
provides a mechanism to pass C function pointers accross modules,
|
|
but I did found it cumbersome. Instead, all our modules are split
|
|
in two:</p>
|
|
<ul class="simple">
|
|
<li>The first part contains the classic Python module code.</li>
|
|
<li>The second part is to be put in a separate dynamic library that
|
|
will hold the shared functions. The Python module is dynamically linked
|
|
against that library like any other. And any other Python module
|
|
requiring the functions will link against the associated shared
|
|
library.</li>
|
|
</ul>
|
|
<p>Each module file will be compiled <em>twice</em>, once to build the Python
|
|
module (<code class="docutils literal"><span class="pre">__PYTHON_MODULE</span></code> is defined) and once to build the supporting
|
|
shared library (<code class="docutils literal"><span class="pre">__PYTHON_MODULE__</span></code> <strong>not</strong> defined). This tricky
|
|
double compilation is taken care of though the <code class="docutils literal"><span class="pre">add_python_module</span></code>
|
|
<code class="docutils literal"><span class="pre">cmake</span></code> macro.</p>
|
|
<p>For the core Hurricane library we will have:</p>
|
|
<ul class="simple">
|
|
<li><code class="docutils literal"><span class="pre">Hurricane.so</span></code> the Python module (use with: <code class="docutils literal"><span class="pre">import</span> <span class="pre">Hurricane</span></code>).</li>
|
|
<li><code class="docutils literal"><span class="pre">libisobar.so.1.0</span></code> the supporting shared library.</li>
|
|
</ul>
|
|
<p>The <code class="docutils literal"><span class="pre">PyLibrary.cpp</span></code> file will have the following structure:</p>
|
|
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"hurricane/isobar/PyLibrary.h"</span><span class="cp"></span>
|
|
|
|
<span class="k">namespace</span> <span class="n">Isobar</span> <span class="p">{</span>
|
|
|
|
<span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
|
|
|
|
<span class="cp">#if defined(__PYTHON_MODULE__)</span>
|
|
|
|
<span class="c1">// +=================================================================+</span>
|
|
<span class="c1">// | "PyLibrary" Python Module Code Part |</span>
|
|
<span class="c1">// +=================================================================+</span>
|
|
<span class="c1">//</span>
|
|
<span class="c1">// The classic part of a Python module. Goes into Hurricane.so.</span>
|
|
|
|
|
|
<span class="cp">#else </span><span class="c1">// End of Python Module Code Part.</span>
|
|
|
|
<span class="c1">// x=================================================================x</span>
|
|
<span class="c1">// | "PyLibrary" Shared Library Code Part |</span>
|
|
<span class="c1">// x=================================================================x</span>
|
|
<span class="c1">//</span>
|
|
<span class="c1">// Functions here will be part of the associated shared library and</span>
|
|
<span class="c1">// made available to all other Python modules. Goes into libisobar.so.1.0</span>
|
|
|
|
|
|
<span class="cp"># endif </span><span class="c1">// Shared Library Code Part.</span>
|
|
|
|
<span class="p">}</span> <span class="c1">// extern "C".</span>
|
|
|
|
<span class="p">}</span> <span class="c1">// Isobar namespace.</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This way, we do not rely upon a pointer transmission through Python
|
|
modules, but directly uses linker capabilities.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="botched-design">
|
|
<h2>1.3 Botched Design<a class="headerlink" href="#botched-design" title="Permalink to this headline">¶</a></h2>
|
|
<p>The mechanism to compute the signature of a call to a Python function,
|
|
the <code class="docutils literal"><span class="pre">__cs</span></code> object, is much too complex and, in fact, not needed.
|
|
At some point I may root it out, but it is used in so many places...</p>
|
|
<p>What I should have used the <code class="docutils literal"><span class="pre">"O!"</span></code> capablity of <code class="docutils literal"><span class="pre">PyArg_ParseTuple()</span></code>,
|
|
like in the code below:</p>
|
|
<p></p>
|
|
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="n">PyObject</span><span class="o">*</span> <span class="nf">PyContact_create</span> <span class="p">(</span> <span class="n">PyObject</span><span class="o">*</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">Contact</span><span class="o">*</span> <span class="n">contact</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="n">HTRY</span>
|
|
<span class="n">PyNet</span><span class="o">*</span> <span class="n">pyNet</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="n">PyLayer</span><span class="o">*</span> <span class="n">pyLayer</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="n">PyComponent</span><span class="o">*</span> <span class="n">pyComponent</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="n">DbU</span><span class="o">::</span><span class="n">Unit</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
|
|
<span class="n">DbU</span><span class="o">::</span><span class="n">Unit</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
|
|
<span class="n">DbU</span><span class="o">::</span><span class="n">Unit</span> <span class="n">width</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
|
|
<span class="n">DbU</span><span class="o">::</span><span class="n">Unit</span> <span class="n">height</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
|
|
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">PyArg_ParseTuple</span><span class="p">(</span> <span class="n">args</span><span class="p">,</span> <span class="s">"O!O!ll|ll:Contact.create"</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">PyTypeNet</span> <span class="p">,</span> <span class="o">&</span><span class="n">pyNet</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">PyTypeLayer</span><span class="p">,</span> <span class="o">&</span><span class="n">pyLayer</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">x</span><span class="p">,</span> <span class="o">&</span><span class="n">y</span><span class="p">,</span> <span class="o">&</span><span class="n">width</span><span class="p">,</span> <span class="o">&</span><span class="n">height</span><span class="p">))</span> <span class="p">{</span>
|
|
<span class="n">contact</span> <span class="o">=</span> <span class="n">Contact</span><span class="o">::</span><span class="n">create</span><span class="p">(</span> <span class="n">PYNET_O</span><span class="p">(</span><span class="n">pyNet</span><span class="p">),</span> <span class="n">PYLAYER_O</span><span class="p">(</span><span class="n">pyLayer</span><span class="p">)</span>
|
|
<span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span> <span class="p">);</span>
|
|
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
|
|
<span class="n">PyErr_Clear</span><span class="p">();</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">PyArg_ParseTuple</span><span class="p">(</span> <span class="n">args</span><span class="p">,</span> <span class="s">"O!O!ll|ll:Contact.create"</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">PyTypeComponent</span><span class="p">,</span> <span class="o">&</span><span class="n">pyComponent</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">PyTypeLayer</span> <span class="p">,</span> <span class="o">&</span><span class="n">pyLayer</span>
|
|
<span class="p">,</span> <span class="o">&</span><span class="n">x</span><span class="p">,</span> <span class="o">&</span><span class="n">y</span><span class="p">,</span> <span class="o">&</span><span class="n">width</span><span class="p">,</span> <span class="o">&</span><span class="n">height</span><span class="p">))</span> <span class="p">{</span>
|
|
<span class="n">contact</span> <span class="o">=</span> <span class="n">Contact</span><span class="o">::</span><span class="n">create</span><span class="p">(</span> <span class="n">PYCOMPONENT_O</span><span class="p">(</span><span class="n">pyComponent</span><span class="p">),</span> <span class="n">PYLAYER_O</span><span class="p">(</span><span class="n">pyLayer</span><span class="p">)</span>
|
|
<span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span> <span class="p">);</span>
|
|
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
|
|
<span class="n">PyErr_SetString</span><span class="p">(</span> <span class="n">ConstructorError</span>
|
|
<span class="p">,</span> <span class="s">"invalid number of parameters for Contact constructor."</span> <span class="p">);</span>
|
|
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
<span class="n">HCATCH</span>
|
|
<span class="k">return</span> <span class="n">PyContact_Link</span><span class="p">(</span> <span class="n">contact</span> <span class="p">);</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="Configuration.html" class="btn btn-neutral float-right" title="2. Basic File Structure and CMake configuration" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="index.html" class="btn btn-neutral" title="Hurricane Python/C++ API Tutorial" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<table class="footer1">
|
|
<tr>
|
|
<td class="LFooter"><small>
|
|
Generated by <a href="http://sphinx-doc.org/">Sphinx</a>
|
|
using a <a href="https://readthedocs.org">RTD</a> theme on Mar 16, 2018.
|
|
</small></td>
|
|
<td class="RFooter"></td>
|
|
</tr>
|
|
</table>
|
|
<table class="footer2">
|
|
<tr>
|
|
<td class="LFooter">Coriolis 2 Documentation</td>
|
|
<td class="RFooter"><small>
|
|
© Copyright 2000-2018, UPMC.
|
|
</small></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT:'../',
|
|
VERSION:'2',
|
|
COLLAPSE_INDEX:false,
|
|
FILE_SUFFIX:'.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="../_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.StickyNav.enable();
|
|
});
|
|
</script>
|
|
|
|
|
|
</body>
|
|
</html> |