Previous - Up - Next

6.5   Ready-to-run Configurations

Simics includes many customizable ready-to-run configurations. Because checkpoint files are by definition very static, these example configurations are not checkpoint-based, but rather build on components and scripts to generate a working simulated machine.

The example configurations are located in separate directories for each system architecture: [simics]/targets/architecture. Each of these directories contains a number of Simics scripts (i.e., files containing Simics commands):

Script that defines a complete simulated machine, i.e., both hardware and software, that can be run by Simics directly. The common script use the -system.include script to define the hardware, and the -setup.include script for software configuration. The -common.simics scripts may add additional hardware in some cases.

These are the files you want to use to start the standard example machines in this directory.

<machine> in the script name is either a Unix machine name, or a some other name that defines the hardware/software combination.

A script that extends the -common.simics script with a new feature. Many minor features, such as the processor frequency, can be controlled using parameters to the common script, but features that are mutually exclusive are added as separate scripts. Typical examples are scripts that add different diff-files to the same disk image in the system setup.
Script that defines the hardware of a machine. This script can be shared by several simulated machines that are based on the same hardware. The hardware setup is typically configurable using some standard parameters.
Script that defines the software and possibly configures the machine to run the selected software, for example setting boot path, and scripting automatic login.

The example configurations are designed to work with the disk images distributed by Virtutech. The machines are described in the Target Guides corresponding to each architecture.

Several machines may be defined for a given architecture, and thus the corresponding architecture directory will contain several machine-common.simics scripts.

Note: The [simics]/home/machine directory contains deprecated example machines provided for backward compatibility reasons. These machine configurations are based on a combination of Simics and Python scripts. It is highly recommended to use the component-based scripts defined in [simics]/targets/architecture rather than the scripts in [simics]/home/machine.

6.5.1   Customizing the Configurations

There are several ways to customize the examples provided with Simics. The table below shows them sorted by how simple they are to use.

The machine scripts distributed with Simics can be modified by setting parameters (CLI variables) before the script is actually run. This is the easiest way to change the default configuration. Parameters can typically be used to change properties such as the amount of memory, the number of processors and the primary MAC address. The available parameters are listed in each Target Guide.
A simulated machine is defined by several scripts, as described above. By replacing the -common.simics file with a user defined one, the system can be configured in more details while keeping the machine definition provided by the -system.include file. Similarly the -setup.include can be replaced to configure different software on the same machine.
Components represents real hardware items such as PCI cards, motherboards, and disks. Using components to configure a machine provides freedom to set up the simulated machine in any way that is supported by the architecture. The -system.include files use components to create their machine definitions. A complete description of components is provided earlier in this chapter.
Objects and Attributes
A component is implemented by one or more configuration objects in Simics, and each object has several attributes describing it. Configuring machines on the object and attribute level is not supported in Simics, and such configurations may not work in future versions.

Below is an example of a simple configuration based on ebony, that uses parameters to configure two machines slightly differently that both run in the same Simics session.

$freq_mhz = 100
$memory_megs = 128
$host_name = "ebony0"
set-component-prefix "ebony0_"
run-command-file "ebony-linux-common.simics"

$freq_mhz = 200
$memory_megs = 256
$host_name = "ebony1"
set-component-prefix "ebony1_"
run-command-file "ebony-linux-common.simics"

6.5.2   Adding Devices to Existing Configurations

The parameters available for each predefined machine allows the user to do minor modifications. It is also possible to extend the ready-to-run configurations with additional components without creating new machine setups from scratch. This is done by adding components and connecting them to the machine before the instantiate-components command is run.

Since the machine setup scripts are located in the read-only master installation of Simics, they should not be modified. User files that add new components should instead be placed in the corresponding [workspace]/targets/architecture directory.

The following commands adds a SCSI controller, and one SCSI disk, to one of the PCI slots in the predefined ebony-linux-common.simics file. The commands should be placed in a file in the target directory for ebony in the workspace, for example in [workspace]/targets/ebony/ebony-linux-scsi.simics

script-branch {
    wait-for-variable machine_defined
    $sym = (create-pci-sym53c810)
    $scsi_bus = (create-std-scsi-bus)
    $system.connect pci-slot2 $sym
    $scsi_bus.connect $sym
    $scsi_bus.connect (create-std-scsi-disk scsi_id = 0 size = 3221225472)

run-command-file "%script%/ebony-linux-common.simics"
The script works by starting a script branch that waits for the CLI variable $machine_defined to be written. All machine defining scripts distributed with Simics sets this variable, by convention, when the complete machine has been created but before the components are instantiated. Since many script branches can wait for the same variable, it is possible to extend the same configuration from different scripts in this way.

When the machine has been created, and machine_defined variable is written, the script branch continues to execute. It creates a SCSI controller, a SCSI bus and a 3GB disk, and then connects them. The $system variable is defined in the ebony-system.include where the machine is created. When the script branch has finished executing, the main script will continue and run instantiate-components.

The example above extends the ebony-linux-common.simics file in the workspace target directory. To access files in the target directory of the main Simics installation, the %simics% path shortcut can be used:

run-command-file "%simics%/targets/ebony/ebony-system.include"

Here's another example that adds a network card in PCI slot 3 and connects it to the same network as the primary ethernet cards:

$create_network = yes

script-branch {
   # wait for machine to be setup and connect the new eth before instantiation
    wait-for-variable machine_defined
    $add_eth = (create-pci-dec21143 mac_address = "10:10:10:10:10:28")
    $system.connect pci-slot3 $add_eth
run-command-file "%script%/ebony-linux-common.simics"                          
ethernet_link_cmp0.connect $add_eth

Previous - Up - Next