ABOUT THE PROGRAMS
------------------

This is a printed circuit board cad package. It consists of the following
programs: a rat nester, an autorouter, a board viewer, a board printer, a
postscript filter, a file packer (two kinds), and a file unpacker. The
following comment appears in each of the main programs (pcb*.c):

** you may give this software to anyone, make as many copies as you like, and
** post it on public computer bulletin boards and file servers. you may not
** sell it or charge any fee for distribution (except for media and postage),
** remove this comment or the copyright notice from the code, or claim that
** you wrote this code or anything derived from it. you may modify the code as
** much as you want (please document clearly with comments, and maintain the
** coding style), but programs which are derived from this one are subject to
** the conditions stated here. i am providing this code so that people can
** learn from it, so if you distribute it, please include source code, not
** just executables. contact me to report bugs or suggest enhancements; i do
** not guarantee support, but i will make an effort in good faith to help you,
** and i want to act as a central clearing house for future versions. you
** should contact me before undertaking a significant development effort, to
** avoid reinventing the wheel. if you come up with an enhancement you
** consider particularly useful, i would appreciate being informed so that it
** can be incorporated in future versions. my address is: Randy Nevin,
** 1731 211th PL NE, Redmond, WA 98053. this code is available directly from
** the author; just send a floppy and a self-addressed floppy mailer with
** sufficient postage.

What I intend this to say is that you can do anything you want with these
programs with the following conditions: (1) you can't sell it or anything
derived from it for profit, and (2) you must give me credit. I do not use the
terms 'shareware', 'freeware', or 'public domain' to describe these programs,
since currently accepted definitions for them do not match my intentions.
These programs are absolutely free.

WHAT THEY DO
------------

The rat nester reads a circuit description, and displays the circuit as a rat
nest, showing the holes and straight lines connecting the specified holes,
without regard to where traces cross. (This program is useful for helping the
designer decide where the components should be located, based on the
connections between them. Minimizing the overall distance of the traces to be
routed can dramatically improve autorouting speed.)

The autorouter reads a circuit description, routes the traces, and outputs the
routed printed circuit board to a file.

The board viewer can read this file and display an image of
the 2-sided board on an EGA monitor.

The board printer can also read this file, and produces board image files of
various resolutions. The board image files can then be sent to a
Hewlett-Packard laserjet II laser printer to get hard copy. The board printer
can also produce vector-oriented board image files which are human-readable,
and should be easily translatable into various graphics printer languages,
such as postscript and hpgl.

The postscript filter is one such translator, and produces postscript output
from the vector-oriented board image.

The file packer and unpacker can be used to save disk space; since board
images usually consist of just a few kinds of bytes, compression rates of 80%
are not uncommon. The file packer and unpacker are intended to compress large
board images, but in fact will work on any file (though the savings are
greatest for files consisting of just a few kinds of bytes).

There are actually two kinds of file packers, but the unpacker can handle
either kind of compression. The first file packer (pcbpak1) uses huffman
encoding down to the bit level, and the second file packer (pcbpak2) uses
run-length encoding at the byte level. I suggest you try each, and use the
one that results in the greatest savings (this will vary according to the
input file).

I initially supported the EGA and the HP laserjet II because they are what I
have access to. Shortly after the first release, a user donated the postscript
filter. Other users will want support for different display adapters (VGA,
Hercules..) and printers. If you have one of these and are ambitious enough to
enhance the programs to work with it, I hope you'll contact me so your work
can be shared with others.

COMPILING THE PROGRAMS
----------------------

A makefile is included which compiles and links the programs. It is written
for the Microsoft C 4.0 compiler and Microsoft MASM 4.0 macro assembler, but
should be easily adaptable to whatever compiler/assembler you have. (This is
an example of an enhancement that others would like to share.) The two rules:
.c.obj:
cl /G2s /Oat /W3 /Zp /c $*.c
.asm.obj:
masm /t /ml $*.asm;
describe compiling and assembling. /G2s allows the compiler to emit 286
instructions, and to omit stack-checking code; if you will be running on an
8088-based machine, you should use /Gs instead (omit the 2). /Oat is
optimization, and is optional. /W3 is a warning level, and is optional. /Zp
causes structures to be packed, and is optional (omitting it could cause the
programs to use more memory). /c keeps the compiler from initiating a link for
each module. /t causes MASM to use terse mode, and is optional. /ml causes
MASM to maintain the case of names (don't automatically uppercase them), and
is required.

RUNNING THE PROGRAMS
--------------------

All the programs except the postscript filter (pcbpsplt) require command line
arguments, and if you forget what they are, just execute the programs with no
arguments. They will give a usage clause describing what arguments are needed.

For pcbrat.exe there is one argument: the input (circuit description)
filename. For pcbroute.exe there are two arguments: the input (circuit
description) filename, and the output (board description) filename. For
pcbview.exe there is one argument: the input (board description) filename.
For pcbprint.exe there is one required argument, the input (board description)
filename, and up to six optional arguments: /P indicates portrait mode (the
circuit board is printed right-side up), /L indicates landscape mode (the
circuit board is printed sideways), /Rn indicates laser printer resolution (n
is 75, 100, 150, or 300 dots per inch), and /Zm indicates the zoom factor (m
is 0, 1, 2, or 3). /H selects hp laserjet output; it is the default, and
causes the four switches above to be accepted. /V selects vector-oriented
output; if it is selected, no other switch is accepted. Vector-oriented output
consists of DIMENSION, LINE, and CIRCLE statements; read the comments in
pcbprint.c if you are trying to produce output for a postscript printer. They
explain these statements. Refer to readme.ps for how to use pcbpsplt.exe. For
pcbpak*.exe there are two arguments: the name of the file to pack, and the
name of the output file. For pcbunpak.exe there are two arguments: the name of
the file to unpack, and the name of the output file.

INPUT FORMAT
------------

The file called EXAMPLE is an example input file. It defines (a) the
dimensions of the circuit board, which are 29 rows and 37 columns (think of
this as a matrix of cells), (b) a chip type (the 7486, which has 4 XOR gates),
(c) holes where power and ground will be applied, (d) holes where the input
will be applied, (e) the hole where the output will appear, (f) four instances
of the 7486 chip, and (g) the pairs of pins that must be connected to complete
the circuit. For a complete description of the input format, read the large
block comment at the beginning of file IO.C.

THE FILES
---------

MAKEFILE-- describes how to compile, assemble, and link the programs
BITMAP1.H-- bitmaps for various cell types
BITMAP2.H-- more bitmaps
BITMAP3.H-- yet more bitmaps
CELL.H-- cell types and other global constants
ALLOC.C-- memory allocation routine
BITMAP.C-- bitmap data structure definitions
BITMAP1.C-- bitmap data structure definitions (holes only)
BOARD.C-- routines to initialize the board, and access cells
DIST.C-- distance calculation routine
IO.C-- input format processing routines
LINE.C-- routine to draw lines
PCBPAK1.C-- main routine for file packer (first kind)
PCBPAK2.C-- main routine for file packer (second kind)
PCBPRINT.C-- main routine for board printer
PCBPSPLT.C-- main routine for postscript filter
PCBRAT.C-- main routine for rat's nester
PCBROUTE.C-- main routine for autorouter
PCBUNPAK.C-- main routine for file unpacker
PCBVIEW.C-- main routine for board viewer
QUEUE.C-- routines to manipulate the search queue
SOLVE.C-- main search routine (using the A* algorithm)
WORK.C-- routines to manipulate the work list
PCBPAK1.EXE-- compiled version of file packer (first kind)
PCBPAK2.EXE-- compiled version of file packer (second kind)
PCBPRINT.EXE-- compiled version of board printer
PCBPSPLT.EXE-- compiled version of postscript filter
PCBRAT.EXE-- compiled version of rat's nester
PCBROUTE.EXE-- compiled version of autorouter
PCBUNPAK.EXE-- compiled version of file unpacker
PCBVIEW.EXE-- compiled version of board viewer
UTIL.ASM-- assembly language graphics helpers
ARTICLE-- text of magazine article submitted to Dr. Dobb's Journal.
when (if?) this is printed, it will be in the second half
of 1989, and some of the wording may be changed. Some
figures referred to in the article are not available, but
hopefully enough material is there to help you understand
what autorouting is and how it works.
ASTAR-- the A* search algorithm
ASTAR.C-- C pseudocode for the A* search algorithm
BFS-- the Breadth-First search algorithm
EXAMPLE-- the example input file
TTL.INC-- include file which includes all of the TTL74*.INC files
TTL74*.INC-- ttl chip definition files. you may want to put all of them
in a subdirectory called TTL
README-- this file
README.PS-- descrition file for postscript filter

THE AUTHOR
----------

Randy Nevin, 1731 211th pl ne, redmond, wa 98053

PCBPSPLT
--------

Dave Schmidt has contributed a filter program to take the vector-oriented
output of pcbprint.exe and translate it into postscript. It is called
pcbpsplt (PostScript PLoTter). See the readme.ps for directions on using it.
The pertinent files are: pcbpsplt.c, pcbpsplt.pro, pcbpsplt.epi, and
readme.ps.