

  <refentry id="genlib">
  <?dbhtml filename="man_genlib.html">

  <refmeta>
    <refentrytitle>genlib</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>ASIM/LIP6</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname> genlib </refname>
    <refpurpose> Procedural design language based upon C. </refpurpose>
  </refnamediv>

  <!--
  <refsect1>
    <title> Origin </title>

    <para> This software belongs to the ALLIANCE CAD system from  the
    CAO-VLSI team at ASIM/LIP6/UPMC laboratory.
    <address>
      <firstname><emphasis>LIP6/ASIM, University P. et M. Curie</emphasis></firstname> 
      <street>4, place Jussieu</street> 
      <postcode>75252 PARIS Cedex 05</postcode> 
      <country>FRANCE</country> 
      <fax>{33/0} 1.44.27.62.86</fax>
      <email>alliance-users@asim.lip6.fr</email>
    </address>
    </para>

  </refsect1>
  -->

  <refsect1>
    <title> Description </title>

    <para> &genlib; is a set of C functions dedicated to procedural
    generation purposes. From a user point of view, genlib is a circuit's
    description  language that allows standard C programming flow control,
    variable use, and specialized functions in order to handle vlsi
    objects.
    </para>
    <para> Based upon the &Alliance; &mbk; data structures, the &genlib;
    language gives the  user  the  ability  to  describe  both netlist
    and layout views, thus allowing both standard cell and full custom
    approachs.
    </para>

    <refsect2>
      <title> Netlist capture </title>

      <para> It is a hierachical structural description of a circuit in
      terms of connectors (I/Os), signals (nets), and instances.
      </para>
      <para> The function calls used to handle the netlist view are :
      <itemizedlist>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_DEF_LOFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SAVE_LOFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_LOINS</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_LOCON</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_LOSIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_FLATTEN_LOFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
      </itemizedlist>
      Some facilities, in order to create vectors are also available :
      <itemizedlist>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_BUS</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_ELM</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
      </itemizedlist>
      </para>
    </refsect2>

    <refsect2>
      <title> Standard cell placement </title>

      <para>The following functions allows to define a placement file
      for a standard cell design. This file can be used by the standard
      cell router <citerefentry><refentrytitle>ocr</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry> :
      <itemizedlist>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_DEF_PHSC</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SAVE_PHSC</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SC_PLACE</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SC_RIGHT</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SC_TOP</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SC_LEFT</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SC_BOTTOM</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
      </itemizedlist>
      </para>

    </refsect2>

    <refsect2>
      <title> Full custom symbolic layout </title>

      <para> Those functions are dedicated to optimized full custom
      procedural layout. In order to provide some process independance,
      &Alliance; uses a symbolic layout approach (fixed grid without
      compaction).
      </para>
      <para> The symbolic objects are segments (wires), vias (contacts),
      connectors (I/Os), references and instances. For more informations,
      see
      <citerefentry><refentrytitle>phseg</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>phvia</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>phcon</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>phref</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>phins</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>
      and <citerefentry><refentrytitle>alc</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>.
      <itemizedlist>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_DEF_PHFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_SAVE_PHFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_DEF_AB</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_DEF_PHINS</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PHCON</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_CON</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_CON_FACE</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_ALL_CON</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PHSEG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_SEG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_THRU_H</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_THRU_V</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_THRU_CON_H</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_THRU_CON_V</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_WIRE1</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_WIRE2</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_WIRE3</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PHVIA</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_RIGHT</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_TOP</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_LEFT</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_BOTTOM</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_ON</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PHREF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_REF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_COPY_UP_ALL_REF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_VIA_REF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_CON_REF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_PLACE_SEG_REF</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_FLATTEN_PHFIG</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_GET_REF_X</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_GET_REF_Y</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_GET_CON_X</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_GET_CON_Y</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_HEIGHT</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
        <listitem><para><citerefentry>
          <refentrytitle>GENLIB_WIDTH</refentrytitle>
          <manvolnum>3</manvolnum>
        </citerefentry></para></listitem>
      </itemizedlist>
      In order to have information about each of these functions, use
      the online documentation with <citerefentry>
      <refentrytitle>man</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>, as in
      <filename>man function-name</filename>.
      </para>
      <para> It is strongly recommended to read some books on C
      programming, in order to take full advantage of the C flow
      control possibilities, as it may greatly reduce  the  size
      of a &genlib; source code.
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title> ENVIRONMENT VARIABLES </title>

    <para>
      <itemizedlist>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_IN_LO</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>al</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_OUT_LO</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>al</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_IN_PH</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>ap</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_OUT_LO</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>ap</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_CATA_LIB</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>.</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_WORK_LIB</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>.</literal>
          </para>
        </listitem>
        <listitem>
          <para>
          <citerefentry>
            <refentrytitle>MBK_CATAL_NAME</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>,
          default value : <literal>CATAL</literal>
          </para>
        </listitem>
      </itemizedlist>
      <!--
      <table pgwide="1" id="table-genlib-environment-variables">
        <title> Environment Variables </title>
        <tgroup cols="2">
          <colspec align="left" colwidth="1*" colname="c1">
          <colspec align="left" colwidth="1*" colname="c2">
          <thead>
            <row>
             <entry align="center"> Name </entry>
             <entry align="center"> Default Value </entry>
           </row>
         </thead>
         <tbody>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_IN_LO</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>al</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_OUT_LO</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>al</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_IN_PH</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>ap</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_OUT_PH</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>ap</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_CATA_LIB</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>.</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_WORK_LIB</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>.</literal></entry>
           </row>
           <row>
             <entry>
               <citerefentry>
                 <refentrytitle>MBK_CATAL_NAME</refentrytitle>
                 <manvolnum>1</manvolnum>
               </citerefentry>
             </entry>
             <entry><literal>CATAL</literal></entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    -->
    See the corresponding manual pages for further informations.
    </para>
    <para> In  order to compile and execute a &genlib; file, one has to
    call &genlib; with one argument, that is the &genlib; source file.
    The source file must have a .c extension, but the extension should
    not be mentionned on the command line.
    </para>
    <para> The names used in genlib, as arguments to genlib functions,
    should be alphanumerical, including the underscore. They also are not
    case sensitive, so &VDD; is equivalent to &vdd;. Vectorized connectors
    or signal can be declareds using the <literal>[n:m]</literal> construct.
    </para>

  </refsect1>

  <refsect1>
    <title>Synopsis</title>

    <cmdsynopsis>
      <command>genlib</command>
      <arg choice="opt">
        <option>-cklmnv</option>
      </arg>
      <arg choice="opt">--no-rm-core</arg>
      <arg choice="opt">--keep-makefile</arg>
      <arg choice="opt">--keep-exec</arg>
      <arg choice="opt">--keep-log</arg>
      <arg choice="opt">--no-exec</arg>
      <arg choice="opt">--verbose</arg>
      <arg choice="req">program</arg>
      <arg choice="opt">-e <replaceable>program_args</replaceable></arg>
    </cmdsynopsis>

    <refsect2>
      <title> Options </title>

      <para>
      <itemizedlist>
        <listitem>
          <para> &arg-program; : the name of the C file containing the
          &genlib; program, whitout extention. Mandatory argument.
          </para>
        </listitem>
        <listitem>
          <para> &arg-no-rm-core; : in case of core dump, do not remove
          the generated core file. This option must be used with
          &arg-keep-exec;.
          </para>
        </listitem>
        <listitem>
          <para> &arg-keep-makefile; : do not erase the generated makefile
          after execution.
          </para>
        </listitem>
        <listitem>
          <para> &arg-keep-exec; : keep the generated executable after the
          &genlib; run.
          </para>
        </listitem>
        <listitem>
          <para> &arg-keep-log; : do not erase the log file after a successfull
          completion (the log is keeped after a faulty run).
          </para>
        </listitem>
        <listitem>
          <para> &arg-no-exec; : do not run the generated program. Should be
          used with &arg-keep-exec;.
          </para>
        </listitem>
        <listitem>
          <para> &arg-verbose; : self explanatory.
          </para>
        </listitem>
        <listitem>
          <para> &arg-e; : all the following arguments are handled to the
          compiled program.
          </para>
        </listitem>
      </itemizedlist>
      </para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Examples</title>

    <informalexample>
      <para> Compile and run a file <filename>amd2901.c</filename> :
      <screen>
genlib -v amd2901
      </screen>
      </para>
    </informalexample>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry>
        <refentrytitle>mbk</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
    </para>
  </refsect1>

  <refsect1>
    <title>Diagnostic</title>

    <para> Many errors may occur while executing the source file,  so
    refer to the proper genlib function manual for more. When an error
    occur, &genlib; left a log file <filename>&lt;program&gt;.grr</filename>.
    As <filename>&lt;program&gt;.c</filename> is a C program, all
    syntatic C error can occurs...
    </para>
    <para> All genlib functions are listed below alphabetically sorted.
    </para>

  </refsect1>
  

  </refentry>
