# # @(#)INSTALLATION 1.35 09/03/96 Delft University of Technology # cat << 'EOF' O C E A N INSTALLATION MANUAL ------------------------------- December 29, 1994 1. INTRODUCTION ============ OCEAN is a freely-available system that enables you to design CMOS chips in the sea-of-gates design style. The sea-of-gates design style aims at three goals: (1) minimizing the chip design time (2) minimizing the chip fabrication time (3) minimizing the chip cost Before you can start designing a sea-of-gates chip you have to select a master image. This is a prefabricated pattern of transistors that is laid out over the entire chip area. The effort of the designer (and the design tools) is to interconnect these transistors by metal wires, thus implementing the desired functionality of the chip. In contrast to other sea-of-gates design systems that we know of, OCEAN allows you to design your chip in a hierarchical fashion. This has several advantages, including the ability to (1) easily mix analogue and digital subcomponents on a chip (2) manually optimize parts of the automatically generated layout (3) design critical subcomponents (e.g. RAM) and reuse them OCEAN has been used extensively at the EE faculty of Delft University of Technology, the Netherlands. Second year students without any previous experience in VLSI design were able to design reasonably complex CMOS chips with OCEAN. After processing in the DIMES foundry, many of these student chips where successfully tested. For more information, we recommend that you retrieve the file 'ocean_docs.tar.gz', which contains a postscript file describing everything about the system. 2. AVAILABILITY ============ OCEAN is integrated with the Nelsis (release 3) full-custom chip design system. For best results, do not install OCEAN without installing Nelsis. Both systems are available for free from Delft University of Technology. You can obtain a copy from the anonymous-FTP host donau.et.tudelft.nl (130.161.144.100), directory pub/ocean. Alternatively you can use the ftp directory on 'olt.et.tudelft.nl' or access the Gopher server 'olt.et.tudelft.nl' and fetch it from "Computer corner/The OCEAN Sea-of-Gates design system distribution/". We try to make sure that the OCEAN distribution archives always contain the latest version. We do not work with releases nor release numbers. Instead, you can easily find the compilation date of each archive file in the directory 'release_info'. OCEAN also runs with Nelsis release 4. This Nelsis release offers a very advanced version mechanism, a flow manager, graphical representation of the chip hierarchy, and many more nifty little things. If you prefer release 4 over release 3, get it from dutente.et.tudelft.nl:pub/nelsis. Note, however, that we do not actively support Nelsis release 4 in combination with OCEAN. 3. REQUIRED HARDWARE ================= The directory donau.et.tudelft.nl:pub/ocean contains sources of the OCEAN system. It also contains the compiled system for four types of machines: PA-RISC1.1_9 Hewlett-Packard computers, series 9000/700 (a.k.a. "snake") and 9000/8x7 (the business servers a.k.a. "Nova") running HP-UX 9.0 or higher. The old 9000/8x5 series cannot run these executables, but you can compile the ocean sources easily yourself for these machines (See section 8.5 and 8.6 below). sun4_4 Sun-4 computers (a.k.a. "Sparc") running SunOS-4.1.3 or later. sun4_5 Sun-4 computers (a.k.a. "Sparc") running SunOS-5.3 or later. This version of SunOS is also known as Solaris-5.3. i486_Linux PC-compatible with a 386, 486 or pentium processor running Linux. Linux is a freely available unix operating system for PC's. It is remarkably stable and has all the features that e.g. HP and Sun offer, like X-windows, networking, compilers, etc. The precompiled installation of OCEAN is statically linked (except Solaris, there appears to be a problem with the libraries on that platform). The advantage of this is that you can install it on your system even if you do not have shared libraries for C++ and X11. The disadvantage is that the executables are considerably bigger. If you are interested in a dynamically linked set of executables you can compile the sources on your system, but you need a C++ and an ANSI-C compiler. (GNU gcc-2.3.3 and later works fine, although there are some gotchas for gcc versions before 2.6.1. We run a sed-script on some source files before calling g++ to make it work. A copy of that script is in the directory pub/ocean/ocean_src, file g++. If you have gcc-2.6.2 or later you are save and you don't need that script.) Please mail any remarks or bug reports to ocean@donau.et.tudelft.nl. 4. HOW TO INSTALL ============== You do not need root privileges to install OCEAN and Nelsis (release 3). Find a place in the file system for Nelsis (about 10 MByte) and for OCEAN (about 8 Mbyte). Let's assume these places are /users/cacd and /users/ocean. (If you choose other places, substitute these in what follows below.) First ftp the appropriate files from donau.et.tudelft.nl:pub/ocean. You need at least the files: cacd_bin_.tar.gz, cacd_process.tar.gz ocean_bin_.tar.gz ocean_celllibs.tar.gz ocean_docs.tar.gz is 'PA-RISC1.1_8' or 'sun4_4' or 'i486_Linux', depending on your hardware. (Yes, even if you have a pentium or i386 you need the i486_Linux binaries.) All files are in compressed (gzip) format. Let's assume that you have put these three files in the /tmp directory. Now one user on the system must be the "owner" of the Nelsis (release 3) tree. This user must execute the following commands (we'll assume she has the login name "spook" and she is installing on a PA-RISC1.1_8 architecture. Replace all references to "PA-RISC1.1_8" by "sun4_4" or by "i486_Linux" if you are on one of these types of machines, and replace the paths '/users/cacd' and '/users/ocean' by the directories of your own choice): [1] mkdir /users/cacd /users/ocean [2] cd /users/cacd [3] zcat /tmp/cacd_bin_PA-RISC1.1_8.tar.gz | tar xf - (if zcat doesn't work, try 'gzip -dc' instead) [4] zcat /tmp/cacd_process.tar.gz | tar xf - [5] cd /users/ocean [6] zcat /tmp/ocean_bin_PA-RISC1.1_8.tar.gz | tar xf - vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv >>> IMPORTANT NOTE: The directory pub/ocean/patches contains programs that >>> have been bug-fixed (or simply improved) since the last time that the >>> *.tar.gz files in pub/ocean were updated. Consult the file >>> pub/ocean/patches/README to find out if you need to fetch and install any >>> patches for your system. Please do this before continuing with the >>> installation ... (The ocean source files in pub/ocean/ocean_src are always >>> up to date.) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Now you have installed the binaries. The next thing you need is the directory containing the cell libraries. OCEAN will not run without them. [1] cd /users/ocean [2] zcat /tmp/ocean_celllibs.tar.gz | tar xf - [3] vi bin/PA-RISC1.1_8/nelsis3/ICELLS (... now set OCEAN_TREE=/users/ocean and NELSIS_TREE=/users/cacd and NELSIS_OWNER=spook ...) [4] setenv MACHINE PA-RISC1.1_8 setenv ICDUSERNAME spook (see also WARNING in section 5, below) setenv ICDPATH /users/cacd [5] bin/PA-RISC1.1_8/nelsis3/ICELLS (... this compiles the cell libraries into the binary format of the Nelsis database. It is normal that numerous warnings appear on your screen-- JUST IGNORE ALL ERRORS AND WARNINGS. If you feel uncertain about the messages, compare them to the file donau.et.tudelft.nl:pub/ocean/ICELLS_mesg which contains a record of an ICELLS run that we consider normal.) If you are interested in the octagon image and the gatearray image, proceed as follows: [6] setenv OCEANPROCESS octagon [7] bin/PA-RISC1.1_8/nelsis3/ICELLS [8] setenv OCEANPROCESS gatearray [9] bin/PA-RISC1.1_8/nelsis3/ICELLS [10] setenv OCEANPROCESS fishbone To set your proper print command, you might want to edit the layout print tool 'playout'. For the first time, this is not absolutely essential, but you'll probably need it to print layouts. [11] vi /users/ocean/bin/playout .... and set the proper print and printer queue commands for your system. We ran this installation procedure on several types of machines and it appeared to work. If you experience any problems, *please* let us know. Mail to ocean@donau.et.tudelft.nl or phone +31 15 786280 or +31 15 786240. At this point we would like to invite you to join the "Nautilus club". This is a special mailing list for OCEAN operators, especially meant to exchange information on the latest versions, updates and installations. Just send an email to ocean@donau.et.tudelft.nl with the subject 'nautilus club'. After you have unwrapped everything, the final directory structure of the system looks like this: /cacd (place of nelsis system = $ICDPATH) -- extracted from from archive 'cacd_bin_.tar.gz': cacd/bin/$MACHINE (nelsis executables) -- extracted from from archive 'cacd_process.tar.gz': cacd/lib/process/.. (process description databases) cacd/man (nelsis manual pages) /ocean (place of ocean system = $OCEANPATH) -- extracted from from archive 'ocean_bin_.tar.gz': ocean/bin/.. (ocean executables and scripts) -- extracted from from archive 'ocean_celllibs.tar.gz': ocean/celllibs/.. (Sea-of-Gates cell libraries and templates) -- extracted from from archive 'ocean_docs.tar.gz': ocean/docs (postscript manuals) ocean/man (on-line manuals) -- extracted from from archive 'ocean_src.tar.gz': ocean/src/.. (source files of ocean) At every installation of a source file using 'tar xf', a file in the directory 'release_info' will be created. This file informs you about the creation and compilation date of the tar archive and its contents. In this way you are able to find out whether you still have the latest release. The directories "release_info" are in the ocean distribution directory, and in your 'cacd' and 'ocean' directories 5. HOW TO RUN ========== Users running Ocean and Nelsis must have a number of environment variables set: OCEANPROCESS to "fishbone" or "octagon" or "gatearray". OCEANPATH to "/users/ocean" (or whatever the root of the OCEAN tree is). ICDPATH to "/users/cacd" (or whatever the root of the Nelsis tree is). ICDUSERNAME to "spook" (or whatever the name of the user owning the Nelsis tree is). WARNING: Sometimes the /etc/passwd file is used to store telephone numbers of users. NOTHING will work if the gecos field of the ICDUSERNAME contains exactly tree commas !!!! MACHINE to "PA-RISC1.1_9" (or whatever the program `thearch` returns as a string. Linux users indicate i486_Linux here, even if they have a pentium or 386). The users also need the following directories in their PATH: $OCEANPATH/bin/$MACHINE/nelsis3 $OCEANPATH/bin/$MACHINE $OCEANPATH/bin . $ICDPATH/bin/$MACHINE where $MACHINE is one of the supported machines (e.g. "PA-RISC1.1_9", refer to section 1 of this installation manual). Note that /users/cacd/bin/$MACHINE appears after the current directory "." and after the ocean bin directories. If you don't care about functional simulations (with the Nelsis tool func_mkdb) you can forget about the "." directory. >>> NOTE: In older versions of Ocean, the Nelsis/cacd executables lived in >>> $ICDPATH/bin; later we moved them to $ICDPATH/bin/$MACHINE. Check where >>> your executables live and adapt the PATH environment accordingly You can try whether everything was installed properly by trying to run the tutorial: [1] tutorial sis [2] cd sis [3] csls hotel.sls File hotel.sls: Parsing network: hotel [4] setenv DISPLAY :0 [4] simeye hotel (clicking [run] should give simulator results) [5] seadali [database], [place and route], [DO IT] (a routed circuit should appear) [write] as hotel [6] space -c hotel [7] ghoti Hotel [8] simeye Hotel (clicking [run] should give simulator result of extracted circuit) 6. THE TOOLS ========= THE OCEAN tools operate on their own EDIF-like database called "the seadif database". The nelsis tools operate on the nelsis database. Both databases are part of a nelsis "design project". Conversion from data in one database to the other database happens automatically, and users do not even notice that this happens. Sometimes OCEAN tools operate immediately on the nelsis database. All tools that are available from the distribution are listed below, with a one-liner briefly describing each tool. The programs that live in the ocean tree document themselves briefly if you pass them the -h option. For full documentation (in LaTeX and postscript) refer to the ocean/docs directory. The Nelsis tools have real manual pages! Use "icdman" to view them. The seadif database is also nicely documented in man pages. **** Executables in ocean/bin/$MACHINE/nelsis3/ ICELLS compiles and installs sea-of-gates cell libraries. cedif compiles EDIF sources into the nelsis database. dofunc front-end for the functional simulator "func_mkdb". fish sea-of-gates layout purifier. ghoti sea-of-gates extracted circuit purifier. mkopr creates a new sea-of-gates design project. mksls constructs a Makefile for updating a nelsis database. nelsea nelsis to seadif and seadif to nelsis database converter. sea front-end for calling seadif tools in a nelsis environment. seadali interactive tool for layout editing, placing and routing. tutorial creates a sea-of-gates design project containing a tutorial. **** Executables in ocean/bin/$MACHINE/ esea compiles EDIF sources into the seadif database. freedif removes cells from the seadif database. gnarp performs various kind of operations on a seadif database. madonna partitioning-based sea-of-gates placer. makebus analyses a netlist to extract buses from it. seedif lists the contents of the seadif database. showbus shows the buses in a netlist, as found by "makebus". trout Lee-type over-the-cell sea-of-gates router. **** Executables in ocean/bin/ INSTALLATION prints OCEAN installation instructions on stdout. buildsrc compiles OCEAN sources with specific "make" parameters. dist distributes OCEAN executables to shadow trees. rmsdflock removes (blasts) the locks from a seadif database. seatail temporarely shows output from a sea-of-gates tool. thearch prints a value for the MACHINE environment on stdout. **** Executables in cacd/bin/ addproj adds a project to the list of imported projects. arrexp expands the arrays in an SLS commandfile, used by "simeye". ccif compiles CIF data format into the nelsis database. cga converts GDS-II data format to ASCII. cgi compiles GDS-II sources into the nelsis database. cig converts info from the nelsis database to GDS-II format. clambda changes the lambda value of a design project. cldm compiles LDM (= layout description language) into the database. csls compiles SLS (= circuit description language) into the database. dbcat lists the contents of cells that are in the nelsis database. dbclean removes data from the database that can be regenerated. dblist lists the contents of the nelsis database. exp expands a layout cell (generate derived data from it). func_mkdb creates a functional ("behavioral") simulator. getepslay converts a layout cell to PostScript suitable for printing. impcell imports a cell from another project (see also "addproj"). layflat removes all hierarchy from a layout cell. macro sets or unset a macro status for a layout cell. makeboxh expands a layout cell hierarchically to boxes (see "exp"). makeboxl expands a layout cell linearly to boxes (see "exp"). makegln creates a non-vertical line segment representation (see "exp"). makevln creates a set of "_vln" data files (see "exp"). mkpr creates a nelsis project (see "mkopr"). mplot makes a plotfile for a masklayout. nspice front-end for spice-2 and spice-3, used by "simeye". nspice_bs pre-processor for spice-2 and spice-3, used by "simeye". nspice_pp post-processor for spice-2 and spice-3, used by "simeye". outgds puts GDS II-formatted files on tape. putdevmod puts a device model description into the circuit database. putspice compiles a SPICE network description into the database. readgds reads GDS II-formatted file from tape. rmdb removes cells from the nelsis database. rmpr removes a nelsis design project. setcmap manipulates the X-window colormap for nelsis and OCEAN tools. simeye interactive switch-level and spice simulator for X-windows. sls switch-level simulator, used by "simeye". sls_exp pre-processor for "sls". sls_mkdb compiles SLS source into the database, see "csls". space layout-to-circuit extractor. tecc technology compiler for "space". xcif extracts CIF format from the layout database. xcmk extracts CIRCUITMASK format (Philips) from the layout database. xedif extracts EDIF format from the circuit database, see "cedif". xldm extracts LDM format from the layout databse, see "cldm". xsls extracts SLS format from the circuit database, see "csls". xspice extracts SPICE format from the circuit database, see "putspice". 7. CONTENTS OF THE PUB/OCEAN DIRECTORY =================================== 7.1 The CACD distribution --------------------------- You must retrieve one of the hardware dependent trees containing the cacd executables: ** cacd_bin_PA-RISC1.1.tar.gz (approx 4.5 Mbyte) ** cacd_bin_i486_Linux.tar.gz (approx 3.0 Mbyte) ** cacd_bin_sun4_4.tar.gz (approx 5.2 Mbyte) ** cacd_bin_sun4_5.tar.gz (approx 1.6 Mbyte, dynamically linked) and the hardware independent part containing process information and manual pages: ** cacd_process.tar.gz (approx 0.7 Mbyte) Alternatively, you can attempt to compile the cacd sources on your own hardware platform, see section 8.6 below. 7.2 The OCEAN binary distribution --------------------------------- The OCEAN binary directory containing all the sea-of-gates programs. Retrieve one of: ** ocean_bin_PA-RISC1.1.tar.gz (approx 1.9 Mbyte) ** ocean_bin_i486_Linux.tar.gz (approx 1.0 Mbyte) ** ocean_bin_sun4_4.tar.gz (approx 2.1 Mbyte) ** ocean_bin_sun4_5.tar.gz (approx 1.7 Mbyte, dynamically linked) Alternatively, you can attempt to compile the ocean sources on your own hardware platform, see section 8.5. 8.3 The OCEAN cell libraries ---------------------------- We distribute a simple cell library that you can use in your sea-of-gates chip. This archive also contains the cell library "primitives" that describes the primitive electric elements (transistors, capacitors, et cetera). Some OCEAN tools don't run without it. It also contains the image description file "image.seadif" for all supported master images, and it contains the tutorial tree. ** ocean_celllibs.tar.gz (approx 1.1 Mbyte) 8.4 Full documentation of OCEAN ------------------------------- Documentation for the OCEAN tools and a tutorial, in postscript form and the on-line manual pages. ** ocean_docs.tar.gz (approx 1.1 Mbyte) 8.5 Source code of ocean ------------------------ The sources of the OCEAN tools and libraries. This also contains Makefiles and a script "src/scripts/buildsrc" that knows about MAKE parameters for HP and Sun computers, as well as parameters for a the GNU gcc/bison/flex environment. You can compile Ocean to work with Nelsis release 4 by specifying the option "-4" to buildsrc. Type "src/scripts/buildsrc -h" for a list of options and examples. In directory pub/ocean/ocean_src: README gnarp.tar.gz makebus.tar.gz seedif.tar.gz blif2sls.tar.gz libocean.tar.gz nelsea.tar.gz trout.tar.gz cruise.tar.gz libseadif.tar.gz scripts.tar.gz esea.tar.gz madonna.tar.gz seadali.tar.gz The README contains instructions on how to compile and install the Ocean sources. 8.6 Source code of cacd ----------------------- All sources of the binaries in the cacd/bin/$MACHINE directory. This includes sls, simeye, space, etc. With sources comes a file src/INSTALLATION that contains instructions on how to compile and install the nelsis sources. ** cacd_src.tar.gz (approx 0.8 Mbyte) 8.6 Release information ----------------------- Contains the date-stamps of the tar-files in the distribution ** release_info/ 3. SUPPORTED MASTER IMAGES ======================= The OCEAN tools can handle almost any sea-of-gates master image that you can think of. All tools read the information concerning the topological and electrical properties of the image from an ascii image description file. If you have designed an image of your own, it is usually not more than a few hours of work to create an image description file for it. To illustrate how generic the tools are, the standard OCEAN installation comes with three radically different master images named "fishbone", "octagon" and "gatearray". The fishbone master image is the one that we almost exclusively use ourselves, because it is reasonably fast (1 ns gatedelay) and our foundry DIMES can process the fishbone image in sufficient quantities. It is a 1.6 micron, 2-metal layer CMOS process. The fishbone master images that we have in stock contain about 200,000 transistors. The octagon master image was designed at Twente University. It allows the designer to mirror and rotate her cells in many ways. It uses a 0.8 micron, 3-metal layer CMOS process. Unfortunately, we do not have the means nor the money to process octagon designs. The gatearray master image is an old fashioned 4 micron, 1-metal layer gate array. It uses the gate array concept of predefined wiring channels. We sometimes use this image for designs of low complexity, where a high-speed operation is not decisive. 'EOF'