blob: acddfa8870643f567e152dfb8c74fbefcbb64df6 [file] [log] [blame]
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001#include "android/help.h"
2#include "android/cmdline-option.h"
3#include "android/utils/path.h"
4#include "android/utils/bufprint.h"
5#include "android/utils/debug.h"
6#include "android/utils/misc.h"
David 'Digit' Turnerd1744342014-07-11 14:03:25 +02007#ifndef NO_SKIN
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08008#include "android/skin/keyset.h"
David 'Digit' Turnerd1744342014-07-11 14:03:25 +02009#endif
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -080010#include "android/android.h"
11#include <stdint.h>
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -080012#include <string.h>
13#include <stdlib.h>
14
15/* XXX: TODO: put most of the help stuff in auto-generated files */
16
17#define PRINTF(...) stralloc_add_format(out,__VA_ARGS__)
18
19static void
20help_virtual_device( stralloc_t* out )
21{
22 PRINTF(
23 " An Android Virtual Device (AVD) models a single virtual\n"
24 " device running the Android platform that has, at least, its own\n"
25 " kernel, system image and data partition.\n\n"
26
27 " Only one emulator process can run a given AVD at a time, but\n"
28 " you can create several AVDs and run them concurrently.\n\n"
29
30 " You can invoke a given AVD at startup using either '-avd <name>'\n"
31 " or '@<name>', both forms being equivalent. For example, to launch\n"
32 " the AVD named 'foo', type:\n\n"
33
34 " emulator @foo\n\n"
35
36 " The 'android' helper tool can be used to manage virtual devices.\n"
37 " For example:\n\n"
38
David Turnerb58c44e2009-03-25 02:42:45 -070039 " android create avd -n <name> -t 1 # creates a new virtual device.\n"
40 " android list avd # list all virtual devices available.\n\n"
41
42 " Try 'android --help' for more commands.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -080043
44 " Each AVD really corresponds to a content directory which stores\n"
45 " persistent and writable disk images as well as configuration files.\n"
46
47 " Each AVD must be created against an existing SDK platform or add-on.\n"
48 " For more information on this topic, see -help-sdk-images.\n\n"
49
50 " SPECIAL NOTE: in the case where you are *not* using the emulator\n"
51 " with the Android SDK, but with the Android build system, you will\n"
52 " need to define the ANDROID_PRODUCT_OUT variable in your environment.\n"
53 " See -help-build-images for the details.\n"
54 );
55}
56
57
58static void
59help_sdk_images( stralloc_t* out )
60{
61 PRINTF(
62 " The Android SDK now supports multiple versions of the Android platform.\n"
63 " Each SDK 'platform' corresponds to:\n\n"
64
65 " - a given version of the Android API.\n"
66 " - a set of corresponding system image files.\n"
67 " - build and configuration properties.\n"
68 " - an android.jar file used when building your application.\n"
69 " - skins.\n\n"
70
71 " The Android SDK also supports the concept of 'add-ons'. Each add-on is\n"
72 " based on an existing platform, and provides replacement or additional\n"
73 " image files, android.jar, hardware configuration options and/or skins.\n\n"
74
75 " The purpose of add-ons is to allow vendors to provide their own customized\n"
76 " system images and APIs without needing to package a complete SDK.\n\n"
77
78 " Before using the SDK, you need to create an Android Virtual Device (AVD)\n"
79 " (see -help-virtual-device for details). Each AVD is created in reference\n"
80 " to a given SDK platform *or* add-on, and will search the corresponding\n"
Vladimir Chtchetkine5389aa12010-02-16 10:38:35 -080081 " directories for system image files, in the following order:\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -080082
83 " - in the AVD's content directory.\n"
84 " - in the AVD's SDK add-on directory, if any.\n"
85 " - in the AVD's SDK platform directory, if any.\n\n"
86
87 " The image files are documented in -help-disk-images. By default, an AVD\n"
88 " content directory will contain the following persistent image files:\n\n"
89
90 " userdata-qemu.img - the /data partition image file\n"
91 " cache.img - the /cache partition image file\n\n"
92
93 " You can use -wipe-data to re-initialize the /data partition to its factory\n"
94 " defaults. This will erase all user settings for the virtual device.\n\n"
95 );
96}
97
98static void
99help_build_images( stralloc_t* out )
100{
101 PRINTF(
102 " The emulator detects that you are working from the Android build system\n"
103 " by looking at the ANDROID_PRODUCT_OUT variable in your environment.\n\n"
104
105 " If it is defined, it should point to the product-specific directory that\n"
106 " contains the generated system images.\n"
107
108 " In this case, the emulator will look by default for the following image\n"
109 " files there:\n\n"
110
111 " - system.img : the *initial* system image.\n"
112 " - ramdisk.img : the ramdisk image used to boot the system.\n"
113 " - userdata.img : the *initial* user data image (see below).\n"
114 " - kernel-qemu : the emulator-specific Linux kernel image.\n\n"
115
116 " If the kernel image is not found in the out directory, then it is searched\n"
Andrew Hsieh045b33e2012-01-18 16:21:11 -0800117 " in <build-root>/prebuilts/qemu-kernel/.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800118
Andrew Hsieh045b33e2012-01-18 16:21:11 -0800119 " Skins will be looked in <build-root>/development/tools/emulator/skins/\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800120
121 " You can use the -sysdir, -system, -kernel, -ramdisk, -datadir, -data options\n"
122 " to specify different search directories or specific image files. You can\n"
David 'Digit' Turner92568952010-04-15 15:04:16 -0700123 " also use the -cache and -sdcard options to indicate specific cache partition\n"
124 " and SD Card image files.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800125
126 " For more details, see the corresponding -help-<option> section.\n\n"
127
128 " Note that the following behaviour is specific to 'build mode':\n\n"
129
130 " - the *initial* system image is copied to a temporary file which is\n"
131 " automatically removed when the emulator exits. There is thus no way to\n"
132 " make persistent changes to this image through the emulator, even if\n"
133 " you use the '-image <file>' option.\n\n"
134
135 " - unless you use the '-cache <file>' option, the cache partition image\n"
136 " is backed by a temporary file that is initially empty and destroyed on\n"
137 " program exit.\n\n"
138
139 " SPECIAL NOTE: If you are using the emulator with the Android SDK, the\n"
140 " information above doesn't apply. See -help-sdk-images for more details.\n"
141 );
142}
143
144static void
145help_disk_images( stralloc_t* out )
146{
147 char datadir[256];
148
149 bufprint_config_path( datadir, datadir + sizeof(datadir) );
150
151 PRINTF(
152 " The emulator needs several key image files to run appropriately.\n"
153 " Their exact location depends on whether you're using the emulator\n"
154 " from the Android SDK, or not (more details below).\n\n"
155
156 " The minimal required image files are the following:\n\n"
157
158 " kernel-qemu the emulator-specific Linux kernel image\n"
159 " ramdisk.img the ramdisk image used to boot the system\n"
160 " system.img the *initial* system image\n"
161 " userdata.img the *initial* data partition image\n\n"
162
163 " It will also use the following writable image files:\n\n"
164
165 " userdata-qemu.img the persistent data partition image\n"
166 " system-qemu.img an *optional* persistent system image\n"
167 " cache.img an *optional* cache partition image\n"
168 " sdcard.img an *optional* SD Card partition image\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100169 " snapshots.img an *optional* state snapshots image\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800170
171 " If you use a virtual device, its content directory should store\n"
172 " all writable images, and read-only ones will be found from the\n"
173 " corresponding platform/add-on directories. See -help-sdk-images\n"
174 " for more details.\n\n"
175
176 " If you are building from the Android build system, you should\n"
177 " have ANDROID_PRODUCT_OUT defined in your environment, and the\n"
178 " emulator shall be able to pick-up the right image files automatically.\n"
179 " See -help-build-images for more details.\n\n"
180
181 " If you're neither using the SDK or the Android build system, you\n"
182 " can still run the emulator by explicitely providing the paths to\n"
183 " *all* required disk images through a combination of the following\n"
184 " options: -sysdir, -datadir, -kernel, -ramdisk, -system, -data, -cache\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100185 " -sdcard and -snapstorage.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800186
187 " The actual logic being that the emulator should be able to find all\n"
188 " images from the options you give it.\n\n"
189
190 " For more detail, see the corresponding -help-<option> entry.\n\n"
191
192 " Other related options are:\n\n"
193
Ot ten Thije353b3b12010-10-05 17:53:30 +0100194 " -init-data Specify an alternative *initial* user data image\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800195
Ot ten Thije353b3b12010-10-05 17:53:30 +0100196 " -wipe-data Copy the content of the *initial* user data image\n"
197" (userdata.img) into the writable one (userdata-qemu.img)\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800198
Ot ten Thije353b3b12010-10-05 17:53:30 +0100199 " -no-cache do not use a cache partition, even if one is\n"
200 " available.\n\n"
201
Ot ten Thije353b3b12010-10-05 17:53:30 +0100202 " -no-snapstorage do not use a state snapshot image, even if one is\n"
203 " available.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800204 ,
205 datadir );
206}
207
208static void
209help_keys(stralloc_t* out)
210{
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200211#ifndef NO_SKIN
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800212 int pass, maxw = 0;
213
214 stralloc_add_str( out, " When running the emulator, use the following keypresses:\n\n");
215
216 if (!android_keyset)
217 android_keyset = skin_keyset_new_from_text( skin_keyset_get_default() );
218
219 for (pass = 0; pass < 2; pass++) {
220 SkinKeyCommand cmd;
221
222 for (cmd = SKIN_KEY_COMMAND_NONE+1; cmd < SKIN_KEY_COMMAND_MAX; cmd++)
223 {
224 SkinKeyBinding bindings[ SKIN_KEY_COMMAND_MAX_BINDINGS ];
225 int n, count, len;
226 char temp[32], *p = temp, *end = p + sizeof(temp);
227
228 count = skin_keyset_get_bindings( android_keyset, cmd, bindings );
229 if (count <= 0)
230 continue;
231
232 for (n = 0; n < count; n++) {
233 p = bufprint(p, end, "%s%s", (n == 0) ? "" : ", ",
234 skin_key_symmod_to_str( bindings[n].sym, bindings[n].mod ) );
235 }
236
237 if (pass == 0) {
238 len = strlen(temp);
239 if (len > maxw)
240 maxw = len;
241 } else {
242 PRINTF( " %-*s %s\n", maxw, temp, skin_key_command_description(cmd) );
243 }
244 }
245 }
246 PRINTF( "\n" );
247 PRINTF( " note that NumLock must be deactivated for keypad keys to work\n\n" );
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200248#endif // !NO_SKIN
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800249}
Xavier Ducrohetfc8ed802011-02-09 18:04:23 -0800250
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800251
252static void
253help_environment(stralloc_t* out)
254{
255 PRINTF(
256 " The Android emulator looks at various environment variables when it starts:\n\n"
257
258 " If ANDROID_LOG_TAGS is defined, it will be used as in '-logcat <tags>'.\n\n"
259
260 " If 'http_proxy' is defined, it will be used as in '-http-proxy <proxy>'.\n\n"
261
262 " If ANDROID_VERBOSE is defined, it can contain a comma-separated list of\n"
263 " verbose items. for example:\n\n"
264
265 " ANDROID_VERBOSE=socket,radio\n\n"
266
267 " is equivalent to using the '-verbose -verbose-socket -verbose-radio'\n"
268 " options together. unsupported items will be ignored.\n\n"
269
270 " If ANDROID_LOG_TAGS is defined, it will be used as in '-logcat <tags>'.\n\n"
271
272 " If ANDROID_SDK_HOME is defined, it indicates the path of the '.android'\n"
273 " directory which contains the SDK user data (Android Virtual Devices,\n"
274 " DDMS preferences, key stores, etc.).\n\n"
275
276 " If ANDROID_SDK_ROOT is defined, it indicates the path of the SDK\n"
277 " installation directory.\n\n"
278
279 );
280}
281
Xavier Ducrohetfc8ed802011-02-09 18:04:23 -0800282
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800283static void
284help_keyset_file(stralloc_t* out)
285{
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200286#ifndef NO_SKIN
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800287 int n, count;
288 const char** strings;
289 char temp[MAX_PATH];
290
291 PRINTF(
292 " on startup, the emulator looks for 'keyset' file that contains the\n"
293 " configuration of key-bindings to use. the default location on this\n"
294 " system is:\n\n"
295 );
296
297 bufprint_config_file( temp, temp+sizeof(temp), KEYSET_FILE );
298 PRINTF( " %s\n\n", temp );
299
300 PRINTF(
301 " if the file doesn't exist, the emulator writes one containing factory\n"
302 " defaults. you are then free to modify it to suit specific needs.\n\n"
303 " this file shall contain a list of text lines in the following format:\n\n"
304
305 " <command> [<modifiers>]<key>\n\n"
306
307 " where <command> is an emulator-specific command name, i.e. one of:\n\n"
308 );
309
310 count = SKIN_KEY_COMMAND_MAX-1;
311 strings = calloc( count, sizeof(char*) );
312 for (n = 0; n < count; n++)
313 strings[n] = skin_key_command_to_str(n+1);
314
315 stralloc_tabular( out, strings, count, " ", 80-8 );
316 free(strings);
317
318 PRINTF(
319 "\n"
320 " <modifers> is an optional list of <modifier> elements (without separators)\n"
321 " which can be one of:\n\n"
322
323 " Ctrl- Left Control Key\n"
324 " Shift- Left Shift Key\n"
325 " Alt- Left Alt key\n"
326 " RCtrl- Right Control Key\n"
327 " RShift- Right Shift Key\n"
328 " RAlt- Right Alt key (a.k.a AltGr)\n"
329 "\n"
330 " finally <key> is a QWERTY-specific keyboard symbol which can be one of:\n\n"
331 );
332 count = skin_keysym_str_count();
333 strings = calloc( count, sizeof(char*) );
334 for (n = 0; n < count; n++)
335 strings[n] = skin_keysym_str(n);
336
337 stralloc_tabular( out, strings, count, " ", 80-8 );
338 free(strings);
339
340 PRINTF(
341 "\n"
342 " case is not significant, and a single command can be associated to up\n"
343 " to %d different keys. to bind a command to multiple keys, use commas to\n"
344 " separate them. here are some examples:\n\n",
345 SKIN_KEY_COMMAND_MAX_BINDINGS );
346
347 PRINTF(
348 " TOGGLE_NETWORK F8 # toggle the network on/off\n"
349 " CHANGE_LAYOUT_PREV Keypad_7,Ctrl-J # switch to a previous skin layout\n"
350 "\n"
351 );
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200352#endif // !NO_SKIN
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800353}
Xavier Ducrohetfc8ed802011-02-09 18:04:23 -0800354
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800355
356static void
357help_debug_tags(stralloc_t* out)
358{
359 int n;
360
361#define _VERBOSE_TAG(x,y) { #x, VERBOSE_##x, y },
362 static const struct { const char* name; int flag; const char* text; }
363 verbose_options[] = {
364 VERBOSE_TAG_LIST
365 { 0, 0, 0 }
366 };
367#undef _VERBOSE_TAG
368
369 PRINTF(
370 " the '-debug <tags>' option can be used to enable or disable debug\n"
371 " messages from specific parts of the emulator. <tags> must be a list\n"
372 " (separated by space/comma/column) of <component> names, which can be one of:\n\n"
373 );
374
375 for (n = 0; n < VERBOSE_MAX; n++)
376 PRINTF( " %-12s %s\n", verbose_options[n].name, verbose_options[n].text );
377 PRINTF( " %-12s %s\n", "all", "all components together\n" );
378
379 PRINTF(
380 "\n"
381 " each <component> can be prefixed with a single '-' to indicate the disabling\n"
382 " of its debug messages. for example:\n\n"
383
384 " -debug all,-socket,-keys\n\n"
385
386 " enables all debug messages, except the ones related to network sockets\n"
387 " and key bindings/presses\n\n"
388 );
389}
390
391static void
392help_char_devices(stralloc_t* out)
393{
394 PRINTF(
395 " various emulation options take a <device> specification that can be used to\n"
396 " specify something to hook to an emulated device or communication channel.\n"
397 " here is the list of supported <device> specifications:\n\n"
398
399 " stdio\n"
400 " standard input/output. this may be subject to character\n"
401 " translation (e.g. LN <=> CR/LF)\n\n"
402
403 " COM<n> [Windows only]\n"
404 " where <n> is a digit. host serial communication port.\n\n"
405
406 " pipe:<filename>\n"
407 " named pipe <filename>\n\n"
408
409 " file:<filename>\n"
410 " write output to <filename>, no input can be read\n\n"
411
412 " pty [Linux only]\n"
413 " pseudo TTY (a new PTY is automatically allocated)\n\n"
414
415 " /dev/<file> [Unix only]\n"
416 " host char device file, e.g. /dev/ttyS0. may require root access\n\n"
417
418 " /dev/parport<N> [Linux only]\n"
419 " use host parallel port. may require root access\n\n"
420
421 " unix:<path>[,server][,nowait]] [Unix only]\n"
422 " use a Unix domain socket. if you use the 'server' option, then\n"
423 " the emulator will create the socket and wait for a client to\n"
424 " connect before continuing, unless you also use 'nowait'\n\n"
425
426 " tcp:[<host>]:<port>[,server][,nowait][,nodelay]\n"
427 " use a TCP socket. 'host' is set to localhost by default. if you\n"
428 " use the 'server' option will bind the port and wait for a client\n"
429 " to connect before continuing, unless you also use 'nowait'. the\n"
430 " 'nodelay' option disables the TCP Nagle algorithm\n\n"
431
432 " telnet:[<host>]:<port>[,server][,nowait][,nodelay]\n"
433 " similar to 'tcp:' but uses the telnet protocol instead of raw TCP\n\n"
434
435 " udp:[<remote_host>]:<remote_port>[@[<src_ip>]:<src_port>]\n"
436 " send output to a remote UDP server. if 'remote_host' is no\n"
437 " specified it will default to '0.0.0.0'. you can also receive input\n"
438 " through UDP by specifying a source address after the optional '@'.\n\n"
439
440 " fdpair:<fd1>,<fd2> [Unix only]\n"
441 " redirection input and output to a pair of pre-opened file\n"
442 " descriptors. this is mostly useful for scripts and other\n"
443 " programmatic launches of the emulator.\n\n"
444
445 " none\n"
446 " no device connected\n\n"
447
448 " null\n"
449 " the null device (a.k.a /dev/null on Unix, or NUL on Win32)\n\n"
450
451 " NOTE: these correspond to the <device> parameter of the QEMU -serial option\n"
452 " as described on http://bellard.org/qemu/qemu-doc.html#SEC10\n\n"
453 );
454}
455
456static void
457help_avd(stralloc_t* out)
458{
459 PRINTF(
David Turnerb58c44e2009-03-25 02:42:45 -0700460 " use '-avd <name>' to start the emulator program with a given Android\n"
461 " Virtual Device (a.k.a. AVD), where <name> must correspond to the name\n"
462 " of one of the existing AVDs available on your host machine.\n\n"
463
464 "See -help-virtual-device to learn how to create/list/manage AVDs.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800465
466 " As a special convenience, using '@<name>' is equivalent to using\n"
467 " '-avd <name>'.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800468 );
469}
470
471static void
472help_sysdir(stralloc_t* out)
473{
474 char systemdir[MAX_PATH];
475 char *p = systemdir, *end = p + sizeof(systemdir);
476
477 p = bufprint_app_dir( p, end );
478 p = bufprint( p, end, PATH_SEP "lib" PATH_SEP "images" );
479
480 PRINTF(
481 " use '-sysdir <dir>' to specify a directory where system read-only\n"
482 " image files will be searched. on this system, the default directory is:\n\n"
483 " %s\n\n", systemdir );
484
485 PRINTF(
486 " see '-help-disk-images' for more information about disk image files\n\n" );
487}
488
489static void
490help_datadir(stralloc_t* out)
491{
492 char datadir[MAX_PATH];
493
494 bufprint_config_path(datadir, datadir + sizeof(datadir));
495
496 PRINTF(
497 " use '-datadir <dir>' to specify a directory where writable image files\n"
498 " will be searched. on this system, the default directory is:\n\n"
499 " %s\n\n", datadir );
500
501 PRINTF(
502 " see '-help-disk-images' for more information about disk image files\n\n" );
503}
504
505static void
506help_kernel(stralloc_t* out)
507{
508 PRINTF(
509 " use '-kernel <file>' to specify a Linux kernel image to be run.\n"
510 " the default image is 'kernel-qemu' from the system directory.\n\n"
511
512 " you can use '-debug-kernel' to see debug messages from the kernel\n"
513 " to the terminal\n\n"
514
515 " see '-help-disk-images' for more information about disk image files\n\n"
516 );
517}
518
519static void
520help_ramdisk(stralloc_t* out)
521{
522 PRINTF(
523 " use '-ramdisk <file>' to specify a Linux ramdisk boot image to be run in\n"
524 " the emulator. the default image is 'ramdisk.img' from the system directory.\n\n"
525
526 " see '-help-disk-images' for more information about disk image files\n\n"
527 );
528}
529
530static void
531help_system(stralloc_t* out)
532{
533 PRINTF(
534 " use '-system <file>' to specify the intial system image that will be loaded.\n"
535 " the default image is 'system.img' from the system directory.\n\n"
536
537 " NOTE: In previous releases of the Android SDK, this option was named '-image'.\n"
538 " And using '-system <path>' was equivalent to using '-sysdir <path>' now.\n\n"
539
540 " see '-help-disk-images' for more information about disk image files\n\n"
541 );
542}
543
544static void
545help_image(stralloc_t* out)
546{
547 PRINTF(
548 " This option is obsolete, you should use '-system <file>' instead to point\n"
549 " to the initial system image.\n\n"
550
551 " see '-help-disk-images' for more information about disk image files\n\n"
552 );
553}
554
555static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800556help_data(stralloc_t* out)
557{
558 PRINTF(
559 " use '-data <file>' to specify a different /data partition image file.\n\n"
560
561 " see '-help-disk-images' for more information about disk image files\n\n"
562 );
563}
564
565static void
566help_wipe_data(stralloc_t* out)
567{
568 PRINTF(
569 " use '-wipe-data' to reset your /data partition image to its factory\n"
570 " defaults. this removes all installed applications and settings.\n\n"
571
572 " see '-help-disk-images' for more information about disk image files\n\n"
573 );
574}
575
576static void
577help_cache(stralloc_t* out)
578{
579 PRINTF(
580 " use '-cache <file>' to specify a /cache partition image. if <file> does\n"
581 " not exist, it will be created empty. by default, the cache partition is\n"
582 " backed by a temporary file that is deleted when the emulator exits.\n"
583 " using the -cache option allows it to be persistent.\n\n"
584
585 " the '-no-cache' option can be used to disable the cache partition.\n\n"
586
587 " see '-help-disk-images' for more information about disk image files\n\n"
588 );
589}
590
591static void
Vladimir Chtchetkine6f50aa32012-04-26 08:20:18 -0700592help_cache_size(stralloc_t* out)
593{
594 PRINTF(
595 " use '-cache <size>' to specify a /cache partition size in MB. By default,\n"
596 " the cache partition size is set to 66MB\n\n"
597 );
598}
599
600static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800601help_no_cache(stralloc_t* out)
602{
603 PRINTF(
604 " use '-no-cache' to disable the cache partition in the emulated system.\n"
605 " the cache partition is optional, but when available, is used by the browser\n"
606 " to cache web pages and images\n\n"
607
608 " see '-help-disk-images' for more information about disk image files\n\n"
609 );
610}
611
612static void
613help_sdcard(stralloc_t* out)
614{
615 PRINTF(
616 " use '-sdcard <file>' to specify a SD Card image file that will be attached\n"
617 " to the emulator. By default, the 'sdcard.img' file is searched in the data\n"
618 " directory.\n\n"
619
620 " if the file does not exist, the emulator will still start, but without an\n"
621 " attached SD Card.\n\n"
622
623 " see '-help-disk-images' for more information about disk image files\n\n"
624 );
625}
626
Ot ten Thije353b3b12010-10-05 17:53:30 +0100627static void
628help_snapstorage(stralloc_t* out)
629{
630 PRINTF(
631 " Use '-snapstorage <file>' to specify a repository file for snapshots.\n"
632 " All snapshots made during execution will be saved in this file, and only\n"
633 " snapshots in this file can be restored during the emulator run.\n\n"
634
635 " If the option is not specified, it defaults to 'snapshots.img' in the\n"
636 " data directory. If the specified file does not exist, the emulator will\n"
637 " start, but without support for saving or loading state snapshots.\n\n"
638
639 " see '-help-disk-images' for more information about disk image files\n"
640 " see '-help-snapshot' for more information about snapshots\n\n"
641 );
642}
643
644static void
645help_no_snapstorage(stralloc_t* out)
646{
647 PRINTF(
648 " This starts the emulator without mounting a file to store or load state\n"
649 " snapshots, forcing a full boot and disabling state snapshot functionality.\n\n"
650 ""
651 " This command overrides the configuration specified by the parameters\n"
652 " '-snapstorage' and '-snapshot'. A warning will be raised if either\n"
653 " of those parameters was specified anyway.\n\n"
654 );
655 }
656
657static void
658help_snapshot(stralloc_t* out)
659{
660 PRINTF(
661 " Rather than executing a full boot sequence, the Android emulator can\n"
662 " resume execution from an earlier state snapshot (which is usually\n"
663 " significantly faster). When the parameter '-snapshot <name>' is given,\n"
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000664 " the emulator loads the snapshot of that name from the snapshot image,\n"
665 " and saves it back under the same name on exit.\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100666
667 " If the option is not specified, it defaults to 'default-boot'. If the\n"
668 " specified snapshot does not exist, the emulator will perform a full boot\n"
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000669 " sequence instead, but will still save.\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100670
671 " WARNING: In the process of loading, all contents of the system, userdata\n"
672 " and SD card images will be OVERWRITTEN with the contents they\n"
673 " held when the snapshot was made. Unless saved in a different\n"
674 " snapshot, any changes since will be lost!\n\n"
675
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000676 " If you want to create a snapshot manually, connect to the emulator console:\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100677
678 " telnet localhost <port>\n\n"
679
680 " Then execute the command 'avd snapshot save <name>'. See '-help-port' for\n"
681 " information on obtaining <port>.\n\n"
682 );
683}
684
685static void
686help_no_snapshot(stralloc_t* out)
687{
688 PRINTF(
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000689 " This inhibits both the autoload and autosave operations, forcing\n"
690 " emulator to perform a full boot sequence and losing state on close.\n"
691 " It overrides the '-snapshot' parameter.\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100692 " If '-snapshot' was specified anyway, a warning is raised.\n\n"
693 );
694}
695
Ot ten Thijeae835ac2010-10-18 13:37:37 +0100696static void
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000697help_no_snapshot_load(stralloc_t* out)
698{
699 PRINTF(
700 " Prevents the emulator from loading the AVD's state from the snapshot\n"
701 " storage on start.\n\n"
702 );
703}
704
705static void
Tim Baverstock24204cc2010-11-25 11:37:43 +0000706help_no_snapshot_save(stralloc_t* out)
707{
708 PRINTF(
709 " Prevents the emulator from saving the AVD's state to the snapshot\n"
710 " storage on exit, meaning that all changes will be lost.\n\n"
711 );
712}
713
714static void
Tim Baverstock622b8f42010-12-07 11:36:59 +0000715help_no_snapshot_update_time(stralloc_t* out)
716{
717 PRINTF(
718 " Prevent the emulator from sending an unsolicited time update\n"
719 " in response to the first signal strength query after loadvm,\n"
720 " to avoid a sudden time jump that might upset testing. (Signal\n"
721 " strength is queried approximately every 15 seconds)\n\n"
722 );
723}
724
725static void
Ot ten Thijeae835ac2010-10-18 13:37:37 +0100726help_snapshot_list(stralloc_t* out)
727{
728 PRINTF(
729 " This prints a table of snapshots that are stored in the snapshot storage\n"
730 " file that the emulator was started with, then exits. Values from the 'ID'\n"
731 " and 'TAG' columns can be used as arguments for the '-snapshot' parameter.\n\n"
732
733 " If '-snapstorage <file>' was specified as well, this command prints a "
734 " table of the snapshots stored in <file>.\n\n"
735
736 " See '-help-snapshot' for more information on snapshots.\n\n"
737 );
738}
739
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800740static void
David 'Digit' Turner045bdbe2014-04-28 22:26:52 +0200741help_accel(stralloc_t *out)
742{
743 PRINTF(
744 " Use '-accel <mode>' to control how CPU emulation can be accelerated\n"
745 " when launching the Android emulator. Accelerated emulation only works\n"
746 " for x86 and x86_64 system images. On Linux, it relies on KVM being\n"
747 " installed. On Windows and OS X, it relies on an Intel CPU and the\n"
748 " Intel HAXM driver being installed on your development machine.\n"
749 " Valid values for <mode> are:\n\n"
750
751 " auto The default, determines automatically if acceleration\n"
752 " is supported, and uses it when possible.\n\n"
753
754 " off Disables acceleration entirely. Mostly useful for debugging.\n\n"
755
756 " on Force acceleration. If KVM/HAXM is not installed or usable,\n"
757 " the emulator will refuse to start and print an error message.\n\n"
758
759 " Note that this flag is ignored if you're not emulating an x86 or x86_64\n"
760 );
761}
762
763static void
764help_no_accel(stralloc_t* out)
765{
766 PRINTF(
767 " Use '-no-accel' as a shortcut to '-accel off', i.e. to disable accelerated\n"
768 " CPU emulation, when emulating an x86 or x86_64 system image. Only useful\n"
769 " for debugging.\n"
770 );
771}
772
773static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800774help_skindir(stralloc_t* out)
775{
776 PRINTF(
777 " use '-skindir <dir>' to specify a directory that will be used to search\n"
778 " for emulator skins. each skin must be a subdirectory of <dir>. by default\n"
779 " the emulator will look in the 'skins' sub-directory of the system directory\n\n"
780
781 " the '-skin <name>' option is required when -skindir is used.\n"
782 );
783}
784
785static void
786help_skin(stralloc_t* out)
787{
788 PRINTF(
789 " use '-skin <skin>' to specify an emulator skin, each skin corresponds to\n"
790 " the visual appearance of a given device, including buttons and keyboards,\n"
791 " and is stored as subdirectory <skin> of the skin root directory\n"
792 " (see '-help-skindir')\n\n" );
793
794 PRINTF(
795 " note that <skin> can also be '<width>x<height>' (e.g. '320x480') to\n"
796 " specify an exact framebuffer size, without any visual ornaments.\n\n" );
797}
798
Siva Velusamy2abcdc42012-10-04 17:44:27 -0700799static void
800help_dynamic_skin(stralloc_t* out)
801{
802 PRINTF(
803 " use '-dynamic_skin' to dynamically generate a skin based on the settings\n"
804 " in the AVD. This option only has effect if the -skin WxH option is used\n"
805 " to specify the width and height of the framebuffer\n");
806}
807
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800808/* default network settings for emulator */
809#define DEFAULT_NETSPEED "full"
810#define DEFAULT_NETDELAY "none"
811
812static void
813help_shaper(stralloc_t* out)
814{
815 int n;
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800816 PRINTF(
817 " the Android emulator supports network throttling, i.e. slower network\n"
818 " bandwidth as well as higher connection latencies. this is done either through\n"
819 " skin configuration, or with '-netspeed <speed>' and '-netdelay <delay>'.\n\n"
820
821 " the format of -netspeed is one of the following (numbers are kbits/s):\n\n" );
822
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200823 for (n = 0;; ++n) {
824 const NetworkSpeed* android_netspeed = &android_netspeeds[n];
825 if (!android_netspeed->name) {
826 break;
827 }
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800828 PRINTF( " -netspeed %-12s %-15s (up: %.1f, down: %.1f)\n",
Vladimir Chtchetkine6b985d72011-01-20 18:02:35 -0800829 android_netspeed->name,
830 android_netspeed->display,
831 android_netspeed->upload/1000.,
832 android_netspeed->download/1000. );
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800833 }
834 PRINTF( "\n" );
835 PRINTF( " -netspeed %-12s %s", "<num>", "select both upload and download speed\n");
836 PRINTF( " -netspeed %-12s %s", "<up>:<down>", "select individual up and down speed\n");
837
838 PRINTF( "\n The format of -netdelay is one of the following (numbers are msec):\n\n" );
David 'Digit' Turnerd1744342014-07-11 14:03:25 +0200839 for (n = 0; ; ++n) {
840 const NetworkLatency* android_netdelay = &android_netdelays[n];
841 if (!android_netdelay->name) {
842 break;
843 }
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800844 PRINTF( " -netdelay %-10s %-15s (min %d, max %d)\n",
Vladimir Chtchetkine6b985d72011-01-20 18:02:35 -0800845 android_netdelay->name, android_netdelay->display,
846 android_netdelay->min_ms, android_netdelay->max_ms );
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800847 }
848 PRINTF( " -netdelay %-10s %s", "<num>", "select exact latency\n");
849 PRINTF( " -netdelay %-10s %s", "<min>:<max>", "select min and max latencies\n\n");
850
851 PRINTF( " the emulator uses the following defaults:\n\n" );
852 PRINTF( " Default network speed is '%s'\n", DEFAULT_NETSPEED);
853 PRINTF( " Default network latency is '%s'\n\n", DEFAULT_NETDELAY);
854}
855
856static void
857help_http_proxy(stralloc_t* out)
858{
859 PRINTF(
860 " the Android emulator allows you to redirect all TCP connections through\n"
861 " a HTTP/HTTPS proxy. this can be enabled by using the '-http-proxy <proxy>'\n"
862 " option, or by defining the 'http_proxy' environment variable.\n\n"
863
864 " <proxy> can be one of the following:\n\n"
865 " http://<server>:<port>\n"
866 " http://<username>:<password>@<server>:<port>\n\n"
867
868 " the 'http://' prefix can be omitted. If '-http-proxy <proxy>' is not used,\n"
869 " the 'http_proxy' environment variable is looked up and any value matching\n"
870 " the <proxy> format will be used automatically\n\n" );
871}
872
873static void
874help_report_console(stralloc_t* out)
875{
876 PRINTF(
877 " the '-report-console <socket>' option can be used to report the\n"
878 " automatically-assigned console port number to a remote third-party\n"
879 " before starting the emulation. <socket> must be in one of these\n"
880 " formats:\n\n"
881
882 " tcp:<port>[,server][,max=<seconds>]\n"
883 " unix:<path>[,server][,max=<seconds>]\n"
884 "\n"
885 " if the 'server' option is used, the emulator opens a server socket\n"
886 " and waits for an incoming connection to it. by default, it will instead\n"
887 " try to make a normal client connection to the socket, and, in case of\n"
888 " failure, will repeat this operation every second for 10 seconds.\n"
889 " the 'max=<seconds>' option can be used to modify the timeout\n\n"
890
891 " when the connection is established, the emulator sends its console port\n"
892 " number as text to the remote third-party, then closes the connection and\n"
893 " starts the emulation as usual. *any* failure in the process described here\n"
894 " will result in the emulator aborting immediately\n\n"
895
896 " as an example, here's a small Unix shell script that starts the emulator in\n"
897 " the background and waits for its port number with the help of the 'netcat'\n"
898 " utility:\n\n"
899
900 " MYPORT=5000\n"
901 " emulator -no-window -report-console tcp:$MYPORT &\n"
902 " CONSOLEPORT=`nc -l localhost $MYPORT`\n"
903 "\n"
904 );
905}
906
907static void
908help_dpi_device(stralloc_t* out)
909{
910 PRINTF(
911 " use '-dpi-device <dpi>' to specify the screen resolution of the emulated\n"
912 " device. <dpi> must be an integer between 72 and 1000. the default is taken\n"
913 " from the skin, if available, or uses the contant value %d (an average of\n"
914 " several prototypes used during Android development).\n\n", DEFAULT_DEVICE_DPI );
915
916 PRINTF(
917 " the device resolution can also used to rescale the emulator window with\n"
918 " the '-scale' option (see -help-scale)\n\n"
919 );
920}
921
922static void
923help_audio(stralloc_t* out)
924{
925 PRINTF(
926 " the '-audio <backend>' option allows you to select a specific backend\n"
927 " to be used to both play and record audio in the Android emulator.\n\n"
928
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800929 " use '-audio none' to disable audio completely.\n\n"
930 );
931}
932
933static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800934help_scale(stralloc_t* out)
935{
936 PRINTF(
937 " the '-scale <scale>' option is used to scale the emulator window to\n"
938 " something that better fits the physical dimensions of a real device. this\n"
939 " can be *very* useful to check that your UI isn't too small to be usable\n"
940 " on a real device.\n\n"
941
942 " there are three supported formats for <scale>:\n\n"
943
944 " * if <scale> is a real number (between 0.1 and 3.0) it is used as a\n"
945 " scaling factor for the emulator's window.\n\n"
946
947 " * if <scale> is an integer followed by the suffix 'dpi' (e.g. '110dpi'),\n"
948 " then it is interpreted as the resolution of your monitor screen. this\n"
949 " will be divided by the emulated device's resolution to get an absolute\n"
950 " scale. (see -help-dpi-device for details).\n\n"
951
952 " * finally, if <scale> is the keyword 'auto', the emulator tries to guess\n"
953 " your monitor's resolution and automatically adjusts its window\n"
954 " accordingly\n\n"
955
956 " NOTE: this process is *very* unreliable, depending on your OS, video\n"
957 " driver issues and other random system parameters\n\n"
958
959 " the emulator's scale can be changed anytime at runtime through the control\n"
960 " console. see the help for the 'window scale' command for details\n\n" );
961}
962
963static void
964help_trace(stralloc_t* out)
965{
966 PRINTF(
967 " use '-trace <name>' to start the emulator with runtime code profiling support\n"
968 " profiling itself will not be enabled unless you press F9 to activate it, or\n"
969 " the executed code turns it on programmatically.\n\n"
970
971 " trace information is stored in directory <name>, several files are created\n"
972 " there, that can later be used with the 'traceview' program that comes with\n"
973 " the Android SDK for analysis.\n\n"
974
975 " note that execution will be slightly slower when enabling code profiling,\n"
976 " this is a necessary requirement of the operations being performed to record\n"
977 " the execution trace. this slowdown should not affect your system until you\n"
978 " enable the profiling though...\n\n"
979 );
980}
981
982static void
983help_show_kernel(stralloc_t* out)
984{
985 PRINTF(
986 " use '-show-kernel' to redirect debug messages from the kernel to the current\n"
987 " terminal. this is useful to check that the boot process works correctly.\n\n"
988 );
989}
990
991static void
992help_shell(stralloc_t* out)
993{
994 PRINTF(
995 " use '-shell' to create a root shell console on the current terminal.\n"
996 " this is unlike the 'adb shell' command for the following reasons:\n\n"
997
998 " * this is a *root* shell that allows you to modify many parts of the system\n"
999 " * this works even if the ADB daemon in the emulated system is broken\n"
1000 " * pressing Ctrl-C will stop the emulator, instead of the shell.\n\n"
1001 " See also '-shell-serial'.\n\n" );
1002}
1003
1004static void
1005help_shell_serial(stralloc_t* out)
1006{
1007 PRINTF(
1008 " use '-shell-serial <device>' instead of '-shell' to open a root shell\n"
1009 " to the emulated system, while specifying an external communication\n"
1010 " channel / host device.\n\n"
1011
1012 " '-shell-serial stdio' is identical to '-shell', while you can use\n"
1013 " '-shell-serial tcp::4444,server,nowait' to talk to the shell over local\n"
1014 " TCP port 4444. '-shell-serial fdpair:3:6' would let a parent process\n"
1015 " talk to the shell using fds 3 and 6.\n\n"
1016
1017 " see -help-char-devices for a list of available <device> specifications.\n\n"
1018 " NOTE: you can have only one shell per emulator instance at the moment\n\n"
1019 );
1020}
1021
1022static void
1023help_logcat(stralloc_t* out)
1024{
1025 PRINTF(
1026 " use '-logcat <tags>' to redirect log messages from the emulated system to\n"
1027 " the current terminal. <tags> is a list of space/comma-separated log filters\n"
1028 " where each filter has the following format:\n\n"
1029
1030 " <componentName>:<logLevel>\n\n"
1031
1032 " where <componentName> is either '*' or the name of a given component,\n"
1033 " and <logLevel> is one of the following letters:\n\n"
1034
1035 " v verbose level\n"
1036 " d debug level\n"
1037 " i informative log level\n"
1038 " w warning log level\n"
1039 " e error log level\n"
1040 " s silent log level\n\n"
1041
1042 " for example, the following only displays messages from the 'GSM' component\n"
1043 " that are at least at the informative level:\n\n"
1044
1045 " -logcat '*:s GSM:i'\n\n"
1046
1047 " if '-logcat <tags>' is not used, the emulator looks for ANDROID_LOG_TAGS\n"
1048 " in the environment. if it is defined, its value must match the <tags>\n"
1049 " format and will be used to redirect log messages to the terminal.\n\n"
1050
1051 " note that this doesn't prevent you from redirecting the same, or other,\n"
1052 " log messages through the ADB or DDMS tools too.\n\n");
1053}
1054
1055static void
1056help_no_audio(stralloc_t* out)
1057{
1058 PRINTF(
1059 " use '-no-audio' to disable all audio support in the emulator. this may be\n"
1060 " unfortunately be necessary in some cases:\n\n"
1061
1062 " * at least two users have reported that their Windows machine rebooted\n"
1063 " instantly unless they used this option when starting the emulator.\n"
1064 " it is very likely that the problem comes from buggy audio drivers.\n\n"
1065
1066 " * on some Linux machines, the emulator might get stuck at startup with\n"
1067 " audio support enabled. this problem is hard to reproduce, but seems to\n"
1068 " be related too to flaky ALSA / audio driver support.\n\n"
1069
1070 " on Linux, another option is to try to change the default audio backend\n"
1071 " used by the emulator. you can do that by setting the QEMU_AUDIO_DRV\n"
1072 " environment variables to one of the following values:\n\n"
1073
1074 " alsa (use the ALSA backend)\n"
1075 " esd (use the EsounD backend)\n"
1076 " sdl (use the SDL audio backend, no audio input supported)\n"
1077 " oss (use the OSS backend)\n"
1078 " none (do not support audio)\n"
1079 "\n"
1080 " the very brave can also try to use distinct backends for audio input\n"
1081 " and audio outputs, this is possible by selecting one of the above values\n"
1082 " into the QEMU_AUDIO_OUT_DRV and QEMU_AUDIO_IN_DRV environment variables.\n\n"
1083 );
1084}
1085
1086static void
1087help_raw_keys(stralloc_t* out)
1088{
1089 PRINTF(
1090 " this option is deprecated because one can do the same using Ctrl-K\n"
1091 " at runtime (this keypress toggles between unicode/raw keyboard modes)\n\n"
1092
1093 " by default, the emulator tries to reverse-map the characters you type on\n"
1094 " your keyboard to device-specific key presses whenever possible. this is\n"
1095 " done to make the emulator usable with a non-QWERTY keyboard.\n\n"
1096
1097 " however, this also means that single keypresses like Shift or Alt are not\n"
1098 " passed to the emulated device. the '-raw-keys' option disables the reverse\n"
1099 " mapping. it should only be used when using a QWERTY keyboard on your machine\n"
1100
1101 " (should only be useful to Android system hackers, e.g. when implementing a\n"
1102 " new input method).\n\n"
1103 );
1104}
1105
1106static void
1107help_radio(stralloc_t* out)
1108{
1109 PRINTF(
1110 " use '-radio <device>' to redirect the GSM modem emulation to an external\n"
1111 " character device or program. this bypasses the emulator's internal modem\n"
1112 " and should only be used for testing.\n\n"
1113
1114 " see '-help-char-devices' for the format of <device>\n\n"
1115
1116 " the data exchanged with the external device/program are GSM AT commands\n\n"
1117
1118 " note that, when running in the emulator, the Android GSM stack only supports\n"
1119 " a *very* basic subset of the GSM protocol. trying to link the emulator to\n"
1120 " a real GSM modem is very likely to not work properly.\n\n"
1121 );
1122}
1123
1124
1125static void
1126help_port(stralloc_t* out)
1127{
1128 PRINTF(
1129 " at startup, the emulator tries to bind its control console at a free port\n"
1130 " starting from 5554, in increments of two (i.e. 5554, then 5556, 5558, etc..)\n"
1131 " this allows several emulator instances to run concurrently on the same\n"
1132 " machine, each one using a different console port number.\n\n"
1133
1134 " use '-port <port>' to force an emulator instance to use a given console port\n\n"
1135
1136 " note that <port> must be an *even* integer between 5554 and 5584 included.\n"
1137 " <port>+1 must also be free and will be reserved for ADB. if any of these\n"
1138 " ports is already used, the emulator will fail to start.\n\n" );
1139}
1140
1141static void
1142help_ports(stralloc_t* out)
1143{
1144 PRINTF(
1145 " the '-ports <consoleport>,<adbport>' option allows you to explicitely set\n"
1146 " the TCP ports used by the emulator to implement its control console and\n"
1147 " communicate with the ADB tool.\n\n"
1148
1149 " This is a very special option that should probably *not* be used by typical\n"
1150 " developers using the Android SDK (use '-port <port>' instead), because the\n"
1151 " corresponding instance is probably not going to be seen from adb/DDMS. Its\n"
1152 " purpose is to use the emulator in very specific network configurations.\n\n"
1153
1154 " <consoleport> is the TCP port used to bind the control console\n"
1155 " <adbport> is the TCP port used to bind the ADB local transport/tunnel.\n\n"
1156
1157 " If both ports aren't available on startup, the emulator will exit.\n\n");
1158}
1159
1160
1161static void
1162help_onion(stralloc_t* out)
1163{
1164 PRINTF(
1165 " use '-onion <file>' to specify a PNG image file that will be displayed on\n"
1166 " top of the emulated framebuffer with translucency. this can be useful to\n"
1167 " check that UI elements are correctly positioned with regards to a reference\n"
1168 " graphics specification.\n\n"
1169
1170 " the default translucency is 50%%, but you can use '-onion-alpha <%%age>' to\n"
1171 " select a different one, or even use keypresses at runtime to alter it\n"
1172 " (see -help-keys for details)\n\n"
1173
1174 " finally, the onion image can be rotated (see -help-onion-rotate)\n\n"
1175 );
1176}
1177
1178static void
1179help_onion_alpha(stralloc_t* out)
1180{
1181 PRINTF(
1182 " use '-onion-alpha <percent>' to change the translucency level of the onion\n"
1183 " image that is going to be displayed on top of the framebuffer (see also\n"
1184 " -help-onion). the default is 50%%.\n\n"
1185
1186 " <percent> must be an integer between 0 and 100.\n\n"
1187
1188 " you can also change the translucency dynamically (see -help-keys)\n\n"
1189 );
1190}
1191
1192static void
1193help_onion_rotation(stralloc_t* out)
1194{
1195 PRINTF(
1196 " use '-onion-rotation <rotation>' to change the rotation of the onion\n"
1197 " image loaded through '-onion <file>'. valid values for <rotation> are:\n\n"
1198
1199 " 0 no rotation\n"
1200 " 1 90 degrees clockwise\n"
1201 " 2 180 degrees\n"
1202 " 3 270 degrees clockwise\n\n"
1203 );
1204}
1205
1206
1207static void
1208help_timezone(stralloc_t* out)
1209{
1210 PRINTF(
1211 " by default, the emulator tries to detect your current timezone to report\n"
1212 " it to the emulated system. use the '-timezone <timezone>' option to choose\n"
1213 " a different timezone, or if the automatic detection doesn't work correctly.\n\n"
1214
1215 " VERY IMPORTANT NOTE:\n\n"
1216 " the <timezone> value must be in zoneinfo format, i.e. it should look like\n"
1217 " Area/Location or even Area/SubArea/Location. valid examples are:\n\n"
1218
1219 " America/Los_Angeles\n"
1220 " Europe/Paris\n\n"
1221
1222 " using a human-friendly abbreviation like 'PST' or 'CET' will not work, as\n"
1223 " well as using values that are not defined by the zoneinfo database.\n\n"
1224
1225 " NOTE: unfortunately, this will not work on M5 and older SDK releases\n\n"
1226 );
1227}
1228
1229
1230static void
1231help_dns_server(stralloc_t* out)
1232{
1233 PRINTF(
1234 " by default, the emulator tries to detect the DNS servers you're using and\n"
1235 " will setup special aliases in the emulated firewall network to allow the\n"
1236 " Android system to connect directly to them. use '-dns-server <servers>' to\n"
1237 " select a different list of DNS servers to be used.\n\n"
1238
1239 " <servers> must be a comma-separated list of up to 4 DNS server names or\n"
1240 " IP addresses.\n\n"
1241
1242 " NOTE: on M5 and older SDK releases, only the first server in the list will\n"
1243 " be used.\n\n"
1244 );
1245}
1246
1247
1248static void
1249help_cpu_delay(stralloc_t* out)
1250{
1251 PRINTF(
1252 " this option is purely experimental, probably doesn't work as you would\n"
1253 " expect, and may even disappear in a later emulator release.\n\n"
1254
1255 " use '-cpu-delay <delay>' to throttle CPU emulation. this may be useful\n"
1256 " to detect weird race conditions that only happen on 'lower' CPUs. note\n"
1257 " that <delay> is a unit-less integer that doesn't even scale linearly\n"
1258 " to observable slowdowns. use trial and error to find something that\n"
1259 " suits you, the 'correct' machine is very probably dependent on your\n"
1260 " host CPU and memory anyway...\n\n"
1261 );
1262}
1263
1264
1265static void
1266help_no_boot_anim(stralloc_t* out)
1267{
1268 PRINTF(
1269 " use '-no-boot-anim' to disable the boot animation (red bouncing ball) when\n"
1270 " starting the emulator. on slow machines, this can surprisingly speed up the\n"
1271 " boot sequence in tremendous ways.\n\n"
1272
1273 " NOTE: unfortunately, this will not work on M5 and older SDK releases\n\n"
1274 );
1275}
1276
1277
1278static void
1279help_gps(stralloc_t* out)
1280{
1281 PRINTF(
1282 " use '-gps <device>' to emulate an NMEA-compatible GPS unit connected to\n"
1283 " an external character device or socket. the format of <device> is the same\n"
1284 " than the one used for '-radio <device>' (see -help-char-devices for details)\n\n"
1285 );
1286}
1287
1288
1289static void
1290help_keyset(stralloc_t* out)
1291{
1292 char temp[256];
1293
1294 PRINTF(
1295 " use '-keyset <name>' to specify a different keyset file name to use when\n"
1296 " starting the emulator. a keyset file contains a list of key bindings used\n"
1297 " to control the emulator with the host keyboard.\n\n"
1298
1299 " by default, the emulator looks for the following file:\n\n"
1300 );
1301
1302 bufprint_config_file(temp, temp+sizeof(temp), KEYSET_FILE);
1303 PRINTF(
1304 " %s\n\n", temp );
1305
1306 bufprint_config_path(temp, temp+sizeof(temp));
1307 PRINTF(
1308 " however, if -keyset is used, then the emulator does the following:\n\n"
1309
1310 " - first, if <name> doesn't have an extension, then the '.keyset' suffix\n"
1311 " is appended to it (e.g. \"foo\" => \"foo.keyset\"),\n\n"
1312
1313 " - then, the emulator searches for a file named <name> in the following\n"
1314 " directories:\n\n"
1315
1316 " * the emulator configuration directory: %s\n"
1317 " * the 'keysets' subdirectory of <systemdir>, if any\n"
1318 " * the 'keysets' subdirectory of the program location, if any\n\n",
1319 temp );
1320
1321 PRINTF(
1322 " if no corresponding file is found, a default set of key bindings is used.\n\n"
1323 " use '-help-keys' to list the default key bindings.\n"
1324 " use '-help-keyset-file' to learn more about the format of keyset files.\n"
1325 "\n"
1326 );
1327}
1328
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001329#ifdef CONFIG_NAND_LIMITS
1330static void
1331help_nand_limits(stralloc_t* out)
1332{
1333 PRINTF(
1334 " use '-nand-limits <limits>' to enable a debugging feature that sends a\n"
1335 " signal to an external process once a read and/or write limit is achieved\n"
1336 " in the emulated system. the format of <limits> is the following:\n\n"
1337
1338 " pid=<number>,signal=<number>,[reads=<threshold>][,writes=<threshold>]\n\n"
1339
1340 " where 'pid' is the target process identifier, 'signal' the number of the\n"
1341 " target signal. the read and/or write threshold'reads' are a number optionally\n"
1342 " followed by a K, M or G suffix, corresponding to the number of bytes to be\n"
1343 " read or written before the signal is sent.\n\n"
1344 );
1345}
1346#endif /* CONFIG_NAND_LIMITS */
1347
1348static void
1349help_bootchart(stralloc_t *out)
1350{
1351 PRINTF(
1352 " some Android system images have a modified 'init' system that integrates\n"
1353 " a bootcharting facility (see http://www.bootchart.org/). You can pass a\n"
1354 " bootcharting period to the system with the following:\n\n"
1355
1356 " -bootchart <timeout>\n\n"
1357
1358 " where 'timeout' is a period expressed in seconds. Note that this won't do\n"
1359 " anything if your init doesn't have bootcharting activated.\n\n"
1360 );
1361}
1362
1363static void
1364help_tcpdump(stralloc_t *out)
1365{
1366 PRINTF(
1367 " use the -tcpdump <file> option to start capturing all network packets\n"
1368 " that are sent through the emulator's virtual Ethernet LAN. You can later\n"
1369 " use tools like WireShark to analyze the traffic and understand what\n"
1370 " really happens.\n\n"
1371
1372 " note that this captures all Ethernet packets, and is not limited to TCP\n"
1373 " connections.\n\n"
1374
1375 " you can also start/stop the packet capture dynamically through the console;\n"
1376 " see the 'network capture start' and 'network capture stop' commands for\n"
1377 " details.\n\n"
1378 );
1379}
1380
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001381static void
vchtchetkine9085a282009-09-14 15:29:20 -07001382help_charmap(stralloc_t *out)
1383{
1384 PRINTF(
1385 " use '-charmap <file>' to use key character map specified in that file.\n"
1386 " <file> must be a full path to a kcm file, containing desired character map.\n\n"
1387 );
1388}
1389
1390static void
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001391help_prop(stralloc_t *out)
1392{
1393 PRINTF(
1394 " use '-prop <name>=<value>' to set a boot-time system property.\n"
1395 " <name> must be a property name of at most %d characters, without any\n"
1396 " space in it, and <value> must be a string of at most %d characters.\n\n",
Vladimir Chtchetkine45d921a2010-07-08 11:05:31 -07001397 BOOT_PROPERTY_MAX_NAME, BOOT_PROPERTY_MAX_VALUE );
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001398
1399 PRINTF(
1400 " the corresponding system property will be set at boot time in the\n"
1401 " emulated system. This can be useful for debugging purposes.\n\n"
1402
1403 " note that you can use several -prop options to define more than one\n"
1404 " boot property.\n\n"
1405 );
1406}
1407
Dries Harnie40beab42010-05-15 17:04:47 +02001408static void
1409help_shared_net_id(stralloc_t* out)
1410{
1411 PRINTF(
1412 " Normally, Android instances running in the emulator cannot talk to each other\n"
1413 " directly, because each instance is behind a virtual router. However, sometimes\n"
1414 " it is necessary to test the behaviour of applications if they are directly\n"
1415 " exposed to the network.\n\n"
1416
1417 " This option instructs the emulator to join a virtual network shared with\n"
1418 " emulators also using this option. The number given is used to construct\n"
1419 " the IP address 10.1.2.<number>, which is bound to a second interface on\n"
1420 " the emulator. Each emulator must use a different number.\n\n"
1421 );
1422}
1423
David Turner9da935d2011-09-12 21:27:56 +02001424static void
1425help_gpu(stralloc_t* out)
1426{
1427 PRINTF(
Jesse Hall7e959f02012-04-18 15:40:12 -07001428 " Use -gpu <mode> to override the mode of hardware OpenGL ES emulation\n"
1429 " indicated by the AVD. Valid values for <mode> are:\n\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001430
David Turner9da935d2011-09-12 21:27:56 +02001431 " on -> enable GPU emulation\n"
1432 " off -> disable GPU emulation\n"
Jesse Hall7e959f02012-04-18 15:40:12 -07001433 " auto -> use the setting from the AVD\n"
David Turner9da935d2011-09-12 21:27:56 +02001434 " enabled -> same as 'on'\n"
1435 " disabled -> same as 'off'\n\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001436
David Turner9da935d2011-09-12 21:27:56 +02001437 " Note that enabling GPU emulation if the system image does not support it\n"
1438 " will prevent the proper display of the emulated framebuffer.\n\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001439
David Turner9da935d2011-09-12 21:27:56 +02001440 " You can always disable GPU emulation (i.e. '-gpu off'), and this will\n"
1441 " force the virtual device to use the slow software renderer instead.\n"
1442 " Note that OpenGLES 2.0 is _not_ supported by it.\n\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001443
Jesse Hall7e959f02012-04-18 15:40:12 -07001444 " The 'auto' mode is the default. In this mode, the hw.gpu.enabled setting\n"
1445 " in the AVD's hardware-qemu.ini file will determine whether GPU emulation\n"
1446 " is enabled.\n\n"
1447
1448 " Even if hardware GPU emulation is enabled, if the host-side OpenGL ES\n"
1449 " emulation library cannot be initialized, the emulator will run with GPU\n"
1450 " emulation disabled rather than failing to start.\n"
David Turner9da935d2011-09-12 21:27:56 +02001451 );
1452}
Dries Harnie40beab42010-05-15 17:04:47 +02001453
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001454static void
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001455help_camera_back(stralloc_t* out)
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001456{
1457 PRINTF(
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001458 " Use -camera-back <mode> to control emulation of a camera facing back.\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001459 " Valid values for <mode> are:\n\n"
1460
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001461 " emulated -> camera will be emulated using software ('fake') camera emulation\n"
1462 " webcam<N> -> camera will be emulated using a webcamera connected to the host\n"
1463 " none -> camera emulation will be disabled\n\n"
Vladimir Chtchetkineae0d8132011-09-13 10:48:02 -07001464 );
1465}
1466
Vladimir Chtchetkineb8dcaff2011-09-17 11:15:47 -07001467static void
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001468help_camera_front(stralloc_t* out)
Vladimir Chtchetkineb8dcaff2011-09-17 11:15:47 -07001469{
1470 PRINTF(
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001471 " Use -camera-front <mode> to control emulation of a camera facing front.\n"
1472 " Valid values for <mode> are:\n\n"
Vladimir Chtchetkineb8dcaff2011-09-17 11:15:47 -07001473
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001474 " emulated -> camera will be emulated using software ('fake') camera emulation\n"
1475 " webcam<N> -> camera will be emulated using a webcamera connected to the host\n"
1476 " none -> camera emulation will be disabled\n\n"
1477 );
1478}
Vladimir Chtchetkineb8dcaff2011-09-17 11:15:47 -07001479
Vladimir Chtchetkine7485c292012-03-19 11:35:29 -07001480static void
1481help_webcam_list(stralloc_t* out)
1482{
1483 PRINTF(
1484 " Use -webcam-list to list web cameras available for emulation.\n\n"
Vladimir Chtchetkineb8dcaff2011-09-17 11:15:47 -07001485 );
1486}
1487
Vladimir Chtchetkine8dd31e82012-02-15 17:16:04 -08001488static void
1489help_screen(stralloc_t* out)
1490{
1491 PRINTF(
1492 " Use -screen <mode> to set the emulated screen mode.\n"
1493 " Valid values for <mode> are:\n\n"
1494
1495 " touch -> emulate a touch screen\n"
1496 " multi-touch -> emulate a multi-touch screen\n"
Vladimir Chtchetkine863d1012012-03-16 12:25:23 -07001497 " no-touch -> disable touch and multi-touch screen emulation\n\n"
Vladimir Chtchetkine8dd31e82012-02-15 17:16:04 -08001498
1499 " Default mode for screen emulation is 'touch'.\n\n"
1500 );
1501}
1502
Andrew Hsiehddd4ef72012-03-22 00:39:08 +08001503static void
Nick Kralevich185231a2013-10-07 13:54:31 -07001504help_selinux(stralloc_t* out)
1505{
1506 PRINTF(
1507 " Use -selinux to control the SELinux enforcement mode.\n"
1508 " By default, SELinux is in enforcing mode. Other modes available are:\n"
1509 " -selinux permissive -> Load the SELinux policy, but do not enforce it.\n"
1510 " Policy violations are logged, but not rejected.\n"
1511 " -selinux disabled -> Disable kernel support for SELinux.\n"
1512 );
1513}
1514
1515static void
Andrew Hsiehddd4ef72012-03-22 00:39:08 +08001516help_force_32bit(stralloc_t* out)
1517{
1518 PRINTF(
1519 " Use -force-32bit to use 32-bit emulator on 64-bit platforms\n\n"
1520
1521 );
1522}
1523
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001524#define help_no_skin NULL
1525#define help_netspeed help_shaper
1526#define help_netdelay help_shaper
1527#define help_netfast help_shaper
1528
1529#define help_noaudio NULL
1530#define help_noskin NULL
1531#define help_nocache NULL
1532#define help_no_jni NULL
1533#define help_nojni NULL
1534#define help_initdata NULL
1535#define help_no_window NULL
1536#define help_version NULL
1537#define help_memory NULL
The Android Open Source Projectb3ee93a2009-03-13 13:04:21 -07001538#define help_partition_size NULL
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001539
1540typedef struct {
1541 const char* name;
1542 const char* template;
1543 const char* descr;
1544 void (*func)(stralloc_t*);
1545} OptionHelp;
1546
1547static const OptionHelp option_help[] = {
1548#define OPT_FLAG(_name,_descr) { STRINGIFY(_name), NULL, _descr, help_##_name },
1549#define OPT_PARAM(_name,_template,_descr) { STRINGIFY(_name), _template, _descr, help_##_name },
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001550#define OPT_LIST OPT_PARAM
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001551#include "android/cmdline-options.h"
1552 { NULL, NULL, NULL, NULL }
1553};
1554
1555typedef struct {
1556 const char* name;
1557 const char* desc;
1558 void (*func)(stralloc_t*);
1559} TopicHelp;
1560
1561
1562static const TopicHelp topic_help[] = {
1563 { "disk-images", "about disk images", help_disk_images },
1564 { "keys", "supported key bindings", help_keys },
1565 { "debug-tags", "debug tags for -debug <tags>", help_debug_tags },
1566 { "char-devices", "character <device> specification", help_char_devices },
1567 { "environment", "environment variables", help_environment },
1568 { "keyset-file", "key bindings configuration file", help_keyset_file },
1569 { "virtual-device", "virtual device management", help_virtual_device },
1570 { "sdk-images", "about disk images when using the SDK", help_sdk_images },
1571 { "build-images", "about disk images when building Android", help_build_images },
1572 { NULL, NULL, NULL }
1573};
1574
1575int
1576android_help_for_option( const char* option, stralloc_t* out )
1577{
1578 OptionHelp const* oo;
1579 char temp[32];
1580
1581 /* the names in the option_help table use underscore instead
1582 * of dashes, so create a tranlated copy of the option name
1583 * before scanning the table for matches
1584 */
1585 buffer_translate_char( temp, sizeof temp, option, '-', '_' );
1586
1587 for ( oo = option_help; oo->name != NULL; oo++ ) {
1588 if ( !strcmp(oo->name, temp) ) {
1589 if (oo->func)
1590 oo->func(out);
1591 else
1592 stralloc_add_str(out, oo->descr);
1593 return 0;
1594 }
1595 }
1596 return -1;
1597}
1598
1599
1600int
1601android_help_for_topic( const char* topic, stralloc_t* out )
1602{
1603 const TopicHelp* tt;
1604
1605 for ( tt = topic_help; tt->name != NULL; tt++ ) {
1606 if ( !strcmp(tt->name, topic) ) {
1607 tt->func(out);
1608 return 0;
1609 }
1610 }
1611 return -1;
1612}
1613
1614
Vladimir Chtchetkine5389aa12010-02-16 10:38:35 -08001615extern void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001616android_help_list_options( stralloc_t* out )
1617{
1618 const OptionHelp* oo;
1619 const TopicHelp* tt;
1620 int maxwidth = 0;
1621
1622 for ( oo = option_help; oo->name != NULL; oo++ ) {
1623 int width = strlen(oo->name);
1624 if (oo->template != NULL)
1625 width += strlen(oo->template);
1626 if (width > maxwidth)
1627 maxwidth = width;
1628 }
1629
1630 for (oo = option_help; oo->name != NULL; oo++) {
1631 char temp[32];
1632 /* the names in the option_help table use underscores instead
1633 * of dashes, so create a translated copy of the option's name
1634 */
1635 buffer_translate_char(temp, sizeof temp, oo->name, '_', '-');
1636
1637 stralloc_add_format( out, " -%s %-*s %s\n",
1638 temp,
1639 (int)(maxwidth - strlen(oo->name)),
1640 oo->template ? oo->template : "",
1641 oo->descr );
1642 }
1643
1644 PRINTF( "\n" );
1645 PRINTF( " %-*s %s\n", maxwidth, "-qemu args...", "pass arguments to qemu");
1646 PRINTF( " %-*s %s\n", maxwidth, "-qemu -h", "display qemu help");
1647 PRINTF( "\n" );
1648 PRINTF( " %-*s %s\n", maxwidth, "-verbose", "same as '-debug-init'");
1649 PRINTF( " %-*s %s\n", maxwidth, "-debug <tags>", "enable/disable debug messages");
1650 PRINTF( " %-*s %s\n", maxwidth, "-debug-<tag>", "enable specific debug messages");
1651 PRINTF( " %-*s %s\n", maxwidth, "-debug-no-<tag>","disable specific debug messages");
1652 PRINTF( "\n" );
1653 PRINTF( " %-*s %s\n", maxwidth, "-help", "print this help");
1654 PRINTF( " %-*s %s\n", maxwidth, "-help-<option>", "print option-specific help");
1655 PRINTF( "\n" );
1656
1657 for (tt = topic_help; tt->name != NULL; tt += 1) {
1658 char help[32];
1659 snprintf(help, sizeof(help), "-help-%s", tt->name);
1660 PRINTF( " %-*s %s\n", maxwidth, help, tt->desc );
1661 }
1662 PRINTF( " %-*s %s\n", maxwidth, "-help-all", "prints all help content");
1663 PRINTF( "\n");
1664}
1665
1666
1667void
1668android_help_main( stralloc_t* out )
1669{
1670 stralloc_add_str(out, "Android Emulator usage: emulator [options] [-qemu args]\n");
1671 stralloc_add_str(out, " options:\n" );
1672
1673 android_help_list_options(out);
1674
1675 /*printf( "%.*s", out->n, out->s );*/
1676}
1677
1678
1679void
1680android_help_all( stralloc_t* out )
1681{
1682 const OptionHelp* oo;
1683 const TopicHelp* tt;
1684
1685 for (oo = option_help; oo->name != NULL; oo++) {
1686 PRINTF( "========= help for option -%s:\n\n", oo->name );
1687 android_help_for_option( oo->name, out );
1688 }
1689
1690 for (tt = topic_help; tt->name != NULL; tt++) {
1691 PRINTF( "========= help for -help-%s\n\n", tt->name );
1692 android_help_for_topic( tt->name, out );
1693 }
1694 PRINTF( "========= top-level help\n\n" );
1695 android_help_main(out);
1696}