1 // Copyright 2015 The Android Open Source Project
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #pragma once
16 
17 #include "aemu/base/c_header.h"
18 
19 #include <stdbool.h>
20 #include <stdint.h>
21 #include <inttypes.h>
22 
23 // Caching types
24 #define MAP_CACHE_MASK      0x0f
25 #define MAP_CACHE_NONE      0x00
26 #define MAP_CACHE_CACHED    0x01
27 #define MAP_CACHE_UNCACHED  0x02
28 #define MAP_CACHE_WC        0x03
29 
30 ANDROID_BEGIN_HEADER
31 // This file includes interfaces to VMMs.
32 
33 // A struct describing the information about host memory associated
34 // with a host memory id. Used with virtio-gpu-next.
35 struct HostmemEntry {
36     uint64_t id;
37     void* hva;
38     uint64_t size;
39     uint32_t caching;
40 };
41 
42 // Called by hostmemRegister(..)
43 struct MemEntry {
44     void* hva;
45     uint64_t size;
46     uint32_t register_fixed;
47     uint64_t fixed_id;
48     uint32_t caching;
49 };
50 
51 // A callback to consume a single line of output (including newline).
52 // |opque| is a handle to a context object. Functions that use this callback
53 // will also take a context handle that will be passed to the callback.
54 // |buff| contains the data to be consumed, of length |len|.
55 // The function should return the number of chars consumed successfully.
56 typedef int (*LineConsumerCallback)(void* opaque, const char* buff, int len);
57 
58 // Enumeration of various causes for shutdown. Please keep this in sync
59 // with the similar enum in include/sysem/sysemu.h.
60 typedef enum QemuShutdownCause {
61     QEMU_SHUTDOWN_CAUSE_NONE,              /* No shutdown request pending */
62     QEMU_SHUTDOWN_CAUSE_HOST_ERROR,        /* An error prevents further use of guest */
63     QEMU_SHUTDOWN_CAUSE_HOST_QMP,          /* Reaction to a QMP command, like 'quit' */
64     QEMU_SHUTDOWN_CAUSE_HOST_SIGNAL,       /* Reaction to a signal, such as SIGINT */
65     QEMU_SHUTDOWN_CAUSE_HOST_UI,           /* Reaction to UI event, like window close */
66     QEMU_SHUTDOWN_CAUSE_GUEST_SHUTDOWN,    /* Guest shutdown/suspend request, via
67                                               ACPI or other hardware-specific means */
68     QEMU_SHUTDOWN_CAUSE_GUEST_RESET,       /* Guest reset request, and command line
69                                               turns that into a shutdown */
70     QEMU_SHUTDOWN_CAUSE_GUEST_PANIC,       /* Guest panicked, and command line turns
71                                               that into a shutdown */
72     QEMU_SHUTDOWN_CAUSE__MAX,
73 } QemuShutdownCause;
74 
75 #define SHUTDOWN_CAUSE_STATIC_ASSERT_ERROR_MESSAGE "QEMU shutdown cause values differ from AndroidEmu's!" \
76 
77 #define SHUTDOWN_CAUSE_STATIC_MATCH(origCause) \
78     static_assert((int)(QEMU_##origCause) == (int)(origCause), SHUTDOWN_CAUSE_STATIC_ASSERT_ERROR_MESSAGE);
79 
80 #define STATIC_ASSERT_SHUTDOWN_CAUSE_MATCHES \
81     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_NONE) \
82     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_HOST_ERROR) \
83     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_HOST_QMP) \
84     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_HOST_SIGNAL) \
85     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_HOST_UI) \
86     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_GUEST_SHUTDOWN) \
87     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_GUEST_RESET) \
88     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE_GUEST_PANIC) \
89     SHUTDOWN_CAUSE_STATIC_MATCH(SHUTDOWN_CAUSE__MAX) \
90 
91 typedef struct {
92     int (*onStart)(void* opaque, const char* name);
93     void (*onEnd)(void* opaque, const char* name, int res);
94     void (*onQuickFail)(void* opaque, const char* name, int res);
95     bool (*isCanceled)(void* opaque, const char* name);
96 } SnapshotCallbackSet;
97 
98 typedef enum {
99     SNAPSHOT_SAVE,
100     SNAPSHOT_LOAD,
101     SNAPSHOT_DEL,
102     SNAPSHOT_OPS_COUNT
103 } SnapshotOperation;
104 
105 struct SnapshotRamBlock;
106 
107 typedef struct {
108     void (*registerBlock)(void* opaque,
109                           SnapshotOperation operation,
110                           const struct SnapshotRamBlock* block);
111     int (*startLoading)(void* opaque);
112     void (*savePage)(void* opaque,
113                      int64_t blockOffset,
114                      int64_t pageOffset,
115                      int32_t size);
116     int (*savingComplete)(void* opaque);
117     void (*loadRam)(void* opaque,
118                     void* hostRamPtr,
119                     uint64_t size);
120 } SnapshotRamCallbacks;
121 
122 typedef struct {
123     SnapshotCallbackSet ops[SNAPSHOT_OPS_COUNT];
124     SnapshotRamCallbacks ramOps;
125 } SnapshotCallbacks;
126 
127 typedef enum {
128     HV_UNKNOWN,
129     HV_NONE,
130     HV_KVM,
131     HV_HAXM,
132     HV_HVF,
133     HV_WHPX,
134 } VmHypervisorType;
135 
136 typedef struct {
137     VmHypervisorType hypervisorType;
138     int32_t numberOfCpuCores;
139     int64_t ramSizeBytes;
140 } VmConfiguration;
141 
142 typedef enum EmuRunState {
143     QEMU_RUN_STATE_DEBUG = 0,
144     QEMU_RUN_STATE_INMIGRATE = 1,
145     QEMU_RUN_STATE_INTERNAL_ERROR = 2,
146     QEMU_RUN_STATE_IO_ERROR = 3,
147     QEMU_RUN_STATE_PAUSED = 4,
148     QEMU_RUN_STATE_POSTMIGRATE = 5,
149     QEMU_RUN_STATE_PRELAUNCH = 6,
150     QEMU_RUN_STATE_FINISH_MIGRATE = 7,
151     QEMU_RUN_STATE_RESTORE_VM = 8,
152     QEMU_RUN_STATE_RUNNING = 9,
153     QEMU_RUN_STATE_SAVE_VM = 10,
154     QEMU_RUN_STATE_SHUTDOWN = 11,
155     QEMU_RUN_STATE_SUSPENDED = 12,
156     QEMU_RUN_STATE_WATCHDOG = 13,
157     QEMU_RUN_STATE_GUEST_PANICKED = 14,
158     QEMU_RUN_STATE_COLO = 15,
159     QEMU_RUN_STATE__MAX = 16,
160 } EmuRunState;
161 
162 typedef enum SnapshotSkipReason {
163     SNAPSHOT_SKIP_UNKNOWN = 0,
164     SNAPSHOT_SKIP_UNSUPPORTED_VK_APP = 1,
165     SNAPSHOT_SKIP_UNSUPPORTED_VK_API = 2,
166 } SnapshotSkipReason;
167 
168 // C interface to expose Qemu implementations of common VM related operations.
169 typedef struct QAndroidVmOperations {
170     bool (*vmStop)(void);
171     bool (*vmStart)(void);
172     void (*vmReset)(void);
173     void (*vmShutdown)(void);
174     bool (*vmPause)(void);
175     bool (*vmResume)(void);
176 
177     bool (*vmIsRunning)(void);
178 
179     // Snapshot-related VM operations.
180     // |outConsuer| and |errConsumer| are used to report output / error
181     // respectively. Each line of output is newline terminated and results in
182     // one call to the callback. |opaque| is passed to the callbacks as context.
183     // Returns true on success, false on failure.
184     bool (*snapshotList)(void* opaque,
185                          LineConsumerCallback outConsumer,
186                          LineConsumerCallback errConsumer);
187     bool (*snapshotSave)(const char* name,
188                          void* opaque,
189                          LineConsumerCallback errConsumer);
190     bool (*snapshotLoad)(const char* name,
191                          void* opaque,
192                          LineConsumerCallback errConsumer);
193     bool (*snapshotDelete)(const char* name,
194                            void* opaque,
195                            LineConsumerCallback errConsumer);
196     bool (*snapshotRemap)(bool shared,
197                           void* opaque,
198                           LineConsumerCallback errConsumer);
199 
200     // Export the qcow2s associated with the given snapshot to the given destination.
201     bool (*snapshotExport)(const char* snapshot,
202                            const char* dest,
203                            void* opaque,
204                            LineConsumerCallback errConsumer);
205 
206     // Get the name of the last loaded snapshot (current snapshot).
207     // Will print "(null)" if the emulator cold booted and loaded no snapshots.
208     bool (*snapshotLastLoaded)(void* opaque,
209                              LineConsumerCallback outConsumer,
210                              LineConsumerCallback errConsumer);
211 
212     // Sets a set of callback to listen for snapshot operations.
213     void (*setSnapshotCallbacks)(void* opaque,
214                                  const SnapshotCallbacks* callbacks);
215 
216     // Sets a protobuf for the snapshot save and load
217     void (*setSnapshotProtobuf)(void* pb);
218     // callbacks to "plug" and "unplug" memory into the provided address range
219     // on fly.
220     void (*mapUserBackedRam)(uint64_t gpa, void* hva, uint64_t size);
221     void (*unmapUserBackedRam)(uint64_t gpa, uint64_t size);
222 
223     // Fills in the supplied |out| with current VM configuration.
224     void (*getVmConfiguration)(VmConfiguration* out);
225 
226     // Notifies QEMU of failed operations according to our own
227     // android::snapshot::FailureReason.
228     void (*setFailureReason)(const char* name, int failureReason);
229 
230     // Notifies QEMU that the emulator is exiting, can impact how
231     // QEMU snapshot save calls work.
232     void (*setExiting)(void);
233 
234     // Allow actual audio on host through to the guest.
235     void (*allowRealAudio)(bool allow);
236 
237     // Get the host address of a guest physical address, if any.
238     void* (*physicalMemoryGetAddr)(uint64_t gpa);
239 
240     // Query whether host audio is allowed.
241     bool (*isRealAudioAllowed)(void);
242 
243     // Set whether to skip snapshotting on exit.
244     void (*setSkipSnapshotSave)(bool used);
245 
246     // Retrieve the state of whether snapshotting is skipped.
247     bool (*isSnapshotSaveSkipped)(void);
248 
249     // Create/register/getinfo for host memory Id's
250     uint64_t (*hostmemRegister)(const struct MemEntry *entry);
251     void (*hostmemUnregister)(uint64_t id);
252     struct HostmemEntry (*hostmemGetInfo)(uint64_t id);
253     EmuRunState (*getRunState)();
254 
255     // virtio display
256     bool (*setDisplay)(int32_t id, int32_t w, int32_t h, uint32_t dpi);
257 
258     // Reset the machine
259     void (*system_shutdown_request)(QemuShutdownCause reason);
260 
261     // Set the reason to skip snapshotting on exit.
262     void (*setSkipSnapshotSaveReason)(SnapshotSkipReason reason);
263 
264     // Get the reason to skip snapshotting on exit.
265     SnapshotSkipReason (*getSkipSnapshotSaveReason)();
266 
267     // Set Vulkan snapshot is actively used, for stats.
268     void (*setStatSnapshotUseVulkan)(void);
269 
270     // Check if Vulkan snapshot is actively used, for stats.
271     bool (*snapshotUseVulkan)();
272 } QAndroidVmOperations;
273 ANDROID_END_HEADER
274