Getting Started with the Octtools The Octtools are a collection of programs and libraries that together form an integrated system for IC design. The system includes tools for PLA and multi-level logic synthesis, standard cell placement and routing, and cus- tom cell design, as well as a variety of utility programs for manipulating schematic, symbolic, and geometric design data. Most tools are integrated with the Oct data manager and the VEM user interface. This document contains general information about running and installing the Octtools. It assumes some familiarity with UNIX. For more information, consult the four volumes of documentation: (1) Volume One contains a tutorial introduction to some of the more important tools, and in-depth tutorials and user's manuals for specific tools. (2) Volume Two presents implementation details about the Oct database and some of the tools. (3) Volume Three collects all the UNIX man pages for the tools (which are available on-line via the octman command). (4) Volume Four contains other assorted documentation (also available on-line through octman). 1. Setting Up the UNIX Environment To use the Octtools, you will need two things defined in your UNIX environment: (1) the OCTTOOLS environment variable; and (2) the Octtools binary directory in your search path. Additionally, some tools require general environment variables that some UNIX systems do not initialize, such as DISPLAY (for X) and USER. On such systems these variables will must be explicitly defined. 1.1. The OCTTOOLS variable This variable should be set to the machine specific directory in which the tools (binary executables and libraries) reside. This directory can be found directly under the Octtools root directory (after the tools have been installed). Machine platforms, which are determined by both processor archi- tecture and version of UNIX, include: (1) hpux (Hewlett-Packard HP-UX Version 8 or later and PA-RISC) (2) mips (DEC Ultrix and MIPS) (3) sun4 (Sun SunOS 4.X and SPARC) For example, if you are running on a SPARCstation 2, and the Octtools reside in /usr/cad/octtools, you should put if ( ! $?OCTTOOLS ) then setenv OCTTOOLS /usr/cad/octtools/sun4 endif in your .cshrc file. 1.2. The Octtools bin directory In order for UNIX to find the Octtools programs, you will need the Oct- tools bin directory in your search path. The bin directory is found in the OCTTOOLS directory, so set path=($path $OCTTOOLS/bin) in your .cshrc file will add the bin directory to your search path. 2. On-Line Documentation On-line documentation is available with the octman command, a slightly modified version of UNIX man that retrieves Octtools documentation. Man pages exist in various degrees of detail and accuracy for most tools. There is also information on Oct library routines (octman 3) and formats (octman 5). In addition, less formally organized documentation exists on a variety of sub- jects (octman doc). 3. Installation To install the Octtools you need: (1) a standard C compiler (from HP, Sun, or DEC -- gcc is problematic); (2) X Windows, Version X11R4 or later; and (3) the Athena Widget Set (libaw.a) for X, which is not distributed on all machines. You may have to build it yourself, in which case you can get the source via FTP from gatekeeper.dec.com. In addition, if you want to build the vov tool, you need g++. Installation is a four stage process: (1) getting and setting up the tar files of the release; (2) unpacking the tar files; (3) setting up the compilation environment for the install; and (4) compiling and installing the tools. 3.1. Getting the tar files To get a copy of the Octtools release package contact software@hera.berkeley.edu or Software Distribution Office Industrial Liaison Program 205 Cory Hall University of California at Berkeley Berkeley, CA 94720 (510) 643-6687 (510) 643-6694 (fax) The release package consists of a few text and script files (including ARCHITECTURE, COPYRIGHTS, INSTALL, PREINSTALL, and README), and a number of compressed tar files that contain source code, technology files, and documen- tation. All these files should be put in the Octtools root directory. The files ARCHITECTURE, INSTALL, and PREINSTALL are scripts that must be execut- able (chmod 755 ...). 3.2. Unpacking the tar files The PREINSTALL script unpacks the tar files. It takes an argument, either KEEP or REMOVE. If KEEP then the compressed tar files are kept; if REMOVE then the tar files are removed and just the unpacked files are kept, saving disk space. The PREINSTALL script also verifies checksums on the tar files. Note that the release package includes items that are not directly part of the Octtools, such as Spice. These items are not unpacked or installed automatically. They also have their own documentation. 3.3. Setting up the compilation environment The INSTALL script sets up the platform dependent binary and library directories, and compiles and installs the tools. Two items must be set up correctly for the script to work. (1) The OCTTOOLS environment variable must be defined. If it is undefined the INSTALL script will try to set it, but it is advisable for the vari- able to be defined in advance. See above for how to set it. (2) Two configuration variables in INSTALL determine the location of the X11 include files and libraries, xincloc and xlibloc. As delivered, these are set to values reasonable at UCB, but will almost certainly have to be changed for your system. In addition, the ARCHITECTURE script must run correctly. Run the script and see if it returns the type of machine you are using. If it does not you can either fix the ARCHITECTURE script or fix INSTALL to compile for your machine type without using ARCHITECTURE. 3.4. Building the tools The INSTALL script uses a layered sequence of makefiles, with one in the OCTTOOLS directory, one in the src directory, one in each tool type directory (such as Layout or Framework), and finally one for each tool. Each of the general (non tool specific) makefiles has an associated TOOL-LIST file that is used to select which tools are built. These files can be edited to change the selected tools. The default TOOL-LIST files make everything but BIGOCT, BearFP, LightLisp, OctLisp, Unsupported, Vov, boss, and slide-maker. Once the environment is configured, simply run INSTALL to compile and install the programs, program libraries, technology descriptions, and documen- tation. All object files and other effluvia can be removed by connecting to the OCTTOOLS directory and typing make clean. 4. How the Octtools Are Organized The initial release, before installation, resides in the Octtools root directory under common, in the four directories (1) tech -- technology files; (2) lib -- assorted design-related library items; (3) document -- the PostScript form of the manual; and (4) src -- program sources, man pages, test cases, etc. The installation process creates (1) common/include (from include files scattered through common/src) (2) common/doc (from doc files scattered through common/src) (3) common/man (from man files scattered through common/src) (4) OCTTOOLS/ (the platform-specific directory) (5) OCTTOOLS//lib (which holds lib*.a files) (6) OCTTOOLS//bin (which holds executables) (7) links from OCTTOOLS/ to various directories in common The Octtools universe residing in common/src is conceptually divided into two basic classes of things: libraries which, when compiled, end up in /lib, and tools, which use the libraries and, when compiled, end up in /bin. Almost all the libraries (called packages), are found in the directories common/src/Packages common/src/Xpackages and the tools are in common/src/Framework common/src/Synthesis common/src/Layout common/src/Technology common/src/Simulation common/src/OtherTools common/src/Utils Packages: This directory, along with Xpackages and Technology, contains the source code for the libraries. Important packages here are oct (the basic Oct database routines), oh (additional Oct helper functions and macros), mm (the Oct versions of malloc and free, which don't port very well), and port (which contains items related exclusively to porting, primarily port.h; note that not all porting problems are solved in port.h -- individual tools also conditionally compile specialized code). There are several other data struc- ture packages as well, such as st (symbol table) and avl (avl tree). Most of these packages are documented; either look in common/doc or use octman (which looks in the common/doc directory). Xpackages: This directory contains X libraries primarily used by vem, including dds (the dialog box definition system) and the rpc libraries used by vem clients. Framework: This directory contains general tools and utilities, some of which are oriented toward design, and some of which are Oct database mainte- nance utilities. Tools include vem (the graphical editor), oct2ps (a postscript translator), octman (man for the Octtools), bdnet (the netlist front end), fabprep (which prepares an Oct layout for fab), chipstats (which compiles statistics on a chip), octflatten (which flattens an Oct cell hierar- chy), and attache (the general Oct facet database editor). These tools range from the almost trivial (inconsistent) to the gigantic (vem). Synthesis: This directory contains logic and PLA synthesis tools, includ- ing espresso and misII. Layout: This directory contains the layout tools, most notably wolfe/Timberwolf (the standard cell placer and router) and mosaico (the macro cell router), which is a shell script that in turn invokes several other tools. Technology: The primary item in this directory is tap, the technology access package, which is used (by vem) to access technology files. Simulation: The primary items in this directory are musa, the multi-level simulator that runs off of the Oct data base, and steps, the Oct to Spice translator. OtherTools: This directory contains miscellaneous items such as xgraph and slide-maker. Utils: This directory contains assorted items used for building an Oct- tools distribution. 5. Making a Tool If you need to build an individual tool, cd to the tool's directory, fix XINCLOC and XLIBLOC in the Makefile to be your X directories (see above), set any necessary platform flags in the CC line, for example CC =/bin/cc -Dhpux and type make or make install to put the executable in OCTTOOLS/bin, or make debug-g to get a version with symbols usable by the debugger. If you want a debug-g version, you will also need debug-g versions of the packages (see below). To build a package (library), cd to the package's directory, fix the X directories, and type make install (which will put the package in OCTTOOLS/lib), or make debug-g to get a debuggable version (which also puts the package in OCTTOOLS/lib). In general, in a tool or package directory you can type make help for a list of the actions make knows about. For more details on Octtools makefiles, if you need to modify or create one, try octman create-octtools-makefile