I. Overview of Homework 1 (Stack Machine VM)
 A. the task
------------------------------------------
          HOMEWORK 1 OVERVIEW
            Due: Oct. 2
            
Problem:

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

   - all source files (.c, .h)
   - output of the tests (.myo, .myp)
   - updated Makefile to build your code
   
------------------------------------------
------------------------------------------
          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
       
------------------------------------------
  1. Details of the program's interface
   a. The VM itself
------------------------------------------
         THE VM AS A UNIX PROGRAM

One command line argument: BOF filename

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

   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

------------------------------------------
   b. The program being run in the VM
------------------------------------------
    RUNNING PROGRAM'S INPUT AND OUTPUT

Program reads



Program writes to 



   
------------------------------------------
 B. Implementation considerations
  1. What we provide in hw1-tests.zip
------------------------------------------
         WHAT WE PROVIDE

Files on Webcourses, hw1 directory,
     download:

         hw1-tests.zip

contents:

  - srm-vm.pdf
      - VM details
      - output format
 
  - Makefile
  - source files for asm and disasm
       *.c, *.h, asm.y, asm_lexer.l

  - 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)

------------------------------------------
  2. Tests provided
------------------------------------------
      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

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

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

------------------------------------------
        Are the .asm files the tests?
------------------------------------------
     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

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

------------------------------------------
  3. Provided source code modules (.h and .c files)          
------------------------------------------
     PROVIDED MODULES (IN HW1-TESTS.ZIP)

 machine_types (machine_types.h,
                machine_types.c)





 bof
 




 instruction






------------------------------------------
------------------------------------------
          MORE PROVIDED FILES

 regname



 utilities



 file_location
  



 Also sources for the assembler (asm* ...)
  and disassembler (disasm* )
------------------------------------------
  4. Provided Makefile
   a. What to change and what not to change
------------------------------------------
       PROVIDED MAKEFILE

You should change:

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


Don't change: the bottom half of Makefile
   (the developer's section)!
   
------------------------------------------
   b. Targets in the Makefile
------------------------------------------
            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-asm-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

------------------------------------------
  5. Writing your own tests
------------------------------------------
       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

------------------------------------------