6.2 Checkpointing

Simics's configuration system can save the complete state of a simulation in a portable way. This functionality is known as checkpointing, and the set of files that represent the elements of the systems are called a checkpoint.

Saving and restoring a checkpoint can be done from the command line with the write-configuration and read-configuration commands.

A checkpoint consists of the following files, collected under a directory:

A main configuration file, named config. This is a text representation of the objects present in the system.
Optional image files (described in section 6.2.3), named after each respective image object.

Below is a portion of a checkpoint file showing an object. Saved objects are always represented as OBJECT object-name TYPE class-name { attributes }. In this case we have an instance of the DEC21143 class (fast Ethernet LAN controller interfacing the PCI bus) named dec0. The attribute pci_bus is used to connect the device to the PCI bus.

OBJECT dec0 TYPE DEC21143 {
        queue: cpu0
        component: eth_adapter_cmp0
        component_slot: "dec"
        object_id: "dec0"
        build_id: 0xbb9
        pci_bus: pci_bus0
        ...
}
OBJECT ... TYPE ... {
...

Objects are saved in the main checkpoint file in no specific order.

6.2.1 Compatibility

Simics maintains checkpoint compatibility with older versions, i.e. it is always possible to continue using checkpoints created in a previous version of Simics when upgrading to a new version. Compatibility is always maintained for one major version older than the oldest of the supported API versions. For checkpoints older than that, load the checkpoint with a newer version of Simics and create a new checkpoint.

The opposite is not true. Trying to load a checkpoint created in a newer version of Simics than the local version will typically not work. The same restriction may apply even between minor Simics releases. For example, a checkpoint created with Simics 3.2.2 is not guaranteed to load correctly in the older Simics 3.2.1 release.

6.2.2 Attributes

The short example of the dec0 description only uses a few types of attribute values: strings, objects, and hexadecimal integers. The possible attribute types are:

string: Strings are enclosed in double quotes, with C-style control characters: "a string\n"
integer: Integers can be in hexadecimal (0xfce2) or signed decimal (-17) notation.
boolean: One of TRUE and FALSE.
floating-point: Specified in decimal (1.0e-2) or hexadecimal (0x5.a21p-32) style, just like in C.
object: The name of a configuration object: cpu0.
list: Comma-separated list of any attribute values, enclosed in parentheses. Example: ("a string", 4711, (1, 2, 3), cpu0)
dictionary: The format is a comma-separated list of key/value pairs, like in: { "master-cpu" : cpu0, "slave-cpu" : cpu1 }. The key should be a string, integer or object, while the value can be of any attribute type. Dictionaries are typically used to save Python dictionaries in a checkpoint. Keys must be unique, although Simics does not enforce this.

Each attribute belongs to one of the following categories. Note that only attributes of the first two categories are saved in checkpoints.

Required: Required attributes must be set when creating an object. They are saved in checkpoints. If you edit a checkpoint, you should never remove a required attribute—Simics will complain and refuse to load the checkpoint if you do.
Optional: If no other value is provided, optional attributes take their default value when the object is created. They are saved in checkpoints, but if you edit them out they will revert to their default value when the checkpoint is loaded.
Pseudo: Pseudo attributes are not saved in checkpoints and usually contain read-only information that does not change, or that is calculated when the attribute is accessed. Pseudo attributes are in some cases used to trigger state changes in the object when written.

6.2.3 Images

Simics implements a special class called image for objects that potentially need to save a huge amount of state, like memories and disks. An image represents a big amount of raw data using pages and compression to minimize disk usage.

To save space and time, images do not necessarily save their entire state every time a checkpoint is written. They can work in several ways:

Images can save their state incrementally. At each checkpoint, an image saves the difference between its current state and the previously saved state (either the previous checkpoint or the initial state). This is the default behavior implemented by Simics. This allows several checkpoints to be saved and restored using the same base image and a series of difference files.
Images can save their entire current state in the checkpoint. This results in an independent checkpoint, which does not depend on the base image or on earlier checkpoints, and can therefore be easily moved around or shared. However, independent checkpoints are typically much larger than incremental ones, and can be time consuming to save.
Images can be used as read-write media. In that case the file representing the data is always up to date to the current state. However, this prevents the image from being used in a previously saved incremental checkpoint or initial state, since its contents are modified as the simulation advances. When images are used in this way, only independent checkpoints can be saved.

It is important to understand that when used in incremental mode, images create dependencies between checkpoints. A checkpoint can only be loaded if all previous checkpoints are intact.

As an example, let us have a look at an assumed disk image:

   ...
}
OBJECT disk0_image TYPE image {
        ...
	files: (("tango1-fedora5.craff", "ro", 0, 0x4c5abc000, 0),
                ("disk0_image.craff", "ro", 0, 0x4c5abc000, 0))
        ...
}
...

The checkpointed image is based on the file tango1-fedora5.craff, on top of which is added the file disk0_image.craff that contains the difference between the checkpoint and the initial state.

Files like disk0_image.craff are often called diff files because they contain the difference between the new state and the previous state.

Image Search Path

This section contains more in-depth explanations about image handling that you may skip when reading this guide for the first time.

When successive incremental checkpoints are saved, an image object may become dependent on several diff files present in different directories. To keep track of all files, Simics stores in the checkpoint a checkpoint path list that contains the absolute directory paths where image files may be found. Image file names are then saved as %n%\filename where %n% represents the number of the entry in the checkpoint path, counting from zero.

Note: Simics's checkpoint path is different from Simics's search path (see section 4.4), although both will be used when looking for image files, as show below.

Note: Independent checkpoints do not affect the checkpoint path.

To summarize, when loading a checkpoint or a new configuration, Simics looks for images in the following way:

If the filename does not contain any path information (like image.craff) or contains a relative path (like test\image.craff), the file is looked up first from the checkpoint directory, then from all the path entries in Simics's search path, in order (see also section 4.4 for more information).
Windows example;
If Simics's search path contains [project]\targets\qsp-x86\ and the checkpoint is located in C:\checkpoints, Simics will look for the file test\image.craff in the following places:
1. C:\checkpoints\test\image.craff
2. [project]\targets\qsp-x86\test\image.craff
Linux example;
If Simics's search path contains [project]/targets/qsp-x86/ and the checkpoint is located in /home/joe/checkpoints/, Simics will look for the file test/image.craff in the following places:
1. /home/joe/checkpoints/test/image.craff
2. [project]/targets/qsp-x86/test/image.craff
If the filename contains a checkpoint path marker (%n%), the marker is translated using Simics's checkpoint path and the file is looked up in the corresponding path.

Windows example;
If Simics's checkpoint path contains
C:\checkpoints\c1;C:\checkpoints\c2, the file %1%/image.craff will be translated into C:\checkpoints\c2\image.craff.
Linux example;
If Simics's checkpoint path contains /home/joe/c1:/home/joe/c2, the file %1%/image.craff will be translated into /home/joe/c2/image.craff.
If the filename contains an absolute path the file path is used as is.
Windows example;
C:\checkpoints\image.craff
Linux example;
/home/joe/image.craff

Note: The reason why Simics's search path is involved in the process is that it makes writing new configurations easier. Adding a path to the place where all initial images are located allows you to just specify the image names.

6.2.4 Saving and Restoring Persistent Data

As an alternative to checkpointing, Simics allows you to only save the persistent state of a machine, i.e., data that survive when the machine is powered-down. This typically consists of disk images and flash memory or NVRAM contents. A persistent data checkpoint is handled exactly like any other checkpoint and contains the same file set, but only objects containing persistent data are saved. This persistent data checkpoint can be loaded on top of a corresponding configuration later on.

The commands save-persistent-state and load-persistent-state respectively save and load the persistent data in a configuration.

Note: These commands are often used to save the state and reboot a machine after the disk contents have been modified. Remember that the target OS might have cached disk contents in memory. In order to have a clean disk that can be used at boot, you should synchronize the disk, for example by running init 0 on a Linux target system, or shutting down the operating system, before you issue the save-persistent-state command.

Another option is to use the command enable-writable-persistent-state. It saves a persistent state and also switches all saved files to be writable, so that the images are used in read-write mode, as described in section 6.2.3. All changes to the images done during the simulation are then automatically written to these files, without the need to explicitly save the state.

This command can also load a state which already exists, created by this command. It is meant to be used in a Simics script and facilitates easy handling of the persistent states, either creating a new state or loading an existing state.

The states created by enable-writable-persistent-state can be loaded using load-persistent-state, if read-write mode is no longer desired. States created by save-persistent-state are generally not usable by enable-writable-persistent-state, since it may not be possible to make them writable.

6.2.5 Modifying Checkpoints

Checkpoints are usually created by saving a configuration inside Simics, but it is possible to edit or even create checkpoints yourself. It may even be required to edit file paths in a checkpoint file if it is relocated.

Because a minimal checkpoint only has to include required attributes, creating a checkpoint from scratch works relatively well for small configurations. We suggest you use an existing checkpoint as a starting point if you wish to do that. Note that more advanced layers have been built on top of the configuration system to make the creation of a new machine much easier. Refer to section 6.6 for more information.

Modifying checkpoints require some extra care. Adding or removing devices may confuse the operating system, which does not expect devices to appear or disappear while the system is running, and cause it to crash.

Changing the processor frequency may be enough to confuse the operating system. Many operating systems check the CPU frequency at boot time, and base their waiting loops and timing on the value they got. Saving a checkpoint and changing the frequency after boot may affect the simulation and confuse the system. Devices that use processor frequency to trigger events at specific times may also behave strangely when the frequency suddenly changes.

6.2.6 Merging Checkpoints

If you want to make an incremental checkpoint independent from all previous checkpoints, for example to distribute it, you can use the small checkpoint-merge program in [simics]\bin from your system command line. It merges the checkpoint with all its ancestors to create a checkpoint that has no dependencies. Specify the checkpoint you want to distribute as the first parameter and the name of the new stand-alone checkpoint as the second. This tool can be used in both Linux and Windows environments.

Note that the merged checkpoint still depends on the base image. This differs from independent checkpoints, which are completely standalone.

6.1 Basics 6.3 Inspecting the Configuration