Introduction to JLS

Although breadboards are a lot of fun to play experiment with, it is very difficult to build anything but very small circuits. (More accurately, it is almost impossible to debug circuits with more than 10 or 15 wires.) Therefore, you will use simulation software when designing and building larger circuits. In particular, this you will be using a circuit simulator from Dave Poplawski at Michigan Tech named JLS (Java Logic Simulator).

The primary objectives for this lab are

• to get JLS set up in your environment,
• to learn how to use JLS,
• to learn how to test your circuits using DLUnit, and
• to build a circuit using JLS.

Pre-lab

As soon as you arrive in lab, demonstrate that you have created at least one circuit using JLS.

Set up JLS

All the JLS code is contained in JLS.jar. If you are using the EOS lab, you will find it in /home/kurmasz/public/CIS351/bin. The easiest way to run JLS is to put this directory in your path. (For most of you, the best way to do this is to add the line export PATH=$PATH:/home/kurmasz/public/CIS351/bin to the end of your .bashrc.) There is a script named jls in this directory that sets up the java classpath and launches JLS. This directory also contains other scripts that will make your life in this course much easier. If you object to adding this directory to your path, you can also launch JLS with this command:
java -jar /home/kurmasz/public/CIS351/bin/JLS.jar/JLS.jar.

To run JLS on your own machine, download JLS.jar. You run JLS by typing java -jar jlsDir/JLS.jar, where jlsDir is the directory into which you saved JLS.jar.

Regardless of where you run JLS, make sure you have the latest version: 4.1.7 (built 16 September 2016).

Learn how to use JLS

Begin by working through the "Introduction", "Full Adder", and "Sign Extender" tutorials. (You may also want to complete the 4-Bit Counter tutorial when we get to registers.) You will find all the tutorials in the Help->Tutorials menu.

As you work through the tutorial, pay special attention to the following details:

• Name your half adder HalfAdder.jls, not ha as suggested by the tutorial.
• Name your sum output Sum, not SUM as suggested by the tutorial.
• Name your full adder FullAdder.jls, not fa as suggested by the tutorial.
• Importing a sub-circuit inserts a copy of the imported sub-circuit into the circuit you are creating. As a result, if you later discover a bug in your sub-circuit, you must re-import that sub-circuit everywhere. It is not sufficient to simply fix the bug in the sub-circuit's jls file. Moral: Thoroughly test your sub-circuits before importing them.

When you are finished, save your half-adder in a file named HalfAdder.jls. Make sure the inputs are named "A" and "B", and the outputs are named "Sum" and "Carry". The program I use to help test your circuits requires the circuits to present a known interface. (In other words, the program needs to know what the input and output pins are named.) If you do not conform to the specified interface (i.e., the given circuit and input names), I will probably not grade your circuit.

Learn how to test JLS circuits

After completing a circuit, your first order of business should be to test it by setting the values of the input pins and examining the values of the output pins. In fact, it is a good idea to test sub-circuits as you build them.

When you have finished building the full adder (as described in the tutorial):

1. Add input pins named InputA, InputB, and CarryIn.
2. Add a "generate test signals" element. (This element is on the toolbar to the right of the "pause" element.). Set appropriate values for the three input pins. (As an example, one line may look like this: InputA 1 end.)
3. Add watches to all the output pins.
4. Place probes on the "Carry" outputs of each component half adder.
5. Open the simulator window, run the simulation, and verify that the resulting output is correct.
6. Change the scale factor from 1 to 5 and observe what happens.

Using the simulator window is a good way to check a few example input/output pairs, or to track down bugs; however, trying to thoroughly test a circuit using this technique would be very tedious and time consuming. Therefore, we provide DLUnit to automate the running of many tests. (Think of it as JUnit for hardware.)

I will use DLUnit to test your circuits. DLUnitwill run your circuit many times with different inputs, and compare the resulting outputs to known values. Practice using this testing setup by testing the half adder you built while completing the tutorial. (Again, make sure the file, inputs, and outputs are all named correctly.)

• in EOS:
  1. Make sure /home/kurmasz/public/CIS351/bin is in your PATH
  2. Download HalfAdderTest.java.
  3. Compile the test: dlunit_compile HalfAdderTest.java
  4. Run DLUnit: dlunit HalfAdder.jls HalfAdderTest.class .
• on your own machine
  1. Download DLUnit.jar.
  2. Download HalfAdderTest.java.
  3. Compile the test: javac -cp DLUnit.jar HalfAdderTest.java
  4. Run java -jar DLUnit.jar HalfAdder.jls HalfAdderTest.class.

To make sure you understand how DLUnit works, deliberately introduce a bug into HalfAdder.jls (e.g., replace the XOR gate with an AND gate) and re-run the test class. (Then fix the circuit once you know what happens when there is an error.)

Build your own circuit

Now that you have had some practice using JLS, it's time to build your own circuit. Build a circuit named "UnsignedFullAdder_16bit" that adds two 16-bit unsigned integers. The simplest way to complete this lab is to implement a ripple-carry adder. However, the upcoming project will offer extra points to those who build an adder that is faster than O(n). Therefore, you may want to get a head start on the project by building a faster adder.

To keep the design manageable, you may want to use one or more sub-circuits (e.g., connect four 4-bit adders, or two 8-bit adders). If you do use sub-circuits, notice that you can unbundle buses into arbitrary groups. For example, you can take a 16-bit bus and split it into 0-3, 4-7, 8-11, and 12-15. In the "Create unbundler" dialog, select "Group bits" instead of "Single bits". (See the "Sign Extender" tutorial built into JLS.)

• Name the inputs "InputA","InputB", and "CarryIn".
• Name the outputs "Output" and "CarryOut". (If you do not name the inputs and outputs correctly, the test script will not run.) The "CarryOut" output should be 1 if, and only if, there is an overflow.
• Test your circuit using SampleUnsigned16BitAdderTest.java). If the test script doesn't work without modification, then you either named your circuit, inputs, or outputs incorrectly.
• SampleUnsigned16BitAdderTest will not completely test your circuit. Add as many tests as necessary to be confident your circuit works.

JLS Shortcuts

Deliverables

• Demonstrate your circuit (and tests) to the instructor.
• Add a text box to your jls files that includes
  • your name,
  • the file name,
  • the assignment name, and
  • the assignment due date.
• Submit the jls files, and any additional test files you used, using Blackboard's Assignment Manager.