From 55623e1013f268713119cdabc86586c0b9dee7a9 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 15:45:43 -0800 Subject: [PATCH 1/2] USM malloc accept new property list ------------------------------------------------ This is a temporary solution to passing buffer_location information onto runtime. Currently the function will support pass in of compiler properties, however it will not do anything with it. In full solution, an annotated pointer should be returned (rather than T*) to capture compile time information. --- .../sycl_ext_oneapi_usm_properties.asciidoc | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc new file mode 100644 index 0000000000000..ad6206c8e74ab --- /dev/null +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc @@ -0,0 +1,171 @@ += 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 + +:blank: pass:[ +] + +// 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} + +== Introduction +IMPORTANT: This specification is a draft. + +NOTE: 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. + +This extension introduces an alternative way to pass properties into usm malloc. This accepts both runtime and compile-time-constant properties. + +`malloc_device`, `malloc_host`, `malloc_shared` take the property list and pass runtime properties onto runtime libraries. + +The properties will be used by the runtime for allocation of the memory. + +== Notice + +Copyright (c) 2021-2022 Intel Corporation. All rights reserved. + +== Status + +Working Draft + +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. + +== Version + +Revision: 1 + +== 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 + +Steffen Larsen, Intel + +== Dependencies + +This extension is written against the SYCL 2020 specification, Revision 4 and the following extensions: + +- link:sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] + +=== Examples + +The properties can be used in the usm allocation as follows: + +[source,c++] +---- + +using namespace sycl::ext::oneapi; + +sycl::ext::oneapi::experimental::properties properties{sycl::ext::intel::buffer_location<1>}; + +int* data = malloc_device(N, q, properties); + +sycl::queue q; +q.parallel_for(range<1>(N), [=] (id<1> i){ + data[i] *= 2; +}).wait(); +---- + +`data` is device allocations allocated on the second device global memory (as indicated by buffer_location 1). +`buffer_location` property is defined as a part of `SYCL_INTEL_buffer_location` extension. + +== Proposal + +=== Feature test macro + +This extension provides a feature-test macro as described in the core SYCL +specification, Section 6.3.3 "Feature test macros". Therefore, 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 +that the implementation supports. + +[%header,cols="1,5"] +|=== +|Value |Description +|1 |Initial extension version +|=== + + +=== New usm allocation overloads + +[source,c++] +---- +namespace sycl { + +template +T *malloc_device( + size_t Count, const queue &Q, const sycl::ext::oneapi::experimental::properties &PropList = {}, + const detail::code_location CodeLoc = detail::code_location::current()) { + return malloc_device(Count, Q.get_device(), Q.get_context(), PropList, CodeLoc); +} + +template +T *malloc_shared( + size_t Count, const queue &Q, const sycl::ext::oneapi::experimental::properties &PropList = {}, + const detail::code_location CodeLoc = detail::code_location::current()) { + ... +} + +template +T *malloc_host( + size_t Count, const context &Ctxt, const sycl::ext::oneapi::experimental::properties &PropList = {}, + const detail::code_location CodeLoc = detail::code_location::current()) { + ... +} + +} // namespace sycl +---- + +The same setup is applied to other variant of the function signatures. + +Compile time properties can be pass into runtime properties within the allocation function. + +The table below describes the effects of associating each properties +with each malloc function. + +|=== +|Property|Description + +|`buffer_location` +|The `buffer_location` property adds the requirement that the memory must be + allocated to the correct device global memory location as defined in `SYCL_INTEL_buffer_location` extension. + With `malloc_device` the returned device pointer must be in the target global memory. + with `malloc_shared`, memories must be implicitly migrate to the target device global memory. + with `malloc_host`, memory must be at the target device global memory when explicitly migrated. + +|=== + +SYCL implementations may introduce additional properties. If any +combinations of properties are invalid, this must be clearly documented +as part of the new usm_property_list definition. + +== 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* +|======================================== \ No newline at end of file From bd92b223dc61962dfd255030cc02871cf45faed6 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 16:02:57 -0800 Subject: [PATCH 2/2] fixup --- .../experimental/sycl_ext_oneapi_usm_properties.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc index ad6206c8e74ab..12625c80f82a8 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_properties.asciidoc @@ -85,7 +85,7 @@ q.parallel_for(range<1>(N), [=] (id<1> i){ ---- `data` is device allocations allocated on the second device global memory (as indicated by buffer_location 1). -`buffer_location` property is defined as a part of `SYCL_INTEL_buffer_location` extension. +`buffer_location` property is defined as a part of `SYCL_INTEL_buffer_location` extension. The buffer location information will then be passed onto runtime libraries for allocation in correct target memory. == Proposal