Device class helper functions¶

Overview¶

Helper functions for sycl::device objects that do not directly map to any sycl::device member function. More…

// typedefs

typedef struct DPCTLDeviceVector* DPCTLDeviceVectorRef;

// global functions

DPCTL_API DPCTLSyclContextRef
DPCTLDeviceMgr_GetCachedContext(__dpctl_keep const DPCTLSyclDeviceRef DRef);

DPCTL_API __dpctl_give const char*
DPCTLDeviceMgr_GetDeviceInfoStr(__dpctl_keep const DPCTLSyclDeviceRef DRef);

DPCTL_API __dpctl_give DPCTLDeviceVectorRef
DPCTLDeviceMgr_GetDevices(int device_identifier);

DPCTL_API size_t
DPCTLDeviceMgr_GetNumDevices(int device_identifier);

DPCTL_API int
DPCTLDeviceMgr_GetPositionInDevices(
    __dpctl_keep DPCTLSyclDeviceRef DRef,
    int device_identifier
    );

DPCTL_API int64_t
DPCTLDeviceMgr_GetRelativeId(__dpctl_keep const DPCTLSyclDeviceRef DRef);

DPCTL_API void
DPCTLDeviceMgr_PrintDeviceInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef);

void
DPCTLDeviceVector_Clear(DPCTLDeviceVectorRef VRef);

DPCTLDeviceVectorRef
DPCTLDeviceVector_Create(void);

DPCTLDeviceVectorRef
DPCTLDeviceVector_CreateFromArray(
    size_t len,
    DPCTLSyclDeviceRef* elems
    );

void
DPCTLDeviceVector_Delete(DPCTLDeviceVectorRef VRef);

DPCTLSyclDeviceRef
DPCTLDeviceVector_GetAt(
    DPCTLDeviceVectorRef VRef,
    size_t index
    );

size_t
DPCTLDeviceVector_Size(DPCTLDeviceVectorRef VRef);

Detailed Documentation¶

Helper functions for sycl::device objects that do not directly map to any sycl::device member function.

Global Functions¶

DPCTL_API DPCTLSyclContextRef
DPCTLDeviceMgr_GetCachedContext(__dpctl_keep const DPCTLSyclDeviceRef DRef)

If the DPCTLSyclDeviceRef argument is a root device, then this function returns a cached default SYCL context for that device.

Parameters:

DRef	A pointer to a sycl::device that will be used to search an internal map containing a cached “default” sycl::context for the device.

Returns:

A DPCTLSyclContextRef associated with the DPCTLSyclDeviceRef argument passed to the function. If the DPCTLSyclDeviceRef is not found in the cache, then returns a nullptr.

DPCTL_API __dpctl_give const char*
DPCTLDeviceMgr_GetDeviceInfoStr(__dpctl_keep const DPCTLSyclDeviceRef DRef)

Returns a set of device info attributes as a string.

Parameters:

DRef	Opaque pointer to a `sycl::device`

Returns:

A formatted C string capturing the following attributes:

device name
driver version
vendor
profiler support
oneapi filter string

DPCTL_API __dpctl_give DPCTLDeviceVectorRef
DPCTLDeviceMgr_GetDevices(int device_identifier)

Returns a pointer to a std::vector<sycl::DPCTLSyclDeviceRef> containing the set of DPCTLSyclDeviceRef pointers matching the passed in device_identifier bit flag.

The device_identifier can be a combination of DPCTLSyclBackendType and DPCTLSyclDeviceType bit flags. The function returns all devices that match the specified bit flags. For example,

// Returns all opencl devices
DPCTLDeviceMgr_GetDevices(DPCTLSyclBackendType::DPCTL_OPENCL);

// Returns all opencl gpu devices
DPCTLDeviceMgr_GetDevices(
    DPCTLSyclBackendType::DPCTL_OPENCL|DPCTLSyclDeviceType::DPCTL_GPU);

// Returns all gpu devices
DPCTLDeviceMgr_GetDevices(DPCTLSyclDeviceType::DPCTL_GPU);

Parameters:

device_identifier

A bitflag that can be any combination of DPCTLSyclBackendType and DPCTLSyclDeviceType enum values.

Returns:

A DPCTLDeviceVectorRef containing DPCTLSyclDeviceRef objects that match the device identifier bit flags.

DPCTL_API size_t
DPCTLDeviceMgr_GetNumDevices(int device_identifier)

Get the number of available devices for given backend and device type combination.

Parameters:

device_identifier

Identifies a device using a combination of DPCTLSyclBackendType and DPCTLSyclDeviceType enum values. The argument can be either one of the enum values or a bitwise OR-ed combination.

Returns:

The number of available devices satisfying the condition specified by the device_identifier bit flag.

DPCTL_API int
DPCTLDeviceMgr_GetPositionInDevices(
    __dpctl_keep DPCTLSyclDeviceRef DRef,
    int device_identifier
    )

Returns an index on the given device in the vector returned by DPCTLDeviceMgr_GetDevices if found, -1 otherwise.

The device_identifier can be a combination of DPCTLSyclBackendType and DPCTLSyclDeviceType bit flags. The function returns all devices that match the specified bit flags.

Parameters:

DRef	A DPCTLSyclDeviceRef opaque pointer.
device_identifier	A bitflag that can be any combination of DPCTLSyclBackendType and DPCTLSyclDeviceType enum values.

Returns:

If found, returns the position of the given device in the vector that would be returned by DPCTLDeviceMgr_GetDevices if called with the same device_identifier argument.

DPCTL_API int64_t
DPCTLDeviceMgr_GetRelativeId(__dpctl_keep const DPCTLSyclDeviceRef DRef)

Gives the index of the given device with respective to all the other devices of the same type in the device’s platform.

The relative device id of a device (Device) is computed by looking up the position of Device in the std::vector returned by calling the get_devices(Device.get_info<sycl::info::device::device_type>()) function for Device’s platform. A relative device id of -1 indicates that the relative id could not be computed.

Parameters:

DRef	A DPCTLSyclDeviceRef opaque pointer.

Returns:

A relative id corresponding to the device, -1 indicates that a relative id value could not be computed.

DPCTL_API void
DPCTLDeviceMgr_PrintDeviceInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef)

Prints out the info::deivice attributes for the device that are currently supported by dpctl.

Parameters:

DRef	A DPCTLSyclDeviceRef opaque pointer.

void
DPCTLDeviceVector_Clear(DPCTLDeviceVectorRef VRef)

Delete all the elements of the std::vector.

Parameters:

VRef	Opaque pointer to a vector.

DPCTLDeviceVectorRef
DPCTLDeviceVector_Create(void)

Create an opaque pointer to a std::vector of opaque pointers wrapping the SYCL data type.

Returns:

Returns a new opaque pointer to a vector.

DPCTLDeviceVectorRef
DPCTLDeviceVector_CreateFromArray(
    size_t len,
    DPCTLSyclDeviceRef* elems
    )

Create an opaque pointer to a std::vector created from the input raw array. The elements of the input array are deep copied before inserting the copies into the vector.

Parameters:

len	Number of elements in the input array.
elems	A C array whose elements will be copied into the returned vector.

Returns:

Returns a new opaque pointer to a vector.

void
DPCTLDeviceVector_Delete(DPCTLDeviceVectorRef VRef)

Delete all elements in the vector and then delete the vector.

Parameters:

VRef	Opaque pointer to a vector to be deleted.

DPCTLSyclDeviceRef
DPCTLDeviceVector_GetAt(
    DPCTLDeviceVectorRef VRef,
    size_t index
    )

Returns the element at the specified index.

Parameters:

VRef	Opaque pointer to a vector.
index	The index position of the element to be returned.

Returns:

The element at the specified position, if the index position is out of bounds then a nullptr is returned.

size_t
DPCTLDeviceVector_Size(DPCTLDeviceVectorRef VRef)

Returns the number of elements in the vector.

Parameters:

VRef	Opaque pointer to a vector.

Returns:

The current size of the vector.