50 points
Goals for this asignment
• Design and implement a substantial digital system
• Ad new instructions to the datapath and control
• Use robust testing methodology in digital logic design
• Learn how to load binary code from the assembler into the instruction memory
• Create MIPS programs that adequately test the procesor
Introduction
In project 2-1 you built two major components of a MIPS procesor, and in project 2-2 you wil
build the rest of a procesor. As in part 1, we provide the top-level skeleton file and test circuits,
and you wil provide the implementation and additional tests.
Geting started
1. Download the starter code from
https:/github.com/bmyerz/proj3-starter/archive/proj2-part2.zip
(or, if you are using git, you can instead clone https:/github.com/bmyerz/proj3-starter.git and
then switch to the branch proj2-part2)
2. Try runing the tests
Use the same method for runing Linux comands that you used in part 1 of the project.
i. Run the tests
make p2sc
You should se output like
cp alu.circ regfile.circ mem.circ cpu.circ tests
cd tests python ./test.py p2sc | tee ../TEST_LOG
Testing files...
Error in formatting of Logisim output:
non-integer in ['xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'00000000000000000000000000000000', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']
FAILED test: CPU starter test (Error in the test)
Error in formatting of expected output:
non-integer in ['00000000000000000000000000000000',
'00000000000000000000000000000000', '00000000000000000000000000000000',
'00000000000000000000000000000000', '\n']
FAILED test: func test (Error in the test)
Passed 0/2 tests
The x’s indicate that those bits are disconected.
3. Copy your regfile.circ and alu.circ solutions from Project 2-1 into the new directory.
4. Alternatively, if your project 2-1 solution didn't fuly work and you want to use a working
alternative, we provide some with instructions below.
a. To use the register file replacement
download regfile.circ and cs3410.jar from:
https:/uiowa.instructure.com/courses/65872/files/folder/homeworks/project2
You must put regfile.circ in the base directory of your project (as it was in project 2-1)
and a copy of the cs3410.jar file must go in both the base directory and tests/ directory.
The advantage to using the replacement regfile.circ is that it uses a fancy register file
that shows the values of the registers, which may make debuging a bit easier.
b. To use the ALU replacement
download alu.circ and ALU.jar from:
https:/uiowa.instructure.com/courses/65872/files/folder/homeworks/project2
You must put alu.circ in the base directory of your project (as it was in project 2-1) and a
copy of the ALU.jar file must go in both the base directory and the tests/ directory.
5. You can check if you copied the ALU and register file (whether using yours or ours)
properly into your project 2 folder by runing the part 1 tests and seing that they pass.
make p1
cp alu.circ regfile.circ tests
cd tests python ./test.py p1 | tee ../TEST_LOG
Testing files...
PASSED test: ALU add (with overflow) test
PASSED test: ALU arithmetic right shift test
PASSED test: RegFile read/write test
PASSED test: RegFile $zero test
Passed 4/4 tests
6. When you start editing the cpu.circ file, you'l want to include the ALU and register file
components by chosing Project > Load Library > Logisim Library.. and choosing the
alu.circ or regfile.circ in the base directory of your project folder.
The processor
Your team’s task is to design, implement, and test a single-cycle MIPS procesor.
The procesor must suport a specific subset of instructions from the 32-bit MIPS instruction
set architecture. That subset is
The specification of the instructions is exactly the one in the “MIPS reference card” or “Human-
friendly MIPS reference card” on the Resources page
http:/homepage.cs.uiowa.edu/~bdmyers/cs2630_fa17/resources/ except for the following
differences.
Instruction differences
jal – Jump and Link – The reference shet might say to store PC+8 into $ra, but you must
instead use PC+4. (Our architecture wil not assume a jump delay slot; neither does MARS by
default).
clz (Count Leading Zeroes) instruction
The clz is a MIPS instruction that was not covered in the class, but you can understand its
behavior. and bit encoding by loking at the help in MARS. HINT: you can implement a clz
circuit with a combination of some components available in the Arithmetic library.
What you must implement
You must modify cpu.circ to implement the CPU. Do not modify or move the inputs and
outputs. You may use sub-circuits in your implementation as long as remains the
top level circuit of cpu.circ. You may use any built-in Logisim components.
For your Data Memory, you can use mem.circ. That module can read or write one memory
location on every cycle. When Write_En=1, the memory wil write data Write_Data to the
location given by Adres on the next rising edge of the clock, and when rite_En=0 the
Read_Data port wil have the value at the location given by Adres.
Tips on building the control unit
Building a control unit can be very complex and eror prone due to the large number of input
and output bits, so you should try to reduce complexity where posible. Specifically,
• Rely on a logic analyzer, such as Logisim's logic analyzer tool (found at Project | Analyze
circuit). It wil allow you to input a function as a truth table and automatically generate
the circuit. Note that the logic analyzer requires 1-bit inputs, so you'l have to split multi-
bit wires into individual bits.
• Use "don't cares" to simplify the logic (the logic analyzer represents them as X's)
• Consider separating the logic that computes the basic 1-bit control signals from the logic
that computes the ALU's switch input.
How you must test
1. Run the tests with the comand make p2sc.
2. To ensure you pass the autograder, you must test your CPU beyond the given tests.
Ading new tests is similar to Project 2-1, except:
• the sample test harnes to copy is tests/CPU-starter_kit_test.circ instead of alu-
harnes.circ and regfile-harnes.circ.
• instead of loading the test inputs into RAMs, you wil load the instruction
memory with an assembled program (and optionally your data memory).
Se the section “Asembling and runing new programs” for a step-by-step guide.
Se the get_test_format function in tests/decode_out.py for the format of the output of
the "cpu" tests. The first list is the headers and the second list is the bit widths.
['$s0 Value', '$s1 Value', '$s2 Value', '$ra Value', '$sp Value', 'Time Step', 'Fetch Adr',
'Instruction'], [32,32,32,32,32,8,32,32]
Testing tips
• Since there is some efort to adding a new test, try to balance keping the tests simple
while including multiple instructions
• Make sure to check diferent cases, such as branch, not branch, branch forward, branch
backward
• Having to give the expected values of the 5 registers, fetch Adres, and instruction bits
on every single clock cycle can be overkil for more complex tests. To help you, we've
included diferent types of tests that check only some of the outputs.
Type Checks outputs Recomendation
cpu '$s0 Value', '$s1 Value', '$s2
Value', '$ra Value', '$sp Value',
use for short/simple tests,
where you want to check
everything on every cycle
'Time Step', 'Fetch Adr',
'Instruction'
cpu-lite '$s0 Value', '$s1 Value', '$s2
Value', '$ra Value', '$sp Value',
'Time Step'
use for tests where you
don’t want to have to
check fetch addres and
instruction
cpu-end '$s0 Value', '$s1 Value', '$s2
Value', '$sp Value'
use for tests where you
only want to check the
state of some registers
when they change.
Note: To understand why cpu-end tests do not check outputs every cycle, rather only
when the registers change, it is helpful to know that Logisim only prints a new line of
output when one of the output values change. For cpu and cpu-lite, the inclusion of
"Time Step" ensures that a line gets printed every cycle.
You specify the test Type by making the last argument to TestCase be "cpu", "cpu-lite", or "cpu-
end" in your tests.py file.
We have provided an example "cpu-end" test called func_test. To use it, you ned folow the
directions described in the next section. The directions describe a diferent test, but you will
learn the steps you ned to create a test harnes called func_test.circ and loading its instruction
memory with the binary code generated by assembling func_test.mars.s.
Assembling and runing new programs
The project kit comes with a copy of Mars (mars.jar) so that you can assemble MIPS programs
in the format required for the instruction memory. What folows is the workflow that we
recomend for writing MIPS programs and runing them on your procesor.
1. Edit your MIPS program in MARS (as you did in HW2,3).
You should set the folowing “Memory Configuration…”, to tel MARS to assemble the
addreses the same way our comand line assembler does (.text starts at addres
0x0000 and .data starts at address 0x00002000)
2. Test and debug your program in MARS (as you did in HW2,3).
3. Save your MIPS program to a file. We’l assume the name “fo.s” for these directions,
but you should name the file appropriately.
4. When you are ready to run your program on the MIPS procesor, you wil use the
assembler provided with the project kit.
Make sure you know the file path of your MIPS file. It’s easiest if you just save it to the
proj2-part2 folder.
i. Change directories to path of your proj2-part2 folder
cd /path/to/proj2-part2 (/path/to should be the actual file path)
ii. Double check that the MIPS program is in your directory by running ls.
Makefile
TEST_LOG
alu-harness.circ
alu.circ
cpu.circ
example_IO_controller.circ
foo.s
mars-assem.sh
mars.jar
mem.circ
regfile-harness.circ
regfile.circ
run.circ
tests
text-out.hex
iii. Run the assembler on your MIPS program
./mars-assem.sh foo.s
If your assembly file didn’t have a .data section you might se a mesage, but it is
just a warning.
This segment has not been written to, there is nothing to dump.
cat: data_t.hex: No such file or directory
rm: data_t.hex: No such file or directory
iv. List the files in the folder again (by running ls) to check that there was output.
Makefile
TEST_LOG
alu-harness.circ
alu.circ
cpu.circ
example_IO_controller.circ
foo.s
foo.s.data.hex
foo.s.text.hex
mars-assem.sh
mars.jar
mem.circ
regfile-harness.circ
regfile.circ
run.circ
tests
text-out.hex
You should se a .text.hex file, which contains the text segment. If you had a .data section, you
should also se a .data.hex file, which contains data memory contents up to and including the
.data segment.
5. Now you can load the program into your procesor in Logisim. Make a copy of CPU-
starter_kit_test.circ and then open that new file in Logisim.
i. Load the instruction memory by right-clicking the Instruction Memory ROM and
chosing Load Image..
Navigate to the fo.s.text.hex file
ii. Load the data memory (OPTIONAL; only ned to do this step if your MIPS program
has a .data section). The data memory implementation is provided to you in
mem.circ, which you should use as a “Logisim library…” in your CPU.
right-click the RAM | Load image | navigate to fo.s.data.hex
You can double-check that your data was loaded into the expected addres in memory
by right clicking the RAM > Edit Contents… > and scroling down to the row for 0200 to se
the data.
iii. Make sure to Save the circuit file containing the instruction memory so that you
don’t have to load the program again (just like you had many test harneses in Part
1, you wil just have another copy of CPU-starter_kit_test.circ for each test
program).
Note that you wil have to load your data memory each time you change
programs or “Reset Simulation”. Logisim applies the reset to RAMs but not ROMs.
Therefore, we sugest making most tests not have a .data section so that you don't
have the inconvenience of loading the RAM.
6. Now you can simulate your CPU by ticking the clock. Notice that once the instruction
memory gets to instructions 0x0000, your procesor should just be executing
NOPs until you stop the simulation.
Input/output
You now have a procesor that executes real MIPS programs! Now it is time to make it more
interesting by including some IO devices. We wil use a methodology for IO called Memory
mapped IO (MMIO). You already have some experience with it from the drawing application in
HW 3.
The way MMIO works is that some range of addreses is reserved for controling IO devices
rather than accesing memory.
If you lok back at MARS's Memory Configuration (Settings > Memory Configuration), you'l se
that addreses starting at 0x007f0 are reserved for MMIO.
An output device wil take in the same Adres/MemWrite/WriteData signals as the data
memory, except it wil listen for its range of addreses (0x007F0 and above). When
MemWrite=1 and the Adres is in range, the output device wil be written to.
We've provided an example module in example_IO_controller.circ. It is a single LED
that can be turned on by writing a 1 to addres 0x007F0 and turned of by writing a 0 to
addres 0x007F0.
There are more IO devices besides the LED available in Logisim's Input/Output folder.
You can experiment with how they work. Post to Piazza discusion if you have trouble
understanding how to control one of them.
What you must do
Your task is to implement an interesting application that uses some input and/or output device.
i. Build an IO controler for the device that you want to use and attach it to the
appropriate signals in your CPU. Your IO device should be placed in the top-level of
cpu.circ. The device should be more than the single LED example (i.e., at least two
LEDs but other devices are encouraged). Write as short of a MIPS test program as
possible that wil read or write (depending on if you picked an input or output) the
device.
ii. Write a second, more interesting MIPS program, that uses your IO device(s). Maybe
it is a timer, an animation, a calculator, a scren and keyboard, a game. The sky is
the limit here! Include a file io_readme.txt that briefly describes how your
application works. Also, tel us which Tick Frequency the application works best at.
iii. Pat yourself on the back. You've built a working and useful computer! Show of your
work to others. (just don't share copies of your files)
Grading
• 35 points – the procesor passes the autograder tests; the tests you submit demonstrate
good coverage of the instructions
• 4 points - clz instruction and a small test program should show that clz works including
various corner cases. Also include the expected output in tests.py and a test harnes file.
• 5 points - attach one or more IO devices. A small test program should show the device
works with the CPU.
• 4 points - dificulty of the IO device (we'l take the highest if you have multiple)
o 0 points: single LED (output)
o 1 point: 2+ LEDs (output)
o 2 points: 7-segment (output), hex display (output)
o 3 points: button (because input takes more thought), LED matrix, joystick,
several 7-segment/hex displays
o 4 points: keyboard, TY
• 2 points - overall originality of the "interesting MIPS program". Note that this one can be
graded independently of the dificulty of the IO device. For example, you might come up
with a program where the blinking of a single LED means something interesting (morse
code?!). Conversely, filing an LED matrix with all gren pixels is not that interesting.
Additional requirements
1. You must suficiently document your circuits using labels. For sub-circuits, label all
inputs and outputs. Label important wires descriptively and label regions of your circuit
with what they do.
2. You must make your circuits as legible as posible. Learn to make use of tunels when
they wil save on mesy wiring. (see
http:/ww.cburch.com/logisim/docs/2.6.0/en/libs/base/tunel.html)
Submision checklist
ü Your circuits don’t have any erors (Red (E) or orange (wrong width) wires). You ought to
avoid blue (X) wires, too.
ü make p2sc runs the tests without crashing
ü Your circuits pass the original tests
ü Your circuits pass additional automated tests that you have written
ü You made a zip file proj2-2.zip that contains these files in the folowing directory
structure:
1. cpu.circ (your completed CPU)
2. mult_test.s, mult_test.circ (your test of the thre multiply related instructions)
3. tests/
§ any additional files you’ve added for your testing
§ Includes
• your test harnes files (i.e., the copies of CPU-starter_kit_test.circ,
renamed appropriately, and with instruction memory loaded
appropriately)
• the MIPS asembly files that you used for your tests
• tests.py (because you wil add to this file if you use our testing
methodology)
• .out files you’ve added to tests/reference_out (although we
recomend putting your expected outputs in test.py as a list of
lists)
• 1 .s file and .circ file test harnes for your "simple" IO program
• 1 .s file and .circ file test harnes for your "interesting" IO program
§ Excludes
• generated files such as the .hex files
ü Double-check your zip file that it contains the correct versions of your files
ü As a team: One submision by any team member for the team. You are responsible for
the contents all being in there on time. You have two options for submision
1. Upload proj2-2.zip to ICON "Project 2-2: A MIPS Procesor"
2. Submit via github.uiowa.edu instead. To do so, put your files on a private
repository on github.uiowa.edu, add csthomps, dmcdermott, and bdmyers as
colaborators, create a tag called "final_submision", and on ICON "Project 2-2: A
MIPS Procesor" use the text box to provide the link to your repository.
ü As a team: kep submitting a wekly update approved by all team members to "Project
2: Evaluation X" assignments on ICON.
Recommended aproach to finishing the project
This project involves lots of implementation and testing (both circuits and MIPS code). We
highly recommended that you get to a basic working processor quickly, which passes some
simple tests with suport for limited number of instructions and then add complexity from
there. (Notice that in the textbok and lectures on MIPS procesor design, complexity was
added incrementally). During grading,
a) a CPU that passes many tests but is missing instructions
wil be given more credit than
b) a CPU that passes 0 or a few tests but atempts to suport all instructions
Tips
• Do not waste your time writing the instruction memory hex files manually. You should
be writing MIPS source programs in MARS. Leave the assembling to the assembler (See
the section above called “Asembling and runing new programs”).
• Be aware that runing the tests wil copy alu.circ, regfile.circ, cpu.circ, and mem.circ into
the tests/ directory. You should not modify those copies (tests/alu.circ, tests/regfile.circ,
tests/cpu.circ, tests/mem.circ) because you risk getting mixed up and losing work.
• Do not leave testing until the last minute. You should be testing as you finish each
instruction.
• Do not rely on just the provided tests. You must add more. The autograder wil test your
circuits extensively. If you fail most of the autograder tests, you will receive a poor
grade.
• Do not rely solely on manually testing your circuits (i.e. poking inputs in the Logisim GUI
and loking at the output). Manual testing is both time-consuming and eror-prone. You
should either extend the automated tests (as described in the testing sections of this
document) or come up with your own automated testing approach.
Teamwork tips
• It is your responsibility to kep in contact with your team and notify the staff as early as
posible (the wekly status report is best but email if you are betwen updates) if
coperation problems arise that your team cannot resolve on its own. Often, isues can
be remedied if recognized early. The staff's role in problem solving wil be to facilitate
team discussions and not to criticize individual team members.
• Although we do not require you and your team to use a version control system (e.g., git
or svn), we highly recommend doing so to kep track of your changes. If you use version
control just be aware that merging .circ files wil corupt them (unlike plain text files), so
avoid working on the same file concurently to avoid merge conflicts all together. Ask
the staff for help if you get stuck!
• Logisim circuits are hard to colaborate on unles you break them up into pieces.
Therefore, you should break up the work among the group members. Some ideas to
break up the work are:
o diferent members work on different sub-circuits
o designs and truth tables + test cases/programs
o datapath design/implementation + control design/implementation + test
cases/programs
• Slip days: refer to the sylabus
Where to get help
Go in this order:
1. Lok for the answer in this document.
2. Refer to the readings and class notes. For example, the design of a procesor with a
small number of instructions is given in the textbok (of course, you’l want to make
sure you build yours to the specifications given in this project document).
3. Get help from your teammates.
4. Find other students to discus isues at a high level. However, do not share
programs or circuit files outside of your team.
5. Refer to the discusion board on Piazza and ask questions there.
6. Ask the staff in class, DYB, or ofice hours.
Academic honesty
We remind you that if you do chose to reuse sub-circuits designed by someone outside of your
team that you clearly cite where they came from. Not citing your sources is plagiarism. You are
strictly prohibited from loking at solutions to other versions of this project. The staff wil be
checking design .circ files against similar past projects.