image

Description

The image class provides persistent file-backed flat-address storage of devices such as physical memory and disks. Writes are fully shadowed, which allows changes to be stored in a compact way and the original images be kept unchanged. Memory page allocation is done lazily.

In an image object, one or more files represent the image data. This is done in a transparent way: page ranges not present in one file is searched in subsequent files.

Image files can be in raw format, compressed craff format, read-only DMG format, or VHDX format (fixed virtual hard disks and dynamic virtual hard disks are supported). The craff utility that is shipped with Simics simulator can be used to manipulate image files, for example, to convert image files from and into the craff format.

Interfaces Implemented

conf_object, log_object, image, checkpoint, linear_image, page_bank

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for this class

add-diff-file – add a diff file to the image
add-partial-diff-file – add a partial diff file to the image
clear-files – clear the list of files for an image
info – print information about the object
list-files – list files representing the contents of an image
status – print status of the object

Commands for interface image

get – get bytes from image
load-file – load file into an image
load-intel-hex – load Intel HEX file into an image
load-intel-obj – load Intel .obj or .32.obj file into an image
load-vmem – load Verilog VMEM file into memory
print-image-memory-stats – image memory usage statistics
save – save image to disk
save-diff-file – save changes since last checkpoint
save-file – save memory contents to a binary file
save-intel-32-obj – save memory contents to an Intel .32.obj file
save-intel-hex – save memory contents to an Intel HEX file
save-intel-obj – save memory contents to an Intel .obj file
save-vmem – save VMEM file of memory
set – set bytes in image to specified value
x – examine image data

Attributes

image_snoop_devices: Optional attribute; read/write access; type: [o*]
Objects implementing the image_snoop. Installed objects will be called through the interface when image data is modified.
size: Required attribute; read/write access; type: i
Logical image size in bytes.
files: Optional attribute; read/write access; type: [[saii]|[saiii]|[saiiii]*]
((file, is-writable, start, size[, offset])+) Specifies the files that represent the (initial) image contents. Several files may be specified and may also overlap in memory. Later files override earlier files. file is the file name of a file in craff, DMG, VHDX, or raw format, or a raw disk device (typically, /dev/sd* on Linux and \\.\PhysicalDriveN on Windows; administrative privileges may be required for access). is-writable is "rw" or "ro" and specifies whether changes made to an image should be written back to the file or cached in memory. start is the first address in the image represented by the file. size is the number of bytes the file represents. If zero, the size is taken from the file. offset is the offset in the file where this mapping starts.
In checkpoint files generated by Simics, file may contain a path of the form %n%. Such a sequence will be replaced by the nth element of the checkpoint_path attribute in the sim object, counting from zero. By using %n% as path, all absolute paths are kept in the checkpoint_path attribute, making it easier to update a checkpoint when files that it depends on have moved.
Only the last file in the list may have is-writable set to "rw". That file will be updated in place with any changes done to the image. If no file is in "rw" mode, changes done to the image are stored as dirty pages. These changes can be saved as a diff-file or to a new checkpoint.
linear: Optional attribute; read/write access; type: i|b
Set if the memory should be preallocated, resident and contiguous. This can only be set before the object is instantiated.
byte_access: Pseudo attribute; read/write access; type: d
Read/write access to single bytes. The attribute is indexed by an integer specifying offset, or by a slice (pair of integers) specifying range.
dirty: Pseudo attribute; read-only access; type: b
Whether there are unsaved changes not backed by any writable file.
init_pattern: Optional attribute; read/write access; type: i
Contents of uninitialized bytes (default zero). Must be a single byte.
cache_reads: Optional attribute; read/write access; type: b
If TRUE, always cache data being read in memory. This improves performance when repeatedly accessing the same or nearby data, at the cost of increased memory consumption. The default is FALSE.
persistent: Pseudo attribute; read-only access; type: b
Whether the image data is persistent.

Class Attributes

memory_limit: Pseudo attribute; read/write access; type: i
Maximum number of bytes cached by all images in the system before pages are swapped to disk. This is used to reduce memory consumption. Setting this limit too high or too low will adversely affect system performance. If set to 0, the limit is disabled.
memory_usage: Pseudo attribute; read-only access; type: i
Total memory usage of image pages.

Provided By

Simics Core