#
# @(#)INSTALLATION 1.34 08/26/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 or 486 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_<your-machine>.tar.gz, 
   cacd_process.tar.gz
   ocean_bin_<your-machine>.tar.gz
   ocean_celllibs.tar.gz  
   ocean_docs.tar.gz  

<Your-machine> is 'PA-RISC1.1_8' or 'sun4_4' or 'i486_Linux', depending on
your hardware. 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 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:

<anywhere>/cacd                   (place of nelsis system = $ICDPATH)
-- extracted from from archive 'cacd_bin_<your_machine>.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)

<anywhere>/ocean                  (place of ocean system = $OCEANPATH)
-- extracted from from archive 'ocean_bin_<your_machine>.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).

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 <your_screen>: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'
