README
------

Copyright
---------

Please read the COPYING file for copyright information and license agreement.

Introduction
------------

OpenAccess Gear is a collection of tools for use with OpenAccess.
Currently OA Gear consists of a number of packages:

* Ai:  And-inverter graph library
* Bazaar:  Graphical user and command line interfaces
* Buffer:  Simple buffer insertion/optimization code
* CapoWrapper:  OA interface to Capo placement tool
* Dd:  Wrapper for decision diagram library
* Examples:  Benchmark circuits
* Func:  Functional/logical representation
* Mapper:  Simple techmapping code
* MiniSat:  Boolean satisfiability package
* Redun:  Redundancy remover
* Timer:  Static timing analysis engine
* Tools:  Miscellaneous command-line tools
* Util:  Library of generally useful classes

-------------------------------------------------------------------------------

Prerequisites/Dependencies
--------------------------

There are several prerequisites for building OA Gear.  Some of these may
be optional depending on the components of OA Gear you wish to build:

* OpenAccess 2.2.6
    Tested with OA-2.2.6 (2.2p052)
    Available at http://openeda.si2.org/
    Older versions may not work due to OA API changes.
* gcc 3.2
    Tested with gcc-3.2.3
    Available at ftp://ftp.gnu.org/
    Note that OA may have more specific requirements for gcc on your
    particular system;  see the OA docs for more details.
* QT 3.3
    Optional: required if you are building OA Gear Bazaar
    Tested with QT-3.3.4
    Available at http://trolltech.com/
    The QT libraries must be compiled with threading support.  If you
    do not have a file named libqt-mt.so in your $QTDIR/lib/ directory,
    your version of QT was compiled without threading.
* UMpack (University of Michigan physical design tools, including Capo)
    Optional: required if you are building CapoWrapper
    Tested with UMpack-42-060927
    Available at http://www.openedatools.org/projects/umpack/
    Also see http://vlsicad.eecs.umich.edu/BK/PDtools/
* TCL 8.4
    Optional: required if you are building Bazaar
    Tested with TCL-8.4.11
    Available at http://www.tcl.tk/
* CUDD 2.4
    Optional: required if you are building the Dd wrapper library
    Tested with CUDD-2.4.1
    Available at http://vlsi.colorado.edu/~fabio/

Make sure the required packages are properly installed.  For QT, this
means the QTDIR environment variable must be set to correctly point to
the QT installation directory.

-------------------------------------------------------------------------------

Compiling/Installing
--------------------

1. Choose a directory to serve as the final installation directory.
    For most users, something like $HOME/OAGear would be sufficient.
    Ideally the install directory should be separate from the source
    directory.

2. cd to the directory containing this README file.

3. Configure the build by issuing the command:
		./configure <options>

    Some of the more useful <options>:

    * General Options:
	--help
	    Shows a list of all options.
	--prefix=<install-dir>
	    Specify the intallation directory chosen in Step 1 above.
	    This option must be specified for a complete install.
	--with-oa=<oa-dir> (default: ../OA-2.2)
	    This option specifies where OpenAccess is installed.
	    This option must be specified so that the build process can
	    find OA.
	--with-sysname=<sysname>
	    This option overrides the automatically detected system name
	    used to determine which version of OA to use.  If you have OA
	    for several different architectures installed under the same
	    directory and autodetection fails to find the correct one,
	    use this option.

    * Disabling Packages:
    	--disable-<package-name>
	    Turns off compilation of the given OA Gear package.  Package
	    names should be specified in all lower case letters, using
	    dashes to separate words.  Run "./configure --help" to see
	    the full list of accepted options.	Some packages depend on
	    the existence of other packages, and you will be warned if
	    you disable a prerequisite of a package which is not disabled.

    * OA Gear Bazaar Options:
	--with-tcl=<tcl-dir> (default: /usr/lib)
	    Specifies the directory where tclConfig.sh can be found.
	    This option can be omitted if you are not building Bazaar.

    * OA Gear CapoWrapper Options:
	--with-umpack=<umpack-dir> (default: ../UMPack)
	    Specifies where UMpack is located.	If you are not building
	    CapoWrapper, this option can be omitted.

    * OA Gear Dd Options:
	--with-cudd=<CUDD_Dir> (default: ../cudd)
	    This option specifies where the CUDD library is installed.
	    If you are not building Dd, this option can be omitted.

4. Build:
		make

5. Install:
		make install

    The binaries may still be usable without actually installing them,
    but this is not recommended.

    OA Gear executables are installed in a subdirectory bin/ in the
    install directory.  You may wish to add this directory to your PATH
    environment variable.

-------------------------------------------------------------------------------

README-developer
----------------

If you are not only planning to use OAGear, but to develope some tools,
or if you should have problems with Compiling and Installing please have 
a look at the README-developer.

-------------------------------------------------------------------------------

genPhysical
-----------

OA Gear comes with a program called "genPhysical" which converts
an oacNetlist view to an oacMaskLayout view.  This conversion may be
necessary since tools such as OA Gear Timer uses the oacMaskLayout view,
which includes physical data, whereas a Verilog netlist does not provide
such information.
 
In addition to creating the oacMaskLayout view, genPhysical generates
an appropriate oaCoreBoxSpec for the design, and primary input/output
oaTerms are assigned positions around the periphery randomly.

For usage notes, run genPhysical with no arguments.

-------------------------------------------------------------------------------

Documentation
-------------

Documentation for the OA Gear packages can be found in the Documentation/
subdirectories in each package directory.

Users of OA Gear Timer may want to look at analyzeTiming.cpp for an
example of how to use the package.

OA Gear developers should see the README-developer file for additional
notes.

-------------------------------------------------------------------------------

Examples
--------

OA Gear comes with some example designs from the ISCAS89 benchmark suite.
These examples are installed using "make install" and appear in the share/
subdirectory in the install directory.

The examples will be converted from the source Verilog files to an OA
database in a subdirectory named "db".

The example designs come with a hypothetical standard cell library on
a 250nm process.  The standard cell library and process tech data are
created in an OA lib named "cbl250".

The example designs themselves are available in an OA lib named "designs".

-------------------------------------------------------------------------------

Regression/Unit Tests
---------------------

Tests for OA Gear can be run by first building OA Gear, then doing:

		make check

in the top level source directory. For further information on regression
tests, please have a look at the README-developer.

-------------------------------------------------------------------------------

Common Problems
---------------

* (Linux) Running an executable gives the message "error while loading
    shared libraries: liboaBase.so: cannot open shared object file: No
    such file or directory".

    You need to have the shared libraries for OpenAccess available in
    your LD_LIBRARY_PATH environment variable.  This variable should
    contain a colon-separated list of directories to search for the
    required lib*.so files.

-------------------------------------------------------------------------------

WWW
---

OA Gear is hosted by SI2.

OA Gear Home Page:     http://openedatools.si2.org/oagear/
OA Gear Project Page:  http://openedatools.si2.org/projects/oagear/

-------------------------------------------------------------------------------

Feedback
--------

OA Gear is in continuous development.  Any feedback or suggestions for
improvement are welcome, and contributions of code, documentation or
additional components are encouraged.

Bugs and other feedback can be submitted through the project page
(URL above).  Also see the AUTHORS file for contact information.

-------------------------------------------------------------------------------

Todo List
---------

* Fix relative path handling in Examples/make-db
* Clean up MiniSAT library handling

