offload

構文

<expression-stmt>

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

必須の指示節

• offload-parameter

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

オプション指示節

• if ( if-clause )

• mandatory

• optional

• signal ( tag )

• status ( statusvarname )

  この節は、インテル® MIC アーキテクチャーでのみ利用できます。

• stream ( handle )

  この節は、インテル® MIC アーキテクチャーでのみ利用できます。

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

引数

必須の指示節

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 識別子。 この引数の変数には次の構文を使用します。 var : length ( l ) var [ 0 : length ] array-slice 1 つの連続する配列要素のセットを表す式です。

modifier

次のいずれかです。 align (align-expression) expression は、スカラー整数式または配列スライス式です。 この修飾子は、インテル® MIC アーキテクチャーでのみ利用できます。 次のものと一緒に使用します。 ポインター変数。 align-expression は、スカラー整数式でなければなりません。 ターゲットで割り当てるポインターデータの最小アライメントを指定します。 値は 2 の累乗でなければなりません。 ポインター配列。 align-expression は、スカラー整数式または配列スライス式のいずれかです。 ターゲットで割り当てるポインターデータの最小アライメントを指定します。 値は 2 の累乗でなければなりません。 align-expression が配列スライス式の場合は、ポインター配列の各ポインターに適用されるアライメント値のセットを指定します。 1 つ目のアライメント値は 1 つ目のポインターに、2 つ目のアライメント値は 2 つ目のポインターに、というように適用されます。 alloc (array-slice) array-slice は、割り当てが必要な配列要素のセットを指定します。 in/ out 式で指定されたデータは、ターゲット上に割り当てられた配列の対応する部分に転送されます。 この修飾子は、インテル® MIC アーキテクチャーでのみ利用できます。 この修飾子の引数には次の構文を使用します。 var[start : length] 詳細は、「部分配列の一部へのメモリー割り当て」を参照してください。 alloc_if ( condition ) condition は、スカラーブール式またはブール配列スライス式です。 次のものと一緒に使用します。 ポインター変数。 condition は、スカラーブール式でなければなりません。 in/out/inout/nocopy 節の変数に割り当てられているメモリーを割り当てるかどうかを制御します。 式が TRUE と評価されると、節でリストされている各変数に新しいメモリーが割り当てられます。 条件が FALSE と評価されると、ターゲットにすでに割り当てられている値が再利用されます (データ保持)。 前のオフロードに対して free_if (0) 節を使用し、十分なサイズのメモリーブロックがターゲットの変数に割り当てられていることを確認する必要があります。 ポインター配列。 condition は、ブール式またはブール配列スライス式です。 ターゲット上で in/out/inout/nocopy 節の変数にメモリーを割り当てるかどうかを制御します。 condition が配列スライス式の場合は、ポインター配列の各ポインターに適用されるブール値のセットを指定します。 1 つ目のブール値は 1 つ目のポインターに、2 つ目のブール値は 2 つ目のポインターに、というように適用されます。 この修飾子のデフォルト設定は次のとおりです。 修飾子 デフォルト設定 in true inout true out true nocopy false alloc_extent ( start : length ) start と length は、整数値のセットとなる整数式または配列スライス式のいずれかです。 どちらの式も実行時に計算されます。 この修飾子は、インテル® MIC アーキテクチャーでのみ利用できます。 この修飾子は、次のものと一緒に使用します。 ポインター配列。 start と length は、整数式または配列スライス式です。 整数式の場合は、各ポインターに適用されます。 配列スライスの場合は、ポインター配列の各要素に対応する配列スライスの要素が指定されます。 start は、ターゲットで割り当てる最初の要素を指定します。 length は、割り当てる要素の数を指定します。 start が負の場合、ランタイムエラーが発生します。 extent ( start : length ) start と length は、整数値のセットとなる整数式または配列スライス式のいずれかです。 どちらの式も実行時に計算されます。 この修飾子は、次のものと一緒に使用します。 ポインター配列。 ホストとターゲットのメモリーアドレスは対応していないため、配列内のポインターの値はホスト/ターゲット間でコピーされません。 代わりに、ポインターが指すオブジェクトがターゲットに、またはターゲットからコピーされ、ポインター配列が更新されます。 start と length は、整数式または配列スライス式です。 整数式の場合は、各ポインターに適用されます。 配列スライスの場合は、ポインター配列の各要素に対応する配列スライスの要素が指定されます。 start は、転送する最初の要素を指定します。 length は、転送する要素の数を指定します。 start が負の場合、ランタイムエラーが発生します。 free_if (condition) condition は、スカラーブール式またはブール配列スライス式です。 次のものと一緒に使用します。 ポインター変数。 condition は、スカラーブール式でなければなりません。in/out/inout/nocopy 節の変数に割り当てられているメモリーを解放するかどうかを制御します。 式が false と評価されると、リストの各変数に割り当てられたメモリーに対する操作は行われません。 割り当てられたメモリーは後の節で再利用できます (データ保持)。 ポインター配列。 condition は、ブール式またはブール配列スライス式です。 ターゲット上で in/out/inout/nocopy 節の変数のメモリーを解放するかどうかを制御します。 condition が配列スライス式の場合は、ポインター配列の各ポインターに適用されるブール値のセットを指定します。 1 つ目のブール値は 1 つ目のポインターに、2 つ目のブール値は 2 つ目のポインターに、というように適用されます。 この修飾子のデフォルト設定は次のとおりです。 修飾子 デフォルト設定 in true inout true out true nocopy false 詳細は、「ポインター変数のメモリー割り当ての管理」を参照してください。 into (var-exp) var-exp は変数式です。 この修飾子は、ホスト上の 1 つの変数からターゲット上の別の変数へ (またはその逆に) データを転送します。 この修飾子を使用する場合、variable-ref では 1 つの項目のみ指定できます。 この修飾子は、インテル® MIC アーキテクチャーでのみ利用できます。 この節の引数には次の構文を使用します。 var (length 修飾子が一緒に使用される場合) var [ start : length ] (個別の length 修飾子が使用されない場合) 詳細は、「1 つの変数から別の変数へのデータの移動」を参照してください。 into_extent ( start : length ) start と length は、整数値のセットとなる整数式または配列スライス式のいずれかです。 どちらの式も実行時に計算されます。 この修飾子は、インテル® MIC アーキテクチャーでのみ利用できます。 この修飾子は、次のものと一緒に使用します。 into 修飾子と一緒に使用されるポインター配列。 start と length は、整数式または配列スライス式です。 整数式の場合は、各ポインターに適用されます。 配列スライスの場合は、ポインター配列の各要素に対応する配列スライスの要素が指定されます。 start は、ターゲットで割り当てる最初の要素を指定します。 length は、割り当てる要素の数を指定します。 start が負の場合、ランタイムエラーが発生します。 length (element-count-expr) element-count-expr は、スカラー整数式または配列スライス式で、実行時に計算されます。 次のものと一緒に使用します。 ポインター変数。 ホストとターゲットのメモリーアドレスが対応していないため、ポインター変数の値はホスト/ターゲットのインターフェイス間でコピーされません。 代わりに、ポインターが指すオブジェクトがターゲットに、またはターゲットからコピーされ、ポインター変数の値が更新されます。 スカラー整数式 element-count-expr を使用して、ポインターが指すデータとして見なされるポインター型の要素の数を指定できます。 式の値が 0 または負の場合、ランタイムエラーが発生します。スカラーポインター変数では、配列スライス式は指定できません。 可変長配列。 element-count-expr は、ホストとターゲット間でコピーする要素の数を指定します。 ポインター配列。 element-count-expr としてスカラー整数式で、転送する配列内のポインター要素の数を 0 番目の要素から指定できます。 式の値が 0 または負の場合、ランタイムエラーが発生します。 配列スライス式 element-count-expr は、ポインター配列の各ポインターに適用される長さのセットを指定します。 1 つ目の長さは 1 つ目のポインターに、2 つ目の長さは 2 つ目のポインターに、というように適用されます。 転送する要素は常に 0 から始まります。 [preallocated] targetptr インテル® MIC アーキテクチャー上でのみメモリーを割り当てます。 CPU 上ではメモリーが割り当てられません。インテル® MIC アーキテクチャー上にメモリーを割り当てるには、preallocated を指定します。 この修飾子を使用すると、ユーザーによって割り当て済みのインテル® MIC アーキテクチャー上のメモリーがデータ転送で利用可能になります。 詳細は、「デバイス上でのみメモリーを割り当てる」を参照してください。

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-number は signal 節と wait 節に必須です。

インテル® グラフィックス・テクノロジーを使用するヘテロジニアス・プログラムをコンパイルする場合、target-number オプションを指定すると、コンパイラーはこのオプションを無視し、次の警告を出力します。

async_offload1.cpp(24): 警告 #35026: *GFX* "#pragma offload target(target-name [ :target-number ])" の target-number は無視されました。

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

オプション指示節

if-clause

ブール式。

式の評価結果	動作
true	文はターゲットで実行されます。
false	文はホストで実行されます。if-clause と signal 節あるいは wait 節を一緒に使用した場合の動作は不定です。

注

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

mandatory

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

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

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

optional

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

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

注

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

signal ( tag ) )

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

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

注

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

status ( statusvarname )

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

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

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

stream ( handle )

handle で指定した stream へオフロードします。 handle は、ストリームを作成するインテル® MIC アーキテクチャー・ベースのデバイスを指定する _Offload_create_stream 関数から取得されます。 オフロードは、ストリームが作成されたデバイスに対して実行されます。 詳細は、「ストリームを使用したオフロード」を参照します。

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

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

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

注

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

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

説明

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

例

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

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 )

#define ARRAY_SIZE 4
#define DATA_ELEMS 100

__declspec(target(mic)) int start[ARRAY_SIZE];
__declspec(target(mic)) int len[ARRAY_SIZE];
__declspec(target(mic)) int align[ARRAY_SIZE];
__declspec(target(mic)) float *p[ARRAY_SIZE];
float *q[ARRAY_SIZE];

int main() {
  int i, j;
  bool failed = false;
  bool align_failed = false;

  for (i=0; i<ARRAY_SIZE; i++) {
    // ポインター配列要素の割り当て。利用可能なメモリーがあると仮定。
    p[i] = (float *)malloc(sizeof(float)*DATA_ELEMS);
    q[i] = (float *)malloc(sizeof(float)*DATA_ELEMS);
    p[i][0:DATA_ELEMS] = i;
    q[i][0:DATA_ELEMS] = p[i][0:DATA_ELEMS];
  }
 
  start[0] = 0;
  start[1] = 1;
  start[2] = 1;
  start[3] = 0;
  len[0] = DATA_ELEMS;
  len[1] = DATA_ELEMS - 2;
  len[2] = DATA_ELEMS - 2;
  len[3] = DATA_ELEMS;
  align[0] = 2048;
  align[1] = 4096;
  align[2] = 8192;
  align[3] = 8;

  // start と length はセクション
  // alloc_if、free_if のデフォルト値
  // アライメントを指定する
  // 配列の割り当ては element 0 から開始するが、転送はそうではない
  // いくつかの要素を更新して MIC から取得する
  // UUUUUUUUUUUUUU
  // .UUUUUUUUUUUU.
  // .UUUUUUUUUUUU.
  // UUUUUUUUUUUUUU

  #pragma offload target(mic) \
  inout( p[0:ARRAY_SIZE] : \
  extent(start[0:ARRAY_SIZE]:len[0:ARRAY_SIZE]) \
  align(align[0:ARRAY_SIZE]) ) { 
    for (i=0; i<ARRAY_SIZE; i++) {
       if (((long long)&p[i][0] & (align[i]-1)) != 0) {
          align_failed = true;
          printf("p[%d] failed alignment\n", i);
          fflush(0);
       }
    p[i][start[i]:len[i]] += 1.0;
    }
 }
 ...
 return 0;
}

#define ARRAY_SIZE 4
#define DATA_ELEMS 100

__declspec(target(mic)) int start[ARRAY_SIZE];
__declspec(target(mic)) int len[ARRAY_SIZE];
__declspec(target(mic)) int allocif[ARRAY_SIZE];
__declspec(target(mic)) int freeif[ARRAY_SIZE];
__declspec(target(mic)) int *p[ARRAY_SIZE];

int main() {
  int i, j;
  bool failed = false;

  for (i=0; i<ARRAY_SIZE; i++) {
    // ポインター配列要素の割り当て。利用可能なメモリーがあると仮定。
    p[i] = (int *)malloc(sizeof(int)*DATA_ELEMS);
    p[i][0:DATA_ELEMS] = i;
  }
 
  start[:] = 1;
  len[:] = 98;

  // start と length はセクション
  // free_if と align のデフォルト値
  // alloc_if はベクトルを使用し、free_if はスカラー拡張を使用する
  // 割り当てのみ
  allocif[:] = 1;
  #pragma offload_transfer target(mic) \
  nocopy( p[0:ARRAY_SIZE] : \
  extent(start[0:ARRAY_SIZE]:len[0:ARRAY_SIZE]) \
  alloc_if(allocif[0:ARRAY_SIZE]) \
  free_if(0) )

  // メモリーを再利用してオフロードを行う
  #pragma offload target(mic) \
  inout( p[0:ARRAY_SIZE] : \
  extent(start[0:ARRAY_SIZE]:len[0:ARRAY_SIZE]) \
  alloc_if(0) \
  free_if(0) ) { 
    for (i=0; i<ARRAY_SIZE; i++) { p[i][start[i]:len[i]] += 1; }
  }

  // メモリーを解放する
  // alloc_if はスカラー、free_if はベクトル
  freeif[:] = 1;
  #pragma offload_transfer target(mic) \
  nocopy( p[0:ARRAY_SIZE] : \
  extent(start[0:ARRAY_SIZE]:len[0:ARRAY_SIZE]) \
  alloc_if(0) \
  free_if(freeif[0:ARRAY_SIZE]) )

 ...
 return 0;
}

#define ARRAY_SIZE 4
#define DATA_ELEMS 100
#define SEND_ROWS 2
#define SEND_COLS 50
#define P_OFFSET_IN 2
#define P_OFFSET_OUT 0
#define Q_OFFSET 0
#define COL_OFFSET 50

__declspec(target(mic)) int len[ARRAY_SIZE];
__declspec(target(mic)) short int *p[ARRAY_SIZE];
__declspec(target(mic)) short int *q[ARRAY_SIZE*2];

#ifdef RUN_ON_CPU
bool run_on_cpu = true;
#else
__declspec(target(mic)) bool run_on_cpu = false;
#endif

int main() {
  int i, j;
  bool failed = false;

  for (i=0; i<ARRAY_SIZE; i++) {
    // ポインター配列要素の割り当て。利用可能なメモリーがあると仮定。
    p[i] = (short int *)malloc(sizeof(short int)*DATA_ELEMS);
    q[i] = (short int *)malloc(sizeof(short int)*DATA_ELEMS);
    q[i+ARRAY_SIZE] = (short int *)malloc(sizeof(short int)*DATA_ELEMS);
    p[i][0:DATA_ELEMS] = i;
  }
 
  len[:] = SEND_COLS;

  // start と length の拡張にスカラーを使用
  // alloc_if、free_if、align のデフォルト値
  // MIC に転送されるデータと MIC から転送されるデータ
  // p[2][50:50] -> q[0][50:50] は指定された 50 要素のみ割り当てる
  // p[3][50:50] -> q[1][50:50] は指定された 50 要素のみ割り当てる
  // 計算を実行する
  // p[0][50:50] <- q[0][50:50]
  // p[1][50:50] <- q[1][50:50]

  #pragma offload target(mic) \
  in (p[P_OFFSET_IN:SEND_ROWS] : extent(COL_OFFSET:SEND_COLS) \
  into(q[Q_OFFSET:SEND_ROWS]) into_extent(COL_OFFSET:SEND_COLS) \
  alloc_extent(COL_OFFSET:len[0:SEND_ROWS]) ) \
  out(q[Q_OFFSET:SEND_ROWS] : extent(COL_OFFSET:SEND_COLS) \
  into(p[P_OFFSET_OUT:SEND_ROWS]) into_extent(COL_OFFSET:SEND_COLS) ) {
    for (i=0; i<SEND_ROWS; i++) {
      // CPU で実行する場合は "in into" を模倣する
      if (run_on_cpu) {
        q[Q_OFFSET+i][COL_OFFSET:SEND_COLS] = p[P_OFFSET_IN+i][COL_OFFSET:SEND_COLS];
      }

    q[Q_OFFSET+i][COL_OFFSET:SEND_COLS] += i*2;
   
    // CPU で実行する場合は "out into" を模倣する
    if (run_on_cpu) {
      p[P_OFFSET_OUT+i][COL_OFFSET:SEND_COLS] = q[Q_OFFSET+i][COL_OFFSET:SEND_COLS];
    }
  }
}
 ... 
 return 0;
}