diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_shortcuts.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_shortcuts.asciidoc new file mode 100644 index 0000000000000..8023818b46c93 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_shortcuts.asciidoc @@ -0,0 +1,448 @@ += sycl_ext_oneapi_usm_shortcuts + +:source-highlighter: coderay +:coderay-linenums-mode: table + +// This section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en +:dpcpp: pass:[DPC++] +:endnote: —{nbsp}end{nbsp}note + +// Set the default source code type in this document to C++, +// for syntax highlighting purposes. This is needed because +// docbook uses c++ and html5 uses cpp. +:language: {basebackend@docbook:c++:cpp} + + +== Notice + +[%hardbreaks] +Copyright (C) 2025 Intel Corporation. All rights reserved. + +Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks +of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by +permission by Khronos. + + +== Contact + +To report problems with this extension, please open a new issue at: + +https://github.com/intel/llvm/issues + + +== Dependencies + +:khr-default-context: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:khr-default-context + +This extension is written against the SYCL 2020 revision 10 specification. +All references below to the "core SYCL specification" or to section numbers in +the SYCL specification refer to that revision. + +[_Note:_ The APIs in this extension depend on the concept of a per-platform +default context as specified in section 4.6.2 "Platform class" of the core SYCL +specification. +As a convenience, this extension specification describes the behavior of its +APIs by using the `khr_get_default_context` function from {khr-default-context}[ +sycl_khr_default_context], however there is no true dependency on that +extension. +An implementation could still implement sycl_ext_oneapi_usm_shortcuts even +without implementing sycl_khr_default_context because the core SYCL +specification still requires there to be a per-platform default context even if +the core SYCL specification does not provide a convenient way to get it. +_{endnote}_] + + +== Status + +This is a proposed extension specification, intended to gather community +feedback. +Interfaces defined in this specification may not be implemented yet or may be in +a preliminary state. +The specification itself may also change in incompatible ways before it is +finalized. +*Shipping software products should not rely on APIs defined in this +specification.* + + +== Overview + +This extension adds convenience overloads to the USM allocation, deallocation, +and query functions, which do not require the caller to pass a device or +context. +The device is inferred from the default device selector, and the context is +inferred from the platform containing that device. +These shortcuts are similar to the default queue constructor, which also infers +the device and context in the same way. +We believe these shortcuts will make it easier for people migrating code from +CUDA because the equivalent CUDA functions (`cudaMalloc`, `cudaMallocManaged`, +and `cudaMallocHost`) also do not take a device or context parameter. + + +== Specification + +=== Feature test macro + +This extension provides a feature-test macro as described in the core SYCL +specification. An implementation supporting this extension must predefine the +macro `SYCL_EXT_ONEAPI_USM_SHORTCUTS` to one of the values defined in the table +below. Applications can test for the existence of this macro to determine if +the implementation supports this feature, or applications can test the macro's +value to determine which of the extension's features the implementation +supports. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|The APIs of this experimental extension are not versioned, so the + feature-test macro always has this value. +|=== + +=== New USM device allocation functions + +This extension adds the following functions which allocate USM device memory. + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* malloc_device(size_t numBytes, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_device(numBytes, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* malloc_device(size_t count, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_device(count, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* aligned_alloc_device(size_t alignment, size_t numBytes, + const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_device(alignment, numBytes, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* aligned_alloc_device(size_t alignment, size_t count, + const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_device(alignment, count, d, ctxt, propList); +---- + +''' + +=== New USM host allocation functions + +This extension adds the following functions which allocate USM host memory. + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* malloc_host(size_t numBytes, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_host(numBytes, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* malloc_host(size_t count, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_host(count, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* aligned_alloc_host(size_t alignment, size_t numBytes, + const property_list& propList = {}) + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_host(alignment, numBytes, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* aligned_alloc_host(size_t alignment, size_t count, + const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_host(alignment, count, ctxt, propList); +---- + +''' + +=== New USM shared allocation functions + +This extension adds the following functions which allocate USM shared memory. + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* malloc_shared(size_t numBytes, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_shared(numBytes, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* malloc_shared(size_t count, const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::malloc_shared(count, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void* aligned_alloc_shared(size_t alignment, size_t numBytes, + const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_shared(alignment, numBytes, d, ctxt, propList); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +template +T* aligned_alloc_shared(size_t alignment, size_t count, + const property_list& propList = {}); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::aligned_alloc_shared(alignment, count, d, ctxt, propList); +---- + +''' + +=== New USM deallocation functions + +This extension adds the following functions which deallocate USM memory. + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +void free(void* ptr); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +sycl::free(ptr, ctxt); +---- + +''' + +=== New USM query functions + +This extension adds the following functions which query USM memory allocations. + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +usm::alloc get_pointer_type(const void* ptr); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::get_pointer_type(ptr, ctxt); +---- + +''' + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +device get_pointer_device(const void* ptr); + +} // namespace sycl::ext::oneapi::experimental +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::contxt ctxt = d.get_platform().khr_get_default_context(); +return sycl::get_pointer_device(ptr, ctxt); +---- + +'''