Previous - Up - Next

7.1   Working with Images

7.1.1   Saving Changes to an Image

If you modify or create new files on a storage device within Simics, you should remember that by default images are read-only. This means that the alterations made when running Simics are not written to the image, and will last only for the current Simics session. As described in the 6.2.2 section, this behavior has many advantages. You may however want to save your changes to the image to re-use them in future simulations.

The first thing you should do is to make sure that all the changes are actually written to the media you are using. In many cases, the simulated operating system caches operations to disks or floppies. A safe way to ensure that all changes are written back is to shutdown the simulated machine.

When all changes have been written to the media in the simulation, you can save the new contents of the image in different ways:

Once you have saved the images, you can do the following:

If you save several persistent states or image diff files that are dependent on each other, it may become cumbersome to take care of all these dependencies and to remember which files are important or not. You can merge the states or image diff files to create a new independent state:

7.1.2   Reducing Memory Usage Due to Images

Although images are divided into pages that are only loaded on request, Simics can run out of host memory if very big images are used, or if the footprint of the software running on the simulated system is bigger than the host memory. To prevent these kind of problems, Simics implements a global image memory limitation controlled by the set-memory-limit command.

When the memory limit is reached, Simics will start swapping out pages to disk very much like an operating system would do. The set-memory-limit command let you specify the maximum amount of memory that can be used, and where swapping should occur.

Note: This memory limitation only applies to images. Although this is unlikely, Simics can run out of memory due to other data structures becoming too large (for example memory profiling information) even though a memory limit has been set.

7.1.3   Using Read/Write Images

As mentioned in section 6.2.2, images can also work as read-write media, although this is not recommended. It can be useful sometimes when planning to make large changes to an image (like installing an operating system on a disk).

To make an image read-write in your own configurations, simply set the second parameter (the "read-only" flag) of the files attribute in the image object to "rw".

In a ready-to-run example like enterprise, you can change this attribute after the configuration is completed:

# read the 'files' attribute
simics> @files = conf.disk0_image.files
simics> @files
[['enterprise3-rh73.craff', 'ro', 0, 20496236544L, 0]]
# provide the complete path to the file
simics> @files[-1][0] = "[workspace]/targets/enterprise/images/
# change the second element to make the file read-write
simics> @files[-1][1] = "rw"
simics> @files
 'rw', 0, 20496236544L, 0]]
# set the 'files' attribute to its new value
simics> @conf.disk0_image.files = files

Note that by indexing files with the index -1, the last element of the array is accessed, which is always the one that should be set read-write, in case files is a list of several files.

As you can see in the example above, Simics by default does not look for files in the Simics search path when the files are used in read-write mode. If you do not provide a complete path to a read-write file, a new file will be created in the current directory.

Use this feature with caution. Make sure to take a copy of the original image before running Simics with the image in read-write mode. Remember to synchronize the storage device within the target OS before exiting Simics, for example by shutting down the simulated machine.

Note: You can not access directly the files attributes by doing
@conf.disk0_image.files[-1][0] = "rw"
because the files attribute is not an indexed attribute. In this case, Python will read the files attribute and change the element [-1][0] in the resulting list, but this list is then discarded and the change produces no effect. The Simics Programming Guide contains a longer discussion explaining the ambiguities introduced by indexed attributes and the [] location.

7.1.4   Editing Images Using Mtools

If you have an image that contains a FAT filesystem, you can use Mtools ( to get read-write access to the image. You must have a raw binary dump of the image for Mtools to work. This can be obtained using the craff utility (see section 7.1.7).

If your image is partitioned (a complete disk for example), you may need to give Mtools special parameters like an offset or a partition. Refer to the Mtools documentation for more information.

7.1.5   Editing Images Using Loopback Mounting

If the host OS supports loopback devices, like, e.g., Linux and Solaris, you can mount an image on your host machine and get direct read/write access to the files within the image. If you have root permissions this allows you to easily and quickly copy files.

Note: Remember that the image must be a raw binary dump. Disk dumps supplied by Virtutech are normally in craff format but you can use the craff utility to unpack the disk image to a raw image. The resulting images have the same size as the simulated disk, so you need to have sufficient free space on your host disk to contain the entire simulated disk image.

Note: Do not try to loopback mount an image over NFS. This does not work reliably on all operating systems (Linux, for example). Instead, move the image to a local disk and mount it from there.

On Solaris 8 or later:

lofiadm -a disk_dump /dev/lofi/1
mount /dev/lofi/1 mnt-point
umount mnt-point
lofiadm -d /dev/lofi/1

On Linux:

mount <disk_dump> mnt_pnt -o loop=/dev/loopn,offset=m


# mount /disk1/rh6.2-kde-ws /mnt/loop -o loop=/dev/loop0,offset=17063424
# cd /mnt/loop
# ls
bin   dev  home  lost+found  opt   root  tmp  var
boot  etc  lib   mnt         proc  sbin  usr

As shown in the example, the disk dump containing a Red Hat 6.2 KDE WS is mounted on the /mnt/loop directory. The file system mounted on / starts on the offset 17063424 on the disk. Linux autodetects the file system type when mounting (ext2 in this example). If you want to access another kind of file system, use the -t fs option to the mount command. Once the file system is mounted, you can copy files in and out of the disk image.

The offset can be calculated by examining the partition table with fdisk (from within Simics). Use mount to find the partition you want to edit or examine (e.g., /dev/hda2 is mounted on /usr which you want to modify). Next, run fdisk on the device handling this partition (such as fdisk /dev/hda). From within fdisk, change the display unit to sectors instead of cylinders with the u command and print the partition table with p. You will now see the start and end sectors of the partitions; you can get the offset by taking the start sector multiplied with the sector size (512).

When you have finished examining or modifying the disk, unmount it and touch the disk image. For example:

umount /mnt/loop
touch /disk1/rh6.2-kde-ws

The modification date of the disk image does not change when if you modify the disk via the loopback device. Thus, if you have run Simics on the disk image earlier, the OS might have cached disk pages from the now modified disk image in RAM. This would cause a new Simics session to still use the old disk pages instead of the newly modified pages. Touching the image file should ensure that the OS rereads each page.

7.1.6   Constructing a Disk from Multiple Files

In some cases, you may want to populate a simulated disk from multiple files covering different parts of the disk. For example, the partition table and boot sectors could be stored in a different disk image file than the main contents of the disk. If that is the case, you cannot use the <image>.add-diff-file command: you must set manually the disk image files attribute to put each image file at its appropriate location.

Assume you are simulating a PC and want to build a disk from a main file called hda1_partition.img and a master boot record image file called MBR.img. The main partition will start at offset 32256 of the disk, and the MBR (Master Boot Record) covers the first 512 bytes of the disk (typically, you would get the contents of these image files from the real disk as detailed in section 7.4). The following command in Simics's start-up script will build the disk from these two files.

create-std-ide-disk disk2 size = 2559836160
@image = get_component_object(conf.disk2, 'hd_image')
@image.files = [["hda1_partition.img", "ro", 32256, 1032151040, 0],
                ["MBR.img",            "ro",     0,        512, 0]]

Note that the two image files cover non-overlapping sections of the disk.

7.1.7   The Craff Utility

The images distributed by Virtutech, and in general most of the images created by Simics are in the craff file format. The craff utility can convert files to and from the craff format, and also merge several craff files into a single file.

In your Simics distribution you will find craff in [simics]/bin. The examples below assume that craff is present in your shell path.

Convert a raw dump to craff format
shell$ craff -o mydisk.craff mydisk.img
Convert a single craff file to a raw file
shell$ craff --decompress -o mydisk.img mydisk.craff
Merge multiple checkpoint files into a single craff file
If more than one input file is specified, they will be merged so that later files override earlier files on the command line.

shell$ craff -o merged.craff chkpt1.craff chkpt2.craff chkpt3.craff
Add a craff file to a raw dump, producing a new dump
shell$ craff --decompress -o new.img mydisk.img diff.craff

The input files can be any combination of raw and craff files.

Make a file of the differences of two dumps
shell$ craff --diff -o diff.craff dump1.img dump2.img

The resulting file, diff.craff, will contain only what is needed to add to dump1.img in order to get dump2.img. This is useful to save space if little has been changed.

See also the Simics Reference Manual for a full description of the craff utility and its parameters.

Previous - Up - Next