.. -*- Mode: rst -*-

.. include:: ../etc/definitions.rst

.. URLs that changes between the various backends.
.. _Coriolis Tools Documentation:   file:///usr/share/doc/coriolis2/index.html

				      

.. |CoriolisSoftSchema|             image:: ./images/Coriolis-Soft-Schema.png
                                    :alt:   Coriolis Software Schematic
                                    :align: middle
                                    :width: 60%

|newpage|


Coriolis Configuration & Initialisation
=======================================


General Software Architecture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|Coriolis| has been build with respect of the classical paradigm that the
computational instensive parts have been written in C++, and almost
everything else in |Python|. To build the |Python| interface we used
two methods:

* For self-contained modules :cb:`boost::python` (mainly in :cb:`vlsisapd`).
* For all modules based on |Hurricane|, we created our own wrappers due
  to very specific requirements such as shared functions between modules
  or C++/|Python| secure bi-directional object deletion.

.. note:: **Python Documentation:**
   Most of the documentation is related to the C++ API and implemetation of
   the tools. However, the |Python| bindings have been created so they
   mimic *as closely as possible* the C++ interface, so the documentation
   applies to both languages with only minor syntactic changes.

|bcenter| |CoriolisSoftSchema| |ecenter|

All configuration & initialization files are Python scripts, despite their
|dot_conf| extention. From a syntactic point of view, there is no difference
between the system-wide configuration files and the user's configuration, 
they may use the same Python helpers.
|medskip|

Configuration is done in two stages:

#. Selecting the symbolic technology.
#. Loading the complete configuration for the given technology.

|newpage|


First Stage: Technology Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|noindent|
The initialization process is done by executing, in order, the following
file(s):

+-------+----------------------------------+----------------------------------------------+
| Order | Meaning                          | File                                         |
+=======+==================================+==============================================+
| **1** | The system setting               | :cb:`/etc/coriolis2/techno.conf`             |
+-------+----------------------------------+----------------------------------------------+
| **2** | The user's global setting        | :cb:`${HOME}/.coriolis2/techno.py`           |
+-------+----------------------------------+----------------------------------------------+
| **3** | The user's local setting         | :cb:`<CWD>/.coriolis2/techno.py`             |
+-------+----------------------------------+----------------------------------------------+

Thoses files must provides only one variable, the name of the technology. Each technology
will provide configuration for both the symbolic part and the real part. |Coriolis| can
work with purely symbolic technology (``symbolic/cmos``) in that case, the real technology
part is a dummy one.

For example, to use |MOSIS| 180nm: ::

    # -*- Mode:Python -*-
    
    technology = '180/scn6m_deep_09'


Second Stage: Technology Configuration Loading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|noindent|
The :cb:`TECHNO` variable is set by the first stage and it's the name of the
symbolic technology. A directory of that name, with all the configuration files,
must exists in the configuration directory. In addition to the technology-specific
directories, a :cb:`common/` directory is there to provides a trunk for all the
identical datas across the various technologies. The initialization process is done
by executing, in order, the following file(s):

+-------+----------------------------------+----------------------------------------------+
| Order | Meaning                          | File                                         |
+=======+==================================+==============================================+
| **1** | The system initialization        | :cb:`/etc/coriolis2/<TECHNO>/<TOOL>.conf`    |
+-------+----------------------------------+----------------------------------------------+
| **2** | The user's global initialization | :cb:`${HOME}/.coriolis2/settings.py`         |
+-------+----------------------------------+----------------------------------------------+
| **3** | The user's local initialization  | :cb:`<CWD>/.coriolis2/settings.py`           |
+-------+----------------------------------+----------------------------------------------+

.. note:: *The loading policy is not hard-coded.* It is implemented
   at Python level in :cb:`/etc/coriolis2/coriolisInit.py`, and thus may be easily be
   amended to whatever site policy.

   The truly mandatory requirement is the existence of :cb:`coriolisInit.py`
   which *must* contain a :cb:`coriolisConfigure()` function with no argument.


Configuration Helpers
~~~~~~~~~~~~~~~~~~~~~

To ease the writing of configuration files, a set of small helpers
is available. They allow to setup the configuration parameters through
simple assembly of tuples. The helpers are installed under the directory: ::

    <install>/etc/coriolis2/

Where :cb:`<install>/` is the root of the installation.

|newpage|


.. _Alliance Helper:

|Alliance| Helper
-----------------

The configuration file must provide a :cb:`allianceConfig` tuple of
the form: ::

    cellsTop = '/usr/share/alliance/cells/'

    allianceConfig = \
        ( ( 'SYMBOLIC_TECHNOLOGY', helpers.sysConfDir+'/technology.symbolic.xml'   )
        , ( 'REAL_TECHNOLOGY'    , helpers.sysConfDir+'/technology.cmos130.s2r.xml')
        , ( 'DISPLAY'            , helpers.sysConfDir+'/display.xml'               )
        , ( 'CATALOG'            , 'CATAL')
        , ( 'WORKING_LIBRARY'    , '.')
        , ( 'SYSTEM_LIBRARY'     , ( (cellsTop+'sxlib'   , Environment.Append)
                                   , (cellsTop+'dp_sxlib', Environment.Append)
                                   , (cellsTop+'ramlib'  , Environment.Append)
                                   , (cellsTop+'romlib'  , Environment.Append)
                                   , (cellsTop+'rflib'   , Environment.Append)
                                   , (cellsTop+'rf2lib'  , Environment.Append)
                                   , (cellsTop+'pxlib'   , Environment.Append) ) )
        , ( 'SCALE_X'            , 100)
        , ( 'IN_LO'              , 'vst')
        , ( 'IN_PH'              , 'ap')
        , ( 'OUT_LO'             , 'vst')
        , ( 'OUT_PH'             , 'ap')
        , ( 'POWER'              , 'vdd')
        , ( 'GROUND'             , 'vss')
        , ( 'CLOCK'              , '^ck.*')
        , ( 'BLOCKAGE'           , '^blockageNet*')
        )


|noindent| The example above shows the system configuration file, with all the
available settings. Some important remarks about thoses settings:

* In it's configuration file, the user do not need to redefine all the settings,
  just the one he wants to change. In most of the cases, the ``SYSTEM_LIBRARY``,
  the ``WORKING_LIBRARY`` and the special net names (at this point there is not
  much alternatives for the others settings).

* ``SYSTEM_LIBRARY`` setting: Setting up the library search path.
  Each library entry in the tuple will be added to the search path according
  to the second parameter:

  * :cb:`Environment::Append`:  append to the search path.

  * :cb:`Environment::Prepend`: insert in head of the search path.

  * :cb:`Environment::Replace`: look for a library of the same name and replace
    it, whithout changing the search path order. If no library of that name
    already exists, it is appended.

  A library is identified by it's name, this name is the last component of the
  path name. For instance: ``/soc/alliance/sxlib`` will be named ``sxlib``.
  Implementing the |Alliance| specification, when looking for a |Cell| ``name``,
  the system will browse sequentially trought the library list and returns
  the first |Cell| whose name match.

* For ``POWER``, ``GROUND``, ``CLOCK`` and ``BLOCKAGE`` net names, a regular
  expression (|GNU| regexp) is expected.

* The ``helpers.sysConfDir`` variable is supplied by the helpers, it is the
  directory in which the system-wide configuration files are locateds.
  For a standard installation it would be: ``/soc/coriolis2``.

.. * Trick and naming convention about ``SYMBOLIC_TECHNOLOGY``, ``REAL_TECHNOLOGY``
..   and ``DISPLAY``. In the previous releases, thoses files where to read by
..   XML parsers, and still do if you triggers the XML compatibility mode.
..   But now, they have Python conterparts. In the configuration files, you
..   still have to name them as XML files, the Python file name will be
..   deduced from this one with thoses two translation rules: 
.. 
..   #. In the filename, all dots, except for the last (the file extention), 
..      are replaced by underscores.
.. 
..   #. The ``.xml`` extention is substituted by a ``.conf``.
..   
..   For the symbolic technology, it would give: ::
.. 
..       /soc/coriolis2/technology.symbolic.xml
..                              --> /soc/coriolis2/technology_symbolic.conf

A typical user's configuration file would be: ::

    import os

    homeDir = os.getenv('HOME')

    allianceConfig = \
        ( ('WORKING_LIBRARY'    , homeDir+'/worklib')
        , ('SYSTEM_LIBRARY'     , ( (homeDir+'/mylib', Environment.Append) ) )
        , ('POWER'              , 'vdd.*')
        , ('GROUND'             , 'vss.*')
        )


Tools Configuration Helpers
---------------------------

All the tools uses the same helper to load their configuration (a.k.a. 
*Configuration Helper*). Currently the following configuration system-wide
configuration files are defined:

* :cb:`misc.conf`: commons settings or not belonging specifically to a tool.
* :cb:`etesian.conf`: for the |Etesian| tool.
* :cb:`kite.conf`: for the |Kite| tool.
* :cb:`stratus1.conf`: for the |stratus1| tool.

Here is the contents of :cb:`etesian.conf`: ::

    # Etesian parameters.
    parametersTable = \
        ( ('etesian.aspectRatio'    , TypePercentage, 100    , { 'min':10, 'max':1000 } )
        , ('etesian.spaceMargin'    , TypePercentage, 5      )
        , ('etesian.uniformDensity' , TypeBool      , False  )
        , ('etesian.routingDriven'  , TypeBool      , False  )
        , ("etesian.effort"         , TypeEnumerate , 2
          , { 'values':( ("Fast"    , 1)
                       , ("Standard", 2)
                       , ("High"    , 3)
                       , ("Extreme" , 4) ) }
          )
        , ("etesian.graphics"       , TypeEnumerate , 2
          , { 'values':( ("Show every step"  , 1)
                       , ("Show lower bound" , 2)
                       , ("Show result only" , 3) ) }
          )
        )
    
    layoutTable = \
        ( (TypeTab   , 'Etesian', 'etesian')
    
        , (TypeTitle , 'Placement area')
        , (TypeOption, "etesian.aspectRatio"   , "Aspect Ratio, X/Y (%)", 0 )
        , (TypeOption, "etesian.spaceMargin"   , "Space Margin"         , 1 )
        , (TypeRule  ,)
        , (TypeTitle , 'Etesian - Placer')
        , (TypeOption, "etesian.uniformDensity", "Uniform density"      , 0 )
        , (TypeOption, "etesian.routingDriven" , "Routing driven"       , 0 )
        , (TypeOption, "etesian.effort"        , "Placement effort"     , 1 )
        , (TypeOption, "etesian.graphics"      , "Placement view"       , 1 )
        , (TypeRule  ,)
        )

|newpage|


Taxonomy of the file:

* It must contains, at least, the two tables:

  * ``parametersTable``, defines & initialise the configuration variables.

  * ``layoutTables``, defines how the various parameters will be displayed
    in the configuration window (:ref:`The Settings Tab`).

* The ``parametersTable``, is a tuple (list) of tuples. Each entry in the list
  describe a configuration parameter. In it's simplest form, it's a quadruplet
  :cb:`(TypeOption, 'paramId', ParameterType, DefaultValue)` with:

  #. ``TypeOption``, tells that this tuple describe a parameter.

  #. ``paramId``, the identifier of the parameter. Identifiers are defined
     by the tools. The list of parameters is detailed in each tool section.

  #. ``ParameterType``, the kind of parameter. Could be:

     * ``TypeBool``, boolean.
     * ``TypeInt``, signed integer.
     * ``TypeEnumerate``, enumerated type, needs extra entry.
     * ``TypePercentage``, percentage, expressed between 0 and 100.
     * ``TypeDouble``, float.
     * ``TypeString``, character string.
  
  #. ``DefaultValue``, the default value for that parameter.


Hacking the Configuration Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Asides from the symbols that gets used by the configuration helpers like
:cb:`allianceConfig` or :cb:`parametersTable`, you can put pretty much anything
in :cb:`<CWD>/.coriolis2/settings.py` (that is, written in |Python|).

For example: ::

    # -*- Mode:Python -*-
    
    defaultStyle = 'Alliance.Classic [black]'
    
    # Regular Coriolis configuration.
    parametersTable = \
        ( ('misc.catchCore'           , TypeBool      , False  )
        , ('misc.info'                , TypeBool      , False  )
        , ('misc.paranoid'            , TypeBool      , False  )
        , ('misc.bug'                 , TypeBool      , False  )
        , ('misc.logMode'             , TypeBool      , True   )
        , ('misc.verboseLevel1'       , TypeBool      , False  )
        , ('misc.verboseLevel2'       , TypeBool      , True   )
        , ('misc.minTraceLevel'       , TypeInt       , 0      )
        , ('misc.maxTraceLevel'       , TypeInt       , 0      )
        )
    
    # Some ordinary Python script...
    import os
    
    print '       o  Cleaning up ClockTree previous run.'
    for fileName in os.listdir('.'):
      if fileName.endswith('.ap') or (fileName.find('_clocked.') >= 0):
        print '          - <%s>' % fileName
        os.unlink(fileName)


See :ref:`Python Interface to Coriolis` for more details those capabilities.
