|
| 1 | +//===-- dpctl_sycl_device_manager.h - A manager for sycl devices -*-C++-*- ===// |
| 2 | +// |
| 3 | +// Data Parallel Control (dpCtl) |
| 4 | +// |
| 5 | +// Copyright 2020-2021 Intel Corporation |
| 6 | +// |
| 7 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 8 | +// you may not use this file except in compliance with the License. |
| 9 | +// You may obtain a copy of the License at |
| 10 | +// |
| 11 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | +// |
| 13 | +// Unless required by applicable law or agreed to in writing, software |
| 14 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 15 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 16 | +// See the License for the specific language governing permissions and |
| 17 | +// limitations under the License. |
| 18 | +// |
| 19 | +//===----------------------------------------------------------------------===// |
| 20 | +/// |
| 21 | +/// \file |
| 22 | +/// This file declares a set of helper functions to query about the available |
| 23 | +/// SYCL devices and backends on the system. |
| 24 | +/// |
| 25 | +//===----------------------------------------------------------------------===// |
| 26 | + |
| 27 | +#pragma once |
| 28 | + |
| 29 | +#include "Support/DllExport.h" |
| 30 | +#include "Support/ExternC.h" |
| 31 | +#include "Support/MemOwnershipAttrs.h" |
| 32 | +#include "dpctl_data_types.h" |
| 33 | +#include "dpctl_sycl_types.h" |
| 34 | +#include "dpctl_vector.h" |
| 35 | + |
| 36 | +DPCTL_C_EXTERN_C_BEGIN |
| 37 | + |
| 38 | +/** |
| 39 | + * @defgroup DeviceManager Device management helper functions |
| 40 | + */ |
| 41 | + |
| 42 | +/*! |
| 43 | + * @brief Contains a #DPCTLSyclDeviceRef and #DPCTLSyclContextRef 2-tuple that |
| 44 | + * contains a sycl::device and a sycl::context associated with that device. |
| 45 | + */ |
| 46 | +typedef struct DeviceAndContextPair |
| 47 | +{ |
| 48 | + DPCTLSyclDeviceRef DRef; |
| 49 | + DPCTLSyclContextRef CRef; |
| 50 | +} DPCTL_DeviceAndContextPair; |
| 51 | + |
| 52 | +// Declares a set of types abd functions to deal with vectors of |
| 53 | +// DPCTLSyclDeviceRef. Refer dpctl_vector_macros.h |
| 54 | +DPCTL_DECLARE_VECTOR(Device) |
| 55 | + |
| 56 | +/*! |
| 57 | + * @brief Checks if two ::DPCTLSyclDeviceRef objects point to the same |
| 58 | + * sycl::device. |
| 59 | + * |
| 60 | + * DPC++ 2021.1.2 has some bugs that prevent the equality of sycl::device |
| 61 | + * objects to work correctly. The DPCTLDeviceMgr_AreEq implements a workaround |
| 62 | + * to check if two sycl::device pointers are equivalent. Since, DPC++ uses |
| 63 | + * std::shared_pointer wrappers for sycl::device objects we check if the raw |
| 64 | + * pointer (shared_pointer.get()) for each device are the same. One caveat is |
| 65 | + * that the trick works only for non-host devices. The function evaluates host |
| 66 | + * devices separately and always assumes that all host devices are equivalent, |
| 67 | + * while checking for the raw pointer equivalent for all other types of devices. |
| 68 | + * The workaround will be removed once DPC++ is fixed to correctly check device |
| 69 | + * equivalence. |
| 70 | + * |
| 71 | + * @param DRef1 First opaque pointer to a sycl device. |
| 72 | + * @param DRef2 Second opaque pointer to a sycl device. |
| 73 | + * @return True if the underlying sycl::device are same, false otherwise. |
| 74 | + * @ingroup DeviceManager |
| 75 | + */ |
| 76 | +bool DPCTLDeviceMgr_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DRef1, |
| 77 | + __dpctl_keep const DPCTLSyclDeviceRef DRef2); |
| 78 | + |
| 79 | +/*! |
| 80 | + * @brief Returns a pointer to a std::vector<sycl::DPCTLSyclDeviceRef> |
| 81 | + * containing the set of ::DPCTLSyclDeviceRef pointers matching the passed in |
| 82 | + * device_identifier bit flag. |
| 83 | + * |
| 84 | + * The device_identifier can be a combination of #DPCTLSyclBackendType and |
| 85 | + * #DPCTLSyclDeviceType bit flags. The function returns all devices that |
| 86 | + * match the specified bit flags. For example, |
| 87 | + * |
| 88 | + * @code |
| 89 | + * // Returns all opencl devices |
| 90 | + * DPCTLDeviceMgr_GetDevices(DPCTLSyclBackendType::DPCTL_OPENCL); |
| 91 | + * |
| 92 | + * // Returns all opencl gpu devices |
| 93 | + * DPCTLDeviceMgr_GetDevices( |
| 94 | + * DPCTLSyclBackendType::DPCTL_OPENCL|DPCTLSyclDeviceType::DPCTL_GPU); |
| 95 | + * |
| 96 | + * // Returns all gpu devices |
| 97 | + * DPCTLDeviceMgr_GetDevices(DPCTLSyclDeviceType::DPCTL_GPU); |
| 98 | + * @endcode |
| 99 | + * |
| 100 | + * @param device_identifier A bitflag that can be any combination of |
| 101 | + * #DPCTLSyclBackendType and #DPCTLSyclDeviceType |
| 102 | + * enum values. |
| 103 | + * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects |
| 104 | + * that match the device identifier bit flags. |
| 105 | + * @ingroup DeviceManager |
| 106 | + */ |
| 107 | +DPCTL_API |
| 108 | +__dpctl_give DPCTLDeviceVectorRef |
| 109 | +DPCTLDeviceMgr_GetDevices(int device_identifier); |
| 110 | + |
| 111 | +/*! |
| 112 | + * @brief Returns the default sycl context inside an opaque DPCTLSyclContextRef |
| 113 | + * pointer for the DPCTLSyclDeviceRef input argument. |
| 114 | + * |
| 115 | + * @param DRef A pointer to a sycl::device that will be used to |
| 116 | + * search an internal map containing a cached "default" |
| 117 | + * sycl::context for the device. |
| 118 | + * @return A #DPCTL_DeviceAndContextPair struct containing the cached |
| 119 | + * #DPCTLSyclContextRef associated with the #DPCTLSyclDeviceRef argument passed |
| 120 | + * to the function. The DPCTL_DeviceAndContextPair also contains a |
| 121 | + * #DPCTLSyclDeviceRef pointer pointing to the same device as the input |
| 122 | + * #DPCTLSyclDeviceRef. The returned #DPCTLSyclDeviceRef was cached along with |
| 123 | + * the #DPCTLSyclContextRef. This is a workaround till device equality is |
| 124 | + * properly fixed in DPC++. If the #DPCTLSyclDeviceRef is not found in the cache |
| 125 | + * then DPCTL_DeviceAndContextPair contains a pair of nullptr. |
| 126 | + * @ingroup DeviceManager |
| 127 | + */ |
| 128 | +DPCTL_API |
| 129 | +DPCTL_DeviceAndContextPair DPCTLDeviceMgr_GetDeviceAndContextPair( |
| 130 | + __dpctl_keep const DPCTLSyclDeviceRef DRef); |
| 131 | + |
| 132 | +/*! |
| 133 | + * @brief Get the number of available devices for given backend and device type |
| 134 | + * combination. |
| 135 | + * |
| 136 | + * @param device_identifier Identifies a device using a combination of |
| 137 | + * #DPCTLSyclBackendType and #DPCTLSyclDeviceType |
| 138 | + * enum values. The argument can be either one of |
| 139 | + * the enum values or a bitwise OR-ed combination. |
| 140 | + * @return The number of available devices satisfying the condition specified |
| 141 | + * by the device_identifier bit flag. |
| 142 | + * @ingroup DeviceManager |
| 143 | + */ |
| 144 | +DPCTL_API |
| 145 | +size_t DPCTLDeviceMgr_GetNumDevices(int device_identifier); |
| 146 | + |
| 147 | +/*! |
| 148 | + * @brief Prints out the info::deivice attributes for the device that are |
| 149 | + * currently supported by dpCtl. |
| 150 | + * |
| 151 | + * @param DRef A #DPCTLSyclDeviceRef opaque pointer. |
| 152 | + * @ingroup DeviceManager |
| 153 | + */ |
| 154 | +DPCTL_API |
| 155 | +void DPCTLDeviceMgr_PrintDeviceInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef); |
| 156 | + |
| 157 | +DPCTL_C_EXTERN_C_END |
0 commit comments