
This is wolcomp, a simple cell compiler written by Mass Sivilotti and
Carver Mead and maintained under Unix by John Lazzaro. Wolcomp is
distributed under the GNU General Public License; see file COPYING in
this directory for more information.

If you have a web browser, the best way to learn about what Wolcomp is
and how to install it is to pick up the latest version of the webdoc
Web pages (webdocX.XX.tar.gz, where X.XX is a version number) from the
same place you picked up this file. Once you have this Web tree
untarred, point your Web browser (examples of Web browsers include
Mosaic, Lynx, Netscape, and tkWWW) to webdoc/index.html for the home
page of the Chipmunk tools, and to webdoc/compile/compile.html for
compilation instructions.

The rest of this file is written assuming that you don't have access
to a Web browser -- all text is copied from webdoc pages
verbatim. I'll do my best to keep this file up to date, but the Web
tree is now the primary documentation for all aspects of the Chipmunk
system.

---------

Wolcomp
-------

Wol is a graphical environment for IC mask layout. Wolcomp is a simple
cell compiler, embedded in C, for the compilation of leaf cells generated
by Wol into a complete chip. The original versions of Wol and Wolcomp
were written by Carver Mead; the version included in the Chipmunk
package was primarily written by Massimo Sivilotti, with major
contributions by Glenn Gribble. The name Wol originates from the
children's book Winnie the Pooh. Features of Wolcomp include: 


Cell composition 
   Wolcomp, a simple cell compiler embedded in C, supports
   composition of leaf cells drawn by Wol under program control,
   allowing the construction of parameterizable macrocell generators.
   Wol includes an full-featured viewer of Wolcomp compositions
   that also supports manual composition; however, manual
   composition in Wol is rudimentary and not suitable for large
   manually-composed designs. 

Wol and Wolcomp have relatively few users, due to the popularity of
Magic and the commercial tool LEdit. Some users do use Wol extensively
to create IC designs for fabrication through MOSIS; I have designed over
20 chips using Wol and Wolcomp since the Unix port of the Chipmunk
tools, using Magic for auxiliary DRC purposes only. For some users, the
advantages of cell compilation outweigh other issues. 

Platforms and Requirements 
--------------------------

The Chipmunk tools require an ANSI c compiler (typically GCC) and
X11 (R4, R5, or R6). Color displays with 8 bits per pixel work best for
Chipmunk (other than 8bpp can be problematic), although Log supports
black-and-white displays. An HTML browser (like Mosaic or Lynx or
Netscape) is also necessary to access the Chipmunk documentation.

These are the currently supported platforms, with details of
platform-specific requirements: 

   AmigaOS. Requires ADE X or AmiWin X11. 
   Apple Macintosh, OS/X and AU/X. 
   DEC MIPS-based DECstations 
   HP Series 300/400, HPUX. 
   HP Series 700, HPUX. The HP-supplied cc, with extra-cost
   ANSI option, will also compile Chipmunk. 
   IBM PC and Compatibles, FreeBSD. 
   IBM PC and Compatibles, Linux, Slackware. 
   IBM RS/6000. The IBM xlc compiler is known to compile
   Chipmunk; gcc has not been tested. 
   SGI. Chipmunk known to work on Indigo and Challenge, no
   others were tested. The SGI cc is recommended. 
   Sun SPARC, Solaris 1.X (SunOS 4.X). 
   Sun SPARC, Solaris 2.X (SunOS 5.X). 
   IBM PC and Compatibles, OS/2. 


     OS/2 Requirements 

     Only the Log system (diglog, analog and loged) is ported. However,
     porting Log meant porting Psys: if you are an OS/2 user who is 
     interested in porting Wolcomp, the Log port gives you a good head
     start.

     Here are the requirements for Log:

     The icc compiler. Not known if gcc will work also, please let
     me know if you try gcc. 

     OS/2 with TCPIP and X11 (PMX). OS/2 revisions 2.1 and higher
     should work, but all current testing has been done using WARP.
     TCPIP version 2.0 with the "latest CSD's" to the Base kit is also
     needed, as is the X-server (PMX) kit. 


If your configuration is different than the ones described above,
only take the package if you feel confident in your C/Unix abilities
to do the porting required. If you do successfully port to a new
architecture or OS, send us the changes required, and we will
incorporate your port in the next release of the chipmunk tools.

Here is the know status of Chipmunk on popular platforms not currently
supported

   IBM PC-Compatibles, MS-DOS or Windows. Several failed
   porting attempts have occurred. However, a new porting effort
   is underway by a group in Europe. Contact me for details.

   IBM PC-Compatibles, NextStep. No ports are in progress, to
   my knowledge. 

   Apple Macintosh, MacOS. No ports are in progress, to my
   knowledge. 

   DEC Alpha, OSF/1 or VMS. Several Alpha ports have failed,
   because of 64-bit compatibility problems with binary file I/O. I
   don't think the port is impossible, just more difficult than the
   successful ports listed above. 

To get wolcomp running, first bring over a copy of psys-Y.YY.tar.Z (where
Y.YY is a version number), available at the same place this file was
found. Untar and make psys per instructions in the package.  After
psys is installed, you can start to install wolcomp.


Compiling Wolcomp
-----------------

Compiling Wolcomp 

This document assumes that you have successfully compiled the Psys 
libraries. This document also assumes that you have uncompressed and
untarred the Wolcomp file, and installed it in the chipmunk directory.
Note that Wolcomp has not been ported to OS/2.

Begin by descending to the wolcomp directory. Edit the file 
Makefile, and make any necessary changes. Comments in Makefile
will guide you through these changes; the changes are labeled with the
markers (1), (2), (3), ect. Once these changes are made, execute the
command 

make install 

If things are working correctly, a long series of compilations,
linkings, and file movements should occur without error. The Wolcomp
library wolcomp.a is now ready to be included in cell compilers. To
learn more about using wolcomp, see the user documentation.

If you have problems compiling wolcomp, I'd be happy to offer
suggestions.Send email to lazzaro@cs.berkeley.edu and include the
following information.

   Complete machine configuration, including machine type, OS
   revision, compilers, and X servers. 

   A listing of the output from the failed compilation process, or
   any messages printed by a Chipmunk program or the OS or X
   when an error occurs.
 
   Details of any changes you have made to the distribution before
   this compilation. 

   The effects of following any advice given in the compilation
   instructions. 


Documentation for Wolcomp
-------------------------

All of the documentation for using Wolcomp is included in the webdoc
package. See:

webdoc/document/wol/index.html

----

If using the Webdoc documention isn't practical, then you can 
directly look at the complete Postcript manual for wol, included
as wol/wolman/wol.ps. The wolman directory also includes complete
TeX source for this manual. Wolcomp is explained as a section of
the Wol manual.

To help understand how to use Wolcomp and Wol in a real
chip design, with the current version of the tools, serious users
will want to check out the examples package, which contains a
VLSI chip design done using Wol and Wolcomp. It's available the
same place you picked up the Chipmunk tools, as a tar file 
that has "example" in its title, probably examples.tar.gz.

Bug fixes and ports are the major additions to Wolcomp in this
release.


                                                --john lazzaro
