Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 1f60afc5 authored by Joe Fernandez's avatar Joe Fernandez
Browse files

docs: Emulator Hardware Acceleration docs for SDK r17 

Change-Id: I0714891d14db598f6c4acd29773975bd7754a912
parent eb1d42e4

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 Diff line number Diff line
@@ -8,8 +8,8 @@ parent.link=index.html 


  <h2>In this document</h2>

  <ol>

    <li><a href="#startup-options">Emulator Startup Options</a></li>

    <li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li>

    <li><a href="#KeyMapping">Keyboard Commands</a></li>

    <li><a href="#startup-options">Command Line Parameters</a></li>

  </ol>



  <h2>See also</h2>
@@ -26,79 +26,127 @@ parent.link=index.html 
that runs on your computer. The emulator lets you develop and test

Android applications without using a physical device.</p>



<p>When the emulator is running, you can interact with the emulated mobile

device just as you would an actual mobile device, except that you use your mouse

pointer to &quot;touch&quot; 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. 

<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

<a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>.





<h2 id="startup-options">Emulator Startup Options</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 &lt;avd_name&gt; [-&lt;option&gt; [&lt;value&gt;]] ... [-&lt;qemu args&gt;]</pre>

<h2 id="KeyMapping">Keyboard Commands</h2>



<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>

  <th width="10%" >Category</th>

  <th width="20%" >Option</th>

    <th width="30%" >Description</th>

    <th width="40%" >Comments</th>

    <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 rowspan="9">Help</td>

  <td><code>-help</code></td>

  <td>Print a list of all emulator options.</td>

  <td>&nbsp;</td>

    <td>Audio volume down button</td>

    <td>KEYPAD_MINUS, Ctrl-F6</td>

  </tr>

  <tr>

  <td><code>-help-all</code></td>

  <td>Print help for all startup options.</td>

  <td>&nbsp;</td>

    <td>Camera button</td>

    <td>Ctrl-KEYPAD_5, Ctrl-F3</td>

  </tr>

  <tr>

  <td><code>-help-&lt;option&gt;</code></td>

  <td>Print help for a specific startup option.</td>

  <td>&nbsp;</td>

    <td>Switch to previous layout orientation (for example, portrait, landscape)</td>

    <td>KEYPAD_7, Ctrl-F11</td>

  </tr>

  <tr>

  <td><code>-help-debug-tags</code></td>

  <td>Print a list of all tags for <code>-debug &lt;tags&gt;</code>.</td>

  <td>&nbsp;</td>

    <td>Switch to next layout orientation (for example, portrait, landscape)</td>

    <td>KEYPAD_9, Ctrl-F12</td>

  </tr>

  <tr>

  <td><code>-help-disk-images</code></td>

  <td>Print help for using emulator disk images.</td>

  <td>&nbsp;</td>

    <td>Toggle cell networking on/off</td>

    <td>F8</td>

  </tr>

  <tr>

  <td><code>-help-environment</code></td>

  <td>Print help for emulator environment variables.</td>

  <td>&nbsp;</td>

</tr><tr>

  <td><code>-help-keys</code></td>

  <td>Print the current mapping of keys.</td>

  <td>&nbsp;</td>

    <td>Toggle code profiling</td>

    <td>F9 (only with <code>-trace</code> startup option)</td>

  </tr>

  <tr>

  <td><code>-help-keyset-file</code></td>

  <td>Print help for defining a custom key mappings file.</td>

  <td>&nbsp;</td>

    <td>Toggle fullscreen mode</td>

    <td>Alt-Enter</td>

  </tr>

  <tr>

  <td><code>-help-virtual-device</code></td>

  <td>Print help for Android Virtual Device usage.</td>

  <td>&nbsp;</td>

    <td>Toggle trackball mode</td>

    <td>F6</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 &lt;avd_name&gt; [-&lt;option&gt; [&lt;value&gt;]] ... [-&lt;qemu args&gt;]</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>

  <td>AVD</td>

  <td><code>-avd &lt;avd_name&gt;</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

      instance.</td>

  <td>You must create an AVD configuration before launching the emulator. For

      information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">

      Managing AVDs with AVD Manager</a>.</td>

      information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing

      AVDs with AVD Manager</a>.</td>

<tr>

  <td rowspan="7">Disk Images</td>

  <td><code>-cache&nbsp;&lt;filepath&gt;</code></td>

  <td>Use &lt;filepath&gt; 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.

  <p>For more information on disk images, use <code>-help-disk-images</code>.</p>

</td></tr>

<tr>

  <td><code>-data&nbsp;&lt;filepath&gt;</code></td>

  <td>Use &lt;filepath&gt; as the working user-data disk image. </td>

  <td>Use {@code &lt;filepath&gt;} as the working user-data disk image. </td>

  <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 &quot;userdata-qemu.img&quot; 

  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>).

</td></tr>

<!--
@@ -146,15 +194,9 @@ on disk images, use <code>-help-disk-images</code>.</p> 
  <td><code>-initdata&nbsp;&lt;filepath&gt;</code></td>

  <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>&lt;system&gt;/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>

</tr>

<!--

<tr>

  <td><code>-kernel&nbsp;&lt;filepath&gt;</code></td>

  <td>Use &lt;filepath&gt; as the emulated kernel.</td>

  <td>Optionally, you can specify a path relative to the current working directory. </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>

</tr>

-->

<tr>

  <td><code>-nocache</code></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&nbsp;&lt;filepath&gt;</code></td>

  <td>Use &lt;filepath&gt; as the ramdisk image.</td>

  <td>Default value is <code>&lt;system&gt;/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>

</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

  device to use for communication with the shell.</td>

  <td>&lt;device&gt; 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> 

  for more information.</p>

  <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>

  for a list of device types.



<p>Here are some examples: </p>

<ul>
@@ -316,8 +359,9 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s 
<tr>

  <td><code>-netdelay &lt;delay&gt;</code></td>

  <td>Set network latency emulation to &lt;delay&gt;.</td>

  <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for 

  supported <code>&lt;delay&gt;</code> values. </td>

  <td>Default value is <code>none</code>. See the table in

    <a href="{@docRoot}guide/developing/devices/emulator.html#netdelay">Network Delay Emulation</a>

    for supported <code>&lt;delay&gt;</code> values. </td>

</tr>

<tr>

  <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>

  <td><code>-netspeed &lt;speed&gt;</code></td>

  <td>Set network speed emulation to &lt;speed&gt;.</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>&lt;speed&gt;</code> values. </td>

</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>

</tr>

<tr>

  <td rowspan="8">System</td>

  <td rowspan="10">System</td>

  <td><code>-cpu-delay &lt;delay&gt;</code></td>

  <td>Slow down emulated CPU speed by &lt;delay&gt; </td>

  <td>Supported values for &lt;delay&gt; are integers between 0 and 1000.
@@ -364,7 +409,7 @@ scale in direct relationship with &lt;delay&gt; values.</p> 
  <td>Use this command to emulate an NMEA-compatible GPS unit connected to

  an external character device or socket. The format of <code>&lt;device&gt;</code> must be QEMU-specific

  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>

</tr>

<tr>
@@ -372,18 +417,37 @@ scale in direct relationship with &lt;delay&gt; values.</p> 
  <td>Disable JNI checks in the Dalvik runtime.</td><td>&nbsp;</td></tr>

<tr>

  <td><code>-qemu</code></td>

  <td>Pass arguments to qemu.</td>

  <td>&nbsp;</td></tr>

  <td>Pass arguments to the qemu emulator software.</td>

  <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 &lt;size&gt;}) 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>

  <td><code>-qemu -h</code></td>

  <td>Display qemu help.</td>

  <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>

  <td><code>-radio &lt;device&gt;</code></td>

  <td>Redirect radio mode to the specified character device.</td>

  <td>The format of <code>&lt;device&gt;</code> must be QEMU-specific

  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>

</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.

AVDs let you associate each skin with a default density and override the default

as needed. For more information, see <a

href="{@docRoot}guide/developing/devices/managing-avds.html#createavd">

Managing Virtual Devices with AVD Manager</a>.

href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices

with AVD Manager</a>.

</td>

</tr>

<tr>

  <td><code>-skindir &lt;dir&gt;</code></td>

  <td>This emulator option is deprecated. </td>

  <td>See comments for <code>-skin</code>, above.</td></tr>

</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>

  <td>See comments for <code>-skin</code>, above.</td>

</tr>

<tr>

    <td>Toggle cell networking on/off</td>

    <td>F8</td>

  <td rowspan="9">Help</td>

  <td><code>-help</code></td>

  <td>Print a list of all emulator options.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>Toggle code profiling</td>

    <td>F9 (only with <code>-trace</code> startup option)</td>

  <td><code>-help-all</code></td>

  <td>Print help for all startup options.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>Toggle fullscreen mode</td>

    <td>Alt-Enter</td>

  <td><code>-help-&lt;option&gt;</code></td>

  <td>Print help for a specific startup option.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>Toggle trackball mode</td>

    <td>F6</td>

  <td><code>-help-debug-tags</code></td>

  <td>Print a list of all tags for <code>-debug &lt;tags&gt;</code>.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>Enter trackball mode temporarily (while key is pressed)</td>

    <td>Delete</td>

  <td><code>-help-disk-images</code></td>

  <td>Print help for using emulator disk images.</td>

  <td>&nbsp;</td>

 </tr>

<tr>

    <td>DPad left/up/right/down</td>

    <td>KEYPAD_4/8/6/2</td>

  <td><code>-help-environment</code></td>

  <td>Print help for emulator environment variables.</td>

  <td>&nbsp;</td>s

</tr><tr>

  <td><code>-help-keys</code></td>

  <td>Print the current mapping of keys.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>DPad center click</td>

    <td>KEYPAD_5</td>

  <td><code>-help-keyset-file</code></td>

  <td>Print help for defining a custom key mappings file.</td>

  <td>&nbsp;</td>

</tr>

<tr>

    <td>Onion alpha increase/decrease</td>

    <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td>

  <td><code>-help-virtual-device</code></td>

  <td>Print help for Android Virtual Device usage.</td>

  <td>&nbsp;</td>

</tr>

</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...