diff --git a/dpctl/__init__.py b/dpctl/__init__.py index 3412040d2d..0287c9783b 100644 --- a/dpctl/__init__.py +++ b/dpctl/__init__.py @@ -1,43 +1,43 @@ +##===----------------- _memory.pyx - dpctl module -------*- Cython -*------===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +## +## \file +## This top-level dpctl module. +## +##===----------------------------------------------------------------------===## ''' - Python Data Parallel Processing Library (PyDPPL) + Data Parallel Control (dpCtl) - PyDPPL provides a lightweight Python abstraction over DPC++/SYCL and + dpCtl provides a lightweight Python abstraction over DPC++/SYCL and OpenCL runtime objects. The DPC++ runtime wrapper objects can be accessed by importing dpctl. The OpenCL runtime wrapper objects can be accessed by importing dpctl.ocldrv. The library is in an early-beta stage of development and not yet ready for production usage. - PyDPPL's intended usage is as a common SYCL interoperability layer for + dpCtl's intended usage is as a common SYCL interoperability layer for different Python libraries and applications. The OpenCL support inside PyDPPL is slated to be deprecated and then removed in future releases of the library. Currently, only a small subset of DPC++ runtime objects are exposed - through the dpctl module. The main API classes inside the dpctl module are: - - Runtime: The class stores a global SYCL queue and a stack of - currently activated queues. Runtime provides a special getter - method to retrieve the currently activated SYCL queue - as a Py_capsule. - - A single global thread local instance of the Runtime class - is created on loading the dpctl module for the first time. - - DeviceArray: A DeviceArray object encapsulates a one-dimensional - cl::sycl::buffer object. A DeviceArray object can be - created using a NumPy ndarray. The initial implementation - of DeviceArray follows NumPy's recommended design to create - a custom array container. DeviceArray does not implement - the __array_function__ and the __array_ufunc__ interfaces. - Therefore, DeviceArray does not support NumPy Universal - functions (ufuncs). The design decision to not support - ufuncs can be revisited later if we have a need for such - functionality. For the time being, the class is only meant - as a data exchange format between Python libraries that - use SYCL. - - Global data members: - runtime - An instance of the Runtime class. + through the dpctl module. The main API classes are defined in the _sycl_core.pyx file. Please use `pydoc dpctl._sycl_core` to look at the current API for dpctl. diff --git a/dpctl/_memory.pyx b/dpctl/_memory.pyx index c790ea17ce..3edd8732bc 100644 --- a/dpctl/_memory.pyx +++ b/dpctl/_memory.pyx @@ -1,3 +1,33 @@ +##===--------------- _memory.pyx - dpctl module --------*- Cython -*-------===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +## +## \file +## This file implements Python buffer protocol using Sycl USM shared and host +## allocators. The USM device allocator is also exposed through this module for +## use in other Python modules. +## +##===----------------------------------------------------------------------===## + +# distutils: language = c++ +# cython: language_level=3 + import dpctl from dpctl.backend cimport * from ._sycl_core cimport SyclContext, SyclQueue diff --git a/dpctl/_sycl_core.pxd b/dpctl/_sycl_core.pxd index cb0c238318..caa18814d8 100644 --- a/dpctl/_sycl_core.pxd +++ b/dpctl/_sycl_core.pxd @@ -1,6 +1,6 @@ -##===------------- sycl_core.pxd - DPPL interface ------*- Cython -*-------===## +##===------------- sycl_core.pxd - dpctl module --------*- Cython -*-------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,9 +19,11 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file defines the Cython interface for the Sycl API of PyDPPL. +## This file declares the extension types and functions for the Cython API +## implemented in sycl_core.pyx. ## ##===----------------------------------------------------------------------===## + # distutils: language = c++ # cython: language_level=3 diff --git a/dpctl/backend.pxd b/dpctl/backend.pxd index 3584cf2e28..f15f51b529 100644 --- a/dpctl/backend.pxd +++ b/dpctl/backend.pxd @@ -1,6 +1,6 @@ -##===------------- backend.pyx - DPPL interface ------*- Cython -*-------===## +##===------------- backend.pyx - dpctl module -------*- Cython -*----------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,9 +19,11 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file defines the Cython interface for the backend API of PyDPPL. +## This file defines the Cython extern types for the functions and opaque data +## types defined by dpctl's C API. ## ##===----------------------------------------------------------------------===## + # distutils: language = c++ # cython: language_level=3 diff --git a/dpctl/ocldrv.py b/dpctl/ocldrv.py index 904a933568..82461069df 100644 --- a/dpctl/ocldrv.py +++ b/dpctl/ocldrv.py @@ -1,6 +1,6 @@ -##===---------- ocldrv.py - dpctl.ocldrv interface -----*- Python -*-----===## +##===------------- ocldrv.py - dpctl.ocldrv module ------*- Python -*------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -20,7 +20,7 @@ ### ### \file ### This file exposes Python classes for different OpenCL classes that are -### exposed by the _dppl_binding CFFI extension module. +### exposed by the _opencl_core CFFI extension module. ##===----------------------------------------------------------------------===## ''' The dpctl.ocldrv module contains a set of Python wrapper classes for OpenCL objects. The module has wrappers for cl_context, cl_device, diff --git a/dpctl/opencl_core.py b/dpctl/opencl_core.py index 327de08122..cef6b9bcc5 100644 --- a/dpctl/opencl_core.py +++ b/dpctl/opencl_core.py @@ -1,6 +1,6 @@ -##===--------- opencl_core.py - dpctl.ocldrv interface -----*- Python -*----===## +##===--------- opencl_core.py - dpctl.ocldrv interface -----*- Python -*---===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data paraller Control (dpctl) ## ## Copyright 2020 Intel Corporation ## diff --git a/dpctl/sycl_core.pyx b/dpctl/sycl_core.pyx index a74917bb62..15f51c4928 100644 --- a/dpctl/sycl_core.pyx +++ b/dpctl/sycl_core.pyx @@ -1,6 +1,6 @@ -##===------------- sycl_core.pyx - DPPL interface ------*- Cython -*-------===## +##===------------- sycl_core.pyx - dpctl module -------*- Cython -*--------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,7 +19,7 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file implements the Cython interface for the Sycl API of PyDPPL. +## This file implements a sub-set of Sycl's interface using dpctl's CAPI. ## ##===----------------------------------------------------------------------===## @@ -199,7 +199,7 @@ cdef class _SyclQueueManager: ''' DPPLPlatform_DumpInfo() - def is_in_dppl_ctxt (self): + def is_in_device_context (self): cdef size_t num = DPPLQueueMgr_GetNumActivatedQueues() if num: return True @@ -219,7 +219,7 @@ has_cpu_queues = _qmgr.has_cpu_queues has_gpu_queues = _qmgr.has_gpu_queues has_sycl_platforms = _qmgr.has_sycl_platforms set_default_queue = _qmgr.set_default_queue -is_in_dppl_ctxt = _qmgr.is_in_dppl_ctxt +is_in_device_context = _qmgr.is_in_device_context from contextlib import contextmanager diff --git a/dpctl/tests/__init__.py b/dpctl/tests/__init__.py index 6bd91b208f..ce80b2561c 100644 --- a/dpctl/tests/__init__.py +++ b/dpctl/tests/__init__.py @@ -1,2 +1,27 @@ +##===-------- tests/dpctl_tests/__init__.py - dpctl ------*- Python -*----===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +## +## \file +## Top-level module of all dpctl Python unit test cases. +##===----------------------------------------------------------------------===## + +from .test_sycl_queue_manager import * +from .test_sycl_usm import * from .test_dump_functions import * -from .dppl_tests import * diff --git a/dpctl/tests/dppl_tests/__init__.py b/dpctl/tests/dppl_tests/__init__.py deleted file mode 100644 index dd992a0db9..0000000000 --- a/dpctl/tests/dppl_tests/__init__.py +++ /dev/null @@ -1,2 +0,0 @@ -from .test_sycl_queue_manager import * -from .test_sycl_usm import * diff --git a/dpctl/tests/test_dump_functions.py b/dpctl/tests/test_dump_functions.py index a925a22ba6..52b41edace 100644 --- a/dpctl/tests/test_dump_functions.py +++ b/dpctl/tests/test_dump_functions.py @@ -1,18 +1,26 @@ -#******************************************************************************* -# Copyright 2020 Intel Corporation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#******************************************************************************/ +##===---------- test_sycl_queue_manager.py - dpctl -------*- Python -*----===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +### +### \file +### A basic unit test to verify that dpctl and dpct.ocldrv exist. +##===----------------------------------------------------------------------===## import unittest @@ -22,19 +30,24 @@ class TestDumpMethods(unittest.TestCase): - def test_dppl_dump (self): + def test_dpctl_dump (self): try: dpctl.dump() except Exception: self.fail("Encountered an exception inside dump().") - def test_dppl_dump_device_info (self): + def test_dpctl_dump_device_info (self): q = dpctl.get_current_queue() try: q.get_sycl_device().dump_device_info() except Exception: self.fail("Encountered an exception inside dump_device_info().") + def test_dpctl_ocldrv_dump (self): + try: + dpctl.ocldrv.runtime.dump() + except Exception: + self.fail("Encountered an exception inside dump_device_info().") if __name__ == '__main__': unittest.main() diff --git a/dpctl/tests/dppl_tests/test_sycl_queue_manager.py b/dpctl/tests/test_sycl_queue_manager.py similarity index 79% rename from dpctl/tests/dppl_tests/test_sycl_queue_manager.py rename to dpctl/tests/test_sycl_queue_manager.py index 5763c18fe7..f8e39042c5 100644 --- a/dpctl/tests/dppl_tests/test_sycl_queue_manager.py +++ b/dpctl/tests/test_sycl_queue_manager.py @@ -1,6 +1,6 @@ -##===---------- test_sycl_queue_manager.py - dpctl -------*- Python -*-----===## +##===---------- test_sycl_queue_manager.py - dpctl -------*- Python -*----===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,28 +19,28 @@ ##===----------------------------------------------------------------------===## ### ### \file -### This file has unit test cases to for the SyclQueueManager class -### in sycl_core.pyx. +### Defines unit test cases for the SyclQueueManager class in sycl_core.pyx. ##===----------------------------------------------------------------------===## import dpctl import unittest class TestGetNumPlatforms (unittest.TestCase): - @unittest.skipIf(not dpctl.has_sycl_platforms(), "No SYCL platforms available") - def test_dppl_get_num_platforms (self): + @unittest.skipIf(not dpctl.has_sycl_platforms(), + "No SYCL platforms available") + def test_dpctl_get_num_platforms (self): if(dpctl.has_sycl_platforms): self.assertGreaterEqual(dpctl.get_num_platforms(), 1) @unittest.skipIf(not dpctl.has_sycl_platforms(), "No SYCL platforms available") class TestDumpMethods (unittest.TestCase): - def test_dppl_dump (self): + def test_dpctl_dump (self): try: dpctl.dump() except Exception: self.fail("Encountered an exception inside dump().") - def test_dppl_dump_device_info (self): + def test_dpctl_dump_device_info (self): q = dpctl.get_current_queue() try: q.get_sycl_device().dump_device_info() @@ -48,22 +48,22 @@ def test_dppl_dump_device_info (self): self.fail("Encountered an exception inside dump_device_info().") @unittest.skipIf(not dpctl.has_sycl_platforms(), "No SYCL platforms available") -class TestDPPLIsInDPPLCtxt (unittest.TestCase): +class TestIsInDeviceContext (unittest.TestCase): - def test_is_in_dppl_ctxt_outside_device_ctxt (self): - self.assertFalse(dpctl.is_in_dppl_ctxt()) + def test_is_in_device_context_outside_device_ctxt (self): + self.assertFalse(dpctl.is_in_device_context()) - def test_is_in_dppl_ctxt_inside_device_ctxt (self): + def test_is_in_device_context_inside_device_ctxt (self): with dpctl.device_context(dpctl.device_type.gpu): - self.assertTrue(dpctl.is_in_dppl_ctxt()) + self.assertTrue(dpctl.is_in_device_context()) @unittest.skipIf(not dpctl.has_cpu_queues(), "No CPU platforms available") - def test_is_in_dppl_ctxt_inside_nested_device_ctxt (self): + def test_is_in_device_context_inside_nested_device_ctxt (self): with dpctl.device_context(dpctl.device_type.cpu): with dpctl.device_context(dpctl.device_type.gpu): - self.assertTrue(dpctl.is_in_dppl_ctxt()) - self.assertTrue(dpctl.is_in_dppl_ctxt()) - self.assertFalse(dpctl.is_in_dppl_ctxt()) + self.assertTrue(dpctl.is_in_device_context()) + self.assertTrue(dpctl.is_in_device_context()) + self.assertFalse(dpctl.is_in_device_context()) @unittest.skipIf(not dpctl.has_sycl_platforms(), "No SYCL platforms available") class TestGetCurrentQueueInMultipleThreads (unittest.TestCase): diff --git a/dpctl/tests/dppl_tests/test_sycl_usm.py b/dpctl/tests/test_sycl_usm.py similarity index 92% rename from dpctl/tests/dppl_tests/test_sycl_usm.py rename to dpctl/tests/test_sycl_usm.py index cdcc95dcc7..3737a01a4c 100644 --- a/dpctl/tests/dppl_tests/test_sycl_usm.py +++ b/dpctl/tests/test_sycl_usm.py @@ -1,6 +1,6 @@ -##===---------- test_sycl_queue_manager.py - dpctl -------*- Python -*-----===## +##===---------- test_sycl_queue_manager.py - dpctl -------*- Python -*----===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -17,6 +17,10 @@ ## limitations under the License. ## ##===----------------------------------------------------------------------===## +## +## \file +## Defines unit test cases for the Memory classes in _memory.pyx. +##===----------------------------------------------------------------------===## import unittest import dpctl @@ -111,3 +115,6 @@ class TestMemoryUSMDevice(TestMemoryUSMBase, unittest.TestCase): MemoryUSMClass = MemoryUSMDevice usm_type = 'device' + +if __name__ == '__main__': + unittest.main()