TKGate User Documentation (Preface)

1. Introduction to TkGate

TkGate is a digital circuit editor and simulator with a Tcl/Tk-based interface. TkGate includes a large number of built-in devices including basic gates, memories, ttys and modules for hierarchical design. The simulator can be controlled either interactively or through a simulation script. Memory contents can be loaded from files, and a microcode/macrocode compiler (gmac) is included to create TkGate memory files from a high-level description. The simulator supports continuous simulation, single step simulation (by clock or epoch) and breakpoints. Save files are in a Verilog-like format.

A TkGate circuit is divided into one or more modules, with one of the modules being designated the "top-level" or "root" module. A module is composed of zero or more "gates" and wires to connect the gates. We use the term "gate" loosely to refer to any circuit element. Special "comment" gates can be used to place text in the circuit.

Creating a gate in TkGate is simply a matter of clicking the cursor to set a position, and selecting a gate type from the menu. Since most gate types have a one or two character shortcut, once you learn the shortcuts you can perform most of your editing with one hand on the keyboard and the other hand on the mouse. Moving gates is almost as easy as creating them, simply select a gate (or gates) and drag them to a new position, any wires connected to the gates will be moved along with them and adjusted to ensure that they contain only horizontal and vertical segments.

1.1 Command Line Options

Start TkGate with a command of the form:

% tkgate [options] [files ...]

The following command-line options are supported:

Option	Description

-v	Be verbose about start-up error messages and warnings.
-V	Read the TkGate files specified on the command-line and check them for internal errors, but do not start TkGate.
-h	Print the list of options.
-d	Turn on debugging.
-x	Automatically starts the simulator on start-up.
-q	Suppresses start-up messages.
-s	Executes with a synchronous X server connection. This option is primarily for debugging.
-n	Do not display the splash screen on start-up.
-l lib	Loads the specified library on start-up. Can be specified multiple times.
-L lang	Specifies the language to use. TkGate must have been built with multi-lingual support in order to use this option.
-O opts	Specifies a list of printer options.
-P printer	Print the specified circuit to a printer without starting up the GUI.
-p file	Print the specified circuit to a file without starting up the GUI.
-X script	Starts the simulator and executes the specified simulation script.

The -O switch is used in conjunction with the -p or -P switches to specify any printer options. The printer options are given as a colon separated list of options. The following printer options are supported through this interface:

Option	Description

epsf=bool	Use encapsulated Postscript format
duplex=bool	Use duplex printing
index=bool	Include index
hier=bool	Include module hierarchy graph
paper=type	Use the specified paper size
4up=bool	Do 4-up printing of small modules
modules=list	Comma separated list of modules to print

1.2 History of TkGate

(click to enlarge)

Figure 1.1: xgate - An Early XLib Based
Predecessor to TkGate

TkGate begin life as an undergraduate project at Carnegie Mellon University (CMU) in 1987. At that time it was called simply 'gate' and ran under the 'wm' window manager, a windowing system developed at CMU before X11 was widely used. This incarnation was used by students in the computer architecture course at CMU to develop a simple microprocessor (dubbed "The Bat Computer"). Many of the bitmap images for the circuit elements and mode cursors (such as the wire-cutter cursor) used today were originally designed in this version. This version also contained the hidden pancake recipe which is still in TkGate today.

After laying dormant for several years, it was resurrected in 1991 and ported to run under X11 with the Xlib API. A screenshot of this version, which was called "xgate", is shown in Figure 1.1. In this incarnation it was used several times by students in the introductory digital logic course, but after the author graduated and left CMU, it went into hibernation again.

Work on the first Tcl/Tk incarnation begun in 1998 as an exercise in learning Tcl/Tk. It was also the first version to use a Verilog-like save file format. Previous versions of gate/xgate used a Lisp-like save file format.

The current version, TkGate 2.0, represents a substantial effort over the previous 1.8 version. Whereas TkGate 1.8 was comprised of approximately 73,000 lines of C and Tcl, TkGate 2.0 nearly doubles that line count with over 130,000 lines of C and Tcl. Major improvements added to TkGate 2.0 include an improved user interface, true Verilog format save files, Verilog-based simulation, a module interface editor, symbolic module interfaces and virtual peripheral devices.