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 或透過 git 從 platform/external/[libpng,zlib] 擷取。

建立測試計畫

測試架構的設計考量到可攜性，唯一必要條件是完整支援 C++，以及用於 I/O、執行緒和通訊端的標準系統程式庫。

CMake 建構系統

deqp 來源含有 CMake 的建構指令碼，這是編譯測試程式的首選工具。

CMake 是開放原始碼的建構系統，支援多個平台和工具鍊。CMake 會從與目標無關的設定檔產生原生 Makefile 或 IDE 專案檔。如要進一步瞭解 CMake，請參閱 CMake 說明文件。

CMake 支援並建議使用來源樹狀目錄外的建構作業，也就是說，您應一律在來源樹狀目錄外的獨立建構目錄中，建立 Makefile 或專案檔案。CMake 沒有任何「distclean」目標，因此必須手動移除 CMake 產生的檔案。

設定選項會使用 -DOPTION_NAME=VALUE 語法提供給 CMake。以下列出一些常用的 deqp 選項。

建立目標建構檔案

系統會使用目標建構檔案，為新目標設定 deqp 建構系統。目標建構檔案會定義平台支援的功能，以及所需的程式庫或額外包含路徑。目標檔案名稱遵循 targets/NAME/NAME.cmake 格式，並使用 DEQP_TARGET 建構參數選取目標。

目標檔案中的檔案路徑是相對於基本 deqp 目錄，而非 targets/NAME 目錄。目標建構檔案可設定下列標準變數。

目標建構檔案可以使用 include_directories() 和 link_directories() CMake 函式，新增其他 include 或連結路徑。

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"

如要建構 64 位元版本，請選取「Visual Studio VERSION Win64」做為建構產生器：

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

您也可以使用 -G "NMake Makefiles" 選項和建構類型 (-DCMAKE_BUILD_TYPE="Debug" 或 "Release") 產生 NMake makefile。

建立算繪環境

您可以在 Windows 上使用 WGL 或 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 上使用動態載入功能建構 deqp 的 EGL。大多數目標預設會採用這項設定。接著，如果主機有可用的 EGL 程式庫，即可使用指令列參數 --deqp-gl-context-type=egl 執行測試。

Android 版本

Android 建構作業會使用 CMake 建構指令碼，建構原生測試程式碼。Java 部分 (即測試執行伺服器和測試應用程式 Stub) 是使用標準 Android 建構工具編譯。

如要使用提供的建構指令碼編譯 Android 適用的 deqp 測試程式，您需要：

• 最新版 Android NDK；android/scripts/common.py 檔案會列出必要版本
• 已安裝 API 13 的 Android 獨立 SDK、SDK 工具、SDK 平台工具和 SDK 建構工具套件
• Apache Ant 1.9.4 (Java 程式碼建構作業需要此工具)
• CMake 2.8.12 以上版本
• 2.x 系列的 Python 2.6 以上版本；不支援 Python 3.x
• Windows：PATH
  • JOM 可加快建構速度
• 選用：Linux 也支援 Ninja make

系統會根據 PATH 環境變數和特定覆寫預設值，找出 Ant 和 SDK 二進位檔。這項邏輯是由 android/scripts/common.py 控制。

NDK 目錄必須是 ~/android-ndk-VERSION 或 C:/android/android-ndk-VERSION，或是透過 ANDROID_NDK_PATH 環境變數定義。

執行 android/scripts/build.py 指令碼即可建構裝置端 Deqp 元件、測試執行服務和測試程式。最終的 .apk 會在 android/package/bin 中建立，並可由 install.py 指令碼安裝。如果使用指令列執行器，系統會透過 ADB 在裝置上啟動 ExecService 和 launch.py 指令碼。這些指令碼可從任何目錄執行。

Linux 建構版本

您可以使用 CMake 產生 Makefile，為 Linux 建構測試二進位檔和指令列公用程式。為 Linux 建構時，有多個預先定義的建構目標相當實用。

請一律使用 -DCMAKE_BUILD_TYPE=<Debug|Release> 定義建構類型。Release 是不錯的預設值。如果沒有這個檔案，系統會建立未經最佳化的預設發布版本。

-DCMAKE_C_FLAGS 和 -DCMAKE_CXX_FLAGS 指令列引數可用於將額外引數傳遞至編譯器。舉例來說，您可以分別設定 -DCMAKE_C(XX)_FLAGS="-m32" 或 "-m64"，建構 32 位元或 64 位元版本。如未指定，系統會使用工具鍊原生架構，通常是 64 位元工具鍊上的 64 位元架構。

CMake 可使用 -DCMAKE_LIBRARY_PATH 和 -DCMAKE_INCLUDE_PATH 引數，提供額外的程式庫或包含搜尋路徑。

以下範例顯示完整指令列，用於針對自訂位置的驅動程式標頭和程式庫，執行 32 位元偵錯建構作業：

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 建構參數選取工具鍊檔案。舉例來說，下列指令會使用適用於 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。然後，系統可以在執行階段動態載入進入點，或平台埠可以在連結時提供進入點。

如果在建構設定中啟用 API 支援，但未提供連結程式庫，deqp 會在執行階段載入必要的進入點。如要進行靜態連結，請在 DEQP_<API>_LIBRARIES 建構設定變數中提供必要的連結程式庫。

移植測試架構

移植 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 目錄中。獨立二進位檔是為電腦目標建構 deqp 測試模組時的一部分。您可以修改 execserver/CMakeLists.txt，在其他目標上啟用建構作業。

測試執行服務的 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 應用程式套件包含所有必要元件，包括測試執行服務、測試二進位檔和資料檔案。測試活動是使用 EGL 的 NativeActivity (需要 Android 3.2 以上版本)。

您可以使用下列指令安裝應用程式套件 (顯示的名稱是 Android CTS 套件中的 APK 名稱，名稱取決於建構作業)：

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

如要手動啟動測試執行活動，請建構以 android.app.NativeActivity 為目標的 Android 意圖。活動可於 com.drawelements.deqp 套件中找到。指令列必須以額外字串的形式提供，並在 Intent 中使用 "cmdLine" 鍵。

測試記錄會寫入 /sdcard/dEQP-log.qpa。如果測試執行作業無法正常啟動，裝置記錄中會提供額外的偵錯資訊。

您可以使用 am 公用程式，從指令列啟動活動。舉例來說，如要在支援 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 偵錯工具下執行測試，請先執行下列兩個指令碼，編譯並安裝偵錯版本：

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

在裝置上安裝偵錯版本後，如要在主機上執行的 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 樣式表，在瀏覽器中查看匯出的測試記錄檔。doc/testlog-stylesheet 目錄中提供樣式表文件範例 (testlog.xsl 和 testlog.css)。如要在瀏覽器中呈現記錄檔，請將兩個樣式表檔案複製到匯出 XML 文件所在的目錄。

如果您使用 Google Chrome，必須透過 HTTP 存取檔案，因為 Chrome 會基於安全考量限制本機檔案存取權。標準 Python 安裝套件包含基本 HTTP 伺服器，可啟動並使用 python –m SimpleHTTPServer 8000 指令提供目前目錄。啟動伺服器後，只要將 Chrome 瀏覽器指向 http://localhost:8000，即可查看測試記錄。

轉換為 JUnit 測試記錄

許多測試自動化系統都能從 JUnit 輸出內容產生測試執行結果報表。您可以使用 testlog-to-junit 工具，將 deqp 測試記錄檔轉換為 JUnit 輸出格式。

這項工具目前僅支援翻譯測試案例的結果。由於 JUnit 只支援「通過」和「失敗」結果，因此 deqp 的通過結果會對應至「JUnit 通過」，其他結果則視為失敗。原始 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.*