インテル® C++ コンパイラー 14.0 ユーザー・リファレンス・ガイド

offload

文をターゲット上で実行します。 このプラグマは、インテル® MIC アーキテクチャーおよびインテル® グラフィックス・テクノロジーにのみ適用されます。 インテル® グラフィックス・テクノロジーはプレビュー機能です。

構文

#pragma offload clause[, clause...]

<expression-stmt>

clause は、次の必須かオプション指示節のいずれかです。

必須の指示節

オプション指示節

引数

必須の指示節

offload-parameter

ホストとターゲット間でコピーされるプログラム変数とデータの量を制御します。clause (節) は次のいずれかです。

in

ターゲット領域への入力に使用する変数。この値はターゲット領域が完了した後にターゲットからホストにコピーされません。

構文: in ( variable-ref [, variable-ref …] [ modifier [ modifier … ] ] )

out

ターゲット領域の出力に使用する変数。 ホストはこの変数をターゲットにコピーしません。

構文: out ( variable-ref [, variable-ref …] [ modifier [ modifier … ] ] )

inout

ホストからターゲットおよびターゲットからホストにコピーされる変数。

構文: inout ( variable-ref [, variable-ref …] [ modifier [ modifier … ] ] )

nocopy

以前のターゲットの実行から再利用される値、またはオフロードされたコードセクション内で使用される値を含む変数は、コピーを防ぐために nocopy 節にリストします。

構文: nocopy ( variable-ref [, variable-ref …] [ modifier [ modifier … ] ] )

pin

ホストとターゲット間で値が共有される変数。

構文: pin ( variable-ref [, variable-ref …] [ modifier [ modifier … ] ] )

転送のために選択されるデータは、(オフロード構造内で字句的に参照されるために) 暗黙で転送される変数と、offload-parameter で明示的にリストされる変数の組み合わせです。

in または outelement-count-expr 式 (後述の modifier の説明を参照) は、式が記述される文または節の前で評価されます。

宣言からサイズが分かる配列変数は全体でコピーされます。 配列のサブセットを処理する場合、サブセットの開始要素へのポインターと element-count-expr を使用して配列のサブセットを転送します。

in 節にリストされないデータポインター変数は構造内で初期化されないため、逆参照できるようになる前に値を割り当てる必要があります。

この引数の変数は次のとおりです。

variable-ref

次のいずれかです。

  • C/C++ 識別子。

  • variable-ref.identifier: この引数の変数には次の構文を使用します。

    • var : length ( l)

    • var [ 0 : length ]

  • array-slice: 1 つの連続する配列要素のセットを表す式です。

modifier

次のいずれかです。

  • align (expression): expression の値は 2 の累乗でなければなりません。 この修飾子はポインター変数に適用され、ターゲットで割り当てたポインターデータの最小アライメントに合わせます。

  • alloc (array-slice): array-slice は、割り当てが必要な配列要素のセットを指定します。 in/ out 式で指定されたデータは、ターゲット上に割り当てられた配列の対応する部分に転送されます。

    この修飾子の引数には次の構文を使用します。

    • var : length ( l)

    • var [ 0 : length ]

    詳細は、「部分配列の一部へのメモリー割り当て」を参照してください。

  • alloc_if (condition): condition は、in 節の割り当て変数に割り当てられているメモリーを割り当てるかどうかを制御するブーリアン論理条件を指定します。 式が TRUE と評価されると、節でリストされている各変数に新しいメモリーが割り当てられます。 条件が FALSE と評価されると、ターゲットにすでに割り当てられている値が再利用されます (データ保持)。 前のオフロードに対して free_if (0) 節を使用し、十分なサイズのメモリーブロックがターゲットの変数に割り当てられていることを確認する必要があります。

    この修飾子のデフォルト設定は次のとおりです。

    修飾子

    デフォルト設定

    in

    true

    inout

    true

    out

    true

    nocopy

    false

  • free_if (condition): in 節の割り当て変数に割り当てたメモリーを解放するかどうかを制御するブーリアン論理条件を指定します。 条件が FALSE と評価されると、リストの各変数に割り当てられたメモリーに対する操作は行われません。 割り当てられたメモリーは後の節で再利用できます (データ保持)。

    この修飾子のデフォルト設定は次のとおりです。

    修飾子

    デフォルト設定

    in

    true

    inout

    true

    out

    true

    nocopy

    false

    詳細は、「ポインター変数のメモリー割り当ての管理」を参照してください。

  • into (var-exp): var-exp は変数式です。 この修飾子は、ホスト上の 1 つの変数からターゲット上の別の変数へ (またはその逆に) データを転送します。 この修飾子を使用する場合、variable-ref では 1 つの項目のみ指定できます。

    この節の引数には次の構文を使用します。

    • var : length ( l)

    • var [ 0 : length ]

    詳細は、「1 つの変数から別の変数へのデータの移動」を参照してください。

  • length ( element-count-expr)

    element-count-expr は整数式で、ランタイムに計算されます。 ポインター変数または可変長配列とともに使用します。

    • ポインター変数。

      ホストとターゲットのメモリーアドレスが対応していないため、ポインター変数の値はホスト/ターゲットのインターフェイス間でコピーされません。 代わりに、ポインターが指すオブジェクトがターゲットに、またはターゲットからコピーされ、ポインター変数の値が更新されます。 デフォルトでは、単一要素がコピーされます。

      element-count-expr を使用して、ポインターが指すデータとして見なすポインター型の要素の数を指定できます。 式の値が 0 または負の場合、ランタイムエラーが発生します。

    • 可変長配列。

      element-count-expr は、ホストとターゲット間でコピーする要素の数を指定します。

target ( target-name [ :target-number ] )

target-name はターゲットを表します。次のいずれかの値を使用できます。

gfx

インテル® グラフィックス・テクノロジー

mic

インテル® Xeon Phi™ 製品

target-number は整数式です。値は次のように解釈されます。

>=0

次の式に応じて、文を特定のターゲット上で実行します。

target = target-number % number_of_targets

例えば、4 つのターゲットを搭載したシステムの場合:

  • 2 または 6 を指定すると、ランタイムシステムはターゲット 2 でコードを実行します (2 % 4 と 6 % 4 はどちらも 2 になるため)。

  • 1000 を指定すると、ランタイムシステムはターゲット 0 でコードを実行します (1000 % 4 = 0 になるため)。

-1 または値なし

文をランタイムシステムによって選択されたターゲット上で実行します。

<-1

予約済み。

target-numbersignal 節と wait 節に必須です。

ターゲットが利用できない場合、optional 節を一緒に指定しない限り、プログラムは実行に失敗してエラーメッセージを出力します。optional 節は、ターゲットが利用できないときに文をホストで実行します。

オプション指示節

if-clause

ブーリアン式。

式の評価結果

動作

true

文はターゲットで実行されます。

false

文はホストで実行されます。if-clausesignal 節あるいは wait 節を一緒に使用した場合の動作は不定です。

この節を使用してオフロードを有効にするかどうかを制御します。関連するオフロード文がすべて有効または無効になるように、関連するプラグマでこの節を適切に使用してください。

mandatory

ターゲットで実行する必要がある場合に指定します。ホストで実行することはできません。

ターゲット・ハードウェアが利用できない場合にプログラムの実行を継続するには、statusvarname 変数を初期化して、このプラグマで status ( statusvarname ) 節を指定します。「説明」セクションで状態変数の初期化方法と設定可能な値について説明します。

optional 節を指定しないと、この節を指定した場合と同じになります。この節を明示的に指定することで、暗黙のデフォルトを明確にすることができます。

optional

ターゲットでの実行を要求しますが、必須ではありません。ターゲットが利用できない場合にホストで実行するように指定します。

ターゲットではなく、ホストで文が実行された理由を確認するには、statusvarname 変数を初期化して、このプラグマで status ( statusvarname ) 節を指定します。「説明」セクションで状態変数の初期化方法と設定可能な値について説明します。

mandatory 節はこの節の逆です。そのため、同じプラグマでこの節と一緒に使用しないでください。

signal ( tag ) )

非同期データ転送または計算処理のハンドルとなります。演算はオフロードで処理され、ホストでプラグマ以降のコードを実行中に out 節によりオフロードから結果が返されます。この節がない場合、オフロード全体と関連するデータ転送は同期して実行されます。ホストは、プラグマが完了するまでそれ以降のコードを実行しません。

tag は、ポインターのサイズ値をベースライン言語で表現したもので、非同期データ転送または計算処理のハンドルとして使用されます。

この節を使用する場合、target 節で 0 以上の target-number を指定します。

status ( statusvarname )

オフロード構造の実行状態を特定します。statusvarname 変数には、実行状態を示す値が含まれます。「説明」セクションで状態変数の初期化方法と設定可能な値について説明します。

optional 節と一緒に使用し、ターゲットが利用できない場合、ターゲットで実行される文は代わりにホストで実行されます。

mandatory 節と一緒に使用し、ターゲットが利用できない場合、ターゲットで実行される文は無視され、プログラムは実行を継続します。文が無視されたり、ホストで実行された理由を確認するには、この変数の値を調べます。

wait ( tag [, tag, ...] ) )

開始した非同期データ転送または非同期計算を待つ場合に指定します。

tag は、ポインターのサイズ値をベースライン言語で表現したものです。signal 節と同じ表現の値が使用され、開始した非同期処理 (非同期データ転送または非同期計算) のハンドルとして使用されます。

この節を使用する場合、target 節で 0 以上の target-number を指定します。

シグナルが開始される前にシグナルを照会すると、未定義の動作を引き起こし、アプリケーションはランタイムアボートします。例えば、target:1 で開始されたシグナルを target:0 で照会すると、シグナルは target:1 で開始されているため、target:0 に関連付けられたシグナルはなく、アプリケーションはランタイムアボートします。

説明

このプラグマは、ターゲットへのデータ転送とオフロード計算の両方を行います。

単一の呼び出し文、複合文、OpenMP* parallel プラグマを含む任意の文の前で使用して、単一の呼び出し文、複合文、トップレベルの OpenMP* 構造をリモートで実行するように指定できます。

このプラグマ内で __MIC__ マクロを使うことはできません。ただし、プラグマから呼び出されるサブプログラムでは __MIC__ マクロを使えます。

このプラグマがあると、次の処理が行われます。

  1. if 節がない場合は、ステップ 3 に進みます。

  2. ホストで if-clause 節を評価します。 節が true と評価された場合、ステップ 3 に進みます。それ以外の場合は、ホストで文を実行して終了します。

  3. ターゲットを取得します。取得に成功した場合は、ステップ 4 に進みます。 それ以外の場合は、ホストで文を実行して終了します。

  4. ホストで in 節と out 節で使用されている alloc_iffree_if、および element-count-expr 式と out 節で使用されている element-count-expr 式を計算します。

  5. ホストで、オフロードへの入力である変数値をすべて収集します。

  6. ホストからターゲットに入力値を送ります。

  7. ターゲットで、可変長 out 変数のメモリーを割り当てます。

  8. ターゲットで、入力値を対応するターゲットの変数にコピーします。

  9. ターゲットで文を実行します。

  10. ターゲットで、out 節で使用されている element-count-expr 式をすべて計算します。

  11. ターゲットで、オフロードの出力である変数値をすべて収集します。

  12. ターゲットからホストに出力値を送ります。

  13. ホストで、受け取った値を対応するホストの変数にコピーします。

プラグマに続く文は、ターゲットが利用可能な場合、ターゲットで実行されます。ターゲットが利用できない場合、optionalmandatory、および status (statusvarname ) 節により文の実行方法が決定されます。

指定する節

ターゲットが利用できない場合の動作

optional

文はホストで実行されます。

optional および status (statusvarname )

文はホストで実行され、statusvarname にターゲットを利用できない理由が格納されます。

mandatory

文は無視され、プログラムは終了します。

mandatory および status (statusvarname )

文は無視され、プログラムは実行を継続します。statusvarname にターゲットを利用できない理由が格納されます。

statusvarname 状態変数を初期化するには、OFFLOAD_STATUS_INIT(statusvarname) マクロを使用します。状態変数の値は offload.h で定義されています。設定可能な値は次のとおりです。

説明

OFFLOAD_SUCCESS = 0

文はターゲットで実行されました。

OFFLOAD_DISABLED

文はターゲットで実行されませんでした。if-clause を指定し、その値が false の場合、文はホストで実行されました。

OFFLOAD_UNAVAILABLE

ターゲットが利用できないため、文はターゲットで実行されませんでした。

OFFLOAD_OUT_OF_MEMORY

offload-parameter 用のメモリーが不足していたため、文はターゲットで実行されませんでした。

OFFLOAD_PROCESS_DIED

ターゲットでランタイムエラーが発生し、ターゲットのプロセスが終了したため、文はターゲットで実行されませんでした。

OFFLOAD_ERROR

エラーが発生したため、文はターゲットで実行されませんでした。

次の例は、可変長配列を使用してホストとターゲット間でコピーする要素の数を指定しています。

void sample(const int nx)
{
  float temp[nx];
  #pragma offload target(mic) in(temp : length(nx))
  {
    ...
  }
}

次の例は、in/out 節の variable-ref の指定方法を示します。

typedef int ARRAY[10][10]; 
int a[1000][500];
int *p;
ARRAY *q;
int *r[10][10];
int i, j;
struct { int y; } x;
#pragma offload …  in( a )
#pragma offload … out( a[i:j][:] )
#pragma offload …  in( p[0:100] )
#pragma offload …  in( (*q)[5][:] )
#pragma offload …  in( r[5][5][0:2] )
#pragma offload … out( x.y )

関連情報


このヘルプトピックについてのフィードバックを送信