Merge pull request #236 from IntelPython/master

PokhodenkoSA · web-flow · commit e6765c997edf · 2020-12-22T14:46:34.000+03:00
0.5.1rc1
diff --git a/docs/dpCtl.dptensor_api.rst b/docs/dpCtl.dptensor_api.rst
@@ -6,3 +6,4 @@ dpCtl dptensor Python API
 
 .. automodule:: dpctl.dptensor
     :members:
+    :undoc-members:
diff --git a/docs/dpCtl.memory_api.rst b/docs/dpCtl.memory_api.rst
@@ -5,11 +5,27 @@ dpCtl Memory Python API
 #######################
 
 .. automodule:: dpctl.memory
+
+Classes
+-------
+
+.. autoclass:: dpctl.memory.MemoryUSMDevice
     :members:
+    :inherited-members:
+    :undoc-members:
 
-....
+.. autoclass:: dpctl.memory.MemoryUSMHost
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: dpctl.memory.MemoryUSMShared
+    :members:
+    :inherited-members:
+    :undoc-members:
 
-**Comparing dpctl.memory to Rapids Memory Manager (RMM)**
+Comparison with Rapids Memory Manager (RMM)
+-------------------------------------------
 
 RMM implements DeviceBuffer which is Cython native class wrapping around something similar to ``std::vector<unsigned char, custom_cuda_allocator (calls resource manager)>`` which is called device_buffer.
 
diff --git a/docs/dpCtl.program_api.rst b/docs/dpCtl.program_api.rst
@@ -5,4 +5,25 @@ dpCtl Program Python API
 ########################
 
 .. automodule:: dpctl.program
+
+Classes
+-------
+
+.. autoclass:: dpctl.program.SyclKernel
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.program.SyclProgram
     :members:
+    :undoc-members:
+
+Exceptions
+----------
+
+.. autoexception::  dpctl.program.SyclProgramCompilationError
+
+Functions
+---------
+
+.. autofunction:: create_program_from_source
+.. autofunction:: create_program_from_spirv
diff --git a/docs/dpCtl_api.rst b/docs/dpCtl_api.rst
@@ -5,4 +5,58 @@ dpCtl Python API
 ################
 
 .. automodule:: dpctl
-   :members:
+
+Classes
+-------
+
+.. autoclass:: dpctl.SyclContext
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclDevice
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclEvent
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclQueue
+    :members:
+    :undoc-members:
+
+Enumerations
+------------
+
+.. autoclass:: dpctl.backend_type
+    :members:
+
+.. autoclass:: dpctl.device_type
+    :members:
+
+Exceptions
+----------
+
+.. autoexception:: dpctl.SyclKernelInvalidRangeError
+.. autoexception:: dpctl.SyclKernelSubmitError
+.. autoexception:: dpctl.SyclQueueCreationError
+.. autoexception:: dpctl.UnsupportedBackendError
+.. autoexception:: dpctl.UnsupportedDeviceError
+
+Functions
+---------
+
+.. autofunction:: device_context
+.. autofunction:: dump
+.. autofunction:: get_current_backend
+.. autofunction:: get_current_device_type
+.. autofunction:: get_current_queue
+.. autofunction:: get_include
+.. autofunction:: get_num_activated_queues
+.. autofunction:: get_num_platforms
+.. autofunction:: get_num_queues
+.. autofunction:: has_cpu_queues
+.. autofunction:: has_gpu_queues
+.. autofunction:: has_sycl_platforms
+.. autofunction:: is_in_device_context
+.. autofunction:: set_default_queue
diff --git a/docs/index.rst b/docs/index.rst
@@ -22,6 +22,5 @@ Indices and tables
     :maxdepth: 3
     :caption: Contents:
 
-    self
     toc_pyapi
     api/dpCtl-CAPI_root
diff --git a/docs/toc_pyapi.rst b/docs/toc_pyapi.rst
@@ -5,6 +5,6 @@ Python API
     :maxdepth: 1
 
     dpctl - SYCL runtime wrapper classes and queue manager <dpCtl_api>
-    dpctl.memory - USM memory manager <dpCtl.memory_api>
     dpctl.dptensor - Data-parallel tensor containers <dpCtl.dptensor_api>
+    dpctl.memory - USM memory manager <dpCtl.memory_api>
     dpctl.program - Program manager <dpCtl.program_api>
diff --git a/dpctl-capi/source/dpctl_sycl_queue_manager.cpp b/dpctl-capi/source/dpctl_sycl_queue_manager.cpp
@@ -236,7 +236,8 @@ QMgrHelper::getQueue (DPCTLSyclBackendType BETy,
         QRef = new queue(gpuQs[DNum]);
         break;
     }
-    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO | DPCTLSyclDeviceType::DPCTL_GPU:
+    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO |
+         DPCTLSyclDeviceType::DPCTL_GPU:
     {
         auto l0GpuQs = get_level0_gpu_queues();
         if (DNum >= l0GpuQs.size()) {
@@ -316,7 +317,8 @@ QMgrHelper::setAsDefaultQueue (DPCTLSyclBackendType BETy,
         activeQ[0] = oclgpu_q[DNum];
         break;
     }
-    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO | DPCTLSyclDeviceType::DPCTL_GPU:
+    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO |
+         DPCTLSyclDeviceType::DPCTL_GPU:
     {
         auto l0gpu_q = get_level0_gpu_queues();
         if (DNum >= l0gpu_q.size()) {
@@ -342,8 +344,8 @@ QMgrHelper::setAsDefaultQueue (DPCTLSyclBackendType BETy,
 /*!
  * Allocates a new sycl::queue by copying from the cached {cpu|gpu}_queues
  * vector. The pointer returned is now owned by the caller and must be properly
- * cleaned up. The helper function DPCTLDeleteSyclQueue() can be used is for that
- * purpose.
+ * cleaned up. The helper function DPCTLDeleteSyclQueue() can be used is for
+ * that purpose.
  */
 __dpctl_give DPCTLSyclQueueRef
 QMgrHelper::pushSyclQueue (DPCTLSyclBackendType BETy,
@@ -383,7 +385,8 @@ QMgrHelper::pushSyclQueue (DPCTLSyclBackendType BETy,
         QRef = new queue(activeQ[get_active_queues().size()-1]);
         break;
     }
-    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO | DPCTLSyclDeviceType::DPCTL_GPU:
+    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO |
+         DPCTLSyclDeviceType::DPCTL_GPU:
     {
         if (DNum >= get_level0_gpu_queues().size()) {
             // \todo handle error
@@ -447,7 +450,7 @@ size_t DPCTLQueueMgr_GetNumActivatedQueues ()
  * type combination.
  */
 size_t DPCTLQueueMgr_GetNumQueues (DPCTLSyclBackendType BETy,
-                                  DPCTLSyclDeviceType DeviceTy)
+                                   DPCTLSyclDeviceType DeviceTy)
 {
     switch (BETy|DeviceTy)
     {
@@ -459,7 +462,8 @@ size_t DPCTLQueueMgr_GetNumQueues (DPCTLSyclBackendType BETy,
     {
         return QMgrHelper::get_opencl_gpu_queues().size();
     }
-    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO | DPCTLSyclDeviceType::DPCTL_GPU:
+    case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO |
+         DPCTLSyclDeviceType::DPCTL_GPU:
     {
         return QMgrHelper::get_level0_gpu_queues().size();
     }
@@ -485,8 +489,8 @@ DPCTLSyclQueueRef DPCTLQueueMgr_GetCurrentQueue ()
  * and device number. A runtime_error gets thrown if no such device exists.
  */
 DPCTLSyclQueueRef DPCTLQueueMgr_GetQueue (DPCTLSyclBackendType BETy,
-                                        DPCTLSyclDeviceType DeviceTy,
-                                        size_t DNum)
+                                          DPCTLSyclDeviceType DeviceTy,
+                                          size_t DNum)
 {
     return QMgrHelper::getQueue(BETy, DeviceTy, DNum);
 }
@@ -506,8 +510,8 @@ bool DPCTLQueueMgr_IsCurrentQueue (__dpctl_keep const DPCTLSyclQueueRef QRef)
  */
 __dpctl_give DPCTLSyclQueueRef
 DPCTLQueueMgr_SetAsDefaultQueue (DPCTLSyclBackendType BETy,
-                                DPCTLSyclDeviceType DeviceTy,
-                                size_t DNum)
+                                 DPCTLSyclDeviceType DeviceTy,
+                                 size_t DNum)
 {
     return QMgrHelper::setAsDefaultQueue(BETy, DeviceTy, DNum);
 }
@@ -517,8 +521,8 @@ DPCTLQueueMgr_SetAsDefaultQueue (DPCTLSyclBackendType BETy,
  */
 __dpctl_give DPCTLSyclQueueRef
 DPCTLQueueMgr_PushQueue (DPCTLSyclBackendType BETy,
-                        DPCTLSyclDeviceType DeviceTy,
-                        size_t DNum)
+                         DPCTLSyclDeviceType DeviceTy,
+                         size_t DNum)
 {
     return QMgrHelper::pushSyclQueue(BETy, DeviceTy, DNum);
 }
@@ -536,8 +540,10 @@ void DPCTLQueueMgr_PopQueue ()
  * SYCL device.
  */
 DPCTLSyclQueueRef
-DPCTLQueueMgr_GetQueueFromContextAndDevice (__dpctl_keep DPCTLSyclContextRef CRef,
-                                           __dpctl_keep DPCTLSyclDeviceRef DRef)
+DPCTLQueueMgr_GetQueueFromContextAndDevice (
+    __dpctl_keep DPCTLSyclContextRef CRef,
+    __dpctl_keep DPCTLSyclDeviceRef DRef
+)
 {
     auto dev = unwrap(DRef);
     auto ctx = unwrap(CRef);
diff --git a/dpctl/__init__.py b/dpctl/__init__.py
@@ -30,10 +30,8 @@
 
     * A SYCL queue manager exposed directly inside the top-level `dpctl`
       module.
-    * A USM memory manager (`dpctl.memory`) that provides Python objects
-      implementing the Python buffer protocol using USM shared and USM host
-      allocators. The memory manager also exposes various utility functions
-      to wrap SYCL's USM allocators, deallocators, `memcpy` functions, *etc.*
+    * Python wrapper classes for the main SYCL runtime classes mentioned in
+      Section 4.6 of SYCL provisional 2020 spec (https://bit.ly/3asQx07).
 """
 __author__ = "Intel Corp."
 
diff --git a/dpctl/_sycl_core.pyx b/dpctl/_sycl_core.pyx
diff --git a/dpctl/program/_program.pyx b/dpctl/program/_program.pyx
diff --git a/setup.py b/setup.py

Original file line number	Diff line number	Diff line change
`@@ -6,3 +6,4 @@ dpCtl dptensor Python API`
`6`	`6`
`7`	`7`	`.. automodule:: dpctl.dptensor`
`8`	`8`	`:members:`
	`9`	`+ :undoc-members:`
Original file line number	Diff line number	Diff line change
`@@ -236,7 +236,8 @@ QMgrHelper::getQueue (DPCTLSyclBackendType BETy,`
`236`	`236`	`QRef = new queue(gpuQs[DNum]);`
`237`	`237`	`break;`
`238`	`238`	`}`
`239`		`- case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \| DPCTLSyclDeviceType::DPCTL_GPU:`
	`239`	`+ case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \|`
	`240`	`+ DPCTLSyclDeviceType::DPCTL_GPU:`
`240`	`241`	`{`
`241`	`242`	`auto l0GpuQs = get_level0_gpu_queues();`
`242`	`243`	`if (DNum >= l0GpuQs.size()) {`
`@@ -316,7 +317,8 @@ QMgrHelper::setAsDefaultQueue (DPCTLSyclBackendType BETy,`
`316`	`317`	`activeQ[0] = oclgpu_q[DNum];`
`317`	`318`	`break;`
`318`	`319`	`}`
`319`		`- case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \| DPCTLSyclDeviceType::DPCTL_GPU:`
	`320`	`+ case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \|`
	`321`	`+ DPCTLSyclDeviceType::DPCTL_GPU:`
`320`	`322`	`{`
`321`	`323`	`auto l0gpu_q = get_level0_gpu_queues();`
`322`	`324`	`if (DNum >= l0gpu_q.size()) {`
`@@ -342,8 +344,8 @@ QMgrHelper::setAsDefaultQueue (DPCTLSyclBackendType BETy,`
`342`	`344`	`/*!`
`343`	`345`	`* Allocates a new sycl::queue by copying from the cached {cpu\|gpu}_queues`
`344`	`346`	`* vector. The pointer returned is now owned by the caller and must be properly`
`345`		`- * cleaned up. The helper function DPCTLDeleteSyclQueue() can be used is for that`
`346`		`- * purpose.`
	`347`	`+ * cleaned up. The helper function DPCTLDeleteSyclQueue() can be used is for`
	`348`	`+ * that purpose.`
`347`	`349`	`*/`
`348`	`350`	`__dpctl_give DPCTLSyclQueueRef`
`349`	`351`	`QMgrHelper::pushSyclQueue (DPCTLSyclBackendType BETy,`
`@@ -383,7 +385,8 @@ QMgrHelper::pushSyclQueue (DPCTLSyclBackendType BETy,`
`383`	`385`	`QRef = new queue(activeQ[get_active_queues().size()-1]);`
`384`	`386`	`break;`
`385`	`387`	`}`
`386`		`- case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \| DPCTLSyclDeviceType::DPCTL_GPU:`
	`388`	`+ case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \|`
	`389`	`+ DPCTLSyclDeviceType::DPCTL_GPU:`
`387`	`390`	`{`
`388`	`391`	`if (DNum >= get_level0_gpu_queues().size()) {`
`389`	`392`	`// \todo handle error`
`@@ -447,7 +450,7 @@ size_t DPCTLQueueMgr_GetNumActivatedQueues ()`
`447`	`450`	`* type combination.`
`448`	`451`	`*/`
`449`	`452`	`size_t DPCTLQueueMgr_GetNumQueues (DPCTLSyclBackendType BETy,`
`450`		`- DPCTLSyclDeviceType DeviceTy)`
	`453`	`+ DPCTLSyclDeviceType DeviceTy)`
`451`	`454`	`{`
`452`	`455`	`switch (BETy\|DeviceTy)`
`453`	`456`	`{`
`@@ -459,7 +462,8 @@ size_t DPCTLQueueMgr_GetNumQueues (DPCTLSyclBackendType BETy,`
`459`	`462`	`{`
`460`	`463`	`return QMgrHelper::get_opencl_gpu_queues().size();`
`461`	`464`	`}`
`462`		`- case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \| DPCTLSyclDeviceType::DPCTL_GPU:`
	`465`	`+ case DPCTLSyclBackendType::DPCTL_LEVEL_ZERO \|`
	`466`	`+ DPCTLSyclDeviceType::DPCTL_GPU:`
`463`	`467`	`{`
`464`	`468`	`return QMgrHelper::get_level0_gpu_queues().size();`
`465`	`469`	`}`
`@@ -485,8 +489,8 @@ DPCTLSyclQueueRef DPCTLQueueMgr_GetCurrentQueue ()`
`485`	`489`	`* and device number. A runtime_error gets thrown if no such device exists.`
`486`	`490`	`*/`
`487`	`491`	`DPCTLSyclQueueRef DPCTLQueueMgr_GetQueue (DPCTLSyclBackendType BETy,`
`488`		`- DPCTLSyclDeviceType DeviceTy,`
`489`		`- size_t DNum)`
	`492`	`+ DPCTLSyclDeviceType DeviceTy,`
	`493`	`+ size_t DNum)`
`490`	`494`	`{`
`491`	`495`	`return QMgrHelper::getQueue(BETy, DeviceTy, DNum);`
`492`	`496`	`}`
`@@ -506,8 +510,8 @@ bool DPCTLQueueMgr_IsCurrentQueue (__dpctl_keep const DPCTLSyclQueueRef QRef)`
`506`	`510`	`*/`
`507`	`511`	`__dpctl_give DPCTLSyclQueueRef`
`508`	`512`	`DPCTLQueueMgr_SetAsDefaultQueue (DPCTLSyclBackendType BETy,`
`509`		`- DPCTLSyclDeviceType DeviceTy,`
`510`		`- size_t DNum)`
	`513`	`+ DPCTLSyclDeviceType DeviceTy,`
	`514`	`+ size_t DNum)`
`511`	`515`	`{`
`512`	`516`	`return QMgrHelper::setAsDefaultQueue(BETy, DeviceTy, DNum);`
`513`	`517`	`}`
`@@ -517,8 +521,8 @@ DPCTLQueueMgr_SetAsDefaultQueue (DPCTLSyclBackendType BETy,`
`517`	`521`	`*/`
`518`	`522`	`__dpctl_give DPCTLSyclQueueRef`
`519`	`523`	`DPCTLQueueMgr_PushQueue (DPCTLSyclBackendType BETy,`
`520`		`- DPCTLSyclDeviceType DeviceTy,`
`521`		`- size_t DNum)`
	`524`	`+ DPCTLSyclDeviceType DeviceTy,`
	`525`	`+ size_t DNum)`
`522`	`526`	`{`
`523`	`527`	`return QMgrHelper::pushSyclQueue(BETy, DeviceTy, DNum);`
`524`	`528`	`}`
`@@ -536,8 +540,10 @@ void DPCTLQueueMgr_PopQueue ()`
`536`	`540`	`* SYCL device.`
`537`	`541`	`*/`
`538`	`542`	`DPCTLSyclQueueRef`
`539`		`-DPCTLQueueMgr_GetQueueFromContextAndDevice (__dpctl_keep DPCTLSyclContextRef CRef,`
`540`		`- __dpctl_keep DPCTLSyclDeviceRef DRef)`
	`543`	`+DPCTLQueueMgr_GetQueueFromContextAndDevice (`
	`544`	`+ __dpctl_keep DPCTLSyclContextRef CRef,`
	`545`	`+ __dpctl_keep DPCTLSyclDeviceRef DRef`
	`546`	`+)`
`541`	`547`	`{`
`542`	`548`	`auto dev = unwrap(DRef);`
`543`	`549`	`auto ctx = unwrap(CRef);`