CS 270
cs270 Programming Assignment - LC3 Simulator

P8A and P8B: LC-3 Simulator (200 points)

See the Progress page of the course web site for due dates


UPDATED (Dec 04) - P8.a

A problem was discovered with the hardware.o contained in the P8.a library. You should download the appropriate P8.a libraries to match the operating system you are using. You must then place it in your source directory and rename it to P8.a.


About The Assignment

In this assignment you create part of the LC-3 simulator. Upon completion, you will have a fully functional LC-3 simulator, identical to the one you have used this semester. In particular, you will be implementing functions in a single file logic.c.

Several functions are provided for you. You will add functions to the code to complete the implementation. Most of the functions should be several lines. The complexity lies in understanding the pieces of the simulator and how they fit together. There will be a fair amount of duplicated or similar code that you may wish to extract into separate functions. The LC-3 Datapath diagram and LC-3 Visualizer may help identify shared elements used by different instructions.


Getting Started

  1. Create a directory for this assignment and cd there.
  2. Download the file appropriate for your OS
  3. Unpack the P8.XXX.tar file. This will create a subdirectory P8 containing all of the files for the project.
        tar -xvpf P8.XXX.tar
  4. cd P8 and do all your work in that directory
  5. Review the Makefile and make sure the variable GCC is appropriate for your C compiler. Also, verify that sed in in your $PATH. This will be OK for the department linux machines.
  6. Examine the files install.c.MASTER and mysim-tk.MASTER and look for the string abs_path_to_install_dir. It occurs once in each file.
  7. Configure the build by
        ./fixPath install.c mysim-tk
    Examine the files install.c and mysim-tk and verify the string has been replaced by the path to this directory. This script uses sed and will not work if it is not in your $PATH or is not available. In this case, you may use an editor to update the files.
  8. Build mysim using the command
        make
    You should see the following on linux.
    
        gcc -g -std=c11 -Wall -c -DSTACK_OPS -DDEBUG Debug.c
        gcc -g -std=c11 -Wall -c -DSTACK_OPS -DDEBUG install.c
        gcc -g -std=c11 -Wall -c -DSTACK_OPS -DDEBUG logic.c
        gcc -g -std=c11 -Wall Debug.o            install.o       logic.o P8.a -o mysim
        
  9. Run the simulator using ./mysim-tk -norun or ./mysim -norun if you prefer the command line version.
  10. Inspect the memory at address 0x200. The is the LC-3 operating system code. You will not be able to execute this code until you complete the missing instructions.
  11. Test some code using the ADD immediate and ST instructions that are already implemented. Create the following simple program with an editor and assemble it using lc3as. Load the assembled program. Single step the program and monitor its operation. This will verify everything is working before you start making changes. Do not proceed until this works correctly.
    
              .ORIG x3000
        STORE .BLKW 1
              ADD R1, R1, #7
              ST R1, STORE
              HALT
              .END
  12. Exit the simulator.

Completing the LC-3 ADD instruction

The initial implementation of execute_ADD() only supports the immediate version of the ADD instruction. Compare the implementation with the definition of the instruction in Appendix A of the book and the LC-3 Visualizer. Complete the implementation of the LC-3 ADD instruction. This only requires a small change to the code.
  1. Add code to execute_ADD() to handle the SR2 version of the instruction.
  2. It is best to make small changes on this assignment, so do a make and fix any problems.
  3. Add some code to your test file.
  4. Start your simulator, load your test file, put values in the registers and step your program. If it works, you will see the sum in the appropriate register. If not, read your code and try to figure out what is wrong.
Congratulations, you are done with one instruction. You are really a lot further along that that.

You should be able to finish the AND and NOT instructions with minimal effort.


Completing more LC-3 instructions

Beyond the arithmetic instructions you have implemented, the remaining LC-3 instructions involve addresses. Recall that part of the executon requires computing the effective address for use by the instruction. The ST instruction is already implemented. You may find the LC-3 visualizer useful in understanding this implementation so you can proceed on the other instructions.

You can now complete the remaining instructions using these steps.

  1. Select one unimplmented LC-3 instruction to work on (e.g. LD).
  2. Understand what information is needed to simulate this instruction using the LC-3 Visualizer.
  3. Add a function call to logic_execute_instruction() to handle this LC-3 instruction. Then add the function header and body to implement this instruction. If you follow the pattern you see in the provided code, your code will be easier to write and debug.
  4. You may find it helpful to extract duplicate/similar code into functions that can be shared by instructions.
  5. Rebuild your simulator using "make" after you finish the instruction.
  6. Create test cases in an instruction specific test program to verify the instruction. You should probably set up regression tests similar to those shown in the graded output of previous assignments.
  7. Run the simulator and test the instruction thoroughly.

For this assignment, you can assume that all input programs are correct in the following ways:

In other words, you do NOT have to do any error checking in this assignment.

TEST! TEST! TEST! Once you are happy, execute the simulator without the -norun. The OS will now load and print out the welcome message. This is a good test of your work because many (but not all) of the LC-3 instructions are used in the OS. You can also set up regression tests that compare the output of ~cs270/lc3tools/lc3sim with mysim.


Debugging your code

Debugging this code is somewhat different from other programs because you do not have source code for ALL the modules.

You may find it useful to run your simulator and the class simulator (from ~cs270/lc3tools) side by side and single step both of them and compare what you see.

If you like to do debugging with printf(), you may do so, but you will NOT be able to use the GUI version of the simulator. This is because printf() is used to to send data from the simulator to the GUI and your printf() may cause the GUI to die. The command line version of the simulator (mysim) has no problems with additional output. However, grading WILL be affected, so you must turn off any degugging in the code you submit!

Even though you do not have all the source code, you may use gdb for debugging.

If you are comfortable with the console lc3 simulator, you may use gdb as you were shown in earlier recitations. Simply do the following:

  1. gdb mysim
  2. Set gdb breakpoint(s) as necessary in the various functions in logic.c. This is the only file you are modifying for this assignment. The general gdb syntax is break functionName
  3. run -norun This start the lc3 simulator, but does not execute any LC3 code. The lc3 simulator program is running, but will halt at any mysim breakpoints you have set.
  4. use the console commands of the lc3 simulator to exercise your code. When you hit a gdb breakpoint, control will transfer to gdb.
  5. when your use of the gdb facilities is complete, use continue to return control to the LC3 console.

If you prefer the GUI version of the lc3 simulator, you may still use gdb but you will need to do several additional steps.

  1. Start the GUI version of the simulator (mysim-tk).
  2. Determine the processID of your simulator. In a terminal, do a
        ps -fu yourLogin | grep mysim
    and you will see several processes listed. One will be the grep, one will be the mysim-tk and the third will be the actual simulator mysim. The process ID will be the first number on the line.
  3. Run gdb
  4. Use the gdb command attach processID and gdb will be attached to your simulator.
  5. Set gdb breakpoint(s) as necessary in the various functions in logic.c. This is the only file you are modifying for this assignment. The general gdb syntax is break functionName
  6. continue This resumes the lc3 simulator.
  7. use the GUI to interact with the lc3 simulator. If you hit any gdb breakpoints, you will then need to work with the gdb console.
  8. when your use of the gdb facilities is complete, use continue to return control to the LC3 GUI.
Note that there are two kinds of breakpoints under these circumstances, those that stop the simulated execution of an LC3 program at a certain LC3 address in simulated memory, and those of GDB stopping the execution on a given C statement of the simulator.

Grading Criteria

Preliminary Testing - P8A (50 points)

You will submit the single file mysim.tar using the checkin program or the Checkin tab of the web page. This file may created by executing make submission. The mysim.tar file should only contain your logic.c file. Type:
    ~cs270/bin/checkin P8A mysim.tar

We will check that the program compiles and test the execution of the ADD, AND, NOT, and ST instructions.

Final Testing - P8B (150 points)

You will submit the single file mysim.tar using the checkin program or the Checkin tab of the web page. This file may created by executing make submission. The mysim.tar file should only contain your logic.c file. Type:
    ~cs270/bin/checkin P8B mysim.tar

We will check that the program compiles and test the execution of the remaining instructions and the operating system.


Relax, you are done with your assignment! The semester is almost over. :)