Cuttlefish: Snapshot and restore

Android 15 introduces how to take a snapshot and restore a snapshot of a Cuttlefish virtual device. Taking a snapshot of a Cuttlefish device lets you save the state of the device in an image on disk. You can then restore the snapshot to bring up a Cuttlefish device to the previously saved state.

You can use snapshots in various automated or manual workflows. When performing a procedure that modifies the device, you can take a snapshot of the device to ensure you can restore the device back to a specified state. For example, when running test suites that modify the state of the device and can potentially cause issues or instabilities in the following tests, you can take a snapshot so you can restore the device to a saved state after a test, ensuring that subsequent tests run cleanly.

Another example workflow where snapshots are useful is when testing the behavior of an app. When testing the behavior of an app based on a set of actions, you can take a snapshot in between actions as the app is running to let you restore to that snapshot without having to restart from the beginning. For example, if launching a game has a long bringup time, you can take a snapshot after reaching the main menu so you can restore the device to that state, skipping the bringup time.

Take snapshot of a Cuttlefish device

When taking a snapshot of a device, the Cuttlefish device must be suspended to make sure the Cuttlefish device is in a stable state. When the device is suspended, all vCPUs and devices are stopped, and all buffers push their state to the VM. The snapshot then saves the vCPU state, memory, and device state to disk at a specified destination folder.

VirtiosFS isn't supported and must be disabled when taking a snapshot. To disable VirtioFS, pass the argument --enable_virtiofs=false when running cvd create or cvd start.

Only the SwiftShader (guest_swiftshader) GPU mode is supported for snapshots. Other accelerated graphics modes aren't supported.

The following steps describes the process of launching a Cuttlefish device and taking a snapshot.

Launch a device, while disabling VirtioFS. (You can then use the device.)
```
cvd create --enable_virtiofs=false --gpu_mode=guest_swiftshader
```
Take a snapshot by running cvd snapshot_take with the following flags:
- --force: If a folder exists at the specified snapshot path, this flag ensures that the existing folder is deleted, and a new folder is created at the snapshot path containing the snapshot
- --auto_suspend: Suspends the device before the snapshot is taken and resumes the device after the snapshot is taken.
- --snapshot_path: The specified path where a new folder is created with the snapshot.
```
cvd snapshot_take --force --auto_suspend \
--snapshot_path=PATH
```

Restore a Cuttlefish device

When restoring a Cuttlefish device snapshot, the Cuttlefish instance for which the snapshot was taken must be stopped. If the instance is already stopped, no further action is required and the snapshot can be restored.

To restore a snapshot of a Cuttlefish device, launch a device with cvd create and include the snapshot path. If the base instance number of the Cuttlefish device on which the snapshot was taken is different from the base instance number of the current Cuttlefish instance, pass that base instance number using the --base_instance_num flag.

cvd create --snapshot_path=PATH \
--base_instance_num=ID

Suspend a Cuttlefish device

You can suspend a Cuttlefish device without taking a snapshot (no disk space is used for saving the state). To suspend a Cuttlefish device, run:

cvd suspend

Resume a Cuttlefish device

To resume a suspended Cuttlefish device, run:

cvd resume

Validate the Snapshot/Restore feature

The Snapshot/Restore feature can be validated by running the following test:

atest SnapshotTest