(c) Copyright 1998-2003 Virtutech AB.
Norrtullsgatan 15, SE-113 27 STOCKHOLM, Sweden TRADEMARKS
Virtutech, the Virtutech logo, and Simics are trademarks or registered trademarks of Virtutech AB or Virtutech, Inc. in the United States and or other countries.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. VIRTUTECH MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.
I
Starting with Simics
9
1 Introduction 11
1.1 Hosts and Targets . . . 12
1.2 Simics Targets - Fully Supported . . . 12
1.2.1 Simics/SunFire . . . 13
1.2.2 Simics/Serengeti . . . 13
1.2.3 Simics/x86. . . 13
1.2.4 Simics/x86-64 . . . 13
1.3 Simics Targets - Limited Support . . . 13
1.3.1 Simics/Alpha . . . 13 1.3.2 Simics/PPC . . . 14 1.3.3 Simics/IA-64 . . . 14 1.3.4 Simics/ARM . . . 14 1.3.5 Simics/MIPS . . . 14 1.4 This Document . . . 14 1.5 Other Documentation . . . 15 2 Installation 17 2.1 Licenses . . . 17
2.2 Flexlm Floating Licenses . . . 17
2.3 Multi-User Environment . . . 19
2.4 .tf Encoded Files. . . 20
2.5 Getting Disk Images . . . 20
3 First Steps 21 3.1 Downloading FirstSteps Disk Image . . . 22
3.2 Booting . . . 22
3.3 Using Checkpointing . . . 24
3.4 Tracing . . . 26
3.5 Scripting Simics . . . 27
3.6 Importing Files into the Simulated Machine . . . 28
3.7 Debugging a Sample Program . . . 29
3.8 Connecting FirstSteps to the Network . . . 31
CONTENTS
3.8.2 Connecting Simics Central to a Real Network . . . 34
4 Troubleshooting 37
II
Using Simics
39
5 Glossary 41 6 Startup Options 43 6.1 Processor Models . . . 43 6.2 Common Options . . . 447 Usual Simics Commands 45 7.1 Simulation . . . 45
7.2 Simulation State . . . 45
7.3 Scripts . . . 46
7.4 Modules . . . 46
7.5 Command-Line Interface. . . 46
8 The Command Line Interface 47 8.1 Invoking Commands . . . 47
8.1.1 How are Arguments Resolved? . . . 48
8.1.2 Namespace Commands . . . 48 8.1.3 Expressions . . . 49 8.1.4 Interrupting Commands . . . 49 8.2 Help System . . . 49 8.3 Tab Completion . . . 51 8.4 Remote Frontend . . . 51
8.4.1 Remote Frontend Limitations . . . 53
9 Configuration and Checkpointing 55 9.1 Saving and Restoring Configurations. . . 57
9.2 Modifying Saved Configurations . . . 57
9.3 Ready-to-run Configurations . . . 57
10 Script Support in Simics 59 10.1 Python in Simics. . . 59
10.2 Accessing the Configuration from Python . . . 60
10.2.1 Configuration Objects . . . 60
10.2.2 Creating Configurations in Python . . . 61
10.3 Accessing Commmand-Line Commands from Python . . . 62
10.4 Script Branches . . . 62
10.4.1 Introduction to Script Branches . . . 62
10.4.2 How Script Branches Work . . . 63
10.4.3 Script Branch Functions . . . 63
11.2 Haps (Event Occurrences) . . . 66
11.2.1 Haps Description . . . 66
11.2.2 Example of Python Callback on a Hap . . . 66
11.2.3 Magic Instructions . . . 67
12 Managing Disks, Floppies, and CD-ROMs 69 12.1 Saving Modifications to Simulated Disk . . . 69
12.1.1 Using Read/Write Disks . . . 70
12.1.2 Saving a Disk Diff . . . 71
12.1.3 Writing Binary Data from Simics . . . 72
12.2 Copying Real Disks . . . 72
12.3 Constructing a Disk from Multiple Files . . . 74
12.4 Accessing Host CD-ROM . . . 75
12.5 Accessing CD-ROM Image File . . . 75
12.6 Accessing Host Floppy . . . 76
12.7 Accessing Floppy Image File. . . 76
12.8 Accessing Disk Images from the Host Machine . . . 77
12.9 Using the /host Filesystem . . . 78
12.9.1 Installing the /host Filesystem on a Simulated Solaris . . . 78
12.10The Craff Utility . . . 79
13 Debugging Tools 81 13.1 Breakpoints . . . 81
13.1.1 Memory Breakpoints . . . 81
13.1.2 Temporal Breakpoints . . . 82
13.1.3 Control Register Breakpoints . . . 82
13.1.4 I/O Breakpoints . . . 82
13.2 Using GDB with Simics. . . 83
13.2.1 Remote GDB and Shared Libraries . . . 84
13.3 Symbolic Debugging Using Symtable . . . 85
13.3.1 Symtables and Contexts . . . 85
13.3.2 Sample Session . . . 86
13.3.3 Common Commands . . . 87
13.3.4 Symbolic Breakpoints . . . 88
13.3.5 Reading Debug Information from Binaries . . . 88
13.3.6 Loading Symbols from Alternate Sources . . . 89
13.3.7 Multiple Debugging Contexts. . . 89
13.3.8 Scripted Debugging . . . 90
14 Network Simulation 93 14.1 Setting up a Simulated Network . . . 93
14.2 Connecting to a Simulated Network . . . 94
14.3 Connecting to a Real Network. . . 95
CONTENTS
14.5 Services in ethernet-central . . . 97
14.6 Booting with DHCP. . . 98
14.7 Booting with BOOTP . . . 98
14.8 Transferring Files with TFTP. . . 99
14.9 Troubleshooting Real Network Configuration Problems . . . 99
15 Cache Simulation 101 15.1 Simulating a Simple Cache. . . 101
15.2 Multiple Level Caches . . . 102
15.3 Generic-Cache Features and Limitations . . . 106
15.4 Observing Instruction Fetches . . . 106
15.5 Understanding Generic-Cache Statistics . . . 107
16 Understanding Simics Timing 109 16.1 Simulation Mechanism . . . 109
16.2 Execution modes . . . 110
16.2.1 In-Order Execution . . . 110
16.2.2 Out-Of-Order Execution . . . 111
16.3 Modeling Time . . . 112
16.3.1 Default Timing Models . . . 112
16.3.2 Memory Hierarchy Interface . . . 113
16.3.3 The Consistency Controller . . . 114
16.3.4 Micro-Architectural Interface . . . 114
16.4 Event Handling . . . 115
16.5 The Simulator Translation Cache (STC) . . . 116
III
Extending Simics
117
17 Creating a Simics Module 119 17.1 Setting up a Build Environment . . . 11917.2 Compiling Modules. . . 121
17.3 Module Makefiles . . . 122
17.4 Adding Modules to the Build List. . . 123
17.5 Standard Module Target Defines . . . 124
17.6 Standard Module Host Defines . . . 124
17.7 User Defined Module Version Numbers . . . 125
17.8 Module Loading Support . . . 125
17.9 The Object Directories . . . 126
18 Inside a Simics Module 127 18.1 Module Loading and Unloading . . . 127
18.2 Implementing Module Functionality . . . 128
18.2.1 Classes and Objects. . . 128
18.2.2 Interfaces . . . 129
18.3.3 Attributes . . . 133 18.3.4 Registering Attributes . . . 137 18.3.5 Registering Interfaces . . . 139 18.3.6 Creating Objects . . . 140 18.3.7 Examples . . . 140 18.4 Posting Events . . . 140
18.5 Simics Header Files . . . 141
18.6 System Calls and Signals . . . 141
18.7 Text Output . . . 142
18.8 Using Threads in Simics Modules. . . 143
19 Adding New CLI Commands 145 19.1 Introduction . . . 145
19.2 Example of a new command. . . 145
19.3 Argument Types. . . 150
20 Creating a Device Step by Step 153 21 Creating a Timing Model 157 21.1 The Operate Function. . . 158
21.2 Observing Instruction Fetches . . . 159
21.3 Changing the Result of Memory Operations. . . 159
21.4 Chaining Timing Models. . . 159
22 Creating a Cache Model 161 22.1 Using the Sample Cache Code. . . 161
22.2 Using the Generic Cache Code . . . 161
Introduction
Simics is an efficient, instrumented, system level instruction set simulator.
• Whereas an emulator is focused on executing a program as quickly and accurately as possible, a simulator, in addition, is designed from the ground up to gather information on the execution and in general be a flexible tool. Simics is more of a platform on which to build simulation-based tools than just a single program. • efficient means that Simics is designed to be sufficiently fast to run realistic
work-loads, typically better than 100x slowdown in comparison with native execution. This can seem slow in comparison to fast emulators, but Simics provides a wide range of features and facilities. In fact, in its class of tools, Simics is the fastest simulator ever implemented.
• instrumented means that Simics was designed not to run just the target system programs, but to gather a great deal of information during runtime. Many sim-ulators are simply fast emsim-ulators with instrumentation added as an afterthought, leading to a situation where when the tool is used as intended (with high levels of information-gathering enabled), it slows down considerably. Simics, in contrast, is specifically designed to achieve high performance even with a high level of instru-mentation and under very large workloads. Simics provides a variety of statistics in its default configuration and allows various add-ons to be developed by power users and plugged into the simulator.
• Simics is system level, meaning that it models a target computer at the level that an operating system acts. Thus, Simics models the binary interfaces to buses, in-terrupt controllers, disks, video memory, etc. This means that Simics can run run anything that the target system can, i.e., arbitrary workloads. Simics can boot un-modified operating system kernels from raw disk dumps.
• instruction set simulator means that Simics models the target system at the level of individual instructions, executing them one at a time. This is the lowest level of the hardware that software has ready access to. Simulating at this level allows Simics to be system level, yet still permits an efficient design.
1.1. Hosts and Targets
Simics fully virtualizes the target computer, allowing simulation of multiprocessor systems as well as a cluster of independent systems, and even networks, regardless of the simulator host type. The virtualization also allows Simics to be cross platform. For instance, Simics/SunFire can run on an Linux/x86 system, thus simulating a 64-bit big-endian system on a 32-bit little big-endian host.
The end uses for Simics include program analysis, computer architecture research, and kernel debugging. The analysis support includes code profiling and memory hier-archy simulation (i.e., cache hierarchies). Debugging support includes a wide variety of breakpoint types. The support for system-level simulation allows operating system code to be developed and analyzed.
1.1
Hosts and Targets
Two very important terms used throughout the Simics manuals are host and target, which are explained below. You can find a longer list of terms used in the glossary (see chapter5).
• host defines the computer on which you are running Simics. It can also refer to the architecture (x86) or the model (Sun SunFire) of computer that runs the simulator, or to the host platform (combination of an architecture and an operating system, like x86-linux).
• target refers to the computer simulated by Simics. It can also refer to the architec-ture or the model of computer simulated.
Simics exists in a variety of target–host combinations. The standard host platforms for Simics are:
• Linux/x86 Compiled for Red Hat Linux 6.2 with GCC, but works on many other Linux distributions as well as later versions of Red Hat Linux.
• Solaris/UltraSPARC 32-bit Sun Forte 6.2 compiled versions. Requires Solaris 8 or newer.
• Windows 2000 Compiled with GCC. This version also works on Windows XP. Additional host platforms for Simics, with only limited support:
• Solaris/UltraSPARC 64-bit Compiled with Sun Forte 6.2. Requires Solaris 8 or newer.
You can refer to the chapter6to get a full list of all the processor models available in Simics.
1.2
Simics Targets - Fully Supported
The following list contains all fully supported Simics targets. Fully supported means that they are available for download and evaluation, and can run on all standard host platforms.
Simics/SunFire simulates the Sun Enterprise 3000-6500 server series running Solaris or Linux. A variety of SBus and PCI based devices are supported, such as SCSI, Fibre-Channel, and graphics cards.
Simics/SunFire is also available in out-of-order mode (see chapter16and the Simics Out-of-Order Guide for more information).
Simics/SunFire runs on all standard host platforms, as well as 64-bit Solaris.
1.2.2
Simics/Serengeti
Simics/Serengeti simulates the Sun Fire 3800-6800 server series from Sun running So-laris. A variety of PCI based devices are supported, such as SCSI, Fibre-Channel, and graphics cards.
Simics/Serengeti runs on all standard host platforms, as well as 64-bit Solaris. Simics/Serengeti is also available in out-of-order mode (see chapter16and the Simics Out-of-Order Guide for more information).
1.2.3
Simics/x86
Simics/x86 simulates various x86 class processors, ranging from 486sx to Pentium 4, and is capable of booting Linux up to version 2.4, Windows NT 4.0, 2000 and XP in both single-processor and multi-processors (SMP) mode. Simics/x86 includes various PC devices needed to boot the virtual PC such as graphic controllers, bus controllers, floppy and hard disks.
Simics/x86 runs on all standard host platforms.
1.2.4
Simics/x86-64
Simics/x86-64 simulates a PC system with a processor conforming to AMD’s x86-64 architecture. It can run a large number of operating systems in both the IA32 compatible legacy modes and in x86-64 native mode.
Simics/x86-64 runs on all standard host platforms.
1.3
Simics Targets - Limited Support
The following list contains Simics targets with limited support. Limited support targets may not be available on all host platforms, and packages may only be available for download and evaluation on request.
1.3.1
Simics/Alpha
Simics/Alpha models the Alpha 21164 (also known as EV5) implementation of the Al-pha architecture. It includes device models and configurations for systems based on the 21174 (Pyxis) chipset, similar to the AlphaPC 164LX.
1.4. This Document
Simics/Alpha is capable of booting Red Hat Linux 6.0 and 6.2. It has been tested with Linux miniloader (MILO).
Simics/Alpha runs on all standard host platforms.
1.3.2
Simics/PPC
Simics/PPC models the 32 bit PowerPC 750 and 7450 (including AltiVec) processors, including devices to simulate Artesyn’s PM/PPC card. The Artesyn PM/PPC is a com-plete real-time computer solution in a very compact, industry standard form-factor. It is designed to allow communication equipment manufacturers to add compute function-ality to a baseboard, such as a T1/E1 or ATM interface board, and provide the localized horsepower necessary for applications such as protocol processing, data filtering or I/O management.
Simics/PPC runs on all standard host platforms.
1.3.3
Simics/IA-64
Simics/IA-64 models the Intel Itanium and Itanium2 processors. It includes device models to simulate a complete system based on the 460GX chipset, and is capable of booting Linux 2.4.
Simics/IA-64 runs on all standard host platforms.
1.3.4
Simics/ARM
Simics/ARM models a generic ARMv5 processor with minimal implementations of the devices from the Intel StrongARM processor that are needed to boot a minimal Linux configuration.
Simics/ARM runs on all standard host platforms.
1.3.5
Simics/MIPS
Simics/MIPS models the 32 bit MIPS-4Kc processor with a limited set of devices from the MIPS Malta reference board. Only the devices needed in order to boot Linux have been implemented.
Simics/MIPS runs on all standard host platforms.
1.4
This Document
The remainder of this document provides an overall description of Simics’ capabilities, environment and user interface.
Scripts, screen dumps and code fragments will be presented in amonospacefont. Sometimes, artificial line breaks may be introduced to prevent the text from being too wide. When a break is introduced, it is shown as a small arrow pointing to the next line. It means that the text that has been interrupted continues on the next line.
line-break that shouldn’t be typed.
The directory[simics]will be used to refer to where Simics is installed when giv-ing path examples, like[simics]/README
1.5
Other Documentation
Release notes for a Simics version is available in the README_<version> file (where <version> is the major Simics version number). This file is updated with information for each patch release of Simics (For example,[simics]/README_1.4). For complete descriptions of Simics commands, APIs, loadable modules etc., please refer to the Simics reference manuals. The reference manuals are target specific; the following exist:
• Simics/Alpha Reference Manual • Simics/ARM Reference Manual • Simics/IA-64 Reference Manual • Simics/MIPS Reference Manual • Simics/PowerPC Reference Manual • Simics/Serengeti Reference Manual • Simics/SunFire Reference Manual • Simics/x86 Reference Manual • Simics/x86-64 Reference Manual
In addition a separate reference manual exists which covers the commands available in Simics Central (used for creating networks of simulators):
• Simics Central Reference Manual
To get a description of the different virtual target machines available as examples, you can consult the target guides:
• Simics/ARM Target Guide • Simics/IA64 Target Guide • Simics/MIPS Target Guide • Simics/PowerPC Target Guide • Simics/Serengeti Target Guide
1.5. Other Documentation
• Simics/SunFire Target Guide • Simics/x86 Target Guide
There is also an online technical FAQ available at: • http://www.simics.net/support
Installation
This chapter describes how to handle encrypted files, licenses and disk dumps, as well as how to install Simics for several users.
2.1
Licenses
If you received a license file for one computer, just copy it in the[simics]/licenses/
directory. It will be automatically recognized and used by Simics.
2.2
Flexlm Floating Licenses
Simics needs a license server for floating licenses. The license server used is FLEXlm v8.1 from GLOBEtrotter. Below we will briefly describe how to set up the license server. For further information on how to manage the server please consult the end user manual which can be found at http://www.globetrotter.com/flexlm/lmgrd.shtml
More information may also be available from thehttp://www.simics.netweb site.
Note: FLEXlm is a very common license technology, and if you are a corporate user then it is likely that you already have a centrally managed corporate server. Ask your system administrator.
To run Simics the first time, a few files should be installed, and a license server must be running. The files are located in the Simics distribution under[simics]/host/sys/ flexlm/bin, e.g.,[simics]/x86-linux/sys/flexlm/bin:
• lmgrd— The License Manager Daemon (server) • lmutil— FLEXlm utility program(s)
2.2. Flexlm Floating Licenses
A license file from Virtutech is also needed (usually sent via e-mail), that specifies your licenses. The license file is typically calledsimics.lic.
lmgrd, lmutil and vtechcan be installed anywhere in the system, but /usr/ local/flexlm/bin/ is the recommended directory. The license file, e.g.,simics. lic, should then be placed in the[simics]/licenses/directory. This is the default location for a license file, meaning that Simics will find it automatically. To override this, the environment variableLM_LICENSE_FILE(orVTECH_LICENSE_FILE) can be set to the name of the license file or to the directory where it resides. It can also be set to @license-host (i.e., the machine running the license server) if the license file cannot be reached through the file system. In this case the license server will know the location of the license file. A typical license file looks like this:
SERVER server ANY USE_SERVER
# change the path to where the license daemon (vtech) is located VENDOR vtech /usr/local/flexlm/bin/vtech
FEATURE simics vtech 1.0 3-oct-2003 20 AAFBC87969B5 \ VENDOR_STRING=comm
#
FEATURE v9_on_x86_linux vtech 1.0 3-oct-2003 20 A1BBBC7B2FBE
whereserveris the name of the host that will run the license server. This can be changed by the user. TheVENDORline specifies the vendor and where to find the vendor daemon. Edit this line. FEATUREspecifies the type of license and for what it is used. In this case it is 20 commercial floating licenses for Simics SPARC-V9 v1.0 on x86 host running Linux with expire date 3-oct-2003. The last hexadecimal codes are checksums which asserts that the license file is not altered in an unauthorized way by the user.
A license server is started as follows:
joe@server:˜$ lmgrd -c license-file
Remember to run lmgrd on theserverhost specified in the license file, in the exam-ple it is “server”. Since lmgrd does not need root privileges it is recommended to run it as a user.
If the -c option is not given, the license server will try to find the license filelicense. datin[simics]/licenses, or find it using theLM_LICENSE_FILEvariable. The server will log all actions tostdout, unless a log file is specified by the-l log-file op-tion.
lmgrdwill find the vendor daemon and start it. All communication between the licensed software and the vendor daemon goes via the license server (lmgrd). It is the vendor daemon that keeps track of products and number of licenses from a particular vendor, thus only one license server is needed to run software from several vendors.
Once the license server is started, Simics can be run like any program and the com-munication to the license server should be transparent to the user. When Simics is started it will ask for a license from the vendor daemon and, if the user is authorized and available licenses exist, Simics will check-out a license and run. On exit, Simics will
checked in. If this happens, the license server needs to be restarted. To shut down the license server and the vendor daemon type:
joe@enterprise:˜$ lmutil lmdown
and the server will go down.
Note: Once flexlm has successively checked out a license it will add the path to the license file (if it is not already present) to the.flexlmrcfile in the user’s home direc-tory. This can be very confusing since flexlm will be able to find license files not longer present in theLM_LICENSE_FILEenvironment variable. If you have trouble with this then delete the.flexlmrcfile.
2.3
Multi-User Environment
Simics can be installed for a multi-user environment on Linux and Solaris. Simics must first be installed as described above, and configure has to be run in the appropriate host directories. Each user, who need read access to the master Simics directory, then runs the script [simics]/scripts/user-install.shto create a personal Simics user installation.
The Simics user tree has the same structure as the master tree, except that most of the files and directories are actually links to the master tree’s files. Some files are however specific to the user and can be modified freely in the user tree:
• home/contains the configuration of the target machines.
• import/links the additional files needed and not provided along with Simics (disk dumps).
• src/contains the framework for developing new Simics modules (including the examples).
• host (such as x86-linux) contains the object files and specific modules or librairies developed by the user.
To be able to build own modules in the user tree, the master tree should have been configured for building as well (by runningconfigurein the host directory). The user can simply runconfigurein its own tree to handle eventual small differences in the build environment. Modules developed in the user tree override those provided in the master tree. In the same way, source files present in the user tree are chosen preferen-tially to those in the master tree. For more information regarding modules and builds, please consult chapter17.
2.4. .tf Encoded Files
2.4
.tf Encoded Files
Some of the files proposed for download are encrypted in the.tfformat. To decrypt them, you will need to download an external decoder calledtfdecode. It is available atftp://ftp.simics.net/pubas archive files.
When you uncompress the archive, you will get an executable file that can be use in the following way:
bash# cat file.tf | tfdecode 0x1 0x2 0x3 0x4 > file
where0x1,0x2,0x3and0x4are the decryption keys corresponding the the pack-age.
If no pre-compiled binaries is matching your system, you can also download the source archive and compile tfdecode by yourself.
2.5
Getting Disk Images
In order to run a real operating system on Simics, you would need to start from the ground and install it from a CD on your new empty simulated workstation. To speed up the process, Virtutech provides disk images (also called disk dumps) of freely available operating systems for download. Since these images are very big, they are not included with the Simics distributions. If you have a Simics CD, some images may have been provided along with the Simics binaries.
These additionnal files can be downloaded on Virtutech web site athttp://www. simics.net/download. These files should be placed in the[simics]/import/target directory, where target is the type of computer simulated (for example, theenterprise
dump should be placed in the[simics]/import/x86/directory, since enterprise is a x86 simulated workstation).
Note: Due to licensing issues, Virtutech distributes only freely available operating sys-tems. If you wish to simulate a commercial system like Windows or Solaris, you will have to install it by yourself. The Target Guides provide information on how to perform standard installations.
First Steps
First Steps with Simics is a step-by-step guide describing how to perform some common tasks with Simics. The guide is based on a target computer known as FirstSteps. First-Steps is a simulated Pentium II machine running a very small Linux Debian 3.0.
First, a few conventions. In this document, text written like this:
Simics Output
this is output from Simics
prompt> this is a command the user should type [...]
is output from Simics itself. The[...]means that some output has been removed. Text written like this:
Target Output
this is output from the simulated machine
prompt> this is a command the user should type on the simulated machine [...]
is output from the simulated machine.
Output from Simics should not be confused with the output from the simulated ma-chine. In the case of FirstSteps, the output from the simulated machine comes to a VGA console (it actually shows the output of a simulated Voodoo3 graphics card). This con-sole opens as a separate window, with the title “Simics Concon-sole: con0”. So, all input and output for the simulated machine goes into the VGA console window, and all input and output for Simics goes to the terminal where you started Simics.
3.1. Downloading FirstSteps Disk Image
3.1
Downloading FirstSteps Disk Image
This tutorial relies on a disk image calledfirststeps1.craff. Check for this file in the
[simics]\import\x86 directory of your installation (where [simics] represents the directory where Simics is installed on your computer). If you do not find it, you need to download it from Virtutech website, otherwise you can directly start the tutorial.
The download area for disk dumps is at http://www.simics.net/download. Download the file firststeps1.craff and place it into the [simics]/import/ x86directory of your installation. You are now ready to run the tutorial.
3.2
Booting
We are now ready to start Simics and boot FirstSteps:
Simics Output
bash$ cd [simics]/home/firststeps bash$ ./simics -x firststeps.simics
Simics startup wrapper. Copyright (c) 2000-2002 Virtutech AB. Checking out a license... done: academic license.
+---+ Copyright 1998-2002 by Virtutech, All Rights Reserved
| Virtutech | Version: Simics 1.4.0
| Simics/x86 | Compiled: Thu Sep 5 09:18:32 CEST 2002
+---+ Simulated processor: x86 (P6 cpuid fpu vme de [...] www.simics.com "Virtutech" and "Simics" are trademarks of Virtutech AB Type ’copyright’ for details on copyright.
Type ’license’ for details on warranty, copying, etc. Type ’readme’ for further information about this version. Type ’help help’ for info on the on-line documentation. Added to search path: ../../import/x86
Added to search path: ../../import/x86_64 [gfx-console]: Connecting to display: :0.0
[disk0_image] Opened subfile ’first-steps1.craff’ (format craff) [rom0_image] Opened subfile ’rombios-2.35’ (format raw)
[rom0_image] Opened subfile ’voodoo3-pci-bios.bin’ (format raw) [gfx-console]: Using MIT-SHM extension
[con0] Input disabled
[con0] Setting poll-rate: 50 Hz +---+ | Welcome to the Simics tutorial | +---+
tutorial.
To boot the FirstSteps machine, just type the command ’c’ followed by enter. To exit Simics, use the command ’q’ followed by enter.
simics>
The -x argument tells Simics to start and run a script, in this casefirststeps. simics.
If everything goes well, you will see a blank window popping up. This is the VGA output console. To start the simulation, use the command continue. Since this is a very commonly used command, there is an alias for it, c.
Note: You can get help on any command by typing help command.
Simics Output simics> c
You will see the usual BIOS messages, then LILO will start loading and uncompress-ing the Linux kernel.
Let Simics run and after a few minutes (depending on how fast your machine is, of course), you will see the familiar login prompt as shown in figure3.1.
Note: If you only see a blank screen, Linux may have started a screen saver. Please continue the tutorial: as soon as you press a key in the simulated machine, you will see the prompt screen reappear.
Now, note that FirstSteps VGA console says “input disabled” in the title bar. This means that the console does not accept any input. This is useful to avoid random key-board events disturbing the deterministic properties of the simulation. Our first action is therefore to enable the input so we can login. This is done by giving Simics the com-mand con0.enable-input. But, since FirstSteps is currently running, we need to inter-rupt it with a control-C first. Press control-C in the Simics terminal (i.e., the window were you started Simics), then type the command con0.enable-input:
Simics Output
control-C ---simics> con0.enable-input [con0] Input enabled simics> c
3.3. Using Checkpointing
Figure 3.1:Linux prompt
Note: You can issue the con0.enable-input command at any time during the boot pro-cess; press control-C in Simics terminal, type the command, and continue by typing c).
The text “input disabled” should now have disappeared from FirstSteps VGA con-sole. Now, we should try to login. FirstSteps has no user accounts, so we login asroot
with no password.
You can try to run a few commands on the console. Remember that the simulated operating system is configured for an american keyboard.
Note: If the VGA console does not respond, first make sure that Simics is actually running (type c at thesimics> prompt). Remember that if Simics is not running, the CPU of the target machine is not running either. Do not be surprised if output suddenly appears on the VGA console when you continue the simulation. This is due to the window’s keyboard buffer flushing out what you have been typing when the simulated cpu was not running.
3.3
Using Checkpointing
In order to avoid booting FirstSteps every time, we use the facility known as configu-ration checkpointing or simply checkpointing. This enables Simics to save away the entire state of a simulated machine into a portable format to be loaded at a later time. The state is saved using the command write-configuration.
control-C
---simics> write-configuration "fs-config-1.config"
[disk0_image] Opened subfile ’fs-config-1.config.disk0_image’ (format craff) [mem0_image] Opened subfile ’fs-config-1.config.mem0_image’ (format craff) [rom0_image] Opened subfile ’fs-config-1.config.rom0_image’ (format craff) simics>
Since Simics only supports one configuration per session, we must quit Simics in order to restart the simulation from the saved configuration.
Simics Output simics> quit
[disk0_image] Closed craff file ’first-steps1.craff’.
[disk0_image] Closed craff file ’fs-config-1.config.disk0_image’. [mem0_image] Closed craff file ’fs-config-1.config.mem0_image’. [rom0_image] Closed raw file ’rombios-2.35’.
[rom0_image] Closed raw file ’voodoo3-pci-bios.bin’.
[rom0_image] Closed craff file ’fs-config-1.config.rom0_image’. Simics license checked in!
bash$
The FirstSteps VGA console should now have disappeared. We start Simics again, but this time without-x firststeps.simics, since we have our own configuration to start from. At the simics prompt, do:
Simics Output bash$ ./simics
Simics startup wrapper. Copyright (c) 2000-2002 Virtutech AB. Defaulting to host x86-linux. Set SIMICS_HOST to override. Checking out a license... done: academic license.
[...]
Type ’help help’ for info on the on-line documentation. simics> read-configuration "fs-config-1.config"
and the machine comes back to the exact same state (including the VGA console, of course). You can continue the simulation again and check that everything is the same.
To learn more about Simics configurations, you can read the chapter9 in the User Guide. Simics includes many pre-configured machines. They are described in the Simics Target Guides.
3.4. Tracing
3.4
Tracing
This section describes how to use the tracing facility provided by the trace module. It en-ables the user to get all instructions, memory accesses, and exceptions printed out in the order in which they occurred. First, let us restart Simics with the initial configuration:
Simics Output
bash$ ./simics -x firststeps.simics
Simics startup wrapper. Copyright (c) 2000-2002 Virtutech AB. Defaulting to host x86-linux. Set SIMICS_HOST to override. [...]
simics>
Then load the trace module by typing:
Simics Output
simics> load-module trace
[trace module] Created a trace0 object Module trace loaded
simics>
The trace-module tells us that it has created an object namedtrace0that will handle the tracing. This object supports two commands, trace0.start and trace0.stop; what they do should be obvious. Let us try to trace the first 10 instructions executed when booting FirstSteps.
Simics Output
simics> trace0.start Tracing enabled simics> c 10
<cs:0x0000fff0> [...] inst: [ 1] CPU 0 e9 68 e0 jmp 0xe05b
<cs:0x0000e05b> [...] inst: [ 2] CPU 0 b8 4a 7b mov ax,0x7b4a
<cs:0x0000e05e> [...] inst: [ 3] CPU 0 ff e0 jmp ax
<cs:0x00007b4a> [...] inst: [ 4] CPU 0 b8 00 90 mov ax,0x9000
<cs:0x00007b4d> [...] inst: [ 5] CPU 0 8e c0 mov es,ax
<cs:0x00007b4f> [...] inst: [ 6] CPU 0 bb ff ff mov bx,0xffff
<cs:0x00007b52> [...] inst: [ 7] CPU 0 26 87 1e 20 fd xchg word [...] <es:0x0000fd20> [...] data: [ 1] CPU 0 Vani WB Read 2 bytes 0x0
<es:0x0000fd20> [...] data: [ 2] CPU 0 Vani WB Write 2 bytes 0xffff
<cs:0x00007b57> [...] inst: [ 8] CPU 0 83 fb 00 cmp bx,0x0
<cs:0x00007b5a> [...] inst: [ 9] CPU 0 0f 85 f1 ff jne 0x7b4f
<cs:0x00007b5e> [...] inst: [10] CPU 0 b8 fe ff mov ax,0xfffe
[cpu0] <cs:0x00007b61> <p:0xffff7b61> 0 0 0 0 0 0 0 89 c4 mov sp,ax simics>
generic information about understanding and writing Simics modules.
3.5
Scripting Simics
Let us use a Simics script to do a somewhat more complex trace. The following script runs one instruction at a time until the registerespis modified. Then it turns on tracing and traces the following ten instructions. It is available as the script filetrace.simics
in thefirststeps/directory.
# trace.simics load-module trace
@start_cycle = conf.cpu0.cycles @esp = read_reg_cmd("cpu0","esp")
@while read_reg_cmd("cpu0","esp") == esp: SIM_continue(1)
@print "CPU has executed", conf.cpu0.cycles - start_cycle, "cycles" @print "%esp has changed. Starting trace and running 10 instructions." trace0.trace-start
run 10
Simics uses Python as its internal scripting language. By prefixing a line with@, we tell the command line to evaluate the line as a Python statement instead of a Simics command.
We can run this script:
Simics Output
bash$ ./simics -x firststeps.simics -x trace.simics [...]
[trace module] Created a trace0 object Module trace loaded
CPU has executed 11 cycles
%esp has changed. Starting trace and running 10 instructions. Tracing enabled
<cs:0x00007b63> [...] inst: [ 1] CPU 0 b8 00 00 mov ax,0x0
<cs:0x00007b66> [...] inst: [ 2] CPU 0 8e d8 mov ds,ax
[...]
<ss:0x0000fffa> [...] data: [ 4] CPU 0 Vani WB Write 2 bytes 0x0 [cpu0] <cs:0x000072a7> <p:0xffff72a7> 0 0 0 0 0 0 0 89 e5 mov bp,sp simics>
3.6. Importing Files into the Simulated Machine
The script tells us thatesphas changed after 11 cycles, and the first instruction exe-cuted after that ismov ax,0x0(at addresscs:0x00007b63).
Note: You can also run the script from Simics’ command-line by using the
run-command-filecommand.
To learn more about Simics’ scripting capabilities, you can read the chapters10and
11in the User Guide.
3.6
Importing Files into the Simulated Machine
FirstSteps is configured with the/hostfilesystem functionality. The/hostfilesystem allows you to mount your real file system inside the simulated machine and to access it directly. Let us load the previously saved checkpoint and import some files into the simulated machine. The -c option tells Simics to run the read-configuration command on the specified file after it has loaded.
Simics Output
bash$ ./simics -c fs-config-1.config [...]
simics> c
Then at the simulated machine prompt, mount the directory/host:
Target Output
firststeps:˜# mount /host [hostfs] mounted
firststeps:˜# ls /host
bin etc initrd opt tmp
boot floppy lib proc usr
cdrom home lost+found root var
dev host mnt sbin vmlinuz
firststeps:˜#
You can copy files from your real machine on the simulated disk and use them inside your simulated machine.
Note: The/hostfilesystem is mounted read-only, that is you can not write files from the simulated machine to your real machine. We also recommend that you copy files on the simulated disk before you execute them instead of running them directly from the
pre-configured machine.
3.7
Debugging a Sample Program
Simics provides many tools for debugging simulated programs. Here we will use the module symtable to trace a very simple program.
Since you have already mounted the/hostfilesystem, you can copy the example file
[simics]/home/firststeps/debug_exampleinto the simulated machine. Just in case, they are also available in the /root/example/directory in the simulated ma-chine.
Target Output
firststeps:˜# cp /host/home/joe/simics/home/firststeps/debug_example .
Note: The source code of this small sample program is available asdebug_example.c
in thefirststeps/directory. The executable was compiled for a GNU Libc 2 system. If you recompile it, do not forget to include debugging symbols to be able to run the tutorial.
If you try to run it as well, you will get the following output:
Target Output
firststeps:˜# ./debug_example Allocating space
Counting
Primes less than 1000000: 78498 Done
firststeps:˜#
In Simics, we will load the symtable module and load the symbol table correspond-ing todebug_example.
Simics Output
control-C
---simics> load-module symtable Module symtable loaded
simics> new-symtable file = debug_example
Created symbol table ’debug_example’ for context ’primary-context’ Loading symbols: debug_example
3.7. Debugging a Sample Program
simics>
The symbol table is now loaded. However, to get the right code line to be printed as well, we need to specify the path of the source filedebug_example.c. symtable has created a debug_example object. We will use the source-path command to tell symtable where to find the source file. This command can work in different ways; we will use it to replace the wrong directory name included in the file (/disk01/joe) by the directory where the filedebug_example.cis actually located:
Simics Output
simics> debug_example.source-path path = /disk01/joe>[simics]/home/firststeps simics>
where [simics] is the absolute Simics directory (i.e, like in/home/joe/simics/ home/firststeps). Take care that there is a > between the two paths to translate.
Note: If you recompile the example yourself, you will not need to change the source path, because the absolute path included along with the debugging information will be correct.
Thedebug_exampleprogram is using a very interesting feature of Simics called a “magic instruction”. This is an instruction that doesn’t affect the state of the simulated machine, but tell Simics that this specific “magic” instruction has run and allows to place breakpoints or other interesting events when the instruction is encountered.. The source code of debug_example has a magic instruction placed just before the main loop of the program.
We start by telling Simics to stop the simulation every time a magic breakpoint is reached with the magic-break-enable command. We continue the simulation, then run debug_example inside the simulated machine and Simics will automatically stop when the magic instruction is reached.
Simics Output
simics> magic-break-enable simics> c
--- after some simulation time ---Magic breakpoint
Pseudo exception 1027 caught
[cpu0] [...] 66 87 db magic breakpoint (xchg bx, bx)
main (argc=1, argv=0xbffffe14) at /disk01/joe/debug_example.c:47
47 MAGIC_INSTRUCTION;
simics> si
[cpu0] [...] c7 45 fc 02 00 00 00 mov dword ptr 0xfc[ebp],0x2 49 for (i=2; i<MAX_VALUE; i++)
simics> si
[cpu0] [...] 7e 02 jle 0x8048585
49 for (i=2; i<MAX_VALUE; i++) simics>
When you run the step instruction (si) command, symtable will print out the code line corresponding to the current instruction.
To learn more on debugging with Simics, you can read the chapter13in the User Guide. Magic instructions are described in the section11.2.3.
3.8
Connecting FirstSteps to the Network
This section describes how to connect one or more machines together in a network us-ing Simics Central. Simics Central works very much like FirstSteps or any other target computer, except that it does not have a CPU. The core of Simics Central is its ether-net module called etherether-net-central. This module provides a virtual ether-network to which Simics instances, such as FirstSteps, can connect. Connecting to this virtual network is tantamount to physically connecting a network card to a switch using a ethernet cable.
Simics Central also has ARP, DHCP, and DNS implementations, to make it easy to quickly set up a small network of machines. A legitimate question is: why not just bridge the ethernet-device in the simulated machine directly to a real network (like “bridged networking” in VMWare)? The answer to that question is that we often want to simulate the network itself, and we want to get rid of the non-determinism inher-ent in networks. One of Simics Cinher-entral’s tasks is therefore to synchronize each of the connected Simics instances so that they execute in a fully deterministic manner. Simics Central also allows to connect the simulated network to a real network, by using central as a router.
3.8.1
Connecting a Single Machine to Simics Central
We begin by starting a Simics Central process in a new terminal window:
Simics Output
bash$ cd [simics]/home/central bash$ ./simics -x central.simics
Simics startup wrapper. Copyright (c) 2000-2002 Virtutech AB.
+---+ Copyright 1998-2002 by Virtutech, All Rights Reserved
| Virtutech | Version: Simics 1.4.0
| Simics Central | Compiled: Mon Sep 16 15:07:44 CEST 2002 +---+
3.8. Connecting FirstSteps to the Network
Using port 4711, socket file mode 0666 Local hostname: computer.virtutech.com Installing new connection: fd 3, index 0 Installing new connection: fd 4, index 1 [ether0] initializing network net0:
[ether0] net: 10.10.0.0
[ether0] netmask: 255.255.255.0
[ether0] broadcast: 10.10.0.255
[ether0] own ip: 10.10.0.1
[ether0] Device registering with Ethernet Central:
[ether0] simics: simics central
[ether0] device: pseudo device
[ether0] network: net0
[ether0] requested addr: 10:10:10:10:10:10 [ether0] assigned addr: 10:10:10:10:10:10 Setting minimum number of processes to 1 New minimum latency: 2 * 25000000
simics> c
Since Simics Central is already configured correctly for our needs, type c to start it. Nothing will happen until a Simics instance connects to it.
We will now focus on connecting FirstSteps to the simulated network. We will start by booting FirstSteps from the firststeps.simics. The network is automatically configured by the simulated operating system. We also need to tell Simics to connect to Simics-central by specifying the -central hostname option where hostname is the computer where you run Simics-central (to get the computer name, use the command
hostnamein a terminal).
Simics Output
bash$ cd [simics]/home/firststeps
bash$ ./simics -central hostname -x firststeps.simics
Simics startup wrapper. Copyright (c) 2000 Virtutech AB. Defaulting to host x86-linux. Set SIMICS_HOST to override. [...]
simics> lance0.connect net0 simics> c
The command lance0.connect plugs in the (virtual) ethernet-cable running from FirstSteps into the switch (named net0, simulated by Simics Central). In our Simics Central window we will see some activity:
Simics Output
Connecting: /tmp/simics-19421
Connection established with local Simics Installing new connection: fd 6, index 2 Enough Simics processes (1) to start running!
[ether0] simics: simics at localhost
[ether0] device: lance0
[ether0] network: net0
[ether0] requested addr: 10:10:10:10:10:34 [ether0] assigned addr: 10:10:10:10:10:34
This means that Simics Central has recognized that a network device with ethernet address10:10:10:10:10:34 has been connected. Note that there will be no traffic until FirstSteps has set up the network deviceeth0.
The Linux distribution running on FirstSteps will automatically configure the net-work and default routes to the local netnet-work and the gateway provided by Simics Cen-tral. When the boot sequence is finished, we can enable console input again, login and then try to have a look at the configuration and ping Simics Central:
Target Output
firststeps:˜# ifconfig
eth0 Link encap:Ethernet HWaddr 10:10:10:10:10:34
inet addr:10.10.0.17 Bcast:10.10.0.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:32 errors:0 dropped:0 overruns:0 frame:0 TX packets:32 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:100
RX bytes:3013 (2.9 kb) TX bytes:2911 (2.8 kb) Interrupt:7 Base address:0x300 DMA chan:4
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0 UP LOOPBACK RUNNING MTU:3924 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b) firststeps:˜# ping -c 5 central
PING central.network.sim (10.10.0.1): 56 data bytes 64 bytes from 10.10.0.1: icmp_seq=0 ttl=32 time=151.1 ms 64 bytes from 10.10.0.1: icmp_seq=1 ttl=32 time=151.1 ms 64 bytes from 10.10.0.1: icmp_seq=2 ttl=32 time=151.1 ms 64 bytes from 10.10.0.1: icmp_seq=3 ttl=32 time=151.1 ms 64 bytes from 10.10.0.1: icmp_seq=4 ttl=32 time=151.1 ms central.network.sim ping statistics
---5 packets transmitted, ---5 packets received, 0% packet loss round-trip min/avg/max = 151.1/151.1/151.1 ms
3.8. Connecting FirstSteps to the Network
Since we have a configured local network, it is time to save a checkpoint so we do not need to reboot FirstSteps. Use control-C on the Simics FirstSteps terminal and save the configuration:
Simics Output
control-C
---simics> write-configuration fs-network
3.8.2
Connecting Simics Central to a Real Network
Note: To do the following, you need root access on the host machines you are working with. If you do not have root access or if you are not used to doing network configura-tion, contact your system administrator for assistance.
Simics Central also allows routing to and from a real network, i.e., the network of the host machine(s). For this to happen, we need to configure the simulated machine to use Simics Central as gateway, and also configure the machine on the real network to use Simics Central as a router to the simulated network.
Note: Simics Central can not route traffic between the simulated network and the ma-chine it is running on. This means that you cannot communicate with the simulated network from the machine on which Simics Central is running.
To connect Simics Central to the real world, we need to be running Simics Central as therootuser on the host machine (to access the network device). To follow the example given below, start Simics Central as root on a different computer than the one FirstSteps is running on, and run the command ether0.connect-real-network.
Simics Output
bash$ telnet another_computer bash$ su
password:
bash# ./simics -x central.simics
Simics startup wrapper. Copyright (c) 2000 Virtutech AB. Defaulting to host x86-linux. Set SIMICS_HOST to override. [...]
simics> ether0.connect-real-network Installing new connection: fd 8, index 2 [ether0] initializing network real-net:
[ether0] net: 10.0.0.0
[ether0] netmask: 255.255.255.0
[ether0] simics: simics central
[ether0] device: pseudo device
[ether0] network: real-net
[ether0] requested addr: 10:10:10:10:10:10 [ether0] assigned addr: 10:10:10:10:10:10 simics> c
Now, if you want to connect from the real world to the simulated machine, you will need to add a route on your real machine to tell it to send the network packets to the machine running Simics Central. You can do that with the command:
bash# /sbin/route add -net 10.10.0.0 netmask 255.255.0.0 gw another_computer
where another_computer is the name of the machine running Simics Central. The syntax for theroutecommand may vary between operating systems, the syntax above is for Linux. You need to add a route on each machine from where you want to reach the simulated network.
For the next example to work, you need to set up a route on a real machine that we will try to ping to later on. You will probably need to berootto run the command.
Let us now restart FirstSteps from our previous checkpoint:
Simics Output
bash$ ./simics -central another_computer -c fs-network
Simics startup wrapper. Copyright (c) 2000-2002 Virtutech AB. Checking out a license... done: academic license.
[...]
[rom0_image] Opened subfile ’fs-network.rom0_image’ (format craff) simics> c
FirstSteps is already configured with a default route with central as gateway, so we can ping from FirstSteps to a real machine:
Target Output
firststeps:˜# ping -c 5 real-machine.virtutech.com
PING real-machine.virtutech.com (10.10.10.10) 56 bytes of data.
64 bytes from real-machine.virtutech.com (10.10.10.10): icmp_seq=0 ttl=254 [...] 64 bytes from real-machine.virtutech.com (10.10.10.10): icmp_seq=1 ttl=254 [...] 64 bytes from real-machine.virtutech.com (10.10.10.10): icmp_seq=2 ttl=254 [...] 64 bytes from real-machine.virtutech.com (10.10.10.10): icmp_seq=3 ttl=254 [...] 64 bytes from real-machine.virtutech.com (10.10.10.10): icmp_seq=4 ttl=254 [...] real-machine.virtutech.com ping statistics
3.8. Connecting FirstSteps to the Network
round-trip min/avg/max = 94.342/98.551/99.619 ms firststeps:˜#
That’s it! The simulated machine can communicate with the exterior world. You can now transfer files, send mail or even browse the web (but you will need a more complete machine than FirstSteps: have a look at Enterprise!).
Note: If you try to connect the simulated machine from the exterior world, you need to specify its IP address since your real machine does not know which DNS to ask to the get a name translation.
To learn more about simulating networks with Simics-central, you can read chapter
Troubleshooting
Simics complains about not finding PythonYou need to have Python 2.2.x installed for Simics to run, since all the command-line interface is Python-based. You can download Python athttp://www.python. org/download.
Simics doesn’t find any license
When starting, Simics tries to check out your license and it will not start if it can’t find a valid one. Check the following:
• If you have a single computer license, check that the corresponding license file is in thesimics/licenses/directory.
• If you have a floating license, check that the corresponding license file is in the simics/licenses/directory. Simics needs to know which server to contact to check out the license. Check as well if the server is reachable from your machine, and if the license server is running.
• A license file is essentially a text file. You can check in the file if the license has expired. As soon as it does, the license won’t be valid anymore.
• If you change your license, you may have troubles with the caching system used by FlexLM. Try to delete the file˜/.flexlmrcand start again Simics.
Simics reports a crash and switch to safe mode
This means you found a bug in Simics. You can report it through the Simics Forum. Try to include as much information as possible for us to reproduce the crash. If the crash is an assertion, this means Simics has reached a state that shouldn’t be allowed. Please report the full assertion text.
If you are developing your own module, please check carefully that your module is not responsible for the crash, since it is loaded as a part of Simics and may crash it just as well as our own code.
In safe mode, you may still issue commands. It is recommended to save the con-figuration and restart Simics.
Simics quits after 100000 errors
By default, when Simics has received 100000 error messages, it assumes this was too many errors for a normal simulation and stops. If this is not the behaviour you want, you can set the maximum error messages count through the simerrmax attribute in the sim object.
Simics Central does not connect to the real network
Check that you run Simics Central asrootto have a direct access to the network device.
Check the section14.9to get more information about diagnosing and solving net-work problems.
Glossary
• callback — A user-defined function installed so that it will be called from Simics, for example when a hap occurs.
• checkpoint — A number of files, together constituting a simulation state. Simics can save its current state as a configuration checkpoint.
• CLI — See Command Line Interface.
• code profile — A listing of source code or assembler instructions where each line has an array of counters attached. Predefined counters include the number of times line has been executed, the number of times branching from a line, and the number of times branching to a line.
• Command Line Interface — The default Simics command-line (user interface). It uses a simple language implemented in Python, and is variously called the Simics “front end” or the “CLI”.
• configuration — A configuration is a description of a target architecture, and is loaded into Simics with the read-configuration command. Note that a configura-tion can also include the state of the target, and saved from within Simics using the write-configuration command, in which case it provides a portable checkpoint facility.
• craff — Compressed Random Access File Format, used to save raw data for ob-jects, such as disk dumps and target memory contents. A separate utility allows you to compress input data to Simics, such as target disk dumps, in a format that Simics can use directly.
• cycle — The smallest unit of time in Simics. The cycle count is usually the same as the step count, except in Simics Out-Of-Order or when memory transactions are stalled.
• device — A module modeling a hardware device that the target processor can access.
• event — A Simics event occurs at some predefined point of simulated time. Time can be specified either as a number of issued instructions on a simulated processor, or a number of simulated clock cycles.
• extension — A module which is not a device, but adds features to Simics; e.g., a statistics collection module.
• hap — Defined simulation or simulator state changes that may trigger callback functions.
• host addresses — Logical memory addresses on the host machine; i.e., addresses in the virtual memory space that the simulator itself is running in.
• host — The machine the simulator (Simics) is running on.
• logical addresses — Memory addresses corresponding to virtual or logical ad-dresses on the target machine. These are typically translated by a memory man-agement unit (MMU) to physical addresses.
• memory hierarchy — A user defined module that simulates caches and timing of memory operations. Interfaces to Simics using a memory transaction data struc-ture.
• module — A dynamically linked library or a script that interfaces to Simics and extends the functionality of the simulator. A module is either an extension or a device.
• physical addresses — Memory addresses corresponding to physical/real addresses on the target machine; i.e., the actual address bits put out on the memory bus. • Python — An object oriented script language. Seehttp://www.python.org
for more info.
• /host filesystem — A “magic” feature allowing simple accesses from a simulated system to the host’s real file system. It is called “hostfs” or “slash host” because the preconfigured dumps have a “/host” mount point for the magic device. This is presently only supported when running Solaris or Linux on the target machine. • STC — Simulator Translation Cache. A mechanism in the simulator to improve simulator performance. Among other things, it filters uninteresting memory ac-cesses from the memory hierarchy.
• step — An issued instruction that completes or causes an exception, or an external interrupt.
• system level instruction set simulation — The effect of every single instruction is simulated both on user and supervisor level. At any instruction, the simulation can be stopped and state can be inspected (and changed).
Startup Options
This chapter describes the most important command-line options accepted by Simics. A complete description can be found in the reference manual.
There are two ways of starting Simics. You can start it by simply running the binary file in the directory[simics]/host/binwhere host corresponds to your computer, or by using a startup scriptsimicsthat is present in each simulated machine directory. By using the script you can select a specific processor model without worrying about where the program files are, or their exact names. For example, if you want to run enterprise, an x86 machine, with a Pentium III, you will run a command similar to:
joe@computer:[simics]/home/enterprise$ ./simics x86-p3 -x enterprise.simics
Thesimicsscript selects a default target (herex86-p2) if none is provided.
6.1
Processor Models
Here is a list of the different processor models that are provided by default with Simics. If a specific model is missing and you wish to use it, you can request it from Virtutech via the Simics Forum.
Processor model Description
Simics/SunFire
sparc-u2 UltraSPARC II
sparc-u2-o3 UltraSPARC II (out-of-order mode—see chapter16)
sparc-u2-ma UltraSPARC II (micro-architecture mode—see chapter16) Simics/Serengeti
sparc-u3 UltraSPARC III
sparc-u3-o3 UltraSPARC III (out-of-order mode—see chapter16)
6.2. Common Options
sparc-u3+ UltraSPARC IIIcu Simics/x86
x86-486sx Intel 486SX (no hardware floating-point)
x86-p2 Intel Pentium II
x86-p2-stall Intel Pentium II (with memory stalling support—see chapter16)
x86-p3 Intel Pentium III
x86-p4 Intel Pentium 4
x86-p4-stall Intel Pentium 4 (with memory stalling support—see chapter16) Simics/x86-64 x86-hammer AMD x86-64 Simics/Alpha alpha-ev5 Alpha 21164 Simics/PPC ppc750 PPC 750 ppc7450 PPC 7450 Simics/IA64
ia64-itanium Intel Itanium
ia64-itanium2 Intel Itanium2 Simics/ARM
armv5te Generic ARMv5 Simics/MIPS
mips-4kc MIPS 4Kc
6.2
Common Options
Here is a list of the most common options used when starting Simics:
-cfile
Tells Simics to read a specific configuration file. This is equivalent to run the com-mand read-configuration file after starting Simics.
-centraladdress:port
Tells Simics to connect to a specific Simics Central instance. This option takes an IP address and an optional port number (the default is 4711). If no port number is supplied, and the local host’s address is supplied, Simics will try to connect to the default Unix file socket.
-h
Makes Simics print out a list of the possible startup flags along with a short de-scription.
-v
Makes Simics print out its version number.
-xfile
Usual Simics Commands
This chapter contains a brief description of usual Simics commands. A complete list by categories is available in all the Simics Reference Manuals. The help command at the prompt also allows you to browse the commands’ documentation.
7.1
Simulation
At the Simics prompt, you can run the simulation with the continue (c) command, fol-lowed by the number of steps you want to run. If no argument is provided, the simula-tion will run until control-C is pressed in the Simics console.
You can also use stepi (si) to make the simulation progress step by step. On out-of-order versions of Simics, you can use the step-cycle (sc) command to make the simula-tion progress cycle by cycle.
7.2
Simulation State
All processors support the pregs command to show the state of the main registers. The argument -all will allow you to inspect all the registers instead of the usual working set. If the processor has floating-point registers, pfregs can be used to print them out. By default, the pregs command (and other commands dependent on the cpu) uses the current cpu scheduled by the simulation. You can change the current selected cpu by using the pselect command. This won’t affect the simulation scheduling.
You can inspect and change the contents of a register by using the read/write-reg commands. Using % is equivalent to the read-reg command (i.e.,%pc, %eax, ...). You can inspect and change the contents of the memory by using the commands get, x and set.
7.3. Scripts
7.3
Scripts
Simics can load both Simics scripts (a file containing a list of acceptable commands for the Simics frontend) or Python script with the commands command-file and
run-python-file. You can read more about Simics scripting in chapter10.
7.4
Modules
Simics usually handles modules automatically when loading a configuration. You may however want to load a specific module by yourself (like the trace module) with the
load-modulecommand. The modules currently loaded are available through the
list-modulescommand. If a module fails to be loaded, it will be listed by the
list-failed-modulescommand, along with an explanation of the problem. You can use the -v argu-ment to get the exact error message preventing the module from loading.
7.5
Command-Line Interface
Simics command-line interface uses GNU Readline, which means you can use the usual readline control sequences for history browsing and command-line editing.
You can also tell the prompt to run commands every time a new command is issued with display command. To stop the command from being run, use undisplay number where number is the number written before the command output.
The print command allows you to print out a value in different ways (binary, hex-adecimal, etc.).
The CLI also supports the following Unix shell-like commands: cd, date, dirs, echo,
The Command Line Interface
The Simics Command Line Interface (CLI) is an advanced text based user interface with builtin help system, context sensitive tab-completion, and scripting support (us-ing Python).
8.1
Invoking Commands
Commands are invoked by typing them at the command line followed by their argu-ments. The synopsis part of a command documentation (see the Simics Reference Manual) explains how to call a command. Here are two examples:
SYNOPSIS
command1-x -y -small [cpu-name] address (size|name)
SYNOPSIS
command2files ...
Arguments starting with a hyphen are flags and are always optional for a command. Flags can be more than one character long so it is not possible to write-xyfor-x -y. The order of the flags is not significant and they can appear anywhere in the argument list.
Arguments enclosed within square brackets are optional, thus it is not necessary to specify cpu-name in the example above. address,on the other hand, is required. The last argument to command1 is either a size or a name, but not both. Such arguments are called polyvalues and can be of different types. Size and name are called sub-arguments. If an argument is followed by tree dots as the file argument in command2 it indicates that the argument can be repeated one or more times.
The type of the arguments, e.g., if they are integers or strings, should be evident from their names. For example size should be an integer and name a string if not documented otherwise.
Integers are written as a sequence of digits beginning with an optional minus charac-ter for negative numbers. Hexadecimal numbers can be written by prefixing them with