Developer Guide and Reference

ID 767253
Date 10/31/2024
Public

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

Document Table of Contents

Compiler Sanitizers

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

OpenMP

The device-side AddressSanitizer (ASan) supports the following error checks for OpenMP (C/C++) device code:

Error Check Host/Device/Shared USM Group Private Global

out-of-bounds

Supported

Supported

Supported

use-after-free

Supported

n/a

n/A

misalign-access

Supported

Supported

Supported

Compile your OpenMP (C/C++) application and execute it with ASan enabled (only supported on GPU).

Compile and Run

Compile your OpenMP (C/C++) example with device-side ASan enabled:

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 (C/C++) offload on GPU device will cause errors.

SYCL

The device-side ASan supports the following error checks for SYCL device code:

Error Check Host/Device/Shared USM Local Memory sycl::buffer DeviceGlobal Private

out-of-bounds

Supported

Supported

Supported

Supported

Supported

use-after-free

Supported

n/a

Supported

n/a

n/a

misalign-access

Supported

Supported

Supported

Supported

n/a

double-free

Supported

n/a

n/a

n/a

n/a

bad-free

Supported

n/a

n/a

n/a

n/a

Compile your SYCL application and execute it with ASan enabled. ASan detects access on unified shared memory (USM), buffer, local memory, and device global; as well as bad-context, bad-free, out-of-bounds, use-after-free, etc. by default.

Compile and Run

Compile a SYCL example with ASan enabled:

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

Run an example on GPU with:

export ONEAPI_DEVICE_SELECTOR=level_zero:gpu
./demo

Run an example on CPU with:

export ONEAPI_DEVICE_SELECTOR=opencl:cpu
./demo

Runtime Flags

The following 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
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.

redzone

16

Minimal size (in bytes) of redzones around USM heap objects. Requirement: redzone >= 16, is a power of two.

max_redzone

2048

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

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.

detect_locals

true

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

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 (C/C++) 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.