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