COP 3402 meeting -*- Outline -*- * Overview of Homework 1 (Stack Machine VM) ** the task ------------------------------------------ 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 actual due date is 11:59pm, see Webcourses ... to create a zip file with all you need to submit ------------------------------------------ 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 input is a binary object file, like an executable file on Linux or .exe file on Windows Students do *not* write the assembler or disassembler, those are provided, nor do they need to write code for the provided modules: - bof - instruction - utilities - file_location - regname - char_utilities *** Details of the program's interface **** 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 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 ------------------------------------------ **** The program being run in the VM ------------------------------------------ INTERACTION: RUNNING PROGRAM'S I/O Program reads Program writes to ------------------------------------------ This doesn't need to be done right away ... from stdin for the RCH instruction ... to stdout for PSTR and PCH instructions (these are all system calls) ** Implementation considerations *** What we provide in hw1-tests.zip ------------------------------------------ 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) ------------------------------------------ Students don't need to implement the assembler (it's provided) but can use the assembler to write their own tests. Q: What are the files in the bof module? bof.h and bof.c *** 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, vm_test7.bof, vm_test8.bof, vm_test9.bof, vm_testA.bof, vm_testB.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 ------------------------------------------ Q: Are the .asm files the tests? No, they are used to create the .bof files and that might need to be done on other kinds of computers (non x86 architecture computers, if you have one ask the instructor) The .asm files might be helpful for understanding the tests, however ------------------------------------------ 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: ------------------------------------------ ... make check-vm-outputs ... make check-lst-outputs demo these make commands *** Finding code using grep When reading code you often will need to know where a name is declared (or defined), this can be done by your IDE or by grep ------------------------------------------ GREP: A USEFUL UNIX TOOL FOR FINDING CODE grep bin_instr_t *.h ------------------------------------------ The *.h is a shell pattern, try echo *.h grep stands for "global regular expression print" it looks for its first argument (like "bin_instr_t") in all of the files, try that... On a Mac, in the terminal (i.e., at the command line) you can use grep On Windows FINDSTR does something similar (try FINDSTR /R /V "bin_instr_t" *.h and use FINDSTR /? for how to use it) *** Provided source code modules (.h and .c files) ------------------------------------------ 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: ------------------------------------------ ... machine_types.h declares types: word_type, uword_type, address_type, func_type, ... machine_types.c defines: machine_types_sgnExt(), machine_types_zeroExt(), machine_types_formOffset(), machine_types_formAddress() ... bof.h declares types: BOFHeader, BOFFILE bof.c defines: bof_read_open(), bof_read_header(), bof_read_word() ... instruction.h declares types: op_codee, func0_code, func1_code, instr_type, syscall_type, comp_instr_t, other_comp_instr_t, syscall_instr_t, immed_instr_t, uimmed_instr_t, jump_instr_t, bin_instr_t instruction.c defines: instruction_read(), instruction_print_table_heading(), instruction_assembly_form(), instruction_type(), instruction_syscall_number() ... utilities defines: bail_with_error() newline() ------------------------------------------ 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 **** 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 ------------------------------------------ ... the definition of the macro VM_OBJECTS to be the list of object files you need for your VM these are currently what the instructor used to build the VM but you can change it to be the list of object files (*.o) you need... (Probably you want everything on lines 2 and 3 of this definition) Explain that the \ at the end of a line continues the definition onto the next line of the file ... Don't need to change anything else. ... Don't change: the bottom part of Makefile (the developer's section)! **** Example of writing code for the VM ------------------------------------------ EXAMPLE #include "machine_types.h" #include "instruction.h" #define formOffset(n) \ machine_types_form_offset(n) // declaration of memory // from the SSM Manual would go here. // And the declaration of GPR also. void interpret(bin_instr_t bi) { switch(instruction_type(bi)) { case comp_instr_type: { comp_instr_t ci = bi.comp; // ci is the instruction switch (ci.func) { case NOP_F: // name of func code break; case ADD_F: memory.words[GPR[ci.rt] + formOffset(ci.ot)] = memory.words[GPR[SP]] + memory.words[GPR[ci.rs] + formOffset(os)]; // ... other cases ... break; default: bail_with_error( "Illegal comp instruction"); break; } break; } // other cases as below // case other_comp_instr_type: ... } } ------------------------------------------ The question this is looking at is: how to interpret a machine instruction? Point out the use of: 1. instruction_type() to get the kind of instruction from instruction.h see instr_type 2. assigning the binary instruction (bi) to the type of the instruction structure (ci) 3. use of a switch based on the function code (for computational instructions) or op code (for immediate or jump instructions) to decide what to do next 4. use an array of register values with the offset to get an address into the memory (with the appropriate signed view, memory.words) and an assignment to do the work of the instruction I'm defining the formOffset macro just to save (horizontal) space. **** 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-lst-outputs - runs check-outputs - runs submission.zip - creates ------------------------------------------ ... machine.c with gcc -c ... ... your VM ... tracing test: ./vm vm_test1.bof > vm_test1.myo 2>&1 ... listing test: ./vm -p vm_test1.bof > vm_test1.myp 2>&1 ... the VM tracing tests puts outputs in the .myo files and compares the outputs with the expected results (.out files) ... the listing tests puts outputs in the .myp files and compares the outputs with the expected results (.lst files) ... all the tests and compares the outputs with the expected results (be sure to look at both results!) ... the submission.zip file to submit the homework (this includes outputs from our tests that you run) ------------------------------------------ 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 ------------------------------------------ The clean target can be used to start over or start from scratch *** 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 ------------------------------------------ demonstrate this! Be sure to include an EXIT instruction!