diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 3000cfc16a..72eba89059 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -298,7 +298,7 @@ cdef class SyclDevice(_SyclDevice): if ret == -1: raise SyclDeviceCreationError( "Could not create a SyclDevice with the selector string " - "'{selector_string}'".format(selector_string=arg) + "'{selector_string}'".format(selector_string=arg) ) elif isinstance(arg, _SyclDevice): ret = self._init_from__SyclDevice(arg) @@ -373,7 +373,7 @@ cdef class SyclDevice(_SyclDevice): Returns: device_type: The type of device encoded as a device_type enum. Raises: - A ValueError is raised if the device type is not recognized. + ValueError: If the device type is not recognized. """ cdef _device_type DTy = ( DPCTLDevice_GetDeviceType(self._device_ref) @@ -393,61 +393,115 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_host(self): - "Returns True if this device is a host device, False otherwise" + """ Returns True if this device is a host device, False otherwise. + + Returns: + bool: Indicates if the device is a host device. + """ cdef _aspect_type AT = _aspect_type._host return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_cpu(self): - "Returns True if this device is a CPU device, False otherwise" + """ Returns True if this device is a CPU device, False otherwise. + + Returns: + bool: Indicates if the device is a cpu. + """ cdef _aspect_type AT = _aspect_type._cpu return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_gpu(self): - "Returns True if this device is a GPU device, False otherwise" + """ Returns True if this device is a GPU device, False otherwise. + + Returns: + bool: Indicates if the device is a gpu. + """ cdef _aspect_type AT = _aspect_type._gpu return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_accelerator(self): - "Returns True if this device is an accelerator device, False otherwise" + """ Returns True if this device is an accelerator device, False + otherwise. + + SYCL considers an accelerator to be a device that usually uses a + peripheral interconnect for communication. + + Returns: + bool: Indicates if the device is an accelerator. + """ cdef _aspect_type AT = _aspect_type._accelerator return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_custom(self): - "Returns True if this device is a custom device, False otherwise" + """ Returns True if this device is a custom device, False otherwise. + + A custom device can be a dedicated accelerator that can use the + SYCL API, but programmable kernels cannot be dispatched to the device, + only fixed functionality is available. Refer SYCL spec for more details. + + Returns: + bool: Indicates if the device is a custom SYCL device. + """ cdef _aspect_type AT = _aspect_type._custom return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_fp16(self): - """ Returns True if kernels submitted to this device - may use 16-bit floating point types, False otherwise + """ Returns True if the device supports half-precision floating point + operations, False otherwise. + + Returns: + bool: Indicates that the device supports half precision floating + point operations. """ cdef _aspect_type AT = _aspect_type._fp16 return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_fp64(self): - """ Returns True if kernels submitted to this device - may use 64-bit floating point types, False otherwise + """ Returns True if the device supports 64-bit precision floating point + operations, False otherwise. + + Returns: + bool: Indicates that the device supports 64-bit precision floating + point operations. """ cdef _aspect_type AT = _aspect_type._fp64 return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_atomic64(self): - """ Returns True if kernels submitted to this device - may perform 64-bit atomic operations, False otherwise + """ Returns true if the device supports a basic set of atomic + operations, False otherwise. + + Indicates that the device supports the following atomic operations on + 64-bit values: + - atomic::load + - atomic::store + - atomic::fetch_add + - atomic::fetch_sub + - atomic::exchange + - atomic::compare_exchange_strong + - atomic::compare_exchange_weak + + Returns: + bool: Indicates that the device supports a basic set of atomic + operations on 64-bit values. """ cdef _aspect_type AT = _aspect_type._atomic64 return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_image(self): - """ Returns True if this device supports images, False otherwise + """ Returns True if the device supports images, False otherwise (refer + Sec 4.7.3 of SYCL 2020 spec). + + Returns: + bool: Indicates that the device supports images """ cdef _aspect_type AT = _aspect_type._image return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -455,7 +509,11 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_online_compiler(self): """ Returns True if this device supports online compilation of - device code, False otherwise + device code, False otherwise. + + Returns: + bool: Indicates that the device supports online compilation of + device code. """ cdef _aspect_type AT = _aspect_type._online_compiler return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -463,7 +521,11 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_online_linker(self): """ Returns True if this device supports online linking of - device code, False otherwise + device code, False otherwise. + + Returns: + bool: Indicates that the device supports online linking of device + code. """ cdef _aspect_type AT = _aspect_type._online_linker return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -471,7 +533,10 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_queue_profiling(self): """ Returns True if this device supports queue profiling, - False otherwise + False otherwise. + + Returns: + bool: Indicates that the device supports queue profiling. """ cdef _aspect_type AT = _aspect_type._queue_profiling return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -479,7 +544,10 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_usm_device_allocations(self): """ Returns True if this device supports explicit USM allocations, - False otherwise + False otherwise (refer Section 4.8 of SYCL 2020 specs). + + Returns: + bool: Indicates that the device supports explicit USM allocations. """ cdef _aspect_type AT = _aspect_type._usm_device_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -487,7 +555,11 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_usm_host_allocations(self): """ Returns True if this device can access USM-host memory, - False otherwise + False otherwise (refer Section 4.8 of SYCL 2020 specs). + + Returns: + bool: Indicates that the device can access USM memory + allocated using ``sycl::malloc_host``. """ cdef _aspect_type AT = _aspect_type._usm_host_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -495,14 +567,25 @@ cdef class SyclDevice(_SyclDevice): @property def has_aspect_usm_shared_allocations(self): """ Returns True if this device supports USM-shared memory - allocated on the same device, False otherwise + allocated on the same device, False otherwise. + + Returns: + bool: Indicates that the device supports USM memory + allocated using ``sycl::malloc_shared``. """ cdef _aspect_type AT = _aspect_type._usm_shared_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @property def has_aspect_usm_restricted_shared_allocations(self): - """ Deprecated property, do not use. + """ Returns True if this device supports USM memory + allocated as restricted USM, False otherwise. + + Returns: + bool: Indicates that the device supports USM memory allocated using + ``sycl::malloc_shared`` as restricted USM. + + .. deprecated:: 0.14 """ cdef _aspect_type AT = _aspect_type._usm_restricted_shared_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -511,7 +594,11 @@ cdef class SyclDevice(_SyclDevice): def has_aspect_usm_system_allocations(self): """ Returns True if system allocator may be used instead of SYCL USM allocation mechanism for USM-shared allocations on this device, - False otherwise + False otherwise. + + Returns: + bool: Indicates that system allocator may be used instead of + ``sycl::malloc_shared``. """ cdef _aspect_type AT = _aspect_type._usm_system_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -520,7 +607,10 @@ cdef class SyclDevice(_SyclDevice): def has_aspect_usm_atomic_host_allocations(self): """ Returns True if this device supports USM-host allocations and the host and this device may concurrently access and atomically - modify host allocations, False otherwise + modify host allocations, False otherwise. + + Returns: + bool: Indicates if the device supports USM atomic host allocations. """ cdef _aspect_type AT = _aspect_type._usm_atomic_host_allocations return DPCTLDevice_HasAspect(self._device_ref, AT) @@ -650,6 +740,9 @@ cdef class SyclDevice(_SyclDevice): def max_work_item_dims(self): """ Returns the maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model. + + Returns: + int: The maximum number of work items supported by the device. """ cdef uint32_t max_work_item_dims = 0 max_work_item_dims = DPCTLDevice_GetMaxWorkItemDims(self._device_ref) @@ -659,8 +752,12 @@ cdef class SyclDevice(_SyclDevice): def max_work_item_sizes1d(self): """ Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<1>. The minimum value is - `(1 )` for devices that are not of device type - ``info::device_type::custom``. + `(1 )` for devices that evaluate to False for + :py:attr:`~has_aspect_custom`. + + Returns: + tuple[int,]: A tuple with the maximum allowed value for a 1D range + used to enqueue a kernel on the device. """ cdef size_t *max_work_item_sizes1d = NULL max_work_item_sizes1d = DPCTLDevice_GetMaxWorkItemSizes1d( @@ -674,8 +771,12 @@ cdef class SyclDevice(_SyclDevice): def max_work_item_sizes2d(self): """ Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<2>. The minimum value is - `(1; 1)` for devices that are not of device type - ``info::device_type::custom``. + `(1; 1)` for devices that evaluate to False for + :py:attr:`~has_aspect_custom`. + + Returns: + tuple[int, int]: A tuple with the maximum allowed value for each + dimension of a 2D range used to enqueue a kernel on the device. """ cdef size_t *max_work_item_sizes2d = NULL max_work_item_sizes2d = DPCTLDevice_GetMaxWorkItemSizes2d( @@ -689,8 +790,12 @@ cdef class SyclDevice(_SyclDevice): def max_work_item_sizes3d(self): """ Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<3>. The minimum value is - `(1; 1; 1)` for devices that are not of device type - ``info::device_type::custom``. + `(1; 1; 1)` for devices that evaluate to False for + :py:attr:`~has_aspect_custom`. + + Returns: + tuple[int, int, int]: A tuple with the maximum allowed value for + each dimension of a 3D range used to enqueue a kernel on the device. """ return ( self._max_work_item_sizes[0], @@ -702,8 +807,16 @@ cdef class SyclDevice(_SyclDevice): def max_work_item_sizes(self): """ Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range. The minimum value is - `(1; 1; 1)` for devices that are not of device type - ``info::device_type::custom``. + `(1; 1; 1)` for devices that evaluate to False for + :py:attr:`~has_aspect_custom`. + + Returns: + tuple[int, int, int]: A tuple whose length depends on the number of + workgrpup dimensions supported by the device. + + .. deprecated:: 0.14 + The property is deprecated use :py:attr:`~max_work_item_sizes3d` + instead. """ warnings.warn( "dpctl.SyclDevice.max_work_item_sizes is deprecated, " @@ -720,6 +833,9 @@ cdef class SyclDevice(_SyclDevice): def max_compute_units(self): """ Returns the number of parallel compute units available to the device. The minimum value is 1. + + Returns: + int: The number of compute units in the device. """ cdef uint32_t max_compute_units = 0 max_compute_units = DPCTLDevice_GetMaxComputeUnits(self._device_ref) @@ -727,10 +843,12 @@ cdef class SyclDevice(_SyclDevice): @property def max_work_group_size(self): - """ Returns the maximum number of work-items - that are permitted in a work-group executing a - kernel on a single compute unit. The minimum + """ Returns the maximum number of work-items that are permitted in a + work-group executing a kernel on a single compute unit. The minimum value is 1. + + Returns: + int: The maximum supported work group size. """ cdef uint32_t max_work_group_size = 0 max_work_group_size = DPCTLDevice_GetMaxWorkGroupSize(self._device_ref) @@ -755,8 +873,12 @@ cdef class SyclDevice(_SyclDevice): @property def sub_group_independent_forward_progress(self): - """ Returns true if the device supports independent forward progress of + """ Returns True if the device supports independent forward progress of sub-groups with respect to other sub-groups in the same work-group. + + Returns: + bool: Indicates if the device supports independent forward progress + of sub-groups. """ return DPCTLDevice_GetSubGroupIndependentForwardProgress( self._device_ref @@ -872,7 +994,11 @@ cdef class SyclDevice(_SyclDevice): @property def __name__(self): - "Name of the class `dpctl.SyclDevice`" + """ Returns the name of the class :class:`dpctl.SyclDevice` + + Returns: + str: Name of the class as a string. + """ return "SyclDevice" def __repr__(self): @@ -890,9 +1016,8 @@ cdef class SyclDevice(_SyclDevice): ) def __hash__(self): - """ - Returns a hash value by hashing the underlying ``sycl::device`` object. - + """Returns a hash value by hashing the underlying ``sycl::device`` + object. """ return DPCTLDevice_Hash(self._device_ref) @@ -1109,8 +1234,7 @@ cdef class SyclDevice(_SyclDevice): Returns: global_mem_cache_type: type of cache memory Raises: - A RuntimeError is raised if an unrecognized memory type - is reported by runtime. + RuntimeError: If an unrecognized memory type is reported by runtime. """ cdef _global_mem_cache_type gmcTy = ( DPCTLDevice_GetGlobalMemCacheType(self._device_ref)