From c7653a3dc4a84de6f34949e67fa84e21bdab4aa5 Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Thu, 9 Jun 2022 14:57:46 -0700 Subject: [PATCH 01/16] Initial draft of the USM memory allocation functions with properties support extension. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 337 ++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc new file mode 100644 index 0000000000000..e66d52ebb8c60 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -0,0 +1,337 @@ += sycl_ext_oneapi_usm_malloc_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} + +// This is necessary for asciidoc, but not for asciidoctor +:cpp: C++ +:dpcpp: DPC++ + +== Notice + +Copyright (c) 2022 Intel Corporation. All rights reserved. + +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. + +== Contact + +Jessica Davies, Intel (jessica 'dot' davies 'at' intel 'dot' com) + +== Contributors + +Jessica Davies, Intel + +Joe Garvey, Intel + +Michael Kinsner, Intel + +Aditi Kumaraswamy, Intel + +Gregory Lueck, Intel + +John Pennycook, Intel + +Roland Schulz, Intel +Jason Sewall, Intel + +Abhishek Tiwari, Intel + +Sherry Yuan, Intel + +== Dependencies + +This extension is written against the SYCL 2020 specification, revision 5. +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 link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension, to the USM malloc APIs. +The USM malloc functions defined in this extension take a `properties` object as a parameter, and return an `annotated_ptr` with the same compile-time-constant properties. +This allows both runtime and compile-time-constant properties to be specified when allocating USM. +Furthermore, the annotated_ptr returned by the USM malloc functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. + +[NOTE] +==== +In this document, we use the shortened form `annotated_ptr` to refer to the +proposed `sycl::ext::oneapi::experimental::annotated_ptr` class. +We also use the shortened form `properties` to refer to the `sycl::ext::oneapi::experimental::properties` class. +==== + +The purpose of this document is to clearly describe and specify USM malloc functions with compile-time-constant properties support, +and related concepts, types, and mechanisms, and to give examples and context for their usage. + +== Examples + +In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a +runtime property. + +The following example shows the use of the USM malloc APIs with compile-time-constant property support. + +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; + +properties P1{bar, baz, foo{1}}; +properties P2{bar, baz, foo{2}}; +properties P3{bar, baz} + +// APtr1 is of type annotated_ptr +auto APtr1 = malloc_device(N, q, P1); + +// APtr2 is of type annotated_ptr +auto APtr2 = malloc_device(N, q, P2); + +// APtr3 is of type annotated_ptr +auto APtr3 = malloc_device(N, q, P3); + +// Runtime property values do not affect the type of the annotated_ptr +// returned by malloc_device +static_assert(std::is_same_v); + +// APtr1 and APtr3 do not have the same runtime properties +static_assert(!std::is_same_v); +---- + +== Specification + +=== 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_MALLOC_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 +|=== + +=== USM Memory Allocation Functions with properties Support + +The core SYCL specification lists eight functions in each of the following four tables: + +- Table 103 "USM Device Memory Allocation Functions", of Section 4.8.3.2 "Device allocation functions" + +- Table 104 "USM Host Memory Allocation Functions", of Section 4.8.3.3 "Host allocation functions" + +- Table 105 "USM Shared Memory Allocation Functions", of Section 4.8.3.4 "Shared allocation functions" + +- Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" + +This extension introduces a new function for each function listed in the above tables of the core SYCL specification. +For the sake of clarity and brevity, this extension specifies the new functions by describing how they differ from the corresponding functions in the core SYCL specification. + +[NOTE] +==== +The USM memory allocation functions defined in the core SYCL specification can be used in the same program as the USM memory allocation functions with `properties` support defined in this extension. +==== + +The following table lists phrases which appear in the the above tables of the core SYCL specification, and how they are replaced to generate the corresponding tables in this extension. +The parameters of each function introduced by this extension are the same as the parameters of the corresponding function in the core SYCL specification, except for the last parameter `propList`. + +[options="header"] +|==== +| Core SYCL | USM memory allocation functions with `properties` support +a| +Zero or more properties can be provided to the allocation function via an instance of property_list. +|Zero or more runtime or compile-time-constant properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. +a| +On failure, returns nullptr. +| +On failure, the raw pointer of the returned annotated_ptr will be nullptr. +a| +sycl::malloc +| +sycl::ext::oneapi::experimental::malloc +a| +sycl::aligned_alloc +| +sycl::ext::oneapi::experimental::aligned_alloc +a| +sycl::malloc_device + +sycl::malloc_host + +sycl::malloc_shared +| +sycl::ext::oneapi::experimental::malloc_device + +sycl::ext::oneapi::experimental::malloc_host + +sycl::ext::oneapi::experimental::malloc_shared +a| +sycl::aligned_alloc_device + +sycl::aligned_alloc_host + +sycl::aligned_alloc_shared +| +sycl::ext::oneapi::experimental::aligned_alloc_device + +sycl::ext::oneapi::experimental::aligned_alloc_host + +sycl::ext::oneapi::experimental::aligned_alloc_shared +a| +The USM memory allocation function is a function template `template ` returning `T *`. +| +The corresponding USM memory allocation function with `properties` support is a function template +`template` returning `annotated_ptr`. +a| +The USM memory allocation funtion is not a function template, and returns `void *`. +| +The corresponding USM memory allocation function with `properties` support is a function template: +`template` returning `annotated_ptr`. +a| +The last parameter of the USM memory allocation function is an optional `const property_list &propList = {}`. +| +The last parameter of the corresponding USM memory allocation function with `properties` support is a non-optional `const propertyListT &propList`. +|==== + +The description of every function in this extension contains the following sentences: + +[options="header"] +|==== +| Function | Sentences appended to the Description +a| any of the functions specified in this extension +| +The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + + +If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + + +Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. +|==== + +For every function added by this extension that contains the word "aligned" in its name, its description contains the following additional sentence: +[options="header"] +|==== +| Function | Sentences appended to the Description +a| any of the functions specified in this extension that contain "aligned" in their name +| +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, its compile-time-constant value must be the same as the value of the `alignment` parameter, otherwise an error will be output by the compiler. +|==== + + + +==== Example + +The following example shows two of the functions specified by this extension: + +[frame="topbot",options="header"] +|=== +|Functions |Description +a| +[source,c++] +---- +template +annotated_ptr +sycl::ext::oneapi::experimental::malloc_device( + size_t count, + const sycl::queue& syclQueue, + const propertyListT &propList) +---- +| +Simplified form where syclQueue +provides the device and context. + + +Zero or more runtime or compile-time-constant properties can be +provided to the allocation function +via an instance of sycl::ext::oneapi::experimental::properties. + + +Throws a synchronous exception +with the errc::feature_not_supported error code if the device does +not have aspect::usm_device_allocations. + + +The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + + +If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + + +Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. + +// --- ROW BREAK --- +a| +[source,c++] +---- +template +annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc( + size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + usm::alloc kind, + const propertyListT &propList) +---- +| +Returns a kind allocation. This allocation is specified in bytes and +aligned to the specified alignment. +This memory must be deallocated +with sycl::free to avoid memory +leaks. + + +On failure, the raw pointer of the returned annotated_ptr will be nullptr. + + +Zero or more runtime or compile-time-constant properties can be +provided to the allocation function +via an instance of sycl::ext::oneapi::experimental::properties. + + +The syclDevice parameter is +ignored if kind is usm::alloc::host. +If kind is not usm::alloc::host, +syclDevice must either be contained by syclContext or it must be +a descendent device of some +device that is contained by that +context, otherwise this function +throws a synchronous exception +with the errc::invalid error code. + + +The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + + +If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + + +Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. + + +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, its compile-time-constant value must be the same as the value of the `alignment` parameter, otherwise an error will be output by the compiler. +|=== + + +==== Deallocation + +To avoid memory leaks, USM memory allocated using the USM memory allocation functions with properties support defined in this extension, must be deallocated using one of the `sycl::free` functions listed in Table 107 "USM Deallocation Functions" of Section 4.8.3.6 "Memory deallocation functions" of the core SYCL specification. + +The following example shows how USM memory allocated using one of the functions defined in this extension should be deallocated, to avoid memory leaks. + +[source,c++] +---- +sycl::ext::oneapi::experimental::properties P1{bar}; +// APtr is of type annotated_ptr; +auto APtr = sycl::ext::oneapi::experimental::malloc_device(N, q, P1); + +// Deallocate the memory using the raw pointer of APtr +sycl::free(APtr.get(), q); +---- + +== Revision History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2022-06-09|Jessica Davies|*Initial public working draft* +|======================================== From f6ca73d66d93455d8f1f05d5aab48825c07f957f Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Fri, 10 Jun 2022 13:59:54 -0700 Subject: [PATCH 02/16] List all functions explicitly. Properties returned in the annotated_ptr can now differ from those passed to the allocation function. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 993 ++++++++++++++++-- 1 file changed, 887 insertions(+), 106 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index e66d52ebb8c60..44d304e57037c 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -67,10 +67,10 @@ not rely on APIs defined in this specification.* == Overview -This extension adds properties support, as defined in the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension, to the USM malloc APIs. -The USM malloc functions defined in this extension take a `properties` object as a parameter, and return an `annotated_ptr` with the same compile-time-constant properties. -This allows both runtime and compile-time-constant properties to be specified when allocating USM. -Furthermore, the annotated_ptr returned by the USM malloc functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. +This extension introduces USM memory allocation functions with support for compile-time-constant and runtime properties, as defined in the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. +The USM memory allocation functions introduced by this extension take a `properties` object as a parameter, and return an `annotated_ptr`. +This allows both runtime and compile-time-constant properties to be specified when allocating USM memory. +Furthermore, the annotated_ptr returned by the USM memory allocation functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. [NOTE] ==== @@ -79,7 +79,7 @@ proposed `sycl::ext::oneapi::experimental::annotated_ptr` class. We also use the shortened form `properties` to refer to the `sycl::ext::oneapi::experimental::properties` class. ==== -The purpose of this document is to clearly describe and specify USM malloc functions with compile-time-constant properties support, +The purpose of this document is to clearly describe and specify USM memory allocation functions with compile-time-constant properties support, and related concepts, types, and mechanisms, and to give examples and context for their usage. == Examples @@ -87,7 +87,9 @@ and related concepts, types, and mechanisms, and to give examples and context fo In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a runtime property. -The following example shows the use of the USM malloc APIs with compile-time-constant property support. +Properties passed to the USM memory allocation functions with `properties` support, may or may not appear on the returned annotated_ptr object. +In this example, we assume that if the `bar` or `foo` properties are passed to a USM memory allocation function, they will also appear on the returned annotated_ptr. +However, the `baz` property will not appear on the returned annotated_ptr. [source,c++] ---- @@ -97,23 +99,35 @@ properties P1{bar, baz, foo{1}}; properties P2{bar, baz, foo{2}}; properties P3{bar, baz} -// APtr1 is of type annotated_ptr +// APtr1 is of type annotated_ptr auto APtr1 = malloc_device(N, q, P1); -// APtr2 is of type annotated_ptr +// APtr2 is of type annotated_ptr auto APtr2 = malloc_device(N, q, P2); -// APtr3 is of type annotated_ptr +// APtr3 is of type annotated_ptr auto APtr3 = malloc_device(N, q, P3); // Runtime property values do not affect the type of the annotated_ptr -// returned by malloc_device static_assert(std::is_same_v); -// APtr1 and APtr3 do not have the same runtime properties +// APtr1 and APtr3 do not have the same properties static_assert(!std::is_same_v); ---- +The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. +When `alignment` is passed to a USM memory allocation function with `properties` support, it will also appear on the returned annotated_ptr. +If the alignment specified by this property is incompatible with the alignment specified at runtime, the result is undefined behavior. + +[source,c++] +---- +properties P1{alignment<8>}; +// APtr1 is of type annotated_ptr +auto APtr1 = sycl::ext::oneapi::experimental::aligned_alloc_device(512, N, q, P1); // UB +auto APtr2 = sycl::ext::oneapi::experimental::aligned_alloc_device(4, N, q, P1); // ok +---- + + == Specification === Feature test macro @@ -133,7 +147,7 @@ that the implementation supports. |1 |Initial extension version |=== -=== USM Memory Allocation Functions with properties Support +=== Orientation The core SYCL specification lists eight functions in each of the following four tables: @@ -143,7 +157,7 @@ The core SYCL specification lists eight functions in each of the following four - Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" This extension introduces a new function for each function listed in the above tables of the core SYCL specification. -For the sake of clarity and brevity, this extension specifies the new functions by describing how they differ from the corresponding functions in the core SYCL specification. +For the sake of clarity, we first describe how the new functions differ from the corresponding functions in the core SYCL specification. All APIs introduced by this extension are listed explicitly in Section <>. [NOTE] ==== @@ -157,13 +171,6 @@ The parameters of each function introduced by this extension are the same as the |==== | Core SYCL | USM memory allocation functions with `properties` support a| -Zero or more properties can be provided to the allocation function via an instance of property_list. -|Zero or more runtime or compile-time-constant properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. -a| -On failure, returns nullptr. -| -On failure, the raw pointer of the returned annotated_ptr will be nullptr. -a| sycl::malloc | sycl::ext::oneapi::experimental::malloc @@ -188,138 +195,912 @@ sycl::ext::oneapi::experimental::aligned_alloc_device + sycl::ext::oneapi::experimental::aligned_alloc_host + sycl::ext::oneapi::experimental::aligned_alloc_shared a| -The USM memory allocation function is a function template `template ` returning `T *`. +The USM memory allocation function is a function template `template ` returning `T *`. | The corresponding USM memory allocation function with `properties` support is a function template -`template` returning `annotated_ptr`. +`template` returning `annotated_ptr`. a| The USM memory allocation funtion is not a function template, and returns `void *`. | -The corresponding USM memory allocation function with `properties` support is a function template: -`template` returning `annotated_ptr`. +The corresponding USM memory allocation function with `properties` support is a function template +`template` returning `annotated_ptr`. +a| +The last parameter of the USM memory allocation function is an optional `const propertyListA &propList = {}`. +| +The last parameter of the corresponding USM memory allocation function with `properties` support is an optional `const propertyListA &propList = {}`. +a| +Zero or more properties can be provided to the allocation function via an instance of property_list. +|Zero or more properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. a| -The last parameter of the USM memory allocation function is an optional `const property_list &propList = {}`. +On failure, returns [code]#nullptr#. | -The last parameter of the corresponding USM memory allocation function with `properties` support is a non-optional `const propertyListT &propList`. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. |==== -The description of every function in this extension contains the following sentences: +The description of every function introduced by this extension contains the following sentence: [options="header"] |==== | Function | Sentences appended to the Description a| any of the functions specified in this extension | -The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + -If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + - -Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. |==== -For every function added by this extension that contains the word "aligned" in its name, its description contains the following additional sentence: +For every function added by this extension that contains the word "aligned" in its name, its description contains the following sentence: [options="header"] |==== | Function | Sentences appended to the Description a| any of the functions specified in this extension that contain "aligned" in their name | -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, its compile-time-constant value must be the same as the value of the `alignment` parameter, otherwise an error will be output by the compiler. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + |==== +[[section.usm.allocs]] +=== USM Memory Allocation Functions with properties Support -==== Example +The following four tables list all functions specified by this extension. -The following example shows two of the functions specified by this extension: -[frame="topbot",options="header"] -|=== -|Functions |Description -a| -[source,c++] +[[section.usm.device.allocs]] +==== Device allocation functions with properties support + +[[table.usm.device.allocs]] +.USM Device Memory Allocation Functions with properties Support +[width="100%",options="header",separator="@",cols="65%,35%"] +|==== +@ Function @ Description +a@ +[source] ---- -template -annotated_ptr -sycl::ext::oneapi::experimental::malloc_device( - size_t count, - const sycl::queue& syclQueue, - const propertyListT &propList) +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) ---- -| -Simplified form where syclQueue -provides the device and context. + +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +success. The allocation size is specified in bytes. This memory is not +accessible on the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_device# +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the +allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a +synchronous [code]#exception# with the [code]#errc::feature_not_supported# +error code if the [code]#syclDevice# does not have +[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be +contained by [code]#syclContext# or it must be a descendent device of some +device that is contained by that context, otherwise this function throws a +synchronous [code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_device(size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +success. The allocation size is specified in number of elements of type +[code]#T#. This memory is not accessible on the host. Memory allocated +by [code]#sycl::ext::oneapi::experimental::malloc_device# must be deallocated with +[code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_device(size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on +the specified [code]#device# with [code]#alignment#-byte alignment on success. +The allocation size is specified in bytes. This memory is not accessible on +the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::aligned_alloc_device# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Devices may only permit certain alignments. Zero or more +properties can be provided to the allocation function via an instance of +[code]#sycl::ext::oneapi::experimental::properties#. Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on +the specified [code]#device# with [code]#alignment#-byte alignment on success. +The allocation size is specified in elements of type [code]#T#. This memory is +not accessible on the host. Memory allocated by +[code]#sycl::ext::oneapi::experimental::aligned_alloc_device# must be deallocated with [code]#sycl::free# +to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Devices may only +permit certain alignments. Zero or more properties can be provided to the +allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a +synchronous [code]#exception# with the [code]#errc::feature_not_supported# +error code if the [code]#syclDevice# does not have +[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be +contained by [code]#syclContext# or it must be a descendent device of some +device that is contained by that context, otherwise this function throws a +synchronous [code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. -Zero or more runtime or compile-time-constant properties can be -provided to the allocation function -via an instance of sycl::ext::oneapi::experimental::properties. + +|==== -Throws a synchronous exception -with the errc::feature_not_supported error code if the device does -not have aspect::usm_device_allocations. + +==== Host allocation functions with properties support -The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + +[[table.usm.host.allocs]] +.USM Host Memory Allocation Functions with properties Support +[width="100%",options="header",separator="@",cols="65%,35%"] +|==== +@ Function @ Description +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in bytes. The allocation is +accessible on the host and devices contained in the specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_host(size_t count, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in number of elements of type [code]#T#. +The allocation is accessible on the host and devices contained in the +specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_host(size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, + size_t numBytes, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in bytes and aligned to the specified +alignment. The allocation is accessible on the host and devices contained +in the specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. On +failure, returns [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, + size_t count, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in elements of type [code]#T# and +aligned to the specified alignment. The allocation is accessible on the +host and devices contained in the specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. On +failure, returns [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. +The properties of the returned annotated_ptr may not be the same as those in propList. -If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. -Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. +|==== -// --- ROW BREAK --- -a| -[source,c++] +==== Shared allocation functions with properties support + +[[table.usm.shared.allocs]] +.USM Shared Memory Allocation Functions with properties Support +[width="100%",options="header",separator="@",cols="65%,35%"] +|==== +@ Function @ Description +a@ +[source] ---- -template -annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc( - size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - usm::alloc kind, - const propertyListT &propList) ----- -| -Returns a kind allocation. This allocation is specified in bytes and -aligned to the specified alignment. -This memory must be deallocated -with sycl::free to avoid memory -leaks. + - -On failure, the raw pointer of the returned annotated_ptr will be nullptr. + - -Zero or more runtime or compile-time-constant properties can be -provided to the allocation function -via an instance of sycl::ext::oneapi::experimental::properties. + - -The syclDevice parameter is -ignored if kind is usm::alloc::host. -If kind is not usm::alloc::host, -syclDevice must either be contained by syclContext or it must be -a descendent device of some -device that is contained by that -context, otherwise this function -throws a synchronous exception -with the errc::invalid error code. + - -The runtime properties and compile-time-constant property values of the returned annotated_ptr will be the same as those in propList. + - -If propList contains the sycl::ext::oneapi::experimental::alignment property, the allocation will be aligned to this specified alignment. + - -Available only if `propertyListT` is a specialization of the sycl::ext::oneapi::experimental::properties class. + - -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, its compile-time-constant value must be the same as the value of the `alignment` parameter, otherwise an error will be output by the compiler. -|=== +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in bytes. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_shared(size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in number of elements of +type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid +memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc_shared(size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in bytes and aligned to the +specified alignment. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in number of elements of type [code]#T# and aligned to the +specified alignment. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +descendent device of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. +|==== + +==== Parameterized allocation functions with properties support + +[[table.usm.param.allocs]] +.USM Parameterized Allocation Functions with properties Support +[width="100%",options="header",separator="@",cols="65%,35%"] +|==== +@ Function @ Description +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc(size_t numBytes, + const device& syclDevice, + const context& syclContext, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation. +This allocation is specified in bytes. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not +[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a descendent device of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc(size_t count, + const device& syclDevice, + const context& syclContext, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation. +This allocation is specified in number of elements of type [code]#T#. +This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not +[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a descendent device of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc(size_t numBytes, + const queue& syclQueue, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The properties of the returned annotated_ptr may not be the same as those in propList. -==== Deallocation +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::malloc(size_t count, + const queue& syclQueue, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The properties of the returned annotated_ptr may not be the same as those in propList. -To avoid memory leaks, USM memory allocated using the USM memory allocation functions with properties support defined in this extension, must be deallocated using one of the `sycl::free` functions listed in Table 107 "USM Deallocation Functions" of Section 4.8.3.6 "Memory deallocation functions" of the core SYCL specification. +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation. +This allocation is specified in bytes and aligned to the +specified alignment. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not +[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a descendent device of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation. +This allocation is specified in number of elements of type [code]#T# and aligned +to the specified alignment. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not +[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a descendent device of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, + size_t numBytes, + const queue& syclQueue, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, + size_t count, + const queue& syclQueue, + usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. +Zero or more properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The properties of the returned annotated_ptr may not be the same as those in propList. + +Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. + +|==== + +=== USM Memory Allocation Properties + +This section specifies the properties that can be passed to the USM memory allocation functions with `properties` support defined in Section <>. +A SYCL implementation or SYCL backend may support additional properties other than those defined here, provided they are defined in accordance with the +link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. +If any other properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. + + +The properties that are valid for USM memory allocation functions with `properties` support are listed in Table <>. +This table also specifies for each supported property, whether or not it will appear on the annotated_ptr object returned by the USM memory allocation function. + +[[table.usm.malloc.properties]] +.Properties supported by the USM memory allocation functions with properties support +[options="header"] +|==== +|Property|Description|Appears on returned annotated_ptr |Source +a| +alignment +| +Sets the alignment of the pointer address in bytes. + +If this property is passed to a USM memory allocation function with a scalar alignment parameter, there must be a positive integer `k` such that the value of the alignment parameter is `k` times the compile-time-constant property value, otherwise the result will be undefined behavior. +| +Yes +| +link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] +|==== + +[NOTE] +==== +Some properties supported by annotated_ptr, including `restrict`, are not supported by the USM memory allocation functions defined in this extension. Intuitively, some properties apply to a pointer but do not apply to the process of allocating memory, and vice versa. +==== + + +=== Deallocation + +To avoid memory leaks, USM memory allocated using the USM memory allocation functions with `properties` support defined in this extension, must be deallocated using one of the `sycl::free` functions listed in Table 107 "USM Deallocation Functions" of Section 4.8.3.6 "Memory deallocation functions" of the core SYCL specification. The following example shows how USM memory allocated using one of the functions defined in this extension should be deallocated, to avoid memory leaks. +==== Example + [source,c++] ---- -sycl::ext::oneapi::experimental::properties P1{bar}; -// APtr is of type annotated_ptr; +sycl::ext::oneapi::experimental::properties P1{alignment<64>}; +// APtr is of type annotated_ptr auto APtr = sycl::ext::oneapi::experimental::malloc_device(N, q, P1); // Deallocate the memory using the raw pointer of APtr From 593f2ddfeeb9c078af2bb232bcb8b7f051794c01 Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Wed, 22 Jun 2022 10:07:20 -0700 Subject: [PATCH 03/16] Add usm_alloc property. Remove APIs that take a runtime alignment. All properties supported by annotated_ptr are supported by malloc. All compile-time and no runtime properties are propagated from malloc to the returned annotated_ptr. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 719 ++++++------------ 1 file changed, 235 insertions(+), 484 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 44d304e57037c..31d74a02b2628 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -84,50 +84,86 @@ and related concepts, types, and mechanisms, and to give examples and context fo == Examples -In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a -runtime property. +This extension introduces a new compile-time constant property `sycl::ext::oneapi::experimental::usm_alloc`, with three possible values: `device`, `host`, and `shared`. +This property will be present on the annotated_ptr returned by the non-parameterized USM memory allocation functions introduced by this extension. + +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; -Properties passed to the USM memory allocation functions with `properties` support, may or may not appear on the returned annotated_ptr object. -In this example, we assume that if the `bar` or `foo` properties are passed to a USM memory allocation function, they will also appear on the returned annotated_ptr. -However, the `baz` property will not appear on the returned annotated_ptr. +// APtr1 is of type annotated_ptr})> +auto APtr1 = malloc_device(N, q, properties{}); + +// APtr2 is of type annotated_ptr})> +auto APtr2 = malloc_host(N, q, properties{}); + +// APtr3 is of type annotated_ptr})> +auto APtr3 = malloc_shared(N, q, properties{}); + +// The properties of the annotated_ptrs are different +static_assert(!std::is_same_v); +static_assert(!std::is_same_v); +static_assert(!std::is_same_v); +---- + +The Parameterized USM memory allocation functions introduced by this extension allow the USM memory allocation kind to be specified at runtime. +Since the USM memory allocation kind is not known at compile-time, the annotated_ptr returned by these functions will not +have a `usm_alloc` property. + +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; + +// APtr1 is of type annotated_ptr +auto APtr1 = malloc(N, q, sycl::usm::alloc::device, properties{}); +---- + + +Additional runtime and compile-time constant properties can be passed to the USM memory allocation functions introduced by this extension. +Properties passed to the USM memory allocation functions may or may not appear on the returned annotated_ptr object: +compile-time constant properties will appear on the annotated_ptr, while runtime properties will not. + +In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a +runtime property. Therefore if `bar` or `baz` is passed to a USM memory allocation function, it will also appear on the returned annotated_ptr. +However, the `foo` property will not appear on the returned annotated_ptr because it is a runtime property. [source,c++] ---- using namespace sycl::ext::oneapi::experimental; properties P1{bar, baz, foo{1}}; -properties P2{bar, baz, foo{2}}; +properties P2{bar, foo{2}}; properties P3{bar, baz} -// APtr1 is of type annotated_ptr +// APtr1 is of type annotated_ptr, bar, baz})> auto APtr1 = malloc_device(N, q, P1); -// APtr2 is of type annotated_ptr +// APtr2 is of type annotated_ptr, bar})> auto APtr2 = malloc_device(N, q, P2); -// APtr3 is of type annotated_ptr +// APtr3 is of type annotated_ptr, bar, baz})> auto APtr3 = malloc_device(N, q, P3); -// Runtime property values do not affect the type of the annotated_ptr -static_assert(std::is_same_v); +// Runtime properties are not present on the returned annotated_ptr +static_assert(std::is_same_v); -// APtr1 and APtr3 do not have the same properties -static_assert(!std::is_same_v); +// APtr1 and APtr2 do not have the same properties +static_assert(!std::is_same_v); ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. -When `alignment` is passed to a USM memory allocation function with `properties` support, it will also appear on the returned annotated_ptr. -If the alignment specified by this property is incompatible with the alignment specified at runtime, the result is undefined behavior. +When `alignment` is passed to a USM memory allocation function with `properties` support, it will also appear on the returned annotated_ptr since it is a compile-time constant property. +It also informs the runtime the memory should be allocated with this alignment. [source,c++] ---- +using namespace sycl::ext::oneapi::experimental; + properties P1{alignment<8>}; -// APtr1 is of type annotated_ptr -auto APtr1 = sycl::ext::oneapi::experimental::aligned_alloc_device(512, N, q, P1); // UB -auto APtr2 = sycl::ext::oneapi::experimental::aligned_alloc_device(4, N, q, P1); // ok +// APtr1 is of type annotated_ptr, alignment<8>})> +auto APtr1 = malloc_device(N, q, P1); ---- - == Specification === Feature test macro @@ -139,7 +175,7 @@ implementation supporting this extension must predefine the macro 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. +the implementation supports. [%header,cols="1,5"] |=== @@ -156,7 +192,7 @@ The core SYCL specification lists eight functions in each of the following four - Table 105 "USM Shared Memory Allocation Functions", of Section 4.8.3.4 "Shared allocation functions" + - Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" -This extension introduces a new function for each function listed in the above tables of the core SYCL specification. +This extension introduces a new function for each function listed in the above tables of the core SYCL specification, except for the USM allocation functions that take an alignment parameter. For the sake of clarity, we first describe how the new functions differ from the corresponding functions in the core SYCL specification. All APIs introduced by this extension are listed explicitly in Section <>. [NOTE] @@ -177,7 +213,7 @@ sycl::ext::oneapi::experimental::malloc a| sycl::aligned_alloc | -sycl::ext::oneapi::experimental::aligned_alloc +This extension does not introduce any corresponding functions. a| sycl::malloc_device + sycl::malloc_host + @@ -191,9 +227,7 @@ sycl::aligned_alloc_device + sycl::aligned_alloc_host + sycl::aligned_alloc_shared | -sycl::ext::oneapi::experimental::aligned_alloc_device + -sycl::ext::oneapi::experimental::aligned_alloc_host + -sycl::ext::oneapi::experimental::aligned_alloc_shared +This extension does not introduce any corresponding functions. a| The USM memory allocation function is a function template `template ` returning `T *`. | @@ -207,10 +241,13 @@ The corresponding USM memory allocation function with `properties` support is a a| The last parameter of the USM memory allocation function is an optional `const propertyListA &propList = {}`. | -The last parameter of the corresponding USM memory allocation function with `properties` support is an optional `const propertyListA &propList = {}`. +The last parameter of the corresponding USM memory allocation function with `properties` support is a non-optional `const propertyListA &propList`. a| -Zero or more properties can be provided to the allocation function via an instance of property_list. -|Zero or more properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of property_list. +| +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. a| On failure, returns [code]#nullptr#. | @@ -224,18 +261,19 @@ The description of every function introduced by this extension contains the foll | Function | Sentences appended to the Description a| any of the functions specified in this extension | - Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. |==== -For every function added by this extension that contains the word "aligned" in its name, its description contains the following sentence: + +The description of every non-parameterized function introduced by this extension contains the following sentence: + [options="header"] |==== | Function | Sentences appended to the Description -a| any of the functions specified in this extension that contain "aligned" in their name +a| +any function specified in this extension that does not take a `usm::alloc` parameter | -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. |==== @@ -261,22 +299,27 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in bytes. This memory is not accessible on the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_device# must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the -allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a + +Zero or more runtime and compile-time constant properties can be provided to the +allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + +Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. a@ @@ -287,7 +330,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_device(size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in number of elements of type @@ -295,8 +338,13 @@ success. The allocation size is specified in number of elements of type by [code]#sycl::ext::oneapi::experimental::malloc_device# must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# @@ -304,7 +352,6 @@ must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. a@ @@ -314,16 +361,20 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -334,124 +385,22 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_device(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on -the specified [code]#device# with [code]#alignment#-byte alignment on success. -The allocation size is specified in bytes. This memory is not accessible on -the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::aligned_alloc_device# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Devices may only permit certain alignments. Zero or more -properties can be provided to the allocation function via an instance of -[code]#sycl::ext::oneapi::experimental::properties#. Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a -descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on -the specified [code]#device# with [code]#alignment#-byte alignment on success. -The allocation size is specified in elements of type [code]#T#. This memory is -not accessible on the host. Memory allocated by -[code]#sycl::ext::oneapi::experimental::aligned_alloc_device# must be deallocated with [code]#sycl::free# -to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Devices may only -permit certain alignments. Zero or more properties can be provided to the -allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a -synchronous [code]#exception# with the [code]#errc::feature_not_supported# -error code if the [code]#syclDevice# does not have -[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be -contained by [code]#syclContext# or it must be a descendent device of some -device that is contained by that context, otherwise this function throws a -synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. -Zero or more properties can be provided to the allocation function +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_device(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. |==== @@ -469,7 +418,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is @@ -477,12 +426,16 @@ accessible on the host and devices contained in the specified [code]#context#. Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -493,7 +446,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_host(size_t count, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on success. This allocation is specified in number of elements of type [code]#T#. @@ -502,12 +455,16 @@ specified [code]#context#. Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -518,15 +475,19 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -537,114 +498,21 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_host(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Only devices that have [code]#aspect::usm_host_allocations# may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, - size_t numBytes, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in bytes and aligned to the specified -alignment. The allocation is accessible on the host and devices contained -in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. On -failure, returns [code]#nullptr#. -Zero or more properties can be provided to the allocation function +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Only devices that have [code]#aspect::usm_host_allocations# may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, - size_t count, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in elements of type [code]#T# and -aligned to the specified alignment. The allocation is accessible on the -host and devices contained in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. On -failure, returns [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Only devices that have [code]#aspect::usm_host_allocations# may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_host(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Only devices that have [code]#aspect::usm_host_allocations# may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. |==== @@ -663,15 +531,20 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# @@ -679,7 +552,6 @@ must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -691,7 +563,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_shared(size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. @@ -699,8 +571,13 @@ This allocation is specified in number of elements of type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# @@ -708,7 +585,6 @@ must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -719,16 +595,20 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -Zero or more properties can be provided to the allocation function + +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. + Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -739,124 +619,22 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc_shared(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. -This allocation is specified in bytes and aligned to the -specified alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a -descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = {}) ----- -a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. -This allocation is specified in number of elements of type [code]#T# and aligned to the -specified alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a -descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc_shared(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. |==== @@ -876,20 +654,22 @@ sycl::ext::oneapi::experimental::malloc(size_t numBytes, const device& syclDevice, const context& syclContext, usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns a [code]#kind# allocation. This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The [code]#syclDevice# parameter is ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not [code]#usm::alloc::host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -902,20 +682,22 @@ sycl::ext::oneapi::experimental::malloc(size_t count, const device& syclDevice, const context& syclContext, usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Returns a [code]#kind# allocation. This allocation is specified in number of elements of type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The [code]#syclDevice# parameter is ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not [code]#usm::alloc::host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -928,13 +710,14 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc(size_t numBytes, const queue& syclQueue, usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Zero or more properties can be provided to the allocation function +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The properties of the returned annotated_ptr may not be the same as those in propList. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. @@ -946,113 +729,56 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::malloc(size_t count, const queue& syclQueue, usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Zero or more properties can be provided to the allocation function +Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The properties of the returned annotated_ptr may not be the same as those in propList. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +|==== + +==== Additional USM Memory Allocation Functions + +This section defines additional USM memory allocation functions with `properties` support, that require a `usm_alloc` property to be passed in. + +[[table.usm.additional.allocs]] +.Additional USM Allocation Functions with properties Support +[width="100%",options="header",separator="@",cols="65%,35%"] +|==== +@ Function @ Description a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - usm::alloc kind, - const propertyListA &propList = {}) +sycl::ext::oneapi::experimental::malloc(size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList) ---- -a@ Returns a [code]#kind# allocation. -This allocation is specified in bytes and aligned to the -specified alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is -ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not -[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a descendent device of some device that -is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - usm::alloc kind, - const propertyListA &propList = {}) ----- -a@ Returns a [code]#kind# allocation. -This allocation is specified in number of elements of type [code]#T# and aligned -to the specified alignment. This memory +The propList must contain a `usm_alloc` property, otherwise the compiler will issue a diagnostic error. +Returns a [code]#usm_alloc# allocation. +This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The [code]#syclDevice# parameter is -ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not -[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of [code]#sycl::ext::oneapi::experimental::properties#. +The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. +Runtime properties in propList will not appear as properties of the returned annotated_ptr. +The [code]#syclDevice# parameter is +ignored if [code]#usm_alloc# is [code]#host#. If [code]#usm_alloc is not +[code]#host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, - size_t numBytes, - const queue& syclQueue, - usm::alloc kind, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The properties of the returned annotated_ptr may not be the same as those in propList. - -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. - -a@ -[source] ----- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::aligned_alloc(size_t alignment, - size_t count, - const queue& syclQueue, - usm::alloc kind, - const propertyListA &propList = {}) ----- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. -Zero or more properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The properties of the returned annotated_ptr may not be the same as those in propList. Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -If the sycl::ext::oneapi::experimental::alignment property is specified in propList, and there is no non-negative integer `k` such that the value of the `alignment` parameter is `k` times the compile-time-constant property value, the result is undefined behavior. |==== @@ -1063,30 +789,55 @@ A SYCL implementation or SYCL backend may support additional properties other th link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. If any other properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. +All properties that are valid for annotated_ptr must be supported by the USM memory allocation functions with `properties` support. +Unless otherwise specified, supported properties do not affect the behavior of the USM memory allocation functions with `properties` support. + +[NOTE] +==== +The USM memory allocation functions defined in this extension support all properties supported by annotated_ptr, as a convenience. This allows the user to attach all desired properties to the annotated_ptr in a single step. +These properties do not affect the behavior of the allocation functions, except where explicitly specified. +==== -The properties that are valid for USM memory allocation functions with `properties` support are listed in Table <>. -This table also specifies for each supported property, whether or not it will appear on the annotated_ptr object returned by the USM memory allocation function. +Table <> lists properties that do affect the behavior of the allocation functions. [[table.usm.malloc.properties]] -.Properties supported by the USM memory allocation functions with properties support +.Properties that affect the behavior of the USM memory allocation functions with properties support [options="header"] |==== -|Property|Description|Appears on returned annotated_ptr |Source +|Property|Description|Source a| alignment | -Sets the alignment of the pointer address in bytes. + -If this property is passed to a USM memory allocation function with a scalar alignment parameter, there must be a positive integer `k` such that the value of the alignment parameter is `k` times the compile-time-constant property value, otherwise the result will be undefined behavior. -| -Yes +Instructs the runtime to allocate memory starting at an address with this alignment in bytes. +The address of the raw pointer belonging to the annotated_ptr returned by the USM memory allocation function will have this alignment in bytes. + | link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] |==== -[NOTE] -==== -Some properties supported by annotated_ptr, including `restrict`, are not supported by the USM memory allocation functions defined in this extension. Intuitively, some properties apply to a pointer but do not apply to the process of allocating memory, and vice versa. -==== +Table <> lists the new properties introduced by this extension. +The `usm_alloc` property is supported by annotated_ptr, and therefore by the USM memory allocation functions defined in this extension. +This property will always appear on the annotated_ptr returned by the USM memory allocation functions defined in this extension that do not have a `usm::alloc` parameter. +The `usm_alloc` property may also be passed to the USM memory allocation functions defined in this extension. +If the USM memory allocation kind specified by a function's `usm::alloc` parameter is different from the `usm_alloc` property, the result is undefined behavior. +If the USM memory allocation function does not have a `usm::alloc` parameter, and the property's value conflicts with the kind of memory allocated by the function, the compiler will issue a diagnostic error. + +[[table.usm.malloc.devhostsh]] +.New compile-time constant properties introduced by this extension +[options="header"] +|==== +|Property|Values|Description +a| +usm_alloc +| +host +device +shared +| +Indicates the type of USM memory accessed by dereferencing this pointer and pointers derived from this pointer. +Instructs the runtime to allocate USM memory of this kind. +If a USM memory allocation kind is also specified by `usm::alloc` the two kinds must be the same, otherwise the result is undefined behavior. +If this property is passed to a USM memory allocation function that allocates a different kind of memory, the compiler will issue a diagnostic error. +|==== === Deallocation @@ -1100,7 +851,7 @@ The following example shows how USM memory allocated using one of the functions [source,c++] ---- sycl::ext::oneapi::experimental::properties P1{alignment<64>}; -// APtr is of type annotated_ptr +// APtr is of type annotated_ptr, alignment<64>})> auto APtr = sycl::ext::oneapi::experimental::malloc_device(N, q, P1); // Deallocate the memory using the raw pointer of APtr @@ -1114,5 +865,5 @@ sycl::free(APtr.get(), q); [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-06-09|Jessica Davies|*Initial public working draft* +|1|2022-06-22|Jessica Davies|*Initial public working draft* |======================================== From 1d667a4588754520249c5fcf0b3cb54f3b089901 Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Wed, 22 Jun 2022 10:58:13 -0700 Subject: [PATCH 04/16] Small fixes. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 31d74a02b2628..54979a8b0c327 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -41,7 +41,7 @@ Michael Kinsner, Intel + Aditi Kumaraswamy, Intel + Gregory Lueck, Intel + John Pennycook, Intel + -Roland Schulz, Intel +Roland Schulz, Intel + Jason Sewall, Intel + Abhishek Tiwari, Intel + Sherry Yuan, Intel @@ -79,13 +79,13 @@ proposed `sycl::ext::oneapi::experimental::annotated_ptr` class. We also use the shortened form `properties` to refer to the `sycl::ext::oneapi::experimental::properties` class. ==== -The purpose of this document is to clearly describe and specify USM memory allocation functions with compile-time-constant properties support, +The purpose of this document is to clearly describe and specify USM memory allocation functions with `properties` support, and related concepts, types, and mechanisms, and to give examples and context for their usage. == Examples This extension introduces a new compile-time constant property `sycl::ext::oneapi::experimental::usm_alloc`, with three possible values: `device`, `host`, and `shared`. -This property will be present on the annotated_ptr returned by the non-parameterized USM memory allocation functions introduced by this extension. +This property will be present on the annotated_ptr returned by some of the USM memory allocation functions introduced by this extension, i.e., when the type of USM memory allocated is known at compile-time. [source,c++] ---- @@ -193,6 +193,8 @@ The core SYCL specification lists eight functions in each of the following four - Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" This extension introduces a new function for each function listed in the above tables of the core SYCL specification, except for the USM allocation functions that take an alignment parameter. +This extension introduces additional USM memory allocation functions with `properties` support that do not correspond to a function in the core SYCL specification. +These additional functions require the user to pass in the new `usm_alloc` property. For the sake of clarity, we first describe how the new functions differ from the corresponding functions in the core SYCL specification. All APIs introduced by this extension are listed explicitly in Section <>. [NOTE] @@ -243,7 +245,7 @@ The last parameter of the USM memory allocation function is an optional `const p | The last parameter of the corresponding USM memory allocation function with `properties` support is a non-optional `const propertyListA &propList`. a| -Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of property_list. +Zero or more properties can be provided to the allocation function via an instance of property_list. | Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. @@ -254,7 +256,7 @@ On failure, returns [code]#nullptr#. On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. |==== -The description of every function introduced by this extension contains the following sentence: +The descriptions of functions introduced by this extension contain the following sentences: [options="header"] |==== @@ -262,25 +264,16 @@ The description of every function introduced by this extension contains the foll a| any of the functions specified in this extension | Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -|==== - - -The description of every non-parameterized function introduced by this extension contains the following sentence: - -[options="header"] -|==== -| Function | Sentences appended to the Description a| any function specified in this extension that does not take a `usm::alloc` parameter | The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. |==== - [[section.usm.allocs]] === USM Memory Allocation Functions with properties Support -The following four tables list all functions specified by this extension. +The following five tables list all functions specified by this extension. [[section.usm.device.allocs]] @@ -742,12 +735,17 @@ Available only if `propertyListA` and `propertyListB` are specializations of the |==== -==== Additional USM Memory Allocation Functions +==== USM Memory Allocation Functions Requiring usm_alloc This section defines additional USM memory allocation functions with `properties` support, that require a `usm_alloc` property to be passed in. +[NOTE] +==== +Unlike the functions defined in the first four tables, the functions defined in this section do not correspond to any functions in the core SYCL specification. +==== + [[table.usm.additional.allocs]] -.Additional USM Allocation Functions with properties Support +.USM Allocation Functions Requiring usm_alloc [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -772,7 +770,7 @@ via an instance of [code]#sycl::ext::oneapi::experimental::properties#. The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. Runtime properties in propList will not appear as properties of the returned annotated_ptr. The [code]#syclDevice# parameter is -ignored if [code]#usm_alloc# is [code]#host#. If [code]#usm_alloc is not +ignored if [code]#usm_alloc# is [code]#host#. If [code]#usm_alloc# is not [code]#host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous @@ -784,7 +782,7 @@ Available only if `propertyListA` and `propertyListB` are specializations of the === USM Memory Allocation Properties -This section specifies the properties that can be passed to the USM memory allocation functions with `properties` support defined in Section <>. +This section specifies the properties that can be passed to the USM memory allocation functions defined in Section <>. A SYCL implementation or SYCL backend may support additional properties other than those defined here, provided they are defined in accordance with the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. If any other properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. From d312c6a6292973511ad95c256a4d2ab7c71fdffc Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Thu, 7 Jul 2022 09:00:52 -0700 Subject: [PATCH 05/16] Add annotated_ prefix to all function names. Add the usm_kind property on the annotated_ptr by default. Add support for specifying alignment and allocation kind at runtime. Provide additional functions that require the usm_kind property. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 1209 ++++++++++++----- 1 file changed, 905 insertions(+), 304 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 54979a8b0c327..58b3bdbe428c1 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -1,4 +1,3 @@ -= sycl_ext_oneapi_usm_malloc_properties :source-highlighter: coderay :coderay-linenums-mode: table @@ -39,6 +38,7 @@ Jessica Davies, Intel + Joe Garvey, Intel + Michael Kinsner, Intel + Aditi Kumaraswamy, Intel + +Steffen Larsen, Intel + Gregory Lueck, Intel + John Pennycook, Intel + Roland Schulz, Intel + @@ -70,7 +70,8 @@ not rely on APIs defined in this specification.* This extension introduces USM memory allocation functions with support for compile-time-constant and runtime properties, as defined in the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. The USM memory allocation functions introduced by this extension take a `properties` object as a parameter, and return an `annotated_ptr`. This allows both runtime and compile-time-constant properties to be specified when allocating USM memory. -Furthermore, the annotated_ptr returned by the USM memory allocation functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. +Furthermore, the `annotated_ptr` returned by the USM memory allocation functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. +This extension also introduces a new compile-time constant property `sycl::ext::oneapi::experimental::usm_kind`, whose single parameter is a value from the enumeration `sycl::usm::alloc`. [NOTE] ==== @@ -84,84 +85,144 @@ and related concepts, types, and mechanisms, and to give examples and context fo == Examples -This extension introduces a new compile-time constant property `sycl::ext::oneapi::experimental::usm_alloc`, with three possible values: `device`, `host`, and `shared`. -This property will be present on the annotated_ptr returned by some of the USM memory allocation functions introduced by this extension, i.e., when the type of USM memory allocated is known at compile-time. +Runtime and compile-time constant properties can be passed to the USM memory allocation functions introduced by this extension. +Properties passed to an allocation function may or may not appear on the returned `annotated_ptr` object: +compile-time constant properties will appear on the `annotated_ptr`, while runtime properties will not. + +In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a +runtime property. Therefore if `bar` or `baz` is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr`. +However, the `foo` property will not appear on the returned `annotated_ptr` because it is a runtime property. + [source,c++] ---- using namespace sycl::ext::oneapi::experimental; -// APtr1 is of type annotated_ptr})> -auto APtr1 = malloc_device(N, q, properties{}); +properties P1{bar, baz, foo{1}}; +properties P2{bar, foo{1}}; +properties P3{bar, baz} + +// APtr1 is of type annotated_ptr})> +auto APtr1 = annotated_malloc_device(N, q, P1); + +// APtr2 is of type annotated_ptr})> +auto APtr2 = annotated_malloc_device(N, q, P2); -// APtr2 is of type annotated_ptr})> -auto APtr2 = malloc_host(N, q, properties{}); +// APtr3 is of type annotated_ptr})> +auto APtr3 = annotated_malloc_device(N, q, P3); -// APtr3 is of type annotated_ptr})> -auto APtr3 = malloc_shared(N, q, properties{}); +// Runtime properties are not present on the returned annotated_ptr +static_assert(std::is_same_v); -// The properties of the annotated_ptrs are different +// APtr1 and APtr2 do not have the same properties static_assert(!std::is_same_v); -static_assert(!std::is_same_v); -static_assert(!std::is_same_v); ---- -The Parameterized USM memory allocation functions introduced by this extension allow the USM memory allocation kind to be specified at runtime. -Since the USM memory allocation kind is not known at compile-time, the annotated_ptr returned by these functions will not -have a `usm_alloc` property. - +If the USM memory allocation kind is known at compile-time, the compile-time-constant property `sycl::ext::oneapi::experimental::usm_kind` will also appear on the returned `annotated_ptr`. + [source,c++] ---- using namespace sycl::ext::oneapi::experimental; -// APtr1 is of type annotated_ptr -auto APtr1 = malloc(N, q, sycl::usm::alloc::device, properties{}); +// APtr4 is of type annotated_ptr})> +auto APtr4 = annotated_malloc_device(N, q, properties{}); + +// APtr5 is of type annotated_ptr})> +auto APtr5 = annotated_malloc_host(N, q, properties{}); + +// APtr6 is of type annotated_ptr})> +auto APtr6 = annotated_malloc_shared(N, q, properties{}); + +static_assert(!std::is_same_v); +static_assert(!std::is_same_v); +static_assert(!std::is_same_v); ---- +This extension also introduces USM memory allocation functions with `properties` support that allow the USM memory allocation kind to be specified at runtime. +In this case, the returned `annotated_ptr` will not have the `sycl::ext::oneapi::experimental::usm_kind` property (unless that property is also passed in). -Additional runtime and compile-time constant properties can be passed to the USM memory allocation functions introduced by this extension. -Properties passed to the USM memory allocation functions may or may not appear on the returned annotated_ptr object: -compile-time constant properties will appear on the annotated_ptr, while runtime properties will not. +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; -In the following examples, `bar` and `baz` are compile-time-constant properties, while `foo` is a -runtime property. Therefore if `bar` or `baz` is passed to a USM memory allocation function, it will also appear on the returned annotated_ptr. -However, the `foo` property will not appear on the returned annotated_ptr because it is a runtime property. +properties P4{bar, foo{1}}; + +// APtr7 is of type annotated_ptr +auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); + +---- + +If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the USM memory allocation kind specified by the property takes precedence. [source,c++] ---- using namespace sycl::ext::oneapi::experimental; -properties P1{bar, baz, foo{1}}; -properties P2{bar, foo{2}}; -properties P3{bar, baz} +properties P6{usm_kind}; -// APtr1 is of type annotated_ptr, bar, baz})> -auto APtr1 = malloc_device(N, q, P1); +// The memory allocated will be of kind sycl::usm::alloc::device +auto APtr10 = annotated_malloc(N, q, sycl::usm::alloc::host, P6); -// APtr2 is of type annotated_ptr, bar})> -auto APtr2 = malloc_device(N, q, P2); +---- -// APtr3 is of type annotated_ptr, bar, baz})> -auto APtr3 = malloc_device(N, q, P3); -// Runtime properties are not present on the returned annotated_ptr -static_assert(std::is_same_v); +If the `sycl::ext::oneapi::experimental::usm_kind` property specifies a different USM memory allocation kind than the function supports, the compiler will issue a diagnostic error. -// APtr1 and APtr2 do not have the same properties -static_assert(!std::is_same_v); +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; + +properties P7{usm_kind}; + +auto APtr11 = annotated_malloc_host(N, q, P7); // Error ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. -When `alignment` is passed to a USM memory allocation function with `properties` support, it will also appear on the returned annotated_ptr since it is a compile-time constant property. -It also informs the runtime the memory should be allocated with this alignment. +When `alignment` is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr` since it is a compile-time constant property. +It also informs the runtime to allocate the memory with this alignment. [source,c++] ---- using namespace sycl::ext::oneapi::experimental; -properties P1{alignment<8>}; -// APtr1 is of type annotated_ptr, alignment<8>})> -auto APtr1 = malloc_device(N, q, P1); +properties P8{alignment<512>}; +// APtr12 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr12 is aligned to 512 bytes +auto APtr12 = annotated_malloc_device(N, q, P8); + +properties P9{alignment<1>}; +// Allocate N integers. +// Alignment must be at least sizeof(int) bytes. +auto APtr13 = annotated_malloc_device(N, q, P9); // Error + +properties P10{alignment<64>}; +// Allocate 512 bytes. +// Alignment must be at least 512 bytes. +auto APtr14 = annotated_malloc_device(512, q, P10); // Exception +---- + +This extension also introduces USM memory allocation functions with `properties` support that allow alignment to be specified at runtime, using a separate parameter of type `size_t`. +If the compile-time constant `alignment` property is also passed in, it takes precedence over the alignment specified by the parameter of type `size_t`. + +[source,c++] +---- +using namespace sycl::ext::oneapi::experimental; + +properties P11{alignment<64>} + +// All four of the following allocations are 64-byte aligned + +// APtr15 is of type annotated_ptr})> +auto APtr15 = annotated_aligned_alloc_device(N, q, 64); + +// APtr16 is of type annotated_ptr, usm_kind})> +auto APtr16 = annotated_aligned_alloc_device(N, q, 64, P11); + +// APtr17 is of type annotated_ptr, usm_kind})> +auto APtr17 = annotated_aligned_alloc_device(N, q, 128, P11); + +// APtr18 is of type annotated_ptr, usm_kind})> +auto APtr18 = annotated_aligned_alloc_device(N, q, 16, P11); ---- == Specification @@ -192,90 +253,23 @@ The core SYCL specification lists eight functions in each of the following four - Table 105 "USM Shared Memory Allocation Functions", of Section 4.8.3.4 "Shared allocation functions" + - Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" -This extension introduces a new function for each function listed in the above tables of the core SYCL specification, except for the USM allocation functions that take an alignment parameter. -This extension introduces additional USM memory allocation functions with `properties` support that do not correspond to a function in the core SYCL specification. -These additional functions require the user to pass in the new `usm_alloc` property. -For the sake of clarity, we first describe how the new functions differ from the corresponding functions in the core SYCL specification. All APIs introduced by this extension are listed explicitly in Section <>. +This extension introduces a new function for each function listed in the above tables of the core SYCL specification. +This extension also adds USM memory allocation functions with `properties` support that require the `sycl::ext::oneapi::experimental::usm_kind` property, +and these do not correspond to any functions in the core SYCL specification. +All USM memory allocation functions introduced by this extension are listed explicitly in Section <>. [NOTE] ==== The USM memory allocation functions defined in the core SYCL specification can be used in the same program as the USM memory allocation functions with `properties` support defined in this extension. +The new functions are distinguished by their names having the `annotated_` prefix. ==== -The following table lists phrases which appear in the the above tables of the core SYCL specification, and how they are replaced to generate the corresponding tables in this extension. -The parameters of each function introduced by this extension are the same as the parameters of the corresponding function in the core SYCL specification, except for the last parameter `propList`. - -[options="header"] -|==== -| Core SYCL | USM memory allocation functions with `properties` support -a| -sycl::malloc -| -sycl::ext::oneapi::experimental::malloc -a| -sycl::aligned_alloc -| -This extension does not introduce any corresponding functions. -a| -sycl::malloc_device + -sycl::malloc_host + -sycl::malloc_shared -| -sycl::ext::oneapi::experimental::malloc_device + -sycl::ext::oneapi::experimental::malloc_host + -sycl::ext::oneapi::experimental::malloc_shared -a| -sycl::aligned_alloc_device + -sycl::aligned_alloc_host + -sycl::aligned_alloc_shared -| -This extension does not introduce any corresponding functions. -a| -The USM memory allocation function is a function template `template ` returning `T *`. -| -The corresponding USM memory allocation function with `properties` support is a function template -`template` returning `annotated_ptr`. -a| -The USM memory allocation funtion is not a function template, and returns `void *`. -| -The corresponding USM memory allocation function with `properties` support is a function template -`template` returning `annotated_ptr`. -a| -The last parameter of the USM memory allocation function is an optional `const propertyListA &propList = {}`. -| -The last parameter of the corresponding USM memory allocation function with `properties` support is a non-optional `const propertyListA &propList`. -a| -Zero or more properties can be provided to the allocation function via an instance of property_list. -| -Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of sycl::ext::oneapi::experimental::properties. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -a| -On failure, returns [code]#nullptr#. -| -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -|==== - -The descriptions of functions introduced by this extension contain the following sentences: - -[options="header"] -|==== -| Function | Sentences appended to the Description -a| any of the functions specified in this extension -| -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. -a| -any function specified in this extension that does not take a `usm::alloc` parameter -| -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. -|==== - [[section.usm.allocs]] === USM Memory Allocation Functions with properties Support - -The following five tables list all functions specified by this extension. +The following five tables list all functions introduced by this extension. +TODO: How is propertyListB going to be inferred? Do we need support for getting the type of a properties list with only the compile-time properties, and also adding a new compile-time property? [[section.usm.device.allocs]] ==== Device allocation functions with properties support @@ -289,22 +283,22 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList) +sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) ---- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in bytes. This memory is not -accessible on the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_device# +accessible on the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_device# must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the -allocation function via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +allocation function via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# @@ -313,30 +307,31 @@ error code if the [code]#syclDevice# does not have contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_device(size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList) +sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) ---- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in number of elements of type [code]#T#. This memory is not accessible on the host. Memory allocated -by [code]#sycl::ext::oneapi::experimental::malloc_device# must be deallocated with +by [code]#sycl::ext::oneapi::experimental::annotated_malloc_device# must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# @@ -345,55 +340,188 @@ must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_device(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_device(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on +the specified [code]#device# on success. The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. +The allocation size is specified in bytes. This memory is not accessible on +the host. Memory allocated by [code]#annotated_aligned_alloc_device# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Devices may only permit certain alignments. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +<> of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on +the specified [code]#device# on success. The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +The allocation size is specified in elements of type [code]#T#. This memory is +not accessible on the host. Memory allocated by +[code]#annotated_aligned_alloc_device# must be deallocated with [code]#sycl::free# +to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +Devices may only permit certain alignments. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a +synchronous [code]#exception# with the [code]#errc::feature_not_supported# +error code if the [code]#syclDevice# does not have +[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be +contained by [code]#syclContext# or it must be a <> of some +device that is contained by that context, otherwise this function throws a +synchronous [code]#exception# with the [code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# +and [code]#context#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +a compile-time constant `alignment` property specifying a different alignment. + + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_device_allocations#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== @@ -409,103 +537,223 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, const context& syclContext, - const propertyListA &propList) + const propertyListA &propList = {}) ---- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is accessible on the host and devices contained in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_host# must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_host(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const context& syclContext, - const propertyListA &propList) + const propertyListA &propList = {}) ---- -a@ Returns an annotated_ptr containing a raw pointer to the newly allocated host memory on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in number of elements of type [code]#T#. The allocation is accessible on the host and devices contained in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::malloc_host# must be +Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_host# must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_host(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_host(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, + size_t numBytes, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in bytes. The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +The allocation is accessible on the host and devices contained +in the specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_aligned_malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + + +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, + size_t count, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on +success. This allocation is specified in elements of type [code]#T#. The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. +The allocation is accessible on the +host and devices contained in the specified [code]#context#. +Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_aligned_malloc_host# must be +deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Only devices that have [code]#aspect::usm_host_allocations# may access the +memory allocated by this function. Attempting to access the memory from +a device that does not have the aspect results in undefined behavior. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + |==== @@ -521,22 +769,22 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. This allocation is specified in bytes. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# @@ -546,30 +794,30 @@ descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_shared(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. This allocation is specified in number of elements of type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the [code]#syclDevice# @@ -579,55 +827,187 @@ descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_shared(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc_shared(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const queue& syclQueue, - const propertyListA &propList) + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. -The returned annotated_ptr will also have the `usm_alloc` property, indicating the type of USM memory allocated. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in bytes. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +<> of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = {}) +---- +a@ Returns a shared allocation that is accessible on the host and +on [code]#syclDevice#. +This allocation is specified in number of elements of type [code]#T#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the [code]#syclDevice# +does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# +must either be contained by [code]#syclContext# or it must be a +<> of some device that is contained by that context, +otherwise this function throws a synchronous [code]#exception# with the +[code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#device# and +[code]#context#. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +The returned `annotated_ptr` will have the property `usm_kind`. + +Throws a synchronous [code]#exception# with the +[code]#errc::feature_not_supported# error code if the device +does not have [code]#aspect::usm_shared_allocations#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== @@ -643,56 +1023,61 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, const device& syclDevice, const context& syclContext, - usm::alloc kind, - const propertyListA &propList) + sycl::usm::alloc kind, + const propertyListA &propList = {}) ---- -a@ Returns a [code]#kind# allocation. +a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + The [code]#syclDevice# parameter is -ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not -[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const device& syclDevice, const context& syclContext, - usm::alloc kind, - const propertyListA &propList) + sycl::usm::alloc kind, + const propertyListA &propList = {}) ---- -a@ Returns a [code]#kind# allocation. +a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + This allocation is specified in number of elements of type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + The [code]#syclDevice# parameter is -ignored if [code]#kind# is [code]#usm::alloc::host#. If [code]#kind# is not -[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -700,52 +1085,187 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc(size_t numBytes, +sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, const queue& syclQueue, - usm::alloc kind, - const propertyListA &propList) + sycl::usm::alloc kind, + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. +Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc(size_t count, +sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const queue& syclQueue, - usm::alloc kind, - const propertyListA &propList) + sycl::usm::alloc kind, + const propertyListA &propList = {}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. + +Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +This allocation is specified in bytes. +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. + +The [code]#syclDevice# parameter is +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a <> of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +This allocation is specified in number of elements of type [code]#T#. +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + + + +The [code]#syclDevice# parameter is +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a <> of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, + size_t numBytes, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. + +Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, + size_t count, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = {}) +---- +a@ Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. + +Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + +The memory will have [code]#alignment#-byte alignment unless `propList` contains +the compile-time constant `alignment` property specifying a different alignment. + +Zero or more runtime and compile-time constant properties can be provided to the allocation function +via an instance of `properties`. +The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== -==== USM Memory Allocation Functions Requiring usm_alloc +==== Additional USM memory allocation functions, requiring the usm_kind property -This section defines additional USM memory allocation functions with `properties` support, that require a `usm_alloc` property to be passed in. +This section defines additional USM memory allocation functions with `properties` support, that require the `sycl::ext::oneapi::experimental::usm_kind` property to be passed in. +These functions do not correspond to any USM memory allocation functions in the core SYCL specification. [NOTE] ==== -Unlike the functions defined in the first four tables, the functions defined in this section do not correspond to any functions in the core SYCL specification. +The `properties` argument is non-optional for the functions defined in this section, since at least one property (i.e., `sycl::ext::oneapi::experimental::usm_kind`) must be provided. +These functions are distinguished from the functions with the same names in Table <>, by the presence or absence of the parameter of type `sycl::usm::alloc`. + ==== [[table.usm.additional.allocs]] -.USM Allocation Functions Requiring usm_alloc +.USM allocation functions requiring the usm_kind property [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -754,49 +1274,125 @@ a@ ---- template sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::malloc(size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList) +sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList) ---- -a@ -The propList must contain a `usm_alloc` property, otherwise the compiler will issue a diagnostic error. -Returns a [code]#usm_alloc# allocation. +a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. +Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned annotated_ptr will be [code]#nullptr#. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of [code]#sycl::ext::oneapi::experimental::properties#. -The compile-time constant properties in propList will also appear as properties of the returned annotated_ptr. -Runtime properties in propList will not appear as properties of the returned annotated_ptr. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Additional runtime and compile-time constant properties can be provided in `propList`. +The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + The [code]#syclDevice# parameter is -ignored if [code]#usm_alloc# is [code]#host#. If [code]#usm_alloc# is not -[code]#host#, [code]#syclDevice# must either be contained by +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_malloc(size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList) +---- +a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. +Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. +This allocation is specified in number of elements of type [code]#T#. +This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Additional runtime and compile-time constant properties can be provided in `propList`. +The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + +The [code]#syclDevice# parameter is +ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not +[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by +[code]#syclContext# or it must be a descendent device of some device that +is contained by that context, otherwise this function throws a synchronous +[code]#exception# with the [code]#errc::invalid# error code. +Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. + + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, + const queue& syclQueue, + const propertyListA &propList) +---- +a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. +Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. +This allocation is specified in bytes. This memory +must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Additional runtime and compile-time constant properties can be provided in `propList`. +The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + +Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. + +a@ +[source] +---- +template +sycl::ext::oneapi::experimental::annotated_ptr +sycl::ext::oneapi::experimental::annotated_malloc(size_t count, + const queue& syclQueue, + const propertyListA &propList) +---- +a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. +Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. +This allocation is specified in number of elements of type [code]#T#. +This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. + +Additional runtime and compile-time constant properties can be provided in `propList`. +The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. +Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. + +Simplified form where [code]#syclQueue# provides the [code]#context# +and any necessary [code]#device#. + +Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. -Available only if `propertyListA` and `propertyListB` are specializations of the sycl::ext::oneapi::experimental::properties class. |==== -=== USM Memory Allocation Properties +=== USM Memory Allocation Properties -This section specifies the properties that can be passed to the USM memory allocation functions defined in Section <>. +This section specifies the properties that can be passed to the USM memory allocation functions with `properties` support defined in Section <>. A SYCL implementation or SYCL backend may support additional properties other than those defined here, provided they are defined in accordance with the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. -If any other properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. +If unsupported properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. -All properties that are valid for annotated_ptr must be supported by the USM memory allocation functions with `properties` support. -Unless otherwise specified, supported properties do not affect the behavior of the USM memory allocation functions with `properties` support. +All properties supported by `annotated_ptr` are supported by the USM memory allocation functions with `properties` support. [NOTE] ==== -The USM memory allocation functions defined in this extension support all properties supported by annotated_ptr, as a convenience. This allows the user to attach all desired properties to the annotated_ptr in a single step. -These properties do not affect the behavior of the allocation functions, except where explicitly specified. +The USM memory allocation functions with `properties` support defined in this extension support all properties supported by `annotated_ptr`, as a convenience. This allows the user to attach all desired properties to the `annotated_ptr` in a single step. +These properties do not affect the behavior of the allocation functions at runtime, except where explicitly specified. ==== -Table <> lists properties that do affect the behavior of the allocation functions. +Table <> lists properties that affect the behavior of the allocation functions. [[table.usm.malloc.properties]] .Properties that affect the behavior of the USM memory allocation functions with properties support @@ -806,39 +1402,42 @@ Table <> lists properties that do affect the behavi a| alignment | -Instructs the runtime to allocate memory starting at an address with this alignment in bytes. -The address of the raw pointer belonging to the annotated_ptr returned by the USM memory allocation function will have this alignment in bytes. + +If this property is present on an `annotated_ptr`, it indicates that the raw pointer has this alignment in bytes. +If this property is passed to a USM memory allocation function with `properties` support, it instructs the runtime to allocate memory with this alignment in bytes. +If the USM memory allocation function with `properties` support is templated on an allocation type `T` and the specified alignment is not suitable for an object of type `T` the compiler will issue a diagnostic error. +If the USM memory allocation function with `properties` support is not templated on an allocation type `T`, and the specified alignment is not suitable for objects with fundamental alignment whose size is less than or equal to the requested allocation size, the USM memory allocation function with `properties` support will throw a synchronous exception with the `errc:invalid` error code. | link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] |==== Table <> lists the new properties introduced by this extension. -The `usm_alloc` property is supported by annotated_ptr, and therefore by the USM memory allocation functions defined in this extension. -This property will always appear on the annotated_ptr returned by the USM memory allocation functions defined in this extension that do not have a `usm::alloc` parameter. -The `usm_alloc` property may also be passed to the USM memory allocation functions defined in this extension. -If the USM memory allocation kind specified by a function's `usm::alloc` parameter is different from the `usm_alloc` property, the result is undefined behavior. -If the USM memory allocation function does not have a `usm::alloc` parameter, and the property's value conflicts with the kind of memory allocated by the function, the compiler will issue a diagnostic error. [[table.usm.malloc.devhostsh]] -.New compile-time constant properties introduced by this extension +.New compile-time constant properties introduced by this extension [options="header"] |==== -|Property|Values|Description +|Property|Values|Description|Supported By a| -usm_alloc +sycl::ext::oneapi::experimental::usm_kind | -host -device -shared +sycl::usm::alloc::host +sycl::usm::alloc::device +sycl::usm::alloc::shared | -Indicates the type of USM memory accessed by dereferencing this pointer and pointers derived from this pointer. +Indicates the kind of USM memory accessed by dereferencing this pointer and pointers derived from this pointer. Instructs the runtime to allocate USM memory of this kind. -If a USM memory allocation kind is also specified by `usm::alloc` the two kinds must be the same, otherwise the result is undefined behavior. -If this property is passed to a USM memory allocation function that allocates a different kind of memory, the compiler will issue a diagnostic error. +| +`annotated_ptr`, + +and the USM memory allocation functions with `properties` support defined in this extension. |==== -=== Deallocation +The `sycl::ext::oneapi::experimental::usm_kind` property is a compile-time constant property with a single non-type parameter. This parameter is a value belonging to the enumeration `sycl::usm::alloc`. +The `sycl::ext::oneapi::experimental::usm_kind` property is supported by `annotated_ptr` and the USM memory allocation functions defined in this extension. +If a USM memory allocation kind is also specified by a parameter of type `sycl::usm::alloc`, the kind specified by the `sycl::ext::oneapi::experimental::usm_alloc` property takes precedence. +If the USM memory allocation function with `properties` support does not have a parameter of type `sycl::usm::alloc`, and the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property passed to the function is different than the kind of memory allocated by the function, the compiler will issue a diagnostic error. + +=== Deallocation To avoid memory leaks, USM memory allocated using the USM memory allocation functions with `properties` support defined in this extension, must be deallocated using one of the `sycl::free` functions listed in Table 107 "USM Deallocation Functions" of Section 4.8.3.6 "Memory deallocation functions" of the core SYCL specification. @@ -848,9 +1447,11 @@ The following example shows how USM memory allocated using one of the functions [source,c++] ---- -sycl::ext::oneapi::experimental::properties P1{alignment<64>}; -// APtr is of type annotated_ptr, alignment<64>})> -auto APtr = sycl::ext::oneapi::experimental::malloc_device(N, q, P1); +using namespace sycl::ext::oneapi::experimental; + +properties P1{alignment<512>}; +// APtr is of type annotated_ptr, usm_kind})> +auto APtr = annotated_malloc_device(N, q, P1); // Deallocate the memory using the raw pointer of APtr sycl::free(APtr.get(), q); @@ -863,5 +1464,5 @@ sycl::free(APtr.get(), q); [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-06-22|Jessica Davies|*Initial public working draft* +|1|2022-07-18|Jessica Davies|*Initial public working draft* |======================================== From 431c7131403f350fc2533a14c8ce1710c3e1b95c Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Mon, 24 Oct 2022 11:24:17 -0700 Subject: [PATCH 06/16] Conflicting alignments or allocation kinds now cause exceptions. Fixed default argument syntax for propList. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 232 ++++++++++-------- 1 file changed, 136 insertions(+), 96 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 58b3bdbe428c1..cdf0ccac8a779 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -125,13 +125,13 @@ If the USM memory allocation kind is known at compile-time, the compile-time-con using namespace sycl::ext::oneapi::experimental; // APtr4 is of type annotated_ptr})> -auto APtr4 = annotated_malloc_device(N, q, properties{}); +auto APtr4 = annotated_malloc_device(N, q); // APtr5 is of type annotated_ptr})> -auto APtr5 = annotated_malloc_host(N, q, properties{}); +auto APtr5 = annotated_malloc_host(N, q); // APtr6 is of type annotated_ptr})> -auto APtr6 = annotated_malloc_shared(N, q, properties{}); +auto APtr6 = annotated_malloc_shared(N, q); static_assert(!std::is_same_v); static_assert(!std::is_same_v); @@ -152,7 +152,8 @@ auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); ---- -If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the USM memory allocation kind specified by the property takes precedence. +If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the function throws a +synchronous [code]#exception# with the [code]#errc::invalid# error code. [source,c++] ---- @@ -160,7 +161,7 @@ using namespace sycl::ext::oneapi::experimental; properties P6{usm_kind}; -// The memory allocated will be of kind sycl::usm::alloc::device +// Throws an exception with error code errc::invalid auto APtr10 = annotated_malloc(N, q, sycl::usm::alloc::host, P6); ---- @@ -191,18 +192,15 @@ properties P8{alignment<512>}; auto APtr12 = annotated_malloc_device(N, q, P8); properties P9{alignment<1>}; -// Allocate N integers. -// Alignment must be at least sizeof(int) bytes. -auto APtr13 = annotated_malloc_device(N, q, P9); // Error +auto APtr13 = annotated_malloc_device(N, q, P9); // Error: alignment must be at least sizeof(int) bytes properties P10{alignment<64>}; -// Allocate 512 bytes. -// Alignment must be at least 512 bytes. -auto APtr14 = annotated_malloc_device(512, q, P10); // Exception +auto APtr14 = annotated_malloc_device(512, q, P10); // Exception: alignment must be at least 512 bytes ---- This extension also introduces USM memory allocation functions with `properties` support that allow alignment to be specified at runtime, using a separate parameter of type `size_t`. -If the compile-time constant `alignment` property is also passed in, it takes precedence over the alignment specified by the parameter of type `size_t`. +If the compile-time constant `alignment` property is also passed in, the value of alignment it specifies must be equal to the alignment specified by the parameter of type `size_t`, otherwise +a synchronous exception will be thrown with error code `errc::invalid`. [source,c++] ---- @@ -218,10 +216,10 @@ auto APtr15 = annotated_aligned_alloc_device(N, q, 64); // APtr16 is of type annotated_ptr, usm_kind})> auto APtr16 = annotated_aligned_alloc_device(N, q, 64, P11); -// APtr17 is of type annotated_ptr, usm_kind})> +// Exception, different alignments auto APtr17 = annotated_aligned_alloc_device(N, q, 128, P11); -// APtr18 is of type annotated_ptr, usm_kind})> +// Exception, different alignments auto APtr18 = annotated_aligned_alloc_device(N, q, 16, P11); ---- @@ -286,7 +284,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in bytes. This memory is not @@ -318,7 +316,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on success. The allocation size is specified in number of elements of type @@ -340,6 +338,7 @@ must either be contained by [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -349,7 +348,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. @@ -373,7 +372,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. @@ -399,11 +398,11 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified [code]#device# on success. The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +the specified [code]#device# on success. +The memory will have [code]#alignment#-byte alignment. The allocation size is specified in bytes. This memory is not accessible on the host. Memory allocated by [code]#annotated_aligned_alloc_device# must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -425,6 +424,9 @@ must either be contained by [code]#syclContext# or it must be a otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -436,11 +438,11 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified [code]#device# on success. The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +the specified [code]#device# on success. +The memory will have [code]#alignment#-byte alignment. The allocation size is specified in elements of type [code]#T#. This memory is not accessible on the host. Memory allocated by @@ -463,6 +465,9 @@ contained by [code]#syclContext# or it must be a <> of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -473,13 +478,12 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -492,6 +496,9 @@ Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -502,14 +509,12 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -a compile-time constant `alignment` property specifying a different alignment. - +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -521,6 +526,9 @@ Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== @@ -539,7 +547,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is @@ -567,7 +575,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in number of elements of type [code]#T#. @@ -596,7 +604,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. @@ -619,7 +627,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. @@ -643,11 +651,10 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, size_t numBytes, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in bytes. The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +success. This allocation is specified in bytes. The memory will have [code]#alignment#-byte alignment. The allocation is accessible on the host and devices contained in the specified [code]#context#. @@ -661,11 +668,13 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. - Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -676,11 +685,10 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, size_t count, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in elements of type [code]#T#. The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +success. This allocation is specified in elements of type [code]#T#. The memory will have [code]#alignment#-byte alignment. The allocation is accessible on the host and devices contained in the specified [code]#context#. Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_aligned_malloc_host# must be @@ -697,6 +705,9 @@ Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -707,12 +718,11 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -724,6 +734,9 @@ Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -734,12 +747,11 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -747,11 +759,13 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. - Only devices that have [code]#aspect::usm_host_allocations# may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -772,7 +786,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. @@ -804,7 +818,7 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. @@ -836,7 +850,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. @@ -860,7 +874,7 @@ template sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. @@ -886,14 +900,13 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment size_t numBytes, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. This allocation is specified in bytes. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -913,6 +926,9 @@ must either be contained by [code]#syclContext# or it must be a otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -924,14 +940,13 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment size_t count, const device& syclDevice, const context& syclContext, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on [code]#syclDevice#. This allocation is specified in number of elements of type [code]#T#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -951,6 +966,9 @@ must either be contained by [code]#syclContext# or it must be a otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -961,13 +979,12 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, size_t numBytes, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -979,6 +996,9 @@ Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -989,13 +1009,12 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, size_t count, const queue& syclQueue, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#device# and [code]#context#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1007,6 +1026,9 @@ Throws a synchronous [code]#exception# with the [code]#errc::feature_not_supported# error code if the device does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== @@ -1027,9 +1049,9 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, const device& syclDevice, const context& syclContext, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +a@ Returns a [code]#kind# allocation. This allocation is specified in bytes. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. @@ -1046,6 +1068,8 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1057,9 +1081,9 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const device& syclDevice, const context& syclContext, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +a@ Returns a [code]#kind# allocation. This allocation is specified in number of elements of type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -1077,6 +1101,8 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1088,17 +1114,19 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, const queue& syclQueue, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Returns a [code]#kind# allocation. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1109,18 +1137,20 @@ sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const queue& syclQueue, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Returns a [code]#kind# allocation. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1133,12 +1163,11 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, const device& syclDevice, const context& syclContext, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +a@ Returns a [code]#kind# allocation. This allocation is specified in bytes. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -1157,6 +1186,11 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1169,12 +1203,11 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, const device& syclDevice, const context& syclContext, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +a@ Returns a [code]#kind# allocation. This allocation is specified in number of elements of type [code]#T#. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. @@ -1185,8 +1218,6 @@ via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - - The [code]#syclDevice# parameter is ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not [code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by @@ -1194,6 +1225,10 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1205,21 +1240,23 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, size_t numBytes, const queue& syclQueue, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Returns a [code]#kind# allocation. -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1232,21 +1269,22 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, size_t count, const queue& syclQueue, sycl::usm::alloc kind, - const propertyListA &propList = {}) + const propertyListA &propList = properties{}) ---- a@ Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Returns a [code]#kind# allocation, unless `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. - -The memory will have [code]#alignment#-byte alignment unless `propList` contains -the compile-time constant `alignment` property specifying a different alignment. +Returns a [code]#kind# allocation. +The memory will have [code]#alignment#-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1295,7 +1333,8 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] @@ -1323,7 +1362,8 @@ ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the alloca [code]#syclContext# or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous [code]#exception# with the [code]#errc::invalid# error code. -Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. + +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ @@ -1348,7 +1388,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] @@ -1372,7 +1412,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` Simplified form where [code]#syclQueue# provides the [code]#context# and any necessary [code]#device#. -Available only if `propertyListA` and `propertyListB` are specializations of the `sycl::ext::oneapi::experimental::properties` class. +Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== From 03923f41bf7bbaaa62f517c2d986bd83373f6967 Mon Sep 17 00:00:00 2001 From: Jessica Davies Date: Tue, 25 Oct 2022 10:45:26 -0700 Subject: [PATCH 07/16] Remove use of code role. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 515 +++++++++--------- 1 file changed, 259 insertions(+), 256 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index cdf0ccac8a779..57bd5e5fb81d4 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -150,10 +150,13 @@ properties P4{bar, foo{1}}; // APtr7 is of type annotated_ptr auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); +// TODO: no properties but still returns an annotated_ptr seems odd +// APtrNone is of type annotated_ptr; +auto APtrNone = annotated_malloc(N, q, sycl::usm::alloc::device); ---- If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the function throws a -synchronous [code]#exception# with the [code]#errc::invalid# error code. +synchronous exception with the `errc::invalid` error code. [source,c++] ---- @@ -286,11 +289,11 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in bytes. This memory is not -accessible on the host. Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_device# -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +accessible on the host. Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_device` +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -299,12 +302,12 @@ Runtime properties in `propList` will not appear as properties of the returned ` The returned `annotated_ptr` will have the property `usm_kind`. Throws a -synchronous [code]#exception# with the [code]#errc::feature_not_supported# -error code if the [code]#syclDevice# does not have -[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be -contained by [code]#syclContext# or it must be a descendent device of some +synchronous `exception` with the `errc::feature_not_supported` +error code if the `syclDevice` does not have +`aspect::usm_device_allocations`. The `syclDevice` must either be +contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a -synchronous [code]#exception# with the [code]#errc::invalid# error code. +synchronous `exception` with the `errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -318,12 +321,12 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on [code]#syclDevice# on +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in number of elements of type -[code]#T#. This memory is not accessible on the host. Memory allocated -by [code]#sycl::ext::oneapi::experimental::annotated_malloc_device# must be deallocated with -[code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +`T`. This memory is not accessible on the host. Memory allocated +by `sycl::ext::oneapi::experimental::annotated_malloc_device` must be deallocated with +`sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -331,13 +334,13 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_device_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -350,8 +353,8 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. +a@ Simplified form where `syclQueue` provides the `device` +and `context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -359,9 +362,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_device_allocations`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -374,8 +377,8 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. +a@ Simplified form where `syclQueue` provides the `device` +and `context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -383,9 +386,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_device_allocations`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -401,12 +404,12 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified [code]#device# on success. -The memory will have [code]#alignment#-byte alignment. +the specified `device` on success. +The memory will have `alignment`-byte alignment. The allocation size is specified in bytes. This memory is not accessible on -the host. Memory allocated by [code]#annotated_aligned_alloc_device# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +the host. Memory allocated by `annotated_aligned_alloc_device` must be +deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Devices may only permit certain alignments. @@ -416,15 +419,15 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_device_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_device_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a <> of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -441,14 +444,14 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified [code]#device# on success. -The memory will have [code]#alignment#-byte alignment. +the specified `device` on success. +The memory will have `alignment`-byte alignment. -The allocation size is specified in elements of type [code]#T#. This memory is +The allocation size is specified in elements of type `T`. This memory is not accessible on the host. Memory allocated by -[code]#annotated_aligned_alloc_device# must be deallocated with [code]#sycl::free# +`annotated_aligned_alloc_device` must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Devices may only permit certain alignments. Zero or more runtime and compile-time constant properties can be provided to the allocation function @@ -458,14 +461,14 @@ Runtime properties in `propList` will not appear as properties of the returned ` The returned `annotated_ptr` will have the property `usm_kind`. Throws a -synchronous [code]#exception# with the [code]#errc::feature_not_supported# -error code if the [code]#syclDevice# does not have -[code]#aspect::usm_device_allocations#. The [code]#syclDevice# must either be -contained by [code]#syclContext# or it must be a <> of some +synchronous `exception` with the `errc::feature_not_supported` +error code if the `syclDevice` does not have +`aspect::usm_device_allocations`. The `syclDevice` must either be +contained by `syclContext` or it must be a <> of some device that is contained by that context, otherwise this function throws a -synchronous [code]#exception# with the [code]#errc::invalid# error code. +synchronous `exception` with the `errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -480,10 +483,10 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. +a@ Simplified form where `syclQueue` provides the `device` +and `context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -492,11 +495,11 @@ Runtime properties in `propList` will not appear as properties of the returned ` The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_device_allocations`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -511,10 +514,10 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# -and [code]#context#. +a@ Simplified form where `syclQueue` provides the `device` +and `context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -522,11 +525,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_device_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_device_allocations`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -551,10 +554,10 @@ sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is -accessible on the host and devices contained in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +accessible on the host and devices contained in the specified `context`. +Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_host` must be +deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -562,7 +565,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. @@ -578,12 +581,12 @@ sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in number of elements of type [code]#T#. +success. This allocation is specified in number of elements of type `T`. The allocation is accessible on the host and devices contained in the -specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +specified `context`. +Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_host` must be +deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -591,7 +594,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. @@ -606,7 +609,7 @@ sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +a@ Simplified form where `syclQueue` provides the `context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -614,7 +617,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. @@ -629,7 +632,7 @@ sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +a@ Simplified form where `syclQueue` provides the `context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -637,7 +640,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. @@ -654,13 +657,13 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in bytes. The memory will have [code]#alignment#-byte alignment. +success. This allocation is specified in bytes. The memory will have `alignment`-byte alignment. The allocation is accessible on the host and devices contained -in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_aligned_malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +in the specified `context`. +Memory allocated by `sycl::ext::oneapi::experimental::annotated_aligned_malloc_host` must be +deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -668,11 +671,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -688,12 +691,12 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in elements of type [code]#T#. The memory will have [code]#alignment#-byte alignment. +success. This allocation is specified in elements of type `T`. The memory will have `alignment`-byte alignment. The allocation is accessible on the -host and devices contained in the specified [code]#context#. -Memory allocated by [code]#sycl::ext::oneapi::experimental::annotated_aligned_malloc_host# must be -deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +host and devices contained in the specified `context`. +Memory allocated by `sycl::ext::oneapi::experimental::annotated_aligned_malloc_host` must be +deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -701,11 +704,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -720,9 +723,9 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +a@ Simplified form where `syclQueue` provides the `context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -730,11 +733,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -749,9 +752,9 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context#. +a@ Simplified form where `syclQueue` provides the `context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -759,11 +762,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have [code]#aspect::usm_host_allocations# may access the +Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -789,10 +792,10 @@ sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. +on `syclDevice`. This allocation is specified in bytes. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -800,13 +803,13 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_shared_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -821,11 +824,11 @@ sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. +on `syclDevice`. This allocation is specified in number of elements of -type [code]#T#. This memory must be deallocated with [code]#sycl::free# to avoid +type `T`. This memory must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -833,13 +836,13 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_shared_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -852,8 +855,8 @@ sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. +a@ Simplified form where `syclQueue` provides the `device` and +`context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -861,9 +864,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_shared_allocations`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -876,8 +879,8 @@ sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. +a@ Simplified form where `syclQueue` provides the `device` and +`context`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -885,9 +888,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_shared_allocations`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -903,14 +906,14 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. +on `syclDevice`. This allocation is specified in bytes. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -918,15 +921,15 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_shared_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a <> of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -943,14 +946,14 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and -on [code]#syclDevice#. -This allocation is specified in number of elements of type [code]#T#. +on `syclDevice`. +This allocation is specified in number of elements of type `T`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -958,15 +961,15 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the [code]#syclDevice# -does not have [code]#aspect::usm_shared_allocations#. The [code]#syclDevice# -must either be contained by [code]#syclContext# or it must be a +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the `syclDevice` +does not have `aspect::usm_shared_allocations`. The `syclDevice` +must either be contained by `syclContext` or it must be a <> of some device that is contained by that context, -otherwise this function throws a synchronous [code]#exception# with the -[code]#errc::invalid# error code. +otherwise this function throws a synchronous `exception` with the +`errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -981,10 +984,10 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. +a@ Simplified form where `syclQueue` provides the `device` and +`context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -992,11 +995,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_shared_allocations`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1011,10 +1014,10 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment const queue& syclQueue, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#device# and -[code]#context#. +a@ Simplified form where `syclQueue` provides the `device` and +`context`. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1022,11 +1025,11 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Throws a synchronous [code]#exception# with the -[code]#errc::feature_not_supported# error code if the device -does not have [code]#aspect::usm_shared_allocations#. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if the device +does not have `aspect::usm_shared_allocations`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1051,24 +1054,24 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation. +a@ Returns a `kind` allocation. This allocation is specified in bytes. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a descendent device of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1083,25 +1086,25 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t count, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation. +a@ Returns a `kind` allocation. -This allocation is specified in number of elements of type [code]#T#. -This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +This allocation is specified in number of elements of type `T`. +This memory must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a descendent device of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1116,16 +1119,16 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. -Returns a [code]#kind# allocation. +a@ Simplified form where `syclQueue` provides the `context` +and any necessary `device`. +Returns a `kind` allocation. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1139,17 +1142,17 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t count, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. +a@ Simplified form where `syclQueue` provides the `context` +and any necessary `device`. -Returns a [code]#kind# allocation. +Returns a `kind` allocation. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1165,13 +1168,13 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation. +a@ Returns a `kind` allocation. This allocation is specified in bytes. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1179,15 +1182,15 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a <> of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a <> of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. @@ -1205,28 +1208,28 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a [code]#kind# allocation. -This allocation is specified in number of elements of type [code]#T#. -The memory will have [code]#alignment#-byte alignment. +a@ Returns a `kind` allocation. +This allocation is specified in number of elements of type `T`. +The memory will have `alignment`-byte alignment. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a <> of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a <> of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1242,20 +1245,20 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. +a@ Simplified form where `syclQueue` provides the `context` +and any necessary `device`. -Returns a [code]#kind# allocation. +Returns a `kind` allocation. -The memory will have [code]#alignment#-byte alignment. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1271,19 +1274,19 @@ sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. +a@ Simplified form where `syclQueue` provides the `context` +and any necessary `device`. -Returns a [code]#kind# allocation. -The memory will have [code]#alignment#-byte alignment. +Returns a `kind` allocation. +The memory will have `alignment`-byte alignment. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous [code]#exception# with the [code]#errc::invalid# error code if `propList` contains an `alignment` property specifying a different +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different alignment. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1320,19 +1323,19 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. This allocation is specified in bytes. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a descendent device of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1348,20 +1351,20 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t count, ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. -This allocation is specified in number of elements of type [code]#T#. -This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +This allocation is specified in number of elements of type `T`. +This memory must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The [code]#syclDevice# parameter is -ignored if the allocation kind is [code]#sycl::usm::alloc::host#. If the allocation kind is not -[code]#sycl::usm::alloc::host#, [code]#syclDevice# must either be contained by -[code]#syclContext# or it must be a descendent device of some device that +The `syclDevice` parameter is +ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous -[code]#exception# with the [code]#errc::invalid# error code. +`exception` with the `errc::invalid` error code. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1378,15 +1381,15 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. This allocation is specified in bytes. This memory -must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. +Simplified form where `syclQueue` provides the `context` +and any necessary `device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1401,16 +1404,16 @@ sycl::ext::oneapi::experimental::annotated_malloc(size_t count, ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. -This allocation is specified in number of elements of type [code]#T#. -This memory must be deallocated with [code]#sycl::free# to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be [code]#nullptr#. +This allocation is specified in number of elements of type `T`. +This memory must be deallocated with `sycl::free` to avoid memory leaks. +On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -Simplified form where [code]#syclQueue# provides the [code]#context# -and any necessary [code]#device#. +Simplified form where `syclQueue` provides the `context` +and any necessary `device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. From 36034222033653f1350eaaec7024813cd33d4b24 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Mon, 7 Nov 2022 10:01:10 -0800 Subject: [PATCH 08/16] Cleanup and corrections. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 157 ++++++++---------- 1 file changed, 66 insertions(+), 91 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 57bd5e5fb81d4..25c4c86e5ad09 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -1,24 +1,8 @@ +:sectnums: -:source-highlighter: coderay -:coderay-linenums-mode: table += `sycl_ext_oneapi_usm_malloc_properties` -// 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} - -// This is necessary for asciidoc, but not for asciidoctor -:cpp: C++ -:dpcpp: DPC++ +:dpcpp: pass:[DPC++] == Notice @@ -71,6 +55,7 @@ This extension introduces USM memory allocation functions with support for compi The USM memory allocation functions introduced by this extension take a `properties` object as a parameter, and return an `annotated_ptr`. This allows both runtime and compile-time-constant properties to be specified when allocating USM memory. Furthermore, the `annotated_ptr` returned by the USM memory allocation functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. + This extension also introduces a new compile-time constant property `sycl::ext::oneapi::experimental::usm_kind`, whose single parameter is a value from the enumeration `sycl::usm::alloc`. [NOTE] @@ -93,6 +78,7 @@ In the following examples, `bar` and `baz` are compile-time-constant properties, runtime property. Therefore if `bar` or `baz` is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr`. However, the `foo` property will not appear on the returned `annotated_ptr` because it is a runtime property. +If the USM memory allocation kind is known at compile-time, the compile-time-constant property `sycl::ext::oneapi::experimental::usm_kind` will also appear on the returned `annotated_ptr`. [source,c++] ---- @@ -116,26 +102,15 @@ static_assert(std::is_same_v); // APtr1 and APtr2 do not have the same properties static_assert(!std::is_same_v); ----- - -If the USM memory allocation kind is known at compile-time, the compile-time-constant property `sycl::ext::oneapi::experimental::usm_kind` will also appear on the returned `annotated_ptr`. -[source,c++] ----- -using namespace sycl::ext::oneapi::experimental; +// APtr4 is of type annotated_ptr})> +auto APtr4 = annotated_malloc_host(N, q); -// APtr4 is of type annotated_ptr})> -auto APtr4 = annotated_malloc_device(N, q); - -// APtr5 is of type annotated_ptr})> -auto APtr5 = annotated_malloc_host(N, q); - -// APtr6 is of type annotated_ptr})> -auto APtr6 = annotated_malloc_shared(N, q); +// APtr5 is of type annotated_ptr})> +auto APtr5 = annotated_malloc_shared(N, q); +// The USM kinds differ static_assert(!std::is_same_v); -static_assert(!std::is_same_v); -static_assert(!std::is_same_v); ---- This extension also introduces USM memory allocation functions with `properties` support that allow the USM memory allocation kind to be specified at runtime. @@ -147,12 +122,12 @@ using namespace sycl::ext::oneapi::experimental; properties P4{bar, foo{1}}; -// APtr7 is of type annotated_ptr -auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); +// APtr6 is of type annotated_ptr +auto APtr6 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); // TODO: no properties but still returns an annotated_ptr seems odd -// APtrNone is of type annotated_ptr; -auto APtrNone = annotated_malloc(N, q, sycl::usm::alloc::device); +// APtr7 is of type annotated_ptr; +auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device); ---- If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the function throws a @@ -162,10 +137,10 @@ synchronous exception with the `errc::invalid` error code. ---- using namespace sycl::ext::oneapi::experimental; -properties P6{usm_kind}; +properties P5{usm_kind}; // Throws an exception with error code errc::invalid -auto APtr10 = annotated_malloc(N, q, sycl::usm::alloc::host, P6); +auto APtr8 = annotated_malloc(N, q, sycl::usm::alloc::host, P5); ---- @@ -176,9 +151,9 @@ If the `sycl::ext::oneapi::experimental::usm_kind` property specifies a differen ---- using namespace sycl::ext::oneapi::experimental; -properties P7{usm_kind}; +properties P6{usm_kind}; -auto APtr11 = annotated_malloc_host(N, q, P7); // Error +auto APtr9 = annotated_malloc_host(N, q, P6); // Error, USM kinds do not agree ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. @@ -189,16 +164,16 @@ It also informs the runtime to allocate the memory with this alignment. ---- using namespace sycl::ext::oneapi::experimental; -properties P8{alignment<512>}; -// APtr12 is of type annotated_ptr, usm_kind})> -// The raw pointer of APtr12 is aligned to 512 bytes -auto APtr12 = annotated_malloc_device(N, q, P8); +properties P7{alignment<512>}; +// APtr10 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr10 is aligned to 512 bytes +auto APtr10 = annotated_malloc_device(N, q, P7); -properties P9{alignment<1>}; -auto APtr13 = annotated_malloc_device(N, q, P9); // Error: alignment must be at least sizeof(int) bytes +properties P8{alignment<1>}; +auto APtr11 = annotated_malloc_device(N, q, P8); // Error: alignment must be at least sizeof(int) bytes -properties P10{alignment<64>}; -auto APtr14 = annotated_malloc_device(512, q, P10); // Exception: alignment must be at least 512 bytes +properties P9{alignment<64>}; +auto APtr12 = annotated_malloc_device(512, q, P9); // Exception: alignment must be at least 512 bytes ---- This extension also introduces USM memory allocation functions with `properties` support that allow alignment to be specified at runtime, using a separate parameter of type `size_t`. @@ -209,21 +184,21 @@ a synchronous exception will be thrown with error code `errc::invalid`. ---- using namespace sycl::ext::oneapi::experimental; -properties P11{alignment<64>} +properties P10{alignment<64>} // All four of the following allocations are 64-byte aligned -// APtr15 is of type annotated_ptr})> -auto APtr15 = annotated_aligned_alloc_device(N, q, 64); +// APtr13 is of type annotated_ptr})> +auto APtr13 = annotated_aligned_alloc_device(N, q, 64); -// APtr16 is of type annotated_ptr, usm_kind})> -auto APtr16 = annotated_aligned_alloc_device(N, q, 64, P11); +// APtr14 is of type annotated_ptr, usm_kind})> +auto APtr14 = annotated_aligned_alloc_device(N, q, 64, P10); // Exception, different alignments -auto APtr17 = annotated_aligned_alloc_device(N, q, 128, P11); +auto APtr15 = annotated_aligned_alloc_device(N, q, 128, P10); // Exception, different alignments -auto APtr18 = annotated_aligned_alloc_device(N, q, 16, P11); +auto APtr16 = annotated_aligned_alloc_device(N, q, 16, P10); ---- == Specification @@ -291,7 +266,7 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in bytes. This memory is not -accessible on the host. Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_device` +accessible on the host. Memory allocated by `annotated_malloc_device` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -324,7 +299,7 @@ sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in number of elements of type `T`. This memory is not accessible on the host. Memory allocated -by `sycl::ext::oneapi::experimental::annotated_malloc_device` must be deallocated with +by `annotated_malloc_device` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -428,7 +403,7 @@ otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -469,7 +444,7 @@ device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -500,7 +475,7 @@ Throws a synchronous `exception` with the does not have `aspect::usm_device_allocations`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -530,7 +505,7 @@ Throws a synchronous `exception` with the does not have `aspect::usm_device_allocations`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -555,7 +530,7 @@ sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_host` must be +Memory allocated by `annotated_malloc_host` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -584,7 +559,7 @@ a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated ho success. This allocation is specified in number of elements of type `T`. The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `sycl::ext::oneapi::experimental::annotated_malloc_host` must be +Memory allocated by `annotated_malloc_host` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -661,7 +636,7 @@ success. This allocation is specified in bytes. The memory will have `alignment` The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `sycl::ext::oneapi::experimental::annotated_aligned_malloc_host` must be +Memory allocated by `annotated_aligned_malloc_host` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -676,7 +651,7 @@ memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -694,7 +669,7 @@ a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated ho success. This allocation is specified in elements of type `T`. The memory will have `alignment`-byte alignment. The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `sycl::ext::oneapi::experimental::annotated_aligned_malloc_host` must be +Memory allocated by `annotated_aligned_malloc_host` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -709,7 +684,8 @@ memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -738,7 +714,7 @@ memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -767,7 +743,7 @@ memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -930,7 +906,7 @@ otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -970,7 +946,7 @@ otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1000,7 +976,7 @@ Throws a synchronous `exception` with the does not have `aspect::usm_shared_allocations`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1030,7 +1006,7 @@ Throws a synchronous `exception` with the does not have `aspect::usm_shared_allocations`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1038,6 +1014,8 @@ Available only if `propertyListA` and `propertyListB` are specializations of the ==== Parameterized allocation functions with properties support +TODO: should the properties argument be non-optional here? + [[table.usm.param.allocs]] .USM Parameterized Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] @@ -1190,9 +1168,9 @@ is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1230,7 +1208,7 @@ is contained by that context, otherwise this function throws a synchronous Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1259,7 +1237,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1287,7 +1265,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment. +alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1342,8 +1320,8 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr +template +sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const device& syclDevice, const context& syclContext, @@ -1396,8 +1374,8 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr +template +sycl::ext::oneapi::experimental::annotated_ptr sycl::ext::oneapi::experimental::annotated_malloc(size_t count, const queue& syclQueue, const propertyListA &propList) @@ -1427,12 +1405,12 @@ A SYCL implementation or SYCL backend may support additional properties other th link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. If unsupported properties are passed to the USM memory allocation functions with `properties` support, the compiler will issue a diagnostic error. -All properties supported by `annotated_ptr` are supported by the USM memory allocation functions with `properties` support. +All properties supported by `annotated_ptr` are supported by the USM memory allocation functions with `properties` support. These properties do not affect the behavior of the allocation functions at runtime, except where explicitly specified. + [NOTE] ==== The USM memory allocation functions with `properties` support defined in this extension support all properties supported by `annotated_ptr`, as a convenience. This allows the user to attach all desired properties to the `annotated_ptr` in a single step. -These properties do not affect the behavior of the allocation functions at runtime, except where explicitly specified. ==== Table <> lists properties that affect the behavior of the allocation functions. @@ -1445,7 +1423,6 @@ Table <> lists properties that affect the behavior a| alignment | -If this property is present on an `annotated_ptr`, it indicates that the raw pointer has this alignment in bytes. If this property is passed to a USM memory allocation function with `properties` support, it instructs the runtime to allocate memory with this alignment in bytes. If the USM memory allocation function with `properties` support is templated on an allocation type `T` and the specified alignment is not suitable for an object of type `T` the compiler will issue a diagnostic error. If the USM memory allocation function with `properties` support is not templated on an allocation type `T`, and the specified alignment is not suitable for objects with fundamental alignment whose size is less than or equal to the requested allocation size, the USM memory allocation function with `properties` support will throw a synchronous exception with the `errc:invalid` error code. @@ -1477,8 +1454,6 @@ and the USM memory allocation functions with `properties` support defined in thi The `sycl::ext::oneapi::experimental::usm_kind` property is a compile-time constant property with a single non-type parameter. This parameter is a value belonging to the enumeration `sycl::usm::alloc`. The `sycl::ext::oneapi::experimental::usm_kind` property is supported by `annotated_ptr` and the USM memory allocation functions defined in this extension. -If a USM memory allocation kind is also specified by a parameter of type `sycl::usm::alloc`, the kind specified by the `sycl::ext::oneapi::experimental::usm_alloc` property takes precedence. -If the USM memory allocation function with `properties` support does not have a parameter of type `sycl::usm::alloc`, and the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property passed to the function is different than the kind of memory allocated by the function, the compiler will issue a diagnostic error. === Deallocation @@ -1507,5 +1482,5 @@ sycl::free(APtr.get(), q); [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-07-18|Jessica Davies|*Initial public working draft* +|1|2022-11-07|Jessica Davies|*Initial public working draft* |======================================== From 6acb364b0e9a7bd187436f11d90d9b933e42e168 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Thu, 15 Dec 2022 12:08:52 -0800 Subject: [PATCH 09/16] Remove exceptions for differing alignments. Format the code in the tables. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 685 ++++++++++-------- 1 file changed, 392 insertions(+), 293 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 25c4c86e5ad09..756a69065ac1e 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -32,7 +32,7 @@ Sherry Yuan, Intel == Dependencies -This extension is written against the SYCL 2020 specification, revision 5. +This extension is written against the SYCL 2020 specification, revision 6. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision. @@ -52,7 +52,7 @@ not rely on APIs defined in this specification.* == Overview This extension introduces USM memory allocation functions with support for compile-time-constant and runtime properties, as defined in the link:../experimental/sycl_ext_oneapi_properties.asciidoc[sycl_ext_oneapi_properties] extension. -The USM memory allocation functions introduced by this extension take a `properties` object as a parameter, and return an `annotated_ptr`. +The USM memory allocation functions introduced by this extension take a `properties` object as a (possibly optional) parameter, and return an `annotated_ptr`. This allows both runtime and compile-time-constant properties to be specified when allocating USM memory. Furthermore, the `annotated_ptr` returned by the USM memory allocation functions allows compile-time-constant information to propagate to the device compiler and thereby enable additional optimization of kernel code. @@ -88,13 +88,13 @@ properties P1{bar, baz, foo{1}}; properties P2{bar, foo{1}}; properties P3{bar, baz} -// APtr1 is of type annotated_ptr})> +// APtr1 is of type annotated_ptr})> auto APtr1 = annotated_malloc_device(N, q, P1); -// APtr2 is of type annotated_ptr})> +// APtr2 is of type annotated_ptr})> auto APtr2 = annotated_malloc_device(N, q, P2); -// APtr3 is of type annotated_ptr})> +// APtr3 is of type annotated_ptr})> auto APtr3 = annotated_malloc_device(N, q, P3); // Runtime properties are not present on the returned annotated_ptr @@ -103,10 +103,10 @@ static_assert(std::is_same_v); // APtr1 and APtr2 do not have the same properties static_assert(!std::is_same_v); -// APtr4 is of type annotated_ptr})> +// APtr4 is of type annotated_ptr})> auto APtr4 = annotated_malloc_host(N, q); -// APtr5 is of type annotated_ptr})> +// APtr5 is of type annotated_ptr})> auto APtr5 = annotated_malloc_shared(N, q); // The USM kinds differ @@ -122,16 +122,16 @@ using namespace sycl::ext::oneapi::experimental; properties P4{bar, foo{1}}; -// APtr6 is of type annotated_ptr +// APtr6 is of type annotated_ptr auto APtr6 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); -// TODO: no properties but still returns an annotated_ptr seems odd -// APtr7 is of type annotated_ptr; +// APtr7 is of type annotated_ptr; auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device); ---- If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the function throws a -synchronous exception with the `errc::invalid` error code. +synchronous exception with the `errc::invalid` error code. +If the `sycl::ext::oneapi::experimental::usm_kind` property specifies a different USM memory allocation kind than the function supports, the compiler will issue a diagnostic error. [source,c++] ---- @@ -142,63 +142,65 @@ properties P5{usm_kind}; // Throws an exception with error code errc::invalid auto APtr8 = annotated_malloc(N, q, sycl::usm::alloc::host, P5); ----- - - -If the `sycl::ext::oneapi::experimental::usm_kind` property specifies a different USM memory allocation kind than the function supports, the compiler will issue a diagnostic error. - -[source,c++] ----- -using namespace sycl::ext::oneapi::experimental; - -properties P6{usm_kind}; - -auto APtr9 = annotated_malloc_host(N, q, P6); // Error, USM kinds do not agree +// Error: the USM kinds do not agree +auto APtr9 = annotated_malloc_host(N, q, P5); ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. When `alignment` is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr` since it is a compile-time constant property. It also informs the runtime to allocate the memory with this alignment. - + [source,c++] ---- using namespace sycl::ext::oneapi::experimental; properties P7{alignment<512>}; +properties P8{alignment<1>}; +properties P9{alignment<64>}; + // APtr10 is of type annotated_ptr, usm_kind})> -// The raw pointer of APtr10 is aligned to 512 bytes +// The raw pointer of APtr10 is 512-byte aligned auto APtr10 = annotated_malloc_device(N, q, P7); -properties P8{alignment<1>}; -auto APtr11 = annotated_malloc_device(N, q, P8); // Error: alignment must be at least sizeof(int) bytes +// APtr11 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr11 is sizeof(int)-byte aligned +auto APtr11 = annotated_malloc_device(N, q, P8); -properties P9{alignment<64>}; -auto APtr12 = annotated_malloc_device(512, q, P9); // Exception: alignment must be at least 512 bytes +// APtr12 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr12 is 512-byte aligned +auto APtr12 = annotated_malloc_device(512, q, P9); ---- This extension also introduces USM memory allocation functions with `properties` support that allow alignment to be specified at runtime, using a separate parameter of type `size_t`. -If the compile-time constant `alignment` property is also passed in, the value of alignment it specifies must be equal to the alignment specified by the parameter of type `size_t`, otherwise -a synchronous exception will be thrown with error code `errc::invalid`. +If the parameter of type `size_t` has value `A` and the compile-time constant `alignment` property has value `B`, the resulting pointer will be both `A`-byte aligned and `B`-byte aligned, as well as `C`-byte aligned, +where `C` is the least common multiple of `A` and `B`. [source,c++] ---- using namespace sycl::ext::oneapi::experimental; -properties P10{alignment<64>} - -// All four of the following allocations are 64-byte aligned +properties P10{alignment<64>}; +properties P11{alignment<8>}; // APtr13 is of type annotated_ptr})> -auto APtr13 = annotated_aligned_alloc_device(N, q, 64); +// The raw pointer of APtr13 is 64-byte aligned +auto APtr13 = annotated_aligned_alloc_device(N, q, 64 /* alignment */); // APtr14 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr14 is 64-byte aligned auto APtr14 = annotated_aligned_alloc_device(N, q, 64, P10); -// Exception, different alignments +// APtr15 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr15 is 128-byte aligned auto APtr15 = annotated_aligned_alloc_device(N, q, 128, P10); -// Exception, different alignments +// APtr16 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr16 is 64-byte aligned auto APtr16 = annotated_aligned_alloc_device(N, q, 16, P10); + +// APtr17 is of type annotated_ptr, usm_kind})> +// The raw pointer of APtr17 is 56-byte aligned +auto APtr17 = annotated_aligned_alloc_device(N, q, 7, P11); ---- == Specification @@ -224,10 +226,10 @@ the implementation supports. The core SYCL specification lists eight functions in each of the following four tables: -- Table 103 "USM Device Memory Allocation Functions", of Section 4.8.3.2 "Device allocation functions" + -- Table 104 "USM Host Memory Allocation Functions", of Section 4.8.3.3 "Host allocation functions" + -- Table 105 "USM Shared Memory Allocation Functions", of Section 4.8.3.4 "Shared allocation functions" + -- Table 106 "USM Parameterized Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" +- Table 103 "Device USM Allocation Functions", of Section 4.8.3.2 "Device allocation functions" + +- Table 104 "Host USM Allocation Functions", of Section 4.8.3.3 "Host allocation functions" + +- Table 105 "Shared USM Allocation Functions", of Section 4.8.3.4 "Shared allocation functions" + +- Table 106 "Parameterized USM Allocation Functions", of Section 4.8.3.5 "Parameterized allocation functions" This extension introduces a new function for each function listed in the above tables of the core SYCL specification. This extension also adds USM memory allocation functions with `properties` support that require the `sycl::ext::oneapi::experimental::usm_kind` property, @@ -245,12 +247,17 @@ The new functions are distinguished by their names having the `annotated_` prefi The following five tables list all functions introduced by this extension. -TODO: How is propertyListB going to be inferred? Do we need support for getting the type of a properties list with only the compile-time properties, and also adding a new compile-time property? +[NOTE] +==== +All functions in the following five tables belong to the `sycl::ext::oneapi::experimental` namespace. The +namespace is omitted to save space. +==== + [[section.usm.device.allocs]] -==== Device allocation functions with properties support +==== Device USM allocation functions with properties support [[table.usm.device.allocs]] -.USM Device Memory Allocation Functions with properties Support +.Device USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -258,11 +265,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_device( + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in bytes. This memory is not @@ -284,17 +292,23 @@ contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. +And error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_device( + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in number of elements of type @@ -317,16 +331,20 @@ descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_device(size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_device( + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -341,16 +359,22 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_device_allocations`. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_device(size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_device( + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -365,18 +389,22 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_device_allocations`. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_device( + size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on the specified `device` on success. @@ -402,21 +430,24 @@ must either be contained by `syclContext` or it must be a otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_device( + size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on the specified `device` on success. @@ -443,8 +474,8 @@ contained by `syclContext` or it must be a <> of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -452,11 +483,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_device( + size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -469,25 +501,27 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. - Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_device_allocations`. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_device(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_device( + size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -504,17 +538,17 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_device_allocations`. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== -==== Host allocation functions with properties support +==== Host USM allocation functions with properties support [[table.usm.host.allocs]] -.USM Host Memory Allocation Functions with properties Support +.Host USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -522,10 +556,11 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_host( + size_t numBytes, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is @@ -544,16 +579,22 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_host( + size_t count, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in number of elements of type `T`. @@ -573,16 +614,20 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_host(size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_host( + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context`. @@ -596,16 +641,22 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_host(size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_host( + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context`. @@ -619,17 +670,21 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, - size_t numBytes, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_host( + size_t alignment, + size_t numBytes, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The memory will have `alignment`-byte alignment. @@ -650,20 +705,23 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, - size_t count, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_host( + size_t alignment, + size_t count, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in elements of type `T`. The memory will have `alignment`-byte alignment. @@ -683,9 +741,8 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. - +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -693,11 +750,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_host( + size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context`. @@ -713,20 +771,23 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_host(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_host( + size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context`. @@ -742,18 +803,18 @@ Only devices that have `aspect::usm_host_allocations` may access the memory allocated by this function. Attempting to access the memory from a device that does not have the aspect results in undefined behavior. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::host`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== -==== Shared allocation functions with properties support +==== Shared USM allocation functions with properties support [[table.usm.shared.allocs]] -.USM Shared Memory Allocation Functions with properties Support +.Shared USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -761,11 +822,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_shared( + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on `syclDevice`. @@ -787,17 +849,23 @@ descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_shared( + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on `syclDevice`. @@ -820,16 +888,20 @@ descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc_shared( + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -844,16 +916,22 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_shared_allocations`. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc_shared(size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc_shared( + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -868,18 +946,22 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_shared_allocations`. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. + Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_shared( + size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on `syclDevice`. @@ -905,21 +987,24 @@ must either be contained by `syclContext` or it must be a otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_shared( + size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList = properties{}) ---- a@ Returns a shared allocation that is accessible on the host and on `syclDevice`. @@ -945,8 +1030,8 @@ must either be contained by `syclContext` or it must be a otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -954,11 +1039,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, - size_t numBytes, - const queue& syclQueue, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc_shared( + size_t alignment, + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -975,20 +1061,23 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_shared_allocations`. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc_shared(size_t alignment, - size_t count, - const queue& syclQueue, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc_shared( + size_t alignment, + size_t count, + const queue& syclQueue, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `device` and `context`. @@ -1005,19 +1094,17 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the device does not have `aspect::usm_shared_allocations`. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. +An error is reported if `propList` contains +a `usm_kind` property with value different than `sycl::usm::alloc::shared`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. |==== -==== Parameterized allocation functions with properties support - -TODO: should the properties argument be non-optional here? +==== Parameterized USM allocation functions with properties support [[table.usm.param.allocs]] -.USM Parameterized Allocation Functions with properties Support +.Parameterized USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Function @ Description @@ -1025,12 +1112,13 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, - const device& syclDevice, - const context& syclContext, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc( + size_t numBytes, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Returns a `kind` allocation. This allocation is specified in bytes. This memory @@ -1056,13 +1144,16 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t count, - const device& syclDevice, - const context& syclContext, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc( + size_t count, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Returns a `kind` allocation. @@ -1091,11 +1182,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, - const queue& syclQueue, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_malloc( + size_t numBytes, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. @@ -1113,12 +1205,15 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t count, - const queue& syclQueue, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_malloc( + size_t count, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. @@ -1138,13 +1233,14 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, - size_t numBytes, - const device& syclDevice, - const context& syclContext, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc( + size_t alignment, + size_t numBytes, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Returns a `kind` allocation. This allocation is specified in bytes. @@ -1169,22 +1265,22 @@ is contained by that context, otherwise this function throws a synchronous Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. - Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, - size_t count, - const device& syclDevice, - const context& syclContext, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc( + size_t alignment, + size_t count, + const device& syclDevice, + const context& syclContext, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Returns a `kind` allocation. This allocation is specified in number of elements of type `T`. @@ -1207,8 +1303,6 @@ is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1216,12 +1310,13 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, - size_t numBytes, - const queue& syclQueue, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +annotated_ptr +annotated_aligned_alloc( + size_t alignment, + size_t numBytes, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. @@ -1236,21 +1331,22 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_aligned_alloc(size_t alignment, - size_t count, - const queue& syclQueue, - sycl::usm::alloc kind, - const propertyListA &propList = properties{}) +template +annotated_ptr +annotated_aligned_alloc( + size_t alignment, + size_t count, + const queue& syclQueue, + sycl::usm::alloc kind, + const propertyListA &propList = properties{}) ---- a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. @@ -1264,8 +1360,6 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains an `alignment` property specifying a different -alignment value than given by the `alignment` argument. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1279,7 +1373,7 @@ These functions do not correspond to any USM memory allocation functions in the [NOTE] ==== The `properties` argument is non-optional for the functions defined in this section, since at least one property (i.e., `sycl::ext::oneapi::experimental::usm_kind`) must be provided. -These functions are distinguished from the functions with the same names in Table <>, by the presence or absence of the parameter of type `sycl::usm::alloc`. +These functions are distinguished from the functions with the same names in Table <>, by the absence of a parameter of type `sycl::usm::alloc`. ==== @@ -1292,11 +1386,12 @@ a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList) +annotated_ptr +annotated_malloc( + size_t numBytes, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList) ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. @@ -1320,12 +1415,15 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t count, - const device& syclDevice, - const context& syclContext, - const propertyListA &propList) +template +annotated_ptr +annotated_malloc( + size_t count, + const device& syclDevice, + const context& syclContext, + const propertyListA &propList) ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. @@ -1346,15 +1444,15 @@ is contained by that context, otherwise this function throws a synchronous Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t numBytes, - const queue& syclQueue, - const propertyListA &propList) +annotated_ptr +annotated_malloc( + size_t numBytes, + const queue& syclQueue, + const propertyListA &propList) ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. @@ -1374,11 +1472,14 @@ Available only if `propertyListA` and `propertyListB` are specializations of the a@ [source] ---- -template -sycl::ext::oneapi::experimental::annotated_ptr -sycl::ext::oneapi::experimental::annotated_malloc(size_t count, - const queue& syclQueue, - const propertyListA &propList) +template +annotated_ptr +annotated_malloc( + size_t count, + const queue& syclQueue, + const propertyListA &propList) ---- a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. @@ -1421,11 +1522,9 @@ Table <> lists properties that affect the behavior |==== |Property|Description|Source a| -alignment +sycl::ext::oneapi::experimental::alignment | If this property is passed to a USM memory allocation function with `properties` support, it instructs the runtime to allocate memory with this alignment in bytes. -If the USM memory allocation function with `properties` support is templated on an allocation type `T` and the specified alignment is not suitable for an object of type `T` the compiler will issue a diagnostic error. -If the USM memory allocation function with `properties` support is not templated on an allocation type `T`, and the specified alignment is not suitable for objects with fundamental alignment whose size is less than or equal to the requested allocation size, the USM memory allocation function with `properties` support will throw a synchronous exception with the `errc:invalid` error code. | link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] |==== @@ -1482,5 +1581,5 @@ sycl::free(APtr.get(), q); [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-11-07|Jessica Davies|*Initial public working draft* +|1|2022-12-15|Jessica Davies|*Initial public working draft* |======================================== From 1c27d5710ea00ec5ba3559eb41224dd263c720cc Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Wed, 25 Jan 2023 13:58:04 -0800 Subject: [PATCH 10/16] Add two new memory deallocation functions that take an annotated_ptr instead of a raw pointer. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 50 +++++++++++++++---- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 756a69065ac1e..e42728115d50c 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -6,7 +6,7 @@ == Notice -Copyright (c) 2022 Intel Corporation. All rights reserved. +Copyright (c) 2023 Intel Corporation. All rights reserved. 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. @@ -292,7 +292,7 @@ contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. -And error is reported if `propList` contains +An error is reported if `propList` contains a `usm_kind` property with value different than `sycl::usm::alloc::device`. Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. @@ -1556,9 +1556,10 @@ The `sycl::ext::oneapi::experimental::usm_kind` property is supported by `annota === Deallocation -To avoid memory leaks, USM memory allocated using the USM memory allocation functions with `properties` support defined in this extension, must be deallocated using one of the `sycl::free` functions listed in Table 107 "USM Deallocation Functions" of Section 4.8.3.6 "Memory deallocation functions" of the core SYCL specification. +This extension introduces two new functions called `sycl::ext::oneapi::experimental::free` that take an `annotated_ptr` as argument. These functions deallocate the memory pointed to by the raw pointer belonging to the `annotated_ptr`. The new deallocation functions are listed in Table <>. These functions belong to the namespace `sycl::ext::oneapi::experimental`. +To avoid memory leaks, USM memory allocated using the USM memory allocation functions with `properties` support defined in this extension, must be deallocated using `sycl::ext::oneapi::experimental::free` or `sycl::free`. -The following example shows how USM memory allocated using one of the functions defined in this extension should be deallocated, to avoid memory leaks. +The following example shows how USM memory allocated using one of the functions defined in this extension can be deallocated, to avoid memory leaks. ==== Example @@ -1566,13 +1567,42 @@ The following example shows how USM memory allocated using one of the functions ---- using namespace sycl::ext::oneapi::experimental; -properties P1{alignment<512>}; -// APtr is of type annotated_ptr, usm_kind})> -auto APtr = annotated_malloc_device(N, q, P1); +// APtr and BPtr are of type +// annotated_ptr})> +auto APtr = annotated_malloc_device(N, q); +auto BPtr = annotated_malloc_device(N, q); + +// Deallocate the memory pointed to by the raw pointer of APtr +free(APtr, q); + +// Deallocate the memory pointed to by the raw pointer of BPtr, using sycl::free +free(BPtr.get(), q); +---- -// Deallocate the memory using the raw pointer of APtr -sycl::free(APtr.get(), q); +[[table.usm.malloc.free]] +.New USM memory deallocation functions introduced by this extension +[options="header"] +|==== +|Function|Description +a| +[source,c++] +---- +template +void free(annotated_ptr &ptr, + const context& syclContext) ---- +| Frees an allocation. The memory pointed to by the raw pointer belonging to `ptr` must have been allocated using one of the USM memory allocation functions with `properties` support defined in this extension, or one of the +SYCL USM allocation routines. `syclContext` must be the same `context` that was used to allocate the memory. The memory is freed without waiting for `commands` operating on it to be completed. If `commands` that use this memory +are in-progress or are enqueued the behavior is undefined. +a| +[source,c++] +---- +template +void free(annotated_ptr &ptr, + const queue& syclQueue) +---- +| Alternate form where `syclQueue` provides the `context`. +|==== == Revision History @@ -1581,5 +1611,5 @@ sycl::free(APtr.get(), q); [options="header"] |======================================== |Rev|Date|Author|Changes -|1|2022-12-15|Jessica Davies|*Initial public working draft* +|1|2023-01-25|Jessica Davies|*Initial public working draft* |======================================== From 063cd0907172bd6d22069d115821d551b5a7a0ce Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Mon, 30 Jan 2023 12:18:11 -0800 Subject: [PATCH 11/16] Rename annotated_malloc to malloc_annotated. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index e42728115d50c..a37005df76074 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -89,13 +89,13 @@ properties P2{bar, foo{1}}; properties P3{bar, baz} // APtr1 is of type annotated_ptr})> -auto APtr1 = annotated_malloc_device(N, q, P1); +auto APtr1 = malloc_device_annotated(N, q, P1); // APtr2 is of type annotated_ptr})> -auto APtr2 = annotated_malloc_device(N, q, P2); +auto APtr2 = malloc_device_annotated(N, q, P2); // APtr3 is of type annotated_ptr})> -auto APtr3 = annotated_malloc_device(N, q, P3); +auto APtr3 = malloc_device_annotated(N, q, P3); // Runtime properties are not present on the returned annotated_ptr static_assert(std::is_same_v); @@ -104,10 +104,10 @@ static_assert(std::is_same_v); static_assert(!std::is_same_v); // APtr4 is of type annotated_ptr})> -auto APtr4 = annotated_malloc_host(N, q); +auto APtr4 = malloc_host_annotated(N, q); // APtr5 is of type annotated_ptr})> -auto APtr5 = annotated_malloc_shared(N, q); +auto APtr5 = malloc_shared_annotated(N, q); // The USM kinds differ static_assert(!std::is_same_v); @@ -123,10 +123,10 @@ using namespace sycl::ext::oneapi::experimental; properties P4{bar, foo{1}}; // APtr6 is of type annotated_ptr -auto APtr6 = annotated_malloc(N, q, sycl::usm::alloc::device, P4); +auto APtr6 = malloc_annotated(N, q, sycl::usm::alloc::device, P4); // APtr7 is of type annotated_ptr; -auto APtr7 = annotated_malloc(N, q, sycl::usm::alloc::device); +auto APtr7 = malloc_annotated(N, q, sycl::usm::alloc::device); ---- If the USM memory allocation kind specified by a parameter to the allocation function is different than the USM memory allocation kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property, the function throws a @@ -140,10 +140,10 @@ using namespace sycl::ext::oneapi::experimental; properties P5{usm_kind}; // Throws an exception with error code errc::invalid -auto APtr8 = annotated_malloc(N, q, sycl::usm::alloc::host, P5); +auto APtr8 = malloc_annotated(N, q, sycl::usm::alloc::host, P5); // Error: the USM kinds do not agree -auto APtr9 = annotated_malloc_host(N, q, P5); +auto APtr9 = malloc_host_annotated(N, q, P5); ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. @@ -160,15 +160,15 @@ properties P9{alignment<64>}; // APtr10 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr10 is 512-byte aligned -auto APtr10 = annotated_malloc_device(N, q, P7); +auto APtr10 = malloc_device_annotated(N, q, P7); // APtr11 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr11 is sizeof(int)-byte aligned -auto APtr11 = annotated_malloc_device(N, q, P8); +auto APtr11 = malloc_device_annotated(N, q, P8); // APtr12 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr12 is 512-byte aligned -auto APtr12 = annotated_malloc_device(512, q, P9); +auto APtr12 = malloc_device_annotated(512, q, P9); ---- This extension also introduces USM memory allocation functions with `properties` support that allow alignment to be specified at runtime, using a separate parameter of type `size_t`. @@ -266,7 +266,7 @@ a@ ---- template annotated_ptr -annotated_malloc_device( +malloc_device_annotated( size_t numBytes, const device& syclDevice, const context& syclContext, @@ -274,7 +274,7 @@ annotated_malloc_device( ---- a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in bytes. This memory is not -accessible on the host. Memory allocated by `annotated_malloc_device` +accessible on the host. Memory allocated by `malloc_device_annotated` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -304,7 +304,7 @@ template annotated_ptr -annotated_malloc_device( +malloc_device_annotated( size_t count, const device& syclDevice, const context& syclContext, @@ -313,7 +313,7 @@ annotated_malloc_device( a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on success. The allocation size is specified in number of elements of type `T`. This memory is not accessible on the host. Memory allocated -by `annotated_malloc_device` must be deallocated with +by `malloc_device_annotated` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -341,7 +341,7 @@ a@ ---- template annotated_ptr -annotated_malloc_device( +malloc_device_annotated( size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -371,7 +371,7 @@ template annotated_ptr -annotated_malloc_device( +malloc_device_annotated( size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -557,7 +557,7 @@ a@ ---- template annotated_ptr -annotated_malloc_host( +malloc_host_annotated( size_t numBytes, const context& syclContext, const propertyListA &propList = properties{}) @@ -565,7 +565,7 @@ annotated_malloc_host( a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on success. This allocation is specified in bytes. The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `annotated_malloc_host` must be +Memory allocated by `malloc_host_annotated` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -591,7 +591,7 @@ template annotated_ptr -annotated_malloc_host( +malloc_host_annotated( size_t count, const context& syclContext, const propertyListA &propList = properties{}) @@ -600,7 +600,7 @@ a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated ho success. This allocation is specified in number of elements of type `T`. The allocation is accessible on the host and devices contained in the specified `context`. -Memory allocated by `annotated_malloc_host` must be +Memory allocated by `malloc_host_annotated` must be deallocated with `sycl::free` to avoid memory leaks. On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. @@ -624,7 +624,7 @@ a@ ---- template annotated_ptr -annotated_malloc_host( +malloc_host_annotated( size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -653,7 +653,7 @@ template annotated_ptr -annotated_malloc_host( +malloc_host_annotated( size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -823,7 +823,7 @@ a@ ---- template annotated_ptr -annotated_malloc_shared( +malloc_shared_annotated( size_t numBytes, const device& syclDevice, const context& syclContext, @@ -861,7 +861,7 @@ template annotated_ptr -annotated_malloc_shared( +malloc_shared_annotated( size_t count, const device& syclDevice, const context& syclContext, @@ -898,7 +898,7 @@ a@ ---- template annotated_ptr -annotated_malloc_shared( +malloc_shared_annotated( size_t numBytes, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -928,7 +928,7 @@ template annotated_ptr -annotated_malloc_shared( +malloc_shared_annotated( size_t count, const queue& syclQueue, const propertyListA &propList = properties{}) @@ -1113,7 +1113,7 @@ a@ ---- template annotated_ptr -annotated_malloc( +malloc_annotated( size_t numBytes, const device& syclDevice, const context& syclContext, @@ -1148,7 +1148,7 @@ template annotated_ptr -annotated_malloc( +malloc_annotated( size_t count, const device& syclDevice, const context& syclContext, @@ -1183,7 +1183,7 @@ a@ ---- template annotated_ptr -annotated_malloc( +malloc_annotated( size_t numBytes, const queue& syclQueue, sycl::usm::alloc kind, @@ -1209,7 +1209,7 @@ template annotated_ptr -annotated_malloc( +malloc_annotated( size_t count, const queue& syclQueue, sycl::usm::alloc kind, @@ -1387,7 +1387,7 @@ a@ ---- template annotated_ptr -annotated_malloc( +malloc_annotated( size_t numBytes, const device& syclDevice, const context& syclContext, @@ -1419,7 +1419,7 @@ template annotated_ptr -annotated_malloc( +malloc_annotated( size_t count, const device& syclDevice, const context& syclContext, @@ -1449,7 +1449,7 @@ a@ ---- template annotated_ptr -annotated_malloc( +malloc_annotated( size_t numBytes, const queue& syclQueue, const propertyListA &propList) @@ -1476,7 +1476,7 @@ template annotated_ptr -annotated_malloc( +malloc_annotated( size_t count, const queue& syclQueue, const propertyListA &propList) @@ -1569,8 +1569,8 @@ using namespace sycl::ext::oneapi::experimental; // APtr and BPtr are of type // annotated_ptr})> -auto APtr = annotated_malloc_device(N, q); -auto BPtr = annotated_malloc_device(N, q); +auto APtr = malloc_device_annotated(N, q); +auto BPtr = malloc_device_annotated(N, q); // Deallocate the memory pointed to by the raw pointer of APtr free(APtr, q); From 16b083e63f1e7fc9f84507b365d912ad69032c73 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Mon, 30 Jan 2023 13:53:28 -0800 Subject: [PATCH 12/16] Address most of Greg's comments. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index a37005df76074..b22df03112750 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -155,7 +155,7 @@ It also informs the runtime to allocate the memory with this alignment. using namespace sycl::ext::oneapi::experimental; properties P7{alignment<512>}; -properties P8{alignment<1>}; +properties P8{alignment<2>}; properties P9{alignment<64>}; // APtr10 is of type annotated_ptr, usm_kind})> @@ -163,7 +163,7 @@ properties P9{alignment<64>}; auto APtr10 = malloc_device_annotated(N, q, P7); // APtr11 is of type annotated_ptr, usm_kind})> -// The raw pointer of APtr11 is sizeof(int)-byte aligned +// The raw pointer of APtr11 is sizeof(int)-byte aligned, e.g., 4 for some implementations auto APtr11 = malloc_device_annotated(N, q, P8); // APtr12 is of type annotated_ptr, usm_kind})> @@ -199,7 +199,7 @@ auto APtr15 = annotated_aligned_alloc_device(N, q, 128, P10); auto APtr16 = annotated_aligned_alloc_device(N, q, 16, P10); // APtr17 is of type annotated_ptr, usm_kind})> -// The raw pointer of APtr17 is 56-byte aligned +// The raw pointer of APtr17 is 56-byte aligned (if this alignment is supported by the implementation) auto APtr17 = annotated_aligned_alloc_device(N, q, 7, P11); ---- @@ -426,7 +426,7 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the `syclDevice` does not have `aspect::usm_device_allocations`. The `syclDevice` must either be contained by `syclContext` or it must be a -<> of some device that is contained by that context, +descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -470,7 +470,7 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the `syclDevice` does not have `aspect::usm_device_allocations`. The `syclDevice` must either be -contained by `syclContext` or it must be a <> of some +contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -983,7 +983,7 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the `syclDevice` does not have `aspect::usm_shared_allocations`. The `syclDevice` must either be contained by `syclContext` or it must be a -<> of some device that is contained by that context, +descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -1026,7 +1026,7 @@ Throws a synchronous `exception` with the `errc::feature_not_supported` error code if the `syclDevice` does not have `aspect::usm_shared_allocations`. The `syclDevice` must either be contained by `syclContext` or it must be a -<> of some device that is contained by that context, +descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -1259,7 +1259,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` The `syclDevice` parameter is ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not `usm::alloc::host`, `syclDevice` must either be contained by -`syclContext` or it must be a <> of some device that +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -1298,7 +1298,7 @@ Runtime properties in `propList` will not appear as properties of the returned ` The `syclDevice` parameter is ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not `sycl::usm::alloc::host`, `syclDevice` must either be contained by -`syclContext` or it must be a <> of some device that +`syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -1525,6 +1525,7 @@ a| sycl::ext::oneapi::experimental::alignment | If this property is passed to a USM memory allocation function with `properties` support, it instructs the runtime to allocate memory with this alignment in bytes. +The set of allowed alignments is implementation defined. Specifying an alignment that is not supported causes the allocation function to return an `annotated_ptr` containing a raw pointer that is `nullptr`. | link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] |==== @@ -1604,12 +1605,3 @@ void free(annotated_ptr &ptr, | Alternate form where `syclQueue` provides the `context`. |==== -== Revision History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|======================================== -|Rev|Date|Author|Changes -|1|2023-01-25|Jessica Davies|*Initial public working draft* -|======================================== From b3ea6e767cca22950a56c1f89b3f13fb0d824cde Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Mon, 30 Jan 2023 15:03:07 -0800 Subject: [PATCH 13/16] Update the function descriptions to be equivalent to Revision 6 of the SYCL 2020 spec. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 558 +++++------------- 1 file changed, 135 insertions(+), 423 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index b22df03112750..9a05327bb9b3b 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -184,23 +184,23 @@ properties P11{alignment<8>}; // APtr13 is of type annotated_ptr})> // The raw pointer of APtr13 is 64-byte aligned -auto APtr13 = annotated_aligned_alloc_device(N, q, 64 /* alignment */); +auto APtr13 = aligned_alloc_device_annotated(N, q, 64 /* alignment */); // APtr14 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr14 is 64-byte aligned -auto APtr14 = annotated_aligned_alloc_device(N, q, 64, P10); +auto APtr14 = aligned_alloc_device_annotated(N, q, 64, P10); // APtr15 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr15 is 128-byte aligned -auto APtr15 = annotated_aligned_alloc_device(N, q, 128, P10); +auto APtr15 = aligned_alloc_device_annotated(N, q, 128, P10); // APtr16 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr16 is 64-byte aligned -auto APtr16 = annotated_aligned_alloc_device(N, q, 16, P10); +auto APtr16 = aligned_alloc_device_annotated(N, q, 16, P10); // APtr17 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr17 is 56-byte aligned (if this alignment is supported by the implementation) -auto APtr17 = annotated_aligned_alloc_device(N, q, 7, P11); +auto APtr17 = aligned_alloc_device_annotated(N, q, 7, P11); ---- == Specification @@ -239,7 +239,7 @@ All USM memory allocation functions introduced by this extension are listed expl [NOTE] ==== The USM memory allocation functions defined in the core SYCL specification can be used in the same program as the USM memory allocation functions with `properties` support defined in this extension. -The new functions are distinguished by their names having the `annotated_` prefix. +The new functions are distinguished by their names having the `_annotated` suffix. ==== [[section.usm.allocs]] @@ -256,6 +256,13 @@ namespace is omitted to save space. [[section.usm.device.allocs]] ==== Device USM allocation functions with properties support +The functions in <> allocate device USM. On success, +these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must +eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory +leak. If there are not enough resources to allocate the requested memory, +these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. + + [[table.usm.device.allocs]] .Device USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] @@ -272,11 +279,8 @@ malloc_device_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on -success. The allocation size is specified in bytes. This memory is not -accessible on the host. Memory allocated by `malloc_device_annotated` -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is allocated on `syclDevice`. +The allocation size is specified in bytes. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -310,12 +314,9 @@ malloc_device_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on `syclDevice` on -success. The allocation size is specified in number of elements of type -`T`. This memory is not accessible on the host. Memory allocated -by `malloc_device_annotated` must be deallocated with -`sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is allocated on `syclDevice`. +The allocation size is specified in number of elements of type +`T`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -349,21 +350,6 @@ malloc_device_annotated( a@ Simplified form where `syclQueue` provides the `device` and `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_device_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::device`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -379,42 +365,22 @@ malloc_device_annotated( a@ Simplified form where `syclQueue` provides the `device` and `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_device_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::device`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- template annotated_ptr -annotated_aligned_alloc_device( +aligned_alloc_device_annotated( size_t alignment, size_t numBytes, const device& syclDevice, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified `device` on success. -The memory will have `alignment`-byte alignment. -The allocation size is specified in bytes. This memory is not accessible on -the host. Memory allocated by `annotated_aligned_alloc_device` must be -deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. - -Devices may only permit certain alignments. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is allocated on +`syclDevice`. +The allocation is specified in bytes and aligned according +to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -442,23 +408,17 @@ template annotated_ptr -annotated_aligned_alloc_device( +aligned_alloc_device_annotated( size_t alignment, size_t count, const device& syclDevice, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory on -the specified `device` on success. -The memory will have `alignment`-byte alignment. - -The allocation size is specified in elements of type `T`. This memory is -not accessible on the host. Memory allocated by -`annotated_aligned_alloc_device` must be deallocated with `sycl::free` -to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. -Devices may only permit certain alignments. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is allocated on +`syclDevice`. +The allocation is specified in number of elements of type +`T` and aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -484,7 +444,7 @@ a@ ---- template annotated_ptr -annotated_aligned_alloc_device( +aligned_alloc_device_annotated( size_t alignment, size_t numBytes, const queue& syclQueue, @@ -493,23 +453,6 @@ annotated_aligned_alloc_device( a@ Simplified form where `syclQueue` provides the `device` and `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_device_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::device`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -517,7 +460,7 @@ template annotated_ptr -annotated_aligned_alloc_device( +aligned_alloc_device_annotated( size_t alignment, size_t count, const queue& syclQueue, @@ -526,27 +469,17 @@ annotated_aligned_alloc_device( a@ Simplified form where `syclQueue` provides the `device` and `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_device_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::device`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - |==== ==== Host USM allocation functions with properties support +The functions in <> allocate host USM. On success, +these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must +eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory +leak. If there are not enough resources to allocate the requested memory, +these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. + + [[table.usm.host.allocs]] .Host USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] @@ -562,12 +495,7 @@ malloc_host_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in bytes. The allocation is -accessible on the host and devices contained in the specified `context`. -Memory allocated by `malloc_host_annotated` must be -deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory. This allocation is specified in bytes. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -575,9 +503,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if no device in +`syclContext` has `aspect::usm_host_allocations`. An error is reported if `propList` contains a `usm_kind` property with value different than `sycl::usm::alloc::host`. @@ -596,13 +524,7 @@ malloc_host_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in number of elements of type `T`. -The allocation is accessible on the host and devices contained in the -specified `context`. -Memory allocated by `malloc_host_annotated` must be -deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory. This allocation is specified in number of elements of type `T`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -610,9 +532,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if no device in +`syclContext` has `aspect::usm_host_allocations`. An error is reported if `propList` contains a `usm_kind` property with value different than `sycl::usm::alloc::host`. @@ -631,21 +553,6 @@ malloc_host_annotated( ---- a@ Simplified form where `syclQueue` provides the `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::host`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -660,40 +567,19 @@ malloc_host_annotated( ---- a@ Simplified form where `syclQueue` provides the `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::host`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- template annotated_ptr -annotated_aligned_alloc_host( +aligned_alloc_host_annotated( size_t alignment, size_t numBytes, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in bytes. The memory will have `alignment`-byte alignment. - -The allocation is accessible on the host and devices contained -in the specified `context`. -Memory allocated by `annotated_aligned_malloc_host` must be -deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory. +This allocation is specified in bytes and aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -701,9 +587,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if no device in +`syclContext` has `aspect::usm_host_allocations`. An error is reported if `propList` contains a `usm_kind` property with value different than `sycl::usm::alloc::host`. @@ -717,19 +603,14 @@ template annotated_ptr -annotated_aligned_alloc_host( +aligned_alloc_host_annotated( size_t alignment, size_t count, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated host memory on -success. This allocation is specified in elements of type `T`. The memory will have `alignment`-byte alignment. -The allocation is accessible on the -host and devices contained in the specified `context`. -Memory allocated by `annotated_aligned_malloc_host` must be -deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory. +This allocation is specified in elements of type `T` and aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -737,9 +618,9 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The returned `annotated_ptr` will have the property `usm_kind`. -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. +Throws a synchronous `exception` with the +`errc::feature_not_supported` error code if no device in +`syclContext` has `aspect::usm_host_allocations`. An error is reported if `propList` contains a `usm_kind` property with value different than `sycl::usm::alloc::host`. @@ -751,7 +632,7 @@ a@ ---- template annotated_ptr -annotated_aligned_alloc_host( +aligned_alloc_host_annotated( size_t alignment, size_t numBytes, const queue& syclQueue, @@ -759,23 +640,6 @@ annotated_aligned_alloc_host( ---- a@ Simplified form where `syclQueue` provides the `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::host`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -783,7 +647,7 @@ template annotated_ptr -annotated_aligned_alloc_host( +aligned_alloc_host_annotated( size_t alignment, size_t count, const queue& syclQueue, @@ -791,28 +655,16 @@ annotated_aligned_alloc_host( ---- a@ Simplified form where `syclQueue` provides the `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Only devices that have `aspect::usm_host_allocations` may access the -memory allocated by this function. Attempting to access the memory from -a device that does not have the aspect results in undefined behavior. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::host`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - - |==== ==== Shared USM allocation functions with properties support +The functions in <> allocate shared USM. On success, +these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must +eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory +leak. If there are not enough resources to allocate the requested memory, +these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. + [[table.usm.shared.allocs]] .Shared USM Allocation Functions with properties Support [width="100%",options="header",separator="@",cols="65%,35%"] @@ -829,11 +681,8 @@ malloc_shared_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns a shared allocation that is accessible on the host and -on `syclDevice`. -This allocation is specified in bytes. This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is associated with `syclDevice`. +This allocation is specified in bytes. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -867,12 +716,9 @@ malloc_shared_annotated( const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns a shared allocation that is accessible on the host and -on `syclDevice`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is associated with `syclDevice`. This allocation is specified in number of elements of -type `T`. This memory must be deallocated with `sycl::free` to avoid -memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +type `T`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -906,21 +752,6 @@ malloc_shared_annotated( a@ Simplified form where `syclQueue` provides the `device` and `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_shared_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::shared`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -936,42 +767,20 @@ malloc_shared_annotated( a@ Simplified form where `syclQueue` provides the `device` and `context`. -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_shared_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::shared`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- template annotated_ptr -annotated_aligned_alloc_shared( +aligned_alloc_shared_annotated( size_t alignment, size_t numBytes, const device& syclDevice, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns a shared allocation that is accessible on the host and -on `syclDevice`. -This allocation is specified in bytes. - -The memory will have `alignment`-byte alignment. - -This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is associated with `syclDevice`. +This allocation is specified in bytes and aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -999,22 +808,15 @@ template annotated_ptr -annotated_aligned_alloc_shared( +aligned_alloc_shared_annotated( size_t alignment, size_t count, const device& syclDevice, const context& syclContext, const propertyListA &propList = properties{}) ---- -a@ Returns a shared allocation that is accessible on the host and -on `syclDevice`. -This allocation is specified in number of elements of type `T`. - -The memory will have `alignment`-byte alignment. - -This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory, which is associated with `syclDevice`. +This allocation is specified in number of elements of type `T` and aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1040,7 +842,7 @@ a@ ---- template annotated_ptr -annotated_aligned_alloc_shared( +aligned_alloc_shared_annotated( size_t alignment, size_t numBytes, const queue& syclQueue, @@ -1049,23 +851,6 @@ annotated_aligned_alloc_shared( a@ Simplified form where `syclQueue` provides the `device` and `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_shared_allocations`. - -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::shared`. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -1073,7 +858,7 @@ template annotated_ptr -annotated_aligned_alloc_shared( +aligned_alloc_shared_annotated( size_t alignment, size_t count, const queue& syclQueue, @@ -1082,26 +867,26 @@ annotated_aligned_alloc_shared( a@ Simplified form where `syclQueue` provides the `device` and `context`. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. -The returned `annotated_ptr` will have the property `usm_kind`. - -Throws a synchronous `exception` with the -`errc::feature_not_supported` error code if the device -does not have `aspect::usm_shared_allocations`. +|==== -An error is reported if `propList` contains -a `usm_kind` property with value different than `sycl::usm::alloc::shared`. +==== Parameterized USM allocation functions with properties support -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. +The functions in <> take a `kind` parameter that +specifies the type of USM to allocate. When `kind` is +`usm::alloc::device`, then the allocation device must have +`aspect::usm_device_allocations`. When `kind` is +`usm::alloc::host`, at least one device in the allocation context must +have `aspect::usm_host_allocations`. When `kind` is +`usm::alloc::shared`, the allocation device must have +`aspect::usm_shared_allocations`. If these requirements are +violated, the allocation function throws a synchronous `exception` with +the `errc::feature_not_supported` error code. -|==== +On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, +which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid +a memory leak. If there are not enough resources to allocate the requested +memory, these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. -==== Parameterized USM allocation functions with properties support [[table.usm.param.allocs]] .Parameterized USM Allocation Functions with properties Support @@ -1120,10 +905,8 @@ malloc_annotated( sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a `kind` allocation. -This allocation is specified in bytes. This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type `kind`. +This allocation size is specified in bytes. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1131,7 +914,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The `syclDevice` parameter is -ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +ignored if `kind` is `sycl::usm::alloc::host`. If `kind` is not `sycl::usm::alloc::host`, `syclDevice` must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous @@ -1155,11 +938,8 @@ malloc_annotated( sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a `kind` allocation. - +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type `kind`. This allocation is specified in number of elements of type `T`. -This memory must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1167,7 +947,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The `syclDevice` parameter is -ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +ignored if `kind` is `sycl::usm::alloc::host`. If `kind` is not `sycl::usm::alloc::host`, `syclDevice` must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous @@ -1191,16 +971,6 @@ malloc_annotated( ---- a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Returns a `kind` allocation. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. a@ [source] @@ -1218,23 +988,12 @@ malloc_annotated( a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Returns a `kind` allocation. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- template annotated_ptr -annotated_aligned_alloc( +aligned_alloc_annotated( size_t alignment, size_t numBytes, const device& syclDevice, @@ -1242,23 +1001,17 @@ annotated_aligned_alloc( sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a `kind` allocation. -This allocation is specified in bytes. -The memory will have `alignment`-byte alignment. - -This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type `kind`. +This allocation is specified in bytes and is aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - The `syclDevice` parameter is -ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not -`usm::alloc::host`, `syclDevice` must either be contained by +ignored if `kind` is `sycl::usm::alloc::host`. If `kind` is not +`sycl::usm::alloc::host`, `syclDevice` must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous `exception` with the `errc::invalid` error code. @@ -1274,7 +1027,7 @@ template annotated_ptr -annotated_aligned_alloc( +aligned_alloc_annotated( size_t alignment, size_t count, const device& syclDevice, @@ -1282,13 +1035,8 @@ annotated_aligned_alloc( sycl::usm::alloc kind, const propertyListA &propList = properties{}) ---- -a@ Returns a `kind` allocation. -This allocation is specified in number of elements of type `T`. -The memory will have `alignment`-byte alignment. - -This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type `kind`. +This allocation is specified in number of elements of type `T` and is aligned according to `alignment`. Zero or more runtime and compile-time constant properties can be provided to the allocation function via an instance of `properties`. @@ -1296,7 +1044,7 @@ The compile-time constant properties in `propList` will appear as properties of Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. The `syclDevice` parameter is -ignored if the allocation kind is `sycl::usm::alloc::host`. If the allocation kind is not +ignored if `kind` is `sycl::usm::alloc::host`. If `kind` is not `sycl::usm::alloc::host`, `syclDevice` must either be contained by `syclContext` or it must be a descendent device of some device that is contained by that context, otherwise this function throws a synchronous @@ -1311,7 +1059,7 @@ a@ ---- template annotated_ptr -annotated_aligned_alloc( +aligned_alloc_annotated( size_t alignment, size_t numBytes, const queue& syclQueue, @@ -1321,19 +1069,6 @@ annotated_aligned_alloc( a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Returns a `kind` allocation. - -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -1341,7 +1076,7 @@ template annotated_ptr -annotated_aligned_alloc( +aligned_alloc_annotated( size_t alignment, size_t count, const queue& syclQueue, @@ -1351,18 +1086,6 @@ annotated_aligned_alloc( a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Returns a `kind` allocation. -The memory will have `alignment`-byte alignment. - -Zero or more runtime and compile-time constant properties can be provided to the allocation function -via an instance of `properties`. -The compile-time constant properties in `propList` will appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Throws a synchronous `exception` with the `errc::invalid` error code if `propList` contains a `sycl::ext::oneapi::experimental::usm_kind` property specifying a different allocation kind. - -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - |==== ==== Additional USM memory allocation functions, requiring the usm_kind property @@ -1374,9 +1097,25 @@ These functions do not correspond to any USM memory allocation functions in the ==== The `properties` argument is non-optional for the functions defined in this section, since at least one property (i.e., `sycl::ext::oneapi::experimental::usm_kind`) must be provided. These functions are distinguished from the functions with the same names in Table <>, by the absence of a parameter of type `sycl::usm::alloc`. - ==== +The functions in <> require a `sycl::ext::oneapi::experimental::usm_kind` property that +specifies the type of USM to allocate. When the `sycl::ext::oneapi::experimental::usm_kind` property has value +`usm::alloc::device`, then the allocation device must have +`aspect::usm_device_allocations`. When the `sycl::ext::oneapi::experimental::usm_kind` property has value +`usm::alloc::host`, at least one device in the allocation context must +have `aspect::usm_host_allocations`. When the `sycl::ext::oneapi::experimental::usm_kind` property has value +`usm::alloc::shared`, the allocation device must have +`aspect::usm_shared_allocations`. If these requirements are +violated, the allocation function throws a synchronous `exception` with +the `errc::feature_not_supported` error code. + +On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, +which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid +a memory leak. If there are not enough resources to allocate the requested +memory, these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. + + [[table.usm.additional.allocs]] .USM allocation functions requiring the usm_kind property [width="100%",options="header",separator="@",cols="65%,35%"] @@ -1393,12 +1132,11 @@ malloc_annotated( const context& syclContext, const propertyListA &propList) ---- -a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. -Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. -This allocation is specified in bytes. This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +a@ +Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type specified by the `sycl::ext::oneapi::experimental::usm_kind` property. +This allocation is specified in bytes. +`propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. @@ -1425,12 +1163,11 @@ malloc_annotated( const context& syclContext, const propertyListA &propList) ---- -a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. -Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. +a@ +Returns an `annotated_ptr` containing a raw pointer to the newly allocated memory of type specified by the `sycl::ext::oneapi::experimental::usm_kind` property. This allocation is specified in number of elements of type `T`. -This memory must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. +`propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. Additional runtime and compile-time constant properties can be provided in `propList`. The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. @@ -1454,21 +1191,9 @@ malloc_annotated( const queue& syclQueue, const propertyListA &propList) ---- -a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. -Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. -This allocation is specified in bytes. This memory -must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. - -Additional runtime and compile-time constant properties can be provided in `propList`. -The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Simplified form where `syclQueue` provides the `context` +a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - a@ [source] ---- @@ -1481,22 +1206,9 @@ malloc_annotated( const queue& syclQueue, const propertyListA &propList) ---- -a@ `propList` must contain the `sycl::ext::oneapi::experimental::usm_kind` property, otherwise the compiler will issue a diagnostic error. -Returns a USM memory allocation of the kind specified by the `sycl::ext::oneapi::experimental::usm_kind` property. -This allocation is specified in number of elements of type `T`. -This memory must be deallocated with `sycl::free` to avoid memory leaks. -On failure, the raw pointer of the returned `annotated_ptr` will be `nullptr`. - -Additional runtime and compile-time constant properties can be provided in `propList`. -The compile-time constant properties in `propList` will also appear as properties of the returned `annotated_ptr`. -Runtime properties in `propList` will not appear as properties of the returned `annotated_ptr`. - -Simplified form where `syclQueue` provides the `context` +a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. -Available only if `propertyListA` and `propertyListB` are specializations of the `properties` class. - - |==== === USM Memory Allocation Properties From ce4315c7ca23d14d364ae1b167f181f25395dd14 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Thu, 2 Feb 2023 14:36:24 -0800 Subject: [PATCH 14/16] Fix nullptr. Add notes to examples about runtime alignment. --- ...l_ext_oneapi_usm_malloc_properties.asciidoc | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 9a05327bb9b3b..fb01da1ebb545 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -147,7 +147,7 @@ auto APtr9 = malloc_host_annotated(N, q, P5); ---- The following example uses the compile-time-constant property `alignment`, defined in the link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] extension. -When `alignment` is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr` since it is a compile-time constant property. +When the `alignment` property is passed to a USM memory allocation function with `properties` support, it will appear on the returned `annotated_ptr` since it is a compile-time constant property. It also informs the runtime to allocate the memory with this alignment. [source,c++] @@ -175,6 +175,7 @@ This extension also introduces USM memory allocation functions with `properties` If the parameter of type `size_t` has value `A` and the compile-time constant `alignment` property has value `B`, the resulting pointer will be both `A`-byte aligned and `B`-byte aligned, as well as `C`-byte aligned, where `C` is the least common multiple of `A` and `B`. +Note that the `alignment` property will not be on the returned `annotated_ptr` (unless it is passed to the function), because the alignment is only known at runtime and not at compile-time. [source,c++] ---- using namespace sycl::ext::oneapi::experimental; @@ -184,14 +185,17 @@ properties P11{alignment<8>}; // APtr13 is of type annotated_ptr})> // The raw pointer of APtr13 is 64-byte aligned +// Note: APtr13 does not have the alignment property. The alignment is runtime information. auto APtr13 = aligned_alloc_device_annotated(N, q, 64 /* alignment */); // APtr14 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr14 is 64-byte aligned +// Note: APtr14 has the alignment property because P10 contains the alignment property auto APtr14 = aligned_alloc_device_annotated(N, q, 64, P10); // APtr15 is of type annotated_ptr, usm_kind})> // The raw pointer of APtr15 is 128-byte aligned +// Note: APtr15 has the alignment property with value 64, because this is the alignment known at compile-time auto APtr15 = aligned_alloc_device_annotated(N, q, 128, P10); // APtr16 is of type annotated_ptr, usm_kind})> @@ -260,7 +264,7 @@ The functions in <> allocate device USM. On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory leak. If there are not enough resources to allocate the requested memory, -these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. +these functions return an `annotated_ptr` containing a null raw pointer. [[table.usm.device.allocs]] @@ -477,7 +481,7 @@ The functions in <> allocate host USM. On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory leak. If there are not enough resources to allocate the requested memory, -these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. +these functions return an `annotated_ptr` containing a null raw pointer. [[table.usm.host.allocs]] @@ -663,7 +667,7 @@ The functions in <> allocate shared USM. On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory leak. If there are not enough resources to allocate the requested memory, -these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. +these functions return an `annotated_ptr` containing a null raw pointer. [[table.usm.shared.allocs]] .Shared USM Allocation Functions with properties Support @@ -885,7 +889,7 @@ the `errc::feature_not_supported` error code. On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory leak. If there are not enough resources to allocate the requested -memory, these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. +memory, these functions return an `annotated_ptr` containing a null raw pointer. [[table.usm.param.allocs]] @@ -1113,7 +1117,7 @@ the `errc::feature_not_supported` error code. On success, these functions return an `annotated_ptr` containing a raw pointer to the newly allocated memory, which must eventually be deallocated with `sycl::ext::oneapi::experimental::free` or `sycl::free` in order to avoid a memory leak. If there are not enough resources to allocate the requested -memory, these functions return an `annotated_ptr` containing a raw pointer that is `nullptr`. +memory, these functions return an `annotated_ptr` containing a null raw pointer. [[table.usm.additional.allocs]] @@ -1237,7 +1241,7 @@ a| sycl::ext::oneapi::experimental::alignment | If this property is passed to a USM memory allocation function with `properties` support, it instructs the runtime to allocate memory with this alignment in bytes. -The set of allowed alignments is implementation defined. Specifying an alignment that is not supported causes the allocation function to return an `annotated_ptr` containing a raw pointer that is `nullptr`. +The set of allowed alignments is implementation defined. Specifying an alignment that is not supported causes the allocation function to return an `annotated_ptr` containing a null raw pointer. | link:../proposed/sycl_ext_oneapi_annotated_ptr.asciidoc[sycl_ext_oneapi_annotated_ptr] |==== From b370b8503595bac841870d19b3ca191371a2f521 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Fri, 3 Feb 2023 09:55:17 -0800 Subject: [PATCH 15/16] Added the convenience vars usm_kind_[host|device|shared]. Added the property key. --- ..._ext_oneapi_usm_malloc_properties.asciidoc | 41 +++++++++++++++---- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index fb01da1ebb545..0093921f470f1 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -1199,7 +1199,8 @@ a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. a@ -[source] +[---- +source] ---- template > lists the new properties introduced by this .New compile-time constant properties introduced by this extension [options="header"] |==== -|Property|Values|Description|Supported By +|Property|Description|Supported By a| -sycl::ext::oneapi::experimental::usm_kind -| -sycl::usm::alloc::host -sycl::usm::alloc::device -sycl::usm::alloc::shared +`sycl::ext::oneapi::experimental::usm_kind` | Indicates the kind of USM memory accessed by dereferencing this pointer and pointers derived from this pointer. Instructs the runtime to allocate USM memory of this kind. + +`kind` can be one of: + +`sycl::usm::alloc::host` + +`sycl::usm::alloc::device` + +`sycl::usm::alloc::shared` + + +For convenience, the following variables are provided: +`sycl::ext::oneapi::experimental::usm_kind_host` + +`sycl::ext::oneapi::experimental::usm_kind_device` + +`sycl::ext::oneapi::experimental::usm_kind_shared` | `annotated_ptr`, + and the USM memory allocation functions with `properties` support defined in this extension. @@ -1271,6 +1279,25 @@ and the USM memory allocation functions with `properties` support defined in thi The `sycl::ext::oneapi::experimental::usm_kind` property is a compile-time constant property with a single non-type parameter. This parameter is a value belonging to the enumeration `sycl::usm::alloc`. The `sycl::ext::oneapi::experimental::usm_kind` property is supported by `annotated_ptr` and the USM memory allocation functions defined in this extension. +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { +struct usm_kind_key { + template + using value_t = sycl::ext::oneapi::experimental::properties::property_value< + usm_kind_key, std::integral_constant>; +}; + +template +inline constexpr usm_kind_key::value_t usm_kind; + +inline constexpr usm_kind_key::value_t usm_kind_host; +inline constexpr usm_kind_key::value_t usm_kind_device; +inline constexpr usm_kind_key::value_t usm_kind_shared; + +} +---- + === Deallocation This extension introduces two new functions called `sycl::ext::oneapi::experimental::free` that take an `annotated_ptr` as argument. These functions deallocate the memory pointed to by the raw pointer belonging to the `annotated_ptr`. The new deallocation functions are listed in Table <>. These functions belong to the namespace `sycl::ext::oneapi::experimental`. From d2d7ce71b66af2b567b9a91ea2e7557b7cb714c2 Mon Sep 17 00:00:00 2001 From: "Davies, Jessica" Date: Wed, 8 Feb 2023 14:03:58 -0800 Subject: [PATCH 16/16] Fix typo. --- .../proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc index 0093921f470f1..979aba24c1a3b 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_usm_malloc_properties.asciidoc @@ -1199,8 +1199,7 @@ a@ Simplified form where `syclQueue` provides the `context` and any necessary `device`. a@ -[---- -source] +[source] ---- template