blob: 1576a1ee97e1a52e14f34710e6358ce901879fc7 [file] [log] [blame]
// Copyright (C) 2018 The Android Open Source Project
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// Note that if you add/remove methods in this file you must update
// the metrics sql as well by running ./android/scripts/
// Please group deleted methods in a block including the date (MM/DD/YY)
// it was removed. This enables us to easily keep metrics around after removal
// List of deleted methods
// rpc iWasDeleted (03/12/12)
// ...
syntax = "proto3";
package android.emulation.control;
import "google/protobuf/empty.proto";
import "snapshot.proto";
option java_multiple_files = true;
option java_package = "";
option objc_class_prefix = "AEC";
// The SnapshotService enables you to list, insert, store, and retrieve
// snapshots.
// Currently there are two types of snapshots:
// - Local (default): These are snapshots that are created locally. They are
// stored internally inside qcow2 files and are very efficient. These are
// the snapshots usually created by interacting with the UI.
// - Remote: These are snapshots that have been exported at a certain point.
// an exported snapshot is normalized (completely self contained) and
// can be imported into an emulator with a similar hardware configuration.
// Currently the emulator has limited support for importing snapshots:
// - Once an imported snapshot has been loaded into an emulator it is no longer
// possible to create new snapshots.
// - The hardware configuration of the emulator your are pushing a snapshot to
// must match (or be very similar) to the one you pulled the snapshot from.
// For example do not expect to be able to restore a snapshot on created on an
// Intel cpu on an AMD cpu.
service SnapshotService {
// Lists all the valid snapshots that are stored locally for the currently
// running avd. This includes all the snapshots that were imported (pushed)
// into this emulator.
// Returns a list of snapshot_id's and associated details that describes
// the hardware configuration, logical name, etc of the snapshot.
rpc ListSnapshots(google.protobuf.Empty) returns (SnapshotList) {}
// Pulls down the snapshot stored inside the AVD as a tar.gz/tar stream
// This will normalize the snapshot, all relevant data to push a snapshot
// into a similar emulator will be placed inside the tar file.
// Pulling down a snapshot will pause the emulator until the snapshots
// are rebased and ready for exporting. Once the snapshot is rebased
// the emulator will continue and downloading should commence.
// Note that pulling .gz stream is slow.
// You must provide the snapshot_id and (desired) format.
rpc PullSnapshot(SnapshotPackage) returns (stream SnapshotPackage) {}
// Push a tar.gz stream contain the snapshot. The tar file should
// be a snapshot that was exported through the PullSnapshot in the past.
// The emulator will try to import the snapshot. The hardware configuration
// of the current emulator should match the one used for pulling.
// A detailed description of the snapshot (emulator_snapshot.Snapshot)
// is stored in the snapshot.pb file inside the tar.
// You must provide the snapshot_id and format in the first message.
// Will return success and a possible error message when a failure occurs.
rpc PushSnapshot(stream SnapshotPackage) returns (SnapshotPackage) {}
// Loads the given snapshot inside the emulator and activates it.
// The device will be in the state as it was when the snapshot was created.
// You will no longer be able to call Save if this was an imported
// snapshot that was pushed into this emulator.
// You must provide the snapshot_id to indicate which snapshot to load
// Will return success and a possible error message when a failure occurs.
rpc LoadSnapshot(SnapshotPackage) returns (SnapshotPackage) {}
// Creates as a snapshot of the current state of the emulator.
// You can only save a snapshot if you never activated (Load) an imported
// snapshot (Push).
// For example:
// - PushSnapshot("some_snap.tar.gz");
// - LoadSnapshot("some_snap");
// - SaveSnapshot("same_newer_snap"); // <--- Will currently fail.
// You can provide the snapshot_id to indicate the name used for storing.
// Will return success and a possible error message when a failure occurs.
rpc SaveSnapshot(SnapshotPackage) returns (SnapshotPackage) {}
// Deletes the snapshot with the given snapshot_id from the avd.
// You must provide the snapshot_id to indicate which snapshot to delete.
// Will return success and a possible error message when a failure occurs.
rpc DeleteSnapshot(SnapshotPackage) returns (SnapshotPackage) {}
// Tracks the given process for automated snapshot creation in case of
// assert failures.
// Will return success and a possible error message when a failure occurs.
// The snapshot_id field will contain the name of the snapshot that
// will be created. The pid field will contain the process id that is
// being tracked.
rpc TrackProcess(IceboxTarget) returns (IceboxTarget) {}
message SnapshotPackage {
enum Format {
TARGZ = 0;
TAR = 1;
// The identifier to the snapshot, only required for the first message.
string snapshot_id = 1;
// A stream of bytes. Encoded as a tar (possibly gzipped) file pendinf on the
// value of format.
bytes payload = 2;
// [Output only] status fields, usually indicates end of transmission.
bool success = 3;
bytes err = 4;
// Format of the payload. Only required for the first message.
Format format = 5;
message SnapshotDetails {
// The id of this snapshot. Use this id to load/delete/pull the
// snapshot.
string snapshot_id = 1;
// Detailed information about this snapshot. This contains a detailed
// hardware description of the snapshot. These details are the same
// as the "snapshot.pb" file found in an exported snapshot.
// Look at the import file for a detailed description of the available
// fields.
emulator_snapshot.Snapshot details = 2;
// A List of on snapshot details.
message SnapshotList { repeated SnapshotDetails snapshots = 1; }
message IceboxTarget {
// This is the process id to attach to, if this value is not set (0)
// The process name will be used instead.
int64 pid = 1;
// The process name to attach to if any, if this is not set the pid will
// be used. This is usually the application name of your application under
// test, that is passed in to the am instrument command. It is likely
// what you will find in your AndroidManifest.xml
string package_name = 2;
// The name of the snapshot that icebox will create if a snapshot is
// generated.
string snapshot_id = 3;
// [Output Only] True if icebox failed to track the given target.
bool failed = 4;
// [Output Only] Detailed error message that might provide more information.
string err = 5;
// List of deleted methods: