/*------------------------- CONTENTS -------------------------*/

This file contains the installation instructions for the SimpleScalar
Tool suite, developed and maintained by SimpleScalar LLC.

See the "COPYRIGHT" file for distribution restrictions.

INInstallation procedure written by Doug Burger, 6/23/97.

The release version is 2.1.0, 6/23/97.

/*------------------------ DOWNLOADING -----------------------*/

There are five distribution files in the directory:

	- simplesim.tar.gz          -> simulator suite, required
	- simpleutils.tar.gz        -> binary utilities, recommended
	- simpletools.tar.gz        -> compiler/asm/libs, optional
	- simplebench.big.tar.gz    -> precompiled SS SPEC95 binaries 
					(big-endian version, optional)
	- simplebench.little.tar.gz -> precompiled SS SPEC95 binaries 
					(little-endian, optional)

Download the desired files into your target directory. If you obtained
the file with the ".gz" suffix, run the GNU decompress utility (gunzip). 
The file should now have a ".tar" suffix. To remove the directories 
from the archive:

	tar -xvf filename.tar

If you downloaded all files, you should now have the following 
subdirectories, with the following contents:

simplesim-2.0 - holds code for five SimpleScalar processor 
	simulators and all supporting code files.
gcc-2.6.3 - holds the GNU C compiler code, targeted toward 
	the SimpleScalar architecture.
binutils-2.5.2 - contains the GNU binary utilities code, 
	ported to the SimpleScalar architecture
glibc-1.09 - contains the GNU libraries code, ported to the 
	SimpleScalar architecture.
f2c-1994.09.27 - contains the 1994 release of AT&T Bell 
	Labs' FORTRAN to C translator code.
ssbig-na-sstrix,
sslittle-na-sstrix - target directories for the ported cross-compiler, 
	compiled GNU binary utilities, and libraries that are targeted
	to the SimpleScalar architecture.  (Which directory is used
	depends on the endian-ness of the host machine).
spec95-big - precompiled SimpleScalar SPEC95 binaries, big-endian 
	versions
spec95-little - precompiled SimpleScalar SPEC95 binaries, little-endian 
	versions

/*----------------------- INSTALLATION -----------------------*/

The SimpleScalar architecture, like the MIPS architecture, supports
both big-endian and little-endian executables. The tool set supports
compiling for either of these targets; the names for the big-endian
and little-endian architecture are ssbig-na-sstrix and
sslittle-na-sstrix, respectively (the following instructions will
assume a big-endian installation, which is our default). To install
the full release, first build the GNU binary utilities (you do not 
need to build them to run pre-compiled binaries, but we recommend that
you do so, as they contain many useful utilities).

	cd $IDIR/binutils-2.5.2
	configure --host=$HOST --target=ssbig-na-sstrix --with-gnu-as
		--with-gnu-ld --prefix=$IDIR 
	make
	make install

$HOST here is a "canonical configuration" string that represents your
host architecture and system (CPU-COMPANY-SYSTEM). The string for a
Sparcstation running SunOS would be sparc-sun-sunos4.1.3, running
Solaris: sparc-sun-solaris2, a 386 running Solaris:
i386-sun-solaris2.4, etc. A complete list of supported $HOST strings
resides in $IDIR/gcc-2.6.3/INSTALL. Once the binutils have been built,
build the simulators themselves. This is necessary to do before
building gcc, since one of the binaries is needed in the
cross-compiler build.

	cd $IDIR/simplesim-2.0
	make

Now, build the compiler itself:

	cd $IDIR/gcc-2.6.3
	configure --host=$HOST --target=ssbig-na-sstrix --with-gnu-as
		--with-gnu-ld --prefix=$IDIR 
	make LANGUAGES=c
	../simplesim-2.0/sim-safe ./enquire -f >! float.h-cross
	make install

We provide pre-built copies of the necessary libraries in
ssbig-na-sstrix/lib, so you do not need to build the code
in glibc-1.09, unless you change the library code. (The libraries
are tricky to build and we do not recommend building them yourself
unless you absolutely need to).  In that event, to build the libraries: 

	cd $IDIR/glibc-1.09
	configure --prefix=$IDIR/ssbig-na-sstrix ssbig-na-sstrix
	unsetenv TZ
	make
	make install

If you have FORTRAN benchmarks, you will need the f2c tool:

	cd $IDIR/f2c-1994.09.27
	make
	make install

/*-------------------------- RUNNING -------------------------*/

The tool set should now be ready for use. To run a test:

	cd $IDIR/simplesim-2.0
	sim-outorder tests/bin.big/test-math

This test should generate about a page of output, and will run very 
quickly.  (If you are running on a little-endian host, use the test 
programs in the "bin.little" directory).  You should now be able to
compile your benchmarks with the version of gcc in the ssbig-na-sstrix
directory, and feed them into any of the simulators (sim-fast,
sim-safe, sim-profile, sim-cache, sim-cheetah, and sim-outorder) as
shown above.

/*------------------ FOR MORE INFORMATION --------------------*/

The technical report describing the 2.0 release and the installation
process in detail is available at ftp://ftp.cs.wisc.edu/sohi/TR_1342.ps.
Any other questions not covered by these report should be sent to Doug
Burger at dburger@cs.wisc.edu.