From 6c679fcd482601ce0458063aab4d5d0f19d7f836 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 12:01:32 -0800 Subject: [PATCH 1/3] Support buffer location for usm allocations --- .../supported/sycl_ext_intel_buffer_location.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc index cc462dc7e34fe..aeaa7ce467a4f 100644 --- a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc +++ b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc @@ -7,7 +7,7 @@ NOTE: Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are tradema NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons. -This document describes an extension that adds a compile-time-constant property to tell the SYCL device compiler and runtime in which memory a particular accessor should be allocated. This is useful on targets that possess more than one type of global memory. +This document describes an extension that adds a compile-time-constant property to tell the SYCL device compiler and runtime in which memory a particular accessor or usm allocation should be allocated. This is useful on targets that possess more than one type of global memory. == Name Strings @@ -45,7 +45,7 @@ The use of this extension requires a target that supports SPV_INTEL_fpga_buffer_ == Overview On targets that provide more than one type of global memory, knowing that a particular pointer can only access one of those memory types at compile time can enable compiler optimizations. -This extension adds an accessor property to indicate to the runtime in which of these memories the buffer corresponding to this accessor should be allocated and to inform the compiler that all accesses made through that accessor can only ever interact with the given memory. +This extension adds an accessor property to indicate to the runtime in which of these memories the buffer corresponding to this accessor should be allocated and to inform the compiler that all accesses made through that accessor can only ever interact with the given memory or it can be used to inform the usm alocation to allocate on a given memory. This information is not a hint; it is a functional requirement of the program that must be respected. == Modifications to the SYCL 2020 Pre-Provisional Specification From 42625e326ee71d18df3c99a4f8479e1b95e996a8 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 24 Feb 2022 12:08:10 -0800 Subject: [PATCH 2/3] specify which usm malloc api accept this property --- .../supported/sycl_ext_intel_buffer_location.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc index aeaa7ce467a4f..d05dfd91063ae 100644 --- a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc +++ b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc @@ -45,7 +45,7 @@ The use of this extension requires a target that supports SPV_INTEL_fpga_buffer_ == Overview On targets that provide more than one type of global memory, knowing that a particular pointer can only access one of those memory types at compile time can enable compiler optimizations. -This extension adds an accessor property to indicate to the runtime in which of these memories the buffer corresponding to this accessor should be allocated and to inform the compiler that all accesses made through that accessor can only ever interact with the given memory or it can be used to inform the usm alocation to allocate on a given memory. +This extension adds an accessor property to indicate to the runtime in which of these memories the buffer corresponding to this accessor should be allocated and to inform the compiler that all accesses made through that accessor can only ever interact with the given memory or it can be used to inform the usm alocation (`malloc_device`, `malloc_shared`, `malloc_host`) to allocate on a given memory. This information is not a hint; it is a functional requirement of the program that must be respected. == Modifications to the SYCL 2020 Pre-Provisional Specification From 3809d0ebbe9a303192b2c67242b3a8228daa16d5 Mon Sep 17 00:00:00 2001 From: Sherry Yuan Date: Thu, 3 Mar 2022 07:56:17 -0800 Subject: [PATCH 3/3] add feature test macro and description of how property can be passed to malloc APIs --- .../sycl_ext_intel_buffer_location.asciidoc | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc index d05dfd91063ae..201a4004514ac 100644 --- a/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc +++ b/sycl/doc/extensions/supported/sycl_ext_intel_buffer_location.asciidoc @@ -48,6 +48,28 @@ On targets that provide more than one type of global memory, knowing that a part This extension adds an accessor property to indicate to the runtime in which of these memories the buffer corresponding to this accessor should be allocated and to inform the compiler that all accesses made through that accessor can only ever interact with the given memory or it can be used to inform the usm alocation (`malloc_device`, `malloc_shared`, `malloc_host`) to allocate on a given memory. 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_INTEL_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 +|Initial version of this extension. +|=== + + == Modifications to the SYCL 2020 Pre-Provisional Specification === Section 4.7.6.9.2 Device buffer accessor properties @@ -86,6 +108,37 @@ It also notifies the SYCL runtime to store the given accessor in that memory. | |=== -- + +== Buffer location as properties of USM allocation APIs + +The buffer location property can also be passed to USM allocation APIs. The following is a synopsis. + +[source,c++] +---- +// A property list containing a compile-time property and a runtime property +sycl::ext::oneapi::experimental::properties properties{sycl::ext::intel::property::buffer_location<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>> +sycl::queue q; +q.parallel_for(range<1>(N), [=] (id<1> i){ + data[i] *= 2; +}).wait(); +---- + +The table below describes the effects of associating the property with each malloc APIs. + +|=== +|USM API|Description + +|`malloc_device` +|The returned device pointer should point to the target memory location. +|`malloc_shared` +|The returned pointer should be implicitly migrated to the target memory location. + +|=== + + == Issues == Revision History @@ -96,4 +149,5 @@ It also notifies the SYCL runtime to store the given accessor in that memory. | |======================================== |Rev|Date|Author|Changes |1|2020-09-08|Joe Garvey|*Initial public draft* +|2|2022-03-03|Sherry Yuan|*USM API acceptance of buffer location* |========================================