Developer Guide and Reference

Download PDF
ID 767253
Date 10/31/2024
Public
Document Table of Contents
Document Table of Contents x
Developer Guide and Reference
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 Use Code Coverage in Microsoft Visual Studio* Use Profile Guided Optimization in Microsoft Visual Studio* Optimization Reports in Microsoft Visual Studio* Dialog Box Help
Dialog Box Help x
Use Intel® oneAPI DPC++/C++ Compiler dialog box Hardware Profile-Guided Optimization dialog box Options: Compilers dialog box Options: Intel Libraries for oneAPI dialog box Options: Converter dialog box Options: Optimization Reports dialog box Options: Profile Guided Optimization dialog box Profile Guided Optimization dialog box Options: Code Coverage dialog box Code Coverage dialog box Code Coverage Settings dialog box
Compiler Reference x
C/C++/SYCL Calling Conventions Compiler Options Floating-Point Operations Attributes Intrinsics Libraries Macros Pragmas Syntactic and Semantic Errors
Compiler Options x
Alphabetical Option List General Rules for Compiler Options What Appears in the Compiler Option Descriptions Optimization Options Advanced Optimization Options Code Generation Options Offload Compilation, OpenMP*, and Parallel Processing Options Interprocedural Optimization Options Profile Guided Optimization Options Optimization Report 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
Advanced Optimization Options x
ffreestanding, Qfreestanding fjump-tables fvec-allow-scalar-stores, Qvec-allow-scalar-stores 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 qmkl-sycl-impl, Qmkl-sycl-impl qopt-assume-no-loop-carried-dep, Qopt-assume-no-loop-carried-dep qopt-dword-index-for-array-of-structs, Qopt-dword-index-for-array-of-structs 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-prefetch-distance, Qopt-prefetch-distance qopt-prefetch-loads-only, Qopt-prefetch-loads-only qopt-streaming-stores, Qopt-streaming-stores qopt-zmm-usage, Qopt-zmm-usage qtbb, Qtbb unroll, Qunroll vec, Qvec vec-threshold, Qvec-threshold vecabi, Qvecabi
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
Offload Compilation, OpenMP*, and Parallel Processing Options x
device-math-lib fintelfpga fiopenmp, Qiopenmp flink-huge-device-code fno-sycl-libspirv fopenmp fopenmp-concurrent-host-device-compile, Qopenmp-concurrent-host-device-compile fopenmp-declare-target-scalar-defaultmap, Qopenmp-declare-target-scalar-defaultmap fopenmp-device-code-split, Qopenmp-device-code-split fopenmp-device-lib fopenmp-device-link, Qopenmp-device-link fopenmp-max-parallel-link-jobs, Qopenmp-max-parallel-link-jobs fopenmp-offload-mandatory, Qopenmp-offload-mandatory fopenmp-target-buffers, Qopenmp-target-buffers fopenmp-target-default-sub-group-size, Qopenmp-target-default-sub-group-size fopenmp-target-loopopt, Qopenmp-target-loopopt fopenmp-target-simd, Qopenmp-target-simd fopenmp-targets, Qopenmp-targets fsycl fsycl-add-default-spec-consts-image fsycl-allow-device-dependencies 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-fp64-conv-emu fsycl-help fsycl-host-compiler fsycl-host-compiler-options fsycl-id-queries-fit-in-int fsycl-instrument-device-code fsycl-link fsycl-max-parallel-link-jobs fsycl-optimize-non-user-code fsycl-pstl-offload fsycl-rdc fsycl-remove-unused-external-funcs fsycl-targets fsycl-unnamed-lambda fsycl-use-bitcode ftarget-compile-fast ftarget-export-symbols ftarget-register-alloc-mode, Qtarget-register-alloc-mode nolibsycl qopenmp, Qopenmp qopenmp-link qopenmp-simd, Qopenmp-simd qopenmp-stubs, Qopenmp-stubs reuse-exe Wno-sycl-strict Xopenmp-target Xs Xsycl-target
Interprocedural Optimization Options x
flto ipo, Qipo
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-names, Qopt-report-names qopt-report-phase, Qopt-report-phase qopt-report-stdout, Qopt-report-stdout
Floating-Point Options x
ffp-accuracy, Qfp-accuracy 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 inline-forceinline, Qinline-forceinline
Output, Debug, and Precompiled Header Options x
c debug (Linux*) debug (Windows*) Fa fasm-blocks Fe Fo Fp fsystem-debug 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 fmaintain-32-byte-stack-align, Qmaintain-32-byte-stack-align 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 fpreview-breaking-changes help MP nologo save-temps, Qsave-temps showIncludes sox 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 code_align const cpu_dispatch, cpu_specific target
Libraries x
Create Libraries Use Intel Shared Libraries Manage Libraries Redistribute Libraries When Deploying Applications Resolve References to Shared Libraries Redistributable Library Considerations 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 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
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 Supported OpenMP* Pragmas Pragmas Compatible with Other Compilers
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 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
OpenMP* Support SYCL* Support Compiler Sanitizers Intel® oneAPI Level Zero Vectorization Instrumented Profile-Guided Optimization Hardware Profile-Guided Optimization High-Level Optimization Interprocedural Optimization Methods to Optimize Code Size Optimization Reports Compiler Math Library SYCL* Device Library
OpenMP* Support x
Add OpenMP* Support Parallel Processing Model Worksharing Using OpenMP* Control Thread Allocation OpenMP* Library Support OpenMP* Contexts OpenMP* Offloading SPMD/SIMT and SIMD Models OpenMP* Advanced Issues OpenMP* Implementation-Defined Behaviors OpenMP* Examples
OpenMP* Library Support x
OpenMP* Runtime Library Routines Intel® Compiler Extension Routines to OpenMP* Execution Environment Stack Size Memory Allocation Thread Sleep Time Target Memory Allocation Target Offload See Also 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
SYCL* Support x
SYCL* Extensions Redistribute Your SYCL* Application CUDA* to SYCL* Migration
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
Compiler Math Library x
Use the 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
SYCL* Device Library x
Basic Arithmetic Operations and Simple Math Functions IMF Transcendental Math Functions
Basic Arithmetic Operations and Simple Math Functions x
Simple Integer Math Functions Basic Integer Arithmetic Operations Simple Arithmetic Operations with Rounding Mode Type Casting Functions for Floating-Point Numbers Type Casting Functions for Half-Precision Types Type Casting Functions for bfloat16 Type Simple Half-Precision Arithmetic Math Functions Half-Precision Comparison Functions
IMF Transcendental Math Functions x
IMF Device Library Usage Example IMF Device Library Function List IMF Device Library Trigonometric Functions IMF Device Library Hyperbolic Functions IMF Device Library Exponential Functions IMF Device Library Logarithmic Functions IMF Device Library Power Functions IMF Device Library Special Functions IMF Device Library Rounding Functions IMF Device Library Miscellaneous Functions
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
Developer Guide and Reference

Intel® Compiler Extension Routines to OpenMP*

The Intel® compiler implements the following group of routines as extensions to the OpenMP* runtime library:

  • Get and set the execution environment

  • Get and set the stack size for parallel threads

  • Memory allocation

  • Get and set the thread sleep time for the throughput execution mode

  • Target memory allocation

The Intel® extension routines described in this section can be used for low-level tuning to verify that the library code and application are functioning as intended. These routines are generally not recognized by other OpenMP-compliant compilers, which may cause the link stage to fail in the other compiler. To execute these OpenMP routines, use the /Qopenmp-stubs (Windows*) or -qopenmp-stubs (Linux*) option.

In most cases, environment variables can be used in place of the extension library routines. For example, the stack size of the parallel threads may be set using the OMP_STACKSIZE environment variable rather than the kmp_set_stacksize_s() library routine.

NOTE:

A runtime call to an Intel extension routine takes precedence over the corresponding environment variable setting.

Execution Environment

Function

Description

void kmp_set_defaults(char const *)

Sets OpenMP environment variables defined as a list of variables separated by "|" in the argument.

void kmp_set_library_throughput(void)

Sets execution mode to throughput, which is the default. Allows the application to determine the runtime environment. Use in multi-user environments.

void kmp_set_library_turnaround(void)

Sets execution mode to turnaround. Use in dedicated parallel (single user) environments.

void kmp_set_library_serial(void)

Sets execution mode to serial.

void kmp_set_library(int)

Sets execution mode indicated by the value passed to the function. Valid values are:

  • 1: Serial mode.

  • 2: Turnaround mode.

  • 3: Throughput mode.

Call this routine before the first parallel region is executed.

int kmp_get_library(void)

Returns a value corresponding to the current execution mode:

  • 1: Serial mode.

  • 2: Turnaround mode.

  • 3: Throughput mode.

Stack Size

Function

Description

size_t kmp_get_stacksize_s(void)

Returns the number of bytes that will be allocated for each parallel thread to use as its private stack. This value can be changed with kmp_set_stacksize_s() routine, prior to the first parallel region or via the KMP_STACKSIZE environment variable.

int kmp_get_stacksize(void)

Provided for backwards compatibility only. Use kmp_get_stacksize_s() routine for compatibility across different families of Intel processors.

void kmp_set_stacksize_s(size_tsize)

Sets to size the number of bytes that will be allocated for each parallel thread to use as its private stack. This value can also be set via the KMP_STACKSIZE environment variable. In order for kmp_set_stacksize_s() to have an effect, it must be called before the beginning of the first (dynamically executed) parallel region in the program.

void kmp_set_stacksize(int size)

Provided for backward compatibility only. Use kmp_set_stacksize_s() for compatibility across different families of Intel® processors.

Memory Allocation

The Intel® compiler implements a group of memory allocation routines as an extension to the OpenMP runtime library to enable threads to allocate memory from a heap local to each thread. These routines are: kmp_malloc(), kmp_calloc(), and kmp_realloc().

The memory allocated by these routines must also be freed by the kmp_free() routine. While you can allocate memory in one thread and then free that memory in a different thread, this mode of operation incurs a slight performance penalty.

Function

Description

void* kmp_malloc(size_t size)

Allocates memory block of size bytes from thread-local heap.

void* kmp_calloc(size_t nelem, size_t elsize)

Allocates array of nelem elements of size elsize from thread-local heap.

void* kmp_realloc(void* ptr, size_t size)

Reallocates memory block at address ptr and size bytes from thread-local heap.

void* kmp_free(void* ptr)

Frees memory block at address ptr from thread-local heap.

The memory must have been previously allocated with kmp_malloc(), kmp_calloc(), or kmp_realloc().

Thread Sleep Time

In the throughput OpenMP* Support Libraries, threads wait for new parallel work at the ends of parallel regions, and then sleep, after a specified period of time. This time interval can be set by the KMP_BLOCKTIME environment variable or by the kmp_set_blocktime() function.

Function

Description

int kmp_get_blocktime(void)

Returns the number of milliseconds that a thread should wait, after completing the execution of a parallel region, before sleeping, as set either by the KMP_BLOCKTIME environment variable or by kmp_set_blocktime().

void kmp_set_blocktime(int msec)

Sets the number of milliseconds that a thread should wait, after completing the execution of a parallel region, before sleeping. This routine affects the block time setting for the calling thread and any OpenMP team threads formed by the calling thread. The routine does not affect the block time for any other threads.

Target Memory Allocation

Function Description

void *omp_target_alloc_host(size_t size, int device_num)

Returns the address of a storage location that is size bytes in length allocated in host memory. The same pointer may be used to access the memory on the host and all supported devices.If the allocation was not successful, a null pointer is returned.

void *omp_target_alloc_device(size_t size, int device_num)

Returns the address of a storage allocation that is size bytes in length. Device allocations are owned by the device specified by device_num in device memory if present. Generally, the allocation can be accessed only by the device, but may be copied to other device or host allocated memory. If the allocation was not successful, a null pointer is returned.

void *omp_target_alloc_shared(size_t size, int device_num)

Returns the address of a storage allocation that is size bytes in length. The same pointer may be used to access the memory on the host and the specified device. Shared allocations are shared by the host and the specified device, and are intended to migrate between the host and the device. If the allocation was not successful, a null pointer is returned.

void *ompx_target_realloc(void *ptr, size_t size, int device_num)

Deallocates the device memory specified with ptr and allocates a new device memory with the specified size in bytes for the given device device_num. The returned memory can be accessed only by the specified device. The contents of the new memory object are the same as that of the old object prior to deallocation up to the minimum size of old allocated size and size argument.

void *ompx_target_realloc_host(void *ptr, size_t size, int device_num)

Deallocates the device memory specified with ptr and allocates a new device memory with the specified size in bytes for the given device device_num. The returned memory can be accessed by the host and all supported devices. The contents of the new memory object are the same as that of the old object prior to deallocation up to the minimum size of old allocated size and size argument.

void *ompx_target_realloc_device(void *ptr, size_t size, int device_num)

Deallocates the device memory specified with ptr and allocates a new device memory with the specified size in bytes for the given device device_num. The returned memory can be accessed only by the specified device. The contents of the new memory object are the same as that of the old object prior to deallocation up to the minimum size of old allocated size and size argument.

void *ompx_target_realloc_shared(void *ptr, size_t size, int device_num)

Deallocates the device memory specified with ptr and allocates a new device memory with the specified size in bytes for the given device device_num. The returned memory can be accessed by the host and the specified device. The contents of the new memory object are the same as that of the old object prior to deallocation up to the minimum size of old allocated size and size argument.

void *ompx_target_aligned_alloc(size_t alignment, size_t size, int device_num)

Allocates device memory that is aligned to the specified alignment argument align for the specified device device_num. The returned memory can be accessed only by the specified device.

void *ompx_target_aligned_alloc_host(size_t alignment, size_t size, int device_num)

Allocates device memory that is aligned to the specified alignment argument align for the specified device device_num. The returned memory can be accessed by the host and all supported devices.

void *ompx_target_aligned_alloc_device(size_t alignment, size_t size, int device_num)

Allocates device memory that is aligned to the specified alignment argument align for the specified device device_num. The returned memory can be accessed only by the specified device.

void *ompx_target_aligned_alloc_shared(size_t alignment, size_t size, int device_num)

Allocates device memory that is aligned to the specified alignment argument align for the specified device device_num. The returned memory can be accessed by the host and the specified device.

void *ompx_target_aligned_alloc_shared_with_hint(size_t align, size_t size, int access_hint, int device_num)

Allocates device memory that is aligned to the specified alignment argument align for the specified device device_num with the specified access_hint. The returned memory can be accessed by the host and the specified device. The following named constants are allowed for access_hint:

  • ompx_mem_hint_read_mostly
  • ompx_mem_hint_prefer_device
  • ompx_mem_hint_non_atomic_mostly
  • ompx_mem_hint_cached
  • ompx_mem_hint_uncached

Target Offload

Function Description

int ompx_get_device_info(int devce_num, int info_id, size_t info_size, void *info_value, size_t *info_size_ret)

Returns device information requested by info_id for device_num in the return parameter info_value. When info_value is NULL and info_size is 0, the function returns the correct size of the requested information in info_size_ret. The function returns zero if the query is successful, non-zero value otherwise. The following list shows the allowed named constants for info_id, their expected data types, and short description of the information. The function fails and returns a non-zero value if the requested device information is not available in the backend:

  • ompx_devinfo_ccs_id: int32_t: The compute command streamer (CCS) ID if the device supports it.

  • ompx_devinfo_eu_simd_width: uint32_t: The physical EU SIMD width.

  • ompx_devinfo_eus_per_subslice: uint32_t: The number of EUs per sub-slice.

  • ompx_devinfo_global_mem_cache_size: uint64_t: The cache size in bytes.

  • ompx_devinfo_global_mem_size: uint64_t: The total memory size in bytes available to the device.

  • ompx_devinfo_local_mem_size: uint32_t: The max shared local memory per group in bytes.

  • ompx_devinfo_max_clock_frequency: uint32_t: The max clock frequency in MHz.

  • ompx_devinfo_max_mem_alloc_size: size_t: The max memory allocation size in bytes.

  • ompx_devinfo_name: char *: The device name.

  • ompx_devinfo_num_eus: uint32_t: The total number of EUs.

  • ompx_devinfo_num_slices: uint32_t: The number of slices.

  • ompx_devinfo_num_threads_per_eu: uint32_t: The number of threads per EU.

  • ompx_devinfo_pci_id: uint32_t: The device ID from PCI configuration.

  • ompx_devinfo_plugin_name: char *: The name of the offload backend.

  • ompx_devinfo_subslices_per_slice: uint32_t: The number of sub-slices per slice.

  • ompx_devinfo_tile_id: int32_t: The tile ID if the device supports it.

int ompx_get_num_subdevices(int device_num, int level)

Returns the number of subdevices supported by the specified device ID (device_num) at the given level.

int ompx_target_register_host_pointer(void *ptr, size_t size, int device_num)

Registers the specified host pointer ptr for efficient memory copy between ptr and a device pointer allocated for device_num. The function returns a non-zero value if successful, zero otherwise.

NOTE:
This is only available for Linux.

void ompx_target_unregister_host_pointer(void *ptr, int device_num)

Unregister the specified host pointer ptr.

NOTE:
This is only available for Linux.

int ompx_target_prefetch_shared_mem(size_t num_ptrs, void **ptrs, size_t *sizes, int device_num)

Prefetches shared memory specified in the list of pointers (num_ptrs and ptrs) on the device device_num. The function returns zero if successful, non-zero otherwise.

int ompx_get_device_from_ptr(const void *ptr)

Returns OpenMP device number which the specified device pointer ptr is allocated on. The function returns a valid OpenMP device number if successful, a negative number otherwise.

Parent topic: OpenMP* Library Support
Level Two Title