

This is log, a schematic editor, analog and digital simulator, and
netlist generator.  Log was written by Dave Gillespie; the analog
simulation capability was added by John Lazzaro.  Log is maintained
under Unix by Dave Gillespie and John Lazzaro.  Log is distributed
under the GNU General Public License; see file COPYING in this
directory for more information.

Log's purpose in life is aid in the simulation, verification, and
documentation of electronic circuits, in particular VLSI circuits.
To run analog, you need:

1) A unix workstation that runs X11r3, X11r4, or Openwindows
2) A color screen (some tools work with black & white screens, see below)
3) Gcc (for most platforms; see below)

This distribution has been built successfully by the maintainers,
using gcc 1.4X, on Sun Sparcstations, HP Series 300, HP/Apollo Series
400, and Apple Macintosh under AU/X. On Suns, 24-bit displays are not
presently supported. 

For these machines, gcc 1.XX is recommended at the present time (not
2.XX). However, in most cases the 2.XX will produce functional code,
if installing gcc 1.4X on your machine is not possible. This
distribution has been built successfully by the maintainers, on DEC
Ultrix MIPS-based machines, using gcc 2.2.2; on these machines gcc
1.XX is NOT recommended.

This distribution has also been built successfully by the maintainers,
using the HP cc compiler with the extra-cost ANSI-option, on HP Series
700/800 machines; presently (Oct 1992) gcc 1.xx and 2.xx do not handle
varargs correctly on these machines, but this hopefully will be
supported soon, and gcc can be used on these machines as well.
However, in some versions of HP compilers (8.05 and earlier), the file
math.c causes an internal compiler bug; if your version of the
compiler has this problem, you will need to compile this file
separately with gcc, while compiling all other files with cc.
Alternatively you can get a patch tape from HP.

This distribution has been updated with suggested changes from users
who have successfully ported the chipmunk tools to the IBM RS/6000
archiecture, using the xlc compiler, but the maintainers have not
tested the distribution on this machine.

The distribution has been built successfully under Linux, using gcc
2.3.3 and the xfree1.1 Xserver. 

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.

The C sources contain ANSI C prototypes in a few places, and several
source files are *very* large.  These two reasons prompt us to require
the use of gcc as the system compiler for most platforms. The specific
gcc version recommendations, as well as non-gcc compiler
recommendations, for different platforms, reflect the current bugs in
gcc versions and cc's on different machines.  If you don't have gcc,
but have an ANSI-standard compiler on your system, psys and the CAD
tools may compile.

To get log running, first bring over a copy of psys-1.10.tar.Z (or
the most recent version of psys), 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 log.


INSTALLING LOG VERSION 5.10 
---------- --- -------


To install log (5.10) on SUN, HP 300/400, or DEC MIPS machines,
follow the following steps.


  0.  The top-level distribution directory is referred to as "/usr/chipmunk"
      here.  You can actually install Chipmunk CAD in any home.  You
      should have been in "/usr/chipmunk" or your equivalent when you
      un-tar'd "log.tar".

  1.  "cd" into "/usr/chipmunk/log/src" and type "make install".
      This will create two copies of the program (actually links)
      called "/usr/chipmunk/bin/diglog" and "/usr/chipmunk/bin/analog".

  2.  Type "diglog" or "analog" to run the program.  These are linked to
      the same program, which uses the name you typed for it to find the
      appropriate ".cnf" file from "/usr/chipmunk/log/lib" to use.

Additional steps are needed for installation on the other supported
architectures. 

For AU/X machines, first execute the command

cp munch.coff munch

For HP Series 700/800 machines, first execute the command

cp munch.hp800 munch

For IBM RS/6000 machines, first execute the command

cp munch.rs6000 munch

In addition to this change, Makefile changes are needed for the HP
series 800, IBM RS/6000, linux, and AU/X machines. Comments in the
Makefiles in this directory and the ana/ directory will guide you
through these changes; the changes are labeled with the markers (1),
(2), (3), ect.

After these steps are taken, proceed to step 1. above.

If compilation does not proceed smoothly, see the suggestions in the
"IF COMPILATION DOES NOT PROCEED SMOOTHLY" section of the psys README
file. If these do not help, send email to lazzaro@cs.berkeley.edu and/or
daveg@synaptics.com, explaining your problem, and we will try to help.
In your correspondence, please include

(1) Complete machine configuration, including machine type, OS revision,
compilers used.

(2) A listing of the output from the failed compilation process.

(3) Details of any changes you have made to the distribution before this
    compilation.

(4) If applicable to your problem, the effects of the suggestions given
    above.

			    USING LOG
                            ---------

The directory log/lib contains several files to help you use log. The
complete manual is contained in the file log.doc, and a short "cheat
sheet" for starting with log is found in the file cheat.text. A postscript
version of a subset of the manual, suitable for analog simulation users of
log, is the file analog-man.ps; thanks to Mike Godfrey (Stanford) for
producting this manual.

Pressing the HELP button on the main screen of LOG creates an X
window with the log.doc manual. For users of analog, there are 5
"lesson" files in this log/lib, lesson1, lesson2, lesson3, lesson4,
lesson5, which act as a quick tutorial for using analog for
subthreshold MOS simulation. For using log as a tool in chip design,
we have prepared a separate examples distribution, available as the
file examples.tar.Z at the same ftp site you obtained this
distribution.

Printing schematics in log may need to be customized for your
particular installation.  On some systems the method of spooling
PostScript files may be different; out of the box, when pressing the
"File" command in the plotting screens, a spool file is made in /tmp,
and the the file is printed using the lp command. If things are
different in your system, change line 2863 in
"/usr/chipmunk/log/src/lplot.c" appropriately.  (The line contains the
string "/tmp/*.ps | lpr *").


	                New Features In Log
			-------------------

This section describes some of the new features in this revision of
log.

* Specifying Window Geometry in Your .Xresources File
  ---------------------------------------------------

This version of log looks in your .Xresources file for geometry
information.  If set properly, this allows windows of a certain size
to be automatically placed at a particular place at every invocation
of log; manual placement of windows is no longer necessary. This
feature was added by Jim Clark at Harvard. Adding these lines to your
.Xresources file:

mylib.geometry: =1150x550+0+0
newcrt.geometry: +510+586

will result in good placement and sizing for the color monitors
shipped with SPARC IPC's; for other screens, charge the numbers after
"+" signs for new positions, and change the numbers between the "x"
for modify the size of the mylib window. The newcrt window cannot be
modified; log expects it to be a fixed size.

Psys now senses if a display screen is black and white, and tries to
use stipple instead of colors. However, there are times where you want
to force the tools to display in black and white, even if the display
screen is color. These times include using an OS/2 based color PC as an
X terminal for the analog tools, because of present incompatabilities
between PC graphics cards and analog. To force a black and white display,
add this line to your .Xresources file:

mylib.color:  black_and_white

and then restart your X server. Black and white support was provided
by Tor Sverre Lande (Oslo), and the .Xresources flag was added by Mike
Godfrey (Stanford).

* Autowindow Mode
  ---------------

Typing :autowindow in log invokes a new window management mode. In
this model, whenever text input into the newcrt window is necessary,
the newcrt window automatically rises in front of any windows that
occlude it.  Once the window is no longer needed, it returns to its
previous condition. This allows users with small display screens to
place the mylib graphics window so it totally occludes the newcrt
screen; the newcrt window no longer wastes screen space. Typing
:autowindow a second time will disable this mode. This was contributed
by Gary Stafford at Apple and Mike Godfrey at Stanford.

* New, Supported, 4-terminal PFET gate
  ------------------------------------

A new transistor gate has been added to the library, PFET6, that has
4 terminals. The standard PFET5 gate assumes the well is tied to Vdd;
this model lets the user actively vary the well potential, and models
the effect of the well potental on Ids. Like PFET5 and NFET5, this model
is fully supported the the chipmunk maintainer (John Lazzaro), and any
functional bugs in the model should be sent to him.

* LOGSPC
  ------

A new command that generates spice netlists from schematics in analog.
This tool was derived from the logntk tool by Harold Levy at Caltech;
it works identically to logntk, except SPICE files are generated
instead of .ntk files. A manual section for log.doc has not been 
written yet; however, since the tool is identical in function to logntk,
the logntk section of log.doc should be sufficient for learning to use
logspc.  To invoke logspc, simply type :logspc at the command line.

New FET transistors models, NSPC1 and PSPC1, have been created by
Bhusan Gupta at Caltech for use with logspc. These transistors have 4
terminals, and allow explicit specification of W and L in microns.
These transistors also simulate in analog; however, the analog
maintainers are not supporting the simulation properties of this
model, and will refer bugs in these models to Bhusan.

* New quantum-well gate
  ---------------------

Harold Levy contributed the analog gate RTD, that simulates a 
resonant tunneling diode, a quantum well device.
 
* Piecewise-linear two-terminal gate
  ----------------------------------  
  
Harold Levy has also contributed the analog gate PWL, that simulates
as a two-terminal device with a user-specifiable i-v characteristic.

* Command line specification for X host
  -------------------------------------

The host machine for the display of X windows can be specified from the
command line; this is necessary for users of MacX, a server program for
MacOS. Here is an example of using this feature:

analog -x foo.myschool.edu:0.0

puts the mylib and newcrt windows on the machine foo.myschool.edu.
Contributed by Gary Stafford at Apple.

* Bug Fixes
  ---------

Logntk and logspc's "identify" mode now works; lplot's "zoom" mode now
works; .lfo backup files get created correctly. (Mark Smith, Sun, Tor
Sverre Lande, Oslo, Lloyd Watts, Caltech)


			PROBLEMS RUNNING LOG
			--------------------

Several common problems often occur when running log; here is a list
of problems I have seen before. If your problem is not on this list,
send email to lazzaro@cs.berkeley.edu and/or daveg@synaptics.com,
explaining your problem, and we will try to help.  In your
correspondence, please include your complete machine configuration,
including machine type, OS revision, compilers used, and the details
of any changes you have made to the distribution.

(P1A) Log runs fine for a few days (weeks, months), but one day it
stopped working. 

(P1B) Log runs on the machine it was compiled on, but not on other
machines in our cluster.

(S1) Log notices where its absolute location is during compile time,
using "pwd" commands in its Makefiles; the psys libraries also use
this method. If your disk is reorganized, log will be confused, and
recompilation will be necessary. Also, if your system uses the NFS
automounter, the results of the "pwd" command may not be correct for
every machine on your cluster, or may change with time. In this case,
replacing the "pwd" commands in the log Makefiles with hard-coded
paths, or with the environment variable PWD, is a good idea.

(P2) gcc -O log.c doesn't compile on a Sun.

(S2) This is a bug in gcc 2.XX; with some versions, -O2 will work,
     in other versions (sadly) optimization must be disabled.

NOTES
-----

This is a preliminary release of LOG.  It has recently been translated
from a different language and operating system, and a few bugs and
weaknesses arising from the translation process still remain.  See
also the LNOTES file containing a list of current known problems with
the Unix version.

Correspondence on LOG should be sent to daveg@synaptics.com and
lazzaro@cs.berkeley.edu.

  Thanks for using LOG!

							-- Dave Gillespie
							-- John Lazzaro



