<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
<!ENTITY klogic '<application>Klogic</application>'>
<!ENTITY kapp "&klogic;">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
<!-- Do not define any other entities; instead, use the entities
from kde-genent.entities and $LANG/user.entities. -->
]>
<book lang="&language;">
<bookinfo>
<title>The klogic Handbook</title>
<authorgroup>
<author>
<firstname>Andreas</firstname>
<othername></othername>
<surname>Rostin</surname>
<affiliation>
<address><email>andreas@a-rostin.de</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>1998</year>
<year>2001</year>
<holder>Andreas Rostin</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>29/09/2001</date>
<releaseinfo>0.09.00</releaseinfo>
<!-- Abstract about this handbook -->
<abstract>
<para>
klogic is an application for easy building and simulating digital circuits.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>kdeutils</keyword>
<keyword>klogic</keyword>
<keyword>digital</keyword>
<keyword>circuit</keyword>
<keyword>simulator</keyword>
<keyword>equation</keyword>
<keyword>logic</keyword>
<keyword>gate</keyword>
<keyword>wire</keyword>
<keyword>device</keyword>
<keyword>karnaugh</keyword>
<keyword>oscillator</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>
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)).
</para>
</chapter>
<chapter id="using-klogic">
<title>Using Klogic</title>
<sect1 id="first-steps">
<title>First Steps</title>
<para>After starting klogic, have a look at the devices toolbar.
Here you can switch between the three main modes of klogic.
They are</para>
<itemizedlist>
<listitem><para>draw wires</para></listitem>
<listitem><para>drop devices</para></listitem>
<listitem><para>selection cut/copy/paste/move</para></listitem>
</itemizedlist>
<para>You can draw wires by selecting the symbol
<mediaobject>
<imageobject>
<imagedata fileref="file:/home/andi/Development/klogic/toolbar/tbDraw.xpm" />
</imageobject>
</mediaobject>
, copy/paste with the second, and drop devices with all other symbols within this toolbar.</para>
</sect1>
<sect1 id="devices">
<title>Devices</title>
<para>You can select different types of devices in the device toolbar, or via the "Logic" menu.</para>
<para>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.</para>
<para>Clicking the right mouse button into the device, a menu with functions appear.</para>
<para>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.</para>
<para>For all but the <link linkend="sub-circuits">sub circuits</link>, the properties dialog can also be opened by double clicking the device</para>
<para>When double-clicking a <link linkend="sub-circuits">sub circuit</link>, the sub circuit will be opened, and its content will be shown on the screen</para>
<para>Try open the properties dialog for a device.</para>
</sect1>
<sect1 id="connect-devices">
<title>Connecting Devices</title>
<para>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.</para>
<para>Backtraces are always allowed, shortcuts (output-output connections) never.</para>
<para>You can also move devices, and access their functions with the right mouse button when in drawing mode.</para>
</sect1>
<sect1 id="sub-circuits">
<title>Sub Circuits</title>
<para>A sub circuit is a device that can contain a complete new circuit, integrated within a parent circuit.</para>
<para>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.</para>
<para>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.</para>
<para>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)</para>
<para>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 <link linkend="simulation">Simulation</link> section)</para>
<para>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.</para>
<para>To display a sub circuit in a separate window, right-click on it (in the parent circuit) and choose "open in window"</para>
</sect1>
<sect1 id="equation-devices">
<title>Equation Devices</title>
<para>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.</para>
<para>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".</para>
<sect2 id="equation-editor">
<title>Equation Editor</title>
<para>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.</para>
<para>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.</para>
<para>Example:</para>
<para>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:</para>
<para>Enter an output-name in the left edit-box, i.e "a".</para>
<para>Then enter an equation in the right edit-box, i.e "/b".</para>
<para>To add the new equation to the equation list, press the "Add" button.
The new equation will then be part of the device.</para>
<para>The used names (here: a and b) will be parsed and automatically added as device inputs (b) and outputs (a).</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
</sect2>
<sect2 id="equations">
<title>Equations</title>
<para>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.</para>
<para>Operator charactes cannot be part of names. The following boolean operators, ordered by their precedence, can be used:</para>
<itemizedlist>
<listitem><para>"/" NOT</para></listitem>
<listitem><para>"#" XOR</para></listitem>
<listitem><para>"&" AND</para></listitem>
<listitem><para>"+" OR</para></listitem>
<listitem><para>"§" 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</para></listitem>
</itemizedlist>
<para>Furthermore, parenthesis ( .. ) can be used to change the precedence of operations and terms.</para>
<para>Examples</para>
<itemizedlist>
<listitem><para>"/a + b & c" will be computed as (b & c) + (/a)</para></listitem>
<listitem><para>"(/a + b) & c" will be computed as ((/a) + b) & c</para></listitem>
</itemizedlist>
<para>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.</para>
</sect2>
<sect2 id="circuit-equations">
<title>Circuit Equation Analysis</title>
<para>Equations of conventional circuits can be analyzed by choosing the menu entry "Simulation/Show Equations".</para>
<para>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.</para>
<para>The substitute function tries to substitute equations with others to reduce the amount of equations in the list.</para>
<para>After modifying them, it is possible to create a new equation device from the conventional circuit.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
</sect2>
</sect1>
<sect1 id="simulation">
<title>Simulation</title>
<para>There is no unit of measurement for the simulation flow. The simulation is running in steps.</para>
<para>You can increase and decrease the time between two steps in the dialog "Options/Global Settings" or with the slider in the toolbar.</para>
<para>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.</para>
<para>The signals of all devices are calcutated and displayed for each simulation step.</para>
<para>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.</para>
<para>Be aware of undefined results in backtraced circuits if you use oscillators with a switch-time smaller than the sum over all delays.</para>
<para>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.</para>
<sect2 id="singe-step">
<title>Single Step Mode</title>
<para>To enter the step-by-step simulation mode, press the "1" button in the simulation toolbar.</para>
<para>Each time you press this button again, another single step will be performed.</para>
<para>You can also use the ´s´-key in the main window to perform single simulation steps.</para>
</sect2>
<sect2 id="multiple-step">
<title>Multiple Step Mode</title>
<para>To enter the multiple stepping simulation mode, press the "N" button in the simulation toolbar.</para>
<para>The calculation of all devices is then running permanentely with the predefined step rate.</para>
</sect2>
<sect2 id="graph">
<title>Simulation Graph</title>
<para>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 <link linkend="sub-circuits">sub circuits</link> 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".</para>
<para>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.</para>
<para>To remove a device from the simulation graph, use the "hide graph"function which is accessable via the right mouse button menu.</para>
<para>The menu will then show you the function "show graph"</para>
<para><link linkend="sub-circuits">sub circuits</link> also have a "display graph" function. The simulation graph will show all devices contained in the sub circuit when using this function.</para>
<para>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.</para>
</sect2>
</sect1>
<sect1 id="Libraries">
<title>Libraries</title>
<para>All basic library functions can be reached via the "File/Library Maintenance" dialog.</para>
<para>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.</para>
<para>After you have created a new library, you cannot choose any devices, of course.</para>
<para>Devices, that can be added to libraries are <link linkend="equation-devices">equation devices</link> and <link linkend="sub-circuits">sub circuits</link>.
To add a device, use the function "add to lib" which is accessable via the right mouse button menu.</para>
<para>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</para>
<para>After the library has some devices, their library parameters can be changed within the "File/Library Maintenance" dialog.</para>
<para>In future releases it will also be possible to edit a library device, and change its image.</para>
</sect1>
</chapter>
<chapter id="developers">
<title>Developer's Guide to Klogic</title>
<para>
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!
</para>
</chapter>
<chapter id="faq">
<title>Questions and Answers</title>
&reporting.bugs;
<qandaset id="faqlist">
<qandaentry>
<question>
<para>klogic won't compile</para>
</question>
<answer>
<para>in that case, you can't read this faq list :-) [to be completed ..]</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>
klogic
</para>
<para>
Program copyright 2001 Andreas Rostin <email>andreas@a-rostin.de</email>
</para>
<para>
Documentation copyright 2001 Andreas Rostin <email>andreas@a-rostin.de</email>
</para>
<para>
Translations done by:
<itemizedlist>
<listitem>
<para>no translations until now</para>
</listitem>
</itemizedlist>
</para>
&underFDL; <!-- FDL: do not remove -->
&underGPL; <!-- GPL License -->
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-klogic">
<title>How to obtain Klogic</title>
<para>
Maybe there are some changes and fixes available at
<ulink url="http://www.a-rostin.de/klogic/index.html">http://www.a-rostin.de</ulink>.
</para>
</sect1>
<sect1 id="requirements">
<title>Requirements</title>
<para>In order to successfully use klogic, you need KDE 2.</para>
</sect1>
<sect1 id="compilation">
<title>Compilation and installation</title>
<para>
In order to compile and install klogic on your system, type the following in the base
directory of the Icon Editor distribution:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
</sect1>
</appendix>
&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
