インテル® C++ コンパイラー 18.0 デベロッパー・ガイドおよびリファレンス
文をターゲット上で実行します。このプラグマは、インテル® MIC アーキテクチャーおよびインテル® グラフィックス・テクノロジーに適用されます。
#pragma offloadclause[, clause...] |
<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, ...])
必須の指示節
ホストとターゲット間でコピーされるプログラム変数とデータの量を制御します。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 |
次のいずれかです。
|
||||||||||||||||||||
modifier |
次のいずれかです。
|
target-name はターゲットを表します。次のいずれかの値を使用できます。
gfx |
インテル® グラフィックス・テクノロジー |
mic |
インテル® Xeon Phi™ 製品 |
target-number は整数式です。値は次のように解釈されます。
次の式に応じて、文を特定のターゲット上で実行します。
target = target-number % number_of_targets
例えば、4 つのターゲットを搭載したシステムの場合:
2 または 6 を指定すると、ランタイムシステムはターゲット 2 でコードを実行します (2 % 4 と 6 % 4 はどちらも 2 になるため)。
1000 を指定すると、ランタイムシステムはターゲット 0 でコードを実行します (1000 % 4 = 0 になるため)。
文をランタイムシステムによって選択されたターゲット上で実行します。
予約済み。
target-number は signal 節と wait 節に必須です。
インテル® グラフィックス・テクノロジーを使用するヘテロジニアス・プログラムをコンパイルする場合、target-number オプションを指定すると、コンパイラーはこのオプションを無視し、次の警告を出力します。
async_offload1.cpp(24): 警告 #35026: *GFX* "#pragma offload target(target-name [ :target-number ])" の target-number は無視されました。
ターゲットが利用できない場合、optional 節を一緒に指定しない限り、プログラムは実行に失敗してエラーメッセージを出力します。optional 節は、ターゲットが利用できないときに文をホストで実行します。
オプション指示節
ブール式。
式の評価結果 |
動作 |
|---|---|
true |
文はターゲットで実行されます。 |
false |
文はホストで実行されます。if-clause と signal 節あるいは wait 節を一緒に使用した場合の動作は不定です。 |
この節を使用してオフロードを有効にするかどうかを制御します。関連するオフロード文がすべて有効または無効になるように、関連するプラグマでこの節を適切に使用してください。
ターゲットで実行する必要がある場合に指定します。ホストで実行することはできません。
ターゲット・ハードウェアが利用できない場合にプログラムの実行を継続するには、statusvarname 変数を初期化して、このプラグマで status ( statusvarname ) 節を指定します。後述の「説明」セクションでステータス変数の初期化方法と設定可能な値について説明します。
optional 節を指定しないと、この節を指定した場合と同じになります。この節を明示的に指定することで、暗黙のデフォルトを明確にすることができます。
ターゲットでの実行を要求しますが、必須ではありません。ターゲットが利用できない場合にホストで実行するように指定します。
ターゲットではなく、ホストで文が実行された理由を確認するには、statusvarname 変数を初期化して、このプラグマで status ( statusvarname ) 節を指定します。後述の「説明」セクションでステータス変数の初期化方法と設定可能な値について説明します。
mandatory 節はこの節の逆です。そのため、同じプラグマでこの節と一緒に使用しないでください。
非同期データ転送または計算処理のハンドルとなります。演算はオフロードで処理され、ホストでプラグマ以降のコードを実行中に out 節によりオフロードから結果が返されます。この節がない場合、オフロード全体と関連するデータ転送は同期して実行されます。ホストは、プラグマが完了するまでそれ以降のコードを実行しません。
tag は、ポインターのサイズ値をベースライン言語で表現したもので、非同期データ転送または計算処理のハンドルとして使用されます。
この節を使用する場合、target 節で 0 以上の target-number を指定します。
オフロード構造の実行状態を特定します。statusvarname 変数には、実行状態を示す値が含まれます。後述の「説明」セクションでステータス変数の初期化方法と設定可能な値について説明します。
optional 節と一緒に使用し、ターゲットが利用できない場合、ターゲットで実行される文は代わりにホストで実行されます。
mandatory 節と一緒に使用し、ターゲットが利用できない場合、ターゲットで実行される文は無視され、プログラムは実行を継続します。文が無視されたり、ホストで実行された理由を確認するには、この変数の値を調べます。
handle で指定した stream へオフロードします。handle は、ストリームを作成するインテル® MIC アーキテクチャー・ベースのデバイスを指定する _Offload_create_stream 関数から取得されます。オフロードは、ストリームが作成されたデバイスに対して実行されます。詳細は、「ストリームを使用したオフロード」を参照します。
開始した非同期データ転送または非同期計算を待つ場合に指定します。
tag は、ポインターのサイズ値をベースライン言語で表現したものです。signal 節と同じ表現の値が使用され、開始した非同期処理のハンドルとして使用されます。ここで言う非同期処理は、非同期データ転送または非同期計算です。
この節を使用する場合、target 節で 0 以上の target-number を指定します。
シグナルが開始される前にシグナルを照会すると、未定義の動作を引き起こし、アプリケーションはランタイムアボートします。例えば、target:1 で開始されたシグナルを target:0 で照会すると、シグナルは target:1 で開始されているため、target:0 に関連付けられたシグナルはなく、アプリケーションはランタイムアボートします。
このプラグマは、ターゲットへのデータ転送とオフロード計算の両方を行います。
単一の呼び出し文、複合文、OpenMP* parallel プラグマを含む任意の文の前で使用して、単一の呼び出し文、複合文、トップレベルの OpenMP* 構造をリモートで実行するように指定できます。
このプラグマ内で __MIC__ マクロを使うことはできません。ただし、プラグマから呼び出されるサブプログラムでは __MIC__ マクロを使えます。
インテル® グラフィックス・テクノロジーの場合
仮想共有メモリー (SVM) ポインターは、GFX オフロード領域の in 節で指定できません。SVM モードのコンパイル時に in 節でポインターが指定されている場合、コンパイルエラーが出力されます。SVM モードのコンパイル時に、メモリー共有節やピン設定節でポインターを指定する必要はありません。GFX オフロード領域の out、inout、pin 節でポインターを割り当てると、コンパイル時に警告が出力されます。
物理メモリーは CPU とプロセッサー・グラフィックス間で共有されます。グローバル・データ・オブジェクトへの直接アクセスを除いて、offload-parameter 値 out と inout を nocopy 実装にマップします。デバイス領域への入口で、リスト項目の物理メモリーがメモリーに保存され、そのデバイス領域が終了するまで保持されます。これにより、コピーを回避してオフロードのオーバヘッドを軽減し、動作を維持します。copy と nocopy どちらの場合も、競合を回避するため、同じメモリーへの CPU アクセスは同期されなければなりません。
このプラグマがあると、次の処理が行われます。
if 節がない場合は、ステップ 3 に進みます。
ホストで if-clause 節を評価します。節が true と評価された場合、ステップ 3 に進みます。それ以外の場合は、ホストで文を実行して終了します。
ターゲットを取得します。取得に成功した場合は、ステップ 4 に進みます。それ以外の場合は、ホストで文を実行して終了します。
ホストで in 節と out 節で使用されている alloc_if、free_if、および element-count-expr 式と out 節で使用されている element-count-expr 式を計算します。
ホストで、オフロードへの入力である変数値をすべて収集します。
ホストからターゲットに入力値を送ります。
ターゲットで、可変長 out 変数のメモリーを割り当てます。
ターゲットで、入力値を対応するターゲットの変数にコピーします。
ターゲットで文を実行します。
ターゲットで、out 節で使用されている element-count-expr 式をすべて計算します。
ターゲットで、オフロードの出力である変数値をすべて収集します。
ターゲットからホストに出力値を送ります。
ホストで、受け取った値を対応するホストの変数にコピーします。
プラグマに続く文は、ターゲットが利用可能な場合、ターゲットで実行されます。ターゲットが利用できない場合、optional、mandatory、および 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 ) |
ターゲットでアライメントを指定するポインター配列の例 |
|---|
#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;
} |
ポインター配列と部分配列を使用する alloc_if と free_if の例 |
|---|
#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;
} |
into、into_extent、alloc_extent を使用するポインター配列の例 |
|---|
#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;
} |