Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

ID 767253
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Ahead of Time Compilation

Ahead of Time (AOT) Compilation is a helpful feature for your development lifecycle or distribution time. The AOT feature provides the following benefits when you know beforehand what your target device is going to be at application execution time:

  • No additional compilation time is done when running your application.

  • No just-in-time (JIT) bugs encountered due to compilation for the target. Any bugs should be found during AOT and resolved.

  • Your final code, executing on the target device, can be tested as-is before you deliver it to end-users.

A program built with AOT compilation for specific target device(s) will not run on different device(s). You must detect the proper target device at runtime and report an error if the targeted device is not present. The use of exception handling with an asynchronous exception handler is recommended.

SYCL supports AOT compilation for the following targets: Intel® CPUs, Intel® Processor Graphics, and Intel® FPGA. For details on AOT compilation for Intel FPGAs, refer to the Intel® oneAPI FPGA Handbook.

OpenMP supports AOT compilation for the following targets: Intel® Processor Graphics.

Prerequisites

To target a GPU with the AOT feature, you must have the OpenCL™ Offline Compiler (OCLOC) tool installed. OCLOC can generate binaries that use OpenCL™ (SYCL only) or the Intel® oneAPI Level Zero (Level Zero) backend.

OCLOC is not packaged with the compiler and must be installed separately. To install OCLOC, you need to install the GPU drivers (whether or not you have an Intel GPU on your system). Refer to the Installation Guides for instructions.

Requirements for Accelerators

GPUs:

  • Intel® UDH Graphics for 11th generation Intel processors or newer

  • Intel® Iris® Xe graphics

  • Intel® Arc™ graphics

  • Intel® Data Center GPU Flex Series

  • Intel® Data Center GPU Max Series

AOT Compilation Supported Options for OpenMP

Use the following options to target a specific device for AOT compilation for OpenMP:

  • -fopenmp-target to specify the device target

  • -Xopenmp-target-backend to pass options to the backend tool

Option -Xopenmp-target-backend is a general device target option. If multiple targets are desired (for example: -fopenmp-targets=spir64,spir64_gen), the options specified with -Xopenmp-target-backend apply to all targets.

For multiple targets, you can add specificity by using, for example, Xopenmp-target-backend=spir64_gen <option>.

When using Ahead of Time (AOT) compilation, the options passed with -Xopenmp-target-backend are not compiler options, but rather options to pass to OCLOC.

To see a list of the options you can pass with -Xopenmp-target-backend when using AOT, specify -fsycl-help=gen on the command line.

AOT Compilation Supported Options for SYCL

Use the following options to target a specific device for AOT compilation for SYCL:

  • -fsycl-target to specify the device target

  • -Xsycl-target-backend to pass options to the backend tool

Option -Xsycl-target-backend is a general device target option. If multiple targets are desired (for example: -fopenmp-targets=spir64_gen,spir64_x86_64), the options specified with -Xsycl-target-backend apply to all targets.

For multiple targets, you can add specificity by using, for example, Xsycl-target-backend=spir64_gen <option>.

When using Ahead of Time (AOT) compilation, the options passed with -Xsycl-target-backend are not compiler options.

To see a list of the options you can pass with -Xsycl-target-backend when using AOT, specify -fsycl-help=gen, -fsycl-help=x86_64, or -fsycl-help=fpga on the command line.

Use AOT for the Target Device (Intel® CPUs)

NOTE:

SYCL compilation is only available with the C/C++ compiler.

However, you can link SYCL-generated objects with the Fortran compiler. The use of -fsycl with ifx allows this, though it is restricted to spir64, spir64_gen, and spir64_x86_64).

Use the following option arguments to specify Intel® CPUs as the target device for AOT compilation:

  • -fsycl-targets=spir64_x86_64

  • -Xsycl-target-backend "-march=<arch>", where <arch> is one of the following:

    Switch Display Name

    avx

    Intel® Advanced Vector Extensions (Intel® AVX)

    avx2

    Intel® Advanced Vector Extensions 2 (Intel® AVX2)

    avx512

    Intel® Advanced Vector Extensions 512 (Intel® AVX-512)

    sse4.2

    Intel® Streaming SIMD Extensions 4.2 (Intel® SSE4.2)

The following examples tell the compiler to generate code that uses Intel® AVX2 instructions:

Linux

icpx -fsycl -fsycl-targets=spir64_x86_64 -Xsycl-target-backend  "-march=avx2" main.cpp

Windows

icx -fsycl /EHsc -fsycl-targets=spir64_x86_64 -Xsycl-target-backend  "-march=avx2" main.cpp

Build an Application with Multiple Source Files for CPU Targeting

NOTE:
This section is for SYCL only.

Compile your normal files (with no SYCL kernels) to create host objects. Then compile the file with the kernel code and link it with the rest of the application.

Linux

The following shows an example of Linux* compilation code:

icpx -c main.cpp      // This creates the host object that is used below
icpx -c -fsycl-targets=spir64_x86_64 -Xsycl-target-backend "-march=mavx2" mandel.cpp
icpx -fsycl-targets=spir64_x86_64 -Xsycl-target-backend "-march=mavx2" mandel.o main.o

Windows

The following shows an example of Windows* compilation code:

icx /EHsc -c main.cpp
icx /EHsc -c -fsycl-targets=spir64_x86_64 -Xsycl-target-backend "-march=mavx2" mandel.cpp
icx -fsycl-targets=spir64_x86_64 -Xsycl-target-backend "-march=mavx2" mandel.obj main.obj

Use AOT for Integrated Graphics (Intel® GPU)

Use the following option arguments to specify Intel® GPU as the target device for AOT compilation:

OpenMP

Option -Xopenmp-target-backend is a general-purpose option, any arguments supplied with -Xopenmp-target-backend will be applied to all offline compilation invocations. These are the relevant options and arguments:

  • -Xopenmp-target-backend "-device <arch>", where <arch> is the target device

  • -fopenmp-targets=spir64_gen

  • -fopenmp-device-code-split=<value> to perform an OpenMP device code split. The <value> is:

    • per_kernel, which creates a device code module for each OpenMP kernel

SYCL

Option -Xsycl-target-backend is a general-purpose option, any arguments supplied with -Xsycl-target-backend will be applied to all offline compilation invocations. These are the relevant options and arguments:

  • -Xsycl-target-backend "-device <arch>", where <arch> is the target device

  • -fsycl-targets=spir64_gen

  • -fsycl-device-code-split=<value> option to perform SYCL device code split. The <value> can be:

    • per_kernel, which creates a device code module for each SYCL kernel

    • per_source, which creates a device code module for each source (translation unit)

    • off, which disables device code split

    • auto, which tells the compiler to use a heuristic to select the best way of splitting device code

      This is the default, and it is the same as specifying -fsycl-device-code-split with no <value>.

To see the complete list of supported target device types for your installed version of OCLOC, run:

ocloc compile --help

To find supported devices look for -device <device_type> in the online help.

If multiple target devices are listed in the compile command, the compiler will compile for each of these targets and create a fat-binary that contains all the device binaries produced this way.

Examples of supported -device patterns:

OpenMP for Linux

  • To compile for a single target, using skl as an example, use:
    icpx -fiopenmp -fopenmp-targets=spir64_gen -Xopenmp-target-backend "-device skl" vector-add.cpp
  • To compile for two targets, using skl and icllp as examples, use:
    icpx -fiopenmp -fopenmp-targets=spir64_gen -Xopenmp-target-backend "-device skl,icllp" vector-add.cpp
  • To compile for all the targets known to OCLOC, use:
    icpx -fiopenmp -fopenmp-targets=spir64_gen -Xopenmp-target-backend "-device *" vector-add.cpp

    Or

    icpx -fiopenmp -fopenmp-targets=spir64_gen -Xopenmp-target-backend=spir64_gen "-device *" vector-add.cpp

SYCL for Linux

  • To compile for a single target, using skl as an example, use:
    icpx -fsycl -fsycl-targets=spir64_gen -Xsycl-target-backend "-device skl" vector-add.cpp
  • To compile for two targets, using skl and icllp as examples, use:
    icpx -fsycl -fsycl-targets=spir64_gen -Xsycl-target-backend "-device skl,icllp" vector-add.cpp
  • To compile for all the targets known to OCLOC, use:
    icpx -fsycl -fsycl-targets=spir64_gen -Xsycl-target-backend "-device *" vector-add.cpp

SYCL for Windows

  • To compile for a single target, using skl as an example, use:
    icx -fsycl /EHsc -fsycl-targets=spir64_gen -Xsycl-target-backend "-device skl" vector-add.cpp
  • To compile for two targets, using skl and icllp as examples, use:
    icx -fsycl /EHsc -fsycl-targets=spir64_gen -Xsycl-target-backend "-device skl,icllp" vector-add.cpp
  • To compile for all the targets known to OCLOC, use:
    icx -fsycl /EHsc -fsycl-targets=spir64_gen -Xsycl-target-backend "-device *" vector-add.cpp

    Or

    icx -fsycl /EHsc -fsycl-targets=spir64_gen -Xsycl-target-backend=spir64_gen "-device *" vector-add.cpp

Build an Application with Multiple Source Files for GPU Targeting

Compile your normal files (with no SYCL kernels) to create host objects. Then compile the file with the kernel code and link it with the rest of the application.

Linux

icpx -c main.cpp
icpx -fsycl -fsycl-targets=spir64_gen -Xsycl-target-backend=spir64_gen "-device *" mandel.o main.o

Windows

icx /c main.cpp
icx -fsycl /EHsc -fsycl-targets=spir64_gen -Xsycl-target-backend=spir64_gen "-device *" mandel.cpp main.obj

Use AOT in Microsoft Visual Studio

NOTE:
This section is for SYCL only.

You can use Microsoft Visual Studio for compiling and linking. Set the following flags to use AOT compilation for CPU or GPU:

CPU:

  • To compile, in the dialog box, select: Configuration Properties > DPC++ > General > Specify SYCL offloading targets for AOT compilation.
  • To link, in the dialog box, select: Configuration Properties > Linker > General > Specify CPU Target Device for AOT compilation.

GPU:

  • To compile, in the dialog box, select: Configuration Properties > DPC++ > General > Specify SYCL offloading targets for AOT compilation.
  • To link, in the dialog box, select: Configuration Properties > Linker > General > Specify GPU Target Device for AOT compilation.

Available GPU Platforms

Device Platform
acm-g10 dg2-g10 Alchemist, Arctic Sound
acm-g11 dg2-g11 Alchemist, Arctic Sound
adl-n Alder Lake
adl-p Alder Lake
adl-s Alder Lake
aml Amber Lake
apl bxt Apollo Lake, Broxton
cfl Coffee Lake
cml Comet Lake
dg1 DG1
ehl jsl Elkhart Lake, Jasper Lake
glk Gemini Lake
icllp Ice Lake
kbl Kaby Lake
rkl Rocket Lake
rpl-s Raptor Lake
skl Intel® microarchitecture code name Skylake
tgllp Tiger Lake
whl Whiskey Lake

See Also