Home | History | Annotate | Download | only in avd
      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 ,
     69 typedef 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  */
     78 typedef struct AvdInfo  AvdInfo;
     79 
     80 /* various flags used when creating an AvdInfo object */
     81 typedef 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 
     96 typedef 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  */
    107 AvdInfo*  avdInfo_new( const char*  name, AvdInfoParams*  params );
    108 
    109 /* Update the AvdInfo hardware config from a given skin name and path */
    110 int 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  */
    123 AvdInfo*  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  */
    130 void        avdInfo_free( AvdInfo*  i );
    131 
    132 /* Return the name of the Android Virtual Device
    133  */
    134 const 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  */
    141 int    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  */
    147 char*  avdInfo_getKernelPath( AvdInfo*  i );
    148 char*  avdInfo_getRamdiskPath( AvdInfo*  i );
    149 char*  avdInfo_getSdCardPath( AvdInfo* i );
    150 char*  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  */
    156 char*  avdInfo_getCachePath( AvdInfo*  i );
    157 char*  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  */
    163 char*  avdInfo_getSystemImagePath( AvdInfo* i );
    164 
    165 /* avdInfo_getSystemInitImagePath() retrieves the path to the read-only
    166  * initialization image for this disk image.
    167  */
    168 char*  avdInfo_getSystemInitImagePath( AvdInfo*  i );
    169 
    170 char*  avdInfo_getDataImagePath( AvdInfo*  i );
    171 char*  avdInfo_getDefaultDataImagePath( AvdInfo*  i );
    172 char*  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  */
    177 const 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  */
    182 const 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  */
    189 const 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  */
    194 uint64_t     avdInfo_getImageFileSize( AvdInfo*  i, AvdImageType  imageType );
    195 
    196 /* Returns 1 if the corresponding image file is read-only
    197  */
    198 int          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  */
    204 int          avdInfo_lockImageFile( AvdInfo*  i, AvdImageType  imageType, int  abortOnError);
    205 
    206 /* Manually set the path of a given image file. */
    207 void         avdInfo_setImageFile( AvdInfo*  i, AvdImageType  imageType, const char*  imagePath );
    208 
    209 /* Returns the content path of the virtual device */
    210 const 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  */
    219 void         avdInfo_getSkinInfo( AvdInfo*  i, char** pSkinName, char** pSkinDir );
    220 
    221 /* Find a charmap file named <charmapName>.kcm for this AVD.
    222  * Returns the path of the file on success, or NULL if not found.
    223  * The result string must be freed by the caller.
    224  */
    225 char*        avdInfo_getCharmapFile( AvdInfo* i, const char* charmapName );
    226 
    227 /* Returns TRUE iff in the Android build system */
    228 int          avdInfo_inAndroidBuild( AvdInfo*  i );
    229 
    230 /* Returns the target ABI for the corresponding platform image.
    231  * This may return NULL if it cannot be determined. Otherwise this is
    232  * a string like "armeabi", "armeabi-v7a" or "x86" that must be freed
    233  * by the caller.
    234  */
    235 char*        avdInfo_getTargetAbi( AvdInfo*  i );
    236 
    237 /* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */
    238 int          avdInfo_initHwConfig( AvdInfo*  i, AndroidHwConfig*  hw );
    239 
    240 /* Returns a *copy* of the path used to store trace 'foo'. result must be freed by caller */
    241 char*        avdInfo_getTracePath( AvdInfo*  i, const char*  traceName );
    242 
    243 /* Returns the path of the hardware.ini where we will write the AVD's
    244  * complete hardware configuration before launching the corresponding
    245  * core.
    246  */
    247 const char*  avdInfo_getCoreHwIniPath( AvdInfo* i );
    248 
    249 /* Returns mode in which ADB daemon running in the guest communicates with the
    250  * emulator
    251  * Return:
    252  *  0 - ADBD communicates with the emulator via forwarded TCP port 5555 (a
    253  *      "legacy" mode).
    254  *  1 - ADBD communicates with the emulator via 'adb' QEMUD service.
    255  */
    256 int          avdInfo_getAdbdCommunicationMode( AvdInfo* i );
    257 
    258 /* Returns config.ini snapshot presense status.
    259  * This routine checks if snapshots are enabled in AVD config.ini file.
    260  * Return:
    261  *  1 - Snapshots are enabled in AVD config.ini file.
    262  *  0 - Snapshots are disabled in AVD config.ini file, of config.ini file is not
    263  *      found.
    264 */
    265 int          avdInfo_getSnapshotPresent(AvdInfo* i);
    266 
    267 /* */
    268 
    269 #endif /* ANDROID_AVD_INFO_H */
    270