########################## Part 1: original.c #################################

This term project for a graduate class in microprocessor system design called
for a small program in Verilog, C, or C++ to simulate (not synthesize) the 
behavior of a write-allocate, MESI protocol, four-way set associative L2 cache
with 4K lines of 64 bytes data each. 

Our C program was tested by running a text file containing lines of the type
  'n address'
where 
  'n' could be 0-9 and indicated the desired operation type and
  'address' was some 32-bit address.

Our demo program was successful for all tests except ensuring cache coherency.
We designed the algorithm for each operation, designed testcase files (see the 
testcases folder) to verify each algorithm, chose a multidimensional array for
the L2 cache itself, and implemented this all in C code. 

Team Members: Jen Hanni, Sai Prasanth, Brian Rho

The final file submitted to the professor and used for the project demo can be
found in original.c in this repo.

########################## Part 2: extensibility ##############################

I felt that the quality of the code, especially after last-minute fixes, could
be improved. Our prof challenged me to improve extensibility so that it would 
take less than fifteen minutes to change the size (number of lines) or set 
associativity (direct-mapped, fully associative).

I have permission from my teammates to take this code, improve on it, and make
it available at http://github.com/wicker/l2cache/ under the MIT license.

Author: Jen Hanni (wicker)

The original file (original.c) had 646 lines, used while loops, assumed a four-way cache and so specified 0-3 for all functions that checked all ways in an index, haphazardly included DRAM and L1 printf access notes but not in all cases and not for any functional purpose, repeated lines of code instead of just calling a function, and failed on cache coherency.

The final revised version (main.c) has 377 lines, uses for loops, uses a global variable to set cache size and can thus be used to simulate a direct mapped or x-way set associative cache, contains no DRAM or L1 printf access notes as they were outside the scope of the simulation, uses functions where appropriate, has an overhauled LRU algorithm, and makes use only of a single output file for the display.

The final cache simulator still fails on cache coherency but you can't have everything you want in life. 

######################### Instructions ########################################

To run this cache, you will need the following files:

main.c - contains the program itself
tesfile.din - the list of 'n' 'address' inputs
Makefile - for ease of removing and compiling files during test
run - 

Download these four files into one directory and cd to that directory.

Give the script 'run' permission to do so: 'chmod u+x run'

Run the script: ./run

main.c will take in the testfile.din and printf the stats of the entire run.

It will also generate a display.txt on every iteration where n = 9. This will display everything in the cache but make no changes. The cache will be reset on every iteration where n = 8.

######################### MIT License #########################################

Copyright (c) 2011 Jen "wicker" Hanni, http://wickerbox.net/

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.