Installation Guide
This document describes how installations of Intel® Simics® Simulator (hereafter
called “the simulator”) work and how to manage Intel Simics Projects, also
called “user projects”. It identifies the hardware and software requirements for
installing and running the simulator. It should be read by users doing
installations on their own, and all administrators.
For formatting and style, see Documentation
Contents.
The minimum hardware requirements are:
- 64-bit Intel® Architecture processor, either Haswell or newer performance core
(“big core”) architecture, or Gracemont or newer efficiency core (Atom)
architecture.
- VMP requires that Intel® Architecture (Intel® VT-x) is enabled in UEFI/BIOS
and visible to the VMXMON kernel module.
- 16 GB of RAM.
- 8 GB of disk space.
More RAM and/or disk is often necessary, depending on the requirements of the
simulated machine.
For best performance, we recommend:
- A host with at least 32 GB of RAM.
- A host processor with a high clock speed, 4GHz or more.
- At least two host cores per simulation running simultaneously (in
particular, check processor allocations in containers and virtual
machines).
- Since a more recent host processor will run faster than older generations, try
to use the most modern Intel® Architecture processor possible.
- Use fast local storage for the simulator swap.
- Faster memory (RAM) can help, but is not as important as the processor
core itself.
For maximum performance when simulating Intel® Architecture targets, the Intel®
Simics® Simulator can use virtualization (also known as VMP or
VMXMON). The use of virtualization requires an Intel processor with
Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64 and
Intel® Architecture (Intel® VT-x).
- The best performance from virtualization is obtained when the host
is as close to the target as possible. In particular, simulating an
Intel® Architecture Server is usually best done on an Intel®
Architecture Server host of the most recent generation.
- Note that running Intel® Simics® simulations in a virtual machine
typically prevents Intel® VT-x from being used or causes it to run
with a significant reduction in speed. If isolation between
simulator instances is desired, use containers on Linux instead as
they normally allow the use of custom drivers on the host.
Run Time Requirements
A modern Linux distribution (1), with at least
- GLIBC 2.22 or later.
- GTK 2.24 or later — for the GUI.
- Linux 4.12 or later and GCC 9.0 or later — for VMXMON driver compilation.
Supported examples are Suse Linux Enterprise Server 12 (and newer) and Red Hat
Enterprise Linux 8 (and newer).
When running Simics with a user provided Python, or when using Simics as a
Python module, Python version 3.10 or later is required.
Model Builder Requirements
- GCC 6.3 compiler. Recommended to use GCC 15 or later (this is required to
build distributed non-sample models).
- Typical GNU-based development environment, with GNU Make 4.1 or later.
- Optional: CMake version 3.4 or later.
- For SystemC*, see footnote (2).
Run Time Requirements
When running Simics with a user provided Python, or when using Simics as a
Python module, Python version 3.10 or later is required.
Model Builder Requirements
- MinGW GCC 6.3 or Microsoft Visual Studio 2015 compiler (3).
Recommended to use MinGW GCC 15 or later, built for UCRT and POSIX threads
(this is required to build distributed non-sample models).
- MinGW development environment, with GNU Make 4.1 or later.
- Optional: CMake version 3.4 or later.
- For SystemC*, see footnote (2).
Simics needs a Python installation to run. The minimum required Python
version is 3.10 and it must have the ctypes module. A few Python
packages are also required to run Simics. These are
installed automatically when setting up a Simics project
(4), into a project local standard Python virtual
environment.
- Installing additional packages may be necessary.
- The Intel® Simics® SystemC* library has its own
compiler requirements, see the SystemC*
Library programming guide for details.
- The Microsoft Visual C++ compilers are only supported
for C++ modules.
- Setting up a project using
project-setup
and addon-manager does not require any extra Python packages.
As a customer you should have received instructions that describe which packages
to install and where to find them. If this is not the case, contact your
provider to obtain this information.
For the installation, use the Intel® Simics® Package Manager (ISPM). ISPM can be
used to check for updated packages, download and install/uninstall, and manage
Intel Simics Projects, also called “user projects”. It supports both command
line (batch) mode and GUI mode.
The simulator is delivered in packages, each one containing different parts of
the functionality. There is a Simics Base package and several add-on packages.
The most common packages are:
- The Simics Base package which provides the simulation engine and the user
interface, as well as a library of standard models.
- Add-on packages, one for each virtual platform, usually containing CPU cores
and various devices. The virtual platform is the simulation platform and the
model of the physical target hardware that is being simulated.
- The Quick-Start Platform for x86 (QSP-x86) add-on package is meant for
training, application development, demos, etc.
Once ISPM has installed Simics Base and one or more platform packages it can
create user projects. A user project is a directory for adding user files and
developing simulation models, and is typically set up for a combination of a few
packages of certain versions. Thus such projects enable users to work with
different package combinations just by switching between projects.
New users are suggested to study the Getting
Started guide which describes how to launch the
simulator and run the QSP-x86 platform.
ISPM can, at any time, install more packages, other versions of already
installed packages, or uninstall packages or versions no longer used.
VMP uses direct execution to simulate x86 systems at near native speed. A kernel
module is needed to communicate directly with the host hardware, and installing
the kernel module requires a separate step.
The VMP feature requires that the host machine running the simulator has the
Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64, and that
Intel® Architecture (Intel® VT-x) is enabled in the host machine firmware (the
UEFI/BIOS) and visible to the VMXMON kernel module.
For more information and known limitations, see Simics User’s
Guide, chapter “Simulation Performance”.
Installing and managing VMP kernel modules requires sudo privileges. Installing
will compile the kernel module and therefore also requires an environment to
build kernel modules. Which packages you need for building kernel modules depend
on the distribution of Linux that you are using, but at least for certain Red
Hat based distributions you would need gcc-c++, kernel-headers, and
kernel-devel. Change directory to the user project and run:
[project]$ bin/vmp-kernel-install
The script will compile and persistently install the kernel modules that are
used by VMP. It will echo what needs to be done, which involves running scripts
in the [simics]/vmxmon/scripts/ directory.
Disable VMP temporarily by running the bin/vmp-kernel-unload script, and
enable VMP with the bin/vmp-kernel-load script. Permanently uninstall VMP from
your host by running the bin/vmp-kernel-uninstall script.
If the installation is read-only, or if you for some other reason want to have
the built VMP artifacts outside of the installation, you can give a directory to
the relevant VMP scripts, for example:
[project]$ bin/vmp-kernel-install /somewhere/directory
[project]$ bin/vmp-kernel-load /somewhere/directory
The kernel module can be loaded and unloaded by running the
bin\vmp-kernel-load.bat and bin\vmp-kernel-unload.bat scripts, respectively,
as administrator. To do that, open a command shell as administrator and run:
[project]> bin\vmp-kernel-load.bat
Another way to perform the same action would be to right-click on
vmp-kernel-load.bat and select run as administrator.
The /AUTO and /DEMAND options select the start option for the VMP service.
With /AUTO (default), the service will be available after restart, whereas
/DEMAND makes the service available just until shutdown or reboot, and then
VMP has to be loaded again when needed.
If the script fails, see the Windows event log for more information. The most
common reason is that Intel® VT-x technology or the NX feature is not enabled in
the UEFI/BIOS. The kernel module will also fail to load if the Hyper-V feature
is enabled.
Intel® Simics® Simulator 7 is binary compatible with recent models from version
6 but it is not directly compatible with either version 4.8 or 5. However, the
simulator supports the same structure of installation and multi-user
configuration, so upgrading should be simple.
For version 4.8, select the 4.8 API to get access to deprecated parts of the
API. This is described in the Simics Migration
Guide.
For both version 4.8 and 5, some Python source code may have to be updated
before recompiling.
Version 7 releases are binary compatible, so nothing special
needs to be done when upgrading. Unless specifically mentioned in their Release
Notes, add-on packages should work with any installation of Simics Base,
version 7. A more detailed description of compatibility
issues for user-created modules is available in the Simics Migration
Guide.
This section provides additional information for users who need deeper
information about some issues.
The Intel® Simics® Package Manager (ISPM) works well for many advanced use
cases. However, sometimes it is necessary to use the addon-manager or the
project-setup programs.
The examples are run on Linux but everything works the same on Windows, except
file paths and file suffixes.
Packages are not installed on top of any other package. Instead each package,
and different versions of it, stay in separate directories. Each user project is
bound to a particular installation of Simics Base, and it keeps its own list of
paths to selected add-on packages that makes them available to the simulation
engine at run-time. To manually configure this list or bind to another
installation of Simics Base, use the addon-manager and project-setup
programs.
Here are a few examples of what those programs can do:
This example will list the add-on packages configured for the particular user
project.
[project]$ bin/addon-manager
=== Using the package list in project ([project]) ===
Configured add-on packages:
QSP-x86 7.0.0 ../simics-qsp-x86-7.0.0
If there are any invalid entries (their paths do not exist anymore, or the
necessary information files are invalid), the addon-manager will suggest
removing them right away.
This example will add a package to the list for the particular user project.
[project]$ bin/addon-manager -s [simics]/simics-gdb-7.0.0
...
Configured add-on packages:
QSP-x86 7.0.0 ../simics-qsp-x86-7.0.0
The following operations will be performed:
-> Add GDB 7.0.0 ../simics-gdb-7.0.0
New package list:
GDB 7.0.0 ../simics-gdb-7.0.0
QSP-x86 7.0.0 ../simics-qsp-x86-7.0.0
Do you want to update the package list? (y/n) [y] <ENTER>
Package list updated
Do you want to update the project? (y/n) [y] <ENTER>
Project updated successfully
This example will remove an add-on package from the list for the particular user
project.
[project]$ bin/addon-manager -d ../simics-gdb-7.0.0/
...
Configured add-on packages:
GDB 7.0.0 ../simics-gdb-7.0.0
QSP-x86 7.0.0 ../simics-qsp-x86-7.0.0
The following operations will be performed:
-> Remove GDB 7.0.0 ../simics-gdb-7.0.0
New package list:
QSP-x86 7.0.0 ../simics-qsp-x86-7.0.0
Do you want to update the package list? (y/n) [y] <ENTER>
...
To manually change which installation of Simics Base a user project is bound to,
use the project-setup program of the installation to bind to.
[project]$ [simics]/bin/project-setup .
Project-local package list updated successfully.
Project updated successfully
The program will save any edited files it wants to update into the project’s
.backup directory.
When building custom modules or extensions on Windows, bin\make.bat must be
setup to find the executables of MinGW. If needed it can be updated by using
project-setup with the –mingw-dir option.
For more options and information about the addon-manager and project-setup
programs, see the Simics Reference
Manual.
By default, the simulator is organized so that the installed packages can be
left read-only in a common location accessible to all users. And users create
custom Intel® Simics® project areas, as described in our manuals.
Historically each installation of Simics Base kept its own list of paths to all
installed add-on packages. Some organizations tweaked the list to create a
“shared configuration” of selected add-on packages.
It is now recommended to use ISPM and instead share manifest files with the
users.
However, if necessary an installation of Simics Base can be configured with
specific add-on packages in the same way as manually managing user projects as
described in a previous section of this chapter. For more information, see about
the addon-manager in the Simics Reference
Manual.
On Windows some functionality of the simulator requires support from third-party
products. This section describes those products.
- OpenVPN TAP driver The port-forwarding kind of real
network connection is included with the simulator. However, to access a real
network using bridges or host connections the OpenVPN TAP driver is required.
The OpenVPN TAP driver can be downloaded from
build.openvpn.net/downloads/releases/.
To learn more about the different real network connection types available, see
the Ethernet Networking technology guide.
- MinGW-w64 If you plan to create models or extensions
for the simulator, you will need the MinGW tools for compilation.
MinGW-w64 provides a GCC compiler and the make programs that are needed to
compile modules on Windows. Download the version for the UCRT runtime with
POSIX threads that is provided at winlibs.com.
Setting up a user project will search in C:\ and in the parent folder of the
Simics Base installation for a directory named mingw64, which must contain the
executables.
- Virtual Serial Ports To connect a
host-serial-console to a virtual serial (COM) port, that port must have been
created in advance. Use any software that can set up virtual COM ports.
All source code for “copyleft” open source software used by, or with, the
simulator is bundled with the same package as the binary is distributed in.
The simulator runs as a user application with standard privileges and is secure
at its core. However, it has some features that present potential
vulnerabilities which are good to be aware of before enabling them. None of them
are enabled by default.
- Access to the command line (CLI) provides access to arbitrary shell commands
on the simulation host (as the user running the simulator). Hence usage of
telnet-frontend potentially opens up shell access to the simulation host
to anyone with network access to it.
- Similarly, access to the simulated target system may potentially be used to
obtain access to the host (as the user running the simulator). The features
which provide communication between target and the simulator, and which
therefore could introduce this type of risk, are SimicsFS, Simics
Agent, the host serial connections in the host-serial-console and
textcon modules, and the debugging functionality in tcf-agent. In
general, bugs in simulation modules can lead to crashes or similar that
result in access to the simulation host.
- Some features may provide access to the simulated target system to users who
have network access to the simulation host. By the previous point, this may
be exploited to access the simulation host. These features are the VNC server
in the graphcon module, the telnet servers in the telnet-console and
textcon modules, the gdb-remote module, distributed simulation and
all types of real network connections using the real-network module.
- The connection modules mentioned above can be configured to use restrictive
connection types, domain sockets on Linux and named pipes on Windows, that do
not make the simulation host accessible over the network.
- Real network connections in particular should be used with care, as they also
allow the target system to initiate connections to the network that the
simulation host is connected to. This can potentially expose information
about the target. Moreover, the Ethernet bridging type of real network
connection makes it possible for users of the simulator, as well as software
at the simulated target machine, to access raw Ethernet frames on the local
network of the host. In particular, do not use the network services of the
simulator (the service-node) when bridging networks, as this exposes
those services to the host network, which is both a security concern and can
also lead to conflicts with other similar services on the network. Also,
Ethernet bridging uses TAP which requires administrator privileges to setup,
an additional risk.
- It is recommended to only use any of the features mentioned above when the
simulation host is on a secure network.
- VMP is a kernel module that must be installed with administrator
privileges and that runs in supervisor mode. Hence, bugs in processor models
can potentially crash the host when running in VMP mode.
Add-on packages often include software intended to run in the simulated target
systems. This software is supplied for demonstration and training purposes only,
and is not intended to be used as part of production setups.