1/* Copyright (C) 2008 The Android Open Source Project 2** 3** This software is licensed under the terms of the GNU General Public 4** License version 2, as published by the Free Software Foundation, and 5** may be copied, distributed, and modified under those terms. 6** 7** This program is distributed in the hope that it will be useful, 8** but WITHOUT ANY WARRANTY; without even the implied warranty of 9** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10** GNU General Public License for more details. 11*/ 12#ifndef ANDROID_AVD_INFO_H 13#define ANDROID_AVD_INFO_H 14 15#include "android/utils/ini.h" 16#include "android/avd/hw-config.h" 17#include "android/config/config.h" 18 19/* An Android Virtual Device (AVD for short) corresponds to a 20 * directory containing all kernel/disk images for a given virtual 21 * device, as well as information about its hardware capabilities, 22 * SDK version number, skin, etc... 23 * 24 * Each AVD has a human-readable name and is backed by a root 25 * configuration file and a content directory. For example, an 26 * AVD named 'foo' will correspond to the following: 27 * 28 * - a root configuration file named ~/.android/avd/foo.ini 29 * describing where the AVD's content can be found 30 * 31 * - a content directory like ~/.android/avd/foo/ containing all 32 * disk image and configuration files for the virtual device. 33 * 34 * the 'foo.ini' file should contain at least one line of the form: 35 * 36 * rootPath=<content-path> 37 * 38 * it may also contain other lines that cache stuff found in the 39 * content directory, like hardware properties or SDK version number. 40 * 41 * it is possible to move the content directory by updating the foo.ini 42 * file to point to the new location. This can be interesting when your 43 * $HOME directory is located on a network share or in a roaming profile 44 * (Windows), given that the content directory of a single virtual device 45 * can easily use more than 100MB of data. 46 * 47 */ 48 49 50/* a macro used to define the list of disk images managed by the 51 * implementation. This macro will be expanded several times with 52 * varying definitions of _AVD_IMG 53 */ 54#define AVD_IMAGE_LIST \ 55 _AVD_IMG(KERNEL,"kernel-qemu","kernel") \ 56 _AVD_IMG(RAMDISK,"ramdisk.img","ramdisk") \ 57 _AVD_IMG(INITSYSTEM,"system.img","init system") \ 58 _AVD_IMG(INITDATA,"userdata.img","init data") \ 59 _AVD_IMG(USERSYSTEM,"system-qemu.img","user system") \ 60 _AVD_IMG(USERDATA,"userdata-qemu.img", "user data") \ 61 _AVD_IMG(CACHE,"cache.img","cache") \ 62 _AVD_IMG(SDCARD,"sdcard.img","SD Card") \ 63 _AVD_IMG(SNAPSHOTS,"snapshots.img","snapshots") \ 64 65/* define the enumared values corresponding to each AVD image type 66 * examples are: AVD_IMAGE_KERNEL, AVD_IMAGE_SYSTEM, etc.. 67 */ 68#define _AVD_IMG(x,y,z) AVD_IMAGE_##x , 69typedef enum { 70 AVD_IMAGE_LIST 71 AVD_IMAGE_MAX /* do not remove */ 72} AvdImageType; 73#undef _AVD_IMG 74 75/* AvdInfo is an opaque structure used to model the information 76 * corresponding to a given AVD instance 77 */ 78typedef struct AvdInfo AvdInfo; 79 80/* various flags used when creating an AvdInfo object */ 81typedef enum { 82 /* use to force a data wipe */ 83 AVDINFO_WIPE_DATA = (1 << 0), 84 /* use to ignore the cache partition */ 85 AVDINFO_NO_CACHE = (1 << 1), 86 /* use to wipe cache partition, ignored if NO_CACHE is set */ 87 AVDINFO_WIPE_CACHE = (1 << 2), 88 /* use to ignore ignore SDCard image (default or provided) */ 89 AVDINFO_NO_SDCARD = (1 << 3), 90 /* use to wipe the system image with new initial values */ 91 AVDINFO_WIPE_SYSTEM = (1 << 4), 92 /* use to ignore ignore state snapshot image (default or provided) */ 93 AVDINFO_NO_SNAPSHOTS = (1 << 5), 94} AvdFlags; 95 96typedef struct { 97 unsigned flags; 98 const char* skinName; 99 const char* skinRootPath; 100 const char* forcePaths[AVD_IMAGE_MAX]; 101} AvdInfoParams; 102 103/* Creates a new AvdInfo object from a name. Returns NULL if name is NULL 104 * or contains characters that are not part of the following list: 105 * letters, digits, underscores, dashes and periods 106 */ 107AvdInfo* avdInfo_new( const char* name, AvdInfoParams* params ); 108 109/* Update the AvdInfo hardware config from a given skin name and path */ 110int avdInfo_getSkinHardwareIni( AvdInfo* i, char* skinName, char* skinDirPath); 111 112/* A special function used to setup an AvdInfo for use when starting 113 * the emulator from the Android build system. In this specific instance 114 * we're going to create temporary files to hold all writable image 115 * files, and activate all hardware features by default 116 * 117 * 'androidBuildRoot' must be the absolute path to the root of the 118 * Android build system (i.e. the 'android' directory) 119 * 120 * 'androidOut' must be the target-specific out directory where 121 * disk images will be looked for. 122 */ 123AvdInfo* avdInfo_newForAndroidBuild( const char* androidBuildRoot, 124 const char* androidOut, 125 AvdInfoParams* params ); 126 127/* Frees an AvdInfo object and the corresponding strings that may be 128 * returned by its getXXX() methods 129 */ 130void avdInfo_free( AvdInfo* i ); 131 132/* Return the name of the Android Virtual Device 133 */ 134const char* avdInfo_getName( AvdInfo* i ); 135 136/* Return the target API level for this AVD. 137 * Note that this will be some ridiculously large 138 * value (e.g. 1000) if this value cannot be properly 139 * determined (e.g. you're using an AVD from a preview SDK) 140 */ 141int avdInfo_getApiLevel( AvdInfo* i ); 142 143/* Returns the path to various images corresponding to a given AVD. 144 * NULL if the image cannot be found. Returned strings must be freed 145 * by the caller. 146 */ 147char* avdInfo_getKernelPath( AvdInfo* i ); 148char* avdInfo_getRamdiskPath( AvdInfo* i ); 149char* avdInfo_getSdCardPath( AvdInfo* i ); 150char* avdInfo_getSnapStoragePath( AvdInfo* i ); 151 152/* This function returns NULL if the cache image file cannot be found. 153 * Use avdInfo_getDefaultCachePath() to retrieve the default path 154 * if you intend to create the partition file there. 155 */ 156char* avdInfo_getCachePath( AvdInfo* i ); 157char* avdInfo_getDefaultCachePath( AvdInfo* i ); 158 159 160/* avdInfo_getSystemImagePath() will return NULL, except if the AVD content 161 * directory contains a file named "system-qemu.img". 162 */ 163char* avdInfo_getSystemImagePath( AvdInfo* i ); 164 165/* avdInfo_getSystemInitImagePath() retrieves the path to the read-only 166 * initialization image for this disk image. 167 */ 168char* avdInfo_getSystemInitImagePath( AvdInfo* i ); 169 170char* avdInfo_getDataImagePath( AvdInfo* i ); 171char* avdInfo_getDefaultDataImagePath( AvdInfo* i ); 172char* avdInfo_getDataInitImagePath( AvdInfo* i ); 173 174/* Returns the path to a given AVD image file. This will return NULL if 175 * the file cannot be found / does not exist. 176 */ 177const char* avdInfo_getImagePath( AvdInfo* i, AvdImageType imageType ); 178 179/* Returns the default path of a given AVD image file. This only makes sense 180 * if avdInfo_getImagePath() returned NULL. 181 */ 182const char* avdInfo_getImageDefaultPath( AvdInfo* i, AvdImageType imageType ); 183 184 185/* Try to find the path of a given image file, returns NULL 186 * if the corresponding file could not be found. the string 187 * belongs to the AvdInfo object. 188 */ 189const char* avdInfo_getImageFile( AvdInfo* i, AvdImageType imageType ); 190 191/* Return the size of a given image file. Returns 0 if the file 192 * does not exist or could not be accessed. 193 */ 194uint64_t avdInfo_getImageFileSize( AvdInfo* i, AvdImageType imageType ); 195 196/* Returns 1 if the corresponding image file is read-only 197 */ 198int avdInfo_isImageReadOnly( AvdInfo* i, AvdImageType imageType ); 199 200/* lock an image file if it is writable. returns 0 on success, or -1 201 * otherwise. note that if the file is read-only, it doesn't need to 202 * be locked and the function will return success. 203 */ 204int avdInfo_lockImageFile( AvdInfo* i, AvdImageType imageType, int abortOnError); 205 206/* Manually set the path of a given image file. */ 207void avdInfo_setImageFile( AvdInfo* i, AvdImageType imageType, const char* imagePath ); 208 209/* Returns the content path of the virtual device */ 210const char* avdInfo_getContentPath( AvdInfo* i ); 211 212/* Retrieve the AVD's specific skin information. 213 * On exit: 214 * '*pSkinName' points to the skin's name. 215 * '*pSkinDir' points to the skin's directory. 216 * 217 * Note that the skin's content will be under <skinDir>/<skinName>. 218 */ 219void avdInfo_getSkinInfo( AvdInfo* i, char** pSkinName, char** pSkinDir ); 220 221/* Returns whether the AVD specifies the use of a dynamic skin */ 222int avdInfo_shouldUseDynamicSkin( AvdInfo* i); 223 224/* Find a charmap file named <charmapName>.kcm for this AVD. 225 * Returns the path of the file on success, or NULL if not found. 226 * The result string must be freed by the caller. 227 */ 228char* avdInfo_getCharmapFile( AvdInfo* i, const char* charmapName ); 229 230/* Returns TRUE iff in the Android build system */ 231int avdInfo_inAndroidBuild( AvdInfo* i ); 232 233/* Returns the target ABI for the corresponding platform image. 234 * This may return NULL if it cannot be determined. Otherwise this is 235 * a string like "armeabi", "armeabi-v7a" or "x86" that must be freed 236 * by the caller. 237 */ 238char* avdInfo_getTargetAbi( AvdInfo* i ); 239 240/* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */ 241int avdInfo_initHwConfig( AvdInfo* i, AndroidHwConfig* hw ); 242 243/* Returns a *copy* of the path used to store trace 'foo'. result must be freed by caller */ 244char* avdInfo_getTracePath( AvdInfo* i, const char* traceName ); 245 246/* Returns the path of the hardware.ini where we will write the AVD's 247 * complete hardware configuration before launching the corresponding 248 * core. 249 */ 250const char* avdInfo_getCoreHwIniPath( AvdInfo* i ); 251 252/* Returns mode in which ADB daemon running in the guest communicates with the 253 * emulator 254 * Return: 255 * 0 - ADBD communicates with the emulator via forwarded TCP port 5555 (a 256 * "legacy" mode). 257 * 1 - ADBD communicates with the emulator via 'adb' QEMUD service. 258 */ 259int avdInfo_getAdbdCommunicationMode( AvdInfo* i ); 260 261/* Returns config.ini snapshot presense status. 262 * This routine checks if snapshots are enabled in AVD config.ini file. 263 * Return: 264 * 1 - Snapshots are enabled in AVD config.ini file. 265 * 0 - Snapshots are disabled in AVD config.ini file, of config.ini file is not 266 * found. 267*/ 268int avdInfo_getSnapshotPresent(AvdInfo* i); 269 270/* */ 271 272#endif /* ANDROID_AVD_INFO_H */ 273