1 // Copyright 2020 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 "hw-config.h" 18 #include "util.h" 19 #include "base/export.h" 20 21 class CIniFile; 22 23 /* An Android Virtual Device (AVD for short) corresponds to a 24 * directory containing all kernel/disk images for a given virtual 25 * device, as well as information about its hardware capabilities, 26 * SDK version number, skin, etc... 27 * 28 * Each AVD has a human-readable name and is backed by a root 29 * configuration file and a content directory. For example, an 30 * AVD named 'foo' will correspond to the following: 31 * 32 * - a root configuration file named ~/.android/avd/foo.ini 33 * describing where the AVD's content can be found 34 * 35 * - a content directory like ~/.android/avd/foo/ containing all 36 * disk image and configuration files for the virtual device. 37 * 38 * the 'foo.ini' file should contain at least one line of the form: 39 * 40 * rootPath=<content-path> 41 * 42 * it may also contain other lines that cache stuff found in the 43 * content directory, like hardware properties or SDK version number. 44 * 45 * it is possible to move the content directory by updating the foo.ini 46 * file to point to the new location. This can be interesting when your 47 * $HOME directory is located on a network share or in a roaming profile 48 * (Windows), given that the content directory of a single virtual device 49 * can easily use more than 100MB of data. 50 * 51 */ 52 53 54 /* a macro used to define the list of disk images managed by the 55 * implementation. This macro will be expanded several times with 56 * varying definitions of _AVD_IMG 57 */ 58 #define AVD_IMAGE_LIST \ 59 _AVD_IMG(KERNEL,"kernel-qemu","kernel") \ 60 _AVD_IMG(KERNELRANCHU,"kernel-ranchu","kernel") \ 61 _AVD_IMG(KERNELRANCHU64,"kernel-ranchu-64","kernel") \ 62 _AVD_IMG(RAMDISK,"ramdisk.img","ramdisk") \ 63 _AVD_IMG(USERRAMDISK,"ramdisk-qemu.img","user ramdisk") \ 64 _AVD_IMG(INITSYSTEM,"system.img","init system") \ 65 _AVD_IMG(INITVENDOR,"vendor.img","init vendor") \ 66 _AVD_IMG(INITDATA,"userdata.img","init data") \ 67 _AVD_IMG(INITZIP,"data","init data zip") \ 68 _AVD_IMG(USERSYSTEM,"system-qemu.img","user system") \ 69 _AVD_IMG(USERVENDOR,"vendor-qemu.img","user vendor") \ 70 _AVD_IMG(USERDATA,"userdata-qemu.img", "user data") \ 71 _AVD_IMG(CACHE,"cache.img","cache") \ 72 _AVD_IMG(SDCARD,"sdcard.img","SD Card") \ 73 _AVD_IMG(ENCRYPTIONKEY,"encryptionkey.img","Encryption Key") \ 74 _AVD_IMG(SNAPSHOTS,"snapshots.img","snapshots") \ 75 _AVD_IMG(VERIFIEDBOOTPARAMS, "VerifiedBootParams.textproto","Verified Boot Parameters") \ 76 77 /* define the enumared values corresponding to each AVD image type 78 * examples are: AVD_IMAGE_KERNEL, AVD_IMAGE_SYSTEM, etc.. 79 */ 80 #define _AVD_IMG(x,y,z) AVD_IMAGE_##x , 81 typedef enum { 82 AVD_IMAGE_LIST 83 AVD_IMAGE_MAX /* do not remove */ 84 } AvdImageType; 85 #undef _AVD_IMG 86 87 /* AvdInfo is an opaque structure used to model the information 88 * corresponding to a given AVD instance 89 */ 90 typedef struct AvdInfo AvdInfo; 91 92 /* various flags used when creating an AvdInfo object */ 93 typedef enum { 94 /* use to force a data wipe */ 95 AVDINFO_WIPE_DATA = (1 << 0), 96 /* use to ignore the cache partition */ 97 AVDINFO_NO_CACHE = (1 << 1), 98 /* use to wipe cache partition, ignored if NO_CACHE is set */ 99 AVDINFO_WIPE_CACHE = (1 << 2), 100 /* use to ignore ignore SDCard image (default or provided) */ 101 AVDINFO_NO_SDCARD = (1 << 3), 102 /* use to wipe the system image with new initial values */ 103 AVDINFO_WIPE_SYSTEM = (1 << 4), 104 /* use to ignore state snapshot image (default or provided) */ 105 AVDINFO_NO_SNAPSHOT_LOAD = (1 << 5), 106 /* use to prevent saving state on exit (set by the UI) */ 107 AVDINFO_NO_SNAPSHOT_SAVE_ON_EXIT = (1 << 6), 108 /* invalidate the current quickboot snapshot */ 109 AVDINFO_SNAPSHOT_INVALIDATE = (1 << 7), 110 } AvdFlags; 111 112 typedef struct { 113 unsigned flags; 114 const char* skinName; 115 const char* skinRootPath; 116 const char* forcePaths[AVD_IMAGE_MAX]; 117 } AvdInfoParams; 118 119 /* Creates a new AvdInfo object from a name. Returns NULL if name is NULL 120 * or contains characters that are not part of the following list: 121 * letters, digits, underscores, dashes and periods 122 */ 123 AvdInfo* avdInfo_new( const char* name, AvdInfoParams* params ); 124 125 /* Sets a custom ID for this AVD. */ 126 void avdInfo_setAvdId( AvdInfo* i, const char* id ); 127 128 /* Update the AvdInfo hardware config from a given skin name and path */ 129 int avdInfo_getSkinHardwareIni( AvdInfo* i, char* skinName, char* skinDirPath); 130 131 /* A special function used to setup an AvdInfo for use when starting 132 * the emulator from the Android build system. In this specific instance 133 * we're going to create temporary files to hold all writable image 134 * files, and activate all hardware features by default 135 * 136 * 'androidBuildRoot' must be the absolute path to the root of the 137 * Android build system (i.e. the 'android' directory) 138 * 139 * 'androidOut' must be the target-specific out directory where 140 * disk images will be looked for. 141 */ 142 AvdInfo* avdInfo_newForAndroidBuild( const char* androidBuildRoot, 143 const char* androidOut, 144 AvdInfoParams* params ); 145 146 /* Frees an AvdInfo object and the corresponding strings that may be 147 * returned by its getXXX() methods 148 */ 149 void avdInfo_free( AvdInfo* i ); 150 151 /* Return the name of the Android Virtual Device 152 */ 153 const char* avdInfo_getName( const AvdInfo* i ); 154 155 /* Get the device ID, which can be different from the AVD name 156 * depending on multiple instances or the specific use case. */ 157 const char* avdInfo_getId( const AvdInfo* i ); 158 159 /* Return the target API level for this AVD. 160 * Note that this will be some ridiculously large 161 * value (e.g. 1000) if this value cannot be properly 162 * determined (e.g. you're using an AVD from a preview SDK) 163 */ 164 static const int kUnknownApiLevel = 1000; 165 int avdInfo_getApiLevel( const AvdInfo* i ); 166 167 /* Return the "dessert name" associated with the 168 * API level 169 */ 170 const char* avdInfo_getApiDessertName(int apiLevel); 171 172 /* Return the full version name associated with the 173 * API level 174 */ 175 void avdInfo_getFullApiName(int apiLevel, char* nameStr, int strLen); 176 177 /* Return the api level corresponding to a single-letter API code, 178 * e.g. 'N' -> 24 179 */ 180 int avdInfo_getApiLevelFromLetter(char letter); 181 182 /* Returns true if the AVD is on Google APIs. */ 183 bool avdInfo_isGoogleApis( const AvdInfo* i ); 184 185 /* Returns true if the AVD is a user build. */ 186 bool avdInfo_isUserBuild(const AvdInfo* i); 187 188 /* Querying AVD flavors. */ 189 AvdFlavor avdInfo_getAvdFlavor( const AvdInfo* i); 190 191 /* Returns the path to various images corresponding to a given AVD. 192 * NULL if the image cannot be found. Returned strings must be freed 193 * by the caller. 194 */ 195 char* avdInfo_getKernelPath( const AvdInfo* i ); 196 char* avdInfo_getRanchuKernelPath( const AvdInfo* i ); 197 char* avdInfo_getRamdiskPath( const AvdInfo* i ); 198 char* avdInfo_getSdCardPath( const AvdInfo* i ); 199 char* avdInfo_getEncryptionKeyImagePath( const AvdInfo* i ); 200 char* avdInfo_getSnapStoragePath( const AvdInfo* i ); 201 202 /* This function returns NULL if the cache image file cannot be found. 203 * Use avdInfo_getDefaultCachePath() to retrieve the default path 204 * if you intend to create the partition file there. 205 */ 206 char* avdInfo_getCachePath( const AvdInfo* i ); 207 char* avdInfo_getDefaultCachePath( const AvdInfo* i ); 208 209 /* avdInfo_getSystemImagePath() will return NULL, except if the AVD content 210 * directory contains a file named "system-qemu.img". 211 */ 212 char* avdInfo_getSystemImagePath( const AvdInfo* i ); 213 214 /* Will return NULL, except if the AVD content 215 * directory contains a file named "VerifiedBootParams.textproto". 216 */ 217 char* avdInfo_getVerifiedBootParamsPath( const AvdInfo* i ); 218 219 /* avdInfo_getSystemInitImagePath() retrieves the path to the read-only 220 * initialization image for this disk image. 221 */ 222 char* avdInfo_getSystemInitImagePath( const AvdInfo* i ); 223 224 char* avdInfo_getVendorImagePath( const AvdInfo* i ); 225 char* avdInfo_getVendorInitImagePath( const AvdInfo* i ); 226 227 /* 228 The following two methods are used for device tree support 229 for early boot of O should always use the following method 230 to get the right path, as things may change for P and afterwards 231 */ 232 233 /* always returns valid string */ 234 char* avdInfo_getSystemImageDevicePathInGuest( const AvdInfo* i ); 235 /* 236 returns NULL if not applicable 237 */ 238 char* avdInfo_getVendorImageDevicePathInGuest( const AvdInfo* i ); 239 240 /* 241 for xish: pci0000:00/0000:00:03.0 242 for armish: %s.virtio_mmio 243 */ 244 char* avdInfo_getDynamicPartitionBootDevice( const AvdInfo* i ); 245 246 char* avdInfo_getDataImagePath( const AvdInfo* i ); 247 char* avdInfo_getDefaultDataImagePath( const AvdInfo* i ); 248 249 /* avdInfo_getDefaultSystemFeatureControlPath() returns the path to the 250 * per-system image feature control file 251 */ 252 char* avdInfo_getDefaultSystemFeatureControlPath(const AvdInfo* i); 253 254 /* avdInfo_getDataInitImagePath returns the path of userdata.img used 255 * for initialization when -wipe-data. 256 * Newer versions of system images shall use avdInfo_getDataInitDirPath 257 * to generate userdata.img when -wipe-data 258 */ 259 char* avdInfo_getDataInitImagePath( const AvdInfo* i ); 260 261 /* avdInfo_getDataInitDirPath returns the path to the unpacked user data 262 * folder. Newer versions of system images shall use the unpacked user data 263 * instead of the prebuilt image to initialize userdata.img. 264 */ 265 char* avdInfo_getDataInitDirPath( const AvdInfo* i ); 266 267 /* Return a reference to the boot.prop file for this AVD, if any. 268 * The file contains additionnal properties to inject at boot time 269 * into the guest system. Note that this never returns NULL, but 270 * the corresponding content can be empty. 271 */ 272 const FileData* avdInfo_getBootProperties(const AvdInfo* i); 273 274 /* Return a reference to the build.prop file for this AVD, if any. 275 * The file contains information about the system image used in the AVD. 276 * Note that this never returns NULL, but the corresponding content can 277 * be empty. 278 */ 279 const FileData* avdInfo_getBuildProperties(const AvdInfo* i); 280 281 /* Return a reference to the avd/confif.init file for this AVD. 282 * Note that this vaue could be NULL. 283 */ 284 CIniFile* avdInfo_getConfigIni(const AvdInfo* i); 285 286 /* Returns the path to a given AVD image file. This will return NULL if 287 * the file cannot be found / does not exist. 288 */ 289 const char* avdInfo_getImagePath( const AvdInfo* i, AvdImageType imageType ); 290 291 /* Returns the default path of a given AVD image file. This only makes sense 292 * if avdInfo_getImagePath() returned NULL. 293 */ 294 const char* avdInfo_getImageDefaultPath( const AvdInfo* i, AvdImageType imageType ); 295 296 297 /* Try to find the path of a given image file, returns NULL 298 * if the corresponding file could not be found. the string 299 * belongs to the AvdInfo object. 300 */ 301 const char* avdInfo_getImageFile( const AvdInfo* i, AvdImageType imageType ); 302 303 /* Return the size of a given image file. Returns 0 if the file 304 * does not exist or could not be accessed. 305 */ 306 uint64_t avdInfo_getImageFileSize( const AvdInfo* i, AvdImageType imageType ); 307 308 /* Returns 1 if the corresponding image file is read-only 309 */ 310 int avdInfo_isImageReadOnly( const AvdInfo* i, AvdImageType imageType ); 311 312 /* lock an image file if it is writable. returns 0 on success, or -1 313 * otherwise. note that if the file is read-only, it doesn't need to 314 * be locked and the function will return success. 315 */ 316 int avdInfo_lockImageFile( const AvdInfo* i, AvdImageType imageType, int abortOnError); 317 318 /* Manually set the path of a given image file. */ 319 void avdInfo_setImageFile( AvdInfo* i, AvdImageType imageType, const char* imagePath ); 320 321 /* Manually set the path of the acpi ini path. */ 322 void avdInfo_setAcpiIniPath( AvdInfo* i, const char* iniPath ); 323 324 /* Returns the content path of the virtual device */ 325 const char* avdInfo_getContentPath( const AvdInfo* i ); 326 327 /* Returns the root ini path of the virtual device */ 328 const char* avdInfo_getRootIniPath( const AvdInfo* i ); 329 330 /* Returns the acpi configuration path of the virtual device*/ 331 const char* avdInfo_getAcpiIniPath( const AvdInfo* i ); 332 333 /* Retrieve the AVD's specific skin information. 334 * On exit: 335 * '*pSkinName' points to the skin's name. 336 * '*pSkinDir' points to the skin's directory. 337 * 338 * Note that the skin's content will be under <skinDir>/<skinName>. 339 */ 340 void avdInfo_getSkinInfo( const AvdInfo* i, char** pSkinName, char** pSkinDir ); 341 342 /* Find a charmap file named <charmapName>.kcm for this AVD. 343 * Returns the path of the file on success, or NULL if not found. 344 * The result string must be freed by the caller. 345 */ 346 char* avdInfo_getCharmapFile( const AvdInfo* i, const char* charmapName ); 347 348 /* Returns TRUE iff in the Android build system */ 349 int avdInfo_inAndroidBuild( const AvdInfo* i ); 350 351 /* Return the target CPU architecture for this AVD. 352 * This returns NULL if that cannot be determined, or a string that 353 * must be freed by the caller otherwise. 354 */ 355 char* avdInfo_getTargetCpuArch(const AvdInfo* i); 356 357 /* Returns the target ABI for the corresponding platform image. 358 * This may return NULL if it cannot be determined. Otherwise this is 359 * a string like "armeabi", "armeabi-v7a" or "x86" that must be freed 360 * by the caller. 361 */ 362 char* avdInfo_getTargetAbi( const AvdInfo* i ); 363 364 /* A helper to quickly find out if this is a x86-compatible AVD */ 365 bool avdInfo_is_x86ish(const AvdInfo* i); 366 367 /* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */ 368 int avdInfo_initHwConfig(const AvdInfo* i, 369 AndroidHwConfig* hw, 370 bool isQemu2); 371 372 /* Returns a *copy* of the path used to store profile 'foo'. result must be freed by caller */ 373 char* avdInfo_getCodeProfilePath( const AvdInfo* i, const char* profileName ); 374 375 /* Returns the path of the hardware.ini where we will write the AVD's 376 * complete hardware configuration before launching the corresponding 377 * core. 378 */ 379 const char* avdInfo_getCoreHwIniPath( const AvdInfo* i ); 380 381 /* Returns the path of the snapshot lock file that is used to determine 382 * whether or not the current AVD is undergoing a snapshot operation. */ 383 const char* avdInfo_getSnapshotLockFilePath( const AvdInfo* i ); 384 385 const char* avdInfo_getMultiInstanceLockFilePath( const AvdInfo* i ); 386 387 /* Describes the ways emulator may set up host adb <-> guest adbd communication: 388 * legacy - ADBD communicates with the emulator via forwarded TCP port 5555. 389 * pipe - ADBD communicates with the emulator via 'adb' pipe service. 390 */ 391 typedef enum { 392 ADBD_COMMUNICATION_MODE_LEGACY, 393 ADBD_COMMUNICATION_MODE_PIPE, 394 } AdbdCommunicationMode; 395 396 /* Returns mode in which ADB daemon running in the guest communicates with the 397 * emulator. 398 */ 399 AdbdCommunicationMode avdInfo_getAdbdCommunicationMode(const AvdInfo* i, 400 bool isQemu2); 401 402 /* Returns config.ini snapshot presense status. 403 * This routine checks if snapshots are enabled in AVD config.ini file. 404 * Return: 405 * 1 - Snapshots are enabled in AVD config.ini file. 406 * 0 - Snapshots are disabled in AVD config.ini file, of config.ini file is not 407 * found. 408 */ 409 int avdInfo_getSnapshotPresent(const AvdInfo* i); 410 411 /* Returns the incremental version number of the AVD's system image. 412 */ 413 int avdInfo_getSysImgIncrementalVersion(const AvdInfo* i); 414 415 /* Return the tag of a specific AVD in the format of "|tag.id|[|tag.display|]". 416 * The default value is "default [Default]". The implementation is in reference 417 * to 418 * sdk/sdkmanager/libs/sdklib/src/com/android/sdklib/internal/avd/AvdInfo.java 419 */ 420 const char* avdInfo_getTag(const AvdInfo* i); 421 422 /* Return SD card size in human readable format or NULL if the SD card doesn't 423 * exist. 424 */ 425 const char* avdInfo_getSdCardSize(const AvdInfo* i); 426 427 /* Returns true if the system image has problems with guest rendering. */ 428 bool avdInfo_sysImgGuestRenderingBlacklisted(const AvdInfo* i); 429 430 /* Replace the disk.dataPartition.size in avd config.ini */ 431 void avdInfo_replaceDataPartitionSizeInConfigIni(AvdInfo* i, int64_t sizeBytes); 432 433 bool avdInfo_isMarshmallowOrHigher(AvdInfo* i); 434 435 AEMU_EXPORT AvdInfo* avdInfo_newCustom( 436 const char* name, 437 int apiLevel, 438 const char* abi, 439 const char* arch, 440 bool isGoogleApis, 441 AvdFlavor flavor); 442 443 /* Set a custom content path. Useful for testing. */ 444 void avdInfo_setCustomContentPath(AvdInfo* info, const char* path); 445 446 /* Set a custom core hw ini path. Useful for testing. */ 447 void avdInfo_setCustomCoreHwIniPath(AvdInfo* info, const char* path); 448 449 void avdInfo_replaceMultiDisplayInConfigIni(AvdInfo* i, int index, 450 int x, int y, 451 int w, int h, 452 int dpi, int flag ); 453 454 /* Maximum number of supported multi display entries in an avd. */ 455 int avdInfo_maxMultiDisplayEntries();