		     README FILE FOR SPIM & XSPIM
		     ============================

This directory contains SPIM--an assembly language MIPS R2000/R3000
simulator.


SPIM is copyrighted by James R. Larus and distributed under the
following conditions:

    You may make copies of SPIM for your own use and modify those copies.

    All copies of SPIM must retain my name and copyright notice.

    You may not sell SPIM or distributed SPIM in conjunction with a
    commercial product or service without the expressed written consent of
    James Larus.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.


The files in this directory are:

BLURB
	A short description of SPIM.

Configure
	A shell script to configure SPIM.

Imakefile
	Input file for the xmkmf program, which produces Makefile for your
	system.

Makefile.std
	The descriptor file for make program.  Only use this file if you
	do not have xmkmf (see Imakefile).

README	This file.

VERSION
	Version number of system.

buttons.c, buttons.h
	X-interface code for command buttons.

data.c, data.h
	Code to handle data directives.

inst.c, inst.h
	Code to build instructions and manipulate symbol table.

mem.c, mem.h
	Code to maintain memory.

mips-syscall.c, mips-syscall.h
	Code to handle system calls and exceptions.

op.h
	Definition of operations.

parser.y, parser.h
	Assembly command parser (YACC).

reg.h
	Register access macros.

run.c, run.h
	Instruction simulator.

scanner.l, scanner.h
	Lexical analyzer (LEX).

spim-syscall.h
	System call numbers.

spim-utils.c, spim-utils.h
	Misc. routines.

spim.c, spim.h
	Top-level interface.

sym-tbl.c, sym-tbl.h
	Symbol table.

windows.c, windows.h
	X-interface code to build windows.

xspim.c, xspim.h
	Top-level X-interface.

trap.handler
	Standard trap handler.

Tests
	Subdirectory contain torture tests to verify that SPIM works.

Documentation/spim.tex
	TeX document that describes SPIM.

Documentation/spim.ps
	Postscript version of TeX document.



			    BUILDING SPIM
			    =============

To make SPIM, run the shell script Configure:

	% Configure

and edit the first few non-comment lines of Imakefile (or Makefile.std, if you
use that instead) to set the pathnames for your system:

	TRAP_DIR  -- The full pathname of the directory in which to install
		     the SPIM trap handler.

	BIN_DIR   -- The full pathname of the directory in which spim and
		     xspim should be installed.

	MAN_DIR   -- The full pathname of the directory in which the manual
		     pages for spim and xspim should be installed.

In general, the remaining few parameters need not be changed.

Then type:

	% xmkmf
	% make

(Note: on RS6000's running AIX, you should edit the Makefile to use
the c89 compiler rather than cc.)

If you want an X-window version of SPIM, also type:

	% make xspim

If you do not have X-windows or the program xmkmf, edit the makefile
in Makefile.std and type:

	% make -f Makefile.std test
	% make -f Makefile.std xspim

To run spim or xspim, the trap handler code must be installed in the
directory specified by the variable TRAP_DIR in the Makefile.  If the file
trap.handler is not installed, spim and xspim fail with a message before
they start running.  You can either install this file by hand or by typing

	% make install

To test that spim is correctly built, type

	% make test

and examine the output of the test.  (Note: the trap handler must be installed
before running the test.)



			 NEW VERSION OF SPIM
			 ===================

I generally release new version of SPIM before each semester (late
August and early January).  The new version are available by anonymous
ftp from:

	ftp.cs.wisc.edu

in the directory:

	pub/spim/spim.tar.Z




		  WHAT ABOUT SPIM ON SYSTEM XYZ?
		  ==============================

SPIM should run without many changes on many Unix systems.  Obviously,
I have not tested SPIM on many system, nor can I port SPIM to systems
that I don't have.  However, I would like to hear about the changes
necessary to run SPIM on your favorite system.

James Larus
larus@cs.wisc.edu
Computer Sciences Department
1210 West Dayton Street
University of Wisconsin
Madison, WI 53706 USA
608-262-9519


$Header: /u/l/a/larus/Software/SPIM/RCS/README,v 1.20 1997/07/09 22:12:06 larus Exp $
