| // 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 |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // 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/gen-grpc-sql.py |
| // |
| // 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 = "com.android.emulator.control"; |
| 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 snapshots, filtered by the given query, 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(SnapshotFilter) 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. |
| // |
| // If SnapshotPackage.path is set, the gRPC service will directly write the |
| // exported snapshot to SnapshotPackage.path without streaming, which is |
| // usually significantly faster. It would require emulator to have direct |
| // access to SnapshotPackage.path, which usually means it can only be used |
| // when pulling from a local emulator. |
| 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. |
| // |
| // If SnapshotPackage.path is set, the gRPC service will directly unzip the |
| // exported snapshot from SnapshotPackage.path without streaming, which is |
| // usually significantly faster. It would require emulator to have direct |
| // access to SnapshotPackage.path, which usually means it can only be used |
| // when pushing to a local emulator. |
| 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) {} |
| } |
| |
| // Sets options for SnapshotService. Used for both request and response messages. |
| message SnapshotPackage { |
| enum Format { |
| TARGZ = 0; |
| TAR = 1; |
| } |
| // The identifier to the snapshot, only required for request messages. For |
| // streaming service, only used in the first stream message of a gRPC call |
| // (would be ignored in consequent stream messages of the same call). |
| string snapshot_id = 1; |
| |
| // A stream of bytes. Encoded as a tar (possibly gzipped) file pendinf on the |
| // value of format. |
| bytes payload = 2; |
| |
| // [response only] status fields, usually indicates end of transmission. |
| bool success = 3; |
| bytes err = 4; |
| |
| // [request only] Format of the payload. Only used in request messages. For |
| // streaming service, only used in the first stream message of a gRPC call |
| // (would be ignored in consequent stream messages of the same call). |
| Format format = 5; |
| |
| // [request only] Path to the snapshot package file. Only used in request |
| // messages. |
| // |
| // When set in a request, the PullSnapshot/PushSnapshot operation will directly |
| // write/read the exported snapshot in path without streaming, which is usually |
| // significantly faster. It would require emulator to have direct access to |
| // path, which usually means it can only be used with a local emulator. |
| string path = 6; |
| } |
| |
| // A snapshot filter can be used to filter the results produced by ListSnapshots |
| message SnapshotFilter { |
| enum LoadStatus { |
| // Only return compatible snapshots |
| CompatibleOnly = 0; |
| |
| // Return all snapshots. |
| All = 1; |
| } |
| |
| // Filter snapshots by load status. |
| LoadStatus statusFilter = 1; |
| } |
| |
| // Provides detailed information regarding the snapshot. |
| message SnapshotDetails { |
| |
| enum LoadStatus { |
| // The emulator believes that the snapshot is compatible with the emulator |
| // that provided this information. The emulator will attempt to load this |
| // snapshot when requested. |
| // |
| // A snapshot is usually compatible when the following statements are true: |
| // - The snapshot was taken by the current emulator version. i.e. |
| // emulator_build_id in the details field matches the build_id of the |
| // emulator that provided this information. |
| // |
| // - The snapshot was taken on the current running machine, and no hardware |
| // changes have taken place between taking and loading the snapshot. |
| // |
| // - The avd configuration has not changed between when this snapshot was |
| // taken and when the snapshot was loaded. |
| // |
| // - The system images on which the avd is based have not changed. |
| Compatible = 0; |
| |
| // The emulator will not allow loading of the snapshot, as it deems the |
| // snapshot to be incompatible. Loading of snapshots can be forced by |
| // launching the emulator with the feature "AllowSnapshotMigration" enabled. |
| Incompatible = 1; |
| |
| // This snapshot was successfully loaded in the emulator, and was used at |
| // the starting point of the current running emulator. The following holds: |
| // |
| // A loaded snapshot is a compatible snapshot |
| // There is at most one snapshot_id that is in the "Loaded" state |
| Loaded = 2; |
| } |
| |
| // 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; |
| |
| // Provides information about the ability to restore this snapshot. |
| LoadStatus status = 3; |
| |
| // The size of the folder that stores required information to load a snapshot. |
| uint64 size = 4; |
| } |
| |
| // 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; |
| |
| // Maximum number of snapshots the emulator can take during one Icebox run. |
| // Set to -1 for unlimited number of snapshots. |
| int32 max_snapshot_number = 6; |
| } |
| |
| // List of deleted methods: |
| // |