# The klogic Handbook

## Introduction

klogic is an application for building and simulating digital circuits easily. It provides an easy way to build circuits containing standard components like AND, OR, XOR and flipflops like RS and JK. To build more complex and reuseable circuits, you can create sub circuits. There is no complexity limit but the hardware (tested with over 60000 devices in 2300 sub circuits (250MByte memory consumption)).

## Using Klogic

### First Steps

After starting klogic, have a look at the devices toolbar. Here you can switch between the three main modes of klogic. They are

- draw wires

- drop devices

- selection cut/copy/paste/move

You can draw wires by selecting the symbol , copy/paste with the second, and drop devices with all other symbols within this toolbar.

### Devices

You can select different types of devices in the device toolbar, or via the "Logic" menu.

After choosen a device you can drop it on an empty place of the screen. After you have dropped it, you can move it with the mouse.

Clicking the right mouse button into the device, a menu with functions appear.

The most important function is the "properties" function. It is available for almost all devices. With the appearing properties dialog you can do changes on look and behaviour of a device. Each device has its own set of properties. But there are also some common properties like the device-name.

For all but the sub circuits, the properties dialog can also be opened by double clicking the device

When double-clicking a sub circuit, the sub circuit will be opened, and its content will be shown on the screen

Try open the properties dialog for a device.

### Connecting Devices

You can connect devices with wires. Dragging or dropping a wire-node on the right side of a device connects the device output with the wire. Dragging or dropping a wire-node on the left side connects the wire with a device input. When a wire is connected to two different devices, the devices will be connected together as well.

Backtraces are always allowed, shortcuts (output-output connections) never.

You can also move devices, and access their functions with the right mouse button when in drawing mode.

### Sub Circuits

A sub circuit is a device that can contain a complete new circuit, integrated within a parent circuit.

Choose this device type from the menu or toolbar. Drop a new sub circuit and double-click on it. A new and empty window opens. Here you can create a new circuit. With the blue "Up" arrow, you can go back to the parent circuit.

The special devices input and output can be used as interface devices to the parent circuit. After placing them in the sub circuit, they appear in the device symbol in the parent circuit. There, they can be connected to other devices.

Unless you have not defined some interface devices in the sub circuit, you will not be able to connect it to other devices (being in the parent circuit)

Input and output devices have neither a function nor a delay. Incoming signals will go directly to the devices connected to them. (the delay of a device is described in more detail in the Simulation section)

In order to save a sub circuits in a separate file, you must switch into it, and do a "File/Save As". You will be asked wether to save the complete, or the sub circuit. When loading a file containing a sub circuit, it will always appear as a new circuit within the current circuit.

To display a sub circuit in a separate window, right-click on it (in the parent circuit) and choose "open in window"

### Equation Devices

Equation devices are a kind of sub sircuits. Instead of creating a new sub circuit you can describe the logic behaviour of such a device with equations.

In the equation editor dialog of this device type (accessable via right mouse button) you can enter and modify its boolean equations. The equation editor is also accessable via properties dialog, the button "Equation Editor".

#### Equation Editor

The equation editor mainly consists of an equation list, two edit boxes to edit a single equation, a group of buttons to choose an output type, and the buttons "Change", "Add" and "Delete". All other available functions are helping you to manage complexity and analysis.

The purpose of the two edit boxes below the equations list box is to edit old, or enter new equations. In the left edit-box, an output name is expected. In the edit-box to the right, an equation is expected.

Example:

After creating a new equation device, the equation list will be empty. You can enter new equations in the line below the list box as follows:

Enter an output-name in the left edit-box, i.e "a".

Then enter an equation in the right edit-box, i.e "/b".

To add the new equation to the equation list, press the "Add" button. The new equation will then be part of the device.

The used names (here: a and b) will be parsed and automatically added as device inputs (b) and outputs (a).

Outputs can also be used in equations, and sometimes you will need outputs only as device internal temporary variables. For that purpose you can choose "Internal" as output type. Those outputs are invisible in the resulting device, but only internally visible to use them in equations.

The "temporary" outputs will be completely removed when closing the dialog. They are not available after closing the dialog, and they are not saved. They can only be used for enhanced circuit analysis purposes.

When there are some equations in the list, you can modify or delete them by selecting them from the list. A selected equation will be displayed again in the edit boxes for manupulation. It can be deleted with the "Delete" button. Changes on output-name, output-type or equation are taken over after pressing the "Change" button.

#### Equations

Equations always consist of two parts, the left side (output name) and the right side (boolean equation), together with an equal sign in the middle.

Operator charactes cannot be part of names. The following boolean operators, ordered by their precedence, can be used:

- "/" NOT

- "#" XOR

- "&" AND

- "+" OR

- "§" reserved for bus operations (2 operands, o1 § o2 equivalent to o2^(n+1) + o1^n) where n is the operand position from the right to the left

Furthermore, parenthesis ( .. ) can be used to change the precedence of operations and terms.

Examples

- "/a + b & c" will be computed as (b & c) + (/a)

- "(/a + b) & c" will be computed as ((/a) + b) & c

Names that occur in equations will be parsed and added as inputs and outputs to the equation device. If a name does not occur as an output name, it will be taken as input name.

#### Circuit Equation Analysis

Equations of conventional circuits can be analyzed by choosing the menu entry "Simulation/Show Equations".

The equation editor will show the set of equations describing the behaviour of the current circuit. The equation list can be manipulated with the functions availabe on the right side of the dialog. These functions are always works on the whole list of equations. Most of them should be self-explaining.

The substitute function tries to substitute equations with others to reduce the amount of equations in the list.

After modifying them, it is possible to create a new equation device from the conventional circuit.

This can be done by simply pressing the "Create Sub Circuit" button, that is only available when opening the dalog via "Simulation/Show Equations" menu. In background, a substitution will start until there is nothing to substitute anymore. After the substitution, a "Tidy Up" will start in background. This function removes all temporary equations from the list.

The speed of substitution depends on the number and size of equations in the list. So it may take some time to perform that command.

Only for not too much equations, substitute works fast and good. Because there is no possibility to interrupt it after started, it is a good idea to save your current circuit before playing around with it.

### Simulation

There is no unit of measurement for the simulation flow. The simulation is running in steps.

You can increase and decrease the time between two steps in the dialog "Options/Global Settings" or with the slider in the toolbar.

The time between two steps (step rate times 40ms) is not guaranteed, and it is not of importance for the calculation results of a circuit.

The signals of all devices are calcutated and displayed for each simulation step.

All devices, except input- and output-devices of sub curcuits, have a tunable delay. A delay of "1", the default value, means that all incoming signals will change the output value with a delay of one simulation step.

Be aware of undefined results in backtraced circuits if you use oscillators with a switch-time smaller than the sum over all delays.

To turn off all delay effects you can increase the burst value in the dialog "Options/Global Settings". Then each device will be calculated n-times in one simulation step.

#### Single Step Mode

To enter the step-by-step simulation mode, press the "1" button in the simulation toolbar.

Each time you press this button again, another single step will be performed.

You can also use the ´s´-key in the main window to perform single simulation steps.

#### Multiple Step Mode

To enter the multiple stepping simulation mode, press the "N" button in the simulation toolbar.

The calculation of all devices is then running permanentely with the predefined step rate.

#### Simulation Graph

With the most left button in the simulation toolbar, you can activate the simulation graph window. Here you can see the signal flow of all devices of the current sub circuits or main circuit as a graph. Devices without an output, like LED and output-device, are not displayed. The unit displayed in the table of the simulation graph is "simulation step".

Two cursors can be used to compare events. Initially, they can be found on the left border of the shown table. Use the mouse to move them over the screen.

To remove a device from the simulation graph, use the "hide graph"function which is accessable via the right mouse button menu.

The menu will then show you the function "show graph"

sub circuits also have a "display graph" function. The simulation graph will show all devices contained in the sub circuit when using this function.

There is currently no possibility to switch back to the main circuit after choosen a sub circuit. The only way to go back is to close and reopen the simulation graph again.

### Libraries

All basic library functions can be reached via the "File/Library Maintenance" dialog.

First of all, you should create a new library with the "new" button. After closing the dialog, a new toolbar with two combo-boxes will appear. The left one can be used to select an open library, the second will show you a list of devices available in the currently choosen library.

After you have created a new library, you cannot choose any devices, of course.

Devices, that can be added to libraries are equation devices and sub circuits. To add a device, use the function "add to lib" which is accessable via the right mouse button menu.

You can add a device name, author and a comment before adding a device to the library. You can also change the library to which you want to add a device

After the library has some devices, their library parameters can be changed within the "File/Library Maintenance" dialog.

In future releases it will also be possible to edit a library device, and change its image.

## Developer's Guide to Klogic

A virtual interface class to derive your own devices from is in progress. Currently it is impossible to add devices without changing a lot of things in many classes. This is a well known design issue!

## Questions and Answers

&reporting.bugs;

klogic won't compile

in that case, you can't read this faq list :-) [to be completed ..]

## Credits and License

klogic

Program copyright 2001 Andreas Rostin andreas@a-rostin.de

Documentation copyright 2001 Andreas Rostin andreas@a-rostin.de

Translations done by:

- no translations until now

&underFDL; &underGPL;

## Installation

### How to obtain Klogic

Maybe there are some changes and fixes available at http://www.a-rostin.de.

### Requirements

In order to successfully use klogic, you need KDE 2.

### Compilation and installation

In order to compile and install klogic on your system, type the following in the base directory of the Icon Editor distribution:

    % ./configure
    % make
    % make install

&documentation.index;