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.
About 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 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 cause 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.
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 12 or later.
- 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 12 or later, built for UCRT and POSIX threads.
- 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. A few Python packages are also required to run
Simics. These are downloaded and installed automatically when setting
up a Simics project (4), into a project local standard
Python virtual environment.
If no Python is available on the host, a Python installation is
provided in Simics package 1033. If that is installed, Simics will
normally find and use Python from there.
- 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 describes 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 respective bin\vmp-kernel-unload.bat scripts 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 with /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 neither version 4.8 nor 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.
Note: 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 to remove 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 results 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.