# TKGate 2.1

User documentation

Jeffery P. Hansen
1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 Jeffery P. Hansen

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

TkGate is a graphical editor and event-driven simulator for digital circuits with a tcl/tk-based interface. Supported circuit elements include basic gates (AND, OR, etc.), tri-state gates, adders, multipliers, registers, memories and mos transistors. Hierarchical design is also supported with support for user defined modules. Save files are based on the Verilog netlist format.

## 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.

### Command Line Options

Start TkGate with a command of the form:

`% tkgate [options] [files ...]`

TkGate command-line options list

Option | Description
--- | ---
-d | Turn on debugging.
-h | Print the list of options.
-l lib | Loads the specified library on start-up. Can be specified multiple times.
-L lang | Specifies the language to use.
-n | Do not display the splash screen on start-up.
-O opts | Specifies a list of printer options in conjunction with -p and -P switches. The printer options are given as a colon separated list (see table 1-2).
-p file | Print the specified circuit to a file without starting up the GUI.
-P printer | Print the specified circuit to a printer without starting up the GUI.
-q | Suppresses start-up messages.
-s | Executes with a synchronous X server connection. This option is primarily for debugging.
-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.
-x | Automatically starts the simulator on start-up.
-X script | Starts the simulator and executes the specified simulation script.

Supported printer options list

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

### History of TkGate

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.1, 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.1 nearly doubles that line count with over 130,000 lines of C and Tcl. Major improvements added to TkGate 2.1 include an improved user interface, true Verilog format save files, Verilog-based simulation, a module interface editor, symbolic module interfaces and virtual peripheral devices.

## Using the Editor

This chapter will introduce the basic concepts needed to create a graphical circuit in TkGate.

### Understanding the TKGate Interface

TkGate Main Window

The main components of the TKGate edit window consists of a menu bar and tool bar at the top, the module, net and port lists on the left, a status bar on the bottom, and the main editing area in the center. The main edit window contains major mode tabs to switch between "Edit" mode for editing your circuit, "Interface" mode for editing the interface of any modules you define, and "Simulate" mode for simulating your circuit. Scroll bars can be used to scroll the circuit, the list of modules or the list of nets.

#### Main Menu

The TkGate menu bar appears at the top edge of the main window and is arranged by category. The menus that are available can change when you enter different modes (e.g., editing versus simulation).

#### Pop-up Menus

Many of the features described in this manual can also be accessed using the context sensitive pop-up menus. The pop-up menus are obtained by pressing the right mouse button, and the menu items that appear depend on what was selected. The menu that appears, depends on where you clicked and what the current mode is.

#### Toolbar

Frequently used commands can be accessed through the TkGate toolbar. These include commands for opening, saving and printing circuit files, changing the editing tool, opening and closing modules and controlling the simulator. The toolbars that are displayed change dynamically with mode. You can also configure which toolbars you want to use on the Toolbars tab of the Options dialog box. A complete list of the toolbar buttons are given in the appendix List of Toolbar Buttons.

#### Keyboard Shortcuts

Many of the commands that can be accessed through the menu or toolbar can also be accessed through keyboard shortcuts. Commands for creating gates are typical single character letters. When possible, the letter is the first character of that gate type (e.g., "a" to create an "AND" gate and "r" to create a "register"). By default, file handling commands use Emacs-style shortcuts (e.g., "ctrl-c ctrl-s" to save, "ctrl-x ctrl-f" to load a file, etc.) If you prefer, you can choose to use Windows style shortcuts through the Interface tab on the options dialog box.

#### Module List and Module Hierarchy

The modules defined in the current circuit can be shown as in an alphabetical list view (press to select), or in a hierarchy view (press to select). The list view simply displays all of the modules in alphabetical order. The hierarchy view displays the module hierarchy starting at the top-level module. Under each module is the list of modules used by that module. There may also be additional hierarchies with the loaded library parts and any unused modules. Modules and the module hierarchy are described in greater detail in Section 3.3 Module Hierarchy.

#### Net and Port Lists

Below the module list in the lower-left corner of the main window is the list of nets or ports in the current module. A symbol precedes each net name depending on the type and whether the net is 1-bit or multi-bit as shown in the table below:

Net type symbols

1-Bit Symbol | Multi-Bit Symbol | Description
--- | --- | ---
|  | Wire with a hidden name.
|  | Wire with a visible name.
|  | Register variable (HDL modules only).
|  | Wire with a probe attached to it (in simulation mode).
|  | Module input port.
|  | Module output port.
|  | Module bidirectional port.

The "Ports" list can be used to list the modules nets that are defined as part of the interface for the current module. These are nets that the user is expected to define in the module definition.

#### Status Bar

Status Bar

The status bar on the bottom indicates the file that is being edited, and the current module from that file that is displayed in the circuit window. A "*" after the file name indicates that the buffer has been modified since the last time the file was saved. Below the file and module name is a message bar for informational messages from TKGate. These messages include confirmation for files that are loaded or saved, or information on the currently selected gate or wire.

#### Major Mode Tabs

Major Mode Tabs

The main edit window has three tabs to indicate and select the major mode in TkGate. "Edit" mode is used for creating and editing your circuit. The majority of your time using TkGate is likely to be in this mode. The "Interface" tab is used to design the interface for any modules that you define. You can also use this mode to view the interface of a module without creating a module of that type. The "Simulate" tab is used to perform simulations. When you press this tab, TkGate will send your circuit to the simulator, check for errors, and if your circuit is error free, start the simulator. By default, the simulator will be "paused" and you will need to press the button.

The icon in the upper right corner of the interface can also help show you what mode you are in. The possible icons listed in Table 2-2.

TkGate state icons

Symbol | Description
--- | ---
| Edit/Interface Mode - The TkGate logo is shown when TkGate is in the "Edit" or "Interface" modes.
| Paused Simulation - A stopped AND dragon shows that TkGate is simulation mode, and the simulation is paused.
| Running Simulation - A running AND dragon shows that TkGate is in simulation mode, and the simulation is running.

#### Balloon Help

Balloon Help

Balloon help is available for many of the elements in the interface, typically on the prompt text. To use balloon help, simply move the mouse cursor over an interface element. After about one second, an informational help message will be displayed as long as the mouse cursor has not moved. For example, moving the mouse cursor over the "Nets" label on the main window produces a balloon help message as shown below: Balloon help is also available in most of the dialog boxes. Position the cursor over the text in a dialog box to view a more detailed description.

### Loading and Saving Circuits

Open File Dialog Box

Opening and saving circuits as well as circuit printing operations are done through the "File" menu option on the main window. To load a file into TKGate, you can either specify the file name on the command line when you start, select "Open..." from the "File" menu or use the button on the toolbar. You can also use the keyboard shortcut Ctl-X Ctl-F. When opening a new file, all existing modules will be flushed from the buffer, and the modules in the new file will be loaded. TkGate save files have the extension ".v" and are in a special annotated Verilog format. Files saved from TkGate contain special comments with information such as circuit elements and wire positions. Also, gates with no explicit counter part in Verilog such as switches and clock generators are saved as annotation comments in the save file.

You can also load non-TkGate generated Verilog files. These files will load as a set of HDL modules. When saving from a file that was loaded as a non-TkGate Verilog file, the saved file will contain TkGate annotations.

When you open or save a circuit, you will see a dialog box such as the one shown in the figure on the right. Enter a file name at the prompt and press the "Open" (or "Save") button, or double click on a file name. Only the appropriate type of files will be displayed. You can change directories by double clicking on a folder to open it, or by using the button in the upper right corner to move up to the parent folder.

### Loading Libraries

Library Manager

Libraries are loaded and unloaded through the "Library Manager". Select "Library Manager" from the "File" menu or select from the toolbar. This will open the library manager as shown on Figure 2-6. To load a library, check the box near the name of the library; to unload a library, uncheck corresponding box. When you have finished selecting which libraries you wish to have loaded, close the dialog box by pressing "OK". If you press "Cancel", all of your changes to the set of loaded libraries will be ignored.

The set of libraries that are displayed in the library are found by searching the TkGate library path. The library path can be set through the library options dialog and can include user-defined libraries.

When you save your design after loading libraries, TkGate will store the names of libraries you have loaded in the save file. Then when you load your design again, TkGate will automatically load the necessary libraries.

### Basic Editing Tools

The basic editing tools are selected through the "Mode" toolbar. While a mode is active, the mouse cursor will change to reflect the active mode. The available editing tools are shown in the table below.

Basic editing tools

Button | Cursor | Shortcut | Description
--- | --- | --- | ---
|  | F1 | Move/Connect tool is indicated by the arrow cursor. Use this tool for most editing operations including creating gates, connecting wires, moving gates and wires, opening module instances, opening property boxes of gates and wires, and deleting circuit elements (with the "delete" key).
|  | (F1) | The Connect tool is indicated by the soldering iron cursor. To use this tool, first select the move/connect tool and then press and hold the left mouse button on a wire endpoint. The cursor will then change to the connect tool as long as you are holding down the mouse button.
|  | F2 | The Wire Cutter tool is indicated by the wire cutter cursor. Use this tool to cut wires by clicking on the wire at the point you want to cut it. If you cut a wire with an unconnected end, the wire segments between the cut point and the unconnected end will be deleted automatically.
|  | F3 | The Inverter tool is indicated by the inverter bubble grabber cursors. Use this tool to add or remove inverter bubbles on the inputs and outputs of gates. Click the cursor near an input or output to converter a non-inverting port to an inverting port or vice-versa.
|  | F4 | The Wire Size/Type tool is indicated by the ribbon cable cursor. Use this mode to change the bit width of a wire or the type of wire. The desired bit width and wire type should be selected in the selector boxes next to the button on the Mode toolbar. Any wires that are clicked on will have their size and type changed to the selected size/type. The wire type affects how the wire's value will be set when multiple gates drive a wire. You can also change wire bit widths and types using the Wire Properties dialog box.

#### Creating Gates

There are three main ways to create gates in TkGate: using the menu bar, using pop-up menus, and using keyboard shortcuts. Once you have mastered the keyboard shortcuts, that is generally the preferred way to create gates. These three methods are described in the following sections.

##### Creating a Gate Using the Menu Bar

Creating a Gate

1) Left click to select the point.

2) Select gate type from menu bar.

3) Gate is created at location set by point.

1) To create a gate such as a NAND gate, first select the Move/Connect tool , and then press the left mouse button at the position you wish to create it. While you are holding the mouse button down, the cursor will change to an outline arrow to indicate the current orientation. In the case shown at the left, the current orientation is 0 degrees indicating the standard orientation.

When you release the button the arrow will disappear and the mark symbol will remain. The mark indicates the center point for the new circuit element. Clicking the left mouse button at another location will move the mark, and selecting a gate or wire will clear the mark.

2) Select the gate type by opening the "Make" menu. The circuit elements are organized into seven basic categories:

- "I/O" types include switches, dip switches, power sources, clocks, etc.

- "Gate" types include the basic logic gates such as AND and OR gates.

- "Reduction" types include reduction versions of the basic gates types which combine multi-bit signals into a single bit.

- "MSI/LSI" types include MUXES, DEMUXES, etc.

- "ALU" types include adders, multiplier, shifters, etc.

- "Memory" types include registers, RAMs, ROMs, etc.

- "Module" types include module blocks and ports.

There are also two additional non-circuit element objects that can be created. A "Comment" is an arbitrary block of text that can be used to add documentation to your circuit, and a "Frame" is a labeled box that you can place around a portion of your circuit.

3) After selecting the menu option or typing the shortcut, the circuit element will be created and displayed in bold to indicate that it is selected. While the gate is still selected, you can press the toolbar button or press the Tab key to rotate the gate to the desired orientation.

##### Creating a Gate Using the Pop-up Menu

Creating a Gate with Pop-up Menu

Right click to use pop-up menus to create a gate.

To create a gate using the pop-up menu, right click on the position at which you wish to create a gate. This will both create the position mark and bring up the pop-up menu. Then select "Make", and then maneuver through the gate category to select the appropriate gate type.

##### Creating a Gate Using Keyboard Shortcuts

To create a gate using keyboard shortcuts, first set a mark in the same way as when creating a gate using the menu bar (Section 2.5.1). Then simply type the shortcut for the gate you wish to create. Most of the gate types have single character commands to create them. For example, you can type "a" to create an AND gate, and "A" to create a NAND gate. A list of the gate types and their keyboard shortcuts are shown in Section 2.16.

#### Connecting Wires

##### Port-to-Port Connections

Port-to-Port Connections

Step 1: select endpoint

Step 2: drag wire end

Step 3: bring wire end close to other terminal

Step 4: release and connect

Port-to-port connections are used to connect the end points of two wires. Before making the connections, make sure you have selected the "Move/Connect" tool from the "Tool" menu. Then, click and hold the left mouse button on the endpoint of one of the ends you wish to connect. The mouse cursor will change to a soldering iron to indicate that connect mode is active as shown in Step 1.

Next, drag the mouse toward the other endpoint you wish to connect to as shown in Step 2, TKGate will automatically introduce any necessary bends and maintain connections with only horizontal and vertical segments. Bring the end close the the wire you wish to connect to as shown in Step 3. When you release the mouse button, the wires will connect as shown in Step 4.

##### Port-to-Joint Connections

Port-to-Joint Connections

Step 1: select endpoint

Step 2: drag wire end

Step 3: bring wire end close to other wire and release

Step 4: continue making connections as necessary

Port-to-joint connections are used to connect a wire end point to the center or corner of another wire, or to an existing wire joint. These connections are made essentially the same way as port-to-port connections. First, as in with port-to-port connections, make sure you have selected the "Move/Connect" tool from the "Tool" menu. Then, select a free endpoint to get the soldering iron (Step 1). Drag the wire near the wire you want to connect to (Step 2) and release the wire to connect to the nearby wire segment (or corner) and create a solder joint (Step 3). You can continue the process to connect as many ports to a net as necessary (Step 4).

##### Creating Bit Taps

Bit Tap

When you attempt to do a port-to-joint connection with wires of different sizes, a "bit tap" will be created if you are connecting a wire with smaller bit size to one with a larger bit size. A bit tap element allows you to select one or more bits off of a bigger wire. To set the desired bit, you should double click on the tap to open the Gate Properties box, select the "Details" tab and enter the desired bit or bits. Ranges are indicated as a pair of bit numbers (high number first) separated by a colon (":") character. For example, to select the low four bits you would use the range "3:0". In the bit tap shown here, bit 4 of the register output is used as an input to the AND gate.

Bit taps can only be used to "read" values off of a larger wire. To individually drive bits on a larger wire you should use the "Concat" device. This device can support data flow in either direction.

##### Creating New Joints

Wire Tap

You can also create joints by right clicking on a wire and selecting "Add Wire Segments". This will create a new unattached wire segment to the wire on which you clicked as shown here.

#### Moving Gates and Wires

##### Moving Single Gates

Moving Single Gates

Step 1: select gate

Step 2: drag gate

To move a single gate, press and hold the left mouse button on the gate you wish to move. The selected gate will be shown in bold as shown in Step 1. While holding the mouse left mouse button down drag the gate to the new position as shown in Step 2. Any wires connected to the gate will move along with it. For very fine adjustments, you can also move the selected gate using the arrow keys.

##### Moving Groups of Gates

Moving Groups of Gates

Step 1: start selection

Step 2: drag selection box

Step 3: grab selection

Step 4: drag selection

To move a group of gates, first select the Move/Connect tool and press and hold the left mouse button at some point near, but not directly on the group you wish to move. The "X" mark should appear just as if you were going to create a new gate (Step 1). Next, while holding the left mouse button drag the cursor to enclose a group of gates in the selection box (Step 2). The box will appear after moving the cursor a few millimeters. Release the mouse button to select the circuit elements enclosed in the box (Step 3). Then, click and hold the mouse cursor on one of the selected elements (Step 4). You can then move the entire group to a new position.

The gates in a group selection will remain selected until you click on a gate not in the selection, or click on an empty part of the canvas. If you do this operation while holding the control key, you can add gates to the selection rather than create a new selection.

#### Cut/Paste and Deleting Gates

The selected gate or gates can be deleted by pressing the delete key, or by right clicking and selecting the " Delete" option. The selection may also be cut or copied to the cut buffer by right clicking and selecting " Cut" or "Copy". The original names of the gates and wires in the cut buffer will be remembered and used when pasting if possible, but when pasting multiple copies from the cut buffer, it may be necessary for TkGate to rename those wires and gates.

#### Rotating Gates

You can rotate single gates, or groups of gates by selecting the single gate or group and using the and toolbar buttons to rotate counter-clockwise or clockwise, respectively. You can also use the Tab or Shift-Tab keys. When rotating a selection, it can not have any wires connecting a selected element to a non-selected element.

You can also set the default rotation by clicking on the button on the toolbar. The inverter symbol on the button will turn to show the current rotation. Any gates that you create will have the default rotation shown on this button.

#### Wire Cutter Tool

Cutting Wires

Before Cut

After Cut

To cut a wire, select the tool from the toolbar to get the wire cutters tool. Click on a wire to cut the wire at the selected point. If there are any loose ends of a wire that is cut, TkGate will automatically delete the loose ends. It will also delete any joints that are no longer needed as the result of a cut. You can also use the wire cutter tool on the edge of a module to "cut off" a port if the module does not have a protected interface.

#### Inverter Add/Remove Tool

Inverting Inputs/Outputs

Before Add

After Add

You can use the tool to add or remove inverters from a gate input or output. Select the tool and click on an input or output port of a gate. If there is currently no inverter on that port, one will be added. If there is already an inverter on that port, the inverter will be removed.