am d90576c9: am c8e83aa7: am 1f60afc5: docs: Emulator Hardware Acceleration docs for SDK r17 (80262cea) · Commits · e / os / android_frameworks_base

docs/html/guide/developing/devices/emulator.jd

+652 −855

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/guide/developing/tools/emulator.jd

+232 −223

Original line number	Original line	Diff line number	Diff line
	@@ -8,8 +8,8 @@ parent.link=index.html

	<h2>In this document</h2>		<h2>In this document</h2>
	<ol>		<ol>
	<li><a href="#startup-options">Emulator Startup Options</a></li>		<li><a href="#KeyMapping">Keyboard Commands</a></li>
	<li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li>		<li><a href="#startup-options">Command Line Parameters</a></li>
	</ol>		</ol>

	<h2>See also</h2>		<h2>See also</h2>
	@@ -26,79 +26,127 @@ parent.link=index.html
	that runs on your computer. The emulator lets you develop and test		that runs on your computer. The emulator lets you develop and test
	Android applications without using a physical device.</p>		Android applications without using a physical device.</p>

	<p>When the emulator is running, you can interact with the emulated mobile		<p>This document is a reference to the available command line options and the keyboard mapping to
	device just as you would an actual mobile device, except that you use your mouse		device keys.
	pointer to "touch" the touchscreen and can use some keyboard keys to
	invoke certain keys on the device. </p>

	<p>This document is a reference to the available command line options and the keyboard mapping to device keys.
	For a complete guide to using the Android Emulator, see		For a complete guide to using the Android Emulator, see
	<a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>.		<a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>.


	<h2 id="startup-options">Emulator Startup Options</h2>		<h2 id="KeyMapping">Keyboard Commands</h2>

	<p>The emulator supports a variety of options that you can specify
	when launching the emulator, to control its appearance or behavior.
	Here's the command-line usage for launching the emulator with options: </p>

	<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>

	<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p>		<p>Table 1 summarizes the mappings between the emulator keys and the keys of your keyboard.</p>

	<table>		<p class="table-caption"><strong>Table 1.</strong> Emulator keyboard mapping</p>
			<table border="0" style="clear:left;">
	<tr>		<tr>
	<th width="10%" >Category</th>		<th>Emulated Device Key </th>
	<th width="20%" >Option</th>		<th>Keyboard Key </th>
	<th width="30%" >Description</th>		</tr>
	<th width="40%" >Comments</th>		<tr>
			<td>Home</td>
			<td>HOME</td>
			</tr>
			<tr>
			<td>Menu (left softkey)</td>
			<td>F2 <em>or</em> Page-up button</td>
			</tr>
			<tr>
			<td>Star (right softkey)</td>
			<td>Shift-F2 <em>or </em>Page Down</td>
			</tr>
			<tr>
			<td>Back</td>
			<td>ESC</td>
			</tr>
			<tr>
			<td>Call/dial button </td>
			<td>F3</td>
			</tr>
			<tr>
			<td>Hangup/end call button</td>
			<td>F4</td>
			</tr>
			<tr>
			<td>Search</td>
			<td>F5 </td>
			</tr>
			<tr>
			<td>Power button</td>
			<td>F7 </td>
			</tr>
			<tr>
			<td>Audio volume up button</td>
			<td>KEYPAD_PLUS, Ctrl-F5</td>
	</tr>		</tr>

	<tr>		<tr>
	<td rowspan="9">Help</td>		<td>Audio volume down button</td>
	<td><code>-help</code></td>		<td>KEYPAD_MINUS, Ctrl-F6</td>
	<td>Print a list of all emulator options.</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-all</code></td>		<td>Camera button</td>
	<td>Print help for all startup options.</td>		<td>Ctrl-KEYPAD_5, Ctrl-F3</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-<option></code></td>		<td>Switch to previous layout orientation (for example, portrait, landscape)</td>
	<td>Print help for a specific startup option.</td>		<td>KEYPAD_7, Ctrl-F11</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-debug-tags</code></td>		<td>Switch to next layout orientation (for example, portrait, landscape)</td>
	<td>Print a list of all tags for <code>-debug <tags></code>.</td>		<td>KEYPAD_9, Ctrl-F12</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-disk-images</code></td>		<td>Toggle cell networking on/off</td>
	<td>Print help for using emulator disk images.</td>		<td>F8</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-environment</code></td>		<td>Toggle code profiling</td>
	<td>Print help for emulator environment variables.</td>		<td>F9 (only with <code>-trace</code> startup option)</td>
	<td> </td>
	</tr><tr>
	<td><code>-help-keys</code></td>
	<td>Print the current mapping of keys.</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-keyset-file</code></td>		<td>Toggle fullscreen mode</td>
	<td>Print help for defining a custom key mappings file.</td>		<td>Alt-Enter</td>
	<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-help-virtual-device</code></td>		<td>Toggle trackball mode</td>
	<td>Print help for Android Virtual Device usage.</td>		<td>F6</td>
	<td> </td>		</tr>
			<tr>
			<td>Enter trackball mode temporarily (while key is pressed)</td>
			<td>Delete</td>
			</tr>
			<tr>
			<td>DPad left/up/right/down</td>
			<td>KEYPAD_4/8/6/2</td>
			</tr>
			<tr>
			<td>DPad center click</td>
			<td>KEYPAD_5</td>
			</tr>
			<tr>
			<td>Onion alpha increase/decrease</td>
			<td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td>
			</tr>
			</table>


			<h2 id="startup-options">Command Line Parameters</h2>

			<p>The emulator supports a variety of options that you can specify
			when launching the emulator, to control its appearance or behavior.
			Here's the command-line syntax of the options available to the {@code emulator} program:</p>

			<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>

			<p class="table-caption"><strong>Table 2.</strong> Emulator command line parameters</p>
			<table>
			<tr>
			<th width="10%" >Category</th>
			<th width="20%" >Option</th>
			<th width="30%" >Description</th>
			<th width="40%" >Comments</th>
	</tr>		</tr>

	<tr>		<tr>
	<td>AVD</td>		<td>AVD</td>
	<td><code>-avd <avd_name></code> or <br>		<td><code>-avd <avd_name></code> or <br>
	@@ -106,21 +154,21 @@ Here's the command-line usage for launching the emulator with options: </p>
	<td><strong>Required</strong>. Specifies the AVD to load for this emulator		<td><strong>Required</strong>. Specifies the AVD to load for this emulator
	instance.</td>		instance.</td>
	<td>You must create an AVD configuration before launching the emulator. For		<td>You must create an AVD configuration before launching the emulator. For
	information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">		information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing
	Managing AVDs with AVD Manager</a>.</td>		AVDs with AVD Manager</a>.</td>
	<tr>		<tr>
	<td rowspan="7">Disk Images</td>		<td rowspan="7">Disk Images</td>
	<td><code>-cache <filepath></code></td>		<td><code>-cache <filepath></code></td>
	<td>Use <filepath> as the working cache partition image. </td>		<td>Use <filepath> as the working cache partition image. </td>
	<td>Optionally, you can specify a path relative to the current working directory.		<td>An absolute or relative path to the current working directory.
	If no cache file is specified, the emulator's default behavior is to use a temporary file instead.		If no cache file is specified, the emulator's default behavior is to use a temporary file instead.
	<p>For more information on disk images, use <code>-help-disk-images</code>.</p>		<p>For more information on disk images, use <code>-help-disk-images</code>.</p>
	</td></tr>		</td></tr>
	<tr>		<tr>
	<td><code>-data <filepath></code></td>		<td><code>-data <filepath></code></td>
	<td>Use <filepath> as the working user-data disk image. </td>		<td>Use {@code <filepath>} as the working user-data disk image. </td>
	<td>Optionally, you can specify a path relative to the current working directory.		<td>Optionally, you can specify a path relative to the current working directory.
	If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img"		If <code>-data</code> is not used, the emulator looks for a file named {@code userdata-qemu.img}
	in the storage area of the AVD being used (see <code>-avd</code>).		in the storage area of the AVD being used (see <code>-avd</code>).
	</td></tr>		</td></tr>
	<!--		<!--
	@@ -146,15 +194,9 @@ on disk images, use <code>-help-disk-images</code>.</p>
	<td><code>-initdata <filepath></code></td>		<td><code>-initdata <filepath></code></td>
	<td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents		<td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents
	of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td>		of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td>
	<td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td>		<td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>.
	</tr>		<p>For more information on disk images, use <code>-help-disk-images</code>.</p></td>
	<!--
	<tr>
	<td><code>-kernel <filepath></code></td>
	<td>Use <filepath> as the emulated kernel.</td>
	<td>Optionally, you can specify a path relative to the current working directory. </td>
	</tr>		</tr>
	-->
	<tr>		<tr>
	<td><code>-nocache</code></td>		<td><code>-nocache</code></td>
	<td>Start the emulator without a cache partition.</td>		<td>Start the emulator without a cache partition.</td>
	@@ -164,7 +206,8 @@ on disk images, use <code>-help-disk-images</code>.</p>
	<td><code>-ramdisk <filepath></code></td>		<td><code>-ramdisk <filepath></code></td>
	<td>Use <filepath> as the ramdisk image.</td>		<td>Use <filepath> as the ramdisk image.</td>
	<td>Default value is <code><system>/ramdisk.img</code>.		<td>Default value is <code><system>/ramdisk.img</code>.
	<p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p>		<p>Optionally, you can specify a path relative to the current working directory.
			For more information on disk images, use <code>-help-disk-images</code>.</p>
	</td>		</td>
	</tr>		</tr>
	<tr>		<tr>
	@@ -225,8 +268,8 @@ on disk images, use <code>-help-disk-images</code>.</p>
	<td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character		<td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character
	device to use for communication with the shell.</td>		device to use for communication with the shell.</td>
	<td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at		<td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at
	<a href="http://wiki.qemu.org/download/qemu-doc.html">wiki.qemu.org</a>		<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>
	for more information.</p>		for a list of device types.

	<p>Here are some examples: </p>		<p>Here are some examples: </p>
	<ul>		<ul>
	@@ -316,8 +359,9 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s
	<tr>		<tr>
	<td><code>-netdelay <delay></code></td>		<td><code>-netdelay <delay></code></td>
	<td>Set network latency emulation to <delay>.</td>		<td>Set network latency emulation to <delay>.</td>
	<td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for		<td>Default value is <code>none</code>. See the table in
	supported <code><delay></code> values. </td>		<a href="{@docRoot}guide/developing/devices/emulator.html#netdelay">Network Delay Emulation</a>
			for supported <code><delay></code> values. </td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-netfast</code></td>		<td><code>-netfast</code></td>
	@@ -326,7 +370,8 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s
	<tr>		<tr>
	<td><code>-netspeed <speed></code></td>		<td><code>-netspeed <speed></code></td>
	<td>Set network speed emulation to <speed>.</td>		<td>Set network speed emulation to <speed>.</td>
	<td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for		<td>Default value is <code>full</code>. See the table in
			<a href="{@docRoot}guide/developing/devices/emulator.html#netspeed">Network Speed Emulation</a> for
	supported <code><speed></code> values. </td>		supported <code><speed></code> values. </td>
	</tr>		</tr>
	<tr>		<tr>
	@@ -347,7 +392,7 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s
	<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td>		<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td>
	</tr>		</tr>
	<tr>		<tr>
	<td rowspan="8">System</td>		<td rowspan="10">System</td>
	<td><code>-cpu-delay <delay></code></td>		<td><code>-cpu-delay <delay></code></td>
	<td>Slow down emulated CPU speed by <delay> </td>		<td>Slow down emulated CPU speed by <delay> </td>
	<td>Supported values for <delay> are integers between 0 and 1000.		<td>Supported values for <delay> are integers between 0 and 1000.
	@@ -364,7 +409,7 @@ scale in direct relationship with <delay> values.</p>
	<td>Use this command to emulate an NMEA-compatible GPS unit connected to		<td>Use this command to emulate an NMEA-compatible GPS unit connected to
	an external character device or socket. The format of <code><device></code> must be QEMU-specific		an external character device or socket. The format of <code><device></code> must be QEMU-specific
	serial device specification. See the documentation for 'serial -dev' at		serial device specification. See the documentation for 'serial -dev' at
	<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>.		<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
	</td>		</td>
	</tr>		</tr>
	<tr>		<tr>
	@@ -372,18 +417,37 @@ scale in direct relationship with <delay> values.</p>
	<td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr>		<td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr>
	<tr>		<tr>
	<td><code>-qemu</code></td>		<td><code>-qemu</code></td>
	<td>Pass arguments to qemu.</td>		<td>Pass arguments to the qemu emulator software.</td>
	<td> </td></tr>		<td><p class="caution"><strong>Important:</strong> When using this option, make sure it is the
			<em>last option</em> specified, since all options after it are interpretted as qemu-specific
			options.</p></td></tr>
			<tr>
			<td><code>-qemu -enable-kvm</code></td>
			<td>Enable KVM acceleration of the emulator virtual machine.</td>
			<td>This option is only effective when your system is set up to use
			<a href="{@docRoot}guide/developing/devices/emulator.html#vm-linux">KVM-based VM acceleration</a>.
			You can optionally specify a memory size ({@code -m <size>}) for the VM, which should match
			your emulator's memory size:</p>
			{@code -qemu -m 512 -enable-kvm}<br>
			{@code -qemu -m 1024 -enable-kvm}
			</td></tr>
	<tr>		<tr>
	<td><code>-qemu -h</code></td>		<td><code>-qemu -h</code></td>
	<td>Display qemu help.</td>		<td>Display qemu help.</td>
	<td></td></tr>		<td></td></tr>
			<tr>
			<td><code>-gpu on</code></td>
			<td>Turn on graphics acceleration for the emulator.</td>
			<td>This option is only available for emulators using a system image with API Level 15, revision 3
			and higher. For more information, see
			<a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">Using the Android
			Emulator</a>.</td></tr>
	<tr>		<tr>
	<td><code>-radio <device></code></td>		<td><code>-radio <device></code></td>
	<td>Redirect radio mode to the specified character device.</td>		<td>Redirect radio mode to the specified character device.</td>
	<td>The format of <code><device></code> must be QEMU-specific		<td>The format of <code><device></code> must be QEMU-specific
	serial device specification. See the documentation for 'serial -dev' at		serial device specification. See the documentation for 'serial -dev' at
	<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>.		<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>.
	</td>		</td>
	</tr>		</tr>
	<tr>		<tr>
	@@ -460,113 +524,58 @@ option. Using this option may yield unexpected and in some cases misleading
	results, since the density with which to render the skin may not be defined.		results, since the density with which to render the skin may not be defined.
	AVDs let you associate each skin with a default density and override the default		AVDs let you associate each skin with a default density and override the default
	as needed. For more information, see <a		as needed. For more information, see <a
	href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">		href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices
	Managing Virtual Devices with AVD Manager</a>.		with AVD Manager</a>.
	</td>		</td>
	</tr>		</tr>
	<tr>		<tr>
	<td><code>-skindir <dir></code></td>		<td><code>-skindir <dir></code></td>
	<td>This emulator option is deprecated. </td>		<td>This emulator option is deprecated. </td>
	<td>See comments for <code>-skin</code>, above.</td></tr>		<td>See comments for <code>-skin</code>, above.</td>
	</table>



	<h2 id="KeyMapping">Emulator Keyboard Mapping</h2>

	<p>The table below summarizes the mappings between the emulator keys and and
	the keys of your keyboard. </p>
	<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p>
	<table border="0" style="clear:left;">
	<tr>
	<th>Emulated Device Key </th>
	<th>Keyboard Key </th>
	</tr>
	<tr>
	<td>Home</td>
	<td>HOME</td>
	</tr>
	<tr>
	<td>Menu (left softkey)</td>
	<td>F2 <em>or</em> Page-up button</td>
	</tr>
	<tr>
	<td>Star (right softkey)</td>
	<td>Shift-F2 <em>or </em>Page Down</td>
	</tr>
	<tr>
	<td>Back</td>
	<td>ESC</td>
	</tr>
	<tr>
	<td>Call/dial button </td>
	<td>F3</td>
	</tr>
	<tr>
	<td>Hangup/end call button</td>
	<td>F4</td>
	</tr>
	<tr>
	<td>Search</td>
	<td>F5 </td>
	</tr>
	<tr>
	<td>Power button</td>
	<td>F7 </td>
	</tr>
	<tr>
	<td>Audio volume up button</td>
	<td>KEYPAD_PLUS, Ctrl-F5</td>
	</tr>

	<tr>
	<td>Audio volume down button</td>
	<td>KEYPAD_MINUS, Ctrl-F6</td>
	</tr>
	<tr>
	<td>Camera button</td>
	<td>Ctrl-KEYPAD_5, Ctrl-F3</td>
	</tr>
	<tr>
	<td>Switch to previous layout orientation (for example, portrait, landscape)</td>
	<td>KEYPAD_7, Ctrl-F11</td>
	</tr>
	<tr>
	<td>Switch to next layout orientation (for example, portrait, landscape)</td>
	<td>KEYPAD_9, Ctrl-F12</td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Toggle cell networking on/off</td>		<td rowspan="9">Help</td>
	<td>F8</td>		<td><code>-help</code></td>
			<td>Print a list of all emulator options.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Toggle code profiling</td>		<td><code>-help-all</code></td>
	<td>F9 (only with <code>-trace</code> startup option)</td>		<td>Print help for all startup options.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Toggle fullscreen mode</td>		<td><code>-help-<option></code></td>
	<td>Alt-Enter</td>		<td>Print help for a specific startup option.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Toggle trackball mode</td>		<td><code>-help-debug-tags</code></td>
	<td>F6</td>		<td>Print a list of all tags for <code>-debug <tags></code>.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Enter trackball mode temporarily (while key is pressed)</td>		<td><code>-help-disk-images</code></td>
	<td>Delete</td>		<td>Print help for using emulator disk images.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>DPad left/up/right/down</td>		<td><code>-help-environment</code></td>
	<td>KEYPAD_4/8/6/2</td>		<td>Print help for emulator environment variables.</td>
			<td> </td>s
			</tr><tr>
			<td><code>-help-keys</code></td>
			<td>Print the current mapping of keys.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>DPad center click</td>		<td><code>-help-keyset-file</code></td>
	<td>KEYPAD_5</td>		<td>Print help for defining a custom key mappings file.</td>
			<td> </td>
	</tr>		</tr>
	<tr>		<tr>
	<td>Onion alpha increase/decrease</td>		<td><code>-help-virtual-device</code></td>
	<td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td>		<td>Print help for Android Virtual Device usage.</td>
			<td> </td>
	</tr>		</tr>
	</table>		</table>

	<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p>

docs/html/images/emulator-wvga800l.png

−406 KiB (95.5 KiB)

Loading image diff...