info.h revision 8b23a6c7e1aee255004dd19098d4c2462b61b849 
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
18/* An Android Virtual Device (AVD for short) corresponds to a
19 * directory containing all kernel/disk images for a given virtual
20 * device, as well as information about its hardware capabilities,
21 * SDK version number, skin, etc...
22 *
23 * Each AVD has a human-readable name and is backed by a root
24 * configuration file and a content directory. For example, an
25 *  AVD named 'foo' will correspond to the following:
26 *
27 *  - a root configuration file named ~/.android/avd/foo.ini
28 *    describing where the AVD's content can be found
29 *
30 *  - a content directory like ~/.android/avd/foo/ containing all
31 *    disk image and configuration files for the virtual device.
32 *
33 * the 'foo.ini' file should contain at least one line of the form:
34 *
35 *    rootPath=<content-path>
36 *
37 * it may also contain other lines that cache stuff found in the
38 * content directory, like hardware properties or SDK version number.
39 *
40 * it is possible to move the content directory by updating the foo.ini
41 * file to point to the new location. This can be interesting when your
42 * $HOME directory is located on a network share or in a roaming profile
43 * (Windows), given that the content directory of a single virtual device
44 * can easily use more than 100MB of data.
45 *
46 */
47
48/* a macro used to define the list of disk images managed by the
49 * implementation. This macro will be expanded several times with
50 * varying definitions of _AVD_IMG
51 */
52#define  AVD_IMAGE_LIST \
53    _AVD_IMG(KERNEL,"kernel-qemu","kernel") \
54    _AVD_IMG(RAMDISK,"ramdisk.img","ramdisk") \
55    _AVD_IMG(INITSYSTEM,"system.img","init system") \
56    _AVD_IMG(INITDATA,"userdata.img","init data") \
57    _AVD_IMG(USERSYSTEM,"system-qemu.img","user system") \
58    _AVD_IMG(USERDATA,"userdata-qemu.img", "user data") \
59    _AVD_IMG(CACHE,"cache.img","cache") \
60    _AVD_IMG(SDCARD,"sdcard.img","SD Card") \
61
62/* define the enumared values corresponding to each AVD image type
63 * examples are: AVD_IMAGE_KERNEL, AVD_IMAGE_SYSTEM, etc..
64 */
65#define _AVD_IMG(x,y,z)   AVD_IMAGE_##x ,
66typedef enum {
67    AVD_IMAGE_LIST
68    AVD_IMAGE_MAX /* do not remove */
69} AvdImageType;
70#undef  _AVD_IMG
71
72/* AvdInfo is an opaque structure used to model the information
73 * corresponding to a given AVD instance
74 */
75typedef struct AvdInfo  AvdInfo;
76
77/* various flags used when creating an AvdInfo object */
78typedef enum {
79    /* use to force a data wipe */
80    AVDINFO_WIPE_DATA = (1 << 0),
81    /* use to ignore the cache partition */
82    AVDINFO_NO_CACHE  = (1 << 1),
83    /* use to wipe cache partition, ignored if NO_CACHE is set */
84    AVDINFO_WIPE_CACHE = (1 << 2),
85    /* use to ignore ignore SDCard image (default or provided) */
86    AVDINFO_NO_SDCARD = (1 << 3),
87    /* use to wipe the system image with new initial values */
88    AVDINFO_WIPE_SYSTEM = (1 << 4),
89} AvdFlags;
90
91typedef struct {
92    unsigned     flags;
93    const char*  skinName;
94    const char*  skinRootPath;
95    const char*  forcePaths[AVD_IMAGE_MAX];
96} AvdInfoParams;
97
98/* Creates a new AvdInfo object from a name. Returns NULL if name is NULL
99 * or contains characters that are not part of the following list:
100 * letters, digits, underscores, dashes and periods
101 */
102AvdInfo*  avdInfo_new( const char*  name, AvdInfoParams*  params );
103
104/* A special function used to setup an AvdInfo for use when starting
105 * the emulator from the Android build system. In this specific instance
106 * we're going to create temporary files to hold all writable image
107 * files, and activate all hardware features by default
108 *
109 * 'androidBuildRoot' must be the absolute path to the root of the
110 * Android build system (i.e. the 'android' directory)
111 *
112 * 'androidOut' must be the target-specific out directory where
113 * disk images will be looked for.
114 */
115AvdInfo*  avdInfo_newForAndroidBuild( const char*     androidBuildRoot,
116                                      const char*     androidOut,
117                                      AvdInfoParams*  params );
118
119/* Frees an AvdInfo object and the corresponding strings that may be
120 * returned by its getXXX() methods
121 */
122void        avdInfo_free( AvdInfo*  i );
123
124/* Return the name of the Android Virtual Device
125 */
126const char*  avdInfo_getName( AvdInfo*  i );
127
128/* Try to find the path of a given image file, returns NULL
129 * if the corresponding file could not be found. the string
130 * belongs to the AvdInfo object.
131 */
132const char*  avdInfo_getImageFile( AvdInfo*  i, AvdImageType  imageType );
133
134/* Returns 1 if the corresponding image file is read-only
135 */
136int          avdInfo_isImageReadOnly( AvdInfo*  i, AvdImageType  imageType );
137
138/* lock an image file if it is writable. returns 0 on success, or -1
139 * otherwise. note that if the file is read-only, it doesn't need to
140 * be locked and the function will return success.
141 */
142int          avdInfo_lockImageFile( AvdInfo*  i, AvdImageType  imageType, int  abortOnError);
143
144/* Manually set the path of a given image file. */
145void         avdInfo_setImageFile( AvdInfo*  i, AvdImageType  imageType, const char*  imagePath );
146
147/* Returns the path of the skin directory */
148/* the string belongs to the AvdInfo object */
149const char*  avdInfo_getSkinPath( AvdInfo*  i );
150
151/* Returns the name of the virtual device's skin */
152const char*  avdInfo_getSkinName( AvdInfo*  i );
153
154/* Returns the root skin directory for this device */
155const char*  avdInfo_getSkinDir ( AvdInfo*  i );
156
157/* Returns the content path of the virtual device */
158const char*  avdInfo_getContentPath( AvdInfo*  i );
159
160/* Returns TRUE iff in the Android build system */
161int          avdInfo_inAndroidBuild( AvdInfo*  i );
162
163/* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */
164int          avdInfo_getHwConfig( AvdInfo*  i, AndroidHwConfig*  hw );
165
166/* Returns a *copy* of the path used to store trace 'foo'. result must be freed by caller */
167char*        avdInfo_getTracePath( AvdInfo*  i, const char*  traceName );
168
169/* */
170
171#endif /* ANDROID_AVD_INFO_H */
172