Docs: Adding GLES32 N updates
Correcting file paths per feedback
Adding Clay's feedback + general html cleanup
Bug: 27929504
Change-Id: If355d2ecb389a77231911e8301386a11c727f4c0
diff --git a/src/devices/graphics/run-tests.jd b/src/devices/graphics/run-tests.jd
index 3da7b31..d08dd35 100644
--- a/src/devices/graphics/run-tests.jd
+++ b/src/devices/graphics/run-tests.jd
@@ -24,11 +24,13 @@
</ol>
</div>
</div>
-
+<p>This page provides instructions for running deqp tests in Linux and Windows
+environments, using command line arguments, and working with the Android
+application package.</p>
<h2 id=linux_and_windows_environments>Linux and Windows environments</h2>
-<p>The following files and directories must be copied to the target.</p>
+<p>Start by copying the following files and directories to the target.</p>
<table>
<tr>
@@ -38,59 +40,78 @@
</tr>
<tr>
- <td><p>Execution Server</p></td>
+ <td>Execution Server</td>
<td><code>build/execserver/execserver</code></td>
- <td><code><dst>/execserver</code></td>
+ <td><code><dst>/execserver</code></td>
</tr>
-
+
<tr>
- <td><p>EGL Module</p></td>
+ <td>EGL Module</td>
<td><code>build/modules/egl/deqp-egl</code></td>
- <td><code><dst>/deqp-egl</code></td>
+ <td><code><dst>/deqp-egl</code></td>
</tr>
-
+
<tr>
- <td><p>GLES2 Module</p></td>
- <td><code>build/modules/gles2/deqp-gles2data/gles2</code></td>
- <td>
- <code>
-<dst>/deqp-gles2<br/>
-<dst>/gles2
- </code>
- </td>
+ <td rowspan=2 style="vertical-align:middle">GLES2 Module</td>
+ <td><code>build/modules/gles2/deqp-gles2</code></td>
+ <td><code><dst>/deqp-gles2</code></td>
</tr>
-
+
+
<tr>
- <td><p>GLES3 Module</p></td>
- <td><code>build/modules/gles3/deqp-gles3data/gles3</code></td>
- <td>
- <code>
-<dst>/deqp-gles3<br/>
-<dst>/gles3
-</code>
-</td>
+ <td><code>data/gles2</code></td>
+ <td><code><dst>/gles2</code></td>
</tr>
-
+
+
+
<tr>
- <td><p>GLES3.1 Module</p></td>
- <td><code>build/modules/gles31/deqp-gles31data/gles31</code></td>
- <td>
- <code>
-<dst>/deqp-gles31<br/>
-<dst>/gles31
- </code>
- </td>
+ <td rowspan=2 style="vertical-align:middle">GLES3 Module</td>
+ <td><code>build/modules/gles3/deqp-gles3</td>
+ <td><code><dst>/deqp-gles3</code></td>
</tr>
+
+ <tr>
+ <td><code>data/gles3</code></td>
+ <td><code><dst>/gles3</code></td>
+ </tr>
+
+ <tr>
+ <td rowspan=2 style="vertical-align:middle">GLES3.1 Module</td>
+ <td><code>build/modules/gles31/deqp-gles31</code></td>
+ <td><code><dst>/deqp-gles31</code></td>
+ </tr>
+
+ <tr>
+ <td><code>data/gles31</code></td>
+ <td><code><dst>/gles31</code></td>
+ </tr>
+
+
+ <tr>
+ <td rowspan=2 style="vertical-align:middle">GLES3.2 Module</td>
+ <td><code>build/modules/gles32/deqp-gles32</code></td>
+ <td><code><dst>/deqp-gles32</code></td>
+ </tr>
+
+ <tr>
+ <td><code>data/gles32</code></td>
+ <td><code><dst>/gles32</code></td>
+ </tr>
+
</table>
-<p>Execution service and test binaries can be deployed anywhere in the target file system. Test binaries expect to find data directories in the current working directory.</p>
-
-<p>Start the Test Execution Service on the target device. For more details on
-starting the service, see <a href="port-tests.html#test_execution_service">Test execution service</a>.</p>
+<p>You can deploy the execution service and test binaries anywhere in the target
+file system; however, test binaries expect to find data directories in the
+current working directory. When ready, start the Test Execution Service on the
+target device. For details on starting the service, see
+<a href="{@docRoot}devices/graphics/port-tests.html#test_execution_service">Test
+execution service</a>.</p>
<h2 id=command_line_arguments>Command line arguments</h2>
-<p>The following table lists command line arguments that affect execution of all test programs. </p>
+<p>The following table lists command line arguments that affect execution of all
+test programs.</p>
<table width="100%">
<col style="width:50%">
@@ -101,42 +122,32 @@
</tr>
<tr>
- <td><code>
---deqp-case=<casename></code></td>
-<td><p>Run cases that match a given pattern. Wildcard (*) is supported.</p>
-</td>
- </tr>
-
- <tr>
- <td><code>
---deqp-log-filename=<filename></code></td>
-<td><p>Write test results to the file whose name you provide. </p>
-<p>The test execution service will set the filename when starting a test.</p>
-</td>
+<td><code>--deqp-case=<casename></code></td>
+<td>Run cases that match a given pattern. Wildcard (*) is supported.</td>
</tr>
<tr>
- <td><code>
---deqp-stdin-caselist<br/>
---deqp-caselist=<caselist><br/>
---deqp-caselist-file=<filename></code></td>
-<td><p>Read case list from stdin or from a given argument. The test execution service
-will set the argument according to the execution request received. See the next
-section for a description of the case list format.</p>
-</td>
+<td><code>--deqp-log-filename=<filename></code></td>
+<td>Write test results to the file whose name you provide. The test execution
+service will set the filename when starting a test.</td>
+ </tr>
+
+ <tr>
+ <td><code>--deqp-stdin-caselist<br/>
+--deqp-caselist=<caselist><br/>
+--deqp-caselist-file=<filename></code></td>
+<td>Read case list from stdin or from a given argument. The test execution
+service will set the argument according to the execution request received. See
+the next section for a description of the case list format.</td>
</tr>
<tr>
- <td><code>
---deqp-test-iteration-count=<count></code></td>
-<td><p>Override iteration count for tests that support a variable number of
-iterations. </p>
-</td>
+<td><code>--deqp-test-iteration-count=<count></code></td>
+<td>Override iteration count for tests that support a variable number of
+iterations.</td>
</tr>
<tr>
- <td><code>
---deqp-base-seed=<seed></code></td>
-<td><p>Base seed for the test cases that use randomization.</p>
-</td>
+ <td><code>--deqp-base-seed=<seed></code></td>
+ <td>Base seed for the test cases that use randomization.</td>
</tr>
</table>
@@ -153,72 +164,64 @@
<th>Description</th>
</tr>
<tr>
- <td><code>
---deqp-gl-context-type=<type></code></td>
-<td><p>OpenGL context type. Available context types depend on the platform. On
-platforms supporting EGL, the value <code>egl</code> can be used to select the EGL context.</p>
-</td>
+ <td><code>--deqp-gl-context-type=<type></code></td>
+ <td>OpenGL context type. Available context types depend on the platform. On
+ platforms supporting EGL, the value <code>egl</code> can be used to select
+ the EGL context.</td>
</tr>
<tr>
- <td><code>
---deqp-gl-config-id=<id></code></td>
-<td><p>Run tests for the provided GL configuration ID. Interpretation is
-platform-dependent. On the EGL platform, this is the EGL configuration ID.</p>
-</td>
+ <td><code>--deqp-gl-config-id=<id></code></td>
+ <td>Run tests for the provided GL configuration ID. Interpretation is
+ platform-dependent. On the EGL platform, this is the EGL configuration ID.</td>
</tr>
<tr>
- <td><code>
---deqp-gl-config-name=<name></code></td>
-<td><p>Run tests for a named GL configuration. Interpretation is platform-dependent.
-For EGL, the format is <code>rgb(a)<bits>d<bits>s<bits></code>. For example, a value of <code>rgb888s8</code> will select the first configuration where the color buffer is RGB888 and the
-stencil buffer has 8 bits.</p>
-</td>
+ <td><code>--deqp-gl-config-name=<name></code></td>
+ <td><p>Run tests for a named GL configuration. Interpretation is
+ platform-dependent. For EGL, the format is
+ <code>rgb(a)<bits>d<bits>s<bits></code>. For example, a
+ value of <code>rgb888s8</code> will select the first configuration where the
+ color buffer is RGB888 and the stencil buffer has 8 bits.</td>
</tr>
<tr>
- <td><code>
---deqp-gl-context-flags=<flags></code></td>
-<td><p>Creates a context. Specify <code>robust</code> or <code>debug</code>.</p>
-</td>
+ <td><code>--deqp-gl-context-flags=<flags></code></td>
+ <td>Creates a context. Specify <code>robust</code> or <code>debug</code>.</td>
</tr>
<tr>
- <td><code>
---deqp-surface-width=<width><br/>
---deqp-surface-height=<height></code></td>
-<td><p>Try to create a surface with a given size. Support for this is optional.</p>
-</td>
+ <td><code>--deqp-surface-width=<width><br/>
+ --deqp-surface-height=<height></code></td>
+ <td>Try to create a surface with a given size. Support for this is optional.</td>
</tr>
<tr>
- <td><code>
---deqp-surface-type=<type></code></td>
-<td><p>Use a given surface type as the main test rendering target. Possible types are <code>window</code>, <code>pixmap</code>, <code>pbuffer</code>, and <code>fbo</code>.</p>
-</td>
+ <td><code>--deqp-surface-type=<type></code></td>
+ <td>Use a given surface type as the main test rendering target. Possible
+ types are <code>window</code>, <code>pixmap</code>, <code>pbuffer</code>,
+ and <code>fbo</code>.</td>
</tr>
<tr>
- <td><code>
---deqp-screen-rotation=<rotation></code></td>
-<td><p>Screen orientation in increments of 90 degrees for platforms that support it.</p>
-</td>
+ <td><code>--deqp-screen-rotation=<rotation></code></td>
+ <td>Screen orientation in increments of 90 degrees for platforms that
+ support it.</td>
</tr>
</table>
<h3 id=test_case_list_format>Test case list format</h3>
-<p>The test case list can be given in two formats. The first option is to list the
-full name of each test on a separate line in a standard ASCII file. As the test
-sets grow, the repetitive prefixes can be cumbersome. To avoid repeating the
-prefixes, use a trie (also known as a prefix tree) syntax shown below.</p>
+<p>The test case list can be given in two formats. The first option is to list
+the full name of each test on a separate line in a standard ASCII file. As the
+test sets grow, the repetitive prefixes can be cumbersome. To avoid repeating
+the prefixes, use a trie (also known as a prefix tree) syntax shown below.</p>
<pre>
{nodeName{firstChild{…},…lastChild{…}}}
</pre>
-<p>For example, please review the following:</p>
+<p>For example:</p>
<pre>
{dEQP-EGL{config-list,create_context{rgb565_depth_stencil}}}
</pre>
-<p>That list would translate into two test cases:</p>
+<p>Translates into the following two test cases:</p>
<pre>
dEQP-EGL.config_list
@@ -227,41 +230,47 @@
<h2 id=android>Android</h2>
-<p>The Android application package contains everything required, including the
-test execution service, test binaries, and data files. The test activity is a <code>NativeActivity </code>and it uses EGL, which requires Android 3.2 or later.</p>
+<p>The Android application package contains all required components, including
+the test execution service, test binaries, and data files. The test activity is
+a <code>NativeActivity</code> that uses EGL (requires Android 3.2 or higher).</p>
-<p>The application package can be installed with the following command. The name shown is the name of the APK in the Android CTS package. The name depends on the build:</p>
-<pre>
-adb –d install –r com.drawelements.deqp.apk
-</pre>
+<p>The application package can be installed with the following command (name
+shown is the name of the APK in the Android CTS package; which name depends on
+the build):</p>
+<pre>$ adb –d install –r com.drawelements.deqp.apk</pre>
<p>To launch the test execution service and to setup port forwarding, use the
following:</p>
<pre>
-adb –d forward tcp:50016 tcp:50016
-adb –d shell am start –n com.drawelements.deqp/.execserver.ServiceStarter
+$ adb –d forward tcp:50016 tcp:50016
+$ adb –d shell am start –n com.drawelements.deqp/.execserver.ServiceStarter
</pre>
<p>Debug prints can be enabled by executing the following before starting the
tests:</p>
+
<pre>
-adb –d shell setprop log.tag.dEQP DEBUG
+$ adb –d shell setprop log.tag.dEQP DEBUG
</pre>
-<h3 id=executing_tests_on_android_without_android_cts>Executing tests on Android without Android CTS</h3>
+<h3 id=executing_tests_on_android_without_android_cts>Executing tests on
+Android without Android CTS</h3>
-<p>If you want to manually start the test execution activity, construct an Android
-intent that targets <code>android.app.NativeActivity</code>. The activities can be found in the <code>com.drawelements.deqp</code> package. The command line must be supplied as an extra string with key <code>"cmdLine"</code> in the Intent.</p>
+<p>To manually start the test execution activity, construct an Android intent
+that targets <code>android.app.NativeActivity</code>. The activities can be
+found in the <code>com.drawelements.deqp</code> package. The command line must
+be supplied as an extra string with key <code>"cmdLine"</code> in the Intent.</p>
-<p>A test log will be written to <code>/sdcard/dEQP-log.qpa</code>. If the test run does not start normally, additional debug information is
-available in the device log.</p>
+<p>A test log is written to <code>/sdcard/dEQP-log.qpa</code>. If the test run
+does not start normally, additional debug information is available in the device
+log.</p>
-<p>The activity can be launched from the command line using the <code>"am"</code> utility. For example, to run <code>dEQP-GLES2.info</code> tests on a platform supporting <code>NativeActivity,</code> the following command can be used:</p>
+<p>You can launch an activity from the command line using the <code>am</code>
+utility. For example, to run <code>dEQP-GLES2.info</code> tests on a platform
+supporting <code>NativeActivity,</code> use the following commands.</p>
-<pre>
-adb -d shell am start -n com.drawelements.deqp/android.app.NativeActivity -e
-cmdLine "deqp --deqp-case=dEQP-GLES2.info.*
---deqp-log-filename=/sdcard/dEQP-Log.qpa
+<pre>$ adb -d shell am start -n com.drawelements.deqp/android.app.NativeActivity -e \
+cmdLine "deqp --deqp-case=dEQP-GLES2.info.* --deqp-log-filename=/sdcard/dEQP-Log.qpa
</pre>
<h3 id=debugging_on_android>Debugging on Android</h3>
@@ -270,48 +279,39 @@
the debug build by running the following two scripts:</p>
<pre>
-python android/scripts/build.py --native-build-type=Debug
-python android/scripts/install.py
+$ python android/scripts/build.py --native-build-type=Debug
+$ python android/scripts/install.py
</pre>
-<p>After the debug build is installed on the device, to launch the tests under GDB
-running on the host, run the following command:</p>
+<p>After the debug build is installed on the device, to launch the tests under
+GDB running on the host, run the following command:</p>
-<pre>
-python android/scripts/debug.py
---deqp-commandline="--deqp-log-filename=/sdcard/TestLog.qpa
---deqp-case=dEQP-GLES2.functional.*"
+<pre>$ python android/scripts/debug.py \
+--deqp-commandline="--deqp-log-filename=/sdcard/TestLog.qpa --deqp-case=dEQP-GLES2.functional.*"
</pre>
-<p>The deqp command line will depend on test cases to be executed and other
-required parameters. The script will add a default breakpoint into the
-beginning of the deqp execution (<code>tcu::App::App</code>).</p>
+<p>The deqp command line depends on the test cases to be executed and other
+required parameters. The script adds a default breakpoint at the beginning of
+the deqp execution (<code>tcu::App::App</code>).</p>
-<p>The <code>debug.py </code>script accepts multiple command line arguments, e.g. for the following:</p>
+<p>The <code>debug.py</code> script accepts multiple command line arguments for
+actions such as setting breakpoints for debugging, gdbserver connection
+parameters, and paths to additional binaries to debug (use <code>debug.py
+--help</code> for all arguments and explanations). The script also copies some
+default libraries from the target device to get symbol listings.</p>
-<ul>
- <li> Setting the breakpoints for debugging
- <li> gdbserver connection parameters
- <li> Paths to additional binaries to debug
-</ul>
+<p>To step through driver code (such as when the GDB needs to know the locations
+of the binaries with full debug information), add more libraries via
+<code>debug.py</code> command line parameters. This script writes out a
+configuration file for the GDB starting from line 132 of the script file. You
+can provide additional paths to binaries, etc., but supplying correct command
+line parameters should be enough.</p>
-<p>Running <code>debug.py --help</code> will list all command line parameters, with explanations.</p>
+<p class="note"><strong>Note:</strong> On Windows, the GDB binary requires
+<code>libpython2.7.dll</code>. Before launching <code>debug.py</code>, add
+<code><path-to-ndk>/prebuilt/windows/bin</code> to the PATH variable.</p>
-<p>The script copies some default libraries from the target device to get symbol
-listings. </p>
-
-<p>If there is a need to step through driver code, more libraries can be added via <code>debug.py</code> command line parameters. This would be applicable, for
-example, if the GDB needs to know the locations of the binaries with full debug
-information. The <code>debug.py</code> script writes out a configuration file for the GDB starting from line 132 of
-the script file. Additional paths to binaries, etc., can be added there, but
-supplying correct command line parameters should be enough.</p>
-
-<p><strong>Notes:</strong></p>
-
-<ul>
- <li> On Windows, the gdb binary requires <code>libpython2.7.dll</code>. Add
-<code><path to ndk>/prebuilt/windows/bin</code> to the PATH variable before launching <code>debug.py</code>.
- <li> Native code debugging does not work on stock Android 4.3. See the Android bug
-report below for suggested workarounds. The bug has been fixed in Android 4.4;
-see the following: <a href="https://code.google.com/p/android/issues/detail?id=58373">https://code.google.com/p/android/issues/detail?id=58373</a>
-</ul>
+<p class="note"><strong>Note:</strong> Native code debugging does not work on
+stock Android 4.3; for workarounds, refer to
+<a href="https://code.google.com/p/android/issues/detail?id=58373">https://code.google.com/p/android/issues/detail?id=58373</a>.
+Android 4.4 and higher do not contain this bug.</p>