Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

SSM - The Saved State Manager

The Saved State Manager (SSM) implements facilities for saving and loading a VM state in a structural manner using callbacks for named data units.

At init time each of the VMM components, Devices, Drivers and one or two other things will register data units which they need to save and restore. Each unit have a unique name (ascii), instance number, and a set of callbacks associated with it. The name will be used to identify the unit during restore. The callbacks are for the two operations, save and restore. There are three callbacks for each of the two - a prepare, a execute and a complete

The SSM provides a number of APIs for encoding and decoding the data:

See also:
The Saved State Manager API

Live Snapshots

The live snapshots feature (LS) is similar to teleportation (TP) and was a natural first step when implementing TP. The main differences between LS and TP are that after a live snapshot we will have a saved state file, disk image snapshots, and the VM will still be running.

Compared to normal saved stated and snapshots, the difference is in that the VM is running while we do most of the saving. Prior to LS, there was only one round of callbacks during saving and the VM was paused during it. With LS there are 1 or more passes while the VM is still running and a final one after it has been paused. The runtime passes are executed on a dedicated thread running at at the same priority as the EMTs so that the saving doesn't starve or lose in scheduling questions (note: not implemented yet). The final pass is done on EMT(0).

There are a couple of common reasons why LS and TP will fail:

The live saving sequence is something like this:

  1. SSMR3LiveSave is called on EMT0. It returns a saved state handle.
  2. SSMR3LiveDoStep1 is called on a non-EMT. This will save the major parts of the state while the VM may still be running.
  3. The VM is suspended.
  4. SSMR3LiveDoStep2 is called on EMT0 to save the remainder of the state in the normal way.
  5. The client does any necessary reconfiguration of harddisks and similar.
  6. SSMR3LiveDone is called on EMT0 to close the handle.
  7. The VM is resumed or powered off and destroyed.


As mentioned in the previous section, the main differences between this and live snapshots are in where the saved state is written and what state the local VM is in afterwards - at least from the VMM point of view. The necessary administrative work - establishing the connection to the remote machine, cloning the VM config on it and doing lowlevel saved state data transfer - is taken care of by layer above the VMM (i.e. Main).

The SSM data format was made streamable for the purpose of teleportation (v1.2 was the last non-streamable version).

Saved State Format

The stream format starts with a header (SSMFILEHDR) that indicates the version and such things, it is followed by zero or more saved state units (name + instance + pass), and the stream concludes with a footer (SSMFILEFTR) that contains unit counts and optionally a checksum for the entire file. (In version 1.2 and earlier, the checksum was in the header and there was no footer. This meant that the header was updated after the entire file was written.)

The saved state units each starts with a variable sized header (SSMFILEUNITHDRV2) that contains the name, instance and pass. The data follows the header and is encoded as records with a 2-8 byte record header indicating the type, flags and size. The first byte in the record header indicates the type and flags:

Record header byte 2 (optionally thru 7) is the size of the following data encoded in UTF-8 style. To make buffering simpler and more efficient during the save operation, the strict checks enforcing optimal encoding has been relaxed for the 2 and 3 byte encodings.

(In version 1.2 and earlier the unit data was compressed and not record based. The unit header contained the compressed size of the data, i.e. it needed updating after the data was written.)

Future Changes

There are plans to extend SSM to make it easier to be both backwards and (somewhat) forwards compatible. One of the new features will be being able to classify units and data items as unimportant (added to the format in v2.0). Another suggested feature is naming data items (also added to the format in v2.0), perhaps by extending the SSMR3PutStruct API. Both features will require API changes, the naming may possibly require both buffering of the stream as well as some helper managing them.

Generated by  Doxygen 1.6.0   Back to index