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/compiler.h" 16 #include "android/utils/ini.h" 17 #include "android/avd/hw-config.h" 18 #include "android/config/config.h" 19 #include "android/utils/file_data.h" 20 21 ANDROID_BEGIN_HEADER 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(RAMDISK,"ramdisk.img","ramdisk") \ 61 _AVD_IMG(INITSYSTEM,"system.img","init system") \ 62 _AVD_IMG(INITDATA,"userdata.img","init data") \ 63 _AVD_IMG(USERSYSTEM,"system-qemu.img","user system") \ 64 _AVD_IMG(USERDATA,"userdata-qemu.img", "user data") \ 65 _AVD_IMG(CACHE,"cache.img","cache") \ 66 _AVD_IMG(SDCARD,"sdcard.img","SD Card") \ 67 _AVD_IMG(SNAPSHOTS,"snapshots.img","snapshots") \ 68 69 /* define the enumared values corresponding to each AVD image type 70 * examples are: AVD_IMAGE_KERNEL, AVD_IMAGE_SYSTEM, etc.. 71 */ 72 #define _AVD_IMG(x,y,z) AVD_IMAGE_##x , 73 typedef enum { 74 AVD_IMAGE_LIST 75 AVD_IMAGE_MAX /* do not remove */ 76 } AvdImageType; 77 #undef _AVD_IMG 78 79 /* AvdInfo is an opaque structure used to model the information 80 * corresponding to a given AVD instance 81 */ 82 typedef struct AvdInfo AvdInfo; 83 84 /* various flags used when creating an AvdInfo object */ 85 typedef enum { 86 /* use to force a data wipe */ 87 AVDINFO_WIPE_DATA = (1 << 0), 88 /* use to ignore the cache partition */ 89 AVDINFO_NO_CACHE = (1 << 1), 90 /* use to wipe cache partition, ignored if NO_CACHE is set */ 91 AVDINFO_WIPE_CACHE = (1 << 2), 92 /* use to ignore ignore SDCard image (default or provided) */ 93 AVDINFO_NO_SDCARD = (1 << 3), 94 /* use to wipe the system image with new initial values */ 95 AVDINFO_WIPE_SYSTEM = (1 << 4), 96 /* use to ignore ignore state snapshot image (default or provided) */ 97 AVDINFO_NO_SNAPSHOTS = (1 << 5), 98 } AvdFlags; 99 100 typedef struct { 101 unsigned flags; 102 const char* skinName; 103 const char* skinRootPath; 104 const char* forcePaths[AVD_IMAGE_MAX]; 105 } AvdInfoParams; 106 107 /* Creates a new AvdInfo object from a name. Returns NULL if name is NULL 108 * or contains characters that are not part of the following list: 109 * letters, digits, underscores, dashes and periods 110 */ 111 AvdInfo* avdInfo_new( const char* name, AvdInfoParams* params ); 112 113 /* Update the AvdInfo hardware config from a given skin name and path */ 114 int avdInfo_getSkinHardwareIni( AvdInfo* i, char* skinName, char* skinDirPath); 115 116 /* A special function used to setup an AvdInfo for use when starting 117 * the emulator from the Android build system. In this specific instance 118 * we're going to create temporary files to hold all writable image 119 * files, and activate all hardware features by default 120 * 121 * 'androidBuildRoot' must be the absolute path to the root of the 122 * Android build system (i.e. the 'android' directory) 123 * 124 * 'androidOut' must be the target-specific out directory where 125 * disk images will be looked for. 126 */ 127 AvdInfo* avdInfo_newForAndroidBuild( const char* androidBuildRoot, 128 const char* androidOut, 129 AvdInfoParams* params ); 130 131 /* Frees an AvdInfo object and the corresponding strings that may be 132 * returned by its getXXX() methods 133 */ 134 void avdInfo_free( AvdInfo* i ); 135 136 /* Return the name of the Android Virtual Device 137 */ 138 const char* avdInfo_getName( AvdInfo* i ); 139 140 /* Return the target API level for this AVD. 141 * Note that this will be some ridiculously large 142 * value (e.g. 1000) if this value cannot be properly 143 * determined (e.g. you're using an AVD from a preview SDK) 144 */ 145 int avdInfo_getApiLevel( AvdInfo* i ); 146 147 /* Returns the path to various images corresponding to a given AVD. 148 * NULL if the image cannot be found. Returned strings must be freed 149 * by the caller. 150 */ 151 char* avdInfo_getKernelPath( AvdInfo* i ); 152 char* avdInfo_getRamdiskPath( AvdInfo* i ); 153 char* avdInfo_getSdCardPath( AvdInfo* i ); 154 char* avdInfo_getSnapStoragePath( AvdInfo* i ); 155 156 /* This function returns NULL if the cache image file cannot be found. 157 * Use avdInfo_getDefaultCachePath() to retrieve the default path 158 * if you intend to create the partition file there. 159 */ 160 char* avdInfo_getCachePath( AvdInfo* i ); 161 char* avdInfo_getDefaultCachePath( AvdInfo* i ); 162 163 164 /* avdInfo_getSystemImagePath() will return NULL, except if the AVD content 165 * directory contains a file named "system-qemu.img". 166 */ 167 char* avdInfo_getSystemImagePath( AvdInfo* i ); 168 169 /* avdInfo_getSystemInitImagePath() retrieves the path to the read-only 170 * initialization image for this disk image. 171 */ 172 char* avdInfo_getSystemInitImagePath( AvdInfo* i ); 173 174 char* avdInfo_getDataImagePath( AvdInfo* i ); 175 char* avdInfo_getDefaultDataImagePath( AvdInfo* i ); 176 char* avdInfo_getDataInitImagePath( AvdInfo* i ); 177 178 /* Return a reference to the boot.prop file for this AVD, if any. 179 * The file contains additionnal properties to inject at boot time 180 * into the guest system. Note that this never returns NULL, but 181 * the corresponding content can be empty. 182 */ 183 const FileData* avdInfo_getBootProperties( AvdInfo* i ); 184 185 /* Returns the path to a given AVD image file. This will return NULL if 186 * the file cannot be found / does not exist. 187 */ 188 const char* avdInfo_getImagePath( AvdInfo* i, AvdImageType imageType ); 189 190 /* Returns the default path of a given AVD image file. This only makes sense 191 * if avdInfo_getImagePath() returned NULL. 192 */ 193 const char* avdInfo_getImageDefaultPath( AvdInfo* i, AvdImageType imageType ); 194 195 196 /* Try to find the path of a given image file, returns NULL 197 * if the corresponding file could not be found. the string 198 * belongs to the AvdInfo object. 199 */ 200 const char* avdInfo_getImageFile( AvdInfo* i, AvdImageType imageType ); 201 202 /* Return the size of a given image file. Returns 0 if the file 203 * does not exist or could not be accessed. 204 */ 205 uint64_t avdInfo_getImageFileSize( AvdInfo* i, AvdImageType imageType ); 206 207 /* Returns 1 if the corresponding image file is read-only 208 */ 209 int avdInfo_isImageReadOnly( AvdInfo* i, AvdImageType imageType ); 210 211 /* lock an image file if it is writable. returns 0 on success, or -1 212 * otherwise. note that if the file is read-only, it doesn't need to 213 * be locked and the function will return success. 214 */ 215 int avdInfo_lockImageFile( AvdInfo* i, AvdImageType imageType, int abortOnError); 216 217 /* Manually set the path of a given image file. */ 218 void avdInfo_setImageFile( AvdInfo* i, AvdImageType imageType, const char* imagePath ); 219 220 /* Returns the content path of the virtual device */ 221 const char* avdInfo_getContentPath( AvdInfo* i ); 222 223 /* Retrieve the AVD's specific skin information. 224 * On exit: 225 * '*pSkinName' points to the skin's name. 226 * '*pSkinDir' points to the skin's directory. 227 * 228 * Note that the skin's content will be under <skinDir>/<skinName>. 229 */ 230 void avdInfo_getSkinInfo( AvdInfo* i, char** pSkinName, char** pSkinDir ); 231 232 /* Returns whether the AVD specifies the use of a dynamic skin */ 233 int avdInfo_shouldUseDynamicSkin( AvdInfo* i); 234 235 /* Returns the path that contains layout and assets for dynamic skin */ 236 char* avdInfo_getDynamicSkinPath( AvdInfo* i); 237 238 /* Find a charmap file named <charmapName>.kcm for this AVD. 239 * Returns the path of the file on success, or NULL if not found. 240 * The result string must be freed by the caller. 241 */ 242 char* avdInfo_getCharmapFile( AvdInfo* i, const char* charmapName ); 243 244 /* Returns TRUE iff in the Android build system */ 245 int avdInfo_inAndroidBuild( AvdInfo* i ); 246 247 /* Return the target CPU architecture for this AVD. 248 * This returns NULL if that cannot be determined, or a string that 249 * must be freed by the caller otherwise. 250 */ 251 char* avdInfo_getTargetCpuArch(AvdInfo* i); 252 253 /* Returns the target ABI for the corresponding platform image. 254 * This may return NULL if it cannot be determined. Otherwise this is 255 * a string like "armeabi", "armeabi-v7a" or "x86" that must be freed 256 * by the caller. 257 */ 258 char* avdInfo_getTargetAbi( AvdInfo* i ); 259 260 /* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */ 261 int avdInfo_initHwConfig( AvdInfo* i, AndroidHwConfig* hw ); 262 263 /* Returns a *copy* of the path used to store trace 'foo'. result must be freed by caller */ 264 char* avdInfo_getTracePath( AvdInfo* i, const char* traceName ); 265 266 /* Returns the path of the hardware.ini where we will write the AVD's 267 * complete hardware configuration before launching the corresponding 268 * core. 269 */ 270 const char* avdInfo_getCoreHwIniPath( AvdInfo* i ); 271 272 /* Returns mode in which ADB daemon running in the guest communicates with the 273 * emulator 274 * Return: 275 * 0 - ADBD communicates with the emulator via forwarded TCP port 5555 (a 276 * "legacy" mode). 277 * 1 - ADBD communicates with the emulator via 'adb' QEMUD service. 278 */ 279 int avdInfo_getAdbdCommunicationMode( AvdInfo* i ); 280 281 /* Returns config.ini snapshot presense status. 282 * This routine checks if snapshots are enabled in AVD config.ini file. 283 * Return: 284 * 1 - Snapshots are enabled in AVD config.ini file. 285 * 0 - Snapshots are disabled in AVD config.ini file, of config.ini file is not 286 * found. 287 */ 288 int avdInfo_getSnapshotPresent(AvdInfo* i); 289 290 ANDROID_END_HEADER 291 292 #endif /* ANDROID_AVD_INFO_H */ 293