diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_properties.asciidoc new file mode 100644 index 0000000000000..0cb5f93fb3c63 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_properties.asciidoc @@ -0,0 +1,185 @@ += sycl_ext_oneapi_usm_properties + +: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++] + +// 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) 2022-2022 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 + +This extension is written against the SYCL 2020 revision 4 specification. All +references below to the "core SYCL specification" or to section numbers in the +SYCL specification refer to that revision. + +This extension also depends on the following other SYCL extensions: + +- link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] +- link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] + + +== 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 properties support (as defined in the sycl_ext_oneapi_properties extension) to the USM malloc APIs. This allows the malloc calls to accept both run time and compile time properties. + +`malloc_device`, `malloc_host`, `malloc_shared` take the properties, and return an annotated_ptr that carries the passed in compile-time properties. + +The goal of these changes is to enable information about properties to propagate to the device compiler and thereby enable additional optimization of kernel code. + + +== 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_PROPERTIES` 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 +|Initial version of this extension. +|=== + + +== Contributors + +Abhishek Tiwari, Intel + +Aditi Kumaraswamy, Intel + +Gregory Lueck, Intel + +Jason Sewall, Intel + +Jessica Davies, Intel + +Joe Garvey, Intel + +Mike Kinsner, Intel + +Sherry Yuan, Intel + + +=== Examples + +The following is a synopsis of the new USM malloc API. + +[source,c++] +---- + +// A property list containing a compile-time property and a runtime property +sycl::ext::oneapi::experimental::properties properties{some_compile_time_prop<1>, some_runtime_prop(1)}; + +// The compile time property is passed to template arguments of annotated_ptr +auto data = sycl::ext::oneapi::experimental::malloc_device(N, q, properties); +// data is of type annotated_ptr>> + +auto data2 = sycl::ext::oneapi::experimental::malloc_device(N, q, properties); +// data2 is of type annotated_ptr>> + +sycl::queue q; +q.parallel_for(range<1>(N), [=] (id<1> i){ + data2[i] *= 2; +}).wait(); +---- + + +=== New USM allocation APIs + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +// All function defined below are available only when is_property_list::value is true + +template +annotated_ptr malloc_device( + size_t Count, const queue &Q, PropertyListT &PropList) { + ... +} + +template +annotated_ptr malloc_device( + size_t Count, const device &Dev, const context &Ctxt, PropertyListT &PropList) { + ... +} + +template +annotated_ptr malloc_shared( + size_t Count, const queue &Q, PropertyListT &PropList) { + ... +} + +template +annotated_ptr malloc_shared( + size_t Count, const device &Dev, const context &Ctxt, PropertyListT &PropList) { + ... +} + +template +annotated_ptr malloc_host( + size_t Count, const context &Ctxt, PropertyListT &PropList) { + ... +} + +template +annotated_ptr malloc_host( + size_t Count, const queue &Q, PropertyListT &PropList) { + ... +} + +} // namespace sycl::ext::oneapi::experimental +---- + +The same setup is applied to other overloads of malloc APIs. + +The returned `annotated_ptr` contains the USM pointers and the passed in compile-time properties to enable additional compiler optimizations. + + +== Revision History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2022-02-21|Sherry Yuan|*Initial public working draft* +|========================================