======================================================================== README.ss-viz from the ss-viz-rel1-2.tar release package Thu Jan 17 13:31:17 CST 2002 $Revision: 1.6 $ ======================================================================== Hello and welcome to the alpha release of the SimpleScalar Visualizer (ss-viz), a colorful and handy graphical front end to the sim-outorder SimpleScalar simulator. This package includes all the files you need to build and configure the SimpleScalar visualizer for Sun Solaris and Linux operating systems. However, in addition to the normal build tools required by SimpleScalar (e.g., the C compiler and runtime libraries), this package requires at least version 8.0 of the Tcl/Tk libraries and X11R6 of the X Window System. A good source for downloading the Tcl/Tk (pronounced "Tickle Tk") libraries for Linux and Solaris: http://www.activestate.com/Products/ActiveTcl/ In addition, the runtime environment needs to include: - a compatible shell (bash has been tested) - and netscape (if you want your users to access the on-line help). Let's say that you have untar-ed this ss-viz-rel1-2.tar file in your home directory, using the following commands: % cd $HOME % untar -xvf ss-viz-rel1-2.tar Afterwards, you will have a directory structure as follows: - $HOME/ss-viz/ # the top level directory of the ss-viz directory - $HOME/ss-viz/README.ss-viz, ss-viz, ss-viz-setup.pl, sstk, and other script files at the top level of the package - $HOME/ss-viz/app-defaults/Sswish (X Windows application settings) - $HOME/ss-viz/help/index.htm (HTML online help) - $HOME/ss-viz/src/*.[ch], and other SimpleScalar source files - $HOME/ss-viz/ui/*.tcl (the Tcl source files) Now review $HOME/src/Makefile: - The INCLUDE and LIBS definitions in the Makefile look like this: INCLUDES = -I/usr/local/include LIBS = -L/usr/local/lib -ltk8.3 -ltcl8.3 -ldl -L/lusr/X11R6/lib -lX11 - These INCLUDE and LIBS definitions appear twice--once in the Linux section and once in the Solaris section. The Makefile is set up for a Linux build, so that the Solaris definitions are commented out with hash characters (#). - The INCLUDE and LIB definitions need to refer to the directory paths for your X Windows and Tcl/Tk header files and libraries. Edit the Makefile manually to update for your particular locations. Next set up the links to the PISA architectural files: % cd $HOME/ss-viz/src % make config-pisa The reason is that SimpleScalar requires you need to specify the type of machine configuration you are using. Currently, PISA is the only SimpleScalar instruction set that has been tested thoroughly with ss-viz. Once you've make the changes, build the C code executables: % cd $HOME/ss-viz/src % make The make process will create a number of simulators and executables, including sysprobe and Version 3.0a of sim-fast, sim-cache, sim-outorder, etc. The whole process takes 10-15 minutes and requires about 20MB of disk space. Note: If you see miscellaneous compile time warnings, such as: misc.c:482: warning: `prec' might be used uninitialized in this function --and-- machine.def:1197: warning: operation on `addr' may be undefined --you may safely ignore these warnings. The most important executable is built last: The 'sswish' C program contains the out-of-order simulator code with "hooks" inserted for the Tcl/Tk graphical user interface. Once sswish builds, you test it simply by running the command: % ./sswish If the program exits immediately, printing the "usage message" error with possible command-line arguments, then the sswish program has been successfully compiled. Note: To run sswish, you may need to specify the path to the Tcl/Tck libraries, depending on where you're installed the libraries. For example, assuming an ActiveTcl Linux distribution under /usr/local/ActiveTcl, you can specify the location by setting the LD_LIBRARY_PATH environment variable: export LD_LIBRARY_PATH=/usr/local/ActiveTcl/lib The ss-viz shell script uses sswish ("SimpleScalar windowing shell") with the interpreted Tcl/Tk scripts in the $HOME/ss-viz/ui subdirectory to create the whole graphical user interface. Now we need to set up the paths in the master script, ss-viz, to run the entire engine. Edit the ss-viz script: % cd $HOME/ss-viz % vi ss-viz (or use any text editor) Modify the following lines in ss-viz: - The first line indicates where your version of bash is located. For example: #!/usr/bin/bash - The BASE_DIR line indicates where the top-level ss-viz directory resides. For example: BASE_DIR=$HOME/ss-viz - The SPEC_DIR line specifies where you have installed the SimpleScalar SPEC95 benchmark binaries. For example: SPEC_DIR=/p/bin/simplescalar/spec95 Note that SPEC_DIR refers to the topmost directory beneath which the "benchmarks" and the "inputs" directories reside. Note also that there are certain naming conventions for the names of benchmarks (such as the *.ss suffix to denote compiled for SimpleScalar). For more information, examine the ss-viz script for the default BENCHMARK_FILE names. - To display the help/index.htm file, the Tcl script "ui/helpmesg.tcl" simply invokes "netscape". If this executable isn't already on the default user path, then you can modify line 39 of "ui/helpmesg.tcl" to hardcode the path name. Next, check that your X Windows configuration is working properly. Try: % xclock If the X window opens on your display, you're ready to roll. Run the SimpleScalar visualizer: % $HOME/ss-viz/ss-viz IMPORTANT: Standard error messages and SimpleScalar text output are redirected to $HOME/ss_results.txt. If the ss-viz window doesn't appear or if the program acts unexpectedly, examine $HOME/ss_results.txt to determine the problem. Note: You can change the name or relocate the "ss-viz" subdirectory, but please don't change the name of the "ss-viz" shell script. Also, because the ss-viz shell script will look in particular places for the other pieces (such as ./src/sswish and ./ui/system.tcl), please don't move or rename these pieces. ========================================================================