1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.system.virtualmachine; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.SuppressLint; 22 import android.annotation.SystemApi; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 27 /** 28 * Callback interface to get notified with the events from the virtual machine. The methods are 29 * executed on a binder thread. Implementations can make blocking calls in the methods. 30 * 31 * @hide 32 */ 33 @SystemApi 34 @SuppressLint("CallbackInterface") // Guidance has changed, lint is out of date (b/245552641) 35 public interface VirtualMachineCallback { 36 /** @hide */ 37 @Retention(RetentionPolicy.SOURCE) 38 @IntDef( 39 prefix = "ERROR_", 40 value = { 41 ERROR_UNKNOWN, 42 ERROR_PAYLOAD_VERIFICATION_FAILED, 43 ERROR_PAYLOAD_CHANGED, 44 ERROR_PAYLOAD_INVALID_CONFIG 45 }) 46 @interface ErrorCode {} 47 48 /** Error code for all other errors not listed below. */ 49 int ERROR_UNKNOWN = 0; 50 51 /** 52 * Error code indicating that the payload can't be verified due to various reasons (e.g invalid 53 * merkle tree, invalid formats, etc). 54 */ 55 int ERROR_PAYLOAD_VERIFICATION_FAILED = 1; 56 57 /** Error code indicating that the payload is verified, but has changed since the last boot. */ 58 int ERROR_PAYLOAD_CHANGED = 2; 59 60 /** Error code indicating that the payload config is invalid. */ 61 int ERROR_PAYLOAD_INVALID_CONFIG = 3; 62 63 /** @hide */ 64 @Retention(RetentionPolicy.SOURCE) 65 @IntDef( 66 prefix = "STOP_REASON_", 67 value = { 68 STOP_REASON_VIRTUALIZATION_SERVICE_DIED, 69 STOP_REASON_INFRASTRUCTURE_ERROR, 70 STOP_REASON_KILLED, 71 STOP_REASON_UNKNOWN, 72 STOP_REASON_SHUTDOWN, 73 STOP_REASON_START_FAILED, 74 STOP_REASON_REBOOT, 75 STOP_REASON_CRASH, 76 STOP_REASON_PVM_FIRMWARE_PUBLIC_KEY_MISMATCH, 77 STOP_REASON_PVM_FIRMWARE_INSTANCE_IMAGE_CHANGED, 78 STOP_REASON_BOOTLOADER_PUBLIC_KEY_MISMATCH, 79 STOP_REASON_BOOTLOADER_INSTANCE_IMAGE_CHANGED, 80 STOP_REASON_MICRODROID_FAILED_TO_CONNECT_TO_VIRTUALIZATION_SERVICE, 81 STOP_REASON_MICRODROID_PAYLOAD_HAS_CHANGED, 82 STOP_REASON_MICRODROID_PAYLOAD_VERIFICATION_FAILED, 83 STOP_REASON_MICRODROID_INVALID_PAYLOAD_CONFIG, 84 STOP_REASON_MICRODROID_UNKNOWN_RUNTIME_ERROR, 85 STOP_REASON_HANGUP, 86 }) 87 @interface StopReason {} 88 89 /** The virtualization service itself died, taking the VM down with it. */ 90 // This is a negative number to avoid conflicting with the other death reasons which match 91 // the ones in the AIDL interface. 92 int STOP_REASON_VIRTUALIZATION_SERVICE_DIED = -1; 93 94 /** There was an error waiting for the VM. */ 95 int STOP_REASON_INFRASTRUCTURE_ERROR = 0; 96 97 /** The VM was killed. */ 98 int STOP_REASON_KILLED = 1; 99 100 /** The VM died for an unknown reason. */ 101 int STOP_REASON_UNKNOWN = 2; 102 103 /** The VM requested to shut down. */ 104 int STOP_REASON_SHUTDOWN = 3; 105 106 /** crosvm had an error starting the VM. */ 107 int STOP_REASON_START_FAILED = 4; 108 109 /** The VM requested to reboot, possibly as the result of a kernel panic. */ 110 int STOP_REASON_REBOOT = 5; 111 112 /** The VM or crosvm crashed. */ 113 int STOP_REASON_CRASH = 6; 114 115 /** The pVM firmware failed to verify the VM because the public key doesn't match. */ 116 int STOP_REASON_PVM_FIRMWARE_PUBLIC_KEY_MISMATCH = 7; 117 118 /** The pVM firmware failed to verify the VM because the instance image changed. */ 119 int STOP_REASON_PVM_FIRMWARE_INSTANCE_IMAGE_CHANGED = 8; 120 121 /** The bootloader failed to verify the VM because the public key doesn't match. */ 122 int STOP_REASON_BOOTLOADER_PUBLIC_KEY_MISMATCH = 9; 123 124 /** The bootloader failed to verify the VM because the instance image changed. */ 125 int STOP_REASON_BOOTLOADER_INSTANCE_IMAGE_CHANGED = 10; 126 127 /** The microdroid failed to connect to VirtualizationService's RPC server. */ 128 int STOP_REASON_MICRODROID_FAILED_TO_CONNECT_TO_VIRTUALIZATION_SERVICE = 11; 129 130 /** The payload for microdroid is changed. */ 131 int STOP_REASON_MICRODROID_PAYLOAD_HAS_CHANGED = 12; 132 133 /** The microdroid failed to verify given payload APK. */ 134 int STOP_REASON_MICRODROID_PAYLOAD_VERIFICATION_FAILED = 13; 135 136 /** The VM config for microdroid is invalid (e.g. missing tasks). */ 137 int STOP_REASON_MICRODROID_INVALID_PAYLOAD_CONFIG = 14; 138 139 /** There was a runtime error while running microdroid manager. */ 140 int STOP_REASON_MICRODROID_UNKNOWN_RUNTIME_ERROR = 15; 141 142 /** The VM killed due to hangup */ 143 int STOP_REASON_HANGUP = 16; 144 145 /** Called when the payload starts in the VM. */ onPayloadStarted(@onNull VirtualMachine vm)146 void onPayloadStarted(@NonNull VirtualMachine vm); 147 148 /** 149 * Called when the payload in the VM is ready to serve. See {@link 150 * VirtualMachine#connectToVsockServer}. 151 */ onPayloadReady(@onNull VirtualMachine vm)152 void onPayloadReady(@NonNull VirtualMachine vm); 153 154 /** Called when the payload has finished in the VM. */ onPayloadFinished(@onNull VirtualMachine vm, int exitCode)155 void onPayloadFinished(@NonNull VirtualMachine vm, int exitCode); 156 157 /** Called when an error occurs in the VM. */ onError(@onNull VirtualMachine vm, @ErrorCode int errorCode, @NonNull String message)158 void onError(@NonNull VirtualMachine vm, @ErrorCode int errorCode, @NonNull String message); 159 160 /** Called when the VM has stopped. */ onStopped(@onNull VirtualMachine vm, @StopReason int reason)161 void onStopped(@NonNull VirtualMachine vm, @StopReason int reason); 162 } 163