Skip to content

Commit 71e48e0

Browse files
authored
[SYCL][Doc] Add test plan for sycl_ext_oneapi_device_image_backend_content extension (#16698)
This PR adds the test plan for [sycl_ext_oneapi_device_image_backend_content](https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_image_backend_content.asciidoc) extension.
1 parent 9956780 commit 71e48e0

File tree

1 file changed

+106
-0
lines changed

1 file changed

+106
-0
lines changed
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Test plan for [`sycl_ext_oneapi_device_image_backend_content`][spec-link]
2+
# extension
3+
4+
## Testing scope
5+
6+
### Device coverage
7+
8+
The unit tests should be launched on every supported device configuration we
9+
have.
10+
11+
The end-to-end tests, which consist of checking the interoperability with
12+
Level Zero, OpenCL and CUDA backends, should be run on devices that are
13+
exposed through these low-level interfaces.
14+
15+
### Type coverage
16+
17+
All of the APIs introduced by this extension are not templated and do not have
18+
any arguments.
19+
20+
There are, however, some requirements related to the value of the
21+
`State` template parameter of the `device_image` class on which these
22+
APIs are defined. In particular, the `ext_oneapi_get_backend_content`
23+
and `ext_oneapi_get_backend_content_view` functions are only
24+
available when `State == sycl::bundle_state::executable`.
25+
Tests should verify that these functions are indeed only
26+
available when this equality occurs.
27+
28+
## Tests
29+
30+
### Unit tests
31+
32+
#### Interface tests
33+
34+
These tests are intended to check that all classes and methods defined by the
35+
extension have correct implementation, i.e.: right signatures, right return
36+
types, all necessary constraints are checked/enforced, etc.
37+
38+
These tests should check the following:
39+
40+
- that diagnostic is emitted when `ext_oneapi_get_backend_content` or
41+
`ext_oneapi_get_backend_content_view` functions are called and
42+
`State != sycl::bundle_state::executable`
43+
- the return types of all functions match the spec
44+
45+
Tests in this category may not perform some useful actions to exercise the
46+
extension functionality in full, but instead they are focused on making sure
47+
that all APIs are consistent with respect to other APIs.
48+
49+
#### Consistency of backend API
50+
51+
The test needs to check that `ext_oneapi_get_backend` returns the
52+
same value as `sycl::kernel_bundle::get_backend` on the kernel bundle
53+
that contains the image.
54+
55+
#### Consistency of image contents and a view of the image contents
56+
57+
The test needs to check that the values returned by
58+
`ext_oneapi_get_backend_content` and `ext_oneapi_get_backend_content_view`
59+
have the same contents.
60+
61+
### End-to-end tests
62+
63+
Tests in this category perform some meaningful actions with the extension to
64+
see that the extension works in scenarios which mimic real-life usage of the
65+
extension.
66+
67+
#### Level Zero and OpenCL interoperability
68+
69+
In general, it is not possible to interpret the device image contents returned
70+
by this API in such a way that allows us to retrieve specific kernels inside
71+
the device image. However, under the conditions that the device be managed by
72+
an Level Zero or OpenCL backend and the kernel is defined using the
73+
requirements [here][ref-link], it is possible to retrieve the kernel from the
74+
device image contents.
75+
76+
This test selects a Level Zero or OpenCL backend device and defines a simple
77+
kernel using free function syntax adhering to the requirements mentioned in
78+
the paragraph above. Then, using the device image contents and backend
79+
specific API, it should create a Level Zero or OpenCL kernel object
80+
corresponding to the kernel. Using interoperability API such as
81+
`sycl::make_kernel`, this kernel object can be made into a high-level SYCL
82+
kernel object. The test, therefore, has two versions of the same SYCL
83+
kernel, one of which is constructed directly from the source code kernel
84+
using only SYCL API and the other constructed using the
85+
`sycl_ext_oneapi_device_image_backend_content` API, backend specific API and
86+
the SYCL interoperability API. The test should run both kernels and verify
87+
that they have the same effect, for example, by having the kernel write a
88+
specific value to a memory location passed as a kernel argument and
89+
checking that after both kernels have run, both memory locations have the
90+
same value.
91+
92+
The test requires either Level Zero or OpenCL backend and development kits
93+
to be available in the testing environment.
94+
95+
### CUDA interoperability
96+
97+
Unlike above, for CUDA, there is not a portable way to retrieve a SYCL
98+
kernel from a CUBIN module. This test, therefore, will simply get the
99+
contents of the CUBIN module and use `cuModuleLoadData` to create a module
100+
object out of the image contents and verify that `CUDA_SUCCESS` is returned.
101+
102+
The test requires CUDA backend and development kit to be available in the
103+
testing environment.
104+
105+
[ref-link]: ../proposed/sycl_ext_oneapi_free_function_kernels.asciidoc#level-zero-and-opencl-compatibility
106+
[spec-link]: https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_image_backend_content.asciidoc

0 commit comments

Comments
 (0)