From 2fff7964d92797119869638b8ea89dd5346c81e1 Mon Sep 17 00:00:00 2001 From: hneemann Date: Tue, 14 Apr 2020 09:08:19 +0200 Subject: [PATCH] adds the static ref file --- src/test/resources/docu/static_zh_ref.xml | 741 ++++++++++++++++++++++ 1 file changed, 741 insertions(+) create mode 100644 src/test/resources/docu/static_zh_ref.xml diff --git a/src/test/resources/docu/static_zh_ref.xml b/src/test/resources/docu/static_zh_ref.xml new file mode 100644 index 000000000..e44d9153e --- /dev/null +++ b/src/test/resources/docu/static_zh_ref.xml @@ -0,0 +1,741 @@ + + + + + + Digital is a simple simulator used to simulate digital circuits. The logic gates are connected + to each other by wires and the behavior of the overall circuit can be simulated. + The user can interact with the simulation by either pressing buttons or setting + values to the inputs of the circuit. + + + In this way, most of the basic circuits used in digital electronics can be built and simulated. + In the folder examples, users can browse for examples that includes a functional + 16-bit single-cycle Harvard processor. + + + The simulator has two modes of operation: Editing and Simulation mode. + In the editing mode, modifications to the circuit can be performed. Users can add or connect components. + In this mode, simulation is disabled. + The simulation mode is activated by pressing the Start button in the tool bar. + While starting the simulation the circuit is checked for consistency. + If there are errors in the circuit an appropriate message is shown and + the affected components or wires are highlighted. If the circuit is error free, the simulation is + enabled. Now you can interact with the running simulation. + In the simulation mode it is not possible to modify the circuit. To do so you have to activate the + editing mode again by stopping the simulation. + + + + + + + + As a first example, a circuit is to be constructed with an Exclusive-Or gate. + From the main window, the Components menu allows you to select the various components. + Then they are placed on the drawing panel. This process can be canceled by pressing the ESC key at any + time. Start by selecting an input component. + This can later be controlled interactively by using the mouse. + + + + + After selection, the first input can be placed on the drawing panel. + The red dot on the input component symbol is a connection point between the component and a wire, + which will be + connected later on. + The red color indicates an output. This means that the port defines a signal value or can drive a + wire. + + + + + + In the same way, a second input is added. It is best to place it directly below the first input. + + + + + After adding the inputs, the Exclusive-Or gate is selected. This gate represents the actual logical + function. + + + + + + This gate can now also be added to the circuit. It is best to place it in a way that the subsequent + wiring is made as simple as possible. The blue dots indicate the input terminals of the gate. + + + + + + Now, select an output which could be used to display a signal state or to later pass signals to + an embedding circuit. + + + + + + This is placed in a way that it can be wired easily. + The output has a blue dot, which indicates an input terminal. + Here you can feed in the value which is then exported. + + + + + + After all components are selected and in place, use the mouse to wire a connection between the blue and + red dots. Make sure that exactly one red dot is connected to any number of blue dots. + Only the usage of three-state outputs makes it possible to deviate from this rule and to interconnect + several red dots. + If all wires have been drawn, the circuit is complete. + + + + + + Interaction with the circuit is possible when simulation is started. + This is done by clicking on the play button located in the toolbar. + After starting the simulation, the color of the wires changes and the + inputs and outputs are now filled. Bright green indicates a logical '1' and dark green a logical '0'. + In the figure above, all wires have a '0' value. + + + + + + By clicking with the mouse, the inputs can be switched. Since the simulation is now active, the + output changes according to the current input states. The circuit behaves like an + Exclusive-Or gate as expected . + + + + + + To further process the circuit, the simulation must first be stopped. The easiest way to do this is + with the Stop button in the tool bar. Clicking on a component with the right mouse button + (control-click on MacOS) opens a dialog which shows the component's properties. The label 'A' can + be defined for the first input via this dialog. + + + + + + In this way, the labels for the remaining inputs and outputs can be defined. The menu item + Analysis + also contains a menu item Analysis. This function performs an analysis of + the current circuit. However, this is only possible if all inputs and outputs are labeled properly. + + + + + + The truth table of the simulated circuit appears in a new window. Below the table you can find the + algebraic expression associated with the circuit. If there are several possible algebraic + expressions, a separate window will open, showing all possible expressions. + + + + + + The table dialog has the menu entry K-Map in its main menu. This allows to display the truth + table in the form of a K-map. + + + + + + At the top of this dialog there is a drop-down list which allows the selection of the desired + expression in the K-map. In this way you can, for example, illustrate how several equivalent + algebraic expressions can result. However, in this example, there is only one minimal expression. + The truth table can also be modified by clicking the K-map. + + + + + All components must be connected via wires. It is not possible to connect two components + by placing them directly next to each other. + + + In addition, there are only connections between an endpoint of a wire and a component. + If a pin of a component is placed in the middle of a wire, no connection is made between the component + and the wire. + Therefore, a wire must actually terminate at each pin which is to be connected. + Even if the tunnel component is used, there must be a wire between the pin and the tunnel element. + + + The component needs to be selected using the rectangular selection tool in order to be moved, + including the connected wires. For moving a component without the connected wires, + select the component using a mouse click. + + + With CTRL-Click a single wire section can be selected to move or delete it. + If the D key is pressed while drawing a wire, a diagonal wire can be drawn. + The key S allows the splitting of a line segment into two segments. + + + + + If a complex circuit is built up, this can quickly become very confusing. To keep track here, + the different parts of a circuit can be stored in different files. This mechanism also makes it + possible to use a subcircuit, which has been created once, several times in a further circuit. + This approach also offers the advantage that the files can be stored independently of each other in a + version control system and changes can be tracked. + + + + + + As an example, consider a 4-bit adder: First, we built a simple half-adder. This consists of an + XOR gate and an AND gate. The sum of the two bits 'A' and 'B' is given to the outputs 'S' and 'C'. + This circuit is stored in the file halfAdder.dig. + + + + + + From two half adders a full adder can now be built. To do this, create a new empty file and save the + empty file as fullAdder.dig in the same folder as the half adder. Then the + half adder can be added to the new circuit via the + Components + + Custom + menu. + The order of the pins at the package of the half-adder can be rearranged in the half adder in the + menu + Edit + + Order inputs + or + Edit + + Order outputs. + The full adder adds the three bits 'A', 'B' and 'Ci' and gives the sum to the outputs 'S' and 'Co'. + + + + + + In order to check the correct function of the full adder, a test case should be added. In the test case, + the truth table is stored, which should fulfill the circuit. In this way it can be automatically + checked whether this is the case. + + + + + + The tests can be executed via the test case editor or the test button in the toolbar. + The table cells highlighted in green indicate that the output of the circuit matches + the truth table given in the test case. + + + + + + Now the full adders can be put together to form a so-called ripple-carry adder. + In this case, the carry output of an addition is forwarded as a carry input to the addition of the + next higher-order bit, just as is usual in pencil-and-paper addition. + This 4-bit adder should be tested for correct function. For this purpose a test case was inserted. + + + + + + This test case performs a 100% test, which is possible only with relatively simple circuits: all + possible 512 input combinations are applied to the circuit, and it is checked whether the output + of the circuit is correct. + The first line lists the input and output signals. Below this, the input values to be applied and + the output values to be checked are specified in a row, as in a truth table. + In this example, however, 512 lines are required. Entering this would be a tedious and error-prone task. + It is easier and more reliable to automatically generate the required lines. + For this purpose, the variables A and B are each traversed + from 0 to 15. The respective values of A and B are then assigned to inputs 'A[n]' and + 'B[n]'. + Then it is checked whether the circuit outputs the value A+B. Then it is checked again with + the carry bit set, in which case A+B+1 must result. + The details of the test syntax are provided by the help dialog. + + + If a circuit is embedded in an other circuit, only the file name of the subcircuit is stored in a + circuit, not the embedded circuit itself. + The corresponding files of + the embedded subcircuits must therefore be found in the file system at runtime of the simulation. + In order to support the various work methods of the users as best as possible and still to avoid a + complex administration of import paths, etc., a somewhat unusual import strategy is implemented. + + + Only the file names of the embedded circuits are stored in a circuits file, not the full path. + If a file needs to be opened, all subfolders are searched for a file of the corresponding name. + If a suitable file is found, it is imported. This process only depends on the file name of the file to + be read, not on its path. Correspondingly, an error message is generated if there are several files of + the same name in different subfolders, since ambiguities then arise. + + + A suitable project structure therefore looks as follows: The root circuit is located in a separate + folder. + All imported circuits must be in the same folder or subfolders. All circuits must have different names, + so it must not happen that there are circuits of the same name in different folders. + + + + + + + During the simulation every logic gate has a propagation delay. Every component found in the library + has the same propagation delay regardless of its complexity. + The AND gate thus has the same propagation delay as the multiplier. + The only exceptions are diodes, switches and splitters which are used to create data buses. + These components have no propagation delay at all. + + + If it's necessary to simulate a gate - e.g. the multiplier - with a longer propagation delay, a delay + gate must be inserted in the circuit right behind the output of the multiplier. + + + If a circuit is included in another parent circuit, the included circuit keeps its timing behaviour. + So if you include a complex circuit which has a large propagation delay because the input signals + has to pass three gates until it reaches the output, this behaviour is conserved while including this + circuit. + There are no additional delays introduced as a result of including a circuit. If not all outputs of a + circuit have + the same propagation delay, then this is also the case if it is included in a parent circuit. + In general, including a circuit into an other circuit does not modify its timing behaviour at all. An + included circuit behaves exactly the same way as if all components had been inserted at the same circuit + level. + + + + + + A circuit can be analyzed via the menu entry Analysis. A truth table is generated for purely + combinatorial circuits. This truth table can be edited as desired. + A new circuit can be generated from this truth table after editing. + + + In addition to purely combinatorial circuits, it is also possible to analyze or generate sequential + circuits. + Instead of a simple truth table a so-called state transition table is created. + Each flip-flop thereby appears on the input side and the output side of the state transition table. + In this table, on the right-hand side, you can find the next state, which will + occur after the next clock signal. This next state depends on the current state of the flip-flops as found + at the left-hand side of the table. + For an analysis to be possible, the flip-flops must be named. + + + The following naming convention applies: The following next state of a bit on the right side of the table + is indicated by a lowercase 'n+1'. The corresponding current state is indicated by an appended 'n'. + If there is a state variable 'A', 'An' indicates the current state and 'An+1' indicates the next state. + If, in the truth table on the left and right side, signals are present, which correspond to this pattern + it is assumed that the table is a state transition table, and a sequential circuit is generated instead of + a combinatorial circuit. + + + It should be noted that the circuit to be analyzed may contain only purely combinatorial elements in + addition to the built-in D and JK flip-flops. If a flip-flop is e.g. made from Nor gates, this + circuit is not recognized as a flip-flop and therefore it is not possible to analyse such a circuit. + + + + + + In the circuit generation menu in the truth table there are also functions to generate so-called + JEDEC files. This is a special file format that describes the fuse map of a PLD. + This JEDEC file can be written into a corresponding PLD using a special programmer. + At the moment, circuits of the type GAL16v8 and GAL22v10 or fuse map compatible + devices are supported. + + + + + The chips in the + + ATF150x + + family are simple CPLDs with up to 128 macrocells. They are available in a + PLCC package, which makes them suitable for laboratory exercises: If an IC is destroyed during + exercises, + it can simply be replaced. In addition, with the + + ATDH1150USB + + an easy to use, low-cost programmer is available. This programmer is able to program the + + ATF150x + + chips in system using a JTAG interface. + A suitable evaluation board + + (ATF15XX-DK3-U) + + is also available. + The software + + ATMISP + + , + which is available on the ATMEL/Microchip website, is required for programming the chips. + + + Unfortunately, the fuse map details are not publicly available so that no suitable fitter for this chip + can be integrated in Digital, as is possible with the GAL16v8 and GAL22v10 chips. + + + Therefore, the fitters fit150[x].exe provided by ATMEL must be used. These programs create a + JEDEC + file from a suitable TT2 file which can then be programmed on the chip. Digital + starts the fitter automatically every time a TT2 file is created. For this purpose, the path to + the + fit150[n].exe + fitters must be specified in the settings. + The created JEDEC file can then be opened and programmed directly with + + ATMISP + + . + + + For legal reasons the fitter fit1502.exe can not be distributed with Digital. However, it can be + found in the folder WinCupl\Fitters after installing + + WinCupl + + . + + WinCupl + + is available on the ATMEL/Microchip website. + On Linux systems, the fitters can also be executed by Digital if wine is installed. + + + + + A circuit can be exported to VHDL or Verilog. A file is generated which contains the complete + description + of the circuit. The generated VHDL code was tested with + Xilinx Vivado + and the open source VHDL simulator ghdl. + The Verilog code is tested with the Verilog simulator Icarus + Verilog. + + + If a circuit contains test cases, the test data is used to generate a HDL test bench. This can be used + to check the correct function of the circuit in a HDL simulation. + + + Additional files which are needed by special boards can be created. At present only the + BASYS3 + board and the Mimas boards + Mimas + and + Mimas V2 + + are supported. + A constraints file is created, which contains the assignment of the pins. The description of the pins + can + be found in the boards data sheet, and must be entered as a pin number for the inputs and outputs. + + + At a BASYS3 board, if the circuit clock frequency is low, a frequency divider is integrated into the HDL + code to divide the board clock accordingly. + If the clock frequency selected in the circuit exceeds 4.7MHz, the MMCM unit of the + Artix-7 is used for clock generation. + This ensures that the FPGA resources provided for the clock distribution are used. + This allows the included example processor to run at 20MHz, and if you can do without the + multiplier, 30HMz is also possible. + + + + If a circuit is to run on a BASYS3 board, a new project can be created in Vivado. + The generated VHDL file and the constraints file must be added to the project. + Once the project has been created, the bitstream can be generated and the Hardware-Manager can be used + to program a BASYS3 board. + + + In order to create the required constraints file in addition to the HDL file, the corresponding board + must be configured in the settings. In the field "Toolchain Configuration" the corresponding XML file + can be selected. + The available configurations can be found in the folder examples/hdl and have the file + extension .config. + If the configuration was successfully integrated, a further menu appears, which makes the board + specific functions accessible. + + + + + + Although Digital has some options that determine the appearance of a circuit when it is embedded in + another, in some cases it may be useful to use a very special shape for a subcircuit. An example is + the representation of the ALU in the processor included in the examples. This chapter explains how to + define such a special shape for a circuit. + + + Digital does not provide an editor for creating a special shape. Instead, a small detour is required + for creating circuit shapes: First, the circuit is opened, which is to be represented by a special shape. + Then an SVG template is created for this circuit. In this template, the circuit is represented by a + simple rectangle. It also contains all the pins of the circuit, represented by blue (inputs) and + red (outputs) circuits. To see which circle belongs to which pin, you can look at the ID of the + circle in the object properties. This ID has the form pin:[name] or pin+:[name]. + In the latter variant, the pin is provided with a label if reimported to digital. + If you do not want such a label, the + can be removed. + + + This SVG file can now be edited. The most suitable is the open source program + Inkscape + which is available for free. + The pins can be moved freely, but are moved to the next grid point during the reimport. + + + If existing SVG files are to be used, it is easiest to open the created template and paste the + existing graphic into the template via Copy&Paste. + + + If the file was saved, it can be imported with Digital. The file is read in and all necessary + information is extracted and stored in the circuit. For further use of the circuit, the SVG + file is no longer required. + + + A final remark: SVG is a very powerful and flexible file format. + It can be used to describe extremely complex graphics. The Digital importer is not able to import all + possible SVG files without errors. If a file can not be imported, or does not appear as expected, + some experimentation may be required before the desired result is achieved. + + + + + It happens that a subcircuit has been created, and this is to be used in different variants. + For example, you can imagine a special counter that is needed for different bit widths. + If one would create a partial circuit for 4, 5 and 6 bits each, the maintenance of the circuit + would be difficult in the future, since one must always work on several subcircuits, which are + identical except for one parameter, the bit width. + + + To prevent this, a generic partial circuit can be created which can be parameterized. + For this purpose, the checkbox "Circuit is generic" must be set in the circuit setting of the circuit. + Then the parameter dialog of each component of the circuit contains the additional field "generic + parameterization". In this field program code can be entered, which can change the parameters of the + component. Each parameter has a name and can be modified as an attribute of the field this. + The names of the parameters can be found in the help dialog of the component. + If you want to change the bit width of an adder, the line this.Bits=int(1); can be used. + Constants - here the one - are always of type long, but the bit width is an int. + Therefore the type conversion to an int is necessary. + + + In this way, however, it is not yet possible to create a circuit that can be parameterized. + It is still necessary to access parameters that are set when the circuit is used. + This is done via the field "args". If you want to set the bit width from outside, you can write: + this.Bits=int(args.bitWidth);. The name of the argument - here bitWidth is arbitrary. + If this partial circuit is used, this argument must be set. + + + If the circuit is used and the parameter dialog of the embedded circuit is opened, it also has a + field "generic parameterization". Here the bit width to be used can be set with the instruction + bitWidth:=5;. + + + In this way, no wires or components can be removed or added. Nevertheless, many circuits can be + realized with a trick. This is achieved by replacing one circuit with another, depending on the + arguments. For this purpose the function setCircuit([Name]) is available. + If it is called in the definition part of a subcircuit, the circuit to be inserted can be replaced + by another circuit. This allows the recursive definition of a circuit. As in other programming + languages, a suitable termination condition must be ensured. + + + The examples/generic folder contains an example of a Gray code counter whose bit width can + be configured. Here a Gray code counter is constructed by recursively adding further bits to an + initial circuit until the required number of bits of the counter is reached. + + + + + If students are to complete exercises with Digital, it can be helpful if the circuits submitted by the + students can be checked in an automatic process. To perform this check, Digital can be started + from the command line. The call is done as follows: + + + + java -cp Digital.jar de.neemann.digital.testing.CommandLineTester [file to test] [[optional file with + test cases]] + + + + If only the file to be tested is specified, the test cases in that file are executed. In this way, the + test cases created by the students themselves can be executed. + + + If a second file name is specified, the test cases are taken from the second file and the first circuit + is checked with these test cases. The second file will therefore usually contain the sample solution + whose test cases are complete and correct. The circuit contained in the second file is ignored. + Only the test cases are taken from it. + + + In order to test a submitted circuit against a sample solution, the signal names of the inputs and + outputs in both circuits must match. + + + + + How to move a wire? + Select one of the end points with the rectangular selection. Then move this point using the mouse. + You can also select a wire with CTRL + mouse button. + + + + How to delete a wire? + Select one of the end points and press DEL or click on the trashcan. + You can also select a wire with CTRL + mouse button. + + + + How to move a component including all the connected wires? + Select the component with the rectangular selection. The selection must include the entire + component. + Then move the component including the wires using the mouse. + + + + There is a component not connected to a wire, even though the pins are on the wire. + A pin is only connected to a wire if the wire has an endpoint at the pin. + + + If the names of the pins in a circuit are long, the names are no longer readable when + the circuit is embedded. What can I do? + + The width of the block can be increased using the menu item + EditEdit circuit attributes + + . + + + + The pins in an embedded circuit have an non-optimal order. How can this be changed? + The sequence can be changed using the menu entry + EditOrder inputs + + or + EditOrder outputs + + . + + + + + When the simulation is started, a wire becomes gray. What does that mean? + The colors light green and dark green are used to represent high and low state. + Gray means the wire is in high Z state. + + + + I have a truth table. How to calculate the minimized boolean equations? + In the menu Analysis select the entry Synthesise. Then enter the truth table. + At the bottom of the window you can find the matching boolean equation. If you enter more than one + dependent variable, a new window opens in which all boolean equations are shown. + + + + I have entered a truth table, but there is more than one boolean equation shown. + Which of them is the correct one? + + Minimizing a boolean equation can result in many equations, describing the same function. + Digital shows all of them and they all create the same truth table. + There may be differences depending on the "don't cares" in the truth table. + + + + I have a truth table. How to create a circuit representing the truth table? + In the menu Analysis select the entry Synthesise. Then enter the truth table. + You can edit the table using the New or Add Columns menus. + In the menu Create you can create a circuit using the Circuit item. + + + + How to edit a signal's name in the truth table? + Right click on the name in the table header to edit the name. + + + I have a boolean equation. How to create a circuit? + In the menu Analysis select the entry Expression. Then enter the expression. + + + + How to create a truth table from a boolean equation? + In the menu Analysis select the entry Expression. Then enter the expression. + Then create a circuit and in the menu Analysis use the entry Analysis to create the truth + table. + + + + How to create a JEDEC file from a given circuit? + In the menu Analysis select the entry Analysis. Then in the menu Create in the + new + window choose the correct device in the sub menu Device. + + + + When creating a JEDEC file: How to assign a pin number to a certain signal? + At the corresponding inputs and outputs you can enter a pin number in the settings dialog of the + pin. + + + + I have created a JEDEC file. How to program it to a GAL16v8 or GAL22v10? + + To program such a chip a special programmer hardware is necessary. + + + I have created a circuit that I want to use in many other circuits. + How can I do this without copying the file over and over again into the appropriate folders? + + The circuit can be saved in the "lib" folder. Then it is available in all other circuits. + + + + + + Starts or stops the simulation. + Opens the measurement table dialog. + Run to Break + Execute test cases + A single clock step (Works only in a running simulation and only if there is a single + clock component). + + Execute a single gate step. + Execute all single gate steps until the circuit has stabilized or, + if a break component is present, until the break. + + Analysis of the circuit + Select all. + Cuts the selected components to the clipboard. + Copys the selected components to the clipboard. + Inserts the components from the clipboard. + Duplicate the current selection without modifying the clipboard. + While inserting this rotates the components. + Inserts the last inserted component again. + Inserts a new tunnel. + New circuit. + Open circuit. + Save the circuit. + Undo last modification. + Redo the last undone modification. + Programs a diode or a FG-FET. + While drawing a wire switches to the diagonal mode. + While drawing a line flips the orientation. + Splits a single wire into two wires. + Abort the current action. + Removes the selected components. + Removes the selected components. + Increases the number of inputs at the component the mouse points to. If it is used with + constants, the value is increased. + + Decreases the number of inputs at the component the mouse points to. If it is used with + constants, the value is decreased. + + Zoom In + Zoom Out + Fit to size + Show or hide the components tree view + + + \ No newline at end of file