DPCT Namespace Usage Guide

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Download PDF

ID 768918

Date 7/13/2023

Version

Public

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

Visible to Intel only — GUID: GUID-F6C90776-F5C7-4BEB-95EA-BE601E852E20

View Details

DPCT Namespace Usage Guide

The 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 (include/dpct) of the Intel® DPC++ Compatibility Tool install path. These header files are intended to become part of your new SYCL* code generated by Intel® DPC++ Compatibility Tool. You can copy these header files if needed and include them with the generated code.

There are three namespaces defined:

Namespace	Description
`dpct::`	This namespace is used in the code generated by Intel® DPC++ Compatibility Tool.
`dpct::detail::`	This namespace is an internal implementation and should not be used in SYCL source files directly, as the API and implementations inside the `dpct::detail::` namespace can be changed at any time without notice.
`dpct::deprecated::`	This namespace is for functionality that has been introduced for compatibility purposes, but relies on deprecated C++ features, that have been removed or will be removed in the future standards. Use of deprecated functionality in the `dpct::deprecated::` namespace should be avoided.

NOTE:

After migration, it is recommended that you continue development using 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

The following table lists the macros used to control the behavior of the helper functions:

Macro	Description
`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 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.

NOTE:

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

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.

The following classes are defined in the device.hpp header file:

Class	Description
`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 SYCL-capable devices available on the system (for example CPU or GPU). `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()`.

Class

Description

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 SYCL-capable devices available on the system (for example CPU or GPU). 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().

Find more details in the device.hpp file.

The following table lists the device helper functions:

Function	Description
`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_ext`object 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

The following table lists SYCL buffer-based memory model helper functions:

Function	Description
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.

Function

Description

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.

The following table lists helper functions to get the SYCL buffer from host virtual address:

Function	Description
`get_buffer_and_offset(const void *ptr)`	Where `ptr`is 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 `ptr`is 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 following helper functions are available:

dpct_malloc()
dpct_free()
dpct_memcpy()
async_dpct_memcpy()
dpct_memset()
async_dpct_memset()

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:

Function	Description
`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 SYCL USM shared memory.

The following table lists main member functions of memory classes:

Function	Description
`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 SYCL 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.

Wrapper	Description
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.
Struct `image_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.

Intel® oneAPI DPC++ Library Specific Utility Helper functions

The helper functions provided by the header files included in dpl_utils.hpp include algorithm functions, memory functions, iterators, and a container for managing data on a device.

Algorithm Helper Functions

The algorithm helper functions are available in the dpl_extras/algorithm.h header file. Algorithm helper functions are wrappers around Intel® oneAPI DPC++ Library (oneDPL) algorithm functions.

Mask-predicated Algorithm Functions

Mask-predicated algorithm functions have parameter lists like the algorithms with the same name in the C++ standard library. These functions accept an additional iterator pointing to a set of values that indicate whether the corresponding elements of the other inputs to the function should be processed by the algorithm. The predicate provided to these functions is applied to a value in the mask, rather than the element of the input data, and if the predicate returns true the corresponding element of the input data is manipulated by the algorithm.

The mask-predicated algorithm functions in the dpl_extras/algorithm.h header file are:

copy_if
partition
partition_copy
remove_if
remove_copy_if
replace_if
replace_copy_if
stable_partition_copy
stable_partition
transform_if

Key-value Pair Algorithm Functions

Key-value pair algorithm functions have parameter lists like the algorithms with the same name in the C++ standard library. The functions accept two sets of input data instead of one: the first representing a set of keys and the second representing the set of values associated with each key. These algorithm functions create zip_iterators and invoke the standard algorithm provided in oneDPL so that the key-value pairs are processed as single data elements.

The key-value pair algorithm functions in the dpl_extras/algorithm.h header file are:

unique
unique_copy
merge
sort
stable_sort
set_difference
set_intersection
set_symmetric_difference
set_union

Additional Algorithm Functions

Function	Description
`partition_point`	Implementation of the C++ standard library algorithm that accepts an execution policy, enabling parallel execution.
`transform_if`	Applies a unary operation to every element in the input for which the predicate provided returns true. A mask-predicated version of the function is also provided.
`iota`	Extends the C++ standard library algorithm by accepting a step in addition to the input iterators and initial value. The step is used to compute the next value in the sequence generated.
`inner_product`	Implementation of the C++ standard library algorithm that accepts an execution policy, enabling parallel execution. The binary operation provided for reduction must be associative and commutative.
`for_each_index`	Assigns each element in the input range provided the result of the unary operator invoked with the element’s index in the input range.

Memory Helper Functions

The dpl_extras/memory.h header file provides classes and functions for working with device memory.

The following table lists memory helper classes:

Class	Description
`device_pointer`	Pointer type that points to memory stored on a device.
`device_iterator`	Iterator type returned by `device_vector` begin and end methods.
`device_reference`	Reference type returned by `device_vector` element access operator.

The device_vector implementation that uses the device_iterator and device_reference classes is defined in dpl_extras/vector.h.

The following table list memory helper functions:

Function	Description
`malloc_device`	Allocates memory for use on a device.
`free_device`	Deallocates memory allocated with `malloc_device`.
`device_new`	Allocates memory for use on a device large enough to hold the requested number of elements of the type specified.
`device_delete`	Deallocates memory allocated using `device_new`.
`get_device_pointer`	Constructs a `device_pointer` from a raw pointer.
`get_raw_pointer`	Returns a raw pointer from a `device_pointer` instance.

oneAPI DPC++ Library Specific Utility Header Files

The following table lists utility header files specific to the oneAPI DPC++ Library:

Header File	Description
`functional.h`	Contains the implementation of the function objects used in the definitions of the algorithm functions described above.
`iterator.h`	Provides an implementation of `constant_iterator`, an iterator that is constructed with a value and when dereferenced will only return that value.
`vector.h`	Provides an implementation of `device_vector`, a container for managing data elements stored in device memory.

Utility Helper Functions

The following table lists header files that define utility functions:

Header File	Description
`util.hpp`	Common utility helper functions.
`blas_utils.hpp`	BLAS-specific utility helper functions.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® DPC++ Compatibility Tool Developer Guide and Reference

DPCT Namespace Usage Guide

Macros

Atomic Helper Functions

Device Helper Functions

Memory Helper Functions

Kernel Helper Functions

Image Helper Functions

Intel® oneAPI DPC++ Library Specific Utility Helper functions

Utility Helper Functions