Intel® oneAPI DPC++/C++ Compiler

Developer Guide and Reference

ID 767253
Date 3/31/2025
Public
Document Table of Contents

Compiler Sanitizers

Compiler sanitizers give you tools to detect bugs and/or errors, including buffer overflows, accesses, dangling pointers, uses-of-uninitialized memory and other types of undefined behavior. The compiler sanitizers work with OpenMP* and SYCL*.

System Requirements

  • Platform Support: CPU device and PVC GPU is supported on Linux.
  • GPU Configuration: This feature supports one PVC GPU card. For the Intel® oneAPI Level Zero (Level Zero) runtime, use the ZE_AFFINITY_MASK=0 environment variable to set this configuration.

Device-Side AddressSanitizer

The device-side AddressSanitizer (ASan) supports the error checks in the following table for SYCL and OpenMP device code.

Feature OpenMP SYCL

bad-context

n/a

Supported

bad-free

n/a

Supported

double-free

n/a

Supported

invalid argument

Supported

Supported

kernel filter

Not supported

Supported

OpenMP

Compile your OpenMP application and execute it with ASan enabled (only supported on GPU), for example:

icpx -fiopenmp -fopenmp-targets=spir64 -Xarch_device -fsanitize=address -g -O2 -o demo demo.cpp

Run on GPU with:

export LIBOMPTARGET_PLUGIN=unified_runtime     
export UR_ENABLE_LAYERS=UR_LAYER_ASAN
 ./demo

NOTE:
Setting the ONEAPI_DEVICE_SELECTOR=level_zero:gpu environment variable for OpenMP offload on GPU device will cause errors.

SYCL

Compile a SYCL example with ASan enabled:

icpx -fsycl -Xarch_device -fsanitize=address -g -O2 -o demo demo.cpp

Run on CPU with:

export ONEAPI_DEVICE_SELECTOR=opencl:cpu
./demo

Run on GPU with:

export ONEAPI_DEVICE_SELECTOR=level_zero:gpu
./demo

Runtime Flags

Runtime flags can be passed to the device-side ASan with the UR_LAYER_ASAN_OPTIONS environment variable, shown in the following example:

export UR_LAYER_ASAN_OPTIONS="quarantine_size_mb:1" ./demo
export UR_LAYER_ASAN_OPTIONS=redzone:32 ./demo 
export UR_LAYER_ASAN_OPTIONS=max_redzone:1024 ./demo export 
UR_LAYER_ASAN_OPTIONS="redzone:32;max_redzone:1024" ./demo

Flag Default Value Description
detect_locals

true

Enable runtime support for detecting out-of-bounds errors on local memory and shared local memory (SLM).

detect_privates

true

Enable runtime support for detecting out-of-bounds errors on private memory.

halt_on_error

true

Crash the program after printing the first error report. The flag is only effective if your code was compiled with the -fsanitize-recover=address compile option.

max_redzone

2048

Maximal size (in bytes) of redzones around USM heap objects.

quarantine_size_mb

0

The size (in MB) of quarantine used to detect use-after-free errors. Lower values may reduce memory usage, but increase the chance of false negatives. The default value is 0, indicating that while the sanitizer continues to detect use-after-free errors, it does not employ quarantine to minimize false negatives, thereby reducing memory overhead.

Device-Side MemorySanitizer

Device-side MemorySanitizer (MSan), a tool in LLVM used to detect uninitialized memory (UUM) in C/C++ code, supports OpenMP and SYCL device code starting with the Intel® oneAPI DPC++/C++ Compiler 2025.1 release. To activate this feature for device code, use the -Xarch_device -fsanitize=memory options when compiling your source code. This SYCL accelerator extension provides a device-side MemorySanitizer, focusing on device USM to address common use cases.

OpenMP

Compiling and running OpenMP code with MSan enabled:

  1. Compile your OpenMP example with device-side MemorySanitizer enabled:
    icpx -fiopenmp -fopenmp-targets=spir64 -Xarch_device -fsanitize=memory -g -o demo demo.cpp
  2. Run your example on GPU:
    export LIBOMPTARGET_PLUGIN=unified_runtime     
    export UR_ENABLE_LAYERS=UR_LAYER_MSAN
    export ZE_AFFINITY_MASK=0
    ./demo

NOTE:
Setting the ONEAPI_DEVICE_SELECTOR=level_zero:gpu environment variable for OpenMP offload on GPU device will cause errors.

SYCL

Compiling and running OpenMP code with MSan enabled:

  1. Compile your SYCL example with device-side MemorySanitizer enabled:
    icpx -fsycl -Xarch_device -fsanitize=memory -g -o demo demo.cpp
  2. Run your example on GPU:
    export ZE_AFFINITY_MASK=0
    export ONEAPI_DEVICE_SELECTOR=level_zero:gpu 
    ./demo
  3. Run your example on CPU:
    export ONEAPI_DEVICE_SELECTOR=opencl:cpu 
    ./demo

Limitations

The compiler sanitizers have the following limitations:

  • Kernel execution is sequential. Concurrent execution is forced to into sequential execution when device-side ASan is enabled.
  • Device-side ASan may lead to an increase of the usage of private memory, causing a reduction in the maximum workgroup size a kernel can support. In this case, you may encounter a UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE error message. To fix this, you need to reduce the SYCL local workgroup size or OpenMP overlay management protocol (OMP) teams.
  • A large number of workgroups on a GPU may lead to the device-side ASan skipping an out-of-bound check for private/local memory.
  • OpenMP (C/C++) only supports execution on a GPU device.

See Also