From f2e8240e2ab46396017848d0457bc16f3be4b262 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 14:26:03 -0800 Subject: [PATCH 1/9] Define new buffer_location runtime property to be passed into malloc_device ----------------------------------------------------------------------------------- This serves as a temporary solution to supporting usm buffer location, and it is the easiest to implement. Align with changes in https://github.com/intel/llvm/pull/5634 A more complex workaround is to define a new malloc API that accept sycl::ext::oneapi::experimental::properties as its property argument of malloc. The full solution is to define a malloc api that takes sycl::ext::oneapi::experimental::properties as property argument and returns annotated_ptr --- ...ext_oneapi_usm_runtime_properties.asciidoc | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc new file mode 100644 index 000000000000..a08a8ff640f8 --- /dev/null +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc @@ -0,0 +1,119 @@ += SYCL_INTEL_usm_runtime_properties + +== 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. + +NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons. + +NOTE: This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution may change in the future. + +This document propose a new buffer_location runtime property that can be passed to `malloc_device`. + +== Name Strings + ++SYCL_INTEL_usm_runtime_properties+ + +== Contributors +Aditi Kumaraswamy, Intel + +Gregory Lueck, Intel + +Joe Garvey, Intel + +Sherry Yuan, Intel + +Steffen Larsen, Intel + +== Notice + +Copyright (c) 2020 Intel Corporation. All rights reserved. + +== Status + +Working Draft + +This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension. + +Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products. + +== Version + +Built On: {docdate} + +Revision: 1 + +== Overview + +This spec describes the solution of passing runtime buffer location properties to malloc APIs, specifically `malloc_device`. + +On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. + +This information is not a hint; it is a functional requirement of the program that must be respected. + +== Examples + +[source,c++] +---- +array = (int *)malloc_device( + N * sizeof(int), q, + property_list{property::buffer::detail::buffer_location(2)}); + +sycl::queue q; +q.parallel_for(range<1>(N), [=] (id<1> i){ + data[i] *= 2; +}).wait(); +---- + +== 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_RUNTIME_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 +|=== + +=== Changes to runtime properties + +To pass the runtime properties into malloc API, a new buffer properties is introduced. + +[source,c++] +---- +namespace sycl { +namespace property { +namespace buffer { +namespace detail { +class buffer_location + : public sycl::detail::PropertyWithData< + sycl::detail::PropWithDataKind::AccPropBufferLocation> { +public: + buffer_location(uint64_t Location) : MLocation(Location) {} + uint64_t get_buffer_location() const { return MLocation; } + +private: + uint64_t MLocation; +}; +} // namespace detail +} // namespace buffer +} // namespace property +} // namespace sycl +---- + +== Issues + +== Revision History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2022-02-24|Sherry Yuan|*Initial public draft* +|======================================== From f2eab1211f96d622dfc827001d18ae94c073f19e Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 14:38:19 -0800 Subject: [PATCH 2/9] rename extension to runtime_buffer_location --- ...ext_oneapi_usm_runtime_properties.asciidoc | 119 ------------------ 1 file changed, 119 deletions(-) delete mode 100644 sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc deleted file mode 100644 index a08a8ff640f8..000000000000 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_usm_runtime_properties.asciidoc +++ /dev/null @@ -1,119 +0,0 @@ -= SYCL_INTEL_usm_runtime_properties - -== 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. - -NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons. - -NOTE: This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution may change in the future. - -This document propose a new buffer_location runtime property that can be passed to `malloc_device`. - -== Name Strings - -+SYCL_INTEL_usm_runtime_properties+ - -== Contributors -Aditi Kumaraswamy, Intel + -Gregory Lueck, Intel + -Joe Garvey, Intel + -Sherry Yuan, Intel + -Steffen Larsen, Intel - -== Notice - -Copyright (c) 2020 Intel Corporation. All rights reserved. - -== Status - -Working Draft - -This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension. - -Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products. - -== Version - -Built On: {docdate} + -Revision: 1 - -== Overview - -This spec describes the solution of passing runtime buffer location properties to malloc APIs, specifically `malloc_device`. - -On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. - -This information is not a hint; it is a functional requirement of the program that must be respected. - -== Examples - -[source,c++] ----- -array = (int *)malloc_device( - N * sizeof(int), q, - property_list{property::buffer::detail::buffer_location(2)}); - -sycl::queue q; -q.parallel_for(range<1>(N), [=] (id<1> i){ - data[i] *= 2; -}).wait(); ----- - -== 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_RUNTIME_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 -|=== - -=== Changes to runtime properties - -To pass the runtime properties into malloc API, a new buffer properties is introduced. - -[source,c++] ----- -namespace sycl { -namespace property { -namespace buffer { -namespace detail { -class buffer_location - : public sycl::detail::PropertyWithData< - sycl::detail::PropWithDataKind::AccPropBufferLocation> { -public: - buffer_location(uint64_t Location) : MLocation(Location) {} - uint64_t get_buffer_location() const { return MLocation; } - -private: - uint64_t MLocation; -}; -} // namespace detail -} // namespace buffer -} // namespace property -} // namespace sycl ----- - -== Issues - -== Revision History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|======================================== -|Rev|Date|Author|Changes -|1|2022-02-24|Sherry Yuan|*Initial public draft* -|======================================== From 9737bb4b70bd70eefcbe1d83b3f28ab1d9f83425 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 15:21:36 -0800 Subject: [PATCH 3/9] fixup --- ...ext_intel_runtime_buffer_location.asciidoc | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc new file mode 100644 index 000000000000..c7484c703582 --- /dev/null +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -0,0 +1,119 @@ += SYCL_INTEL_usm_runtime_properties + +== 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. + +NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons. + +NOTE: This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution may change in the future. + +This document propose a new buffer_location runtime property that can be passed to `malloc_device`. + +== Name Strings + ++SYCL_INTEL_runtime_buffer_location+ + +== Contributors +Aditi Kumaraswamy, Intel + +Gregory Lueck, Intel + +Joe Garvey, Intel + +Sherry Yuan, Intel + +Steffen Larsen, Intel + +== Notice + +Copyright (c) 2020 Intel Corporation. All rights reserved. + +== Status + +Working Draft + +This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension. + +Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products. + +== Version + +Built On: {docdate} + +Revision: 1 + +== Overview + +This spec describes the solution of passing runtime buffer location properties to malloc APIs, specifically `malloc_device`. + +On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. + +This information is not a hint; it is a functional requirement of the program that must be respected. + +== Examples + +[source,c++] +---- +array = (int *)malloc_device( + N * sizeof(int), q, + property_list{property::buffer::detail::buffer_location(2)}); + +sycl::queue q; +q.parallel_for(range<1>(N), [=] (id<1> i){ + data[i] *= 2; +}).wait(); +---- + +== 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_RUNTIME_BUFFER_LOCATION` 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 +|=== + +=== Changes to runtime properties + +To pass the runtime properties into malloc API, a new buffer properties is introduced. + +[source,c++] +---- +namespace sycl { +namespace property { +namespace buffer { +namespace detail { +class buffer_location + : public sycl::detail::PropertyWithData< + sycl::detail::PropWithDataKind::AccPropBufferLocation> { +public: + buffer_location(uint64_t Location) : MLocation(Location) {} + uint64_t get_buffer_location() const { return MLocation; } + +private: + uint64_t MLocation; +}; +} // namespace detail +} // namespace buffer +} // namespace property +} // namespace sycl +---- + +== Issues + +== Revision History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2022-02-24|Sherry Yuan|*Initial public draft* +|======================================== From bc2bbfae8088f2b54bf9d4a45029eee7077d472b Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Mon, 28 Feb 2022 13:03:10 -0800 Subject: [PATCH 4/9] Follow new spec template --------------------------------- 1. remove ipmlemetation details 2. rename extension 3. fix feature test macro to have same name 4. fix name space to be in sycl::ext::intel::experimental::property::usm --- ...ext_intel_runtime_buffer_location.asciidoc | 134 ++++++++++-------- 1 file changed, 71 insertions(+), 63 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc index c7484c703582..c8104b6a0c4f 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -1,59 +1,94 @@ -= SYCL_INTEL_usm_runtime_properties += sycl_ext_intel_runtime_buffer_location -== Introduction -IMPORTANT: This specification is a draft. +:source-highlighter: coderay +:coderay-linenums-mode: table -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 section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en +:dpcpp: pass:[DPC++] -NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons. +// 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} -NOTE: This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution may change in the future. +== Notice -This document propose a new buffer_location runtime property that can be passed to `malloc_device`. +[%hardbreaks] +Copyright (C) 2022-2022 Intel Corporation. All rights reserved. -== Name Strings +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. -+SYCL_INTEL_runtime_buffer_location+ +== Contact -== Contributors -Aditi Kumaraswamy, Intel + -Gregory Lueck, Intel + -Joe Garvey, Intel + -Sherry Yuan, Intel + -Steffen Larsen, Intel +To report problems with this extension, please open a new issue at: -== Notice +https://github.com/intel/llvm/issues -Copyright (c) 2020 Intel Corporation. All rights reserved. +== Dependencies -== Status +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. -Working Draft - -This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension. - -Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products. +== Status +This is an experimental extension specification, intended to provide early +access to features and gather community feedback. Interfaces defined in this +specification are implemented in {dpcpp}, but they are not finalized and may +change incompatibly in future versions of {dpcpp} without prior notice. +*Shipping software products should not rely on APIs defined in this +specification.* -== Version +[NOTE] +==== +This extension is currently implemented in {dpcpp} only for FPGA devices. Attempting to use this extension on other devices or backends may result in no effect. -Built On: {docdate} + -Revision: 1 +This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution will come in the future. +==== == Overview -This spec describes the solution of passing runtime buffer location properties to malloc APIs, specifically `malloc_device`. +This document propose a new buffer_location runtime property that can be passed to `malloc_device`. On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. This information is not a hint; it is a functional requirement of the program that must be respected. +== 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_INTEL_RUNTIME_BUFFER_LOCATION` 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. +|=== + == Examples [source,c++] ---- array = (int *)malloc_device( N * sizeof(int), q, - property_list{property::buffer::detail::buffer_location(2)}); + property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)}); sycl::queue q; q.parallel_for(range<1>(N), [=] (id<1> i){ @@ -61,24 +96,6 @@ q.parallel_for(range<1>(N), [=] (id<1> i){ }).wait(); ---- -== 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_RUNTIME_BUFFER_LOCATION` 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 -|=== === Changes to runtime properties @@ -86,24 +103,15 @@ To pass the runtime properties into malloc API, a new buffer properties is intro [source,c++] ---- -namespace sycl { -namespace property { -namespace buffer { -namespace detail { -class buffer_location - : public sycl::detail::PropertyWithData< - sycl::detail::PropWithDataKind::AccPropBufferLocation> { -public: - buffer_location(uint64_t Location) : MLocation(Location) {} - uint64_t get_buffer_location() const { return MLocation; } - -private: - uint64_t MLocation; +namespace sycl::ext::intel::experimental::property::usm { + +class buffer_location { + public: + buffer_location(int location); + int get_buffer_location() const; }; -} // namespace detail -} // namespace buffer -} // namespace property -} // namespace sycl + +} // namespace sycl::ext::intel::experimental::property::usm ---- == Issues From 8335ff5a09200cb8b0e8bb4c2493c9f5125040ea Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Tue, 1 Mar 2022 08:52:23 -0800 Subject: [PATCH 5/9] Add more details on motivation of the extension -------------------------------------------------------------- 1. Remove notes 2. Specify which malloc api accept the property 3. Add more detaile ddescription, and expected behavior when used on non fpga device --- ...ext_intel_runtime_buffer_location.asciidoc | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc index c8104b6a0c4f..dca7bc749b95 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -45,12 +45,6 @@ change incompatibly in future versions of {dpcpp} without prior notice. *Shipping software products should not rely on APIs defined in this specification.* -[NOTE] -==== -This extension is currently implemented in {dpcpp} only for FPGA devices. Attempting to use this extension on other devices or backends may result in no effect. - -This serves as a temporary workaround for usm allocation to accept buffer location properties, and the formal solution will come in the future. -==== == Overview @@ -58,8 +52,6 @@ This document propose a new buffer_location runtime property that can be passed On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. -This information is not a hint; it is a functional requirement of the program that must be respected. - == Specification === Feature test macro @@ -86,12 +78,12 @@ supports. [source,c++] ---- -array = (int *)malloc_device( - N * sizeof(int), q, - property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)}); +array = (int *)sycl::malloc_device( + N, q, + sycl::property_list{sycl::ext::intel::experimental::property::usm::buffer_location(2)}); sycl::queue q; -q.parallel_for(range<1>(N), [=] (id<1> i){ +q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){ data[i] *= 2; }).wait(); ---- @@ -99,7 +91,7 @@ q.parallel_for(range<1>(N), [=] (id<1> i){ === Changes to runtime properties -To pass the runtime properties into malloc API, a new buffer properties is introduced. +This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location`` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, `sycl::malloc_host()` function. However, this property has no effect when passed to `sycl::malloc_shared()`, `sycl::malloc_host()`. Following is a synopsis of this property. [source,c++] ---- @@ -114,6 +106,11 @@ class buffer_location { } // namespace sycl::ext::intel::experimental::property::usm ---- +On targets that provide more than one type of global memory, `buffer_location` allows user to specify which of the global memory to allocate memory to. This provide user the flexibility to choose the global memory that satisfy requirements for bandwodth and throughput. + +This property is ignored for non-FPGA devices. Attempting to use this extension on other devices or backends will result in no effect. + + == Issues == Revision History From 63ea912206bce5c07e6f21a4df457c6da56955a9 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Tue, 1 Mar 2022 09:03:14 -0800 Subject: [PATCH 6/9] fix_typos --- .../sycl_ext_intel_runtime_buffer_location.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc index dca7bc749b95..a8597fad12a8 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -91,7 +91,7 @@ q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){ === Changes to runtime properties -This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location`` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, `sycl::malloc_host()` function. However, this property has no effect when passed to `sycl::malloc_shared()`, `sycl::malloc_host()`. Following is a synopsis of this property. +This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, `sycl::malloc_host()` function. However, this property has no effect when passed to `sycl::malloc_shared()`, `sycl::malloc_host()`. Following is a synopsis of this property. [source,c++] ---- @@ -106,7 +106,7 @@ class buffer_location { } // namespace sycl::ext::intel::experimental::property::usm ---- -On targets that provide more than one type of global memory, `buffer_location` allows user to specify which of the global memory to allocate memory to. This provide user the flexibility to choose the global memory that satisfy requirements for bandwodth and throughput. +On targets that provide more than one type of global memory, `buffer_location` allows user to specify which of the global memory to allocate memory to. This provide user the flexibility to choose the global memory that satisfy requirements for bandwidth and throughput. This property is ignored for non-FPGA devices. Attempting to use this extension on other devices or backends will result in no effect. From 4805f405b103954933d192ff87d8ff349abf1bd2 Mon Sep 17 00:00:00 2001 From: sherry-yuan Date: Tue, 1 Mar 2022 14:46:08 -0500 Subject: [PATCH 7/9] Update sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc Co-authored-by: Greg Lueck --- .../sycl_ext_intel_runtime_buffer_location.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc index a8597fad12a8..e907fe8924d8 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -91,7 +91,7 @@ q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){ === Changes to runtime properties -This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, `sycl::malloc_host()` function. However, this property has no effect when passed to `sycl::malloc_shared()`, `sycl::malloc_host()`. Following is a synopsis of this property. +This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, and `sycl::malloc_host()` functions. However, this property has no effect when passed to `sycl::malloc_shared()` or `sycl::malloc_host()`. Following is a synopsis of this property. [source,c++] ---- From 25e81e26962704bf75c17d0dff737875ce36e3e3 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Tue, 1 Mar 2022 11:57:58 -0800 Subject: [PATCH 8/9] change all lines to be less than 80 characters --- ...ext_intel_runtime_buffer_location.asciidoc | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc index e907fe8924d8..da9f8f7b5d17 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -48,9 +48,12 @@ specification.* == Overview -This document propose a new buffer_location runtime property that can be passed to `malloc_device`. +This document propose a new buffer_location runtime property that can be +passed to `malloc_device`. -On targets that provide more than one type of global memory, this provide users the flexibility of choosing which memory the device usm should be allocated to. +On targets that provide more than one type of global memory, this provide +users the flexibility of choosing which memory the device usm should be +allocated to. == Specification @@ -91,7 +94,13 @@ q.parallel_for(sycl::range<1>(N), [=] (sycl::id<1> i){ === Changes to runtime properties -This extension adds the new property `sycl::ext::intel::experimental::property::usm::buffer_location` which applications can pass in the property_list parameter to all overloads of the `sycl::malloc_device()`, `sycl::malloc_shared()`, and `sycl::malloc_host()` functions. However, this property has no effect when passed to `sycl::malloc_shared()` or `sycl::malloc_host()`. Following is a synopsis of this property. +This extension adds the new property +`sycl::ext::intel::experimental::property::usm::buffer_location` which +applications can pass in the property_list parameter to all overloads of the +`sycl::malloc_device()`, `sycl::malloc_shared()`, and `sycl::malloc_host()` +functions. However, this property has no effect when passed to +`sycl::malloc_shared()` or `sycl::malloc_host()`. Following is a synopsis of + this property. [source,c++] ---- @@ -106,9 +115,13 @@ class buffer_location { } // namespace sycl::ext::intel::experimental::property::usm ---- -On targets that provide more than one type of global memory, `buffer_location` allows user to specify which of the global memory to allocate memory to. This provide user the flexibility to choose the global memory that satisfy requirements for bandwidth and throughput. +On targets that provide more than one type of global memory, `buffer_location` +allows user to specify which of the global memory to allocate memory to. This +provide user the flexibility to choose the global memory that satisfy +requirements for bandwidth and throughput. -This property is ignored for non-FPGA devices. Attempting to use this extension on other devices or backends will result in no effect. +This property is ignored for non-FPGA devices. Attempting to use this +extension on other devices or backends will result in no effect. == Issues @@ -120,5 +133,5 @@ This property is ignored for non-FPGA devices. Attempting to use this extension [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-02-24|Sherry Yuan|*Initial public draft* +|1|2022-03-01|Sherry Yuan|*Initial public draft* |======================================== From 9301c51e755d118cee94fb2df391ccb3549d6a23 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Tue, 1 Mar 2022 14:48:44 -0800 Subject: [PATCH 9/9] move from experimental to proposed folder --- .../sycl_ext_intel_runtime_buffer_location.asciidoc | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) rename sycl/doc/extensions/{experimental => proposed}/sycl_ext_intel_runtime_buffer_location.asciidoc (90%) diff --git a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_intel_runtime_buffer_location.asciidoc similarity index 90% rename from sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc rename to sycl/doc/extensions/proposed/sycl_ext_intel_runtime_buffer_location.asciidoc index da9f8f7b5d17..8a2aece3c12e 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_intel_runtime_buffer_location.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_intel_runtime_buffer_location.asciidoc @@ -38,13 +38,11 @@ references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision. == Status -This is an experimental extension specification, intended to provide early -access to features and gather community feedback. Interfaces defined in this -specification are implemented in {dpcpp}, but they are not finalized and may -change incompatibly in future versions of {dpcpp} without prior notice. -*Shipping software products should not rely on APIs defined in this -specification.* - +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