P8: LC-3 Simulator (200 points)

See Canvas for due dates

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.

Some functions are provided for you. You will add functions 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

Create a directory for this assignment and cd there.
Download the file appropriate for your OS
- P8.linux.tar.
- P8.osx.tar.
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
```
cd P8 and do all your work in that directory
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.
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.
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.

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

Run the simulator using ./mysim-tk -norun or ./mysim -norun if you prefer the command line version.
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.
You may test the code as you implement individual instructions. Start by implementing the NOT instruction in logic.c Create the following simple test program with an editor and assemble it using lc3as.
```
          .ORIG x3000
          NOT R1,R7
          NOT R6,R2
          HALT
          .END
```
Add additional instructions to your test program as you implement them.
Load the assembled program into your simulator. Set default values in the source registers R7 and R2. Single step the program and monitor its operation. This will help verify everything is working. Do not proceed until this works correctly.
Exit the simulator.

Completing the LC-3 instructions

Implement the instructions using these steps.

Select an unimplmented LC-3 instruction to work on (e.g. NOT).
Understand what information is needed to simulate this instruction using the LC-3 Visualizer.
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.
You may find it helpful to extract duplicate/similar code into functions that can be shared by instructions.
Rebuild your simulator using "make" after you finish the instruction.
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.
Run the simulator and test the instruction thoroughly.
You may find the LC-3 Visualizer useful in guiding the implementation.

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

The input assembly program had to be correct enough to go through the assembler.
We will not give you any programs that do things like infinitely loop, modify code, or branch to a data address/label.

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:

gdb mysim
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
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.
use the console commands of the lc3 simulator to exercise your code. When you hit a gdb breakpoint, control will transfer to gdb.
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.

Start the GUI version of the simulator (mysim-tk).
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.
Run gdb
Use the gdb command attach processID and gdb will be attached to your simulator.
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
continue This resumes the lc3 simulator.
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.
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

There is no preliminary testing for this assignment.

Final Testing (200 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 P8 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. :)