Developer Guide and Reference

  • 2021.3
  • 06/28/2021
  • Public Content

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 DPC++ code generated by the Intel® DPC++ Compatibility Tool. You can copy these header files if needed and include them with the generated code.
There are two namespaces defined:
dpct::
and
dpct::detail::
.
dpct::
is used in the code generated by the Intel® DPC++ Compatibility Tool.
dpct::detail::
is an internal implementation and should not be used in DPC++ source files directly, as the API and implementations inside the
dpct::detail::
namespace can be changed at any time without notice.
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
.
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 (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()
.
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_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

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
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 helper functions are listed below. Find more details in the
memory.hpp
file.
  • dpct_malloc()
  • dpct_free()
  • dpct_memcpy()
  • async_dpct_memcpy()
  • dpct_memset()
  • async_dpct_memset()
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.
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
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.
Memory Helper Function Classes
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
.
Memory Helper Functions
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.
Additional oneAPI DPC++ Library Specific Utility Header Files
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

util.hpp
Common utility helper functions.
blas_utils.hpp
BLAS-specific utility helper functions.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.