Simics Tutorial for ECE/CS 757 ------------------------------ By Min Xu, March 2002. Note: This file is also available in your "simics" directory after installation. Installation ------------ Logon to one of the instructional machines, for example tux1.cs.wisc.edu. Make sure you have at least 15 MB free space in your home directory and run the following installation script: /p/course/cs757-markhill/public/simics/dist.sh After entering the destination directory, you will have the complete Simics/Ruby package installed for this class (don't worry about the two "No such file or directory" errors). After installation you will see the following four directories in your top installation directory: common/ : common data structures and makefiles ruby/ : Ruby memory simulator scripts/ : Simics utility simics/ : Simics full system simulator Start Simics ------------ Simics is a multi-platform full system simulator. In your package you are provided with binaries that can simulate a SPARC V9 system running Solaris 8 on a x86 Linux host system. You should run simics on either a personal x86 workstation or one of the CS instructional machines (ie, tux**). The default startup script of Simics resides in simics/home/sarek First, make sure you have the license environment variable set in your .cshrc file: setenv VTECH_LICENSE_FILE /p/multifacet/projects/simics/licenses/license.dat setenv SIMICS_HOME . setenv LD_LIBRARY_PATH /p/multifacet/projects/simics/lib/ setenv SIMICS_EXTRA_LIB ./modules setenv PYTHONPATH ./modules Run the following scripts to prepare your installation: scripts/cvsmapfs -cw < symlinks.list (again, don't worry about "symlink failed" errors) scripts/prepare_simics_home.sh /simics/home/sarek You should start the simulator from that directory, for example: cd simics/home/sarek ./simics Now, you should see the Simics command line prompt. Load the Simulated System ------------------------- As a full system simulator, Simics has the ability to stop the simulated system and store the entire system state into files on disk. These files are usually called system checkpoints. To get you started, we have put 5 system checkpoints in simics/checkpoints. They are live system snapshots from systems that have 1, 2, 4, 8 and 16 processors. For example, you can load the 1 processor system checkpoint by: simics> read-conf ../../checkpoints/golden-1p.check After a while you will see a small yellow xterm window shows up on your screen. Note that, you can use key to auto-complete on the Simics command line. And simulation speed is inversely proportional to the processor number. Resume the Target System Execution ---------------------------------- The simulated system in the small yellow window is currently stopped. To continue: simics> c This will resume the target system execution from the checkpoint. Note that you can stop the simulation at any time by pressing in the Simics command line window. Copy Files from the Host System ------------------------------- Create a simple C file in your 757 directory on host system (the Tux machine), e.g.: % cat /afs/cs.wisc.edu/u/x/u/xu/757/test.c #include main() { printf("hello...\n"); for(;;) {}; } Compile it with Solaris compiler (on ironsides): ironsides % gcc -o test test.c Now, you'd like to run this program inside the simulator. But how? First you need to mount the host file system, in the yellow window: mount /host Now copy the file directly, in the yellow window: cp /host/afs/cs.wisc.edu/u/x/u/xu/757/test /space/ Finally run the program, in the yellow window: cd /space ./test Of course, this program will never finish, you can stop it with Ctrl-c inside the yellow window. Plant Magic Instruction ----------------------- How do we stop simulation from inside the simulator? Why this is important? You ask. Well, in some cases, you want to tell the simulator something just happened, for example, one database transaction has just been finished. So modify your test.c program as the following: % cat /afs/cs.wisc.edu/u/x/u/xu/757/test.c #include #include "simics/magic_call/magic_services.h" main() { printf("hello...\n"); RUBY_MAGIC_CALL(Do_Breakpoint); } compile it and copy it into the target system as before. However, this time enable magic-break point in simics by: simics> magic-break-enable Now, run the test program and it should stop the simulation. As you may notice, you can also call RUBY_MAGIC_CALL with "End_Transaction" parameter. In a later section, we will discuss how to use it to stop simulation only after "n" transactions are completed. Write Your Own Checkpoint ------------------------- Usually, after you have done certain setup work, or the system has entered a steady state, you often want to save the system state into a checkpoint that could be used in the future. simics> write-conf /tmp/test.check should save the system state into a number of files. Note that, your checkpoints will depend on the checkpoint you used to create it and the files can not be moved once they are created, unless you manually update the absolute path in the .check file. Simics CLI ---------- Simics uses a Python based command line interface (CLI). The command line environment is so powerful that you can execute arbitrary python script in it. User input that starts with "@" is treated as a Python line. For example, you can use the following command to setup a breakpoint in simics after 10 "End_Transaction" signal. simics> @from mfacet import * simics> @setup_run_for_n_transactions(10, 1) Now, run this test program in the yellow window: #include #include "simics/magic_call/magic_services.h" main() { int i; printf("hello...\n"); for(i = 0; i < 100; i++) { RUBY_MAGIC_CALL(End_Transaction); } } you should see the following output: simics> c end_transaction_magic_call: transaction completed: 1, transaction_limit: 10 end_transaction_magic_call: transaction completed: 2, transaction_limit: 10 end_transaction_magic_call: transaction completed: 3, transaction_limit: 10 end_transaction_magic_call: transaction completed: 4, transaction_limit: 10 end_transaction_magic_call: transaction completed: 5, transaction_limit: 10 end_transaction_magic_call: transaction completed: 6, transaction_limit: 10 end_transaction_magic_call: transaction completed: 7, transaction_limit: 10 end_transaction_magic_call: transaction completed: 8, transaction_limit: 10 end_transaction_magic_call: transaction completed: 9, transaction_limit: 10 end_transaction_magic_call: transaction completed: 10, transaction_limit: 10 end_transaction_magic_call: limit reached, unregistering callback end_transaction_magic_call: 10 transactions reached [cpu0] add %o0, 1, %o0 Simics timing model ------------------- Simics is a pure functional simulator, it has very simple timing model. It assumes that each instruction takes one time tick to execute and the processor execute all instructions in a sequential order. You can get the current simulated time: simics> print-time Number of steps executed (CPU cpu0) : 2151047000 Simics module ------------- Simics provides interface for more accurate timing models. These models are usually plugged into the simulator as modules. Some simple Simics modules have been included in simics/src/extensions/ directory. You can try out the "trace" module using the following commands (after reading a configuration): simics> load-module trace simics> trace0.trace-start /tmp/t.log simics> c < ... after one second or so ... > simics> simics> trace0.trace-stop simics> q Now, in /tmp/t.log you should have detailed trace of the program execution. Further reading --------------- In simics/doc directory, there are HTML and PDF format document available for simics API and commands. Please consult them for advanced features provided by Simics.