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:

Using the save-persistent-state command, all image changes for
persistent storage media are saved to disk as a persistent state. This is
the recommended way of saving your image changes.

Using the <image>.save-diff-file command, you can manually
save a diff file for the images you are interested in.

Using the <image>.save command, you can create a raw
binary dump of the image that is completely independent of all previous images
and diff files. Note that this is not the best way to get a new and
shiny image, since the image is saved uncompressed, which can take a lot of
time and disk space.

Note: The <image>.save actually allows you to save a
partial dump of an image, which may be useful to dump a specific part
of a disk or a floppy.

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

If you used save-persistent-state, you can issue the
load-persistent-state command just after starting the original
configuration. This will add the new changes to the persistent storage media
images and the machine will boot with the changes included. This is the
recommended way of using a saved persistent state.

For example, let us suppose that you saved some new files on the disk of the
enterprise machine (started with the
enterprise-common.simics script). You saved the persistent state
of the machine after stopping it to the persistent state file
new-files-added. You can easily create a small script to start
enterprise with the new files:

You can also load the original configuration and add the diff files
manually to the images, using the <image>.add-diff-file
command.

If you are building your own configurations (either as scripts or as
checkpoints), you can add the diff files to the files attribute of
the corresponding image object. This corresponds to what the
<image>.add-diff-file command does.

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:

If you are working with persistent states, you can use the
checkpoint-merge utility to create a persistent state that is
independent of all previous files, including the original images provided by
Virtutech. This is the recommended way of creating a new independent
image. You can load it as usual with the load-persistent-state
command.

If you saved some image diff files manually, you can use the
craff utility described below to merge the diff files
yourself.

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:

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
(http://mtools.linux.lu) 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.

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:

cd
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.

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.