drawElements Quality Program テスト

AOSP には、drawElements Quality Program（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 ビルド パラメータを使用して選択します。

ターゲット ファイル内のファイルパスは、targets/NAME ディレクトリではなく deqp ベース ディレクトリに対する相対パスです。ターゲット ビルドファイルによって以下の標準変数を設定できます。

ターゲット ビルドファイルで 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"

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 コンテキストの作成がサポートされます。WGL コンテキストは、--deqp-gl-context-type=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 ビルドでは、ネイティブ テストコードのビルドに CMake ビルド スクリプトを使用します。テスト実行サーバーやテストアプリ スタブなど、Java を使用する部分は、標準の Android ビルドツールを使用してコンパイルされます。

提供されたビルド スクリプトを使用して Android の deqp テスト プログラムをコンパイルするには、以下が必要です。

• 最新バージョンの Android NDK（android/scripts/common.py ファイルに必要なバージョンがリストされています）
• API 13、SDK Tools、SDK Platform Tools、SDK Build Tools パッケージがインストールされた Android スタンドアロン SDK
• Apache Ant 1.9.4（Java コードビルドで必要）
• CMake 2.8.12 以降
• 2.x シリーズの Python 2.6 以降（Python 3.x はサポートされていません）
• Windows の場合: NMake または JOM（PATH が通ったディレクトリにあること）
  • 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 ビルド

Linux 用にテストバイナリとコマンドライン ユーティリティをビルドするには、CMake を使用して makefile を生成します。Linux 向けのビルドを行う際に有用な複数のビルド ターゲットが事前に定義されています。

必ず -DCMAKE_BUILD_TYPE=<Debug|Release> を使用してビルドタイプの定義を行うようにしてください。適切なデフォルトは Release です。これを使用しない場合は、デフォルトの最適化されていないリリースビルドが作成されます。

-DCMAKE_C_FLAGS と -DCMAKE_CXX_FLAGS のコマンドライン引数を使用して、追加の引数をコンパイラに渡すことができます。たとえば、32 ビットまたは 64 ビットのビルドを行うには、それぞれ -DCMAKE_C(XX)_FLAGS="-m32" または "-m64" を設定します。これを指定しないと、ツールチェーンのネイティブ アーキテクチャ（通常、64 ビットのツールチェーンでは 64 ビット）が使用されます。

CMake は -DCMAKE_LIBRARY_PATH 引数と -DCMAKE_INCLUDE_PATH 引数を使用して、CMake の追加ライブラリを渡す、または検索パスを追加することができます。

次の例は、特定の場所にあるドライバ ヘッダーおよびライブラリに対して 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 の移植は、ベース ポータビリティ ライブラリの適合化、テストフレームワーク プラットフォーム統合インターフェースの実装、実行サービスの移植という 3 つのステップで構成されます。

次の表に、移植による変更の可能性がある場所を示します。これら以外の変更はまれです。

ベース ポータビリティ ライブラリ

ベース ポータビリティ ライブラリでは、Windows、ほとんどの Linux、Mac OS、iOS、Android がすでにサポートされています。テスト ターゲットがこれらのオペレーティング システムのいずれかで実行されている場合、ベース ポータビリティ ライブラリで必要な手順はほぼないと考えられます。

テスト フレームワークのプラットフォーム ポート

deqp テスト フレームワークのプラットフォーム ポートには、アプリ エントリ ポイントとプラットフォーム インターフェース実装の 2 つのコンポーネントが必要です。

アプリのエントリ ポイントは、プラットフォーム オブジェクトとコマンドライン（tcu::CommandLine）オブジェクトを作成し、テストログ（tcu::TestLog）を開いて、テストアプリ（tcu::App）を反復処理します。ターゲット OS が標準の main() エントリ ポイントをサポートしている場合は、エントリ ポイントの実装として tcuMain.cpp を使用できます。

deqp プラットフォーム API の詳細は、次のファイルに記述されています。

すべてのプラットフォーム ポートの基本クラスは tcu::Platform です。プラットフォーム ポートは、GL 固有および EGL 固有のインターフェースにも対応しています。テストの実行に必要な実装の概要については、次の表をご覧ください。

プラットフォーム ポートを実装する際の詳しい手順については、移植レイヤのヘッダーに記載されています。

テスト実行サービス

deqp テスト実行インフラストラクチャまたはコマンドライン エグゼキュータを使用するには、テスト実行サービスをターゲットで使用できる必要があります。サービスのポータブルな C++ 実装は、execserver ディレクトリにあります。スタンドアロン バイナリは、PC ターゲット向けの deqp テスト モジュール ビルドの一部としてビルドされます。execserver/CMakeLists.txt を変更して、他のターゲットでビルドを有効にできます。

C++ バージョンのテスト実行サービスは、次の 2 つのコマンドライン パラメータを受け取ります。

• --port=<port> はサーバーがリッスンする TCP ポートを設定します。デフォルトは 50016 です。
• --single を指定すると、クライアントの接続が解除されたときにサーバー プロセスを終了します。デフォルトでは、以降のテスト実行リクエストを処理するためにサーバー プロセスが維持されます。

テストを実行する

このページでは、Linux および Windows 環境での deqp テストの実行、コマンドライン引数の使用、Android アプリ パッケージの利用について説明します。

Linux 環境と Windows 環境

まず、次のファイルとディレクトリをターゲットにコピーします。

実行サービスとテストバイナリは、ターゲット ファイル システムの任意の場所にデプロイできます。ただし、テストバイナリはデータ ディレクトリが現在の作業ディレクトリ下にあることを想定しています。準備ができたら、ターゲット デバイスでテスト実行サービスを起動します。サービスの起動の詳細については、テスト実行サービスをご覧ください。

コマンドライン引数

次の表に、すべてのテスト プログラムの実行に影響するコマンドライン引数を示します。

GLES2 と GLES3 に固有の引数

テストケースのリスト形式

テストケースのリストは、2 つの形式で指定できます。1 つ目は、標準 ASCII ファイルで各テストの完全な名前を 1 行に 1 つずつ記述する方法です。テストセットが増えると、プレフィックスの繰り返しが煩雑になる可能性があります。プレフィックスの繰り返しを避けるには、次の trie（プレフィックス ツリーとも呼ばれる）構文を使用します。

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

次に例を示します。

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

次の 2 つのテストケースに変換されます。

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 パッケージ内にあります。コマンドラインは、インテントでキー "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 デバッガによるテストを実行するには、まず次の 2 つのスクリプトを実行し、デバッグビルドをコンパイルしてインストールします。

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 変数に <path-to-ndk>/prebuilt/windows/bin を追加してください。

注: ストック Android 4.3 ではネイティブ コードのデバッグが機能しません。回避策については、公開バグをご覧ください。Android 4.4 以降にはこのバグが含まれていません。

テストを自動化する

deqp テスト モジュールは、複数の方法で自動テストシステムに統合できます。既存のテスト インフラストラクチャとターゲット環境によって最適な方法は異なります。

テスト実行のメイン出力は、常にテストログ ファイル（つまり .qpa 接尾辞付きのファイル）です。完全なテスト結果は、テストログから解析できます。コンソール出力はデバッグ情報のみであり、一部のプラットフォームでは使用できない場合があります。

テストバイナリは、テスト自動化システムから直接呼び出すことができます。特定のケース、テストセット、または使用可能なすべてのテストに対してテストバイナリを起動できます。実行中に致命的なエラーが発生した場合（特定の API エラーやクラッシュなど）、テストの実行は中止されます。回帰テストでは、ハードエラーが発生した場合でも部分的な結果を得られるように、各ケースまたは小規模なテストセットに対してテストバイナリを個別に呼び出す方法をおすすめします。

deqp にはコマンドライン テスト実行ツールが用意されており、実行サービスと組み合わせて使用すれば、より堅牢な統合を実現できます。エグゼキュータはテストプロセスの終了を検出し、次の使用可能なケースでテスト実行を再開します。完全なテスト セッションから生成されるログファイルは 1 つです。この設定は、クラッシュ リカバリ機能を備えていない軽量テストシステムに適しています。

コマンドライン テスト実行ツール

現在のコマンドライン ツールセットには、リモートテスト実行ツール、回帰分析用のテストログ比較生成ツール、テストログ - CSV 変換ツール、テストログ - XML 変換ツール、テストログ - JUnit 変換ツールが含まれます。

これらのツールのソースコードは executor ディレクトリにあり、バイナリは <builddir>/executor ディレクトリにビルドされます。

コマンドライン テスト エグゼキュータ

コマンドライン テスト エグゼキュータは、デバイスでテスト実行を開始し、TCP/IP 経由で結果ログを収集するポータブルな C++ ツールです。エグゼキュータは、ターゲット デバイス上の実行サービス（execserver）と通信します。この 2 つの連携により、テストプロセスのクラッシュから復旧する機能などが提供されます。次の例は、コマンドライン テスト エグゼキュータの使用方法を示したものです（詳細については、--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: 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 ドキュメントに変換できます。次の 2 つの出力モードがサポートされています。

• 個別ドキュメント モードでは、各テストケースと caselist.xml サマリー ドキュメントが宛先ディレクトリに書き込まれます。
• 単一ファイルモードでは、.qpa ファイルのすべての結果が単一の XML ドキュメントに書き込まれます。

エクスポートされたテストログ ファイルは、XML スタイルシートを使用してブラウザで表示できます。doc/testlog-stylesheet ディレクトリには、スタイルシート ドキュメントのサンプル（testlog.xsl と testlog.css）があります。ブラウザでログファイルをレンダリングするには、エクスポートした XML ドキュメントがあるディレクトリに 2 つのスタイルシート ファイルをコピーします。

Google Chrome を使用している場合は、セキュリティ上の理由でローカル ファイルへのアクセスが制限されるため、HTTP 経由でファイルにアクセスする必要があります。標準の Python インストールには、python –m SimpleHTTPServer 8000 コマンドで起動できる基本的な HTTP サーバーが用意されており、現在のディレクトリ内容を提供することができます。サーバーを起動したら、Chrome ブラウザで http://localhost:8000 を指定すればテストログが表示されます。

JUnit テストログへの変換

多くのテスト自動化システムでは、JUnit 出力からテスト実行結果レポートを生成できます。deqp テストログ ファイルを JUnit 出力形式に変換するには、テストログ - 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.*