|
| 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