JLSCircuitTester

JLSCircuitTester is an extension to the JLS digital logic simulator that allows users to automatically test circuits (including CPUs) constructed using JLS. Our main goals for this project are to

1. encourage students to more thoroughly test their circuits by simplifying the generation and running of tests; and
2. save instructors time by automating the testing of student circuits.

To test a circuit, users run a command-line program named jlsCircuitTester that takes (1) the file name of the JLS circuit under test and (2) the name of a script describing one or more input sets. (A input set lists the desired input for each input pin, register, and memory object.) For each input set, jlsCircuitTester simulates the circuit under test, compares the observed results (output pins, registers, and memory) to the expected results, and reports any discrepancies.

For CPUs, users run a command-line program named jlsCPUTester that takes (1) the name of the .jls file under test and (2) the name of a MIPS assembly file. The program then assembles and simulates the assembly file and compares the final states of the registers and memories to those of the simulated CPU.

Features

Named value lists

Users can specify several input sets at one time by providing a list of values for a given input pin. These lists can be given a name and used in several tests.

Programmed value lists

JLSCircuitTester also provides some "programmed" lists of common test cases including ranges, "corner cases" (e.g., values around powers of 2), "templates" (e.g., the eight values that match the pattern 1???0), and random values.

The ability to use Java classes to compute expected output values.

Users can specify the expected simulation results in one of two ways: First, they can simply list the expected results along with the desired inputs for each test. This technique works well for simple circuits like a half adder. (See this example input file.) However, listing the output can become tedious for more complex circuits (e.g., ALUs or CPUs). Thus, JLSCircuitTester allows users to specify a Java class to compute the expected results. This technique is especially useful (1) in combination with input sets specified using value lists, and (2) when testing CPUs.

Obtaining

• The latest version of JLS. (JLS is a separate product from David Poplawski at Michigan Tech.)
• jlsCircuitTester.jar: The jar file containing all our code.
• jlsCircuitTester or jlsCircuitTester.bat : scripts to simplify the launching of the circuit tester.

• The MARS MIPS Simulator. (MARS is a separate product from Ken Vollmar and Pete Sanderson.)
• jlsCPUTester or jlsCPUTester.bat: scripts to simplify the launching of the CPU tester.

Alternately, JLSCircuitTester.tar contains all of the aforementioned files.

Basic Usage

• Put JLS.jar, jlsCircuitTester.jar, and jlsCircuitTester all in the same directory.
• Run jlsCircuitTester circuitName.jls inputSetFile, where circuitName.jls is the name of a JLS circuit, and inputSetFile is the name of a text file describing the sets of inputs to test. (An "input set" is a set of initial values for the circuit's input pins, registers, and/or memory.)

To test MIPS-like CPUs:

• Put JLS.jar, Mars.jar, jlsCircuitTester.jar, and jlsCPUTester all in the same directory.
• Run jlsCPUTester circuitName.jls assemblyCode.a, where where circuitName.jls is the name of a JLS circuit, and assemblyName.a is the name of a file containing MIPS assembly code (the same code you would give to SPIM or MARS). Notice that SPIM and MARS will handle code that most student-written CPUs won't (because time constraints will prevent most students from implement every MIPS feature); therefore, make sure the code will work with the CPU being simulated.

Full Documentation

• jlsCircuitTester
• jlsCPUTester
• SimpleGV Input Set format.

Assignments

• Introduction to JLS.
• Build an ALU using JLS.
• Assemble the Single-Cycle CPU from the Patterson and Hennessy textbook (also used by the Harris and Harris textbook).

Future Work

• Allow the user to specify the gate delays and other timings in the input set files.
• Allow the user to specify input values that vary over time.
• Allow users to provide code to compute their own programmed value lists.
• Provide for the testing of circuits built using other simulators. Although we wrote this first release specifically for JLS, we kept the design as general as possible. We hope to eventually package the circuit tester core in such a way that it can be easily extended to work with almost any digital logic simulator. (At present, it appears that such simulators will either need a Java API or a batch mode with a command-line interface.)

Request For Comments

• This is my first attempt to thoroughly document a program I have written. (Previous programs have been simple enough to require only trivial documentation.) If you find anything here to be difficult to understand, please let me know. I won't be offended. In fact, I could use some advice on how to make these pages easier to understand.
• I would appreciate your thoughts on what features would be most useful. I have a long list of ideas for new features; but, rather than clutter the program with features nobody uses, I'll wait until I hear from users about which features will be most useful.
• Of course, please bring any bugs to my attention quickly.

Acknowledgments

• David Poplawski, author of JLS, for his advice and for his work modifying JLS to make it integrate better with JLSCircuitTester.
• Pete Sanderson, co-author of the MARS MIPS Simulator, for his efforts making MARS integrate better with JLSCircuitTester.
• Christan Trefftz for his help with JavaCC.
• Paul Jorgensen and Steve Salerno for their advice on testing.
• Robert Adams for his advice on several different topics.
• Paul R. Hosler Jr. for providing JOpt Simple.

Licenses

• JLSCircuitTester
• MARS
• JOpt Simple
• The JLS license appears upon the first running of JLS.