/***********************************************************************
 * Pipelined Y86 Simulator
 *
 * Copyright (c) 2002, 2010, R. Bryant and D. O'Hallaron,
 * All rights reserved.
 * May not be used, modified, or copied without permission.
 ***********************************************************************/ 

This directory contains the code to construct simulators for PIPE and
the variants of it described in the homework exercises.

*************************
1. Building the simulator
*************************

Different versions of the PIPE simulator can be constructed to use
different HCL files when working on the different homework problems.


Binary	VERSION		HCL File	  Description
psim	std		pipe-std.hcl	  Standard simulator (default)
psim	broken		pipe-broken.hcl   Does not handle any hazards
psim	full		pipe-full.hcl	  For adding iaddl and leave
psim	nobypass	pipe-nobypass.hcl For implementing PIPE-
					  (called pipe-stall.hcl in text)
psim	lf		pipe-lf.hcl	  For implementing load forwarding
psim	nt		pipe-nt.hcl	  For implementing NT branch prediction
psim	btfnt		pipe-btfnt.hcl	  For implementing BTFNT branch pred.
psim	1w		pipe-1w.hcl	  For implementing single write port


The Makefile can be configured to build simulators that support GUI
and/or TTY interfaces. A simulator running in TTY mode prints all
information about its runtime behavior on the terminal.  It's hard to
understand what's going on, but useful for automated testing, and
doesn't require any special installation features.  A simulator
running in GUI mode uses a fancy graphical user interface.  Nice for
visualizing and debugging, but requires installation of Tcl/Tk on your
system.

The Makefile has simple instructions for building the TTY and GUI
forms. In either case, once you've configured the Makefile, you can
build different versions of the simulators with different HCL files
with commands of the form:

	unix> make clean; make psim VERSION=xxx

where "xxx" is one of the versions listed above.  To save typing, you
can set the Makefile's VERSION variable. For example, if you are working
on Problems 4.52 and 4.53, which require to modify pipe-full.hcl, then 
you could set VERSION=full in the Makefile. Typing

	unix> make clean; make psim

would then make the pipe-full.hcl version of PIPE.

***********************
2. Using the simulators
***********************

The simulator recognize the following command line arguments:

Usage: psim [-htg] [-l m] [-v n] file.yo

file.yo required in GUI mode, optional in TTY mode (default stdin)

   -h     Print this message
   -g     Run in GUI mode instead of TTY mode (default TTY mode)
   -l m   Set instruction limit to m [TTY mode only] (default 10000)
   -v n   Set verbosity level to 0 <= n <= 2 [TTY mode only] (default 2)
   -t     Test result against the ISA simulator (yis) [TTY model only]

********
3. Files
********

Makefile		Build the simulator
Makefile-sim		Makefile for the student distribution
README			This file

**********************************************
* Files related to the CS:APP Architecture Lab
**********************************************

* Sample programs
ncopy.ys		The default version of ncopy that the students optimize
ncopy.c			C version of ncopy that defines its semantics

* Preconstructed driver programs (by gen-driver.pl)
sdriver.ys		Driver that calls ncopy.ys on a short (4-word) array
ldriver.ys		Driver that calls ncopy.ys on a longer (63-word) array 
			Both drivers are generated automatically by the
			Makefile by typing "make drivers".

* Solution files (Instructors only)
gen-ncopy.pl	        Generates versions of benchmark program with various
		        optimizations.  See comments in file for explanation.

* Testing scripts
gen-driver.pl		Generate a driver program for an arbitrary ncopy 
			implementation (default ncopy.ys). Type "make drivers"
			to construct sdriver.ys and ldriver.ys.
benchmark.pl		Runs an implementation of ncopy on array sizes
			1 to 64	(default ncopy.ys) and computes its performance
			in units of CPE (cycles per element).
correctness.pl		Runs an implementation of ncopy on array sizes 
			0 to 64, and several longer ones and checks each for
			correctness.
check-len.pl		Determines number of bytes in .yo representation of
			ncopy function.


****************************************************
* HCL files for different versions of the simulators
****************************************************

pipe-std.hcl		The standard PIPE processor described in the text
pipe-broken.hcl		A simulator that does not detect or handle hazards
			(useful when explaining hazards in lectures)

* HCL files for various CS:APP Homework Problems
pipe-nobypass.hcl	4.51: Build version of PIPE without bypassing 
			(called pipe-stall.hcl in the text)
pipe-full.hcl		4.52-53: Add iaddl and leave instructions to PIPE
pipe-nt.hcl		4.54: Implement branch not taken strategy
pipe-btfnt.hcl		4.55: Implement back-taken forward-not-taken strategy
pipe-lf.hcl		4.56: Implement load forwarding logic
pipe-1w.hcl		4.57: Implement single ported register file

* HCL solution files for the CS:APP Homework Problems (Instructors only)
pipe-nobypass-ans.hcl	4.51 solution
pipe-full-ans.hcl	4.52-53 solutions
pipe-nt-ans.hcl		4.54 solution
pipe-btfnt-ans.hcl	4.55 solution
pipe-lf-ans.hcl		4.56 solutions
pipe-1w-ans.hcl		4.57 solutions

*****************************
* PIPE simulator source files
*****************************

psim.c			Base simulator code
sim.h			PIPE header files
pipeline.h
stages.h
pipe.tcl		TCL script for the GUI version of PIPE



