Adding compile time and runtime properties for usm allocations

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<void*, property_list_t<some_compile_time_prop<1>>>
+
+auto data2 = sycl::ext::oneapi::experimental::malloc_device<int>(N, q, properties);
+// data2 is of type annotated_ptr<int*, property_list_t<some_compile_time_prop<1>>>
+
+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<PropertyListT>::value is true
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> malloc_device(
+    size_t Count, const queue &Q, PropertyListT &PropList) {
+  ...
+}
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> malloc_device(
+    size_t Count, const device &Dev, const context &Ctxt, PropertyListT &PropList) {
+  ...
+}
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> malloc_shared(
+    size_t Count, const queue &Q, PropertyListT &PropList) {
+  ...
+}
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> malloc_shared(
+    size_t Count, const device &Dev, const context &Ctxt, PropertyListT &PropList) {
+  ...
+}
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> malloc_host(
+    size_t Count, const context &Ctxt, PropertyListT &PropList) {
+  ...
+}
+
+template <typename T = void, typename PropertyListT>
+annotated_ptr<T, PropertyListT> 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*
+|========================================