|
| 1 | +# Test plan for [`sycl_ext_oneapi_launch_queries`][spec-link] extension |
| 2 | + |
| 3 | +## Testing scope |
| 4 | + |
| 5 | +### Device coverage |
| 6 | + |
| 7 | +The unit tests should be launched on every supported device configuration we |
| 8 | +have. |
| 9 | + |
| 10 | +### Type coverage |
| 11 | + |
| 12 | +Each query is templated on a single template type argument `Param` |
| 13 | +with some queries being template overloads of each other. |
| 14 | +Each query has a restriction on the value of `Param` defined |
| 15 | +in the relevant section of the spec. |
| 16 | + |
| 17 | +Param must be one of the following types defined in |
| 18 | +`sycl::ext::oneapi::experiemntal::info::kernel` namespace: |
| 19 | +- `max_work_item_sizes<1>` |
| 20 | +- `max_work_item_sizes<2>` |
| 21 | +- `max_work_item_sizes<3>` |
| 22 | +- `max_work_group_size` |
| 23 | +- `max_num_work_groups` |
| 24 | +- `max_sub_group_size` |
| 25 | +- `num_sub_groups` |
| 26 | + |
| 27 | +The tests should cover all of these types. |
| 28 | + |
| 29 | +## Tests |
| 30 | + |
| 31 | +### Unit tests |
| 32 | + |
| 33 | +#### Interface tests |
| 34 | + |
| 35 | +These tests are intended to check that all classes and methods defined by the |
| 36 | +extension have correct implementation, i.e.: right signatures, right return |
| 37 | +types, all necessary constraints are checked/enforced, etc. |
| 38 | + |
| 39 | +These tests should check the following: |
| 40 | + |
| 41 | +- that each query is not available when the template argument `Param` has |
| 42 | + a value different than the one in the spec. |
| 43 | +- that each query can be called with the appropriate value for `Param` and the |
| 44 | + appropriate argument types as defined by its signature. |
| 45 | +- the return types of all queries match the spec. |
| 46 | + |
| 47 | +Tests in this category may not perform some useful actions to exercise the |
| 48 | +extension functionality in full, but instead they are focused on making sure |
| 49 | +that all APIs are consistent with respect to other APIs. |
| 50 | + |
| 51 | +#### Consistency with device-specific queries |
| 52 | + |
| 53 | +Verify, for each query in the extension, that the value returned is smaller |
| 54 | +than or equal than the value returned when querying the corresponding |
| 55 | +device-specific queries. |
| 56 | + |
| 57 | +For example, |
| 58 | + |
| 59 | +- `max_work_item_sizes<dim>` can be compared with |
| 60 | +`sycl::info::device::max_work_item_sizes<dim>` |
| 61 | +- `max_work_group_size` can be compared with `sycl::info::device::max_work_group_size` |
| 62 | +- `max_num_work_groups` can be compared with `sycl::ext::oneapi::experimental::info::device::max_work_groups<dim>` |
| 63 | +- `max_sub_group_size` can be compared with `sycl::info::kernel_device_specific::max_sub_group_size` |
| 64 | +- `num_sub_groups` can be compared with `sycl::info::device::max_num_sub_groups` |
| 65 | + |
| 66 | +#### Consistency of `max_sub_group_size` queries |
| 67 | + |
| 68 | +The test needs to check that all three `ext_oneapi_get_info` queries for |
| 69 | +which `Param == max_sub_group_size` return the same value as |
| 70 | +`sub_group::get_max_local_range()` inside the kernel. |
| 71 | + |
| 72 | +#### Check behavior in the case of invalid arguments to queries |
| 73 | + |
| 74 | +For all queries for which `Param == max_num_work_groups` or |
| 75 | +`Param == max_sub_group_size` or `Param == num_sub_groups`, verify that |
| 76 | +a synchronous `exception` with the error code `errc::invalid` is thrown |
| 77 | +if the work-group size `r` is 0. |
| 78 | + |
| 79 | +#### Check return value of queries depending on queue submission status |
| 80 | + |
| 81 | +Verify that if kernel submission to a queue does not throw then |
| 82 | +the return value of each query on the queue with the given kernel |
| 83 | +is strictly greater than 0. |
| 84 | +Likewise, verify that if at least one query returns 0, then kernel |
| 85 | +submission throws. |
| 86 | + |
| 87 | +[spec-link]: https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/proposed/sycl_ext_oneapi_launch_queries.asciidoc |
0 commit comments