Adding DTR documentation

vlsisapd/doc/agds/agds.dox

@@ -41,6 +41,13 @@
   Here is the C++ code (\c driveAgds.cpp) used to generate the transistor.agds file. (Source is available in examples directory).
   \include driveAgds.cpp
 
+  \note In order to compile this code, a CMakeLists.txt file is provided. User must set the $VLSISAPD_TOP variable before running these commands in the directory containing the CMakeLists.txt file:
+  \code
+  %> mkdir build; cd build
+  %> cmake ..
+  %> make
+  \endcode
+
   \subsection agdsPython Python
   Here is the Python code (\c driveAgds.py) used to generate the transistor.agds file. (Source is available in examples directory).
   \include driveAgds.py

vlsisapd/doc/cif/cif.dox

@@ -29,6 +29,13 @@
   Here is the C++ code (\c driveCif.cpp) used to generate the transistor.cif file. (Source is available in examples directory).
   \include driveCif.cpp
 
+  \note In order to compile this code, a CMakeLists.txt file is provided. User must set the $VLSISAPD_TOP variable before running these commands in the directory containing the CMakeLists.txt file:
+  \code
+  %> mkdir build; cd build
+  %> cmake ..
+  %> make
+  \endcode
+
   \subsection cifPython Python
   Here is the Python code (\c driveCif.py) used to generate the transistor.cif file. (Source is available in examples directory).
   \include driveCif.py

vlsisapd/doc/doxyfile

@@ -179,11 +179,7 @@ TAB_SIZE               = 4
 # will result in a user-defined paragraph with heading "Side Effects:".
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = "arguments=\b Arguments:\n"\
+ALIASES                =
-                         "returns=\b Returns:\n" \
-                         "note=\b Note:\n" \
-                         "checks=\b Checks:\n" \
-                         "example=\b Example:\n"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.
@@ -572,7 +568,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = "." "../src/cif" "../src/agds"
+INPUT                  = "." "../src/cif" "../src/agds" "../src/dtr"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

vlsisapd/doc/dtr/Name.dox

@@ -0,0 +1,57 @@
+// -*- C++ -*-
+
+namespace DTR {
+/*! \class Name
+ *
+ *  This class provides an automatic management of shared name.
+ */
+
+/*! \fn Name::Name(std::string str)
+ *   \brief gets a shared Name, creates it if it does not exist.
+ *
+ *   \param str the string associated to the name.
+ */
+
+/*! \fn Name::Name(const char* cstr)
+ *   \brief gets a shared Name, creates it if it does not exist.
+ *
+ *   \param cstr the character string associated to the name.
+ *
+ *   \note this method is not yet available in python
+ */
+
+/*! \fn bool Name::operator==(const Name&)
+ *   \brief redifines the '==' operator.
+ *
+ *   \note this method is not yet available in python
+ */
+ 
+/*! \fn bool Name::operator==(const std::string&)
+ *   \brief redifines the '==' operator.
+ *
+ *   \note this method is not yet available in python
+ */
+ 
+/*! \fn bool Name::operator!=(const Name&)
+ *   \brief redifines the '!=' operator.
+ *
+ *   \note this method is not yet available in python
+ */
+ 
+/*! \fn bool Name::operator!=(const std::string&)
+ *   \brief redifines the '!=' operator.
+ *
+ *   \note this method is not yet available in python
+ */
+
+/*! \fn bool Name::operator<(const Name) const
+ *   \brief redifines the '<' operator.
+ *
+ *   \note this method is not yet available in python
+ */
+
+/*! \fn inline const std::string& Name::getString() const
+ *   \brief returns the string associated to the Name.
+ */
+ 
+}

vlsisapd/doc/dtr/Rule.dox

@@ -0,0 +1,85 @@
+// -*- C++ -*-
+
+namespace DTR {
+/*! \class Rule
+ *
+ *  This class describes a symmetrical rule.
+ *
+ *  A symmetrical rule represents several type of rules:
+ *   - a simple rule with only a name (e.g. transistorMinW: transistor minimum width)
+ *   - a rule for a unique layer (e.g. minWidth.metal1: the minimum width for metal1 wire)
+ *   - a rule associating two layers (e.g minSpace.poly.active: the minimum spacing between a poly shape and an active shape)
+ *  In this last case the symmetrical characteristic is important since it implies that the value is the same if we invert the two layers : minSpacing poly vs active = minSpacing active vs poly.
+ *
+ *  Typical rules using no layer are:
+ *  <i>transistorMinW, transsitorMaxW, transistorMinL transistorMaxL</i>
+ *
+ *  Typical rules using one layer are:
+ *  <i>minWidth, minSpacing, minArea, minGateSpacing, minStrapEnclosure</i>
+ *
+ *  Typical rules using two layers are:
+ *  <i>minSpacing</i>
+ *
+ */
+
+/*! \fn Rule::Rule(Name name, double value, Name ref, Name layer1, Name layer2)
+ *   \brief creates a new rule.
+ *
+ *   \param name   the name of the rule.
+ *   \param value  the value of the rule.
+ *   \param ref    the reference of the rule (helpful to find rule in design kit).
+ *   \param layer1 the first layer.
+ *   \param layer2 the second layer.
+ */
+
+/*! \fn inline Name Rule::getName()
+ *   \brief returns the name of the rule.
+ */
+
+/*! \fn inline Name Rule::getType()
+ *   \brief returns the type of the rule.
+ *
+ *   Rule's type allows to set a specific type for a rule especially the 'area' type to take into account that the value of the rule is to be considered in unit^2.
+ */
+
+/*! \fn inline double Rule::getValue()
+ *   \brief returns the value of the rule.
+ */
+
+/*! \fn inline std::string Rule::getValueAsString()
+ *   \brief returns the string corresponding to the value of the rule.
+ */
+
+/*! \fn inline Name Rule::getRef()
+ *   \brief returns the reference of the rule.
+ */
+
+/*! \fn inline Name Rule::getLayer1()
+ *   \brief returns the first layer of the rule.
+ */
+
+/*! \fn inline Name Rule::getLayer2()
+ *   \brief returns the second layer of the rule.
+ */
+
+/*! \fn inline void Rule::setType(Name type)
+ *   \brief sets the type of a rule.
+ *
+ *   \param type   the type of the rule.
+ *
+ *   \note By default the type of a rule is Name("").
+ */
+
+ /*! \class ARule
+ *
+ *  This class describes an asymmetrical rule.
+ *
+ *  An asymmetrical rule represents a two layers rule for which inverting layer1 and layer2 implies that the value of rule change.
+ *  For example minimum enclosure rule is assymetrical.
+ *
+ *  Typical arules are:
+ *  <i>minExtension, minEnclosure, minLengthEnclosure, minWidthEnclosure, lineExtension, minGateExtension, minGateEnclosure</i>
+ *
+ */
+ 
+}

vlsisapd/doc/dtr/Techno.dox

@@ -0,0 +1,100 @@
+// -*- C++ -*-
+
+namespace DTR {
+/*! \class Techno
+ *
+ *  This class contains generic informations such as the name of the technology and the unit used, and the list of all technologic rules.
+ */
+
+/*! \fn Techno::Techno(Name name, Name unit)
+ *   \brief creates a new technology
+ *
+ *   \param  name the name of the technology.
+ *   \param  unit the unit used for all values.
+ */
+
+/*! \fn inline Name Techno::getName()
+ *   \brief returns the name of the technology.
+ */
+
+/*! \fn inline Name Techno::getUnit()
+ *   \brief returns the unit.
+ */
+
+/*! \fn inline std::vector<Rule*>& Techno::getRules()
+ *   \brief returns a reference on the std::vector containing all technology's rules.
+ *
+ *   \note this method is not yet available in python
+ */
+
+/*! \fn Rule* Techno::addRule(Name name, double value, Name ref, Name layer1, Name layer2)
+ *   \brief creates a new Rule and adds it the to Techno object.
+ *
+ *   \param name   the name of the rule.
+ *   \param value  the value of the rule.
+ *   \param ref    the reference of the rule (helpful to find the rule in design kit).
+ *   \param layer1 the first layer. This is an optionnal argument, default value is Name("").
+ *   \param layer2 the second layer. This is an optionnal argument, default value is Name("").
+ *   
+ *   \return the newly created Rule object.
+ */
+
+/*! \fn Arule* Techno::addARule(Name name, double value, Name ref, Name layer1, Name layer2)
+ *   \brief creates a new ARule and adds it to the Techno object.
+ *
+ *   \param name   the name of the rule.
+ *   \param value  the value of the rule.
+ *   \param ref    the reference of the rule (helpful to find the rule in design kit).
+ *   \param layer1 the first layer.
+ *   \param layer2 the second layer.
+ *
+ *   \return the newly created ARule object.
+ */
+
+/*! \fn Rule* Techno::getRule(Name name, Name layer1, Name layer2)
+ *   \brief returns the rule uniquely identified by its name and layers.
+ *
+ *   \param name   the name of the rule.
+ *   \param layer1 the first layer. This is an optionnal argument, default value is Name("").
+ *   \param layer2 the second layer. This is an optionnal argument, default value is Name("").
+ *
+ *   \return the rule.
+ */
+
+/*! \fn double Techno::getValue(Name name, Name layer1, Name layer2)
+ *   \brief returns the value of a rule uniquely identified by its name and layers.
+ *
+ *   \param name   the name of the rule.
+ *   \param layer1 the first layer. This is an optionnal argument, default value is Name("").
+ *   \param layer2 the second layer. This is an optionnal argument, default value is Name("").
+ *
+ *   \return the value of the rule.
+ */
+
+/*! \fn std::string Techno::getValueAsString(Name name, Name layer1, Name layer2)
+ *   \brief returns a string corresponding to the value of a rule uniquely identified by its name and layers.
+ * 
+ *   \param name   the name of the rule.
+ *   \param layer1 the first layer. This is an optionnal argument, default value is Name("").
+ *   \param layer2 the second layer. This is an optionnal argument, default value is Name("").
+ *
+ *   \return the string corresponding to the value of the rule.
+ *
+ *   \note this method is important for python module since to avoid rounding problems it is necessary to use Decimal object which is build based on a string.
+ */
+
+/*! \fn bool Techno::writeToFile(std::string filename)
+ *   \brief writes the database to file.
+ *
+ *   \param filename the destination file name.
+ */
+
+/*! \fn static Techno* Techno::readFromFile(const std::string filename)
+ *   \brief creates and returns a Techno object based on a database source file.
+ *
+ *   \param filename the source file name.
+ *
+ *   \return the newly created Techno.
+ */
+ 
+}

vlsisapd/doc/dtr/dtr.dox

@@ -0,0 +1,58 @@
+/*! \page DTR DTR Format
+
+  \section dtrPres Presentation
+  The <b>Design Technology Rules (DTR)</b> format was developped as a part of the Chams Project (http://www-soc.lip6.fr/recherche/cian/chams/). It aims at offering a generic description of layout design rules for CMOS technologies.\n
+
+  \subsection dtrAutrhos Author
+  Damien Dupuis: damien.dupuis(at)lip6(.)fr
+
+  \subsection dtrLimits Limitations
+  Only simple rules are supported at the moment. For example the minimum width of a metal layer has only one value, although it should depends on the length of the wire drawned.
+
+  \section dtrDB Stand alone database structure
+  The database contains four object :
+  - DTR::Techno contains generic informations such as the name of the technology and the unit used, and the list of all technologic rules.
+  - DTR::Rule & DTR::ARule respectively describe a symmetrical and an asymmetrical rule.
+  - DTR::Name provides an automatic management of shared name.
+
+  \subsection dtrParser Using the parser
+  Simply load a technology with static function DTR::Techno::readFromFile() and then get rules (DTR::Techno::getRule()) or directly values (DTR::Techno::getValue()).
+
+  \subsection dtrDriver Using the driver
+  Using the driver is very simple, user has to create a DTR::Techno object and simply add DTR::Rule or DTR::ARule to it.
+  The adding methods return the newly created Rule so user can set the rule type (DTR::Rule::setType()) if necessary. Finally use the DTR::Techno::writeToFile() method to dump the database to file.
+
+  \section dtrExamples Examples
+  As said is the global presentation, VLSI SAPD project provides C++ libraries and Python modules for each supported format. In this section we present simple code examples to parse and drive a DTR file using C++ or Python. The DTR file considered is the same for all examples: \c example.dtr.xml
+  \include example.dtr.xml
+
+  All source codes are available in the \c examples directory.
+
+  \subsection dtrC C++
+  \subsubsection dtrParseC Parser
+  The following code (\c parseDtr.cpp) is an example of how to parse a DTR file using C++ library.
+  \include parseDtr.cpp
+
+  \subsubsection dtrDriveC Driver
+  This C++ code (\c driveDtr.cpp) generates a out.dtr.xml file equivalent to the previous example.dtr.xml.
+  \include driveDtr.cpp
+
+  \note In order to compile these codes, a CMakeLists.txt file is provided. User must set the $VLSISAPD_TOP variable before running these commands in the directory containing the CMakeLists.txt file:
+  \code
+  %> mkdir build; cd build
+  %> cmake ..
+  %> make
+  \endcode
+
+  \subsection dtrPython Python
+  \subsubsection dtrParsePython Parser
+  The following python script (\c parseDtr.py) is an example of how to parse a DTR file using python module.
+  \include parseDtr.py
+
+  \subsubsection dtrDrivePython Driver
+  This python script (\c driveDtr.py) generates a out.dtr.xml file equivalent to the previous example.dtr.xml.
+  \include driveDtr.py
+
+  \note In order to run these two scripts (\c parseDtr.py & driveDtr.py), user must ensure that $PYTHONPATH variable points to the directory containing pyDTR.so module.
+*/
+

vlsisapd/doc/header.html

@@ -10,8 +10,9 @@
       <table class="header">
         <tr>
           <td><a href="index.html">Presentation</a></td>
-          <td><a href="_c_i_f.html">CIF</a></td>
           <td><a href="_a_g_d_s.html">AGDS</a></td>
+          <td><a href="_c_i_f.html">CIF</a></td>
+          <td><a href="_d_t_r.html">DTR</a></td>
           <td><a href="_contact.html">Links & Contact</a></td>
         </tr>
       </table>

vlsisapd/doc/mainPage.dox

@@ -10,17 +10,17 @@
     <td><center><b>Parser</b></center></td>
     <td><center><b>Driver</b></center></td>
   </tr><tr>
-    <td>CIF</td>
+    <td>AGDS</td>
     <td></td>
     <td><center>x</center></td>
   </tr><tr>
-    <td>AGDS</td>
+    <td>CIF</td>
     <td></td>
     <td><center>x</center></td>
   </tr><tr>
     <td>DTR</td>
     <td><center>x</center></td>
-    <td></td>
+    <td><center>x</center></td>
   </tr><tr>
     <td>OPENCHAMS</td>
     <td><center>x</center></td>
@@ -31,7 +31,8 @@
 
 
   To quickly access to documentation of a format, one can use the following links :
-  - \subpage CIF CIF Format
   - \subpage AGDS AGDS Format
+  - \subpage CIF CIF Format
+  - \subpage DTR DTR Format
 
 */

vlsisapd/doc/stylesheet.css

@@ -130,8 +130,7 @@
  }
 
  tt          { color:           #3090FF; }
- em          { font-style:      italic;
+ em          { font-style:      italic;  }
-               font-weight:     bold;    }
  strong      { font-weight:     bold;    }
 
  span.textit { font-style:      italic;  }