/***********************************************************************
 * Sequential Y86 Simulators
 *
 * 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 SEQ,
SEQ+, and the variants of it described in the homework exercises.

**************************
1. Building the simulators
**************************

Different versions of the SEQ and SEQ+ simulators can be constructed
to use different HCL files when working on the different homework
problems.

Binary	VERSION	HCL File	Description
ssim	std	seq-std.hcl	Standard SEQ simulator described in textbook.
ssim	full	seq-full.hcl	For adding iaddl and leave to SEQ.
ssim+	std	seq+-std.hcl	Standard SEQ+ simulator described in textbook.

The simulators run in either TTY or GUI mode:

o TTY mode: 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.

o GUI mode: 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 TTY or GUI
simulators. A TTY simulator runs in TTY mode only. A GUI
simulator can run in either TTY mode or GUI mode, according to 
a command line argument.

Once you've configured the Makefile, you can build the different
simulators with commands of the form

	unix> make clean; make ssim VERSION=xxx

where "xxx" is one of the versions listed above.  For example, to build
the version of SEQ described in the CS:APP text based on the control
logic in seq-std.hcl, type

	unix> make clean; make ssim VERSION=std

To save typing, you can also set the Makefile's VERSION variable.

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

The simulators take identical command line arguments:

Usage: ssim [-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		Builds the SEQ and SEQ+ simulators
Makefile-sim		Makefile for student distribution
README			This file

seq+.tcl		TCL script for GUI version of SEQ+
seq.tcl			TCL script for GUI version of SEQ

ssim.c			Base sequential simulator code and header file
sim.h

seq-std.hcl		Standard SEQ control logic
seq+-std.hcl		Standard SEQ+ control logic	
seq-full.hcl		Template for the iaddl and leave problems (4.34-35)

seq-full-ans.hcl	Solution for the iaddl and leave problems (4.34-35)
			(Instructor distribution only)


