blob: 7df6704d9189455477730fe2d64e27463c67617a [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"
7#include "android/skin/keyset.h"
8#include "android/android.h"
9#include <stdint.h>
10#include "audio/audio.h"
11#include <string.h>
12#include <stdlib.h>
Vladimir Chtchetkine777eb682011-01-26 11:19:19 -080013#include "android/protocol/core-commands-api.h"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -080014
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"
117 " in <build-root>/prebuilt/android-arm/kernel/.\n\n"
118
Xavier Ducrohet5bc61822009-11-20 12:24:17 -0800119 " Skins will be looked in <build-root>/sdk/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#if CONFIG_ANDROID_SNAPSHOTS
170 " snapshots.img an *optional* state snapshots image\n\n"
171#endif
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800172
173 " If you use a virtual device, its content directory should store\n"
174 " all writable images, and read-only ones will be found from the\n"
175 " corresponding platform/add-on directories. See -help-sdk-images\n"
176 " for more details.\n\n"
177
178 " If you are building from the Android build system, you should\n"
179 " have ANDROID_PRODUCT_OUT defined in your environment, and the\n"
180 " emulator shall be able to pick-up the right image files automatically.\n"
181 " See -help-build-images for more details.\n\n"
182
183 " If you're neither using the SDK or the Android build system, you\n"
184 " can still run the emulator by explicitely providing the paths to\n"
185 " *all* required disk images through a combination of the following\n"
186 " options: -sysdir, -datadir, -kernel, -ramdisk, -system, -data, -cache\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100187#if CONFIG_ANDROID_SNAPSHOTS
188 " -sdcard and -snapstorage.\n\n"
189#else
190 " and -sdcard.\n\n"
191#endif
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800192
193 " The actual logic being that the emulator should be able to find all\n"
194 " images from the options you give it.\n\n"
195
196 " For more detail, see the corresponding -help-<option> entry.\n\n"
197
198 " Other related options are:\n\n"
199
Ot ten Thije353b3b12010-10-05 17:53:30 +0100200 " -init-data Specify an alternative *initial* user data image\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800201
Ot ten Thije353b3b12010-10-05 17:53:30 +0100202 " -wipe-data Copy the content of the *initial* user data image\n"
203" (userdata.img) into the writable one (userdata-qemu.img)\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800204
Ot ten Thije353b3b12010-10-05 17:53:30 +0100205 " -no-cache do not use a cache partition, even if one is\n"
206 " available.\n\n"
207
208#if CONFIG_ANDROID_SNAPSHOTS
209 " -no-snapstorage do not use a state snapshot image, even if one is\n"
210 " available.\n\n"
211#endif
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800212 ,
213 datadir );
214}
215
216static void
217help_keys(stralloc_t* out)
218{
219 int pass, maxw = 0;
220
221 stralloc_add_str( out, " When running the emulator, use the following keypresses:\n\n");
222
223 if (!android_keyset)
224 android_keyset = skin_keyset_new_from_text( skin_keyset_get_default() );
225
226 for (pass = 0; pass < 2; pass++) {
227 SkinKeyCommand cmd;
228
229 for (cmd = SKIN_KEY_COMMAND_NONE+1; cmd < SKIN_KEY_COMMAND_MAX; cmd++)
230 {
231 SkinKeyBinding bindings[ SKIN_KEY_COMMAND_MAX_BINDINGS ];
232 int n, count, len;
233 char temp[32], *p = temp, *end = p + sizeof(temp);
234
235 count = skin_keyset_get_bindings( android_keyset, cmd, bindings );
236 if (count <= 0)
237 continue;
238
239 for (n = 0; n < count; n++) {
240 p = bufprint(p, end, "%s%s", (n == 0) ? "" : ", ",
241 skin_key_symmod_to_str( bindings[n].sym, bindings[n].mod ) );
242 }
243
244 if (pass == 0) {
245 len = strlen(temp);
246 if (len > maxw)
247 maxw = len;
248 } else {
249 PRINTF( " %-*s %s\n", maxw, temp, skin_key_command_description(cmd) );
250 }
251 }
252 }
253 PRINTF( "\n" );
254 PRINTF( " note that NumLock must be deactivated for keypad keys to work\n\n" );
255}
256
257
258static void
259help_environment(stralloc_t* out)
260{
261 PRINTF(
262 " The Android emulator looks at various environment variables when it starts:\n\n"
263
264 " If ANDROID_LOG_TAGS is defined, it will be used as in '-logcat <tags>'.\n\n"
265
266 " If 'http_proxy' is defined, it will be used as in '-http-proxy <proxy>'.\n\n"
267
268 " If ANDROID_VERBOSE is defined, it can contain a comma-separated list of\n"
269 " verbose items. for example:\n\n"
270
271 " ANDROID_VERBOSE=socket,radio\n\n"
272
273 " is equivalent to using the '-verbose -verbose-socket -verbose-radio'\n"
274 " options together. unsupported items will be ignored.\n\n"
275
276 " If ANDROID_LOG_TAGS is defined, it will be used as in '-logcat <tags>'.\n\n"
277
278 " If ANDROID_SDK_HOME is defined, it indicates the path of the '.android'\n"
279 " directory which contains the SDK user data (Android Virtual Devices,\n"
280 " DDMS preferences, key stores, etc.).\n\n"
281
282 " If ANDROID_SDK_ROOT is defined, it indicates the path of the SDK\n"
283 " installation directory.\n\n"
284
285 );
286}
287
288
289static void
290help_keyset_file(stralloc_t* out)
291{
292 int n, count;
293 const char** strings;
294 char temp[MAX_PATH];
295
296 PRINTF(
297 " on startup, the emulator looks for 'keyset' file that contains the\n"
298 " configuration of key-bindings to use. the default location on this\n"
299 " system is:\n\n"
300 );
301
302 bufprint_config_file( temp, temp+sizeof(temp), KEYSET_FILE );
303 PRINTF( " %s\n\n", temp );
304
305 PRINTF(
306 " if the file doesn't exist, the emulator writes one containing factory\n"
307 " defaults. you are then free to modify it to suit specific needs.\n\n"
308 " this file shall contain a list of text lines in the following format:\n\n"
309
310 " <command> [<modifiers>]<key>\n\n"
311
312 " where <command> is an emulator-specific command name, i.e. one of:\n\n"
313 );
314
315 count = SKIN_KEY_COMMAND_MAX-1;
316 strings = calloc( count, sizeof(char*) );
317 for (n = 0; n < count; n++)
318 strings[n] = skin_key_command_to_str(n+1);
319
320 stralloc_tabular( out, strings, count, " ", 80-8 );
321 free(strings);
322
323 PRINTF(
324 "\n"
325 " <modifers> is an optional list of <modifier> elements (without separators)\n"
326 " which can be one of:\n\n"
327
328 " Ctrl- Left Control Key\n"
329 " Shift- Left Shift Key\n"
330 " Alt- Left Alt key\n"
331 " RCtrl- Right Control Key\n"
332 " RShift- Right Shift Key\n"
333 " RAlt- Right Alt key (a.k.a AltGr)\n"
334 "\n"
335 " finally <key> is a QWERTY-specific keyboard symbol which can be one of:\n\n"
336 );
337 count = skin_keysym_str_count();
338 strings = calloc( count, sizeof(char*) );
339 for (n = 0; n < count; n++)
340 strings[n] = skin_keysym_str(n);
341
342 stralloc_tabular( out, strings, count, " ", 80-8 );
343 free(strings);
344
345 PRINTF(
346 "\n"
347 " case is not significant, and a single command can be associated to up\n"
348 " to %d different keys. to bind a command to multiple keys, use commas to\n"
349 " separate them. here are some examples:\n\n",
350 SKIN_KEY_COMMAND_MAX_BINDINGS );
351
352 PRINTF(
353 " TOGGLE_NETWORK F8 # toggle the network on/off\n"
354 " CHANGE_LAYOUT_PREV Keypad_7,Ctrl-J # switch to a previous skin layout\n"
355 "\n"
356 );
357}
358
359
360static void
361help_debug_tags(stralloc_t* out)
362{
363 int n;
364
365#define _VERBOSE_TAG(x,y) { #x, VERBOSE_##x, y },
366 static const struct { const char* name; int flag; const char* text; }
367 verbose_options[] = {
368 VERBOSE_TAG_LIST
369 { 0, 0, 0 }
370 };
371#undef _VERBOSE_TAG
372
373 PRINTF(
374 " the '-debug <tags>' option can be used to enable or disable debug\n"
375 " messages from specific parts of the emulator. <tags> must be a list\n"
376 " (separated by space/comma/column) of <component> names, which can be one of:\n\n"
377 );
378
379 for (n = 0; n < VERBOSE_MAX; n++)
380 PRINTF( " %-12s %s\n", verbose_options[n].name, verbose_options[n].text );
381 PRINTF( " %-12s %s\n", "all", "all components together\n" );
382
383 PRINTF(
384 "\n"
385 " each <component> can be prefixed with a single '-' to indicate the disabling\n"
386 " of its debug messages. for example:\n\n"
387
388 " -debug all,-socket,-keys\n\n"
389
390 " enables all debug messages, except the ones related to network sockets\n"
391 " and key bindings/presses\n\n"
392 );
393}
394
395static void
396help_char_devices(stralloc_t* out)
397{
398 PRINTF(
399 " various emulation options take a <device> specification that can be used to\n"
400 " specify something to hook to an emulated device or communication channel.\n"
401 " here is the list of supported <device> specifications:\n\n"
402
403 " stdio\n"
404 " standard input/output. this may be subject to character\n"
405 " translation (e.g. LN <=> CR/LF)\n\n"
406
407 " COM<n> [Windows only]\n"
408 " where <n> is a digit. host serial communication port.\n\n"
409
410 " pipe:<filename>\n"
411 " named pipe <filename>\n\n"
412
413 " file:<filename>\n"
414 " write output to <filename>, no input can be read\n\n"
415
416 " pty [Linux only]\n"
417 " pseudo TTY (a new PTY is automatically allocated)\n\n"
418
419 " /dev/<file> [Unix only]\n"
420 " host char device file, e.g. /dev/ttyS0. may require root access\n\n"
421
422 " /dev/parport<N> [Linux only]\n"
423 " use host parallel port. may require root access\n\n"
424
425 " unix:<path>[,server][,nowait]] [Unix only]\n"
426 " use a Unix domain socket. if you use the 'server' option, then\n"
427 " the emulator will create the socket and wait for a client to\n"
428 " connect before continuing, unless you also use 'nowait'\n\n"
429
430 " tcp:[<host>]:<port>[,server][,nowait][,nodelay]\n"
431 " use a TCP socket. 'host' is set to localhost by default. if you\n"
432 " use the 'server' option will bind the port and wait for a client\n"
433 " to connect before continuing, unless you also use 'nowait'. the\n"
434 " 'nodelay' option disables the TCP Nagle algorithm\n\n"
435
436 " telnet:[<host>]:<port>[,server][,nowait][,nodelay]\n"
437 " similar to 'tcp:' but uses the telnet protocol instead of raw TCP\n\n"
438
439 " udp:[<remote_host>]:<remote_port>[@[<src_ip>]:<src_port>]\n"
440 " send output to a remote UDP server. if 'remote_host' is no\n"
441 " specified it will default to '0.0.0.0'. you can also receive input\n"
442 " through UDP by specifying a source address after the optional '@'.\n\n"
443
444 " fdpair:<fd1>,<fd2> [Unix only]\n"
445 " redirection input and output to a pair of pre-opened file\n"
446 " descriptors. this is mostly useful for scripts and other\n"
447 " programmatic launches of the emulator.\n\n"
448
449 " none\n"
450 " no device connected\n\n"
451
452 " null\n"
453 " the null device (a.k.a /dev/null on Unix, or NUL on Win32)\n\n"
454
455 " NOTE: these correspond to the <device> parameter of the QEMU -serial option\n"
456 " as described on http://bellard.org/qemu/qemu-doc.html#SEC10\n\n"
457 );
458}
459
460static void
461help_avd(stralloc_t* out)
462{
463 PRINTF(
David Turnerb58c44e2009-03-25 02:42:45 -0700464 " use '-avd <name>' to start the emulator program with a given Android\n"
465 " Virtual Device (a.k.a. AVD), where <name> must correspond to the name\n"
466 " of one of the existing AVDs available on your host machine.\n\n"
467
468 "See -help-virtual-device to learn how to create/list/manage AVDs.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800469
470 " As a special convenience, using '@<name>' is equivalent to using\n"
471 " '-avd <name>'.\n\n"
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800472 );
473}
474
475static void
476help_sysdir(stralloc_t* out)
477{
478 char systemdir[MAX_PATH];
479 char *p = systemdir, *end = p + sizeof(systemdir);
480
481 p = bufprint_app_dir( p, end );
482 p = bufprint( p, end, PATH_SEP "lib" PATH_SEP "images" );
483
484 PRINTF(
485 " use '-sysdir <dir>' to specify a directory where system read-only\n"
486 " image files will be searched. on this system, the default directory is:\n\n"
487 " %s\n\n", systemdir );
488
489 PRINTF(
490 " see '-help-disk-images' for more information about disk image files\n\n" );
491}
492
493static void
494help_datadir(stralloc_t* out)
495{
496 char datadir[MAX_PATH];
497
498 bufprint_config_path(datadir, datadir + sizeof(datadir));
499
500 PRINTF(
501 " use '-datadir <dir>' to specify a directory where writable image files\n"
502 " will be searched. on this system, the default directory is:\n\n"
503 " %s\n\n", datadir );
504
505 PRINTF(
506 " see '-help-disk-images' for more information about disk image files\n\n" );
507}
508
509static void
510help_kernel(stralloc_t* out)
511{
512 PRINTF(
513 " use '-kernel <file>' to specify a Linux kernel image to be run.\n"
514 " the default image is 'kernel-qemu' from the system directory.\n\n"
515
516 " you can use '-debug-kernel' to see debug messages from the kernel\n"
517 " to the terminal\n\n"
518
519 " see '-help-disk-images' for more information about disk image files\n\n"
520 );
521}
522
523static void
524help_ramdisk(stralloc_t* out)
525{
526 PRINTF(
527 " use '-ramdisk <file>' to specify a Linux ramdisk boot image to be run in\n"
528 " the emulator. the default image is 'ramdisk.img' from the system directory.\n\n"
529
530 " see '-help-disk-images' for more information about disk image files\n\n"
531 );
532}
533
534static void
535help_system(stralloc_t* out)
536{
537 PRINTF(
538 " use '-system <file>' to specify the intial system image that will be loaded.\n"
539 " the default image is 'system.img' from the system directory.\n\n"
540
541 " NOTE: In previous releases of the Android SDK, this option was named '-image'.\n"
542 " And using '-system <path>' was equivalent to using '-sysdir <path>' now.\n\n"
543
544 " see '-help-disk-images' for more information about disk image files\n\n"
545 );
546}
547
548static void
549help_image(stralloc_t* out)
550{
551 PRINTF(
552 " This option is obsolete, you should use '-system <file>' instead to point\n"
553 " to the initial system image.\n\n"
554
555 " see '-help-disk-images' for more information about disk image files\n\n"
556 );
557}
558
559static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800560help_data(stralloc_t* out)
561{
562 PRINTF(
563 " use '-data <file>' to specify a different /data partition image file.\n\n"
564
565 " see '-help-disk-images' for more information about disk image files\n\n"
566 );
567}
568
569static void
570help_wipe_data(stralloc_t* out)
571{
572 PRINTF(
573 " use '-wipe-data' to reset your /data partition image to its factory\n"
574 " defaults. this removes all installed applications and settings.\n\n"
575
576 " see '-help-disk-images' for more information about disk image files\n\n"
577 );
578}
579
580static void
581help_cache(stralloc_t* out)
582{
583 PRINTF(
584 " use '-cache <file>' to specify a /cache partition image. if <file> does\n"
585 " not exist, it will be created empty. by default, the cache partition is\n"
586 " backed by a temporary file that is deleted when the emulator exits.\n"
587 " using the -cache option allows it to be persistent.\n\n"
588
589 " the '-no-cache' option can be used to disable the cache partition.\n\n"
590
591 " see '-help-disk-images' for more information about disk image files\n\n"
592 );
593}
594
595static void
596help_no_cache(stralloc_t* out)
597{
598 PRINTF(
599 " use '-no-cache' to disable the cache partition in the emulated system.\n"
600 " the cache partition is optional, but when available, is used by the browser\n"
601 " to cache web pages and images\n\n"
602
603 " see '-help-disk-images' for more information about disk image files\n\n"
604 );
605}
606
607static void
608help_sdcard(stralloc_t* out)
609{
610 PRINTF(
611 " use '-sdcard <file>' to specify a SD Card image file that will be attached\n"
612 " to the emulator. By default, the 'sdcard.img' file is searched in the data\n"
613 " directory.\n\n"
614
615 " if the file does not exist, the emulator will still start, but without an\n"
616 " attached SD Card.\n\n"
617
618 " see '-help-disk-images' for more information about disk image files\n\n"
619 );
620}
621
Ot ten Thije353b3b12010-10-05 17:53:30 +0100622#if CONFIG_ANDROID_SNAPSHOTS
623static void
624help_snapstorage(stralloc_t* out)
625{
626 PRINTF(
627 " Use '-snapstorage <file>' to specify a repository file for snapshots.\n"
628 " All snapshots made during execution will be saved in this file, and only\n"
629 " snapshots in this file can be restored during the emulator run.\n\n"
630
631 " If the option is not specified, it defaults to 'snapshots.img' in the\n"
632 " data directory. If the specified file does not exist, the emulator will\n"
633 " start, but without support for saving or loading state snapshots.\n\n"
634
635 " see '-help-disk-images' for more information about disk image files\n"
636 " see '-help-snapshot' for more information about snapshots\n\n"
637 );
638}
639
640static void
641help_no_snapstorage(stralloc_t* out)
642{
643 PRINTF(
644 " This starts the emulator without mounting a file to store or load state\n"
645 " snapshots, forcing a full boot and disabling state snapshot functionality.\n\n"
646 ""
647 " This command overrides the configuration specified by the parameters\n"
648 " '-snapstorage' and '-snapshot'. A warning will be raised if either\n"
649 " of those parameters was specified anyway.\n\n"
650 );
651 }
652
653static void
654help_snapshot(stralloc_t* out)
655{
656 PRINTF(
657 " Rather than executing a full boot sequence, the Android emulator can\n"
658 " resume execution from an earlier state snapshot (which is usually\n"
659 " significantly faster). When the parameter '-snapshot <name>' is given,\n"
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000660 " the emulator loads the snapshot of that name from the snapshot image,\n"
661 " and saves it back under the same name on exit.\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100662
663 " If the option is not specified, it defaults to 'default-boot'. If the\n"
664 " specified snapshot does not exist, the emulator will perform a full boot\n"
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000665 " sequence instead, but will still save.\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100666
667 " WARNING: In the process of loading, all contents of the system, userdata\n"
668 " and SD card images will be OVERWRITTEN with the contents they\n"
669 " held when the snapshot was made. Unless saved in a different\n"
670 " snapshot, any changes since will be lost!\n\n"
671
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000672 " If you want to create a snapshot manually, connect to the emulator console:\n\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100673
674 " telnet localhost <port>\n\n"
675
676 " Then execute the command 'avd snapshot save <name>'. See '-help-port' for\n"
677 " information on obtaining <port>.\n\n"
678 );
679}
680
681static void
682help_no_snapshot(stralloc_t* out)
683{
684 PRINTF(
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000685 " This inhibits both the autoload and autosave operations, forcing\n"
686 " emulator to perform a full boot sequence and losing state on close.\n"
687 " It overrides the '-snapshot' parameter.\n"
Ot ten Thije353b3b12010-10-05 17:53:30 +0100688 " If '-snapshot' was specified anyway, a warning is raised.\n\n"
689 );
690}
691
Ot ten Thijeae835ac2010-10-18 13:37:37 +0100692static void
Tim Baverstock53d8a5c2010-12-02 14:21:39 +0000693help_no_snapshot_load(stralloc_t* out)
694{
695 PRINTF(
696 " Prevents the emulator from loading the AVD's state from the snapshot\n"
697 " storage on start.\n\n"
698 );
699}
700
701static void
Tim Baverstock24204cc2010-11-25 11:37:43 +0000702help_no_snapshot_save(stralloc_t* out)
703{
704 PRINTF(
705 " Prevents the emulator from saving the AVD's state to the snapshot\n"
706 " storage on exit, meaning that all changes will be lost.\n\n"
707 );
708}
709
710static void
Tim Baverstock622b8f42010-12-07 11:36:59 +0000711help_no_snapshot_update_time(stralloc_t* out)
712{
713 PRINTF(
714 " Prevent the emulator from sending an unsolicited time update\n"
715 " in response to the first signal strength query after loadvm,\n"
716 " to avoid a sudden time jump that might upset testing. (Signal\n"
717 " strength is queried approximately every 15 seconds)\n\n"
718 );
719}
720
721static void
Ot ten Thijeae835ac2010-10-18 13:37:37 +0100722help_snapshot_list(stralloc_t* out)
723{
724 PRINTF(
725 " This prints a table of snapshots that are stored in the snapshot storage\n"
726 " file that the emulator was started with, then exits. Values from the 'ID'\n"
727 " and 'TAG' columns can be used as arguments for the '-snapshot' parameter.\n\n"
728
729 " If '-snapstorage <file>' was specified as well, this command prints a "
730 " table of the snapshots stored in <file>.\n\n"
731
732 " See '-help-snapshot' for more information on snapshots.\n\n"
733 );
734}
735
Ot ten Thije353b3b12010-10-05 17:53:30 +0100736#endif
737
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800738static void
739help_skindir(stralloc_t* out)
740{
741 PRINTF(
742 " use '-skindir <dir>' to specify a directory that will be used to search\n"
743 " for emulator skins. each skin must be a subdirectory of <dir>. by default\n"
744 " the emulator will look in the 'skins' sub-directory of the system directory\n\n"
745
746 " the '-skin <name>' option is required when -skindir is used.\n"
747 );
748}
749
750static void
751help_skin(stralloc_t* out)
752{
753 PRINTF(
754 " use '-skin <skin>' to specify an emulator skin, each skin corresponds to\n"
755 " the visual appearance of a given device, including buttons and keyboards,\n"
756 " and is stored as subdirectory <skin> of the skin root directory\n"
757 " (see '-help-skindir')\n\n" );
758
759 PRINTF(
760 " note that <skin> can also be '<width>x<height>' (e.g. '320x480') to\n"
761 " specify an exact framebuffer size, without any visual ornaments.\n\n" );
762}
763
764/* default network settings for emulator */
765#define DEFAULT_NETSPEED "full"
766#define DEFAULT_NETDELAY "none"
767
768static void
769help_shaper(stralloc_t* out)
770{
771 int n;
Vladimir Chtchetkine6b985d72011-01-20 18:02:35 -0800772 NetworkSpeed* android_netspeed;
773 NetworkLatency* android_netdelay;
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800774 PRINTF(
775 " the Android emulator supports network throttling, i.e. slower network\n"
776 " bandwidth as well as higher connection latencies. this is done either through\n"
777 " skin configuration, or with '-netspeed <speed>' and '-netdelay <delay>'.\n\n"
778
779 " the format of -netspeed is one of the following (numbers are kbits/s):\n\n" );
780
Vladimir Chtchetkine777eb682011-01-26 11:19:19 -0800781 for (n = 0; !corecmd_get_netspeed(n, &android_netspeed); n++) {
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800782 PRINTF( " -netspeed %-12s %-15s (up: %.1f, down: %.1f)\n",
Vladimir Chtchetkine6b985d72011-01-20 18:02:35 -0800783 android_netspeed->name,
784 android_netspeed->display,
785 android_netspeed->upload/1000.,
786 android_netspeed->download/1000. );
787 free(android_netspeed);
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800788 }
789 PRINTF( "\n" );
790 PRINTF( " -netspeed %-12s %s", "<num>", "select both upload and download speed\n");
791 PRINTF( " -netspeed %-12s %s", "<up>:<down>", "select individual up and down speed\n");
792
793 PRINTF( "\n The format of -netdelay is one of the following (numbers are msec):\n\n" );
Vladimir Chtchetkine777eb682011-01-26 11:19:19 -0800794 for (n = 0; !corecmd_get_netdelay(n, &android_netdelay); n++) {
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800795 PRINTF( " -netdelay %-10s %-15s (min %d, max %d)\n",
Vladimir Chtchetkine6b985d72011-01-20 18:02:35 -0800796 android_netdelay->name, android_netdelay->display,
797 android_netdelay->min_ms, android_netdelay->max_ms );
798 free(android_netdelay);
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800799 }
800 PRINTF( " -netdelay %-10s %s", "<num>", "select exact latency\n");
801 PRINTF( " -netdelay %-10s %s", "<min>:<max>", "select min and max latencies\n\n");
802
803 PRINTF( " the emulator uses the following defaults:\n\n" );
804 PRINTF( " Default network speed is '%s'\n", DEFAULT_NETSPEED);
805 PRINTF( " Default network latency is '%s'\n\n", DEFAULT_NETDELAY);
806}
807
808static void
809help_http_proxy(stralloc_t* out)
810{
811 PRINTF(
812 " the Android emulator allows you to redirect all TCP connections through\n"
813 " a HTTP/HTTPS proxy. this can be enabled by using the '-http-proxy <proxy>'\n"
814 " option, or by defining the 'http_proxy' environment variable.\n\n"
815
816 " <proxy> can be one of the following:\n\n"
817 " http://<server>:<port>\n"
818 " http://<username>:<password>@<server>:<port>\n\n"
819
820 " the 'http://' prefix can be omitted. If '-http-proxy <proxy>' is not used,\n"
821 " the 'http_proxy' environment variable is looked up and any value matching\n"
822 " the <proxy> format will be used automatically\n\n" );
823}
824
825static void
826help_report_console(stralloc_t* out)
827{
828 PRINTF(
829 " the '-report-console <socket>' option can be used to report the\n"
830 " automatically-assigned console port number to a remote third-party\n"
831 " before starting the emulation. <socket> must be in one of these\n"
832 " formats:\n\n"
833
834 " tcp:<port>[,server][,max=<seconds>]\n"
835 " unix:<path>[,server][,max=<seconds>]\n"
836 "\n"
837 " if the 'server' option is used, the emulator opens a server socket\n"
838 " and waits for an incoming connection to it. by default, it will instead\n"
839 " try to make a normal client connection to the socket, and, in case of\n"
840 " failure, will repeat this operation every second for 10 seconds.\n"
841 " the 'max=<seconds>' option can be used to modify the timeout\n\n"
842
843 " when the connection is established, the emulator sends its console port\n"
844 " number as text to the remote third-party, then closes the connection and\n"
845 " starts the emulation as usual. *any* failure in the process described here\n"
846 " will result in the emulator aborting immediately\n\n"
847
848 " as an example, here's a small Unix shell script that starts the emulator in\n"
849 " the background and waits for its port number with the help of the 'netcat'\n"
850 " utility:\n\n"
851
852 " MYPORT=5000\n"
853 " emulator -no-window -report-console tcp:$MYPORT &\n"
854 " CONSOLEPORT=`nc -l localhost $MYPORT`\n"
855 "\n"
856 );
857}
858
859static void
860help_dpi_device(stralloc_t* out)
861{
862 PRINTF(
863 " use '-dpi-device <dpi>' to specify the screen resolution of the emulated\n"
864 " device. <dpi> must be an integer between 72 and 1000. the default is taken\n"
865 " from the skin, if available, or uses the contant value %d (an average of\n"
866 " several prototypes used during Android development).\n\n", DEFAULT_DEVICE_DPI );
867
868 PRINTF(
869 " the device resolution can also used to rescale the emulator window with\n"
870 " the '-scale' option (see -help-scale)\n\n"
871 );
872}
873
874static void
875help_audio(stralloc_t* out)
876{
877 PRINTF(
878 " the '-audio <backend>' option allows you to select a specific backend\n"
879 " to be used to both play and record audio in the Android emulator.\n\n"
880
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800881 " use '-audio none' to disable audio completely.\n\n"
882 );
883}
884
885static void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -0800886help_scale(stralloc_t* out)
887{
888 PRINTF(
889 " the '-scale <scale>' option is used to scale the emulator window to\n"
890 " something that better fits the physical dimensions of a real device. this\n"
891 " can be *very* useful to check that your UI isn't too small to be usable\n"
892 " on a real device.\n\n"
893
894 " there are three supported formats for <scale>:\n\n"
895
896 " * if <scale> is a real number (between 0.1 and 3.0) it is used as a\n"
897 " scaling factor for the emulator's window.\n\n"
898
899 " * if <scale> is an integer followed by the suffix 'dpi' (e.g. '110dpi'),\n"
900 " then it is interpreted as the resolution of your monitor screen. this\n"
901 " will be divided by the emulated device's resolution to get an absolute\n"
902 " scale. (see -help-dpi-device for details).\n\n"
903
904 " * finally, if <scale> is the keyword 'auto', the emulator tries to guess\n"
905 " your monitor's resolution and automatically adjusts its window\n"
906 " accordingly\n\n"
907
908 " NOTE: this process is *very* unreliable, depending on your OS, video\n"
909 " driver issues and other random system parameters\n\n"
910
911 " the emulator's scale can be changed anytime at runtime through the control\n"
912 " console. see the help for the 'window scale' command for details\n\n" );
913}
914
915static void
916help_trace(stralloc_t* out)
917{
918 PRINTF(
919 " use '-trace <name>' to start the emulator with runtime code profiling support\n"
920 " profiling itself will not be enabled unless you press F9 to activate it, or\n"
921 " the executed code turns it on programmatically.\n\n"
922
923 " trace information is stored in directory <name>, several files are created\n"
924 " there, that can later be used with the 'traceview' program that comes with\n"
925 " the Android SDK for analysis.\n\n"
926
927 " note that execution will be slightly slower when enabling code profiling,\n"
928 " this is a necessary requirement of the operations being performed to record\n"
929 " the execution trace. this slowdown should not affect your system until you\n"
930 " enable the profiling though...\n\n"
931 );
932}
933
Vladimir Chtchetkine5389aa12010-02-16 10:38:35 -0800934#ifdef CONFIG_MEMCHECK
935static void
936help_memcheck(stralloc_t* out)
937{
938 PRINTF(
939 " use '-memcheck <flags>' to start the emulator with memory access checking\n"
940 " support.\n\n"
941
942 " <flags> enables, or disables memory access checking, and also controls\n"
943 " what events are going to be logged by the memory access checker.\n"
944 " <flags> can be one of the following:\n"
945 " 1 - Enables memory access checking with default logging (\"LIRW\"), or\n"
946 " 0 - Disables memory access checking, or\n"
947 " A combination (in no particular order) of the following:\n"
948 " L - Logs memory leaks on process exit.\n"
949 " I - Logs attempts to use invalid pointers in free, or realloc routines.\n"
950 " R - Logs memory access violation on read operations.\n"
951 " W - Logs memory access violation on write operations.\n"
952 " N - Logs new process ID allocation.\n"
953 " F - Logs guest's process forking.\n"
954 " S - Logs guest's process starting.\n"
955 " E - Logs guest's process exiting.\n"
956 " C - Logs guest's thread creation (clone).\n"
957 " B - Logs libc.so initialization in the guest system.\n"
958 " M - Logs module mapping and unmapping in the guest system.\n"
959 " A - Logs all emulator events. Equala to \"LIRWFSECANBM\" combination.\n"
960 " e - Logs error messages, received from the guest system.\n"
961 " d - Logs debug messages, received from the guest system.\n"
962 " i - Logs information messages, received from the guest system.\n"
963 " a - Logs all messages, received from the guest system.\n"
964 " This is equal to \"edi\" combination.\n\n"
965
966 " note that execution might be significantly slower when enabling memory access\n"
967 " checking, this is a necessary requirement of the operations being performed\n"
968 " to analyze memory allocations and memory access.\n\n"
969 );
970}
971#endif // CONFIG_MEMCHECK
972
Vladimir Chtchetkine9a33e852010-11-08 16:52:04 -0800973#ifdef CONFIG_STANDALONE_UI
974static void
975help_list_cores(stralloc_t* out)
976{
977 PRINTF(
978 " use '-list-cores localhost to list emulator core processes running on this machine.\n"
979 " use '-list-cores host_name, or IP address to list emulator core processes running on\n"
980 " a remote machine.\n"
981 );
982}
Vladimir Chtchetkined87b0802010-12-06 10:55:11 -0800983
984static void
985help_attach_core(stralloc_t* out)
986{
987 PRINTF(
988 " the -attach-core <console socket> options attaches the UI to a running emulator core process.\n\n"
989
990 " the <console socket> parameter must be in the form [host:]port, where 'host' addresses the\n"
991 " machine on which the core process is running, and 'port' addresses the console port number for\n"
992 " the running core process. Note that 'host' value must be in the form that can be resolved\n"
993 " into an IP address.\n\n"
994
995 " Use -list-cores to enumerate console ports for all currently running core processes.\n"
996 );
997}
Vladimir Chtchetkine9a33e852010-11-08 16:52:04 -0800998#endif // CONFIG_STANDALONE_UI
999
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001000static void
1001help_show_kernel(stralloc_t* out)
1002{
1003 PRINTF(
1004 " use '-show-kernel' to redirect debug messages from the kernel to the current\n"
1005 " terminal. this is useful to check that the boot process works correctly.\n\n"
1006 );
1007}
1008
1009static void
1010help_shell(stralloc_t* out)
1011{
1012 PRINTF(
1013 " use '-shell' to create a root shell console on the current terminal.\n"
1014 " this is unlike the 'adb shell' command for the following reasons:\n\n"
1015
1016 " * this is a *root* shell that allows you to modify many parts of the system\n"
1017 " * this works even if the ADB daemon in the emulated system is broken\n"
1018 " * pressing Ctrl-C will stop the emulator, instead of the shell.\n\n"
1019 " See also '-shell-serial'.\n\n" );
1020}
1021
1022static void
1023help_shell_serial(stralloc_t* out)
1024{
1025 PRINTF(
1026 " use '-shell-serial <device>' instead of '-shell' to open a root shell\n"
1027 " to the emulated system, while specifying an external communication\n"
1028 " channel / host device.\n\n"
1029
1030 " '-shell-serial stdio' is identical to '-shell', while you can use\n"
1031 " '-shell-serial tcp::4444,server,nowait' to talk to the shell over local\n"
1032 " TCP port 4444. '-shell-serial fdpair:3:6' would let a parent process\n"
1033 " talk to the shell using fds 3 and 6.\n\n"
1034
1035 " see -help-char-devices for a list of available <device> specifications.\n\n"
1036 " NOTE: you can have only one shell per emulator instance at the moment\n\n"
1037 );
1038}
1039
1040static void
1041help_logcat(stralloc_t* out)
1042{
1043 PRINTF(
1044 " use '-logcat <tags>' to redirect log messages from the emulated system to\n"
1045 " the current terminal. <tags> is a list of space/comma-separated log filters\n"
1046 " where each filter has the following format:\n\n"
1047
1048 " <componentName>:<logLevel>\n\n"
1049
1050 " where <componentName> is either '*' or the name of a given component,\n"
1051 " and <logLevel> is one of the following letters:\n\n"
1052
1053 " v verbose level\n"
1054 " d debug level\n"
1055 " i informative log level\n"
1056 " w warning log level\n"
1057 " e error log level\n"
1058 " s silent log level\n\n"
1059
1060 " for example, the following only displays messages from the 'GSM' component\n"
1061 " that are at least at the informative level:\n\n"
1062
1063 " -logcat '*:s GSM:i'\n\n"
1064
1065 " if '-logcat <tags>' is not used, the emulator looks for ANDROID_LOG_TAGS\n"
1066 " in the environment. if it is defined, its value must match the <tags>\n"
1067 " format and will be used to redirect log messages to the terminal.\n\n"
1068
1069 " note that this doesn't prevent you from redirecting the same, or other,\n"
1070 " log messages through the ADB or DDMS tools too.\n\n");
1071}
1072
1073static void
1074help_no_audio(stralloc_t* out)
1075{
1076 PRINTF(
1077 " use '-no-audio' to disable all audio support in the emulator. this may be\n"
1078 " unfortunately be necessary in some cases:\n\n"
1079
1080 " * at least two users have reported that their Windows machine rebooted\n"
1081 " instantly unless they used this option when starting the emulator.\n"
1082 " it is very likely that the problem comes from buggy audio drivers.\n\n"
1083
1084 " * on some Linux machines, the emulator might get stuck at startup with\n"
1085 " audio support enabled. this problem is hard to reproduce, but seems to\n"
1086 " be related too to flaky ALSA / audio driver support.\n\n"
1087
1088 " on Linux, another option is to try to change the default audio backend\n"
1089 " used by the emulator. you can do that by setting the QEMU_AUDIO_DRV\n"
1090 " environment variables to one of the following values:\n\n"
1091
1092 " alsa (use the ALSA backend)\n"
1093 " esd (use the EsounD backend)\n"
1094 " sdl (use the SDL audio backend, no audio input supported)\n"
1095 " oss (use the OSS backend)\n"
1096 " none (do not support audio)\n"
1097 "\n"
1098 " the very brave can also try to use distinct backends for audio input\n"
1099 " and audio outputs, this is possible by selecting one of the above values\n"
1100 " into the QEMU_AUDIO_OUT_DRV and QEMU_AUDIO_IN_DRV environment variables.\n\n"
1101 );
1102}
1103
1104static void
1105help_raw_keys(stralloc_t* out)
1106{
1107 PRINTF(
1108 " this option is deprecated because one can do the same using Ctrl-K\n"
1109 " at runtime (this keypress toggles between unicode/raw keyboard modes)\n\n"
1110
1111 " by default, the emulator tries to reverse-map the characters you type on\n"
1112 " your keyboard to device-specific key presses whenever possible. this is\n"
1113 " done to make the emulator usable with a non-QWERTY keyboard.\n\n"
1114
1115 " however, this also means that single keypresses like Shift or Alt are not\n"
1116 " passed to the emulated device. the '-raw-keys' option disables the reverse\n"
1117 " mapping. it should only be used when using a QWERTY keyboard on your machine\n"
1118
1119 " (should only be useful to Android system hackers, e.g. when implementing a\n"
1120 " new input method).\n\n"
1121 );
1122}
1123
1124static void
1125help_radio(stralloc_t* out)
1126{
1127 PRINTF(
1128 " use '-radio <device>' to redirect the GSM modem emulation to an external\n"
1129 " character device or program. this bypasses the emulator's internal modem\n"
1130 " and should only be used for testing.\n\n"
1131
1132 " see '-help-char-devices' for the format of <device>\n\n"
1133
1134 " the data exchanged with the external device/program are GSM AT commands\n\n"
1135
1136 " note that, when running in the emulator, the Android GSM stack only supports\n"
1137 " a *very* basic subset of the GSM protocol. trying to link the emulator to\n"
1138 " a real GSM modem is very likely to not work properly.\n\n"
1139 );
1140}
1141
1142
1143static void
1144help_port(stralloc_t* out)
1145{
1146 PRINTF(
1147 " at startup, the emulator tries to bind its control console at a free port\n"
1148 " starting from 5554, in increments of two (i.e. 5554, then 5556, 5558, etc..)\n"
1149 " this allows several emulator instances to run concurrently on the same\n"
1150 " machine, each one using a different console port number.\n\n"
1151
1152 " use '-port <port>' to force an emulator instance to use a given console port\n\n"
1153
1154 " note that <port> must be an *even* integer between 5554 and 5584 included.\n"
1155 " <port>+1 must also be free and will be reserved for ADB. if any of these\n"
1156 " ports is already used, the emulator will fail to start.\n\n" );
1157}
1158
1159static void
1160help_ports(stralloc_t* out)
1161{
1162 PRINTF(
1163 " the '-ports <consoleport>,<adbport>' option allows you to explicitely set\n"
1164 " the TCP ports used by the emulator to implement its control console and\n"
1165 " communicate with the ADB tool.\n\n"
1166
1167 " This is a very special option that should probably *not* be used by typical\n"
1168 " developers using the Android SDK (use '-port <port>' instead), because the\n"
1169 " corresponding instance is probably not going to be seen from adb/DDMS. Its\n"
1170 " purpose is to use the emulator in very specific network configurations.\n\n"
1171
1172 " <consoleport> is the TCP port used to bind the control console\n"
1173 " <adbport> is the TCP port used to bind the ADB local transport/tunnel.\n\n"
1174
1175 " If both ports aren't available on startup, the emulator will exit.\n\n");
1176}
1177
1178
1179static void
1180help_onion(stralloc_t* out)
1181{
1182 PRINTF(
1183 " use '-onion <file>' to specify a PNG image file that will be displayed on\n"
1184 " top of the emulated framebuffer with translucency. this can be useful to\n"
1185 " check that UI elements are correctly positioned with regards to a reference\n"
1186 " graphics specification.\n\n"
1187
1188 " the default translucency is 50%%, but you can use '-onion-alpha <%%age>' to\n"
1189 " select a different one, or even use keypresses at runtime to alter it\n"
1190 " (see -help-keys for details)\n\n"
1191
1192 " finally, the onion image can be rotated (see -help-onion-rotate)\n\n"
1193 );
1194}
1195
1196static void
1197help_onion_alpha(stralloc_t* out)
1198{
1199 PRINTF(
1200 " use '-onion-alpha <percent>' to change the translucency level of the onion\n"
1201 " image that is going to be displayed on top of the framebuffer (see also\n"
1202 " -help-onion). the default is 50%%.\n\n"
1203
1204 " <percent> must be an integer between 0 and 100.\n\n"
1205
1206 " you can also change the translucency dynamically (see -help-keys)\n\n"
1207 );
1208}
1209
1210static void
1211help_onion_rotation(stralloc_t* out)
1212{
1213 PRINTF(
1214 " use '-onion-rotation <rotation>' to change the rotation of the onion\n"
1215 " image loaded through '-onion <file>'. valid values for <rotation> are:\n\n"
1216
1217 " 0 no rotation\n"
1218 " 1 90 degrees clockwise\n"
1219 " 2 180 degrees\n"
1220 " 3 270 degrees clockwise\n\n"
1221 );
1222}
1223
1224
1225static void
1226help_timezone(stralloc_t* out)
1227{
1228 PRINTF(
1229 " by default, the emulator tries to detect your current timezone to report\n"
1230 " it to the emulated system. use the '-timezone <timezone>' option to choose\n"
1231 " a different timezone, or if the automatic detection doesn't work correctly.\n\n"
1232
1233 " VERY IMPORTANT NOTE:\n\n"
1234 " the <timezone> value must be in zoneinfo format, i.e. it should look like\n"
1235 " Area/Location or even Area/SubArea/Location. valid examples are:\n\n"
1236
1237 " America/Los_Angeles\n"
1238 " Europe/Paris\n\n"
1239
1240 " using a human-friendly abbreviation like 'PST' or 'CET' will not work, as\n"
1241 " well as using values that are not defined by the zoneinfo database.\n\n"
1242
1243 " NOTE: unfortunately, this will not work on M5 and older SDK releases\n\n"
1244 );
1245}
1246
1247
1248static void
1249help_dns_server(stralloc_t* out)
1250{
1251 PRINTF(
1252 " by default, the emulator tries to detect the DNS servers you're using and\n"
1253 " will setup special aliases in the emulated firewall network to allow the\n"
1254 " Android system to connect directly to them. use '-dns-server <servers>' to\n"
1255 " select a different list of DNS servers to be used.\n\n"
1256
1257 " <servers> must be a comma-separated list of up to 4 DNS server names or\n"
1258 " IP addresses.\n\n"
1259
1260 " NOTE: on M5 and older SDK releases, only the first server in the list will\n"
1261 " be used.\n\n"
1262 );
1263}
1264
1265
1266static void
1267help_cpu_delay(stralloc_t* out)
1268{
1269 PRINTF(
1270 " this option is purely experimental, probably doesn't work as you would\n"
1271 " expect, and may even disappear in a later emulator release.\n\n"
1272
1273 " use '-cpu-delay <delay>' to throttle CPU emulation. this may be useful\n"
1274 " to detect weird race conditions that only happen on 'lower' CPUs. note\n"
1275 " that <delay> is a unit-less integer that doesn't even scale linearly\n"
1276 " to observable slowdowns. use trial and error to find something that\n"
1277 " suits you, the 'correct' machine is very probably dependent on your\n"
1278 " host CPU and memory anyway...\n\n"
1279 );
1280}
1281
1282
1283static void
1284help_no_boot_anim(stralloc_t* out)
1285{
1286 PRINTF(
1287 " use '-no-boot-anim' to disable the boot animation (red bouncing ball) when\n"
1288 " starting the emulator. on slow machines, this can surprisingly speed up the\n"
1289 " boot sequence in tremendous ways.\n\n"
1290
1291 " NOTE: unfortunately, this will not work on M5 and older SDK releases\n\n"
1292 );
1293}
1294
1295
1296static void
1297help_gps(stralloc_t* out)
1298{
1299 PRINTF(
1300 " use '-gps <device>' to emulate an NMEA-compatible GPS unit connected to\n"
1301 " an external character device or socket. the format of <device> is the same\n"
1302 " than the one used for '-radio <device>' (see -help-char-devices for details)\n\n"
1303 );
1304}
1305
1306
1307static void
1308help_keyset(stralloc_t* out)
1309{
1310 char temp[256];
1311
1312 PRINTF(
1313 " use '-keyset <name>' to specify a different keyset file name to use when\n"
1314 " starting the emulator. a keyset file contains a list of key bindings used\n"
1315 " to control the emulator with the host keyboard.\n\n"
1316
1317 " by default, the emulator looks for the following file:\n\n"
1318 );
1319
1320 bufprint_config_file(temp, temp+sizeof(temp), KEYSET_FILE);
1321 PRINTF(
1322 " %s\n\n", temp );
1323
1324 bufprint_config_path(temp, temp+sizeof(temp));
1325 PRINTF(
1326 " however, if -keyset is used, then the emulator does the following:\n\n"
1327
1328 " - first, if <name> doesn't have an extension, then the '.keyset' suffix\n"
1329 " is appended to it (e.g. \"foo\" => \"foo.keyset\"),\n\n"
1330
1331 " - then, the emulator searches for a file named <name> in the following\n"
1332 " directories:\n\n"
1333
1334 " * the emulator configuration directory: %s\n"
1335 " * the 'keysets' subdirectory of <systemdir>, if any\n"
1336 " * the 'keysets' subdirectory of the program location, if any\n\n",
1337 temp );
1338
1339 PRINTF(
1340 " if no corresponding file is found, a default set of key bindings is used.\n\n"
1341 " use '-help-keys' to list the default key bindings.\n"
1342 " use '-help-keyset-file' to learn more about the format of keyset files.\n"
1343 "\n"
1344 );
1345}
1346
1347static void
1348help_old_system(stralloc_t* out)
1349{
1350 PRINTF(
1351 " use '-old-system' if you want to use a recent emulator binary to run\n"
1352 " an old version of the Android SDK system images. Here, 'old' means anything\n"
1353 " older than version 1.4 of the emulator.\n\n"
1354
1355 " NOTE: using '-old-system' with recent system images is likely to not work\n"
1356 " properly, though you may not notice it immediately (e.g. failure to\n"
1357 " start the emulated GPS hardware)\n\n"
1358 );
1359}
1360
1361#ifdef CONFIG_NAND_LIMITS
1362static void
1363help_nand_limits(stralloc_t* out)
1364{
1365 PRINTF(
1366 " use '-nand-limits <limits>' to enable a debugging feature that sends a\n"
1367 " signal to an external process once a read and/or write limit is achieved\n"
1368 " in the emulated system. the format of <limits> is the following:\n\n"
1369
1370 " pid=<number>,signal=<number>,[reads=<threshold>][,writes=<threshold>]\n\n"
1371
1372 " where 'pid' is the target process identifier, 'signal' the number of the\n"
1373 " target signal. the read and/or write threshold'reads' are a number optionally\n"
1374 " followed by a K, M or G suffix, corresponding to the number of bytes to be\n"
1375 " read or written before the signal is sent.\n\n"
1376 );
1377}
1378#endif /* CONFIG_NAND_LIMITS */
1379
1380static void
1381help_bootchart(stralloc_t *out)
1382{
1383 PRINTF(
1384 " some Android system images have a modified 'init' system that integrates\n"
1385 " a bootcharting facility (see http://www.bootchart.org/). You can pass a\n"
1386 " bootcharting period to the system with the following:\n\n"
1387
1388 " -bootchart <timeout>\n\n"
1389
1390 " where 'timeout' is a period expressed in seconds. Note that this won't do\n"
1391 " anything if your init doesn't have bootcharting activated.\n\n"
1392 );
1393}
1394
1395static void
1396help_tcpdump(stralloc_t *out)
1397{
1398 PRINTF(
1399 " use the -tcpdump <file> option to start capturing all network packets\n"
1400 " that are sent through the emulator's virtual Ethernet LAN. You can later\n"
1401 " use tools like WireShark to analyze the traffic and understand what\n"
1402 " really happens.\n\n"
1403
1404 " note that this captures all Ethernet packets, and is not limited to TCP\n"
1405 " connections.\n\n"
1406
1407 " you can also start/stop the packet capture dynamically through the console;\n"
1408 " see the 'network capture start' and 'network capture stop' commands for\n"
1409 " details.\n\n"
1410 );
1411}
1412
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001413static void
vchtchetkine9085a282009-09-14 15:29:20 -07001414help_charmap(stralloc_t *out)
1415{
1416 PRINTF(
1417 " use '-charmap <file>' to use key character map specified in that file.\n"
1418 " <file> must be a full path to a kcm file, containing desired character map.\n\n"
1419 );
1420}
1421
1422static void
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001423help_prop(stralloc_t *out)
1424{
1425 PRINTF(
1426 " use '-prop <name>=<value>' to set a boot-time system property.\n"
1427 " <name> must be a property name of at most %d characters, without any\n"
1428 " space in it, and <value> must be a string of at most %d characters.\n\n",
Vladimir Chtchetkine45d921a2010-07-08 11:05:31 -07001429 BOOT_PROPERTY_MAX_NAME, BOOT_PROPERTY_MAX_VALUE );
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001430
1431 PRINTF(
1432 " the corresponding system property will be set at boot time in the\n"
1433 " emulated system. This can be useful for debugging purposes.\n\n"
1434
1435 " note that you can use several -prop options to define more than one\n"
1436 " boot property.\n\n"
1437 );
1438}
1439
Dries Harnie40beab42010-05-15 17:04:47 +02001440static void
1441help_shared_net_id(stralloc_t* out)
1442{
1443 PRINTF(
1444 " Normally, Android instances running in the emulator cannot talk to each other\n"
1445 " directly, because each instance is behind a virtual router. However, sometimes\n"
1446 " it is necessary to test the behaviour of applications if they are directly\n"
1447 " exposed to the network.\n\n"
1448
1449 " This option instructs the emulator to join a virtual network shared with\n"
1450 " emulators also using this option. The number given is used to construct\n"
1451 " the IP address 10.1.2.<number>, which is bound to a second interface on\n"
1452 " the emulator. Each emulator must use a different number.\n\n"
1453 );
1454}
1455
1456
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001457#define help_no_skin NULL
1458#define help_netspeed help_shaper
1459#define help_netdelay help_shaper
1460#define help_netfast help_shaper
1461
1462#define help_noaudio NULL
1463#define help_noskin NULL
1464#define help_nocache NULL
1465#define help_no_jni NULL
1466#define help_nojni NULL
1467#define help_initdata NULL
1468#define help_no_window NULL
1469#define help_version NULL
1470#define help_memory NULL
The Android Open Source Projectb3ee93a2009-03-13 13:04:21 -07001471#define help_partition_size NULL
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001472
1473typedef struct {
1474 const char* name;
1475 const char* template;
1476 const char* descr;
1477 void (*func)(stralloc_t*);
1478} OptionHelp;
1479
1480static const OptionHelp option_help[] = {
1481#define OPT_FLAG(_name,_descr) { STRINGIFY(_name), NULL, _descr, help_##_name },
1482#define OPT_PARAM(_name,_template,_descr) { STRINGIFY(_name), _template, _descr, help_##_name },
David 'Digit' Turner318e4f22009-05-25 18:01:03 +02001483#define OPT_LIST OPT_PARAM
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001484#include "android/cmdline-options.h"
1485 { NULL, NULL, NULL, NULL }
1486};
1487
1488typedef struct {
1489 const char* name;
1490 const char* desc;
1491 void (*func)(stralloc_t*);
1492} TopicHelp;
1493
1494
1495static const TopicHelp topic_help[] = {
1496 { "disk-images", "about disk images", help_disk_images },
1497 { "keys", "supported key bindings", help_keys },
1498 { "debug-tags", "debug tags for -debug <tags>", help_debug_tags },
1499 { "char-devices", "character <device> specification", help_char_devices },
1500 { "environment", "environment variables", help_environment },
1501 { "keyset-file", "key bindings configuration file", help_keyset_file },
1502 { "virtual-device", "virtual device management", help_virtual_device },
1503 { "sdk-images", "about disk images when using the SDK", help_sdk_images },
1504 { "build-images", "about disk images when building Android", help_build_images },
1505 { NULL, NULL, NULL }
1506};
1507
1508int
1509android_help_for_option( const char* option, stralloc_t* out )
1510{
1511 OptionHelp const* oo;
1512 char temp[32];
1513
1514 /* the names in the option_help table use underscore instead
1515 * of dashes, so create a tranlated copy of the option name
1516 * before scanning the table for matches
1517 */
1518 buffer_translate_char( temp, sizeof temp, option, '-', '_' );
1519
1520 for ( oo = option_help; oo->name != NULL; oo++ ) {
1521 if ( !strcmp(oo->name, temp) ) {
1522 if (oo->func)
1523 oo->func(out);
1524 else
1525 stralloc_add_str(out, oo->descr);
1526 return 0;
1527 }
1528 }
1529 return -1;
1530}
1531
1532
1533int
1534android_help_for_topic( const char* topic, stralloc_t* out )
1535{
1536 const TopicHelp* tt;
1537
1538 for ( tt = topic_help; tt->name != NULL; tt++ ) {
1539 if ( !strcmp(tt->name, topic) ) {
1540 tt->func(out);
1541 return 0;
1542 }
1543 }
1544 return -1;
1545}
1546
1547
Vladimir Chtchetkine5389aa12010-02-16 10:38:35 -08001548extern void
The Android Open Source Project8b23a6c2009-03-03 19:30:32 -08001549android_help_list_options( stralloc_t* out )
1550{
1551 const OptionHelp* oo;
1552 const TopicHelp* tt;
1553 int maxwidth = 0;
1554
1555 for ( oo = option_help; oo->name != NULL; oo++ ) {
1556 int width = strlen(oo->name);
1557 if (oo->template != NULL)
1558 width += strlen(oo->template);
1559 if (width > maxwidth)
1560 maxwidth = width;
1561 }
1562
1563 for (oo = option_help; oo->name != NULL; oo++) {
1564 char temp[32];
1565 /* the names in the option_help table use underscores instead
1566 * of dashes, so create a translated copy of the option's name
1567 */
1568 buffer_translate_char(temp, sizeof temp, oo->name, '_', '-');
1569
1570 stralloc_add_format( out, " -%s %-*s %s\n",
1571 temp,
1572 (int)(maxwidth - strlen(oo->name)),
1573 oo->template ? oo->template : "",
1574 oo->descr );
1575 }
1576
1577 PRINTF( "\n" );
1578 PRINTF( " %-*s %s\n", maxwidth, "-qemu args...", "pass arguments to qemu");
1579 PRINTF( " %-*s %s\n", maxwidth, "-qemu -h", "display qemu help");
1580 PRINTF( "\n" );
1581 PRINTF( " %-*s %s\n", maxwidth, "-verbose", "same as '-debug-init'");
1582 PRINTF( " %-*s %s\n", maxwidth, "-debug <tags>", "enable/disable debug messages");
1583 PRINTF( " %-*s %s\n", maxwidth, "-debug-<tag>", "enable specific debug messages");
1584 PRINTF( " %-*s %s\n", maxwidth, "-debug-no-<tag>","disable specific debug messages");
1585 PRINTF( "\n" );
1586 PRINTF( " %-*s %s\n", maxwidth, "-help", "print this help");
1587 PRINTF( " %-*s %s\n", maxwidth, "-help-<option>", "print option-specific help");
1588 PRINTF( "\n" );
1589
1590 for (tt = topic_help; tt->name != NULL; tt += 1) {
1591 char help[32];
1592 snprintf(help, sizeof(help), "-help-%s", tt->name);
1593 PRINTF( " %-*s %s\n", maxwidth, help, tt->desc );
1594 }
1595 PRINTF( " %-*s %s\n", maxwidth, "-help-all", "prints all help content");
1596 PRINTF( "\n");
1597}
1598
1599
1600void
1601android_help_main( stralloc_t* out )
1602{
1603 stralloc_add_str(out, "Android Emulator usage: emulator [options] [-qemu args]\n");
1604 stralloc_add_str(out, " options:\n" );
1605
1606 android_help_list_options(out);
1607
1608 /*printf( "%.*s", out->n, out->s );*/
1609}
1610
1611
1612void
1613android_help_all( stralloc_t* out )
1614{
1615 const OptionHelp* oo;
1616 const TopicHelp* tt;
1617
1618 for (oo = option_help; oo->name != NULL; oo++) {
1619 PRINTF( "========= help for option -%s:\n\n", oo->name );
1620 android_help_for_option( oo->name, out );
1621 }
1622
1623 for (tt = topic_help; tt->name != NULL; tt++) {
1624 PRINTF( "========= help for -help-%s\n\n", tt->name );
1625 android_help_for_topic( tt->name, out );
1626 }
1627 PRINTF( "========= top-level help\n\n" );
1628 android_help_main(out);
1629}