DPCT Namespace Usage Guide

DPCT namespace provides helper functions and macros to assist the migration of input source code. DPCT namespace helper functions are implemented in header files, and are available in the include folder of the Intel® DPC++ Compatibility Tool install path.

Note

After migration, it is recommended that you continue development using DPC++, SYCL, and C++ standard APIs, rather than continue development based on DPCT namespace helper functions and macros.

The following sections describe different domains of helper functions and macros in more detail.

Macros

There are three macros used to control the behavior of the helper functions: DPCT_USM_LEVEL_NONE, DPCT_NAMED_LAMBDA and DPCT_COMPATIBILITY_TEMP.

Note

Do not manually define these macros. They are automatically defined by the Intel® DPC++ Compatibility tool according to the options specified in the dpct command line.

DPCT_USM_LEVEL_NONE If the --usm-level=none option of Intel® DPC++ Compatibility Tool is used, then DPCT_USM_LEVEL_NONE is defined before DPCT namespace helper header files are included into migrated code. By default, this macro is not defined. If DPCT_USM_LEVEL_NONE is defined, corresponding helper functions guarded by this macro are active, and the resulting migrated code will use buffer-based memory functions instead of USM-based memory functions.
DPCT_NAMED_LAMBDA If the --sycl-named-lambda option of Intel® DPC++ Compatibility Tool is used, then DPCT_NAMED_LAMBDA is defined before DPCT namespace helper header files are included in migrated code. By default, this macro is not defined. If DPCT_NAMED_LAMBDA is defined, corresponding helper code guarded by this macro is active and the resulting migrated code is using it.
DPCT_COMPATIBILITY_TEMP DPCT_COMPATIBILITY_TEMP is defined as an integer number in helper header files, and is inserted into migrated code by the Intel® DPC++ Compatibility Tool. You can replace this macro in the generated code or change the value of DPCT_COMPATIBILITY_TEMP according to your needs.

Atomic Helper Functions

The atomic helper functions are available in the atomic.hpp header file. Atomic helper functions are wrappers around standard SYCL atomic operations.

Device Helper Functions

The device helper functions are available in the device.hpp header file. There are three classes defined: device_info, device_ext and dev_mgr. Find more details in the device.hpp file.

Device Helper Function Classes

device_info

device_info is used to present information enumerated by SYCL device information descriptors.

device_ext

device_ext is a subclass of SYCL device class cl::sycl::device.

device_ext adds a default SYCL queue associated with the device on top of SYCL device, along with interface to query device information, and initializes device_info class.
dev_mgr dev_mgr is a singleton, intended to manage all DPC++-capable devices available on the system (e.g. CPU, GPU, etc.). dev_mgr selects one of the available devices as current device, according to the behavior of SYCL default device selector. Display the current device using current_device(), and change the current device using select_device().
Helper Functions

get_current_device()

Returns the current device in the device manager.

get_default_queue()

Returns the default queue associated with the current device in the device manager.

get_device(unsigned int id)

Returns the device_extobject by integer id.

cpu_device Returns the device_ext object associated with the SYCL CPU device.
get_default_context()

Returns the SYCL context of the default queue associated with the current device in device manager.

Memory Helper Functions

SYCL Buffer-Based Memory Model Helper Functions

Device Memory Manager (mem_mgr )

Device memory manager is a singleton, intended to assist with migration of memory API calls if a SYCL buffer-based memory model is used. It provides API to allocate and free host virtual address space bound to cl::sycl::buffer, and transform between the host virtual address and cl::sycl::buffer. By default, the mem_mgr maintains 128GB of virtual memory space. You can change virtual memory space as required by changing the value of mapped_region_size in the memory.hpp file.

Helper Functions to Get SYCL Buffer From the Host Virtual Address

get_buffer_and_offset(const void *ptr)

Where ptris the host virtual address. This function returns the cl::sycl::buffer bound to the host virtual address, and the offset of the host virtual address in the cl::sycl::buffer.

get_buffer(const void *ptr)

Where ptris the host virtual address. Returns the sycl::buffer bound to the host virtual address.

General Helper Functions

General memory helper functions are used to assist the migration of memory API calls, like memory allocation, memory copy, and memory set, for both USM and buffer-based memory model. The helper functions are listed below. Find more details in the memory.hpp file.

Helper Functions Assisting Migration of Device Memory Variables

To assist with migration of variables declared with global and constant device memory attributes, the helper functions provide the following template classes:

global_memory Represents a SYCL global memory variable.
constant_memory Represents a SYCL constant memory variable.
shared_memory Represents memory that can be accessed by host and device, in the same way as DPC++ USM shared memory.

Main Member functions of Memory Classes

get_prt()

Returns memory pointer of the memory object. It is a virtual pointer when buffer-based memory model is used, and it is a device pointer when a USM memory model is used.

get_size()

Returns the size of a memory object.

get_access()

Returns the accessor to the memory object. If a USM memory model is used, this function returns a dpct_accessor_t object for the device memory object. dpct_accessor_t is a helper type, which contains the data pointer, data dimension information, and provides a method to access the memory. If a buffer-based memory model is used, this function returns cl::sycl::accessor for the device memory object..

init()

Allocates memory after a SYCL device is selected, and initializes device memory if it has initial value. This API should be called after the SYCL device is selected.

Kernel Helper Functions

Kernel helper functions provide a structure kernel_function_info to keep DPC++ kernel information, and provide a utility function get_kernel_function_info() to get the kernel information.

Image Helper Functions

The image helper functions provide class wrappers to assist the migration of texture API. Find more details on image helper functions in the image.hpp file.

template class image_wrapper

The wrapper of cl::sycl::image. It provides methods to attach/detach 1D/2D/3D data to/from cl::sycl::image and method get_access() to return the SYCL image accessor.

class image_accessor_ext

Wraps SYCL sampler and SYCL image accessor together. Provides the read() method to read data from the accessor.

class image_data

Represents the data used to create a cl::sycl::image object. Supports the following data types:

  • matrix for 2D or 3D matrix data (see image_matrix class)
  • linear for 1D linear array
  • pitch for pitched 2D or 3D memory data (pitched_data class)

class image_matrix

Represents 2D/3D matrix data for an image. It contains the image channel information, dimensions, size of each dimension, and the raw data pointer.

class pitched_data

Represents the 2D/3D pitched data for an image.

structimage_channel

Keeps image channel information; including order, data width, and type information.

class image_info

Image sampling information; including addressing mode, filtering mode, and normalization mode.

image_wrapper operations API: create_image_wrapper()

Creates an object of the helper image class according to the parameters provided.

Utility Helper Functions

util.hpp Common utility helper functions.
blas_utils.hpp BLAS-specific utility helper functions.
dpc_utils.hpp Intel® oneAPI DPC++ Library-specific utility helper functions.