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
21ANDROID_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 ,
73typedef 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 */
82typedef struct AvdInfo  AvdInfo;
83
84/* various flags used when creating an AvdInfo object */
85typedef 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
100typedef 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 */
111AvdInfo*  avdInfo_new( const char*  name, AvdInfoParams*  params );
112
113/* Update the AvdInfo hardware config from a given skin name and path */
114int 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 */
127AvdInfo*  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 */
134void        avdInfo_free( AvdInfo*  i );
135
136/* Return the name of the Android Virtual Device
137 */
138const 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 */
145int    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 */
151char*  avdInfo_getKernelPath( AvdInfo*  i );
152char*  avdInfo_getRamdiskPath( AvdInfo*  i );
153char*  avdInfo_getSdCardPath( AvdInfo* i );
154char*  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 */
160char*  avdInfo_getCachePath( AvdInfo*  i );
161char*  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 */
167char*  avdInfo_getSystemImagePath( AvdInfo* i );
168
169/* avdInfo_getSystemInitImagePath() retrieves the path to the read-only
170 * initialization image for this disk image.
171 */
172char*  avdInfo_getSystemInitImagePath( AvdInfo*  i );
173
174char*  avdInfo_getDataImagePath( AvdInfo*  i );
175char*  avdInfo_getDefaultDataImagePath( AvdInfo*  i );
176char*  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 */
183const 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 */
188const 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 */
193const 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 */
200const 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 */
205uint64_t     avdInfo_getImageFileSize( AvdInfo*  i, AvdImageType  imageType );
206
207/* Returns 1 if the corresponding image file is read-only
208 */
209int          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 */
215int          avdInfo_lockImageFile( AvdInfo*  i, AvdImageType  imageType, int  abortOnError);
216
217/* Manually set the path of a given image file. */
218void         avdInfo_setImageFile( AvdInfo*  i, AvdImageType  imageType, const char*  imagePath );
219
220/* Returns the content path of the virtual device */
221const 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 */
230void         avdInfo_getSkinInfo( AvdInfo*  i, char** pSkinName, char** pSkinDir );
231
232/* Returns whether the AVD specifies the use of a dynamic skin */
233int          avdInfo_shouldUseDynamicSkin( AvdInfo* i);
234
235/* Returns the path that contains layout and assets for dynamic skin */
236char*        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 */
242char*        avdInfo_getCharmapFile( AvdInfo* i, const char* charmapName );
243
244/* Returns TRUE iff in the Android build system */
245int          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 */
251char*        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 */
258char*        avdInfo_getTargetAbi( AvdInfo*  i );
259
260/* Reads the AVD's hardware configuration into 'hw'. returns -1 on error, 0 otherwise */
261int          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 */
264char*        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 */
270const 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 */
279int          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*/
288int          avdInfo_getSnapshotPresent(AvdInfo* i);
289
290ANDROID_END_HEADER
291
292#endif /* ANDROID_AVD_INFO_H */
293