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(prefix = "ERROR_", value = {
39         ERROR_UNKNOWN,
40         ERROR_PAYLOAD_VERIFICATION_FAILED,
41         ERROR_PAYLOAD_CHANGED,
42         ERROR_PAYLOAD_INVALID_CONFIG
43     })
44     @interface ErrorCode {}
45 
46     /** Error code for all other errors not listed below. */
47     int ERROR_UNKNOWN = 0;
48     /**
49      * Error code indicating that the payload can't be verified due to various reasons (e.g invalid
50      * merkle tree, invalid formats, etc).
51      */
52     int ERROR_PAYLOAD_VERIFICATION_FAILED = 1;
53     /** Error code indicating that the payload is verified, but has changed since the last boot. */
54     int ERROR_PAYLOAD_CHANGED = 2;
55     /** Error code indicating that the payload config is invalid. */
56     int ERROR_PAYLOAD_INVALID_CONFIG = 3;
57 
58     /** @hide */
59     @Retention(RetentionPolicy.SOURCE)
60     @IntDef(
61             prefix = "STOP_REASON_",
62             value = {
63                 STOP_REASON_VIRTUALIZATION_SERVICE_DIED,
64                 STOP_REASON_INFRASTRUCTURE_ERROR,
65                 STOP_REASON_KILLED,
66                 STOP_REASON_UNKNOWN,
67                 STOP_REASON_SHUTDOWN,
68                 STOP_REASON_START_FAILED,
69                 STOP_REASON_REBOOT,
70                 STOP_REASON_CRASH,
71                 STOP_REASON_PVM_FIRMWARE_PUBLIC_KEY_MISMATCH,
72                 STOP_REASON_PVM_FIRMWARE_INSTANCE_IMAGE_CHANGED,
73                 STOP_REASON_BOOTLOADER_PUBLIC_KEY_MISMATCH,
74                 STOP_REASON_BOOTLOADER_INSTANCE_IMAGE_CHANGED,
75                 STOP_REASON_MICRODROID_FAILED_TO_CONNECT_TO_VIRTUALIZATION_SERVICE,
76                 STOP_REASON_MICRODROID_PAYLOAD_HAS_CHANGED,
77                 STOP_REASON_MICRODROID_PAYLOAD_VERIFICATION_FAILED,
78                 STOP_REASON_MICRODROID_INVALID_PAYLOAD_CONFIG,
79                 STOP_REASON_MICRODROID_UNKNOWN_RUNTIME_ERROR,
80                 STOP_REASON_HANGUP,
81             })
82     @interface StopReason {}
83 
84     /** The virtualization service itself died, taking the VM down with it. */
85     //  This is a negative number to avoid conflicting with the other death reasons which match
86     //  the ones in the AIDL interface.
87     int STOP_REASON_VIRTUALIZATION_SERVICE_DIED = -1;
88 
89     /** There was an error waiting for the VM. */
90     int STOP_REASON_INFRASTRUCTURE_ERROR = 0;
91 
92     /** The VM was killed. */
93     int STOP_REASON_KILLED = 1;
94 
95     /** The VM died for an unknown reason. */
96     int STOP_REASON_UNKNOWN = 2;
97 
98     /** The VM requested to shut down. */
99     int STOP_REASON_SHUTDOWN = 3;
100 
101     /** crosvm had an error starting the VM. */
102     int STOP_REASON_START_FAILED = 4;
103 
104     /** The VM requested to reboot, possibly as the result of a kernel panic. */
105     int STOP_REASON_REBOOT = 5;
106 
107     /** The VM or crosvm crashed. */
108     int STOP_REASON_CRASH = 6;
109 
110     /** The pVM firmware failed to verify the VM because the public key doesn't match. */
111     int STOP_REASON_PVM_FIRMWARE_PUBLIC_KEY_MISMATCH = 7;
112 
113     /** The pVM firmware failed to verify the VM because the instance image changed. */
114     int STOP_REASON_PVM_FIRMWARE_INSTANCE_IMAGE_CHANGED = 8;
115 
116     /** The bootloader failed to verify the VM because the public key doesn't match. */
117     int STOP_REASON_BOOTLOADER_PUBLIC_KEY_MISMATCH = 9;
118 
119     /** The bootloader failed to verify the VM because the instance image changed. */
120     int STOP_REASON_BOOTLOADER_INSTANCE_IMAGE_CHANGED = 10;
121 
122     /** The microdroid failed to connect to VirtualizationService's RPC server. */
123     int STOP_REASON_MICRODROID_FAILED_TO_CONNECT_TO_VIRTUALIZATION_SERVICE = 11;
124 
125     /** The payload for microdroid is changed. */
126     int STOP_REASON_MICRODROID_PAYLOAD_HAS_CHANGED = 12;
127 
128     /** The microdroid failed to verify given payload APK. */
129     int STOP_REASON_MICRODROID_PAYLOAD_VERIFICATION_FAILED = 13;
130 
131     /** The VM config for microdroid is invalid (e.g. missing tasks). */
132     int STOP_REASON_MICRODROID_INVALID_PAYLOAD_CONFIG = 14;
133 
134     /** There was a runtime error while running microdroid manager. */
135     int STOP_REASON_MICRODROID_UNKNOWN_RUNTIME_ERROR = 15;
136 
137     /** The VM killed due to hangup */
138     int STOP_REASON_HANGUP = 16;
139 
140     /** Called when the payload starts in the VM. */
onPayloadStarted(@onNull VirtualMachine vm)141     void onPayloadStarted(@NonNull VirtualMachine vm);
142 
143     /**
144      * Called when the payload in the VM is ready to serve. See {@link
145      * VirtualMachine#connectToVsockServer}.
146      */
onPayloadReady(@onNull VirtualMachine vm)147     void onPayloadReady(@NonNull VirtualMachine vm);
148 
149     /** Called when the payload has finished in the VM. */
onPayloadFinished(@onNull VirtualMachine vm, int exitCode)150     void onPayloadFinished(@NonNull VirtualMachine vm, int exitCode);
151 
152     /** Called when an error occurs in the VM. */
onError(@onNull VirtualMachine vm, @ErrorCode int errorCode, @NonNull String message)153     void onError(@NonNull VirtualMachine vm, @ErrorCode int errorCode, @NonNull String message);
154 
155     /** Called when the VM has stopped. */
onStopped(@onNull VirtualMachine vm, @StopReason int reason)156     void onStopped(@NonNull VirtualMachine vm, @StopReason int reason);
157 }
158