Previous - Up - Next

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 on the command-line with the write-configuration and read-configuration commands.

A checkpoint consists of the following files:

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 AM79C960 class (a 10Mbits ISA Ethernet card with on-board DMA) named lance0. The irq_dev and the irq_level attributes connect the device to a controller that will handle the interrupts it generates. Since this device has on-board DMA, it is also connected to memory with the memory attribute.

OBJECT lance0 TYPE AM79C960 {
        mac_address: "10:10:10:10:10:30"
        irq_dev: isa0
        irq_level: 7
        memory: pci_mem0
OBJECT ... TYPE ... {

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

6.2.1   Attributes

The short example of the lance0 description only uses three types of attribute values: strings, objects, and (signed 64-bit) integers. The possible attribute types are:

Strings are enclosed in double quotes, with C-style control characters: "a string\n"
Integers can be in hexadecimal (0xfce2) or signed decimal (-17) notation.
One of TRUE or FALSE.
Specified in decimal (1.0e-2) or hexadecimal (0x5.a21p-32) style, just like in C.
The name of a configuration object: cpu0.
raw data
Arbitrary data; typically used to save large dumps of binary information. The data itself is stored in the raw data file. The syntax is [R length-in-bytes filename file-offset].
Comma-separated list of any attribute values, enclosed in parentheses. Example: ("a string", 4711, (1, 2, 3), cpu0)
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 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.
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.
Session attributes are only valid during a Simics session. They are not saved in checkpoints. They are usually used for statistics gathering or values that can be computed from the rest of the object state.
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.

There are two special cases in the attribute checkpointing process. The first one, described above, concerns raw data. Raw data is saved in a separate file that belongs to the checkpoint file set. The main configuration file only contains a pointer to the corresponding data in the raw data file.

The second one concerns images.

6.2.2   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 save their entire state every time a checkpoint is written. They can work in two ways:

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.

To re-use the example above, let us have a look at the disk image of the same x86 computer:

OBJECT disk0_image TYPE image {
        files: (("enterprise3-rh73.craff", "ro", 0, 0x4c5abc000, 0),
                ("checkpoint-1.disk0_image", "ro", 0, 0x4c5abc000, 0))
        size: 0x4c5abc000

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

Files like checkpoint-1.disk0_image 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 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. Images filenames 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 15.4), although both will be used when looking for image files, as show below.

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

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.3   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 Unix target system, or shutting down the operating system, before you issue the save-persistent-state command.

6.2.4   Modifying Checkpoints

Checkpoints are usually created by saving a configuration inside Simics, but it is possible to edit or even create checkpoints yourself.

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.5 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.5   Merging Checkpoints

If you want to make a 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 Unix and Windows environments, but it can not handle Cygwin paths on Windows.

Previous - Up - Next