drawElements 质量计划测试

AOSP 包含 drawElements 质量计划 (deqp) GPU 测试套件，该套件位于 https://android.googlesource.com/platform/external/deqp。本页将详细介绍如何将 deqp 测试套件部署到新环境中。

如需采用最新提交的代码，请使用 deqp-dev 分支。如需采用适用于特定 Android CTS 版本的代码，请使用 release-code-name-release 分支（例如，对于 Android 6.0，请使用 marshmallow-release 分支）。

源代码布局

deqp 测试模块和支持的库的源代码布局如下表所示（列出的内容并不全面，但突出显示了最重要的目录）。

开放源代码组件

deqp 使用 libpng 和 zlib，您可以使用脚本 platform/external/deqp/external/fetch_sources.py 或通过 platform/external/[libpng,zlib] 中的 git 获取它们。

构建测试程序

相关人员在设计测试框架时考虑到了可移植性。仅有的强制性要求是针对 I/O、线程和套接字的全面 C++ 支持和标准系统库。

CMake 构建系统

deqp 来源具有适用于 CMake 的 build 脚本，这是编译测试程序的首选工具。

CMake 是一个开源构建系统，支持多种平台和工具链。CMake 从与目标无关的配置文件生成原生 Makefile 或 IDE 项目文件。如需详细了解 CMake，请参阅 CMake 文档。

CMake 支持且建议在源代码树之外进行构建，也就是说，您应该始终在源代码树之外的独立 build 目录中创建 Makefile 或项目文件。CMake 没有任何类型的“distclean”目标，因此，您必须手动移除 CMake 生成的所有文件。

您可以使用 -DOPTION_NAME=VALUE 语法为 CMake 提供配置选项。deqp 的一些常用选项如下所示。

创建目标 build 文件

针对新目标的 deqp 构建系统应使用目标构建文件进行配置。目标 build 文件可定义平台支持哪些功能以及需要哪些库或其他包含路径。目标文件名采用 targets/NAME/NAME.cmake 格式，并且目标是使用 DEQP_TARGET build 参数选择的。

目标文件中的文件路径是相对于基本 deqp 目录（而非 targets/NAME 目录）的路径。目标 build 文件可以设置以下标准变量。

目标 build 文件可以使用 include_directories() 和 link_directories() CMake 函数添加其他包含或链接路径。

Win32 构建

为 Windows 构建 deqp 模块最简单的方法是使用 CMake 构建系统。您需要使用 CMake 2.6.12 或更高版本以及 Microsoft Visual C/C++ 编译器。deqp 已通过 Visual Studio 2013 测试。

可以使用以下命令生成 Visual Studio 项目文件：

cmake path\to\src\deqp -G "Visual Studio 12"

选择“Visual Studio VERSION Win64”作为 build 生成器可制作 64 位 build：

cmake path\to\src\deqp -G "Visual Studio 12 Win64"

您还可以通过 -G "NMake Makefiles" 选项以及构建类型（-DCMAKE_BUILD_TYPE="Debug" 或 "Release"）生成 NMake Makefile。

创建渲染上下文

渲染上下文可通过 WGL 或 Windows 上的 EGL 进行创建。

WGL 支持

所有 Win32 二进制文件都支持使用 WGL 创建 GL 上下文，因为它只需要标准库。使用 --deqp-gl-context-type=wgl 命令行参数可以选择 WGL 上下文。在 WGL 模式下，deqp 使用 WGL_EXT_create_context_es_profile 扩展程序创建 OpenGL ES 上下文。经过测试，该程序可与 NVIDIA 和 Intel 的最新驱动程序配合使用。AMD 驱动程序不支持所需的扩展程序。

EGL 支持

如果 DEQP_SUPPORT_EGL 的状态为“ON”（这是大多数目标中的默认状态），则通过动态加载为 Windows 上的 EGL 构建 deqp。接下来，如果主机有可用的 EGL 库，则可以通过命令行参数 --deqp-gl-context-type=egl 对其运行测试。

Android 构建

Android build 使用 CMake build 脚本来构建原生测试代码。Java 部分（即测试执行服务器和测试应用桩）使用标准的 Android build 工具进行编译。

要使用提供的 build 脚本编译 Android 的 deqp 测试程序，您需要：

• 最新版本的 Android NDK；android/scripts/common.py 文件中列出了所需的版本
• Android 独立 SDK（已安装 API 13、SDK 工具、SDK 平台工具和 SDK 构建工具软件包）
• Apache Ant 1.9.4（Java 代码构建所需）
• CMake 2.8.12 或更高版本
• Python 2.6 或更高版本（2.x 系列）；不支持 Python 3.x
• 对于 Windows：PATH 中的 NMake 或 JOM
  • JOM 的构建速度更快
• 可选：Linux 上还支持 Ninja make

Ant 和 SDK 二进制文件的位置取决于具有特定覆盖默认值的 PATH 环境变量。具体逻辑通过 android/scripts/common.py 进行控制。

NDK 目录必须是 ~/android-ndk-VERSION 或 C:/android/android-ndk-VERSION，也可以通过 ANDROID_NDK_PATH 环境变量定义。

deqp 设备组件、测试执行服务和测试程序都是通过执行 android/scripts/build.py 脚本进行构建的。最终 .apk 在 android/package/bin 中创建，并可通过 install.py 脚本进行安装。如果使用命令行执行程序，则可以在设备上通过 adb 使用 launch.py 脚本启动 ExecService。可以从任何目录执行这些脚本。

Linux 构建

通过使用 CMake 生成 Makefile，可以构建适用于 Linux 的测试二进制文件和命令行实用工具。其中有多个预定义的 build 目标对 Linux 构建很有帮助。

始终使用 -DCMAKE_BUILD_TYPE=<Debug|Release> 来定义 build 类型。Release 是一个很实用的默认值。如果没有该值，则默认创建未优化的发布 build。

-DCMAKE_C_FLAGS 和 -DCMAKE_CXX_FLAGS 命令行参数可用于向编译器传递额外的参数。例如，可以通过分别设置 -DCMAKE_C(XX)_FLAGS="-m32" 或 "-m64" 来实现 32 位或 64 位 build。如果未指定，则使用工具链原生架构（通常会为 64 位工具链生成 64 位构建）。

-DCMAKE_LIBRARY_PATH 和 -DCMAKE_INCLUDE_PATH 参数可用于 CMake 为 CMake 提供额外的库或包含搜索路径。

用于针对自定义位置中的驱动程序头文件和库执行 32 位调试 build 的完整命令行示例如下：

cmake <path to src>/deqp -DDEQP_TARGET=x11_egl -DCMAKE_C_FLAGS="-m32"
-DCMAKE_CXX_FLAGS="-m32" -DCMAKE_BUILD_TYPE=Debug
-DCMAKE_LIBRARY_PATH="PATH_TO_DRIVER/lib"
-DCMAKE_INCLUDE_PATH="PATH_TO_DRIVER/inc"
make -j4

交叉编译

使用 CMake 工具链文件可实现交叉编译。工具链文件可指定要使用的编译器，以及用于库和标头的自定义搜索路径。一些适用于常见场景的工具链文件包含在 framework/delibs/cmake 目录下的发布包中。

除了标准的 CMake 变量之外，工具链文件还可以设置以下特定于 deqp 的变量。CMake 通常可以正确检测 DE_OS、DE_COMPILER 和 DE_PTR_SIZE，但 DE_CPU 必须由工具链文件设置。

可使用 CMAKE_TOOLCHAIN_FILE build 参数选择工具链文件。例如，以下代码将使用适用于 ARM/Linux 的 CodeSourcery 交叉编译器为构建创建 Makefile：

cmake PATH_TO_SRC/deqp –DDEQP_BUILD_TYPE="Release"
–DCMAKE_TOOLCHAIN_FILE=PATH_TO_SRC/delibs/cmake/toolchain-arm-cs.cmake
–DARM_CC_BASE=PATH_TO_CC_DIRECTORY

GLES 和 EGL 库的运行时链接

deqp 在链接时期间不需要正在测试的 API 接入点。测试代码始终通过函数指针访问 API。这样接入点便可以在运行时动态加载，或者平台端口也可以在链接时提供接入点。

如果在 build 设置中启用了对 API 的支持且未提供链接库，deqp 将在运行时加载所需的接入点。如果需要使用静态链接，请在 DEQP_<API>_LIBRARIES build 配置变量中提供所需的链接库。

移植测试框架

移植 deqp 需要三个步骤：调整基础可移植性库，实现测试框架平台集成接口以及移植执行服务。

下表列出了可能发生移植更改的位置。在此范围之外的位置很可能是有异常情况。

基础可移植性库

基础可移植性库已支持 Windows、大多数 Linux 变体、Mac OS、iOS 和 Android。若测试目标在其中一个操作系统上运行，很可能根本无需动用基础可移植性库。

测试框架平台端口

deqp 测试框架平台端口需要两个组件：应用入口点和平台接口实现。

应用入口点负责创建平台对象、创建命令行 (tcu::CommandLine) 对象、打开测试日志 (tcu::TestLog) 以及迭代测试应用 (tcu::App)。若目标 OS 支持标准的 main() 入口点，则可以将 tcuMain.cpp 用作入口点实现。

以下文件详细说明了 deqp 平台 API。

所有平台端口的基类都为 tcu::Platform。平台端口可选择性支持 GL 和 EGL 特定接口。请参见下表，大体上了解一下运行测试需要实现的内容。

有关实现平台端口的详细说明，请参阅移植层标头。

测试执行服务

要使用 deqp 测试执行基础架构或命令行执行程序，目标上必须提供测试执行服务。该服务的可移植 C++ 实现在 execserver 目录中提供。独立的二进制文件是作为 PC 目标的 deqp 测试模块 build 的一部分构建的。您可以修改 execserver/CMakeLists.txt 以便在其他目标中启用 build。

C++ 版的测试执行服务接受两个命令行参数：

• --port=<port> 会设置服务器侦听的 TCP 端口。默认端口号为 50016。
• --single 会在客户端断开连接时终止服务器进程。默认情况下，为了进一步处理测试执行请求，服务器进程将保持运行。

运行测试

本页介绍了如何在 Linux 和 Windows 环境中运行 deqp 测试、如何使用命令行参数，以及如何使用 Android 应用包。

Linux 与 Windows 环境

首先，请将以下文件和目录复制到目标中。

您可以在目标文件系统的任意位置部署执行服务和测试二进制文件，但是测试二进制文件需要在当前的工作目录中查找数据目录。准备就绪后，在目标设备上启动测试执行服务。有关如何启动服务的详细信息，请参阅测试执行服务一节。

命令行参数

下表列出了影响所有测试程序执行的命令行参数。

特定于 GLES2 及 GLES3 的参数

测试用例列表格式

测试用例列表有两种格式。第一种选项是在标准 ASCII 文件的单独一行中列出每个测试的全名。随着测试集的增长，重复添加前缀可能会很麻烦。为避免重复添加前缀，可使用以下所示的 trie（也称为前缀树）语法。

{nodeName{firstChild{…},…lastChild{…}}}

例如：

{dEQP-EGL{config-list,create_context{rgb565_depth_stencil}}}

会转换为以下两个测试用例：

dEQP-EGL.config_list
dEQP-EGL.create_context.rgb565_depth_stencil

Android

Android 应用包软件包含所需的所有组件，包括测试执行服务、测试二进制文件和数据文件。测试 activity 是使用 EGL 的 NativeActivity（需要 Android 3.2 或更高版本）。

应用软件包可使用以下命令安装（所示名称为 Android CTS 软件包中 APK 的名称；该名称因 build 而异）：

adb –d install –r com.drawelements.deqp.apk

如需启动测试执行服务并设置端口转发，请使用以下命令：

adb –d forward tcp:50016 tcp:50016
adb –d shell am start –n com.drawelements.deqp/.execserver.ServiceStarter

在开始测试之前，可执行以下命令来启用调试打印：

adb –d shell setprop log.tag.dEQP DEBUG

在没有 Android CTS 的 Android 设备上执行测试

如需手动启动测试执行 activity，请构建一个目标为 android.app.NativeActivity 的 Android intent。可在 com.drawelements.deqp 软件包中找到这些 activity。在 intent 中，命令行必须以含 "cmdLine" 键的额外字符串形式提供。

测试日志会写入 /sdcard/dEQP-log.qpa。若测试运行无法正常启动，请查看设备日志，了解其他调试信息。

您可使用 am 实用程序从命令行启动 activity。例如，如需在支持 NativeActivity, 的平台上运行 dEQP-GLES2.info 测试，请使用以下命令。

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

在 Android 上调试

要采用 Android 系统中的 GDB 调试器运行测试，首先要运行以下两个脚本来编译并安装调试 build：

python android/scripts/build.py --native-build-type=Debug
python android/scripts/install.py

当设备上安装调试 build 后，要采用主机上运行的 GDB 启动测试，请运行以下命令：

python android/scripts/debug.py \
--deqp-commandline="--deqp-log-filename=/sdcard/TestLog.qpa --deqp-case=dEQP-GLES2.functional.*"

deqp 命令行取决于要执行的测试用例和其他所需参数。脚本会在开始执行 deqp 时添加一个默认断点 (tcu::App::App)。

debug.py 脚本接受多个命令行参数用于相关操作，例如：设置调试断点、gdbserver 连接参数及要调试的其他二进制文件的路径（对于所有参数和解释，都执行 debug.py --help）。该脚本还会从目标设备中复制一些默认库，以获取符号列表。

逐步检查驱动程序代码（例如，当 GDB 需要了解具有完整调试信息的二进制文件的位置时），请通过 debug.py 命令行参数添加更多的库。该脚本从脚本文件的第 132 行开始写出 GDB 的配置文件。您还可以提供额外的二进制文件路径等信息，但提供正确的命令行参数就已足够。

注意：在 Windows 上，GDB 二进制文件需要使用 libpython2.7.dll。在启动 debug.py 前，请将 <path-to-ndk>/prebuilt/windows/bin 添加到 PATH 变量中。

注意：原生代码调试不适用于 Android 4.3 及之前的所有版本。有关解决方法，请参阅此公开错误。Android 4.4 及更高版本不包含此错误。

自动化测试

deqp 测试模块可通过多种方式集成到自动化测试系统中。最佳方式取决于现有的测试基础架构和目标环境。

测试运行的主要输出始终是测试日志文件，即带 .qpa 后缀的文件。可以从测试日志中解析得到完整的测试结果。控制台输出仅包含调试信息，并且可能并非在所有平台上都可获得。

测试二进制文件可以直接从测试自动化系统调用。可以针对特定用例、某个测试集或所有可用测试启动测试二进制文件。如果执行期间发生致命错误（如某些 API 错误或系统崩溃），测试执行过程将会中止。对于回归测试，最佳方式是为单个用例或小型测试集单独调用测试二进制文件，以便在发生严重故障时也可获得部分结果。

deqp 附带命令行测试执行工具，这些工具可与执行服务结合使用，以实现更强大的集成。执行器检测测试过程的终止，然后会在下一个可用用例上恢复测试执行过程。由完整测试会话生成单个日志文件。对于不提供崩溃恢复机制的轻量级测试系统而言，该设置是一个理想之选。

命令行测试执行工具

当前的命令行工具集包含以下组件：远程测试执行工具、用于执行回归分析的测试日志比较生成器、测试日志转 CSV 文件的转换器、测试日志转 XML 文件的转换器和测试日志转 JUnit 的转换器。

这些工具的源代码位于 executor 目录中，相关的二进制文件内置于 <builddir>/executor 目录中。

命令行测试执行器

命令行测试执行器是一种便携式 C++ 工具，用于在设备上启动测试运行，并基于 TCP/IP 协议从设备收集生成的日志。该执行器与目标设备上的执行服务 (execserver) 进行通信。二者共同协作，提供从测试过程崩溃恢复等功能。 以下示例演示了如何使用命令行测试执行器（可使用 --help 了解更多详情）：

示例 1：在 Android 设备上运行 GLES2 功能测试

executor --connect=127.0.0.1 --port=50016 --binaryname=
com.drawelements.deqp/android.app.NativeActivity
--caselistdir=caselists
--testset=dEQP-GLES2.* --out=BatchResult.qpa
--cmdline="--deqp-crashhandler=enable --deqp-watchdog=enable
--deqp-gl-config-name=rgba8888d24s8"

示例 2：在本地继续执行部分 OpenGL ES 2 测试

executor --start-server=execserver/execserver --port=50016
--binaryname=deqp-gles2 --workdir=modules/opengl
--caselistdir=caselists
--testset=dEQP-GLES2.* --exclude=dEQP-GLES2.performance.* --in=BatchResult.qpa
--out=BatchResult.qpa

以 CSV 格式导出测试日志并进行比较

deqp 具有将测试日志（.qpa 文件）转换为 CSV 文件的工具。CSV 输出中包含一系列测试用例及其结果。该工具还可以比较两个或多个批处理结果，并仅列出在输入批处理结果中具有不同状态代码的测试用例。该比较还会列出匹配用例的数量。

CSV 格式的输出内容非常实用，可用于通过标准命令行实用程序或电子表格编辑器进行进一步处理。使用命令行参数 --format=text 还可以选择其他人类可读的纯文本格式。

示例 1：以 CSV 格式导出测试日志

testlog-to-csv --value=code BatchResult.qpa > Result_statuscodes.csv
testlog-to-csv --value=details BatchResult.qpa > Result_statusdetails.csv

示例 2：列出两个测试日志中测试结果之间的差异

testlog-to-csv --mode=diff --format=text Device_v1.qpa Device_v2.qpa

注意：参数 --value=code 会输出测试结果代码，如“Pass”或“Fail”。参数 --value=details 可选择对性能、功能或精度测试产生的结果或数值做进一步说明。

以 XML 格式导出测试日志

测试日志文件可以使用 testlog-to-xml 实用程序转换为有效的 XML 文档。日志支持两种输出模式：

• 独立文档模式，其中每个测试用例和 caselist.xml 汇总文档都会写入目标目录；
• 单个文件模式，其中 .qpa 文件中的所有结果都将写入单个 XML 文档。

可使用 XML 样式表在浏览器中查看导出的测试日志文件。 示例样式表文档（testlog.xsl 和 testlog.css）位于 doc/testlog-stylesheet 目录中。若要在浏览器中查看日志文件，可将两个样式表文件复制到导出的 XML 文档所在的同一目录。

如果您使用的是 Google Chrome，则必须通过 HTTP 访问这些文件，因为 Chrome 出于安全考虑，会限制对本地文件的访问。标准的 Python 安装包括一个基本的 HTTP 服务器，该服务器可通过 python –m SimpleHTTPServer 8000 命令启动，以作为当前目录。启动服务器后，只需将 Chrome 浏览器指向 http://localhost:8000 即可查看测试日志。

转换为 JUnit 测试日志

很多测试自动化系统都可以从 JUnit 输出生成测试运行结果报告。可使用 testlog-to-junit 工具将 deqp 测试日志文件转换为 JUnit 输出格式。

该工具目前仅支持转换测试用例判定表。由于 JUnit 仅支持“pass”和“fail”结果，deqp 的通过结果会映射到“JUnit pass”，其他结果则会被视为失败。原始的 deqp 结果代码可从 JUnit 输出中获得。转换时将不会保留日志消息或结果图片等其他数据。

使用特殊测试组

某些测试组可能需要或支持特殊命令行选项，或在特定系统上使用时需要特别注意。

内存分配压力测试

内存分配压力测试会模拟测试内存不足的情况，方法是重复分配特定资源，直到驱动程序报告内存不足错误。

在某些平台（例如 Android 和大多数 Linux 变体）上，可能会发生以下情况：操作系统可能会终止测试进程，而非允许驱动程序处理或以其他方式产生内存不足错误。在此类平台上，旨在产生内存不足错误的测试默认处于停用状态，必须使用 --deqp-test-oom=enable 命令行参数来启用。建议您手动运行此类测试，以检查系统在面临资源压力时是否正常运行。不过在这种情况下，测试过程崩溃应被视为通过测试。

测试组

dEQP-GLES2.stress.memory.*
dEQP-GLES3.stress.memory.*

长时间运行的渲染压力测试

渲染压力测试旨在揭示持续渲染负载下的稳健性问题。默认情况下，测试仅会执行几次迭代，但可通过提供 --deqp-test-iteration-count=-1 命令行参数来配置为无限期运行。如果要长时间运行这些测试，应停用测试监控程序 (--deqp-watchdog=disable)。

测试组

dEQP-GLES2.stress.long.*
dEQP-GLES3.stress.long.*