HOMEWORK 1 OVERVIEW
      Group Project, Due: Sept. 30
            
Problem:

2. (100 points) Implement the SSM
   in C. Submit on webcourses:

   - all source files (.c, .h)
   - output of the tests (.myo, .myp)
   - updated Makefile to build your code

   You can use
       make submission.zip


          THE TASK FOR HOMEWORK 1

Write VM that:

  - reads binary object files
  - loads the program in the bof

  - with -p option:
     prints the loaded program and exits

       ./vm -p vm_test0.bof

  - with no options:
      - executes the program
      - produces tracing output

       ./vm vm_test0.bof
       

         THE VM AS A UNIX PROGRAM

One command line argument: BOF filename

 - Mandatory argument is a bof file name
     This file contains the instructions

   Example:

     ./vm vm_test2.bof


 - Optional argument to list the program
    -p

   Example:

    ./vm -p vm_test2.bof
    

I/O:
 - Listing and tracing output to stdout

 - Error messages to stderr


    INTERACTION: RUNNING PROGRAM'S I/O

Program reads from stdin



Program writes to stdout



   

         WHAT WE PROVIDE

Files on Webcourses, hw1 directory,
     download:

         hw1-tests.zip

contents:

  - ssm-vm.pdf
      - VM details
      - output format
 
  - Makefile

  - Useful modules:
     - machine_types
     - bof
     - instruction
     - utilities
     - ...

  - our tests
      vm_test*.bof
  - expected vm results
     vm_test*.out
  - expected vm -p results
     vm_test*.lst

  - sources for the assembler (asm*, ...)
  - sources for the disassembler (disasm*)
  - (assembly code for the tests
          vm_test*.asm)


      TESTS AND EXPECTED TEST RESULTS

Test inputs:

    vm_test0.bof, vm_test1.bof,
    vm_test2.bof, vm_test3.bof,
    vm_test4.bof, vm_test5.bof,
    vm_test6.bof

Expected tracing output results:

    vm_test0.out, vm_test1.out,
    vm_test2.out, vm_test3.out,
    vm_test4.out, vm_test5.out,
    vm_test6.out, vm_test7.out,
    vm_test8.out, vm_test9.out,
    vm_testA.out, vm_testB.out

Expected listing output results:

    vm_test0.lst, vm_test1.lst,
    vm_test2.lst, vm_test3.lst,
    vm_test4.lst, vm_test5.lst,
    vm_test6.lst, vm_test7.lst,
    vm_test8.lst, vm_test9.lst,
    vm_testA.lst, vm_testB.lst

Examples of running tests:

   make vm_test0.myo

   # or

   ./vm vm_test0.bof >vm_test0.myo 2>&1

   # compare to expected results
   
   diff -w -B vm_test0.out vm_test0.myo


   make vm_test0.myp

   # or

   ./vm -p vm_tset0.bof >vm_tset0.myp 2>&1


   # compare to expected results
   
   diff -w -B vm_test0.lst vm_test0.myp


     FILE NAMES FOR YOUR TEST RESULTS

Your tracing test (./vm) results:

    vm_test0.myo, vm_test1.myo,
    vm_test2.myo, vm_test3.myo,
    vm_test4.myo, vm_test5.myo,
    vm_test6.myo, vm_test7.myo,
    vm_test8.myo, vm_test9.myo,
    vm_testA.myo, vm_testB.myo

check all with:



Your listing test (./vm -p) results:

    vm_test0.myp, vm_test1.myp,
    vm_test2.myp, vm_test3.myp,
    vm_test4.myp, vm_test5.myp,
    vm_test6.myp, vm_test7.myp,
    vm_test8.myp, vm_test9.myp,
    vm_testA.myp, vm_testB.myp

check all with:




 GREP: A USEFUL UNIX TOOL FOR FINDING CODE

grep bin_instr_t *.h



     PROVIDED MODULES (IN HW1-TESTS.ZIP)

 machine_types.h declares types:


  machine_types.c defines:





 bof.h declares types:
 

  bof.c defines:




 instruction.h declares types:









  instruction.c defines:






 utilities defines:

 


    MORE PROVIDED FILES (LESS IMPORTANT)

 regname.h declares macros:
   NUM_REGISTERS, GP, SP, FP, RA
  regname.c defines:
   regname_get()


 file_location.h declares type:
   file_location

  file_location.c defines:
    file_location_make(),
    file_location_copy()
  
  


 Also sources for the assembler (asm* ...)
  and disassembler (disasm* )

  compile and link them with:

    make asm disasm

       PROVIDED MAKEFILE

You should change:


VM_OBJECTS = machine_main.o machine.o \
    machine_types.o instruction.o bof.o \
    regname.o utilities.o 






            USING THE MAKEFILE

Use the Unix command

   make target

to build target

Key targets:

 machine.o  - compiles

 
 vm   - builds


 vm_test1.myo - runs 



 vm_test1.myp - runs 


 check-vm-outputs - runs
 


 check-lst-outputs - runs


 
 check-outputs - runs


 submission.zip - creates
 

     OTHER POTENTIALLY USEFUL TARGETS

 clean - removes *.o *.myo *.myp
         removes vm vm.exe
         removes submission.zip

 asm - builds the assembler

 file.bof - uses the assembler to create
            file.bof from file.asm
            

       HOW TO WRITE YOUR OWN TESTS

Build the assembler:

    make asm

Write a test in a .asm file

    emacs test_add.asm

    # see srm-asm.pdf for the language
    
Make the .bof file

    make test_add.bof

    # or

    ./asm test_add.asm

Optional: Check the bof file

    make test_add.myp

    # or

    ./vm -p test_add.bof

Run your test in your VM

    make test_add.myo

    # or

    ./vm test_add.bof > test_add.myo 2>&1