offload

Executes the statements on the target. This pragma only applies to Intel® MIC Architecture and Intel® Graphics Technology. Intel® Graphics Technology is a preview feature.

Syntax

#pragma offload clause[, clause...]

<expression-stmt>

Where clause can be the following required and optional clauses:

Required Clauses

  • offload-parameter

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

Optional Clauses

  • if ( if-clause )

  • mandatory

  • optional

  • signal ( tag )

  • status ( statusvarname )

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

Arguments

Required Clauses

offload-parameter

Controls how the program variables and the amount of data are copied between the host and the target. This clause can be one of the following:

in

The variable is strictly an input to the target region. The value is not copied back after the region completes.

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

out

The variable is strictly an output of the target region. The host does not copy the variable to the target.

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

inout

The variable is both copied from the host to the target and back from the target to the host.

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

nocopy

A variable whose value is reused from a previous target execution or one that is used entirely within the offloaded code section may be named in a nocopy clause to avoid any copying.

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

pin

A variable whose value shared between the host and the target.

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

The data selected for transfer is a combination of variables implicitly transferred because the variables are lexically referenced within offload constructs, and variables explicitly listed in offload-parameter.

An in or out element-count-expr expression (see description below within modifier) is evaluated at a point in the program before the statement or clause in which it is used.

An array variable whose size is known from the declaration is copied in its entirety. If a subset of an array is to be processed, use a pointer to the starting element of the subset and the element-count-expr to transfer the array subset.

Because a data pointer variable not listed in an in clause is uninitialized within the construct, it must be assigned a value before it can be de-referenced.

The following are the variables to use with this argument:

variable-ref

Is one of the following:

  • a C/C++ identifier.

  • variable-ref.identifier Use the following syntax for the variables in this arguments:

    • var : length ( l)

    • var [ 0 : length ]

  • array-slice which is an expression that denotes one contiguous set of array elements.

modifier

Is one of the following:

  • align ( expression ) where the value of expression should be a power of two. This modifier applies to pointer variables and requests the specified minimum alignment for pointer data allocated on the target.

  • alloc ( array-slice ) where array-slice specifies a set of elements of the array that need allocation. Data specified by the in/ out expression is transferred into the corresponding section of the array allocated on the target.

    Use the following syntax for the argument in this modifier:

    • var : length ( l)

    • var [ 0 : length ]

    For more information, see Allocating Memory for Parts of Arrays.

  • alloc_if ( condition ) where condition is a Boolean expression that controls whether to allocate the memory allocated for the allocatable variables in the in clause. If the expression evaluates to true, a new memory allocation is performed for each variable listed in the clause. If the condition evaluates to false, the existing allocated values on the target are reused (data persistence). You must ensure that a block of memory of sufficient size has been previously allocated for the variables on the target by using a free_if (0) clause on an earlier offload.

    The following are the default settings for this modifier:

    Modifier

    Default Setting

    in

    true

    inout

    true

    out

    true

    nocopy

    false

  • free_if ( condition ) specifies a Boolean condition that controls whether to whether to deallocate the memory allocated for the allocatable variables in the in clause. If the condition evaluates to false, no action is taken on the memory pointed to by the variables in the list. A subsequent clause will be able to reuse the allocated memory (data persistence).

    The following are the default settings for this modifier:

    Modifier

    Default Setting

    in

    true

    inout

    true

    out

    true

    nocopy

    false

    For more information, please see Managing Memory Allocation for Pointer Variables.

  • into ( var-exp ) where var-exp is a variable expression. This modifier allows data to be transferred from one variable on the host to another variable on the target, and vice versa. Only one item is allowed in variable-ref when using this modifier.

    Use the following syntax for the argument in this clause:

    • var : length ( l)

    • var [ 0 : length ]

    For more information, see Moving Data from One Variable to Another.

  • length ( element-count-expr)

    where element-count-expr is an integral expression, computed at runtime. Use it with:

    • Pointer variables.

      Pointer variable values themselves are never copied across the host/target interface because there is no correspondence between the memory addresses of the host and the target. Instead, objects that a pointer points to are copied to or from the target, and the value of the pointer variable is recreated. By default a single element is copied.

      You can use element-count-expr to specify how many elements of the pointer type should be considered as the data the pointer points to. If the expression value is zero or negative, a runtime error occurs.

    • Variable-length arrays.

      element-count-expr specifies a number of elements copied between the host and target.

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

target-name represents the target and can be one of the following values:

gfx

Intel® Graphics Technology

mic

Intel® Xeon Phi™ products

target-number is an integer expression whose value is interpreted as follows:

>=0

Executes the statement on a specified target according to the following formula:

target = target-number % number_of_targets

For example, in a system with four targets:

  • Specifying 2 or 6 tells the runtime systems to execute the code on target 2, because the result of 2 % 4 and 6 % 4 is 2.

  • Specifying 1000 tells the runtime systems to execute the code on target 0, because the result of 1000 % 4 is 0.

-1 or no value

Executes the statements on a target selected by the runtime system.

<-1

Reserved.

target-number is required for the signal and wait clauses .

If the target is not available, the program fails with an error message unless you also specify the optional clause. The optional clause allows the statements to execute on the host if the target is not available.

Optional Clauses

if-clause

A Boolean expression.

If the expression evaluates to ...

... then the following occurs.

true

The statements are executed on the target.

false

Statements are executed on the host. The behavior is undefined if the if-clause is used with either the signal or wait clauses.

Note

Use this clause to control whether offload is enabled. A set of related pragmas should use this clause in a coordinated fashion, so that either all or none of the related offload statements are enabled.

mandatory

Specifies execution on the target is required. Execution on the host is not allowed.

To continue the program if the correct target hardware is not available, initialize a variable statusvarname and use the status ( statusvarname ) clause in this pragma. The Description section explains how to initialize a status variable and the possible values for the status variable.

This clause is implied if the optional clause is not specified. You can explicitly specify this clause to reinforce the implied default.

optional

Specifies execution on the target is requested but not required. Execution on the host is allowed if the target is not available.

To determine why the statements where executed on the host instead of the target, initialize a variable statusvarname and use the status ( statusvarname ) clause in this pragma. The Description section explains how to initialize a status variable and the possible values for the status variable.

Note

Do not use this clause and the mandatory clause in the same pragma as these clauses are opposites of each other.

signal ( tag ) )

Handle on an asynchronous data transfer or computational activity. The computation performed by the offload clause and any results returned from the offload using out clauses occurs concurrently with host execution of the code after the pragma. If this clause is not used, then the entire offload and associated data transfer are executed synchronously. The host will not continue past the pragma until it has completed.

tag is an expression that is a pointer-size value in the baseline language which serves as a handle on an asynchronous activity, either data transfer or computation.

Note

You must specify a target clause with a target-number that is greater than or equal to zero with this clause.

status ( statusvarname )

Determine the status of the execution of an offloading construct. The statusvarname variable contains the value that explains the status of the execution. The Description section explains how to initialize a status variable and the possible values for this variable.

When used with the optional clause and the target is unavailable, the statements to be executed on the target are instead executed on the host.

When used with the mandatory clause and the target is unavailable, the statements are ignored and the program continues. To determine why the statements were ignored or executed on the host, examine the value of this variable.

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

Specifies a wait until a previously initiated asynchronous data transfer or asynchronous computation is completed.

tag is an expression that is a pointer-size value in the baseline language. This expression serves as a handle on a previously initiated asynchronous activity which used the same expression value in a signal clause. The activity could be an asynchronous computation or asynchronous data transfer.

Note

You must specify a target clause with a target-number that is greater than or equal to zero with this clause.

Querying a signal before the signal has been initiated results in undefined behavior and a runtime abort of the application. For example, querying a signal on target:0 that was initiated for target:1 results in a runtime abort of the application because the signal was initiated for target:1, so there is no signal associated with target:0.

Description

This pragma both transfers data and offloads computation to the target.

You can use this pragma before any statement, including a compound statement, or an OpenMP* parallel pragma, to specify remote execution of that compound statement or top-level OpenMP* construct, or a single call statement.

Note

Do not use the __MIC__ macro inside this pragma. You can, however, use the __MIC__ macro in a subprogram called from the pragma.

Conceptually, this is the sequence of events when this pragma is encountered:

  1. If there is no if clause, go to step 3.

  2. On the host, evaluate the if-clause clause. If the clause evaluates to true, go to step 3. Otherwise, execute the statements on the host and be done.

  3. Attempt to acquire the target. If successful, go to step 4. Otherwise, execute the statements on the host and be done.

  4. On the host, compute all alloc_if, free_if, and element-count-expr expressions used in the in and out clauses, and element-count-expr expressions used in out clause.

  5. On the host, gather all variable values that are inputs to the offload.

  6. Send the input values from the host to the target.

  7. On the target, allocate memory for variable-length out variables.

  8. On the target, copy input values into corresponding target variables.

  9. On the target, execute the statements.

  10. On the target, compute all element-count-expr expressions used in out clauses.

  11. On the target, gather all variable values that are outputs of the offload.

  12. Send output values back from the target to the host.

  13. On the host, copy values received into corresponding host variables.

The statements following this pragma are executed on the target if the target is available. If the target is not available, the optional, mandatory, and status ( statusvarname ) clauses determine how the statements are executed.

If you specified these clauses and the target is unavailable ...

... then the following occurred.

optional

The statements were executed on the host.

optional and status ( statusvarname )

The statements are executed on the host and the statusvarname contains the reason why the target was unavailable.

mandatory

The statements were ignored and the program ends.

mandatory and status ( statusvarname )

The statements were ignored and the program continues. The statusvarname contains the reason why the target was unavailable.

To initialize a status variable statusvarname, use the OFFLOAD_STATUS_INIT( statusvarname ) macro. The values of the status variables are defined in offload.h and can be the following values:

Value

Description

OFFLOAD_SUCCESS = 0

The statements were successfully executed on the target.

OFFLOAD_DISABLED

The statements were not executed were not executed on the target. If you specified if-clause and the value of this clause is false, the statements were successfully executed on the host.

OFFLOAD_UNAVAILABLE

The statements were not executed on the target because the target was unavailable.

OFFLOAD_OUT_OF_MEMORY

The statements were not executed on the target because there was not enough memory available for offload-parameter.

OFFLOAD_PROCESS_DIED

The statements were not executed on the target because a runtime error occurred on the target that caused in the target process to terminate.

OFFLOAD_ERROR

The statements were not executed on the target because of an error.

Example

The following example demonstrates how to use a variable-length array to specify a number of elements copied between the host and target.

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

The following example demonstrates variable-ref in the in/out clauses:

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 )
For more complete information about compiler optimizations, see our Optimization Notice.