[SYCL] Implement USM allocation functions with properties (#10235)
This is an implementation of
https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc
The path for the new extension is
`sycl/include/sycl/ext/oneapi/experimental/annotated_usm`, which
contains 6 header files:
- **alloc_util.hpp**: all the utilities (functions & type traits) used
in the implementation
- **alloc_base.hpp**: allocation APIs with no explicit usm kind on the
function name, i.e. `aligned_alloc_annotated` and `malloc_annotated`,
where the usm kind is passed through argument or property list. These
functions are the base of the other annotated allocation functions.
- **alloc_device.hpp**: allocation APIs with "device" on the function
name
- **alloc_host.hpp**: allocation APIs with "host" on the function name
- **alloc_shared.hpp**: allocation APIs with "shared" on the function
name
- **dealloc.hpp**: the deallocation APIs
The new USM alloc APIs with property support are basically wrappers on
the existing USM alloc functions (e.g. `sycl::malloc_host`). The new
APIs do the following things under the hood:
1. extract values of the input compile-time properties `usm_kind`,
`buffer_location` and `alignment`
2. use the values from (1) as the arguments and invoke existing alloc
functions
- `usm_kind`: check if it conflicts with the function (e.g. usm_kind is
_host_ while calling _malloc_device_annotated_)
- `buffer_location`: generate the runtime
`property_list{buffer_location(N)}`, which is passed to
_sycl::malloc_xxx_ as a argument
- `alignment`: combined with the alignment argument (for
_aligned_alloc_xxx_ function) by the following rules
- if one of the alignments is 0, use the other alignment
- otherwise, return the least common multiple
4. create annotated_ptr instance upon the raw pointer from (2), and
return
### Tests added
lit tests:
- sycl/test/extensions/annotated_usm/annotated_usm.cpp
- sycl/test/extensions/annotated_usm/invalid_compile_time_properties.cpp
- sycl/test/extensions/annotated_usm/invalid_runtime_properties.cpp
- sycl/test/extensions/annotated_usm/invalid_usm_kind.cpp
- (test utility) sycl/test/extensions/annotated_usm/fake_properties.cpp
e2e tests:
- sycl/test-e2e/Annotated_usm/annotated_usm_align.cpp
- sycl/test-e2e/Annotated_usm/annotated_usm_align_shared.cpp
- sycl/test-e2e/Annotated_usm/annotated_usm_kind.cpp
- sycl/test-e2e/Annotated_usm/annotated_usm_negative.cpp
