.. index:: pair: group; Device class helper functions .. _doxid-dc/ddc/group___device_manager: Device class helper functions ============================= .. toctree:: :hidden: Overview ~~~~~~~~ Helper functions for sycl::device objects that do not directly map to any sycl::device member function. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct DPCTLDeviceVector* :target:`DPCTLDeviceVectorRef`; // global functions :ref:`DPCTL_API` :ref:`DPCTLSyclContextRef` :ref:`DPCTLDeviceMgr_GetCachedContext`(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef); :ref:`DPCTL_API` :ref:`__dpctl_give` const char* :ref:`DPCTLDeviceMgr_GetDeviceInfoStr`(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef); :ref:`DPCTL_API` :ref:`__dpctl_give` :ref:`DPCTLDeviceVectorRef` :ref:`DPCTLDeviceMgr_GetDevices`(int device_identifier); :ref:`DPCTL_API` size_t :ref:`DPCTLDeviceMgr_GetNumDevices`(int device_identifier); :ref:`DPCTL_API` int :ref:`DPCTLDeviceMgr_GetPositionInDevices`( :ref:`__dpctl_keep` :ref:`DPCTLSyclDeviceRef` DRef, int device_identifier ); :ref:`DPCTL_API` int64_t :ref:`DPCTLDeviceMgr_GetRelativeId`(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef); :ref:`DPCTL_API` void :ref:`DPCTLDeviceMgr_PrintDeviceInfo`(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef); void :ref:`DPCTLDeviceVector_Clear`(:ref:`DPCTLDeviceVectorRef` VRef); :ref:`DPCTLDeviceVectorRef` :ref:`DPCTLDeviceVector_Create`(void); :ref:`DPCTLDeviceVectorRef` :ref:`DPCTLDeviceVector_CreateFromArray`( size_t len, :ref:`DPCTLSyclDeviceRef`* elems ); void :ref:`DPCTLDeviceVector_Delete`(:ref:`DPCTLDeviceVectorRef` VRef); :ref:`DPCTLSyclDeviceRef` :ref:`DPCTLDeviceVector_GetAt`( :ref:`DPCTLDeviceVectorRef` VRef, size_t index ); size_t :ref:`DPCTLDeviceVector_Size`(:ref:`DPCTLDeviceVectorRef` VRef); .. _details-dc/ddc/group___device_manager: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Helper functions for sycl::device objects that do not directly map to any sycl::device member function. Global Functions ---------------- .. index:: pair: function; DPCTLDeviceMgr_GetCachedContext .. _doxid-dc/ddc/group___device_manager_1gabb587f003e809eaef26d7dbd253ec88e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` :ref:`DPCTLSyclContextRef` DPCTLDeviceMgr_GetCachedContext(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef) If the DPCTLSyclDeviceRef argument is a root device, then this function returns a cached default SYCL context for that device. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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. .. rubric:: Returns: A DPCTLSyclContextRef associated with the :ref:`DPCTLSyclDeviceRef ` argument passed to the function. If the :ref:`DPCTLSyclDeviceRef ` is not found in the cache, then returns a nullptr. .. index:: pair: function; DPCTLDeviceMgr_GetDeviceInfoStr .. _doxid-dc/ddc/group___device_manager_1ga496a3ecb3729a4aec2d16b2b11cb40d9: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` :ref:`__dpctl_give` const char* DPCTLDeviceMgr_GetDeviceInfoStr(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef) Returns a set of device info attributes as a string. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - DRef - Opaque pointer to a ``sycl::device`` .. rubric:: Returns: A formatted C string capturing the following attributes: * device name * driver version * vendor * profiler support * oneapi filter string .. index:: pair: function; DPCTLDeviceMgr_GetDevices .. _doxid-dc/ddc/group___device_manager_1gab7f1386fee08d194d4ad046221c02e18: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` :ref:`__dpctl_give` :ref:`DPCTLDeviceVectorRef` DPCTLDeviceMgr_GetDevices(int device_identifier) Returns a pointer to a std::vector containing the set of :ref:`DPCTLSyclDeviceRef ` pointers matching the passed in device_identifier bit flag. The device_identifier can be a combination of :ref:`DPCTLSyclBackendType ` and :ref:`DPCTLSyclDeviceType ` bit flags. The function returns all devices that match the specified bit flags. For example, .. ref-code-block:: cpp // 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); .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - device_identifier - A bitflag that can be any combination of :ref:`DPCTLSyclBackendType ` and :ref:`DPCTLSyclDeviceType ` enum values. .. rubric:: Returns: A :ref:`DPCTLDeviceVectorRef ` containing :ref:`DPCTLSyclDeviceRef ` objects that match the device identifier bit flags. .. index:: pair: function; DPCTLDeviceMgr_GetNumDevices .. _doxid-dc/ddc/group___device_manager_1ga2578ffe4d41ef3adbb690ea99bb5f664: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` size_t DPCTLDeviceMgr_GetNumDevices(int device_identifier) Get the number of available devices for given backend and device type combination. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - device_identifier - Identifies a device using a combination of :ref:`DPCTLSyclBackendType ` and :ref:`DPCTLSyclDeviceType ` enum values. The argument can be either one of the enum values or a bitwise OR-ed combination. .. rubric:: Returns: The number of available devices satisfying the condition specified by the device_identifier bit flag. .. index:: pair: function; DPCTLDeviceMgr_GetPositionInDevices .. _doxid-dc/ddc/group___device_manager_1ga1f86861af1da6e44aa917f1c20285325: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` int DPCTLDeviceMgr_GetPositionInDevices( :ref:`__dpctl_keep` :ref:`DPCTLSyclDeviceRef` DRef, int device_identifier ) Returns an index on the given device in the vector returned by :ref:`DPCTLDeviceMgr_GetDevices ` if found, -1 otherwise. The device_identifier can be a combination of :ref:`DPCTLSyclBackendType ` and :ref:`DPCTLSyclDeviceType ` bit flags. The function returns all devices that match the specified bit flags. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - DRef - A :ref:`DPCTLSyclDeviceRef ` opaque pointer. * - device_identifier - A bitflag that can be any combination of :ref:`DPCTLSyclBackendType ` and :ref:`DPCTLSyclDeviceType ` enum values. .. rubric:: Returns: If found, returns the position of the given device in the vector that would be returned by :ref:`DPCTLDeviceMgr_GetDevices ` if called with the same device_identifier argument. .. index:: pair: function; DPCTLDeviceMgr_GetRelativeId .. _doxid-dc/ddc/group___device_manager_1ga38db5431168d0d9883a62681b139762a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` int64_t DPCTLDeviceMgr_GetRelativeId(:ref:`__dpctl_keep` const :ref:`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())`` function for Device's platform. A relative device id of -1 indicates that the relative id could not be computed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - DRef - A :ref:`DPCTLSyclDeviceRef ` opaque pointer. .. rubric:: Returns: A relative id corresponding to the device, -1 indicates that a relative id value could not be computed. .. index:: pair: function; DPCTLDeviceMgr_PrintDeviceInfo .. _doxid-dc/ddc/group___device_manager_1ga4d424acf4bfc1365804d43aad4238846: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTL_API` void DPCTLDeviceMgr_PrintDeviceInfo(:ref:`__dpctl_keep` const :ref:`DPCTLSyclDeviceRef` DRef) Prints out the info::deivice attributes for the device that are currently supported by dpctl. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - DRef - A :ref:`DPCTLSyclDeviceRef ` opaque pointer. .. index:: pair: function; DPCTLDeviceVector_Clear .. _doxid-dc/ddc/group___device_manager_1gaaf299d11c92ca191c2c462b7770da85f: .. ref-code-block:: cpp :class: doxyrest-title-code-block void DPCTLDeviceVector_Clear(:ref:`DPCTLDeviceVectorRef` VRef) Delete all the elements of the std::vector. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - VRef - Opaque pointer to a vector. .. index:: pair: function; DPCTLDeviceVector_Create .. _doxid-dc/ddc/group___device_manager_1gab1ad93a83df63e792f0737f3511f9bb9: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTLDeviceVectorRef` DPCTLDeviceVector_Create(void) Create an opaque pointer to a std::vector of opaque pointers wrapping the SYCL data type. .. rubric:: Returns: Returns a new opaque pointer to a vector. .. index:: pair: function; DPCTLDeviceVector_CreateFromArray .. _doxid-dc/ddc/group___device_manager_1gaf953b4219f4a3190e19f33ddf9fe288d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTLDeviceVectorRef` DPCTLDeviceVector_CreateFromArray( size_t len, :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - len - Number of elements in the input array. * - elems - A C array whose elements will be copied into the returned vector. .. rubric:: Returns: Returns a new opaque pointer to a vector. .. index:: pair: function; DPCTLDeviceVector_Delete .. _doxid-dc/ddc/group___device_manager_1ga399969b37e0b59da8a69555d1656f473: .. ref-code-block:: cpp :class: doxyrest-title-code-block void DPCTLDeviceVector_Delete(:ref:`DPCTLDeviceVectorRef` VRef) Delete all elements in the vector and then delete the vector. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - VRef - Opaque pointer to a vector to be deleted. .. index:: pair: function; DPCTLDeviceVector_GetAt .. _doxid-dc/ddc/group___device_manager_1gaf0a733eb1b642540733ac816cb1a3097: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`DPCTLSyclDeviceRef` DPCTLDeviceVector_GetAt( :ref:`DPCTLDeviceVectorRef` VRef, size_t index ) Returns the element at the specified index. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - VRef - Opaque pointer to a vector. * - index - The index position of the element to be returned. .. rubric:: Returns: The element at the specified position, if the index position is out of bounds then a nullptr is returned. .. index:: pair: function; DPCTLDeviceVector_Size .. _doxid-dc/ddc/group___device_manager_1gaab476722fdab31a92d4fc17a7b20cc76: .. ref-code-block:: cpp :class: doxyrest-title-code-block size_t DPCTLDeviceVector_Size(:ref:`DPCTLDeviceVectorRef` VRef) Returns the number of elements in the vector. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - VRef - Opaque pointer to a vector. .. rubric:: Returns: The current size of the vector.