Filename: README
HW 6: Universal Virtual Machine
Course: CS 40
Names: Dylan Keenan (dkeena01) and Harsh Sinha (hsinha02)
Date: 20-NOV

Program Purpose:

        Our goal in this assignment was to implement a functioning UVM 
        that is able to emulate results from the source UVM and pass
        given tests. The focus for this program was on correctness 
        over performance in this version.


Acknowledgements:

        Hanson Sequence 
        Umlab (very useful for testing)
        Course Website 
        Piazza Posts


Implementation:

        All part of the spec have been tested and correctly implemented.


Briefly enumerates any significant departures from your design:

        Originally, we planned for the UM interface to call functions like Load
        and Store, but then we found it easier to add another accessor that 
        returned the whole segment. This wasused to easier copy over 
        instruction in the the load program command so we didn't have to call
        store and load each time.

        Succinctly describes the architecture of your system. Identify the 
        modules used, what abstractions they implement, what secrets they 
        know, and how they relate to one another. Avoid narrative descriptions
        of the behavior of particular modules.


Architecture:

        SegMemory: SegMemory emulates a 32-bit segmented memory on a 64-bit 
        system. It utilizes a Hanson Sequence to store 64-bit pointer 
        efficiently. SegMemory reads instructions from a binary file converts
        them into 32-bit words and maps them in segmented memory. It creates
        a new segment using sequences and uses a stack when unmapping to 
        handle recycledIDs. This interface handles memory storage on the heap
        and ensures recycledIDs are re-used properly, segments are mapped, 
        unmapped, loaded, stored and freed correctly.

        Functions:

        SegMemory_read_program(): Reads program instructions from a binary 
        file, converts them into 32-bit words, and loads them into a newly 
        mapped segment

        SegMemory_new(): Creates and initializes a new SegMemory 

        SegMemory_free(): Frees all segments within SegMemory 

        SegMemory_map(): Maps a new segment, using sequences.

        SegMemory_unmap(): Unmaps a segment, recycling its ID for proper re-use

        SegMemory_get(): Retrieves the starting address of a mapped segment

        SegMemory_length(): Returns the number of words of a mapped segment

        SegMemory_load(): Loads and retrieves instructions from a specified
        offset in a segment

        SegMemory_store(): Stores instructions at a specified offset in a 
        segment

        UM: The UM module implements the UVM emulator, which executes 
        instructions from a segmented memory system. It is responsible 
        for taking in the 32-bit instruction and based on the extracted 
        opcode it conducts a given UVM operation using helper functions 
        and segmemory when necessary. We used UM_Info struct to manage
        program, its registers, length and counter. Our Reg_indices struct
        manages the three registers case and Reg_LV handles the register
        for the loadval case.

        Functions:

        UM_Run(SegMemory_T program): Executes the UM machine on the provided 
        segmented memory program

        getopcode(), getregisters(), getvalue(): Decodes value from the 
        instruction

        execute(UM_Info *uminfo, Um_instruction instruction): executes program

        conditional_move(), segmented_load(), segmented_store(), add(), 
        multiply(), divide(), bit_nand(): instruction functions
       
        halt(SegMemory_T segmemory): Halts the UM machine, freeing the 
        segmented memory

        map_segment(), unmap_segment(): Map and unmap segment instruction 

        input(), output(): Handle input and output operations
        
        load_program(): Loads a program into the UM machine.

        load_value(): Loads a 32-bit value into a specified register.

        

Explains how long it takes your UM to execute 50 million instructions, and how
you know:

        It took 5.432 seconds to execute midmark (30,109 instructions) or 
        ~0.00018 seconds per instruction. So, for 50,000,000 it would take: 
        ~9000 seconds or ~2.5 hours.


UM TESTS

halt.um:                tests the halt command
halt-verbose.um:        tests halt then loads and outputs "Bad\n"
add.um:                 tests addition operation
print-six.um:           tests addition in registers and outputs 6
load-value.um:          tests instruction to loadvalue 48 and output val
print-word.um:          tests instruction to load "Good\n" and output val
arithmetic.um:          tests arithmetic operations and outputs expected val
conditional.um:         tests to hit a conditional and go to halt
load-program.um:        tests loading in a new program
input-and-output.um:    tests that input can be outputted as given


Time Spent:
        6 hours analyzing assignment
        3 hours on the design and architecture
        20 hours on coding, debugging and testing
        Total: 29+ hours