SYCL* と OpenMP* 開発向けの oneAPI デバッグツール
次に示すツールは、SYCL* および OpenMP* オフロード処理のデバッグに役立ちます。
ツール |
使用方法 |
|---|---|
環境変数 |
環境変数を使用して、プログラムを変更することなく、プログラムの実行時に OpenMP* および SYCL* ランタイムから診断情報を収集できます。 |
GPU 向けのプロファイル・ツールである ze_tracer ツール (GPU 向け PTI) |
SYCL* よび OpenMP* オフロードでインテル® oneAPI レベルゼロと OpenCL* バックエンドを使用する場合、このツールを利用してバックエンドのエラーをデバッグし、ホストとデバイスの両方でパフォーマンスのプロファイルを実行できます。 |
OpenCL* アプリケーションのインターセプト・レイヤー |
SYC*L および OpenMP* オフロードで OpenCL* バックエンドを使用する場合、このライブラリーを利用してバックエンドのエラーをデバッグし、ホストとデバイスの両方でパフォーマンスのプロファイルを実行できます。 |
インテル® ディストリビューションの GDB* |
通常ホストおよびデバイス (CPU、GPU、FPGA エミュレーション) で、論理的なバグを調査する際にアプリケーションのソースレベルのデバッグで使用されます。 |
インテル® Inspector |
このツールは、オフロードの失敗につながる問題を含め、メモリーとスレッドの問題を検出してデバッグするのに役立ちます。 注 インテル® Inspector は、インテル® HPC ツールキットに含まれていましたが、2025.3 リリースからは非推奨となりました。 |
アプリケーション・デバッグ |
これらのツールとランタイムベースのアプローチに加えて、開発者は別のアプローチから問題を見つけることもできます。以下に例を示します:
注 SYCL* と OpenMP* では、どちらもオフロード領域内からの stdout への出力をサポートします。どの SIMD レーンまたはスレッドが出力しているか確認してください。 |
SYCL* 例外ハンドラー |
一部の DPC++ プログラミングのエラーは、プログラムの実行中に SYCL* ランタイムから例外として返されます。これらは、実行時にフラグを使用するコード内のエラーを診断するのに役立ちます。詳細とサンプルについては、「SYCL* 例外」を参照してください。SYCL* 例外のサンプルについては、以下を参照してください: * ガイド付き行列乗算の例外 * ガイド付き行列乗算の無効なコンテキスト * ガイド付き行列乗算の競合状態 |
インテル® Advisor |
Fortran、C、C++、OpenCL* および SYCL* アプリケーションが最新のプロセッサーで最大限のパフォーマンスを発揮するのを支援します。 |
インテル® VTune™ プロファイラー |
ネイティブシステムまたはリモートシステムでパフォーマンス・データを収取して解析します。 |
OpenMP* ディレクティブ |
「インテルツールによる OpenMP* アプリケーションのオフロードと最適化」では、OpenMP* ディレクティブを使用してアプリケーションに並列処理を追加する方法について説明しています。 |
デバッグ環境変数
OpenMP* と SYCL* のオフロードランタイム、およびレベルゼロ、OpenCL*、シェーダーコンパイラーは、ホストとオフロードデバイス間の通信を監視する環境変数を提供します。この環境変数を使用して、オフロード計算向けに選択されたランタイムを検出または制御できます。
OpenMP* オフロード環境変数
OpenMP* オフロードがどのように動作するかを理解し、バックエンドの制御に利用できるいくつかの環境変数が用意されています。
注
OpenMP* は、FPGA デバイスではサポートされません。
環境変数 |
説明 |
|---|---|
LIBOMPTARGET_DEBUG=<Num> |
この環境設定は、OpenMP* オフロードランタイムからのデバッグ出力を有効にします。詳細はランタイムを参照してください。この環境設定は、OpenMP* オフロードランタイムからのデバッグ出力を有効にします。以下が報告されます:
値:
デフォルト: 0 |
LIBOMPTARGET_INFO=<Num> |
この環境変数は、オフロードされた OpenMP* コードのパフォーマンス・データの表示を有効にします。以下を表示します。ユーザーが libomptarget から各種タイプのランタイム情報を要求できるようにします。詳細はランタイム を参照してください。
値: (0, 1, 2, 4, 8, 32) デフォルト: 0 |
LIBOMPTARGET_PLUGIN_PROFILE=<Enable>[,<Unit>] |
この環境変数は、オフロードされた OpenMP* コードのパフォーマンス・データの表示を有効にします。以下を表示します:
値:
デフォルト: 例: <Enable> := 1 | T
<Unit> := usec | unit_usecプラグインの基本的なプロファイルを有効にし、プログラムの終了時に結果を表示します。 |
LIBOMPTARGET_PLUGIN=<Name> |
この環境変数を使用して OpenMP* オフロードの実行に使用するバックエンドを選択できます。 注 レベルゼロのバックエンドは GPU デバイスでのみサポートされます。 <Name> := LEVEL0 | OPENCL | CUDA | X86_64 | NIOS2 |
level0 | opencl | cuda | x86_64 | nios2 |使用するオフロードのプラグイン名を指定します。このオプションを指定すると、オフロードランタイムはほかの RTL をロードしません。 値:
デフォルト:
|
LIBOMPTARGET_PROFILE=<FileName> |
libomptarget が Clang の |
LIBOMPTARGET_DEVICES=<DeviceKind> |
<DeviceKind> := DEVICE | SUBDEVICE | SUBSUBDEVICE | ALL |
device | subdevice | subsubdevice | allサブデバイスをユーザーに公開する方法を制御します。
デフォルト: |
LIBOMPTARGET_LEVEL0_MEMORY_POOL=<Option> |
<Option> := 0 | <PoolInfoList>
<PoolInfoList> := <PoolInfo>[,<PoolInfoList>]
<PoolInfo> := <MemType>[,<AllocMax>[,<Capacity>[,<PoolSize>]]]
<MemType> := all | device | host | shared
<AllocMax> := 正の整数または空、最大割り当てサイズ（MB）
<Capacity> := 正の整数または空、単一ブロックからの割り当て数
<PoolSize> := 正の整数または空、最大プールサイズ（MB）再利用可能なメモリープールの構成を制御します。プールは、単一ブロックから デフォルト: |
LIBOMPTARGET_LEVEL0_STAGING_BUFFER_SIZE=<Num> |
ステージのバッファーサイズを デフォルト: 16 |
LIBOMPTARGET_LEVEL_ZERO_COMMAND_BATCH=<Value> |
<Value> := <Type>[,<Count>]
<Type> := none | NONE | copy | COPY | compute | COMPUTE
<Count> := バッチ処理するコマンドの最大数
ターゲット領域に対してコマンドのバッチ処理を有効にします。``<Type>=none|NONE``: コマンドのバッチ処理を無効にします。``<Type>=copy|COPY``: データ転送のターゲット領域に対するコマンドのバッチ処理を有効にします。``<Type>=compute|COMPUTE``: データ転送と計算にターゲット領域のコマンドバッチ処理を有効にし、コピーエンジンの利用を無効にします。``<Type>`` が ``copy`` または ``compute`` (有効) のいずれかで、``<Count>`` が指定されていないと、ターゲット領域ですべてのコマンドに対してバッチ処理が行われます。**デフォルト**: ``<Type>=none`` (無効) |
LIBOMPTARGET_LEVEL_ZERO_USE_IMMEDIATE_COMMAND_LIST=<Value> |
<True> := 1 | T | t
<False>:= 0 | F | f
<Bool>:= <True> | <False>
<Value> := <Bool> | compute | COMPUTE | copy | COPY | all | ALLcompute: カーネル送信に即時コマンドリストの処理を有効にしますcopy: メモリーコピー操作に即時コマンドリストの処理を有効にしますall: カーネル送信メモリーコピー操作に即時コマンドリストの処理を有効にします<True>: compute と等価です<False>: 即時コマンドリストは無効です。デフォルト: “all” |
OMP_TARGET_OFFLOAD=MANDATORY |
これは OpenMP* 仕様で定義されています: https:// www.openmp.org/spec-html/5.1/ openmpse74.html#x340-515000617 (英語) |
ONEAPI_DEVICE_SELECTOR |
このデバイス選択環境変数によって、OpenMP* アプリケーションの実行時に使用するデバイスの選択を制御できます。デバイスを特定のタイプ (GPU やアクセラレーター) またはバックエンド (レベルゼロや OpenCL*) に制限するのに役立ちます。ONEAPI_DEVICE_SELECTOR の構文は OpenMP* と共有されており、デバイスを可能にします。詳しい説明は、インテル® oneAPI DPC++ コンパイラーのドキュメントを参照してください。インテル® oneAPI DPC++ コンパイラーのドキュメント (英語) を参照してください。 |
SYCL* と DPC++ 環境変数
インテル® oneAPI DPC++ コンパイラーは、すべての標準 SYCL* 環境変数をサポートします。すべての環境変数については GitHub をご覧ください。デバッグで注目すべきは、次の SYCL 環境変数と追加のレベルゼロ環境変数です。
環境変数 |
説明 |
|---|---|
ONEAPI_DEVICE_SELECTOR |
この複雑な環境変数を使用すると、ランタイムで使用されるランタイム、計算デバイス ID を利用可能なすべての組み合わせのサブセットに制御できます。 計算デバイス ID は、SYCL* API、 詳細については、GitHub にある環境変数の説明をご覧ください: https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md (英語) 次のような値を含みます:
デフォルト: 利用可能なすべてのランタイムとデバイスを使用します |
ONEAPI_DEVICE_SELECTOR |
このデバイス選択環境変数によって、SYCL* ベースのアプリケーションの実行時に使用するデバイスの選択を制御できます。デバイスを特定のタイプ (GPU やアクセラレーター) またはバックエンド (レベルゼロや OpenCL*) に制限するのに役立ちます。このデバイス選択のメカニズムは、ONEAPI_DEVICE_SELECTOR を置き換えるものです。ONEAPI_DEVICE_SELECTOR の構文は OpenMP* と共有されており、デバイスを可能にします。インテル® oneAPI DPC++ コンパイラーのドキュメントを参照してください: https://intel.github.io/llvm/EnvironmentVariables.html (英語) |
SYCL_UR_TRACE |
この環境設定は、ランタイムからのデバッグ出力を有効にします。 値:
デフォルト: 無効 |
ZE_DEBUG |
この環境変数は、ランタイムが使用された際にレベルゼロ・バックエンドからのデバッグ出力を有効にします。以下が報告されます:
値: 任意の値で定義された変数 (有効) デフォルト: 無効 |
サポート向けの診断情報を生成する環境変数
レベルゼロ・バックエンドは、動作を制御して診断を支援するいくつかの環境変数を提供します。
デバッグ情報の追加リソースは、実行時または事前コンパイル (AOT) 時に、レベルゼロまたは OpenCL* バックエンド (OpenMP* オフロードと SYCL*/DPC++ ランタイムで使用される) によって呼び出されるインテル® グラフィックス・コンパイラーから提供されます。インテル® グラフィックス・コンパイラーは、ターゲットのオフロードデバイス向けの実行形式コードを生成します。これらの環境変数の完全なリストは、https://github.com/intel/intel-graphics-compiler/blob/master/documentation/configuration_flags.md (英語) にあります。パフォーマンスの問題をデバッグする際に必要となるのは、次の 2 つです:
IGC_ShaderDumpEnable=1 (デフォルト=0)の場合、インテル® グラフィックス・コンパイラーによって生成されたすべての LLVM、アセンブリー、および ISA コードが/tmp/IntelIGC/<application_name>に書き込まれます。IGC_DumpToCurrentDir=1 (デフォルト = 0)は、IGC_ShaderDumpEnableによって作成されたすべてのファイルを/tmp/IntelIGC/<application_name>ではなく現在のディレクトリーに書き込みます。多数のファイルが生成される可能性があるため、一時ディレクトリーを作成することを推奨します。
インテル® oneAPI の異なるバージョン間で生じる OpenMP* オフロードや SYCL* オフロード・アプリケーションのパフォーマンスの問題がある場合、異なるコンパイラー・オプションを使用したり、デバッガーを使用するなど、IGC_ShaderDumpEnable を有効にして結果ファイルを提供することが必要となる場合がります。互換性の詳細については、oneAPI ライブラリーの互換性を参照してください。
オフロード・インターセプト・ツール
オフロード・ソフトウェア自身に組み込まれているデバッガーと診断情報に加えて、オフロード・パイプラインを介して送信される API 呼び出しとデータを監視するのは有益です。レベルゼロでは、アプリケーションが onetrace または ze_tracer ツールの引数として実行される場合、アプリケーションのレベルゼロのさまざまな動作がインターセプトされ報告されます。OpenCL* では、OpenCL* 呼び出しをインターセプトして報告するライブラリーを LD_LIBRARY_PATH に追加して、環境変数を設定しファイルへの診断情報生成を制御できます。また、onetrace または cl_tracer を使用して、アプリケーションの OpenCL* API 呼び出しのさまざまな情報をレポートすることもできます。ここでも、アプリケーションは onetrace や cl_tracer ツールへの引数として実行されます。
OpenCL* アプリケーションのインターセプト・レイヤー
このライブラリーは、SYCL* または OpenMP* オフロードのバックエンドとして OpenCL* が使用される場合にデバッグおよびパフォーマンス・データを収集します。OpenCL* が SYCL* または OpenMP* オフロードのバックエンドである場合、このツールはバッファーのオーバーライト、メモリーリーク、ポインターの不一致を検出し、ランタイム・エラー・メッセージのより詳しい情報を提供します (CPU、FPGA、または GPU のいずれかが計算デバイスである場合にこれらの問題を診断できます)。OpenCL* バックエンドを使用するプログラムで onetrace を利用する場合や、レベルゼロ・バックエンドを使用するプログラムで OpenCL* アプリケーション・ライブラリーのインターセプト・レイヤーを利用する場合には、あまり有用ではないことに注意してください。
関連情報
OpenCL* アプリケーションのインターセプト・レイヤーのビルドと使用法に関する各種情報は、https://github.com/intel/opencl-intercept-layer (英語) から入手できます。
注
最良の結果を得るには、次のフラグを使用して
cmakeを実行します:-DENABLE_CLIPROF=TRUE -DENABLE_CLILOADER=TRUE同様のツール (CLIntercept) に関する情報は、https://github.com/gmeeker/clintercept (英語) および https://sourceforge.net/p/clintercept/wiki/Home/ (英語) で入手できます。
OpenCL* アプリケーションのインターセプト・レイヤーのコントロールに関する情報は、https://github.com/intel/opencl-intercept-layer/blob/master/docs/controls.md (英語) にあります。
GPU の最適化に関する情報は、oneAPI GPU 最適化ガイドから入手できます。
GPU 向けのプロファイル・ツールのインターフェイス (onetrace、cl_tracer および ze_trace)
OpenCL* アプリケーションのインターセプト・レイヤーと同様に、これらツールは、レベルゼロが SYCL* または OpenMP* バックエンドである場合にデバッグおよびパフォーマンス・データを収集します。レベルゼロは、GPU で実行される計算のバックエンドとしてのみ利用できることに注意してください (現時点で、CPU と FPGA 向けのレベルゼロ・バックエンドはありません)。ze_tracer ツールは、https://github.com/intel/pti-gpu (英語) にある GPU 向けのプロファイル・ツール・インターフェイス (GPU 向け PTI) プロジェクトの一部です。このプロジェクトには、レベルゼロまたは OpenCL* オフロード・バックエンドからのアクティビティーのみをトレースする ze_tracer や cl_tracer ツールも含まれています。ze_tracer および cl_tracer ツールは、他のバックエンドを使用するアプリケーションで使用されると、出力を生成しませんが、onetrace は使用するオフロード・バックエンドに関わりなく出力できます。
onetrace ツールはソースで配布されています。ツールのビルドに関する手順は、https://github.com/intel/pti-gpu/tree/master/tools/onetrace (英語) で入手できます。このツールは次の機能を提供します:
呼び出しのログ: このモードでは、すべての標準レベルゼロ (L0) および OpenCL* API 呼び出しとその引数、およびタイムスタンプ付きの戻り値をトレースできます。これにより、ホストプログラムが接続された計算デバイスを利用する際に発生する障害の補足情報が得られます。
ホストとデバイスのタイミング: すべての API 呼び出しの存続期間、カーネルの存続期間、およびアプリケーション全体の実行時間を提供します。
デバイス・タイムライン・モード: 各デバイス・アクティビティーのタイムスタンプを提供します。すべてのタイムスタンプは、同じ (CPU) 時間スケールで示されます。
chrome://tracing browser tool (英語) で開くことができる JSON 形式への API 呼び出しをダンプします。
このデータはオフロードの障害やパフォーマンスの問題をデバッグするのに役立ちます。
関連情報
インテル® ディストリビューションの GDB*
インテル® ディストリビューションの GDB* は、プログラムの状態を調査および変更できるアプリケーション・デバッガーです。アプリケーションのホスト部分とデバイスにオフロードされたカーネルの両方を、同じデバッグセッションでシームレスにデバッグできます。このデバッガーは、CPU、GPU、および FPGA エミュレーション・デバイスをサポートします。主な機能を以下に示します。
GPU デバイスに自動的に接続してデバッグイベントを監視します
デバッグ用に JIT コンパイルされた、または動的にロードされたカーネルバイナリーを自動的に検出します
プログラムの実行を停止するブレークポイントの設定 (カーネル内部と外部の両方)
スレッドのリスト表示。現在のスレッド・コンテキストへの切り替え
アクティブな SIMD レーンのリスト表示。現在の SIMD レーンのコンテキストをスレッドごとに切り替え
複数のスレッドと SIMD レーン・コンテキストの式値の評価と出力
レジスター値の調査と変更
マシン命令の逆アセンブル
関数呼び出しスタックの表示とナビゲート
ソースと命令レベルのステップ実行
非停止およびすべて停止のデバッグモード
インテル® プロセッサー・トレースを使用した実行の記録 (CPU のみ)
インテル® ディストリビューションの GDB* の詳細とドキュメントへのリンクは、「インテル® ディストリビューションの GDB* の導入ガイド Linux* ホスト (英語) | Windows* ホスト (英語)」をご覧ください。
オフロード向けインテル® Inspector
インテル® Inspector は、シリアルおよびマルチスレッド・アプリケーションを開発するユーザー向けの動的メモリーおよびスレッドエラーを検出するツールです。動的に生成されたオフロードコードだけでなく、アプリケーションのネイティブコードの正当性を検証するのに利用できます。
前述のツールや手法とは異なり、インテル® Inspector は GPU または FPGA と通信するオフロードコードのエラーを検出することはできません。インテル® Inspector では、CPU をターゲットとしてカーネルを実行するように SYCL* または OpenMP* ランタイムを設定する必要があります。解析を実行する前に、次の環境変数を設定する必要があります。
CPU デバイスでカーネルを実行するように SYCL* アプリケーションを設定します
export ONEAPI_DEVICE_SELECTOR=opencl:cpu
CPU デバイスでカーネルを実行するように OpenMP アプリケーションを設定します
export OMP_TARGET_OFFLOAD=MANDATORY export LIBOMPTARGET_DEVICETYPE=cpu
JIT コンパイラーまたはランタイムでコード解析とトレース有効にします
export CL_CONFIG_USE_VTUNE=True export CL_CONFIG_USE_VECTORIZER=false
次のいずれかのコマンドを使用して、コマンドラインから解析を開始します。インテル® Inspector のグラフィカル・ユーザー・インターフェイスからも開始できます。
メモリー:
inspxe-cl -c mi3 -- <app> [app_args]スレッド化:
inspxe-cl -c ti3 -- <app> [app_args]
次のコマンドを使用して解析結果を表示します: inspxe-cl -report=problems -report-all
SYCL* や OpenMP* オフロードプログラムが OpenCL* バックエンドに不正なポインターを渡したり、誤ったスレッドからバックエンドに不正なポインターを渡す場合、インテル® Inspector は問題を警告します。これは、インターセプト・レイヤーやデバッガーを使用して問題を見つけるよりも容易な場合があります。
インテル® Inspector ユーザーガイドで詳細を参照できます (Linux* (英語) | Windows* (英語))。