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