Merge pull request #865 from AlexeySachkov/private/asachkov/oneapi-co…

…mposite-device-test-plan

Add test plan for sycl_ext_oneapi_composite_device

test_plans/sycl_ext_oneapi_composite_device.asciidoc

@@ -0,0 +1,148 @@
+:sectnums:
+:xrefstyle: short
+
+= Test plan for sycl_ext_oneapi_composite_device
+
+This is a test plan for the API described in the
+https://github.com/intel/llvm/blob/e94b24718e60a7fa03ca1abbde4f7e37bbd0557d/sycl/doc/extensions/proposed/sycl_ext_oneapi_composite_device.asciidoc[`sycl_ext_oneapi_composite_device`]
+extension specification.
+
+== Testing scope
+
+=== Device coverage
+
+All of the tests described below are performed on the default device that is
+selected on the CTS command line, but some of the test cases may query for
+additional devices from the same platform the default device belongs to.
+
+=== Feature test macro
+
+All of the tests should use `#ifdef SYCL_EXT_ONEAPI_COMPOSITE_DEVICE` so they
+can be skipped if the extension is not supported.
+
+== Tests
+
+Note that some of the sections below closely follow the extension specification
+document and describe tests with narrower scope, which are aimed to check
+specific functionality. There are sections below which describe bigger test
+cases which are intended to check how different elements of the extension work
+together.
+
+=== Enumerating composite devices
+
+==== Through the new `get_composite_devices()` API
+
+This test should check that freestanding function `get_composite_devices()`:
+
+* has the correct signature
+* does not throw an exception
+* returns the same result on subsequent calls
+
+==== Through the new `platform::ext_oneapi_get_composite_devices()` API
+
+This test should take a platform the selected device belongs to and check that
+`platform::ext_oneapi_get_composite_devices()` method:
+
+* has the correct signature
+* does not throw an exception
+* returns the same result on subsequent calls
+
+==== Composite devices are not considered as root devices
+
+The test should ensure that no composite devices are returned through the
+`platform::get_devices()` method for a platform the selected device belongs to.
+
+=== New device information descriptors
+
+Composite devices are not considered as root devices and therefore they won't
+ever be selected by the CTS. To increase coverage, tests in this subcategory
+should be additionally performed on a composite device the selected device
+belongs to (if the selected device is a component device).
+
+==== `info::device::component_devices`
+
+The test should check that a query for the information descriptor has correct
+return type.
+
+The test should also check the value returned for the descriptor:
+
+* if a tested device is not a composite device, an empty vector is expected
+* otherwise, returned vector is expected to have at least two elements and those
+  elements should be additionally checked:
+** each returned device should have the `ext_oneapi_is_component` aspect
+** each returned device should return the tested device through
+   `info::device::composite_device` query
+
+==== `info::device::composite_device`
+
+The test should check that a query for the information descriptor has correct
+return type.
+
+The test should also check the value returned for the descriptor:
+
+* if a tested device is not a component device, then a synchronous
+  `exception` with `errc::invalid` error code is expected
+* otherwise, returned device should have the `ext_oneapi_is_composite` aspect
+
+=== New device aspects
+
+==== `ext_oneapi_is_composite`
+
+The test should ensure that all of devices returned by
+`get_composite_devices()` and `platform::ext_oneapi_get_composite_devices()`
+have `ext_oneapi_is_composite` aspect.
+
+==== `ext_oneapi_is_component`
+
+The test should ensure that none of devices returned by
+`get_composite_devices()` and `platform::ext_oneapi_get_composite_devices()`
+have `ext_oneapi_is_component` aspect.
+
+If the CTS selected device is a component device, then test should then attempt
+to partition a component device using one of partition methods it supports and
+check that none of sub-devices have the `ext_oneapi_is_component` aspect.
+
+=== Impact on "descendent device"
+
+The test should first obtain both a component and a composite device and it is
+skipped if that is not possible using the selected device.
+
+Having those two, the test should create a `context` using the _composite_
+device and then attempt to create a `queue` by passing the created context in
+there *and* the _component_ device. The test checks that `queue` was created
+successfully, i.e. no exceptions were thrown.
+
+=== More complex test cases
+
+Tests in this category are intended to represent miniature versions of potential
+real-world applications to check how the extension works with other core SYCL
+features.
+
+==== Basic tests for the composite device
+
+The test obtains a composite device using the selected device and it is skipped
+if unable to do so.
+
+The composite device is then used to submit a series of kernels that perform
+some computations and memory operations using a `queue` object associated with
+that device.
+
+==== "Interoperability" between composite and component devices
+
+The test should first obtain both a component and a composite device and it is
+skipped if that is not possible using the selected device.
+
+The test then creates a shared context for both devices, allocates a shared
+memory and creates separate command queues for each device. Test performs some
+computations and memory operations on that shared data using both devices.
+
+==== Sharing memory to a descendent device
+
+The test should first obtain both a component and a composite device and it is
+skipped if that is not possible using the selected device.
+
+The test allocates a memory in a context a component device belongs to. It then
+create a queue for a composite device using _the same_ context and checks that
+memory allocated for a composite device is available to a descendent component
+device as well.
+