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.
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:
Each attribute belongs to one of the following categories. Note that only attributes of the first two categories are saved in checkpoints.
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.
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.
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.
To summarize, when loading a checkpoint or a new configuration, Simics looks for images in the following way:
For example, if Simics's search path contains [workspace]/targets/sunfire/ and the checkpoint is located in /home/joe/checkpoints/, Simics will look for the file test/image.craff in the following places:
For 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.
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.
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.
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.