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

Download PDF
ID 767253
Date 11/07/2023
Public

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

Document Table of Contents
Document Table of Contents x
Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference
Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference x
Intel® oneAPI DPC++/C++ Compiler Introduction Compiler Setup Compiler Reference Compilation Optimization and Programming Compatibility and Portability Notices and Disclaimers
Intel® oneAPI DPC++/C++ Compiler Introduction x
Get Help and Support Related Information
Compiler Setup x
Use the Command Line Use Eclipse Use Microsoft Visual Studio
Use the Command Line x
Specify Component Locations Invoke the Compiler Use the Command Line on Windows File Extensions Use Makefiles for Compilation Use CMake with the Compiler Use Compiler Options Specify Compiler Files Convert Projects to Use a Selected Compiler
Use Eclipse x
Add the Compiler to Eclipse Multiversion Compiler Support Use Cheat Sheets Create a Simple Eclipse Project Makefiles Use Intel Libraries with Eclipse
Use Microsoft Visual Studio x
Create a New Project Use the Intel® oneAPI DPC++/C++ Compiler Select the Compiler Version Specify a Base Platform Toolset Use Property Pages Use Intel® Libraries with Microsoft Visual Studio* Include MPI Support Dialog Box Help
Dialog Box Help x
Options: Compilers dialog box Use Intel® oneAPI DPC++/C++ Compiler dialog box Options: Intel Libraries for oneAPI dialog box
Compiler Reference x
C/C++/SYCL Calling Conventions Compiler Options Floating-Point Operations Attributes Intrinsics Libraries Macros Pragmas Error Handling
Compiler Options x
Alphabetical Option List General Rules for Compiler Options What Appears in the Compiler Option Descriptions Optimization Options Code Generation Options Interprocedural Optimization Options Advanced Optimization Options Profile Guided Optimization Options Optimization Report Options Offload Compilation, OpenMP*, and Parallel Processing Options Floating-Point Options Inlining Options Output, Debug, and Precompiled Header Options Preprocessor Options Component Control Options Language Options Data Options Compiler Diagnostic Options Compatibility Options Linking or Linker Options Miscellaneous Options Deprecated and Removed Compiler Options Display Option Information Alternate Compiler Options Portability and GCC-Compatible Warning Options
Optimization Options x
fast fbuiltin, Oi foptimize-sibling-calls GF nolib-inline O Od Ofast Os Ot Ox
Code Generation Options x
arch ax, Qax EH fasynchronous-unwind-tables fcf-protection, Qcf-protection fdata-sections, Gw fexceptions ffunction-sections, Gy fomit-frame-pointer Gd GR guard Gv m, Qm m64, Qm64 m80387 march masm mauto-arch, Qauto-arch mbranches-within-32B-boundaries, Qbranches-within-32B-boundaries mintrinsic-promote, Qintrinsic-promote momit-leaf-frame-pointer mtune, tune regcall, Qregcall x, Qx xHost, QxHost
Interprocedural Optimization Options x
flto ipo, Qipo
Advanced Optimization Options x
ffreestanding, Qfreestanding fjump-tables fvec-peel-loops, Qvec-peel-loops fvec-remainder-loops, Qvec-remainder-loops fvec-with-mask, Qvec-with-mask ipp-link, Qipp-link mno-gather, Qgather- mno-scatter, Qscatter- qactypes, Qactypes qdaal, Qdaal qipp, Qipp qmkl, Qmkl qmkl-ilp64, Qmkl-ilp64 qopt-assume-no-loop-carried-dep, Qopt-assume-no-loop-carried-dep qopt-dynamic-align, Qopt-dynamic-align qopt-for-throughput, Qopt-for-throughput qopt-mem-layout-trans, Qopt-mem-layout-trans qopt-multiple-gather-scatter-by-shuffles, Qopt-multiple-gather-scatter-by-shuffles qopt-prefetch, Qopt-prefetch qopt-streaming-stores, Qopt-streaming-stores qtbb, Qtbb unroll, Qunroll vec, Qvec vec-threshold, Qvec-threshold vecabi, Qvecabi
Profile Guided Optimization Options x
fprofile-dwo-dir fprofile-ml-use fprofile-sample-generate fprofile-sample-use
Optimization Report Options x
qopt-report, Qopt-report qopt-report-file, Qopt-report-file qopt-report-stdout, Qopt-report-stdout
Offload Compilation, OpenMP*, and Parallel Processing Options x
device-math-lib fintelfpga fiopenmp, Qiopenmp flink-huge-device-code fno-sycl-libspirv foffload-static-lib fopenmp fopenmp-declare-target-scalar-defaultmap, Qopenmp-declare-target-scalar-defaultmap fopenmp-device-code-split, Qopenmp-device-code-split fopenmp-device-lib fopenmp-max-parallel-link-jobs, Qopenmp-max-parallel-link-jobs fopenmp-target-buffers, Qopenmp-target-buffers fopenmp-targets, Qopenmp-targets fsycl fsycl-add-targets fsycl-dead-args-optimization fsycl-device-code-split fsycl-device-lib fsycl-device-obj fsycl-device-only fsycl-early-optimizations fsycl-enable-function-pointers fsycl-esimd-force-stateless-mem fsycl-explicit-simd fsycl-force-target fsycl-help fsycl-host-compiler fsycl-host-compiler-options fsycl-id-queries-fit-in-int fsycl-instrument-device-code fsycl-link fsycl-link-huge-device-code fsycl-link-targets fsycl-max-parallel-link-jobs fsycl-optimize-non-user-code fsycl-pstl-offload fsycl-rdc fsycl-targets fsycl-unnamed-lambda fsycl-use-bitcode ftarget-compile-fast ftarget-export-symbols nolibsycl qopenmp, Qopenmp qopenmp-link qopenmp-simd, Qopenmp-simd qopenmp-stubs, Qopenmp-stubs reuse-exe Wno-sycl-strict Xopenmp-target Xs Xsycl-target
Floating-Point Options x
ffp-contract fimf-absolute-error, Qimf-absolute-error fimf-accuracy-bits, Qimf-accuracy-bits fimf-arch-consistency, Qimf-arch-consistency fimf-domain-exclusion, Qimf-domain-exclusion fimf-max-error, Qimf-max-error fimf-precision, Qimf-precision fimf-use-svml, Qimf-use-svml fma, Qfma fp-model, fp fp-speculation, Qfp-speculation ftz, Qftz pc, Qpc
Inlining Options x
fgnu89-inline finline finline-functions
Output, Debug, and Precompiled Header Options x
c debug (Linux*) debug (Windows*) Fa fasm-blocks Fe Fo Fp fverbose-asm g gdwarf grecord-gcc-switches gsplit-dwarf o S use-msasm Y- Yc Yu Zi, Z7, ZI
Preprocessor Options x
B C D dD, QdD dM, QdM E EP FI H, QH I idirafter imacros iprefix iquote isystem iwithprefix iwithprefixbefore M, QM MD, QMD MF, QMF MG, QMG MM, QMM MMD, QMMD MQ, QMQ MT, QMT nostdinc++ P TP U undef X
Component Control Options x
Qoption
Language Options x
ansi fno-gnu-keywords fno-operator-names fno-rtti fpermissive fshort-enums fsyntax-only, Zs funsigned-char, J std, Qstd strict-ansi vd vmg x (type option) Zc Zg Zp
Data Options x
fcommon fkeep-static-consts, Qkeep-static-consts fmath-errno fpack-struct fpic fpie fstack-protector fstack-security-check fvisibility fzero-initialized-in-bss, Qzero-initialized-in-bss GA Gs GS mcmodel Qlong-double
Compiler Diagnostic Options x
w W Wabi Wall Wcheck-unicode-security Wcomment Wdeprecated Werror, WX Werror-all Wextra-tokens Wformat Wformat-security Wmain Wmissing-declarations Wmissing-prototypes Wpointer-arith Wreorder Wreturn-type Wshadow Wsign-compare Wstrict-aliasing Wstrict-prototypes Wtrigraphs Wuninitialized Wunknown-pragmas Wunused-function Wunused-variable Wwrite-strings
Compatibility Options x
gcc-toolchain vmv
Linking or Linker Options x
F (Windows*) fixed fortlib fuse-ld l L LD link MD MT nodefaultlibs no-intel-lib, Qno-intel-lib nostartfiles nostdlib pie pthread shared shared-intel shared-libgcc static static-intel static-libgcc static-libstdc++ T u (Linux*) v Wa Wl Wp Xlinker Zl
Miscellaneous Options x
dryrun dumpmachine dumpversion help nologo save-temps, Qsave-temps showIncludes sox, Qsox sysroot Tc TC Tp version
Floating-Point Operations x
Programming Tradeoffs in Floating-Point Applications Floating-Point Optimizations Denormal Numbers Floating-Point Environment Set the FTZ and DAZ Flags Tuning Performance IEEE Floating-Point Operations
Attributes x
align align_value allow_cpu_features const cpu_dispatch, cpu_specific target
Libraries x
Create Libraries Use Intel Shared Libraries on Linux Manage Libraries Redistribute Libraries When Deploying Applications Resolve References to Shared Libraries Sanitizers Intel's Memory Allocator Library SIMD Data Layout Templates Intel® C++ Class Libraries Intel's C++ Asynchronous I/O Extensions for Windows IEEE 754-2008 Binary Floating-Point Conformance Library Intel's Numeric String Conversion Library
SIMD Data Layout Templates x
Function Calls and Containers User-Level Interface Examples
Function Calls and Containers x
Construct an n_container Bounds
User-Level Interface x
SDLT Primitives soa1d_container aos1d_container n_container Bounds Accessors Proxy Objects Number Representation Fixed Aligned int Indexes Convenience and Correctness
aos1d_container x
access_by
n_container x
Layouts Shape make_ n_container template function extent_d template function
Shape x
n_extent_generator
Bounds x
bounds_t sdlt::bounds Template Function n_bounds_t n_bounds_generator bounds_d Template Function
Accessors x
soa1d_container::accessor and aos1d_container::accessor soa1d_container::const_accessor and aos1d_container::const_accessor Accessor Concept
Proxy Objects x
Proxy ConstProxy
Number Representation x
Fixed Aligned int aligned_offset fixed_offset
Indexes x
linear_index n_index_t n_index_generator index_d template function
Convenience and Correctness x
max_val min_val
Examples x
Efficiency with Structure of Arrays Example Complex SDLT Primitive Construction Example Forward Dependency Example Use of Offsets and Methods on a SDLT Primitive Example RGB to YUV Conversion Example
Intel® C++ Class Libraries x
C++ Classes and SIMD Operations Capabilities of C++ SIMD Classes Integer Vector Classes Floating-Point Vector Classes Classes Quick Reference Programming Example Intel's valarray Implementation
Integer Vector Classes x
Terms and Syntax Rules for Operators Assignment Operator Logical Operators Addition and Subtraction Operators Multiplication Operators Shift Operators Comparison Operators Conditional Select Operators Debug Operations Unpack Operators Pack Operators Clear MMX™ State Operator Integer Functions for Intel® Streaming SIMD Extensions Conversions between Fvec and Ivec
Floating-Point Vector Classes x
Fvec Syntax and Notation Data Alignment Conversions Constructors and Initialization Arithmetic Operators Minimum and Maximum Operators Logical Operators Compare Operators Conditional Select Operators for Fvec Classes Cacheability Support Operators Debug Operations Load and Store Operators Unpack Operators Move Mask Operators
Intel's C++ Asynchronous I/O Extensions for Windows x
Intel's C++ Asynchronous I/O Library for Windows Intel's C++ Asynchronous I/O Class for Windows
Intel's C++ Asynchronous I/O Library for Windows x
aio_read aio_write Example for aio_read and aio_write Functions aio_suspend Example for aio_suspend Function aio_error aio_return Example for aio_error and aio_return Functions aio_fsync aio_cancel Example for aio_cancel Function lio_listio Example for lio_listio Function Asynchronous I/O Function Errors
Intel's C++ Asynchronous I/O Class for Windows x
Template Class async_class get_last_operation_id wait get_status get_last_error get_error_operation_id stop_queue resume_queue clear_queue Example for Using async_class Template Class
IEEE 754-2008 Binary Floating-Point Conformance Library x
Intel® IEEE 754-2008 Binary Floating-Point Conformance Library and Usage Function List Homogeneous General-Computational Operations Functions General-Computational Operation Functions Quiet-Computational Operations Functions Signaling-Computational Operations Functions Non-Computational Operations Functions
Intel's Numeric String Conversion Library x
Use Intel's Numeric String Conversion Library Function List
Macros x
ISO Standard Predefined Macros Additional Predefined Macros Use Predefined Macros to Specify Intel® Compilers
Pragmas x
Intel-Specific Pragma Reference Intel-Supported Pragma Reference
Intel-Specific Pragma Reference x
block_loop/noblock_loop distribute_point inline, noinline, forceinline ivdep loop_count nofusion novector omp target variant dispatch ompx prefetch data prefetch/noprefetch unroll/nounroll unroll_and_jam/nounroll_and_jam vector
Compilation x
Compilation Overview Supported Environment Variables Pass Options to the Linker Specify Alternate Tools and Paths Use Configuration Files Use Response Files Global Symbols and Visibility Attributes for Linux* Save Compiler Information in Your Executable Link Debug Information Ahead of Time Compilation Device Offload Compilation Considerations Use a Third-Party Compiler as a Host Compiler for SYCL Code
Optimization and Programming x
Extensions OpenMP* Support Intel® oneAPI Level Zero Vectorization Instrumented Profile-Guided Optimization Hardware Profile-Guided Optimization High-Level Optimization Interprocedural Optimization Methods to Optimize Code Size Intel® oneAPI DPC++/C++ Compiler Math Library
OpenMP* Support x
Add OpenMP* Support Parallel Processing Model Worksharing Using OpenMP* Control Thread Allocation OpenMP* Pragmas OpenMP* Library Support OpenMP* Contexts OpenMP* Advanced Issues OpenMP* Implementation-Defined Behaviors OpenMP* Examples
OpenMP* Library Support x
OpenMP* Runtime Library Routines Intel® Compiler Extension Routines to OpenMP* OpenMP* Support Libraries Use the OpenMP Libraries Thread Affinity Interface OpenMP* Memory Spaces and Allocators
OpenMP* Contexts x
OpenMP* Context Selectors Score and Match Context Selectors
Intel® oneAPI Level Zero x
Intel® oneAPI Level Zero Switch Intel® oneAPI Level Zero Backend Specification Programming with the Intel® oneAPI Level Zero Backend
Vectorization x
Automatic Vectorization Explicit Vector Programming
Automatic Vectorization x
Vectorization Programming Guidelines Use Automatic Vectorization Vectorization and Loops Loop Constructs
Explicit Vector Programming x
User-Mandated or SIMD Vectorization SIMD-Enabled Functions SIMD-Enabled Function Pointers Function Annotations and the SIMD Directive for Vectorization Explicit SIMD SYCL Extension
Interprocedural Optimization x
Use Interprocedural Optimization Performance Considerations Create a Library from IPO Objects Inline Expansion of Functions
Intel® oneAPI DPC++/C++ Compiler Math Library x
Use the Intel® oneAPI DPC++/C++ Compiler Math Library Math Function List Trigonometric Functions Hyperbolic Functions Exponential Functions Special Functions Nearest Integer Functions Remainder Functions Miscellaneous Functions Complex Functions C99 Macros
Compatibility and Portability x
Standards Conformance GCC Compatibility and Interoperability Microsoft Compatibility Port from Microsoft Visual C++* to the Intel® oneAPI DPC++/C++ Compiler Port from GCC* to the Intel® oneAPI DPC++/C++ Compiler
Port from Microsoft Visual C++* to the Intel® oneAPI DPC++/C++ Compiler x
Modify Your makefile Other Considerations
Port from GCC* to the Intel® oneAPI DPC++/C++ Compiler x
Modify Your makefile Other Considerations
Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

Number Representation

When specifying extents, positions inside of, or bounds of a container, numeric values can be represented three different ways: fixed, aligned, and int. Fixed is most precise and int is least precise. It is advised to use as precise specification as possible. The compiler may optimize better with more information.

Fixed

Represent a numerical constant whose value specified at compile time. 

template <int NumberT> class fixed;

If offsets applied to index values inside a SIMD loop are known at compile time, then the compiler can use that information. For example, to maintain aligned access, if boundary is fixed and known to be aligned when accessing underlying data layout. When multiple accesses are happening near each other, the compiler will have the opportunity to detect which accesses occur in the same cache lines and potentially avoid prefetching the same cache line repeatedly. Additionally, if the start of an iteration space is known at compile time, if it's a multiple of the SIMD lane count, the compiler could skip generating a peel loop. Whenever possible, fixed values should be used over aligned or arbitrary integer values.

Although std::integral_constant<int> provides the same functionality, the library defines own type to provide overloaded operators and avoid collisions with any other code's interactions with std::integral_constant<int>.

The following table provides information about the template arguments for fixed.

Template Argument Description 

int Number T

 The numerical value the fixed will represent.

The following table provides information about the members of fixed.

Member Description 
static constexpr int value = NumberT
The numerical value known at compile-time. 
constexpr operator value_type() const

Returns: The numerical value 

constexpr value_type operator()() const;

Returns: The numerical value

Constant expression arithmetic operators +,- (both unary and binary), * and / are defined for type sdlt::fixed<> and will be evaluated at compile-time.

The suffix _fixed is a C++11 user-defined equivalent literal. For example, 1080_fixed is equivalent to fixed<1080>. Consider the readability of the two samples below. 

foo3d(fixed<1080>(), fixed<1920>());

versus 

foo3d(1080_fixed, 1920_fixed);

NOTE:
This note does not apply to SYCL. The sdlt::fixed<NumberT> type supersedes the deprecated sdlt::fixed_offset<OffsetT> type found in SDLT v1. It is strongly advised to use sdlt::fixed<NumberT>. However, in this release, a template alias is provided mapping sdlt::fixed_offset<OffsetT> onto sdlt::fixed<NumberT>.

Aligned

Represent integer value known at compile time to be a multiple of an IndexAlignment. 

template <int IndexAlignmentT> class aligned;

If you can tell the compiler that you know that an integer will be a multiple of known value, then, when combined with a loop index inside a SIMD loop, the compiler can use that information to maintain aligned access when accessing underlying data layout.

Internally, the integer value is converted to a block count, where: 

block_count = value/IndexAlignmentT;

Overloaded math operations can then use that aligned block count as needed. The value() is represented by AlignmentT*block_count allowing the compiler to prove that the value() is a multiple of AlignmentT, which can utilize alignment optimizations.

The following table provides information about the template arguments for aligned.

Template Argument Description 

int IndexAlignmentT

 The alignment the user is stating that the number is a multiple of. IndexAlignmentT must be a power of two.

The following table provides information about the types defined as members of aligned.

Member Type Description 

typedef int value_type

 The type of the numerical value. 

typedef int block_type

 The type of the block_count.

The following table provides information about the members of aligned.

Member Description 
static const int index_alignment

The IndexAlignmentT value. 

aligned()

Constructs empty (uninitialized) object 

explicit aligned(value_type)

Constructs computing block_count=a_value/IndexAlignmentT. 

aligned(const aligned& a_other)

Constructs copying block_count from a_other. a_other must have same IndexAlignmentT. 

template<int OtherAlignment>
explicit aligned(const aligned& other)

Constructs computing block_count optimized by avoiding computing other.value(). Must have IndexAlignmentT of a_other < IndexAlignmentT and other.value() be multiple of IndexAlignmentT. 

template<int OtherAlignment>
aligned(const aligned& other)

Constructs computing block_count with a multiply instead of divide. Must have IndexAlignmentT of a_other > IndexAlignmentT

 
static aligned from_block_count(block_type block_count)

Creates an instance of aligned avoiding any math by directly using supplied block_count

 
value_type value() const

Computes the value represented by the aligned.

Returns: aligned_block_count()*IndexAlignmentT

 
operator value_type()

Conversion to int.

Returns: value()

 
block_type aligned_block_count() const

Conversion to int.

Returns: The block count

The following operations are supported for the aligned type.

Operation Description 
operator *(int), commutative
 Scale value.

Returns: aligned<IndexAlignmentT >

 
operator *(fixed<V>), commutative

Scales IndexAlignment by 2^M and value by K. Must have V=2^M*K (V is a multiple of a power of 2).

Returns: aligned<IndexAlignmentT*(2^M)>

 
operator *(aligned<OtherAl>)

Scales IndexAlignment by OtherAl and block_count by argument.

Returns: aligned<IndexAlignmentT*OtherAl>

 
int operator/(fixed<IndexAlignmentT>)

Returns: aligned_block_count() 

int operator/(fixed<-IndexAlignmentT>)

Returns: -aligned_block_count(); 

int operator/(fixed<V>)

Must have abs(V)>IndexAlignmentT && IndexAlignmentT%V==0.

Returns: aligned_block_count()/(V/IndexAlignmentT)

 
int operator/(fixed<V>)

Must have abs(V) < IndexAlignmentT && V%IndexAlignmentT==0

Returns: aligned_block_count()*(IndexAlignmentT/V)

 
aligned operator -()

Returns: Same type aligned for negated value. 

aligned operator -(const aligned &)
                const

Returns: Same type aligned for value of difference. 

template<int OtherAl> 
aligned<?> operator -(const aligned<OtherAl>&) const

Difference with other alignment. Behavior and returned alignment type depend on relation between alignments of operands.

Returns: Value for difference as lower of incoming alignments 

template<int V>
aligned<?> operator -(const fixed<V> &) const

Difference with fixed value. Behavior and returned alignment type depend on relation between alignments of aligned<> operand and the value of V.

Returns: Adjusted aligned value of a difference 

aligned operator +(const aligned &)const

Returns: Same type aligned for value of sum 

template<int OtherAl>
aligned<?> operator +(const aligned<OtherAl>&) const

Sum with other alignment. Behavior and returned alignment type depend on relation between alignments of operands.

Returns: Value for sum as lower of incoming alignments 

template<int V>
aligned<?> operator +(const fixed<V> &) const

Sum with fixed value. Behavior and returned alignment type depend on relation between alignments of aligned<> operand and the value of V.

Returns: Adjusted aligned value of a sum. 

template<int OtherAl>
aligned operator +=(const aligned<OtherAl> &) const

Increments value for the aligned object if IndexAlignmentT is compatible with OtherAl

Returns: Aligned with incremented value. 

template<int OtherAl>
aligned operator -=(const aligned<OtherAl> &) const

Decrements value for the aligned object if IndexAlignmentT is compatible with OtherAl

Returns: Same type aligned with decremented value. 

template<int OtherAl>
aligned operator *=(const aligned<OtherAl> &) const

Multiplies value for the aligned object if IndexAlignmentT is compatible with OtherAl.

Returns: Same type aligned with multiplied value. 

template<int OtherAl>
aligned operator /=(const aligned<OtherAl> &) const

Divides value for the aligned object if IndexAlignmentT is compatible with OtherAl

Returns: Same type aligned with divided value.

NOTE:
This note does not apply to SYCL. The sdlt::aligned<> type supersedes the deprecated sdlt::aligned_offset<> type found in SDLT v1. It is strongly advised to use sdlt::aligned<>, however in this release a template alias is provided mapping sdlt::aligned_offset<> onto sdlt::aligned<>.

int

Represents an arbitrary integer value. In interfaces where fixed<> and aligned<> values supported you may also use plain old integer value. It provides least information among these three and so least facilitates compiler optimizations.

Parent topic: User-Level Interface
  • aligned_offset
    Represent an integer based offset whose value is a multiple of an IndexAlignment specified at compile time. #include <sdlt/aligned_offset.h>
  • fixed_offset
    Represent an integer based offset whose value specified at compile time. #include <sdlt/fixed_offset.h>
Level Two Title