

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.

If you have a web browser, the best way to learn about what
Log 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.

---------

The Log System 
--------------


Log is a circuit schematic capture tool and simulation environment,
written by Dave Gillespie. Highlights of the Log system include: 

Schematic capture 
   Log supports schematic entry for documentation, simulation,
   and netlist creation. Schematic printouts can be previewed
   on-screen, and encapsulated Postscript and HPGL output file
   formats are supported. In addition, the input file format for the
   Chipmunk graphics editor Until is supported. 
Netlist generation 
   Log can generate SPICE netlists for circuit schematics; Log can
   also generate NTK format netlists, also generated by the
   Chipmunk VLSI layout tool Wol . Log supports hierarchial
   netlist generation. Using Log, Wol, and Netcmp (a netlist
   comparison tool included in the Chipmunk supplementary 
   toolkit), 50,000 transistor IC designs have been verified for
   layout-vs-schematic netlist equality. Alternatively, IC
   designers can use Log to generate SPICE schematics, to support
   netlist verification of layout generated with Magic; Gemini is
   often used as the netlist comparison tool in this situation. 
   Freely redistributable tools are now available for generating Xilinx
   XNF format netlists from Log netlist outputs. 
Simulation data visualization 
   Log includes a simulator-independent service for graphically
   viewing and measuring simulation data, supporting an arbitrary
   number of traces. The service generates output data suitable for
   input to the commercial tool MATLAB, and to the Chipmunk
   data plotting tool View . In addition, a simple plotting tool is
   integrated into the data visualization system, supporting
   Postscript and HPGL formats, and the file format for the
   Chipmunk graphics editor Until . 
Analog circuit simulation 
   Log includes a full-featured analog circuit simulation package, 
   Analog, written by John Lazzaro. Circuit schematic editing and
   parameter adjustments can occur while the simulator is in
   operation, supporting the metaphor of a virtual lab workbench.
   Model components include MOS transistor models optimized
   for accurate simulation in the weak-inversion regime, and
   macromodels of several of the circuits featured in Carver
   Mead's book Analog VLSI and Neural Systems. Circuits of 64
   nodes or less can be reasonably simulated in analog; hierarchial
   simulation is not presently supported. 
Digital circuit simulation 
   Log includes a unit-time-delay digital circuit simulation
   package, Diglog, written by Dave Gillespie. Circuit schematic
   editing and parameter adjustments can occur while the
   simulator is in operation, supporting the metaphor of a virtual
   lab workbench. Circuit libraries include many 7400-series TTL
   parts, and hard macros for early Actel FPGAs. Hierarchial
   simulation is supported. Third-party tools support XNF creation.
Custom gate creation 
   The log package includes a standalone gate editor, Loged, for
   creating custom gate icons. The simulation code for simple
   digital gates can be embedded during gate description using
   loged; complex digital gates and simulation code for analog
   circuits requires separate C code. Loged can also generate
   data-sheets showing gate symbols and attributed, the the
   Postscript format. 

Log is the most popular Chipmunk tool, and has founded many uses in
academia and industry. Log can serve as a cost-free alternative to
commercial tools like ViewLogic, for users with simple needs.
Integrated circuit designers use it as an inexpensive tools for netlist
creation; educators use it for introductory digital logic courses;
weak-inversion MOS circuit designs use it to simulate small circuits. 

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

The Chipmunk tools require an ANSI c compiler (typically GCC) and X11
(R4, R5, or R6).  Monochrome, 8-bit, 16-bit, and 24-bit per pixel
color displays are supported; however, 16-bit and 24-bit color modes
have only been tested on PC platforms (X11 under Linux and OS/2). 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, AU/X. 
   Apple Macintosh, MachTen
   DEC MIPS-based DECstations 
   DEC Linux/Alpha. OSF/1(Digital Unix) not tested, but may also work. 
   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/x86. 
   IBM RS/6000. The IBM xlc compiler is known to compile
   Chipmunk; gcc has not been tested. 
   SGI, Irix 5.2/5.3, gcc or cc.. 
   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. Here are the
     requirements for Log:

     WARP Connect.

     The PMX server (The X Window System for OS/2) About $140 US, availible
     from Indelible Blue, 800-776-8284.
 
     The icc compiler, and nmake. Not known if gcc will work also, please
     let me know if you try gcc. 

Binary distributions have been built by third-parties for the
following architectures. Contact the authors for additional
information.

IBM PC-Compatibles, MS-DOS. Luigi Rizzo's group at the Universita' di
Pisa, Italy, has been working on an MS-DOS port of analog. Compiled
with djgpp, uses xlibemu and fvwm to provide an interface similar to a
virtual window manager under X with Motif-like widgets. See his home
page for current status; there may be an early-alpha version of a
binary available for evaluation (see "Materiale didattico" section).
(http://www.iet.unipi.it/~luigi/) 

Amiga. Marco Gigante (se62@galileo.iet.unipi.it) has created a binary
distribution for the Amiga, which uses the ADE X or AmiWin X
server. These binaries are available on the Aminet server
(ftp://ftp.wustl.edu/pub/aminet/misc/sci/), for several hardware
configurations. Binary filesets ChipMunk*.lha, log*.lha, view*.lha,
until*.lha, wol*.lha, contain the distributions for Chipmunk, Log,
View, Until, and Wol respectively.

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.

Absent from this list are the following popular platforms. 

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

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

Apple Macintosh, MacOS. No ports are in progress, to my knowledge. However,
MachTen does run as a process on top of MacOS. 



To get log 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 log.


INSTALLING LOG VERSION 5.64 
---------- --- -------

Compiling Log 
-------------

This document assumes that you have successfully compiled the Psys 
libraries. This document also assumes that you have uncompressed and
untarred the Log file, and installed it in the chipmunk directory. 

Begin by descending to the log/src directory. At this point OS/2
users only should execute the following commands. 
      ----

cp Makefile.os2 Makefile 

cp ana/Makefile.os2 ana/Makefile 

All users should now edit the files Makefile and ana/Makefile,
and make any necessary changes. Comments in the Makefile will guide
you through these changes; the changes are labeled with the markers
(1), (2), (3), etc. 

Once these edits are made, check to see if your platform is listed
below. If it is, execute the command under the platform name in the 
log/src directory. 

Apple Macintosh, AU/X 
   cp munch.coff munch 
HP Series 700, HPUX 
   cp munch.hp800 munch 
IBM RS/6000 
   cp munch.rs6000 munch 
Sun SPARC, Solaris 2.X (SunOS 5.X) 
   cp munch.solaris2 munch 

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. This will
create the programs chipmunk/bin/diglog, chipmunk/bin/analog, and
chipmunk/bin/loged. To check basic functionality, try to run these
three programs. For each program, two windows should appear on program
launch, one called newcrt and one called mylib. Type :exit in the
newcrt window to leave analog and diglog. Type exit in the newcrt to
leave loged. See the user documentation for information on using these
tools.

Problems and Solutions 
----------------------

Its quite possible that compilation did not proceed smoothly, or that
execution problems happen while using the tool. Here are some
possible ways that things could have went wrong, along with
suggestions. 

Log comes up in monochrome -- too few colors available 

   This symptom could indicate several conditions. If you display
   hardware has less that 4 bits per pixel, Log can't use the small
   number of colors available effectively, and reverts to monochrome
   display. If your display has greater than 4 bits per pixel, perhaps a
   color-hungry program (like Netscape) is monopolizing the colormap. To
   test this hypothesis, exit Netscape then restart Log. See the Netscape
   FAQs for information on improving the color-allocation manners of the
   program.

Log comes up in monochrome -- too many colors available 

   Log now has code to handle displays with 16 bits per pixel and 24 bits
   per pixel. However, this code hasn't been extensively tested on many X
   servers, and may be buggy. See the final section of log/lib/log.doc for
   for information on working around these bugs. Alternatively, try
   switching your display driver to 8 bits per pixel" mode.

File system problems 
   The symptom is that Log runs fine for a few days (weeks,
   months), but one day it stops working. Another symptom is that
   Log runs on the machine it was compiled on, but not on other
   machines in a NFS cluster. The cause of these problems often
   traces to Log noting where its absolute location is during
   compile time, using pwd commands in its Makefiles. If your
   disk is reorganized, Log will be confused, and recompilation
   (Psys and Log) 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. 

log.c won't compile 
   This file breaks many compilers because of its length, in many
   different ways. Possible solutions include compiling with or
   without optimization on, and directing the compiler to place
   temporary files in a disk partition with more free space. 

Print spooling is broken 
   Pressing File in the Log preview screens should send a
   Postscript file to a local printer, by writing a file to /tmp, and
   printing the file using lpr. This may be incorrect for your
   system. If so, change line 2868 (Unix) or 2865 (OS/2) of the file
   log/src/lplot.c to conform to your environment. 

Problems finding libraries or include files 
   Some OS installations don't have X11 or other needed libraries in
   the include path and/or the linking path. Look in the Makefile for
   tips on solving this problem, at the definitions of LIBX11 and
   XINCLUDEDIR. 


If these suggestions don't help you compile Log, 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. 

			    USING LOG
                            ---------

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

webdoc/document/log/index.html

----

If using the Webdoc documention isn't practical, most of the contents
of the Webdoc log pages are contained in the following files in 
log/lib/*

log.doc: The log reference manual. This is also the document that pops
up when you press HELP in log. Eventually, I'll replace this HELP action
with running a web browser, in a later release.

analog-man.ps: Michael Godfrey converted parts of the Log manual into
a guide for analog simulation users, in Postscript

mos.ps: Michael Godfrey also wrote an excellent paper describing
the MOS models used in analog, also in Postscript. 

lesson*.lgf: A series of 5 annotated circuit schematics,
log/lib/lesson1.lgf through log/lib/lesson5.lgf, form an interactive
way to learn about Analog by using Analog. Developed by Dave Gillespie. 

cheat.text: A set of 28 tips for the novice Analog user. Most ways
novices get stuck while learning Analog are in this guide, written by
Dave Gillespie. 

analog-tr.ps: For information on how the simulation engine in analog
works, see this Postscript document by John Lazzaro -- note the
transistor models described in this document are no longer used in
analog. The models described are the obsolete NFET4 and PFET4 gates,
included in analog only for backwards compatibility.

New Features
------------

	Aside from the new supported machines, there were many little
fixes and additions to Log. Here is a partial list:

[March 1997]

Support for 16/24-bit displays. TrueColor mode is now
supported. Chipmunk programs autoconfigure by default; an environment
variable (LOG_COLOR = bw | 8bit | 16bit | 24bit) forces a particular
depth (Michael Godfrey, Stanford University).

New MOS models. New MOS transistor gates. (Michael Godfrey, Stanford
University).

Scope improvements. Edge-triggered scope function now works in Diglog
(Bob Moniot, Fordham College at Lincoln Center).
 
Lplot Enhancements. New Lplot commands (PSFILE and FILE) allow
specification of printer and file names (Tobi Delbruck, Caltech and
Tim Edwards, Johns Hopkins). Lplot command HEADER now works correctly
(Michael Godfrey, Stanford University).

TO/FROM Enhancement. TO/FROM gate editing improved (Tim Edwards, Johns
Hopkins).

Bug fixes. Memory leak fixed in digital hierarchial simulation
(Olivier Teman, Versailles University); reset operation fixed for
several analog gates (Joel White, Tufts University).


[May 1996]

     Diglog schematic corruption bugfix. A
     major bug that caused Diglog to
     occasionally core dump on large
     hierarchial circuits has been fixed; Diglog
     is safer to use for larger projects. [Ingo
     Cyliax (U. Indiana), Lars Larsson
     (Hamburg U.), Dave Gillespie] 

     Lower load-averages for Log. Log no
     longer runs a unity load average
     indiscriminantly. If simulation is turned
     off, an analog circuit is "incomplete," or a
     diglog circuit is the null schematic, Log
     will consume few cycles if the user isn't
     interacting with the program. [Nick
     Bailey (U. Leeds, UK), Dave Gillespie] 

     Analog gate improvements. Bugs in
     the NPN1 and PNP1 bipolar transistors
     were found and fixed [Jamie Honan,
     Australia] as were bugs in the Diode gate
     [Shudi Gu, Beijing]. 

     XNF file support. New tools for
     supporting Xilinx designs [Ingo Cyliax (U.
     Indiana)]. 

     Log display support. When launched on
     a machine with inadequate or
     unsupported display hardware, Log
     reverts to monochrome display instead of
     core-dumping [Huiling, CSU Fresno]. 

     Diode gate model. New document
     explaining the diode gate model in analog.
     [Jamie Honan, Australia] 

     Making new Analog gates New
     document on adding new gates to
     Analog. 

     MachTen. Analog now runs under
     MachTen, a BSD for MacOS. [James
     Yang, UC Davis] 

     MS-DOS Alpha release available for
     the MS-DOS port of Log [Luigi Rizzo
     and collaborators, University of Pisa,
     Italy]. http://www.iet.unipi.it/~luigi/


[Feb 1995]

Postscript updates. All Chipmunk tools now produce encapsulated
postscript that is compatible with the psfig macros distributed with
TeX. John Platt and Dave Gillespie of Synaptics, Michael Godfrey at
ISL, Himanshu R. Pota of ADFA in Australia, and
gary@minster.york.ac.uk contributed to these improvements.

Logspc updates. Harold Levy of Caltech contributed a new version of
Logspc, the SPICE netlist tool for Log, that contains new features and
bug fixes.

MATLAB support. Michael Godfrey of ISL contributed a filter program
for converting data files produced by Log into files suitable for MATLAB. 
It is part of the Supplementary Toolkit: pick up util1.0.tar.gz to
get the toolkit.

Major DigLog bugfix. Micah Beck of the University of Tennessee helped
trace down a major bug in DigLog, that was responsible for schematic
corruption of large files. Many users were bitten by this bug in the
past. Until new users report back, we won't know for sure if this
change completely solves schematic corruption for large designs when
DigLog simulation is occuring: it's hard to test for bugs that only
occur only in large designs.


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



