From a9e5682592a6e8f9adae01d7a54a74bee5fb1951 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 25 Sep 2024 07:18:03 -0700 Subject: [PATCH] [SYCL][Doc] Introduce test plan for virtual mem extension --- sycl/test-e2e/VirtualMem/test-plan.md | 140 ++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 sycl/test-e2e/VirtualMem/test-plan.md diff --git a/sycl/test-e2e/VirtualMem/test-plan.md b/sycl/test-e2e/VirtualMem/test-plan.md new file mode 100644 index 0000000000000..a8b717e188e66 --- /dev/null +++ b/sycl/test-e2e/VirtualMem/test-plan.md @@ -0,0 +1,140 @@ +# Test plan for [`sycl_ext_oneapi_virtual_mem`][spec-link] extension + +## Testing scope + +### Device coverage + +Functionality provided by the extension is optional and it is only available if +corresponding aspect (`ext_oneapi_virtual_mem`) is supported by a device. + +However, we still need to check that that we return a proper exception (with +`feature_not_supported` error code) if the extension is attempted to be used on +a device which doesn't support corresponding aspect. + +Therefore, tests should be structured in a way that negative testing is +performed on all available devices, while positive tests can be skipped if +device doesn't support the extension. + +### Type coverage + +APIs for physical and virtual memory allocation are not dependent on types and +operate on opaque `void *` and `uintptr_t`. Therefore, there is no need for +tests to be dependent on data types and to be repeated for every different data +type there is. + +## Tests + +### Unit-tests + +Tests in this category may not perform some useful actions to exercise the +extension functionality in full, but instead they are focused on making sure +that all APIs are consistent with respect to other APIs. + +#### Memory granularity + +The following checks should be performed for `get_mem_granularity` API: +- the returned value is always bigger than 0 +- recommended granularity is not smaller than minimum granularity +- exception with `feature_not_supported` error code is thrown when `context` + passed to it contains multiple devices and not every of them have + `ext_oneapi_virtual_mem` aspect +- **TODO**: do we need to check that returned granularity is not bigger than + maximum allocation size on a device? + +#### Reserving virtual address ranges + +A check should be performed that exception with `feature_not_supported` error +code is thrown when `context` passed to it contains multiple devices and not +every of them have `ext_oneapi_virtual_mem` aspect. + +A check should be performed that we can successfully perform and immediately +release a valid reservation. + +**TODO**: the spec currently says that passing any invalid arguments to those +APIs results in UB and therefore there is nothing to test. This is probably an +incorrect approach of the spec, because we should be able to perform some checks +and inform user about an error. If/when the spec is updated, this test plan +should be updated as well to cover those new scenarios. + +#### Physical memory + +A check should be performed that methods `get_context()`, `get_device()` and +`size()` return correct values (i.e. ones which were passed to `physical_mem` +constructor). + +A check should be performed that a value returned from a valid call to `map()` +is the same as `reinterpret_cast(ptr)`. + +**TODO**: the spec currently doesn't say what happens if `map` arguments are +invalid (misaligned `ptr`, or `offset + numBytes > size()`) and once that is +clarified the test plan should be updated to cover those scenarios as well. + +A check should be performed that we can change access mode of a virtual memory +range and immediately see it changed. + +A check should be performed that we can successfully map and immediately unmap +a virtual memory range. + +### End-to-end tests + +Tests in this category perform some meaningful actions with the extension to +see that the extension works in a scenarios which mimic real-life usage of the +extension. + +#### Basic access from a kernel + +A test should allocate some amount of a physical memory and then create a +virtual memory range mapped to that physical memory with access mode read-write. +Test should submit two kernels: +- the first kernel fills virtual memory with some data +- the second kernel reads from that virtual memory and copies it content into + an accessor + +Before the second kernel is submitted, we should change access mode of the +virtual memory range to be read-only. + +The content of the accessor is then checked on host to ensure that data can be +correctly both written and read from virtual memory. + +#### Ability to use virtual memory as USM memory + +This test case is intended to check that a pointer produced by a virtual memory +range mapping can indeed be used in various APIs accepting a USM pointer. + +A series of checks should be performed: +- that we can copy _from_ virtual memory _to_ a buffer via accessor +- that we can copy _from_ virtual memory _to_ a USM allocation +- that we can copy _from_ a USM allocation _to_ virtual memory +- that we can copy _from_ a buffer via accessor _to_ virtual memory +- that we can use `memset` on virtual memory +- that we can use `fill` on virtual memory + +#### Remapping of virtual memory range + +This test case is intended to check that we can correctly access virtual memory +range even if it was re-mapped to a different physical range. + +A test should allocate some physical memory and create a virtual memory range +mapped to it. Then, a kernel should be submitted which will fill that virtual +memory range with data. +Once the kernel is complete, another physical memory region should be allocated +and existing virtual memory range should be re-mapped to it. Another kernel +should be submitted to fill that virtual memory range once again with some new +data (different from the data used in the first kernel). +After that we should check that virtual memory range contains the right data +(put there by the second kernel). + +#### "Extending" virtual memory range + +This test case is intended to check that memory accesses to contiguous +virtual memory ranges are performed correctly. + +A test reserve a number of virtual memory ranges which comprsise a contiguous +memory range. Each virtual memory range should be mapped to separate physical +memory range. + +Then this single huge virtual memory range (consisting of several smaller +ranges) should be used to perform various operations, like copying from/to that +range and accessing it from a kernel. + +[spec-link]: https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/experimental/sycl_ext_oneapi_virtual_mem.asciidoc