From 46487a3b34f9e6d887c2d9a00128966f6bc33f47 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Fri, 18 Apr 2025 03:13:10 -0700 Subject: [PATCH 01/47] [KHR] Provide an alternative to This PR aims to address KhronosGroup/SYCL-Docs#780 by introducing a new KHR extension that document more headers that SYCL applications can include for better control of what they pay for in terms of compile time. --- adoc/chapters/architecture.adoc | 1 + adoc/chapters/device_compiler.adoc | 2 +- adoc/chapters/programming_interface.adoc | 9 + adoc/extensions/index.adoc | 1 + adoc/extensions/sycl_khr_includes.adoc | 610 +++++++++++++++++++++++ 5 files changed, 622 insertions(+), 1 deletion(-) create mode 100644 adoc/extensions/sycl_khr_includes.adoc diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index 4b06f72b3..cc190a182 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -1758,6 +1758,7 @@ code as well as the <> for the As in the <> case, each <> could either contain native device ISA or an intermediate language. +[[subsec:library-only]] === Library-only implementation It is also possible to implement SYCL purely as a library, using an diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index d37574999..6c3e05817 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -342,7 +342,7 @@ double |==== - +[[sec:preprocessor-directives-and-macros]] == Preprocessor directives and macros The standard {cpp} preprocessing directives and macros are supported. diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index c0193c56a..52033d38d 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -599,6 +599,7 @@ A SYCL implementation or a <> may provide additional properties other than those defined here, provided they are defined in accordance with the requirements described in <>. +[[subsec:properties-interface]] ==== Properties interface Each of the runtime classes mentioned above must provide a common interface of @@ -4834,6 +4835,7 @@ template typename Param::return_type get_profiling_info() const |==== +[[sec:event-info-descriptors]] ==== Event information and profiling descriptors An <> can be queried for information using the [code]#get_info# member @@ -7213,6 +7215,7 @@ being constructed, so they are described more fully below in the section that pertains to each of the accessor types. +[[sec:accessor-properties]] ==== Properties All accessor constructors accept a [code]#property_list# parameter, which @@ -16931,6 +16934,7 @@ _Throws:_ the <> that corresponds with [code]#Param# is different from the <> that is associated with this kernel bundle. +[[sec:kernel-info-descriptors]] ==== Kernel information descriptors A <> can be queried for information using the [code]#get_info()# member @@ -17254,6 +17258,7 @@ declarable ([code]#std::complex#). include::{code_dir}/lambdaNameExamples.cpp[lines=4..-1] ---- +[[subsec:is-device-copyable-type-trait]] === [code]#is_device_copyable# type trait .... @@ -21782,6 +21787,7 @@ described in <>. It is undefined behavior for any group function to be invoked within a [code]#parallel_for_work_group# or [code]#parallel_for_work_item# context. +[[subsec:group-type-traits]] ==== Group type trait [source,,linenums] @@ -25274,6 +25280,7 @@ The return type is [code]#NonScalar# unless [code]#NonScalar# is the ''' +[[sec:native-precision-math-functions]] === Native precision math functions This section describes the native precision math functions that are available in @@ -25712,6 +25719,7 @@ The return type is [code]#NonScalar# unless [code]#NonScalar# is the ''' +[[sec:half-precision-math-functions]] === Half precision math functions This section describes the half precision math functions that are available in @@ -26968,6 +26976,7 @@ The return type is [code]#Int32Bit1# unless [code]#Int32Bit1# is the ''' +[[sec:common-functions]] === Common functions This section describes the common functions that are available in the diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc index 1a13364ad..70b0a37cf 100644 --- a/adoc/extensions/index.adoc +++ b/adoc/extensions/index.adoc @@ -11,3 +11,4 @@ specification, but their design is subject to change. // include::sycl_khr_extension_name.adoc[leveloffset=2] include::sycl_khr_default_context.adoc[leveloffset=2] +include::sycl_khr_includes.adoc[leveloffset=2] diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc new file mode 100644 index 000000000..3d9d4e8c4 --- /dev/null +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -0,0 +1,610 @@ +[[sec:khr-includes]] += sycl_khr_includes + +The core SYCL specification says that all APIs provided by the specification are +accessible through single [code]## header file. + +That leads to increased compilation times, because SYCL users have to pay for +features that they are not even using. Moreover, the situation doesn't scale +well with more extensions being proposed. + +This extension provides an alternative set of header files which provide +limited set of APIs each, thus allowing user to avoid paying compilation time +cost for features that are not used by an application. + +The alternative set of headers provided by this extension does not introduce +any new functionality, but simply provides an alternative way of accessing the +core SYCL 2020 features with less compile-time overhead on features unused by +an application. + +[[sec:khr-includes-dependencies]] +== Dependencies + +This extension has no dependencies on other extensions. However, other +extensions may not be adapted to be used together with this extension. See +<> for more details about this. + +[[sec:khr-includes-feature-test]] +== Feature test macro + +An implementation supporting this extension must predefine the macro +[code]#SYCL_KHR_INCLUDES# to one of the values defined in the table +below. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +[NOTE] +==== +Please note that an implementation may choose the +<> to implementing the SYCL +specification and therefore it won't be possible for it to predefine any macro +outside of header files. See <> below +about performing a portable check for this extension. +==== + +[[sec:khr-includes-full-list-of-headers]] +== Extension overview + +The <> below provides a list of all new +headers with high-level description of their content. + +All headers are provided under [code]## include path. + +The Description column in the table is non-formative and intended to help you +navigate the extension document quicker. Formal description of each new header +file is provided in subsequent sections below. + +[[table.khr-includes-list]] +.List of headers provided by the extension +[width="100%",options="header",cols="1,2"] +|==== +|Header +|Description + +|[code]## +|This header contains all macro definitions provided by the implementation + +|[code]## +|This header covers queue operations. It contains definitions of [code]#queue#, +[code]#handler# and [code]#event# class. If you don't use events and/or only +use [code]#queue# shortcut functions, then it is recommended to include those +classes individually through the corresponding headers. + +|[code]## +|Contains definition of [code]#queue# class. + +|[code]## +|Contains definition of [code]#handler# class. + +|[code]## +|Contains definition of [code]#event# class. + +|[code]## +|Contains definitions of [code]#device#, [code]#platform# and [code]#context# +classes, as well as device selectors. + +|[code]## +|Contains definitions of [code]#id#, [code]#range#, [code]#nd_item#, +[code]#nd_range# and [code]#item# classes + +|[code]## +|Contains definition of [code]#usm_allocator# class and USM free functions for +memory management (like [code]#malloc_shared#). + +|[code]## +|Contains definition of [code]#buffer# class + +|[code]## +|Contains definitions of [code]#accessor#, [code]#local_accessor# and +[code]#host_accessor# classes. + +|[code]## +|Contains definition of [code]#atomic_ref# class + +|[code]## +|Contains definition of [code]#half# class + +|[code]## +|Contains definition of [code]#vec# class + +|[code]## +|Contains definition of [code]#marray# class + +|[code]## +|This header provides access to the corresponding group of built-in +functions defined by <> + +|[code]## +|This header provides access to [code]#group# and [code]#sub_group# classes, as +well as operations that can be performed with them such as broadcasts or scans + +|[code]## +|This header provides access to [code]#multi_ptr# class and related address +space class aliases + +|[code]## +|This header provides access to function objects like [code]#plus# or +[code]#locial_or# defined by <> + +|[code]## +|This header provides access to functionality related to reductions (such as +[code]#reduction# interface and [code]#reducer class) + +|[code]## +|Contains definition of [code]#stream# class + +|[code]## +|Contains definitions of various type traits like [code]#is_property#, +[code]#is_group#, [code]#is_device_copyable#, etc. + +|[code]## +|Contains definition of [code]#property_list# class + +|[code]## +|Contains definitions of [code]#kernel_bundle#, [code]#kernel#, +[code]#kernel_id#, [code]#device_image# and [code]#specialization_id# classes + +|[code]## +|Contains definitions of [code]#sampler#, [code]#sampled_image#, +[code]#unsampled_image# and corresponding accessors + +|[code]## +|This header provides access to error handling APIs + +|[code]## +|Contains definition of [code]#private_memory# and [code]#h_item# + +|[code]## +|Contains definition of [code]#interop_handle# class + +|[code]## +|Contains definition of [code]#backend_traits# and [code]#make_*# functions + +|[code]##, [code]## +|Headers in this set match by name with those provided by the next C++ +specification. They contain pre-adopted features from that standard. + +|[code]## +|Contains definition of [code]#byte# alias +|==== + +Classes, constants, types and functions provided by the headers listed above +exist within the [code]#::sycl# namespace as with the standard +[code]## header. + +Note: there is no strict requirement for the content of those headers, i.e. they +may contain other functions and classes than documented in this extension. In +fact, some classes, functions or enumerations are documented to be available +through multiple headers. Nevertheless, implementations are encouraged to keep +headers contents as small as reasonably possible to provide maximum benefit for +users. + +[[sec:khr-includes-version]] +=== [code]## header + +This header contains definitions of: +- [code]#SYCL_KHR_INCLUDES# macro +- All macro defined by <> +- All macro defined by other extensions supported by an implementation + +[code]## header is included by every other header +documented by this extension, as well as [code]##. + +There is no guarantee that the aforementioned macro are defined before the +inclusion point of [code]##. + +{note}Implementations providing a dedicated SYCL compiler can predefine those +macro within the compiler. However, the SYCL standard allows for library-only +implementations and therefore a portable application should not assume that +any macro definitions are available until [code]## is +included.{endnote} + +To properly detect in a portable way if this extension is supported by an +implementation, the following approach should be used: + +[source] +---- +#if __has_include() +// The extension is supported, but the SYCL_KHR_INCLUDES is not +// guaranteed to be defined at this point for library-only implementations + +#include +// Now the SYCL_KHR_INCLUDES macro is guaranteed to be defined for all kinds of +// implementations + +// Use the extension +#include + +#else +// Extension is not supported by an implementation +// Fallback to the core SYCL standard +#include +#endif +---- + +[[sec:khr-includes-backend]] +=== [code]## header + +This header file contains everything related to SYCL backend APIs: + +- [code]#enum class backend# +- [code]#backend_traits# +- [code]#get_native# +- [code]#make_*# + +Note that even though functions defined in the header operate with various +classes like [code]#platform# or [code]#queue#, there is no guarantee that +the [code]## header provides full definitions for +those classes. In order to write a portable program, additional [code]##include# +directives must be used in a SYCL program to ensure availability of the +corresponding classes. + +[[sec:khr-includes-runtime]] +=== [code]## header + +This header groups most of classes defined by 4.6 SYCL runtime classes. +It includes: + +- [code]#default_selector_v#, [code]#gpu_selector_v#, + [code]#accelerator_selector_v#, [code]#cpu_selector_v#, + [code]#aspect_selector# +- [code]#platform# class +- All [code]#info::platform# information descriptors defined by + <> +- [code]#context# class +- All [code]#info::context# information descriptors defined by + <> +- [code]#device# class +- All [code]#info::device# information descriptors defined by + <> +- All other enumerations defined by <> +- [code]#enum class aspect# + +[[sec:khr-includes-submit]] +=== [code]## header + +This is a convenience header, which simply groups other headers to a single +common entry point. It includes: + +- [code]## +- [code]## +- [code]## + +[[sec:khr-includes-queue]] +=== [code]## header + +This header contains: + +- [code]#queue# class +- All [code]#info::queue# information descriptors defined by + <> +- All [code]#properties::queue# types defined by <> + +[[sec:khr-includes-handler]] +=== [code]## header + +This header contains: + +- [code]#handler# class + +[[sec:khr-includes-event]] +=== [code]## header + +This header contains: + +- [code]#event# class +- All [code]#info::event# information descriptors defined by + <> + +[[sec:khr-includes-buffer]] +=== [code]## header + +This header contains: + +- [code]#buffer# class +- [code]#buffer_allocator# +- All [code]#property::buffer# types defined by <> + +[[sec:khr-includes-image]] +=== [code]## header + +This header contains: + +- [code]#unsampled_image# and [code]#sampled_image# classes +- [code]#image_allocator# +- All [code]#property::image# types defined by <> +- [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, + [code]#host_unsampled_image_accessor# and [code]#host_sampled_image_accessor# + classes +- [code]#property::no_init# and [code]#no_init# defined by + <> +- [code]#addresing_mode#, [code]#filtering_mode#, + [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# + struct + +[[sec:khr-includes-accessor]] +=== [code]## header + +This header contains: + +- [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes +- [code]#property::no_init# and [code]#no_init# defined by + <> + +[[sec:khr-includes-multi-ptr]] +=== [code]## header + +This header contains: + +- [code]#multi_ptr# class +- [code]#address_space#, [code]#decorated# enumerations +- [code]#remove_decoration# type trait +- [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and + other aliases defined by <> + +[[sec:khr-includes-hierarchical-parallelism]] +=== [code]## header + +This header contains: + +- [code]#private_memory# and [code]#h_item# classes + +[[sec:khr-includes-usm]] +=== [code]## header + +This header gives access to functionality defined by <>. Specifically, +it contains: + +- [code]#usm::alloc# enumeration +- [code]#usm_allocator# class +- Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, + [code]#malloc# and [code]#get_pointer_type# as defined by sections + 4.8.3 USM allocations and 4.8.4 Unified shared memory pointer queries + +[[sec:khr-includes-index-space]] +=== [code]## header + +This header gives access to ranges and index space identifiers that are defined +by the section 4.9.1 Ranges and index space identifiers. Specifically, it +contains: + +- [code]#id# +- [code]#item# +- [code]#nd_item# +- [code]#range# +- [code]#nd_range# + +[[sec:khr-includes-reduction]] +=== [code]## header + +This header gives access to functionality related to reductions as defined by +<> + +It contains: + +- [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# + and [code]#has_known_identity_v# type traits +- [code]#reduction# interface +- [code]#property::reduction::initialize_to_identity# property +- [code]#reducer# class +- All [code]#property::reduction# types defined by <> + +This header also includes [code]## for convenience + +[[sec:khr-includes-interop-handle]] +=== [code]## header + +This header contains: + +- [code]#interop_handle# class + +[[sec:khr-includes-kernel-bundle]] +=== [code]## header + +This header gives access to kernel bundles and related functionality as defined +by <>. It +contains: + +- [code]#bundle_state# enumeration +- [code]#kernel_id#, [code]#kernel#, [code]#device_image# and + [code]#kernel_bundle# classes +- All [code]#info::kernel# information descriptors defined by + <> +- Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, + [code]#compile#, [code]#link# +- [code]#specialization_id# class + +[[sec:khr-includes-exception]] +=== [code]## header + +This header gives access to error handling APIs defined by <>. +It contains: + +- [code]#async_handler# alias +- [code]#exception# and [code]#exception_list# classes +- [code]#errc# enumeration +- [code]#make_error_code# and [code]#sycl_category# free functions +- [code]#std::is_error_code_enum# type trait specialization for + [code]#sycl::errc# + +[[sec:khr-includes-half]] +=== [code]## header + +This header contains definition of [code]#half# class + +[[sec:khr-includes-vec]] +=== [code]## header + +This header gives access to [code]#vec# class defined by <>. +It contains: + +- [code]#rounding_mode# enumeration +- [code]#elem# struct and [code]#vec# class +- Type aliases defined by the section 4.14.2.2 Aliases +- [code]#__writeable_swizzle__# and [code]#__const_swizzle__# classes defined + by <> + +Note that the simple swizzle functions ([code]#XYZW_SWIZZLE# and +[code]#RGBA_SWIZZLE# defined by the table 123) are only available when the macro +[code]#SYCL_SIMPLE_SWIZZLES# is defined before including +[code]##. + +[[sec:khr-includes-marray]] +=== [code]## header + +This header gives access to math array types defined by <>. +It contains: + +- [code]#marray# class +- Type aliases defined by the section 4.14.3.2 Aliases + +[[sec:khr-includes-atomic]] +=== [code]## header + +This header contains: +- [code]#atomic_fence# function +- [code]#memory_order#, [code]#memory_scope# enumerations +- [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined + by <> +- [code]#atomic# class and free functions like [code]#atomic_store#, + [code]#atomic_fetch_and# as defined by the section 4.15.4 Atomic types + (deprecated) + +[[sec:khr-includes-stream]] +=== [code]## header + +This header gives access to [code]#stream# class and related functionality +described by <>. It contains: + +- [code]#stream_manipulator# enumeration and corresponding constants (like + [code]#flush# or [code]#endl#) +- [code]#setprecision# and [code]#setw# functions +- [code]#stream# class +- [code]#template const stream& operator<<(const stream& os, const T& rhs)# + operator + +[[sec:khr-includes-type-traits]] +=== [code]## header + +This header contains: + +- [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and + [code]#is_property_of_v# defined by <> +- [code]#is_group# and [code]#is_group_v# defined by + <> +- [code]#is_device_copyable# defined by <> +- [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# + and [code]#all_devices_have_v# defined by <> + +[[sec:khr-includes-property-list]] +=== [code]## header + +This header contains: + +- [code]#property_list# class definition + +[[sec:khr-includes-functional]] +=== [code]##header + +This header contains: +- [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, + [code]#bit_xor#, [code]#logical_and#, [code]#logical_or#, + [code]#minimum#, [code]#maximum# structs + +[[sec:khr-includes-groups]] +=== [code]## header + +This header gives access to group classes and algorithms library as defined +by sections <>, <>, <> and +<>. It contains: + +- [code]#group# and [code]#sub_group# classes +- [code]#device_event# class +- [code]#group_broadcast#, [code]#group_barrier# functions +- [code]#any_of#, [code]#all_of#, [code]#none_of#, [code]#shift_left#, + [code]#shift_right#, [code]#permute#, [code]#select#, [code]#reduce#, + [code]#exclusive_scan_over_group#, [code]#inclusive_scan_over_group#, + [code]#joint_exclusive_scan# and [code]#joint_inclusive_scan# functions + +[[sec:khr-includes-math]] +=== [code]## header + +This header includes all SYCL built-in functions documented by sections: + +- <> +- <> +- <> +- <> +- <> +- <> +- <> + +[[sec:khr-includes-bit]] +=== [code]## header + +This header contains definition of [code]#bit_cast# pre-adopted from the next +C++ specification. + +[[sec:khr-includes-span]] +=== [code]## header + +This header contains definitions of [code]#span# and [code]#dynamic_extent# +pre-adopted from the next C++ specification. + +[[sec:khr-includes-byte]] +=== [code]## header + +This header contains definition of [code]#byte# type alias + +[[sec:khr-includes-macro]] +=== Preprocessor directives and macros + +In case a SYCL implementation is made using library-only approach, macros +defined by the section 5.6 Preprocessor directives and macros should be +available regardless of which one of the headers introduced by this extension is +included. + +For example, [code]#SYCL_LANGUAGE_VERSION# macro should be available even if +a translation unit within an application only includes +[code]## header. + +[[sec:khr-includes-other-extensions]] +=== Co-existence with other extensions + +The ultimate source of truth about accessibility of an extension through a set +of fine-grained headers is an extension specification itself. However, there are +many existing extensions which may not have been updated to account for this +extension. + +Therefore, any extension which does not explicitly document how can it +be accessed through header files, should be assumed to be available through +[code]## only. + +{note}It _may_ seem safe to assume that if an extension modifies some existing +class, then its functionality should be available through a header file which +exposes that class. However, there exist implementation possibilities where this +won't be the case and therefore this assumption is not safe to make for +applications that aim to be portable between SYCL implementations.{endnote} + +If an implementation supports this extension together with other extensions, +then any macro defined by other extensions myst be made available through +[code]## header. + +== Open issues/questions + +- Should we put [code]#remove_decoration# into + [code]## (currently resides in + [code]##)? +- The proposal says that simple swizzle functions are only available if + [code]#SYCL_SIMPLE_SWIZZLES# is defined _before_ including + [code]##, but what if an implementation needs + [code]#vec# class for some other things? An example could be math built-in + functions. Need to evaluate if the proposed wording is actually implementable + and possibly change it. From 2f70d45aaef845bd58f590cd75eda3dea70dc932 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 27 May 2025 12:21:21 +0200 Subject: [PATCH 02/47] Fix formatting --- adoc/extensions/sycl_khr_includes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 3d9d4e8c4..ae256a6b1 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -135,7 +135,7 @@ space class aliases |[code]## |This header provides access to functionality related to reductions (such as -[code]#reduction# interface and [code]#reducer class) +[code]#reduction# interface and [code]#reducer# class) |[code]## |Contains definition of [code]#stream# class From 35394ca62e02016a523e4ec81eec93aadf82c2d4 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 27 May 2025 12:22:41 +0200 Subject: [PATCH 03/47] Move `remove_decoration` into type traits header --- adoc/extensions/sycl_khr_includes.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index ae256a6b1..5066dd472 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -345,7 +345,6 @@ This header contains: - [code]#multi_ptr# class - [code]#address_space#, [code]#decorated# enumerations -- [code]#remove_decoration# type trait - [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and other aliases defined by <> @@ -502,6 +501,7 @@ This header contains: - [code]#is_device_copyable# defined by <> - [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# and [code]#all_devices_have_v# defined by <> +- [code]#remove_decoration# type trait [[sec:khr-includes-property-list]] === [code]## header @@ -599,9 +599,6 @@ then any macro defined by other extensions myst be made available through == Open issues/questions -- Should we put [code]#remove_decoration# into - [code]## (currently resides in - [code]##)? - The proposal says that simple swizzle functions are only available if [code]#SYCL_SIMPLE_SWIZZLES# is defined _before_ including [code]##, but what if an implementation needs From ba0812d5b01c7528617baae93bddef40b6fe03df Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 27 May 2025 14:38:50 +0200 Subject: [PATCH 04/47] Generalize guarantees about headers content --- adoc/extensions/sycl_khr_includes.adoc | 29 ++++++++++++++------------ 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 5066dd472..602bb7c99 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -179,12 +179,22 @@ Classes, constants, types and functions provided by the headers listed above exist within the [code]#::sycl# namespace as with the standard [code]## header. -Note: there is no strict requirement for the content of those headers, i.e. they -may contain other functions and classes than documented in this extension. In -fact, some classes, functions or enumerations are documented to be available -through multiple headers. Nevertheless, implementations are encouraged to keep -headers contents as small as reasonably possible to provide maximum benefit for -users. +There is no guarantee that headers documented by this extension contain anything +else besides things listed in sections below. For example, [code]#queue# class +has methods which accept [code]#accessor# object, but +[code]## is not required to provide [code]#accessor# +definition. Therefore, a portable application should include the corresponding +header to get [code]#accessor# definition explicitly. + +[NOTE] +==== +However, there is no requirement for the implementations to **only** provide +through those headers exactly what's specified, i.e. they may contain other +functions and classes than documented in this extension. In fact, some classes, +functions or enumerations are documented to be available through multiple +headers. Nevertheless, implementations are encouraged to keep headers contents +as small as reasonably possible to provide maximum benefit for users. +==== [[sec:khr-includes-version]] === [code]## header @@ -239,13 +249,6 @@ This header file contains everything related to SYCL backend APIs: - [code]#get_native# - [code]#make_*# -Note that even though functions defined in the header operate with various -classes like [code]#platform# or [code]#queue#, there is no guarantee that -the [code]## header provides full definitions for -those classes. In order to write a portable program, additional [code]##include# -directives must be used in a SYCL program to ensure availability of the -corresponding classes. - [[sec:khr-includes-runtime]] === [code]## header From 0963fdb4953f144ab200b558f20663ed03dbf468 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 27 May 2025 17:32:40 +0200 Subject: [PATCH 05/47] Split and remove runtime include --- adoc/extensions/sycl_khr_includes.adoc | 40 ++++++++++++++++++-------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 602bb7c99..117637b16 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -86,9 +86,14 @@ classes individually through the corresponding headers. |[code]## |Contains definition of [code]#event# class. -|[code]## -|Contains definitions of [code]#device#, [code]#platform# and [code]#context# -classes, as well as device selectors. +|[code]## +|Contains definitions of [code]#device# class and device selectors + +|[code]## +|Contains definition of [code]#platform# class + +|[code]## +|Contains definition of [code]#context# class |[code]## |Contains definitions of [code]#id#, [code]#range#, [code]#nd_item#, @@ -249,26 +254,37 @@ This header file contains everything related to SYCL backend APIs: - [code]#get_native# - [code]#make_*# -[[sec:khr-includes-runtime]] -=== [code]## header +[[sec:khr-includes-device]] +=== [code]## header -This header groups most of classes defined by 4.6 SYCL runtime classes. -It includes: +This header gives access to: - [code]#default_selector_v#, [code]#gpu_selector_v#, [code]#accelerator_selector_v#, [code]#cpu_selector_v#, [code]#aspect_selector# +- [code]#device# class +- All [code]#info::device# information descriptors defined by + <> +- All other enumerations defined by <> +- [code]#enum class aspect# + +[[sec:khr-includes-platform]] +=== [code]## header + +This header gives access to: + - [code]#platform# class - All [code]#info::platform# information descriptors defined by <> + +[[sec:khr-includes-context]] +=== [code]## header + +This header gives access to: + - [code]#context# class - All [code]#info::context# information descriptors defined by <> -- [code]#device# class -- All [code]#info::device# information descriptors defined by - <> -- All other enumerations defined by <> -- [code]#enum class aspect# [[sec:khr-includes-submit]] === [code]## header From 5214772887c0f137728b3d9558c84556dc1d5936 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 3 Jun 2025 11:20:38 +0200 Subject: [PATCH 06/47] Fix section reference --- adoc/extensions/sycl_khr_includes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 117637b16..6e85cd272 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -206,7 +206,7 @@ as small as reasonably possible to provide maximum benefit for users. This header contains definitions of: - [code]#SYCL_KHR_INCLUDES# macro -- All macro defined by <> +- All macro defined by <> - All macro defined by other extensions supported by an implementation [code]## header is included by every other header From 736fe3e650a3ecbb65b1f2effe81e660b588235e Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 11 Jun 2025 16:14:28 +0200 Subject: [PATCH 07/47] Add .hpp extension to new headers --- adoc/extensions/sycl_khr_includes.adoc | 161 +++++++++++++------------ 1 file changed, 81 insertions(+), 80 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 6e85cd272..3bacbb9ec 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -68,115 +68,115 @@ file is provided in subsequent sections below. |Header |Description -|[code]## +|[code]## |This header contains all macro definitions provided by the implementation -|[code]## +|[code]## |This header covers queue operations. It contains definitions of [code]#queue#, [code]#handler# and [code]#event# class. If you don't use events and/or only use [code]#queue# shortcut functions, then it is recommended to include those classes individually through the corresponding headers. -|[code]## +|[code]## |Contains definition of [code]#queue# class. -|[code]## +|[code]## |Contains definition of [code]#handler# class. -|[code]## +|[code]## |Contains definition of [code]#event# class. -|[code]## +|[code]## |Contains definitions of [code]#device# class and device selectors -|[code]## +|[code]## |Contains definition of [code]#platform# class -|[code]## +|[code]## |Contains definition of [code]#context# class -|[code]## +|[code]## |Contains definitions of [code]#id#, [code]#range#, [code]#nd_item#, [code]#nd_range# and [code]#item# classes -|[code]## +|[code]## |Contains definition of [code]#usm_allocator# class and USM free functions for memory management (like [code]#malloc_shared#). -|[code]## +|[code]## |Contains definition of [code]#buffer# class -|[code]## +|[code]## |Contains definitions of [code]#accessor#, [code]#local_accessor# and [code]#host_accessor# classes. -|[code]## +|[code]## |Contains definition of [code]#atomic_ref# class -|[code]## +|[code]## |Contains definition of [code]#half# class -|[code]## +|[code]## |Contains definition of [code]#vec# class -|[code]## +|[code]## |Contains definition of [code]#marray# class -|[code]## +|[code]## |This header provides access to the corresponding group of built-in functions defined by <> -|[code]## +|[code]## |This header provides access to [code]#group# and [code]#sub_group# classes, as well as operations that can be performed with them such as broadcasts or scans -|[code]## +|[code]## |This header provides access to [code]#multi_ptr# class and related address space class aliases -|[code]## +|[code]## |This header provides access to function objects like [code]#plus# or [code]#locial_or# defined by <> -|[code]## +|[code]## |This header provides access to functionality related to reductions (such as [code]#reduction# interface and [code]#reducer# class) -|[code]## +|[code]## |Contains definition of [code]#stream# class -|[code]## +|[code]## |Contains definitions of various type traits like [code]#is_property#, [code]#is_group#, [code]#is_device_copyable#, etc. -|[code]## +|[code]## |Contains definition of [code]#property_list# class -|[code]## +|[code]## |Contains definitions of [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, [code]#device_image# and [code]#specialization_id# classes -|[code]## +|[code]## |Contains definitions of [code]#sampler#, [code]#sampled_image#, [code]#unsampled_image# and corresponding accessors -|[code]## +|[code]## |This header provides access to error handling APIs -|[code]## +|[code]## |Contains definition of [code]#private_memory# and [code]#h_item# -|[code]## +|[code]## |Contains definition of [code]#interop_handle# class -|[code]## +|[code]## |Contains definition of [code]#backend_traits# and [code]#make_*# functions -|[code]##, [code]## +|[code]##, [code]## |Headers in this set match by name with those provided by the next C++ specification. They contain pre-adopted features from that standard. -|[code]## +|[code]## |Contains definition of [code]#byte# alias |==== @@ -187,7 +187,7 @@ exist within the [code]#::sycl# namespace as with the standard There is no guarantee that headers documented by this extension contain anything else besides things listed in sections below. For example, [code]#queue# class has methods which accept [code]#accessor# object, but -[code]## is not required to provide [code]#accessor# +[code]## is not required to provide [code]#accessor# definition. Therefore, a portable application should include the corresponding header to get [code]#accessor# definition explicitly. @@ -202,23 +202,23 @@ as small as reasonably possible to provide maximum benefit for users. ==== [[sec:khr-includes-version]] -=== [code]## header +=== [code]## header This header contains definitions of: - [code]#SYCL_KHR_INCLUDES# macro - All macro defined by <> - All macro defined by other extensions supported by an implementation -[code]## header is included by every other header +[code]## header is included by every other header documented by this extension, as well as [code]##. There is no guarantee that the aforementioned macro are defined before the -inclusion point of [code]##. +inclusion point of [code]##. {note}Implementations providing a dedicated SYCL compiler can predefine those macro within the compiler. However, the SYCL standard allows for library-only implementations and therefore a portable application should not assume that -any macro definitions are available until [code]## is +any macro definitions are available until [code]## is included.{endnote} To properly detect in a portable way if this extension is supported by an @@ -226,16 +226,16 @@ implementation, the following approach should be used: [source] ---- -#if __has_include() +#if __has_include() // The extension is supported, but the SYCL_KHR_INCLUDES is not // guaranteed to be defined at this point for library-only implementations -#include +#include // Now the SYCL_KHR_INCLUDES macro is guaranteed to be defined for all kinds of // implementations // Use the extension -#include +#include #else // Extension is not supported by an implementation @@ -245,7 +245,7 @@ implementation, the following approach should be used: ---- [[sec:khr-includes-backend]] -=== [code]## header +=== [code]## header This header file contains everything related to SYCL backend APIs: @@ -255,7 +255,7 @@ This header file contains everything related to SYCL backend APIs: - [code]#make_*# [[sec:khr-includes-device]] -=== [code]## header +=== [code]## header This header gives access to: @@ -269,7 +269,7 @@ This header gives access to: - [code]#enum class aspect# [[sec:khr-includes-platform]] -=== [code]## header +=== [code]## header This header gives access to: @@ -278,7 +278,7 @@ This header gives access to: <> [[sec:khr-includes-context]] -=== [code]## header +=== [code]## header This header gives access to: @@ -287,17 +287,17 @@ This header gives access to: <> [[sec:khr-includes-submit]] -=== [code]## header +=== [code]## header This is a convenience header, which simply groups other headers to a single common entry point. It includes: -- [code]## -- [code]## -- [code]## +- [code]## +- [code]## +- [code]## [[sec:khr-includes-queue]] -=== [code]## header +=== [code]## header This header contains: @@ -307,14 +307,14 @@ This header contains: - All [code]#properties::queue# types defined by <> [[sec:khr-includes-handler]] -=== [code]## header +=== [code]## header This header contains: - [code]#handler# class [[sec:khr-includes-event]] -=== [code]## header +=== [code]## header This header contains: @@ -323,7 +323,7 @@ This header contains: <> [[sec:khr-includes-buffer]] -=== [code]## header +=== [code]## header This header contains: @@ -332,7 +332,7 @@ This header contains: - All [code]#property::buffer# types defined by <> [[sec:khr-includes-image]] -=== [code]## header +=== [code]## header This header contains: @@ -349,7 +349,7 @@ This header contains: struct [[sec:khr-includes-accessor]] -=== [code]## header +=== [code]## header This header contains: @@ -358,7 +358,7 @@ This header contains: <> [[sec:khr-includes-multi-ptr]] -=== [code]## header +=== [code]## header This header contains: @@ -368,14 +368,14 @@ This header contains: other aliases defined by <> [[sec:khr-includes-hierarchical-parallelism]] -=== [code]## header +=== [code]## header This header contains: - [code]#private_memory# and [code]#h_item# classes [[sec:khr-includes-usm]] -=== [code]## header +=== [code]## header This header gives access to functionality defined by <>. Specifically, it contains: @@ -387,7 +387,7 @@ it contains: 4.8.3 USM allocations and 4.8.4 Unified shared memory pointer queries [[sec:khr-includes-index-space]] -=== [code]## header +=== [code]## header This header gives access to ranges and index space identifiers that are defined by the section 4.9.1 Ranges and index space identifiers. Specifically, it @@ -400,7 +400,7 @@ contains: - [code]#nd_range# [[sec:khr-includes-reduction]] -=== [code]## header +=== [code]## header This header gives access to functionality related to reductions as defined by <> @@ -414,17 +414,18 @@ It contains: - [code]#reducer# class - All [code]#property::reduction# types defined by <> -This header also includes [code]## for convenience +This header also includes [code]## for +convenience. [[sec:khr-includes-interop-handle]] -=== [code]## header +=== [code]## header This header contains: - [code]#interop_handle# class [[sec:khr-includes-kernel-bundle]] -=== [code]## header +=== [code]## header This header gives access to kernel bundles and related functionality as defined by <>. It @@ -440,7 +441,7 @@ contains: - [code]#specialization_id# class [[sec:khr-includes-exception]] -=== [code]## header +=== [code]## header This header gives access to error handling APIs defined by <>. It contains: @@ -453,12 +454,12 @@ It contains: [code]#sycl::errc# [[sec:khr-includes-half]] -=== [code]## header +=== [code]## header This header contains definition of [code]#half# class [[sec:khr-includes-vec]] -=== [code]## header +=== [code]## header This header gives access to [code]#vec# class defined by <>. It contains: @@ -472,10 +473,10 @@ It contains: Note that the simple swizzle functions ([code]#XYZW_SWIZZLE# and [code]#RGBA_SWIZZLE# defined by the table 123) are only available when the macro [code]#SYCL_SIMPLE_SWIZZLES# is defined before including -[code]##. +[code]##. [[sec:khr-includes-marray]] -=== [code]## header +=== [code]## header This header gives access to math array types defined by <>. It contains: @@ -484,7 +485,7 @@ It contains: - Type aliases defined by the section 4.14.3.2 Aliases [[sec:khr-includes-atomic]] -=== [code]## header +=== [code]## header This header contains: - [code]#atomic_fence# function @@ -496,7 +497,7 @@ This header contains: (deprecated) [[sec:khr-includes-stream]] -=== [code]## header +=== [code]## header This header gives access to [code]#stream# class and related functionality described by <>. It contains: @@ -509,7 +510,7 @@ described by <>. It contains: operator [[sec:khr-includes-type-traits]] -=== [code]## header +=== [code]## header This header contains: @@ -523,14 +524,14 @@ This header contains: - [code]#remove_decoration# type trait [[sec:khr-includes-property-list]] -=== [code]## header +=== [code]## header This header contains: - [code]#property_list# class definition [[sec:khr-includes-functional]] -=== [code]##header +=== [code]##header This header contains: - [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, @@ -538,7 +539,7 @@ This header contains: [code]#minimum#, [code]#maximum# structs [[sec:khr-includes-groups]] -=== [code]## header +=== [code]## header This header gives access to group classes and algorithms library as defined by sections <>, <>, <> and @@ -553,7 +554,7 @@ by sections <>, <>, <> and [code]#joint_exclusive_scan# and [code]#joint_inclusive_scan# functions [[sec:khr-includes-math]] -=== [code]## header +=== [code]## header This header includes all SYCL built-in functions documented by sections: @@ -566,19 +567,19 @@ This header includes all SYCL built-in functions documented by sections: - <> [[sec:khr-includes-bit]] -=== [code]## header +=== [code]## header This header contains definition of [code]#bit_cast# pre-adopted from the next C++ specification. [[sec:khr-includes-span]] -=== [code]## header +=== [code]## header This header contains definitions of [code]#span# and [code]#dynamic_extent# pre-adopted from the next C++ specification. [[sec:khr-includes-byte]] -=== [code]## header +=== [code]## header This header contains definition of [code]#byte# type alias @@ -592,7 +593,7 @@ included. For example, [code]#SYCL_LANGUAGE_VERSION# macro should be available even if a translation unit within an application only includes -[code]## header. +[code]## header. [[sec:khr-includes-other-extensions]] === Co-existence with other extensions @@ -614,13 +615,13 @@ applications that aim to be portable between SYCL implementations.{endnote} If an implementation supports this extension together with other extensions, then any macro defined by other extensions myst be made available through -[code]## header. +[code]## header. == Open issues/questions - The proposal says that simple swizzle functions are only available if [code]#SYCL_SIMPLE_SWIZZLES# is defined _before_ including - [code]##, but what if an implementation needs + [code]##, but what if an implementation needs [code]#vec# class for some other things? An example could be math built-in functions. Need to evaluate if the proposed wording is actually implementable and possibly change it. From 7e6881de691c1b75ce63aed28979b61db709795a Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 11 Jun 2025 16:20:32 +0200 Subject: [PATCH 08/47] Resolve SYCL_SIMPLE_SWIZZLES issue --- adoc/extensions/sycl_khr_includes.adoc | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 3bacbb9ec..5d0dc3d79 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -470,10 +470,11 @@ It contains: - [code]#__writeable_swizzle__# and [code]#__const_swizzle__# classes defined by <> -Note that the simple swizzle functions ([code]#XYZW_SWIZZLE# and -[code]#RGBA_SWIZZLE# defined by the table 123) are only available when the macro -[code]#SYCL_SIMPLE_SWIZZLES# is defined before including -[code]##. +In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and +[code]#RGBA_SWIZZLE# defined by the table 123) available, the macro +[code]#SYCL_SIMPLE_SWIZZLES# should be defined before *any* other +[code]#sycl/# header is included. The recommended way of doing that is through +command line options. [[sec:khr-includes-marray]] === [code]## header @@ -619,9 +620,3 @@ then any macro defined by other extensions myst be made available through == Open issues/questions -- The proposal says that simple swizzle functions are only available if - [code]#SYCL_SIMPLE_SWIZZLES# is defined _before_ including - [code]##, but what if an implementation needs - [code]#vec# class for some other things? An example could be math built-in - functions. Need to evaluate if the proposed wording is actually implementable - and possibly change it. From 6aaa8df87736d3c35e905f2abf8243d686377006 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 17 Jun 2025 16:38:44 +0200 Subject: [PATCH 09/47] WIP on unifying wording --- adoc/extensions/sycl_khr_includes.adoc | 170 +++++++++++++------------ 1 file changed, 89 insertions(+), 81 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 5d0dc3d79..0471c2668 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -69,7 +69,7 @@ file is provided in subsequent sections below. |Description |[code]## -|This header contains all macro definitions provided by the implementation +|This header provides varios macro definitions |[code]## |This header covers queue operations. It contains definitions of [code]#queue#, @@ -78,106 +78,120 @@ use [code]#queue# shortcut functions, then it is recommended to include those classes individually through the corresponding headers. |[code]## -|Contains definition of [code]#queue# class. +|This header provides defintion of the [code]#queue# class |[code]## -|Contains definition of [code]#handler# class. +|This header provides defintion of the [code]#handler# class |[code]## -|Contains definition of [code]#event# class. +|This header provides defintion of the [code]#event# class |[code]## -|Contains definitions of [code]#device# class and device selectors +|This header provides defintions of the [code]#device# class and device +selectors |[code]## -|Contains definition of [code]#platform# class +|This header provides defintion of the [code]#platform# class |[code]## -|Contains definition of [code]#context# class +|This header provides defintion of the [code]#context# class |[code]## -|Contains definitions of [code]#id#, [code]#range#, [code]#nd_item#, -[code]#nd_range# and [code]#item# classes +|This header groups together ranges and most of index space identifiers from +<> +{note} +Classes like [code]#h_item#, [code]#group# and [code]#sub_group# are provided by +other headers. +{endnote} |[code]## -|Contains definition of [code]#usm_allocator# class and USM free functions for -memory management (like [code]#malloc_shared#). +|This header provides functionality defined by <>, such as +[code]#usm_allocator# class and USM free functions for memory management +like [code]#malloc_shared#. |[code]## -|Contains definition of [code]#buffer# class +|This header provides defintion of the [code]#buffer# class |[code]## -|Contains definitions of [code]#accessor#, [code]#local_accessor# and -[code]#host_accessor# classes. +|This header provides defintions of the [code]#accessor#, [code]#local_accessor# +and [code]#host_accessor# classes. |[code]## -|Contains definition of [code]#atomic_ref# class +|This header provides defintion of the [code]#atomic_ref# class |[code]## -|Contains definition of [code]#half# class +|This header provides defintion of the [code]#half# data type |[code]## -|Contains definition of [code]#vec# class +|This header provides functionality defined by <>, i.e. +[code]#vec# class and related enumerations |[code]## -|Contains definition of [code]#marray# class +|This header provides functionality defined by <>, i.e. +[code]#marray# class |[code]## -|This header provides access to the corresponding group of built-in -functions defined by <> +|This header provides defintions of built-in functions defined by +<> |[code]## -|This header provides access to [code]#group# and [code]#sub_group# classes, as -well as operations that can be performed with them such as broadcasts or scans +|This header provides defintions of the [code]#group# and [code]#sub_group# +classes, as well as operations that can be performed with them such as +broadcasts or scans |[code]## -|This header provides access to [code]#multi_ptr# class and related address -space class aliases +|This header provides defintions of the [code]#multi_ptr# class and related +address space class aliases |[code]## -|This header provides access to function objects like [code]#plus# or +|This header provides definitions of function objects like [code]#plus# or [code]#locial_or# defined by <> |[code]## -|This header provides access to functionality related to reductions (such as -[code]#reduction# interface and [code]#reducer# class) +|This header provides definitions defined by <>, such as +[code]#reduction# interface and [code]#reducer# class |[code]## -|Contains definition of [code]#stream# class +|This header provides functionality defined by <>, i.e. +[code]#stream# class and related functions |[code]## -|Contains definitions of various type traits like [code]#is_property#, -[code]#is_group#, [code]#is_device_copyable#, etc. +|This header provides defintions of various type traits like +[code]#is_property#, [code]#is_group#, [code]#is_device_copyable#, etc. |[code]## -|Contains definition of [code]#property_list# class +|This header provides defintion of the [code]#property_list# class |[code]## -|Contains definitions of [code]#kernel_bundle#, [code]#kernel#, -[code]#kernel_id#, [code]#device_image# and [code]#specialization_id# classes +|This header provides definitions defined by <>, such +as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, +[code]#device_image# and [code]#specialization_id# classes |[code]## -|Contains definitions of [code]#sampler#, [code]#sampled_image#, +|This header provides defintions of the [code]#sampler#, [code]#sampled_image#, [code]#unsampled_image# and corresponding accessors |[code]## -|This header provides access to error handling APIs +|This header provides definitions of error handling APIs defined by +<>, such as [code]#exception# and [code]#exception_list# classes |[code]## -|Contains definition of [code]#private_memory# and [code]#h_item# +|This header provides defintions of the [code]#private_memory# and +[code]#h_item# classes |[code]## -|Contains definition of [code]#interop_handle# class +|This header provides defintion of the [code]#interop_handle# class |[code]## -|Contains definition of [code]#backend_traits# and [code]#make_*# functions +|This header provides defintion of the [code]#backend_traits# and +[code]#make_*# functions |[code]##, [code]## |Headers in this set match by name with those provided by the next C++ specification. They contain pre-adopted features from that standard. |[code]## -|Contains definition of [code]#byte# alias +|This header provides defintion of the [code]#byte# alias |==== Classes, constants, types and functions provided by the headers listed above @@ -204,7 +218,7 @@ as small as reasonably possible to provide maximum benefit for users. [[sec:khr-includes-version]] === [code]## header -This header contains definitions of: +This header provides definitions of: - [code]#SYCL_KHR_INCLUDES# macro - All macro defined by <> - All macro defined by other extensions supported by an implementation @@ -247,17 +261,19 @@ implementation, the following approach should be used: [[sec:khr-includes-backend]] === [code]## header -This header file contains everything related to SYCL backend APIs: +This header provides definitions of common SYCL backend APIs: -- [code]#enum class backend# +- [code]#backend# enumeration - [code]#backend_traits# +- [code]#backend_input_t# +- [code]#backend_return_t# - [code]#get_native# -- [code]#make_*# +- [code]#make_*# functions defined by <> [[sec:khr-includes-device]] === [code]## header -This header gives access to: +This header provides definitions of: - [code]#default_selector_v#, [code]#gpu_selector_v#, [code]#accelerator_selector_v#, [code]#cpu_selector_v#, @@ -271,7 +287,7 @@ This header gives access to: [[sec:khr-includes-platform]] === [code]## header -This header gives access to: +This header provides definitions of: - [code]#platform# class - All [code]#info::platform# information descriptors defined by @@ -280,7 +296,7 @@ This header gives access to: [[sec:khr-includes-context]] === [code]## header -This header gives access to: +This header provides definitions of: - [code]#context# class - All [code]#info::context# information descriptors defined by @@ -299,7 +315,7 @@ common entry point. It includes: [[sec:khr-includes-queue]] === [code]## header -This header contains: +This header provides definitions of: - [code]#queue# class - All [code]#info::queue# information descriptors defined by @@ -309,14 +325,14 @@ This header contains: [[sec:khr-includes-handler]] === [code]## header -This header contains: +This header provides definition of: - [code]#handler# class [[sec:khr-includes-event]] === [code]## header -This header contains: +This header provides definitions of: - [code]#event# class - All [code]#info::event# information descriptors defined by @@ -325,7 +341,7 @@ This header contains: [[sec:khr-includes-buffer]] === [code]## header -This header contains: +This header provides definitions of: - [code]#buffer# class - [code]#buffer_allocator# @@ -334,7 +350,7 @@ This header contains: [[sec:khr-includes-image]] === [code]## header -This header contains: +This header provides definitions of: - [code]#unsampled_image# and [code]#sampled_image# classes - [code]#image_allocator# @@ -351,7 +367,7 @@ This header contains: [[sec:khr-includes-accessor]] === [code]## header -This header contains: +This header provides definitions of: - [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes - [code]#property::no_init# and [code]#no_init# defined by @@ -360,7 +376,7 @@ This header contains: [[sec:khr-includes-multi-ptr]] === [code]## header -This header contains: +This header provides definitions of: - [code]#multi_ptr# class - [code]#address_space#, [code]#decorated# enumerations @@ -370,15 +386,14 @@ This header contains: [[sec:khr-includes-hierarchical-parallelism]] === [code]## header -This header contains: +This header provides definitions of: - [code]#private_memory# and [code]#h_item# classes [[sec:khr-includes-usm]] === [code]## header -This header gives access to functionality defined by <>. Specifically, -it contains: +This header provides definitions of: - [code]#usm::alloc# enumeration - [code]#usm_allocator# class @@ -389,9 +404,7 @@ it contains: [[sec:khr-includes-index-space]] === [code]## header -This header gives access to ranges and index space identifiers that are defined -by the section 4.9.1 Ranges and index space identifiers. Specifically, it -contains: +This header provides definitions of: - [code]#id# - [code]#item# @@ -402,10 +415,7 @@ contains: [[sec:khr-includes-reduction]] === [code]## header -This header gives access to functionality related to reductions as defined by -<> - -It contains: +This header provides definitions of: - [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# and [code]#has_known_identity_v# type traits @@ -420,16 +430,14 @@ convenience. [[sec:khr-includes-interop-handle]] === [code]## header -This header contains: +This header provides definition of: - [code]#interop_handle# class [[sec:khr-includes-kernel-bundle]] === [code]## header -This header gives access to kernel bundles and related functionality as defined -by <>. It -contains: +This header provides definitions of: - [code]#bundle_state# enumeration - [code]#kernel_id#, [code]#kernel#, [code]#device_image# and @@ -443,8 +451,7 @@ contains: [[sec:khr-includes-exception]] === [code]## header -This header gives access to error handling APIs defined by <>. -It contains: +This header provides definitions of: - [code]#async_handler# alias - [code]#exception# and [code]#exception_list# classes @@ -456,13 +463,12 @@ It contains: [[sec:khr-includes-half]] === [code]## header -This header contains definition of [code]#half# class +This header provides definition of [code]#half# data type [[sec:khr-includes-vec]] === [code]## header -This header gives access to [code]#vec# class defined by <>. -It contains: +This header provides definitions of: - [code]#rounding_mode# enumeration - [code]#elem# struct and [code]#vec# class @@ -479,8 +485,7 @@ command line options. [[sec:khr-includes-marray]] === [code]## header -This header gives access to math array types defined by <>. -It contains: +This header provides definitions of: - [code]#marray# class - Type aliases defined by the section 4.14.3.2 Aliases @@ -488,7 +493,8 @@ It contains: [[sec:khr-includes-atomic]] === [code]## header -This header contains: +This header provides definitions of: + - [code]#atomic_fence# function - [code]#memory_order#, [code]#memory_scope# enumerations - [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined @@ -500,8 +506,7 @@ This header contains: [[sec:khr-includes-stream]] === [code]## header -This header gives access to [code]#stream# class and related functionality -described by <>. It contains: +This header provides definitions of: - [code]#stream_manipulator# enumeration and corresponding constants (like [code]#flush# or [code]#endl#) @@ -513,7 +518,7 @@ described by <>. It contains: [[sec:khr-includes-type-traits]] === [code]## header -This header contains: +This header provides definitions of: - [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and [code]#is_property_of_v# defined by <> @@ -527,14 +532,15 @@ This header contains: [[sec:khr-includes-property-list]] === [code]## header -This header contains: +This header provides definition of: - [code]#property_list# class definition [[sec:khr-includes-functional]] === [code]##header -This header contains: +This header provides definitions of: + - [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, [code]#bit_xor#, [code]#logical_and#, [code]#logical_or#, [code]#minimum#, [code]#maximum# structs @@ -544,7 +550,9 @@ This header contains: This header gives access to group classes and algorithms library as defined by sections <>, <>, <> and -<>. It contains: +<>. + +This header provides definitions of: - [code]#group# and [code]#sub_group# classes - [code]#device_event# class From bcc0d74c979938080e89590111a928a809dc80a8 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 17 Jun 2025 16:40:17 +0200 Subject: [PATCH 10/47] Switch to the new note syntax --- adoc/extensions/sycl_khr_includes.adoc | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 0471c2668..5e0de3eca 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -40,14 +40,13 @@ below. |Initial version of this extension. |=== -[NOTE] -==== +{note} Please note that an implementation may choose the <> to implementing the SYCL specification and therefore it won't be possible for it to predefine any macro outside of header files. See <> below about performing a portable check for this extension. -==== +{endnote} [[sec:khr-includes-full-list-of-headers]] == Extension overview @@ -205,15 +204,14 @@ has methods which accept [code]#accessor# object, but definition. Therefore, a portable application should include the corresponding header to get [code]#accessor# definition explicitly. -[NOTE] -==== +{note} However, there is no requirement for the implementations to **only** provide through those headers exactly what's specified, i.e. they may contain other functions and classes than documented in this extension. In fact, some classes, functions or enumerations are documented to be available through multiple headers. Nevertheless, implementations are encouraged to keep headers contents as small as reasonably possible to provide maximum benefit for users. -==== +{endnote} [[sec:khr-includes-version]] === [code]## header From 0f59355855bedf8af45f14f324162ac6847133c1 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 17 Jun 2025 16:43:07 +0200 Subject: [PATCH 11/47] Use asterics instead of dash for bullet lists --- adoc/extensions/sycl_khr_includes.adoc | 197 +++++++++++++------------ 1 file changed, 99 insertions(+), 98 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 5e0de3eca..d9bd04ac4 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -217,9 +217,10 @@ as small as reasonably possible to provide maximum benefit for users. === [code]## header This header provides definitions of: -- [code]#SYCL_KHR_INCLUDES# macro -- All macro defined by <> -- All macro defined by other extensions supported by an implementation + +* [code]#SYCL_KHR_INCLUDES# macro +* All macro defined by <> +* All macro defined by other extensions supported by an implementation [code]## header is included by every other header documented by this extension, as well as [code]##. @@ -261,34 +262,34 @@ implementation, the following approach should be used: This header provides definitions of common SYCL backend APIs: -- [code]#backend# enumeration -- [code]#backend_traits# -- [code]#backend_input_t# -- [code]#backend_return_t# -- [code]#get_native# -- [code]#make_*# functions defined by <> +* [code]#backend# enumeration +* [code]#backend_traits# +* [code]#backend_input_t# +* [code]#backend_return_t# +* [code]#get_native# +* [code]#make_*# functions defined by <> [[sec:khr-includes-device]] === [code]## header This header provides definitions of: -- [code]#default_selector_v#, [code]#gpu_selector_v#, +* [code]#default_selector_v#, [code]#gpu_selector_v#, [code]#accelerator_selector_v#, [code]#cpu_selector_v#, [code]#aspect_selector# -- [code]#device# class -- All [code]#info::device# information descriptors defined by +* [code]#device# class +* All [code]#info::device# information descriptors defined by <> -- All other enumerations defined by <> -- [code]#enum class aspect# +* All other enumerations defined by <> +* [code]#enum class aspect# [[sec:khr-includes-platform]] === [code]## header This header provides definitions of: -- [code]#platform# class -- All [code]#info::platform# information descriptors defined by +* [code]#platform# class +* All [code]#info::platform# information descriptors defined by <> [[sec:khr-includes-context]] @@ -296,8 +297,8 @@ This header provides definitions of: This header provides definitions of: -- [code]#context# class -- All [code]#info::context# information descriptors defined by +* [code]#context# class +* All [code]#info::context# information descriptors defined by <> [[sec:khr-includes-submit]] @@ -306,34 +307,34 @@ This header provides definitions of: This is a convenience header, which simply groups other headers to a single common entry point. It includes: -- [code]## -- [code]## -- [code]## +* [code]## +* [code]## +* [code]## [[sec:khr-includes-queue]] === [code]## header This header provides definitions of: -- [code]#queue# class -- All [code]#info::queue# information descriptors defined by +* [code]#queue# class +* All [code]#info::queue# information descriptors defined by <> -- All [code]#properties::queue# types defined by <> +* All [code]#properties::queue# types defined by <> [[sec:khr-includes-handler]] === [code]## header This header provides definition of: -- [code]#handler# class +* [code]#handler# class [[sec:khr-includes-event]] === [code]## header This header provides definitions of: -- [code]#event# class -- All [code]#info::event# information descriptors defined by +* [code]#event# class +* All [code]#info::event# information descriptors defined by <> [[sec:khr-includes-buffer]] @@ -341,24 +342,24 @@ This header provides definitions of: This header provides definitions of: -- [code]#buffer# class -- [code]#buffer_allocator# -- All [code]#property::buffer# types defined by <> +* [code]#buffer# class +* [code]#buffer_allocator# +* All [code]#property::buffer# types defined by <> [[sec:khr-includes-image]] === [code]## header This header provides definitions of: -- [code]#unsampled_image# and [code]#sampled_image# classes -- [code]#image_allocator# -- All [code]#property::image# types defined by <> -- [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, +* [code]#unsampled_image# and [code]#sampled_image# classes +* [code]#image_allocator# +* All [code]#property::image# types defined by <> +* [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, [code]#host_unsampled_image_accessor# and [code]#host_sampled_image_accessor# classes -- [code]#property::no_init# and [code]#no_init# defined by +* [code]#property::no_init# and [code]#no_init# defined by <> -- [code]#addresing_mode#, [code]#filtering_mode#, +* [code]#addresing_mode#, [code]#filtering_mode#, [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# struct @@ -367,8 +368,8 @@ This header provides definitions of: This header provides definitions of: -- [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes -- [code]#property::no_init# and [code]#no_init# defined by +* [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes +* [code]#property::no_init# and [code]#no_init# defined by <> [[sec:khr-includes-multi-ptr]] @@ -376,9 +377,9 @@ This header provides definitions of: This header provides definitions of: -- [code]#multi_ptr# class -- [code]#address_space#, [code]#decorated# enumerations -- [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and +* [code]#multi_ptr# class +* [code]#address_space#, [code]#decorated# enumerations +* [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and other aliases defined by <> [[sec:khr-includes-hierarchical-parallelism]] @@ -386,16 +387,16 @@ This header provides definitions of: This header provides definitions of: -- [code]#private_memory# and [code]#h_item# classes +* [code]#private_memory# and [code]#h_item# classes [[sec:khr-includes-usm]] === [code]## header This header provides definitions of: -- [code]#usm::alloc# enumeration -- [code]#usm_allocator# class -- Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, +* [code]#usm::alloc# enumeration +* [code]#usm_allocator# class +* Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, [code]#malloc# and [code]#get_pointer_type# as defined by sections 4.8.3 USM allocations and 4.8.4 Unified shared memory pointer queries @@ -404,23 +405,23 @@ This header provides definitions of: This header provides definitions of: -- [code]#id# -- [code]#item# -- [code]#nd_item# -- [code]#range# -- [code]#nd_range# +* [code]#id# +* [code]#item# +* [code]#nd_item# +* [code]#range# +* [code]#nd_range# [[sec:khr-includes-reduction]] === [code]## header This header provides definitions of: -- [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# +* [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# and [code]#has_known_identity_v# type traits -- [code]#reduction# interface -- [code]#property::reduction::initialize_to_identity# property -- [code]#reducer# class -- All [code]#property::reduction# types defined by <> +* [code]#reduction# interface +* [code]#property::reduction::initialize_to_identity# property +* [code]#reducer# class +* All [code]#property::reduction# types defined by <> This header also includes [code]## for convenience. @@ -430,32 +431,32 @@ convenience. This header provides definition of: -- [code]#interop_handle# class +* [code]#interop_handle# class [[sec:khr-includes-kernel-bundle]] === [code]## header This header provides definitions of: -- [code]#bundle_state# enumeration -- [code]#kernel_id#, [code]#kernel#, [code]#device_image# and +* [code]#bundle_state# enumeration +* [code]#kernel_id#, [code]#kernel#, [code]#device_image# and [code]#kernel_bundle# classes -- All [code]#info::kernel# information descriptors defined by +* All [code]#info::kernel# information descriptors defined by <> -- Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, +* Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, [code]#compile#, [code]#link# -- [code]#specialization_id# class +* [code]#specialization_id# class [[sec:khr-includes-exception]] === [code]## header This header provides definitions of: -- [code]#async_handler# alias -- [code]#exception# and [code]#exception_list# classes -- [code]#errc# enumeration -- [code]#make_error_code# and [code]#sycl_category# free functions -- [code]#std::is_error_code_enum# type trait specialization for +* [code]#async_handler# alias +* [code]#exception# and [code]#exception_list# classes +* [code]#errc# enumeration +* [code]#make_error_code# and [code]#sycl_category# free functions +* [code]#std::is_error_code_enum# type trait specialization for [code]#sycl::errc# [[sec:khr-includes-half]] @@ -468,10 +469,10 @@ This header provides definition of [code]#half# data type This header provides definitions of: -- [code]#rounding_mode# enumeration -- [code]#elem# struct and [code]#vec# class -- Type aliases defined by the section 4.14.2.2 Aliases -- [code]#__writeable_swizzle__# and [code]#__const_swizzle__# classes defined +* [code]#rounding_mode# enumeration +* [code]#elem# struct and [code]#vec# class +* Type aliases defined by the section 4.14.2.2 Aliases +* [code]#__writeable_swizzle__# and [code]#__const_swizzle__# classes defined by <> In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and @@ -485,19 +486,19 @@ command line options. This header provides definitions of: -- [code]#marray# class -- Type aliases defined by the section 4.14.3.2 Aliases +* [code]#marray# class +* Type aliases defined by the section 4.14.3.2 Aliases [[sec:khr-includes-atomic]] === [code]## header This header provides definitions of: -- [code]#atomic_fence# function -- [code]#memory_order#, [code]#memory_scope# enumerations -- [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined +* [code]#atomic_fence# function +* [code]#memory_order#, [code]#memory_scope# enumerations +* [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined by <> -- [code]#atomic# class and free functions like [code]#atomic_store#, +* [code]#atomic# class and free functions like [code]#atomic_store#, [code]#atomic_fetch_and# as defined by the section 4.15.4 Atomic types (deprecated) @@ -506,11 +507,11 @@ This header provides definitions of: This header provides definitions of: -- [code]#stream_manipulator# enumeration and corresponding constants (like +* [code]#stream_manipulator# enumeration and corresponding constants (like [code]#flush# or [code]#endl#) -- [code]#setprecision# and [code]#setw# functions -- [code]#stream# class -- [code]#template const stream& operator<<(const stream& os, const T& rhs)# +* [code]#setprecision# and [code]#setw# functions +* [code]#stream# class +* [code]#template const stream& operator<<(const stream& os, const T& rhs)# operator [[sec:khr-includes-type-traits]] @@ -518,28 +519,28 @@ This header provides definitions of: This header provides definitions of: -- [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and +* [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and [code]#is_property_of_v# defined by <> -- [code]#is_group# and [code]#is_group_v# defined by +* [code]#is_group# and [code]#is_group_v# defined by <> -- [code]#is_device_copyable# defined by <> -- [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# +* [code]#is_device_copyable# defined by <> +* [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# and [code]#all_devices_have_v# defined by <> -- [code]#remove_decoration# type trait +* [code]#remove_decoration# type trait [[sec:khr-includes-property-list]] === [code]## header This header provides definition of: -- [code]#property_list# class definition +* [code]#property_list# class definition [[sec:khr-includes-functional]] === [code]##header This header provides definitions of: -- [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, +* [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, [code]#bit_xor#, [code]#logical_and#, [code]#logical_or#, [code]#minimum#, [code]#maximum# structs @@ -552,10 +553,10 @@ by sections <>, <>, <> and This header provides definitions of: -- [code]#group# and [code]#sub_group# classes -- [code]#device_event# class -- [code]#group_broadcast#, [code]#group_barrier# functions -- [code]#any_of#, [code]#all_of#, [code]#none_of#, [code]#shift_left#, +* [code]#group# and [code]#sub_group# classes +* [code]#device_event# class +* [code]#group_broadcast#, [code]#group_barrier# functions +* [code]#any_of#, [code]#all_of#, [code]#none_of#, [code]#shift_left#, [code]#shift_right#, [code]#permute#, [code]#select#, [code]#reduce#, [code]#exclusive_scan_over_group#, [code]#inclusive_scan_over_group#, [code]#joint_exclusive_scan# and [code]#joint_inclusive_scan# functions @@ -565,13 +566,13 @@ This header provides definitions of: This header includes all SYCL built-in functions documented by sections: -- <> -- <> -- <> -- <> -- <> -- <> -- <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> [[sec:khr-includes-bit]] === [code]## header From e4233da37182a425724b4e9555d032e78e5b51c0 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 14:53:12 +0200 Subject: [PATCH 12/47] Apply some comments --- adoc/extensions/sycl_khr_includes.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index d9bd04ac4..9038fa825 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -4,7 +4,7 @@ The core SYCL specification says that all APIs provided by the specification are accessible through single [code]## header file. -That leads to increased compilation times, because SYCL users have to pay for +That leads to increased compilation times because SYCL users have to pay for features that they are not even using. Moreover, the situation doesn't scale well with more extensions being proposed. @@ -56,7 +56,7 @@ headers with high-level description of their content. All headers are provided under [code]## include path. -The Description column in the table is non-formative and intended to help you +The Description column in the table is non-normative and intended to help you navigate the extension document quicker. Formal description of each new header file is provided in subsequent sections below. @@ -472,8 +472,8 @@ This header provides definitions of: * [code]#rounding_mode# enumeration * [code]#elem# struct and [code]#vec# class * Type aliases defined by the section 4.14.2.2 Aliases -* [code]#__writeable_swizzle__# and [code]#__const_swizzle__# classes defined - by <> +* [code]#+__writeable_swizzle__+# and [code]#+__const_swizzle__+# classes + defined by <> In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and [code]#RGBA_SWIZZLE# defined by the table 123) available, the macro @@ -536,7 +536,7 @@ This header provides definition of: * [code]#property_list# class definition [[sec:khr-includes-functional]] -=== [code]##header +=== [code]## header This header provides definitions of: @@ -622,7 +622,7 @@ won't be the case and therefore this assumption is not safe to make for applications that aim to be portable between SYCL implementations.{endnote} If an implementation supports this extension together with other extensions, -then any macro defined by other extensions myst be made available through +then any macro defined by other extensions must be made available through [code]## header. == Open issues/questions From a55dc244a36c51cdac3627474ba28cd9ead565b5 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:02:32 +0200 Subject: [PATCH 13/47] Remove hardcoded section references --- adoc/chapters/programming_interface.adoc | 4 ++++ adoc/extensions/sycl_khr_includes.adoc | 16 +++++++--------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 54ca3b65b..d1248c4be 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -11140,6 +11140,7 @@ Users may query the device to determine if system allocations are supported for use on the device, through [code]#aspect::usm_system_allocations#. +[[subsec:usm-allocations]] === USM allocations USM provides several allocation functions. @@ -11850,6 +11851,7 @@ _Effects_: Equivalent to [code]#return free(ptr, q.get_context());#. submit a "free" <> to the device; the [code]#queue# argument is only used to determine the [code]#context# associated with [code]#ptr#.{endnote} +[[subsec:usm-mem-ptr-queries]] === Unified shared memory pointer queries Since USM pointers look like raw {cpp} pointers, users cannot deduce what kind @@ -18765,6 +18767,7 @@ defined integer type. |==== +[[subsec:vec-aliases]] ==== Aliases The SYCL programming API provides all permutations of the type alias: @@ -20175,6 +20178,7 @@ marray operator!(const marray& v) +[[subsec:marray-aliases]] ==== Aliases The SYCL programming API provides all permutations of the type alias: diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 9038fa825..0815f2076 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -398,7 +398,7 @@ This header provides definitions of: * [code]#usm_allocator# class * Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, [code]#malloc# and [code]#get_pointer_type# as defined by sections - 4.8.3 USM allocations and 4.8.4 Unified shared memory pointer queries + <> and <> [[sec:khr-includes-index-space]] === [code]## header @@ -471,12 +471,12 @@ This header provides definitions of: * [code]#rounding_mode# enumeration * [code]#elem# struct and [code]#vec# class -* Type aliases defined by the section 4.14.2.2 Aliases +* Type aliases defined by <> * [code]#+__writeable_swizzle__+# and [code]#+__const_swizzle__+# classes defined by <> In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and -[code]#RGBA_SWIZZLE# defined by the table 123) available, the macro +[code]#RGBA_SWIZZLE# defined by <>) available, the macro [code]#SYCL_SIMPLE_SWIZZLES# should be defined before *any* other [code]#sycl/# header is included. The recommended way of doing that is through command line options. @@ -487,7 +487,7 @@ command line options. This header provides definitions of: * [code]#marray# class -* Type aliases defined by the section 4.14.3.2 Aliases +* Type aliases defined by <> [[sec:khr-includes-atomic]] === [code]## header @@ -499,8 +499,7 @@ This header provides definitions of: * [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined by <> * [code]#atomic# class and free functions like [code]#atomic_store#, - [code]#atomic_fetch_and# as defined by the section 4.15.4 Atomic types - (deprecated) + [code]#atomic_fetch_and# as defined by <> [[sec:khr-includes-stream]] === [code]## header @@ -595,9 +594,8 @@ This header contains definition of [code]#byte# type alias === Preprocessor directives and macros In case a SYCL implementation is made using library-only approach, macros -defined by the section 5.6 Preprocessor directives and macros should be -available regardless of which one of the headers introduced by this extension is -included. +defined by <> should be available +regardless of which one of the headers introduced by this extension is included. For example, [code]#SYCL_LANGUAGE_VERSION# macro should be available even if a translation unit within an application only includes From 3b4e2a11b39372e85a271044504c777f47a5f53e Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:07:48 +0200 Subject: [PATCH 14/47] Document missing event info descriptors --- adoc/extensions/sycl_khr_includes.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 0815f2076..6316600b0 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -336,6 +336,10 @@ This header provides definitions of: * [code]#event# class * All [code]#info::event# information descriptors defined by <> +* All [code]#info::event_command_status# descriptors defined by + <> +* All [code]#info::event_profiling# descriptors defined by + <> [[sec:khr-includes-buffer]] === [code]## header From d546d2f649bc1c3e0d888d4e7b1140d739802e9b Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:11:56 +0200 Subject: [PATCH 15/47] Document missing accessor-related enumerations --- adoc/chapters/programming_interface.adoc | 1 + adoc/extensions/sycl_khr_includes.adoc | 3 +++ 2 files changed, 4 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index d1248c4be..075fdf457 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -7221,6 +7221,7 @@ access_mode::read_write |==== +[[subsec:accessor-deduction-tags]] ==== Deduction tags Some accessor constructors take a [code]#TagT# parameter, which is used to diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 6316600b0..9396c9d61 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -375,6 +375,9 @@ This header provides definitions of: * [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes * [code]#property::no_init# and [code]#no_init# defined by <> +* [code]#target#, [code]#access::target#, [code]#access::placeholder#, + [code]#access_mode# and [code]#access::access_mode# enumerations +* Deduction tags defined by <> [[sec:khr-includes-multi-ptr]] === [code]## header From 497a2c9d2af45ad37955033854ed7cff3cd0e8da Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:12:45 +0200 Subject: [PATCH 16/47] Fix missing namespaces --- adoc/extensions/sycl_khr_includes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 9396c9d61..c2ace326c 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -385,7 +385,7 @@ This header provides definitions of: This header provides definitions of: * [code]#multi_ptr# class -* [code]#address_space#, [code]#decorated# enumerations +* [code]#access::address_space#, [code]#access::decorated# enumerations * [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and other aliases defined by <> From 0c47b34a0f11e6f0c69d9a6692870047dca94bc2 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:13:22 +0200 Subject: [PATCH 17/47] Remove duplication in reduction.hpp description --- adoc/extensions/sycl_khr_includes.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index c2ace326c..7d054c595 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -426,7 +426,6 @@ This header provides definitions of: * [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# and [code]#has_known_identity_v# type traits * [code]#reduction# interface -* [code]#property::reduction::initialize_to_identity# property * [code]#reducer# class * All [code]#property::reduction# types defined by <> From a64a4ec94929bafc10d5c1628ef16c57b8aac0b4 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:14:39 +0200 Subject: [PATCH 18/47] Move identity-related type traits into the dedicated header with other type traits --- adoc/extensions/sycl_khr_includes.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 7d054c595..24559dc9b 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -423,8 +423,6 @@ This header provides definitions of: This header provides definitions of: -* [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# - and [code]#has_known_identity_v# type traits * [code]#reduction# interface * [code]#reducer# class * All [code]#property::reduction# types defined by <> @@ -532,6 +530,8 @@ This header provides definitions of: * [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# and [code]#all_devices_have_v# defined by <> * [code]#remove_decoration# type trait +* [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# + and [code]#has_known_identity_v# type traits [[sec:khr-includes-property-list]] === [code]## header From 3319528d304b5eead0c8a857c221b1e4ec8882ac Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:16:34 +0200 Subject: [PATCH 19/47] Document missing kernel-device-specific info descriptors --- adoc/extensions/sycl_khr_includes.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 24559dc9b..69db1bb12 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -445,8 +445,8 @@ This header provides definitions of: * [code]#bundle_state# enumeration * [code]#kernel_id#, [code]#kernel#, [code]#device_image# and [code]#kernel_bundle# classes -* All [code]#info::kernel# information descriptors defined by - <> +* All [code]#info::kernel# and [code]#info::kernel_device_specific# information + descriptors defined by <> * Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, [code]#compile#, [code]#link# * [code]#specialization_id# class From f75f7253b217bcc6132e0c7ccfa1a15e33eb44a9 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:19:10 +0200 Subject: [PATCH 20/47] Drop memory_order_traits because it is exposition-only --- adoc/extensions/sycl_khr_includes.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 69db1bb12..fbf9842d5 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -500,8 +500,7 @@ This header provides definitions of: * [code]#atomic_fence# function * [code]#memory_order#, [code]#memory_scope# enumerations -* [code]#memory_order_traits# struct and [code]#atomic_ref# class as defined - by <> +* [code]#atomic_ref# class as defined by <> * [code]#atomic# class and free functions like [code]#atomic_store#, [code]#atomic_fetch_and# as defined by <> From b1daf3acc91f4800d3ee15174e3741e72a8a0cab Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:20:06 +0200 Subject: [PATCH 21/47] Drop submit.hpp header --- adoc/extensions/sycl_khr_includes.adoc | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index fbf9842d5..888f4a7ea 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -70,12 +70,6 @@ file is provided in subsequent sections below. |[code]## |This header provides varios macro definitions -|[code]## -|This header covers queue operations. It contains definitions of [code]#queue#, -[code]#handler# and [code]#event# class. If you don't use events and/or only -use [code]#queue# shortcut functions, then it is recommended to include those -classes individually through the corresponding headers. - |[code]## |This header provides defintion of the [code]#queue# class @@ -301,16 +295,6 @@ This header provides definitions of: * All [code]#info::context# information descriptors defined by <> -[[sec:khr-includes-submit]] -=== [code]## header - -This is a convenience header, which simply groups other headers to a single -common entry point. It includes: - -* [code]## -* [code]## -* [code]## - [[sec:khr-includes-queue]] === [code]## header From 792170ee1fa2a3bad449a0eca25c0d7b5f74a1ac Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:36:04 +0200 Subject: [PATCH 22/47] Document SYCL_BACKEND_* macro --- adoc/extensions/sycl_khr_includes.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 888f4a7ea..445ecc441 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -215,6 +215,8 @@ This header provides definitions of: * [code]#SYCL_KHR_INCLUDES# macro * All macro defined by <> * All macro defined by other extensions supported by an implementation +* Backend macros in the form of [code]#SYCL_BACKEND_# defined by + <> [code]## header is included by every other header documented by this extension, as well as [code]##. From d7cce9f955d226b33adfa2d6a302675f752f6965 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 30 Jun 2025 15:46:10 +0200 Subject: [PATCH 23/47] Split groups.hpp header --- adoc/extensions/sycl_khr_includes.adoc | 27 ++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 445ecc441..78c39ec25 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -129,8 +129,10 @@ and [code]#host_accessor# classes. |[code]## |This header provides defintions of the [code]#group# and [code]#sub_group# -classes, as well as operations that can be performed with them such as -broadcasts or scans +classes + +|[code]## +|This header provides defintions of group operations such as broadcasts or scans |[code]## |This header provides defintions of the [code]#multi_ptr# class and related @@ -537,19 +539,24 @@ This header provides definitions of: [[sec:khr-includes-groups]] === [code]## header -This header gives access to group classes and algorithms library as defined -by sections <>, <>, <> and -<>. - This header provides definitions of: * [code]#group# and [code]#sub_group# classes * [code]#device_event# class -* [code]#group_broadcast#, [code]#group_barrier# functions -* [code]#any_of#, [code]#all_of#, [code]#none_of#, [code]#shift_left#, - [code]#shift_right#, [code]#permute#, [code]#select#, [code]#reduce#, - [code]#exclusive_scan_over_group#, [code]#inclusive_scan_over_group#, +* [code]#group_barrier# function + +[[sec:khr-includes-group-algorithms]] +=== [code]## header + +This header provides definitions of: + +* [code]#group_broadcast# function +* [code]#any_of#, [code]#all_of# and [code]#none_of# functions +* [code]#shift_left#, [code]#shift_right#, [code]#permute#, [code]#select# and + [code]#reduce# functions +* [code]#exclusive_scan_over_group#, [code]#inclusive_scan_over_group#, [code]#joint_exclusive_scan# and [code]#joint_inclusive_scan# functions + functions [[sec:khr-includes-math]] === [code]## header From 73d713b7ff4b9ea0a05b8e79910193b351b0a7ac Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Fri, 18 Jul 2025 14:53:39 +0200 Subject: [PATCH 24/47] Put kernel_handler into its own header --- adoc/extensions/sycl_khr_includes.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 78c39ec25..58f1d077a 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -162,6 +162,9 @@ address space class aliases as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, [code]#device_image# and [code]#specialization_id# classes +|[code]## +|This header provides definition of the [code]#kernel_handler# class + |[code]## |This header provides defintions of the [code]#sampler#, [code]#sampled_image#, [code]#unsampled_image# and corresponding accessors @@ -439,6 +442,11 @@ This header provides definitions of: [code]#compile#, [code]#link# * [code]#specialization_id# class +[[sec:khr-includes-kernel-handler]] +=== [code]## header + +This header provides definition of [code]#kernel_handler# class + [[sec:khr-includes-exception]] === [code]## header From cfaf79c63c835204e2ce09b2c2a32d831d364738 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Fri, 18 Jul 2025 15:14:32 +0200 Subject: [PATCH 25/47] Split a single bullet into multiple --- adoc/extensions/sycl_khr_includes.adoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 58f1d077a..eb9a0a489 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -540,9 +540,15 @@ This header provides definition of: This header provides definitions of: -* [code]#plus#, [code]#multiplies#, [code]#bit_and#, [code]#bit_or#, - [code]#bit_xor#, [code]#logical_and#, [code]#logical_or#, - [code]#minimum#, [code]#maximum# structs +* [code]#plus# +* [code]#multiplies# +* [code]#bit_and# +* [code]#bit_or# +* [code]#bit_xor# +* [code]#logical_and# +* [code]#logical_or# +* [code]#minimum# +* [code]#maximum# [[sec:khr-includes-groups]] === [code]## header From 59b5e14ed8c6d020c5bda03f2d5c76cd6b484566 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 22 Jul 2025 12:02:45 +0200 Subject: [PATCH 26/47] Outline all properties into distinct headers --- adoc/extensions/sycl_khr_includes.adoc | 50 +++++++++++++++++++++----- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index eb9a0a489..f0bc182db 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -142,6 +142,10 @@ address space class aliases |This header provides definitions of function objects like [code]#plus# or [code]#locial_or# defined by <> +|[code]## +|This set of headers each are named after a property class they describe, such +as [code]#use_host_ptr# or [code]#no_init# + |[code]## |This header provides definitions defined by <>, such as [code]#reduction# interface and [code]#reducer# class @@ -310,7 +314,6 @@ This header provides definitions of: * [code]#queue# class * All [code]#info::queue# information descriptors defined by <> -* All [code]#properties::queue# types defined by <> [[sec:khr-includes-handler]] === [code]## header @@ -339,7 +342,6 @@ This header provides definitions of: * [code]#buffer# class * [code]#buffer_allocator# -* All [code]#property::buffer# types defined by <> [[sec:khr-includes-image]] === [code]## header @@ -348,12 +350,9 @@ This header provides definitions of: * [code]#unsampled_image# and [code]#sampled_image# classes * [code]#image_allocator# -* All [code]#property::image# types defined by <> * [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, [code]#host_unsampled_image_accessor# and [code]#host_sampled_image_accessor# classes -* [code]#property::no_init# and [code]#no_init# defined by - <> * [code]#addresing_mode#, [code]#filtering_mode#, [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# struct @@ -364,8 +363,6 @@ This header provides definitions of: This header provides definitions of: * [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes -* [code]#property::no_init# and [code]#no_init# defined by - <> * [code]#target#, [code]#access::target#, [code]#access::placeholder#, [code]#access_mode# and [code]#access::access_mode# enumerations * Deduction tags defined by <> @@ -416,7 +413,6 @@ This header provides definitions of: * [code]#reduction# interface * [code]#reducer# class -* All [code]#property::reduction# types defined by <> This header also includes [code]## for convenience. @@ -550,6 +546,44 @@ This header provides definitions of: * [code]#minimum# * [code]#maximum# +[[sec:khr-includes-properties-enable-profiling]] +=== [code]## header + +This header provides definition of [code]#enable_profiling# property + +[[sec:khr-includes-properties-in-order]] +=== [code]## header + +This header provides definition of [code]#in_order# property + +[[sec:khr-includes-properties-use-host-ptr]] +=== [code]## header + +This header provides definition of [code]#use_host_ptr# property (in both +[code]#buffer# and [code]#image# namespaces) + +[[sec:khr-includes-properties-use-mutex]] +=== [code]## header + +This header provides definition of [code]#use_mutex# property (in both +[code]#buffer# and [code]#image# namespaces) + +[[sec:khr-includes-properties-context-bound]] +=== [code]## header + +This header provides definition of [code]#context_bound# property (in both +[code]#buffer# and [code]#image# namespaces) + +[[sec:khr-includes-properties-no-init]] +=== [code]## header + +This header provides definition of [code]#no_init# property + +[[sec:khr-includes-properties-initialize-to-identity]] +=== [code]## header + +This header provides definition of [code]#initialize_to_identity# property + [[sec:khr-includes-groups]] === [code]## header From 7187f28abfda609ffa95fa88fd85531dd68b10f4 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 22 Jul 2025 12:14:50 +0200 Subject: [PATCH 27/47] Clarify the content of reduction.hpp --- adoc/extensions/sycl_khr_includes.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index f0bc182db..c57ed1054 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -148,7 +148,9 @@ as [code]#use_host_ptr# or [code]#no_init# |[code]## |This header provides definitions defined by <>, such as -[code]#reduction# interface and [code]#reducer# class +[code]#reduction# interface and [code]#reducer# class. Note that this header +does not provide definitions of group algorithm functions such as +[code]#joint_reduce#. |[code]## |This header provides functionality defined by <>, i.e. From f0578dd259bdcd999cc99b730263d6a761efcac0 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 9 Sep 2025 14:22:01 +0200 Subject: [PATCH 28/47] Restore extra anchors lost during merge --- adoc/chapters/programming_interface.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 5541fd1f3..5b5c995fd 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -606,6 +606,7 @@ A SYCL implementation or a <> may provide additional properties other than those defined here, provided they are defined in accordance with the requirements described in <>. +[[subsec:properties-interface]] ==== Properties interface Each of the runtime classes mentioned above must provide a common interface of @@ -7216,6 +7217,7 @@ access_mode::read_write |==== +[[subsec:accessor-deducation-tags]] ==== Deduction tags Some accessor constructors take a [code]#DeductionTagT# parameter, which is used @@ -7236,6 +7238,7 @@ being constructed, so they are described more fully below in the section that pertains to each of the accessor types. +[[sec:accessor-properties]] ==== Properties All accessor constructors accept a [code]#property_list# parameter, which @@ -11136,6 +11139,7 @@ Users may query the device to determine if system allocations are supported for use on the device, through [code]#aspect::usm_system_allocations#. +[[sec:usm-allocations]] === USM allocations USM provides several allocation functions. @@ -11850,6 +11854,7 @@ _Effects_: Equivalent to [code]#return free(ptr, q.get_context());#. submit a "free" <> to the device; the [code]#queue# argument is only used to determine the [code]#context# associated with [code]#ptr#.{endnote} +[[subsec:usm-mem-ptr-queries]] === Unified shared memory pointer queries Since USM pointers look like raw {cpp} pointers, users cannot deduce what kind @@ -16978,6 +16983,7 @@ _Throws:_ the <> that corresponds with [code]#Param# is different from the <> that is associated with this kernel bundle. +[[sec:kernel-info-descriptors]] ==== Kernel information descriptors A <> can be queried for information using the [code]#get_info()# member @@ -17305,6 +17311,7 @@ declarable ([code]#std::complex#). include::{code_dir}/lambdaNameExamples.cpp[lines=4..-1] ---- +[[subsec:is-device-copyable-type-trait]] === [code]#is_device_copyable# type trait .... @@ -18786,6 +18793,7 @@ defined integer type. |==== +[[subsec:vec-aliases]] ==== Aliases The SYCL programming API provides all permutations of the type alias: @@ -20196,6 +20204,7 @@ marray operator!(const marray& v) +[[subsec:marray-aliases]] ==== Aliases The SYCL programming API provides all permutations of the type alias: @@ -21912,6 +21921,7 @@ described in <>. It is undefined behavior for any group function to be invoked within a [code]#parallel_for_work_group# or [code]#parallel_for_work_item# context. +[[subsec:group-type-traits]] ==== Group type trait [source,,linenums] @@ -25436,6 +25446,7 @@ The return type is [code]#NonScalar# unless [code]#NonScalar# is the ''' +[[sec:native-precision-math-functions]] === Native precision math functions This section describes the native precision math functions that are available in @@ -25874,6 +25885,7 @@ The return type is [code]#NonScalar# unless [code]#NonScalar# is the ''' +[[sec:half-precision-math-functions]] === Half precision math functions (deprecated) This section describes the half precision math functions that are available in @@ -27137,6 +27149,7 @@ The return type is [code]#Int32Bit1# unless [code]#Int32Bit1# is the ''' +[[sec:common-functions]] === Common functions This section describes the common functions that are available in the From bba9f81996096b7952f3f25c7fd4de9d0812337c Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 9 Sep 2025 14:30:31 +0200 Subject: [PATCH 29/47] Fix references to the core spec --- adoc/extensions/sycl_khr_includes.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index c57ed1054..ad78cebf9 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -91,7 +91,7 @@ selectors |[code]## |This header groups together ranges and most of index space identifiers from -<> +<> {note} Classes like [code]#h_item#, [code]#group# and [code]#sub_group# are provided by other headers. @@ -125,7 +125,7 @@ and [code]#host_accessor# classes. |[code]## |This header provides defintions of built-in functions defined by -<> +<> |[code]## |This header provides defintions of the [code]#group# and [code]#sub_group# @@ -153,7 +153,7 @@ does not provide definitions of group algorithm functions such as [code]#joint_reduce#. |[code]## -|This header provides functionality defined by <>, i.e. +|This header provides functionality defined by <>, i.e. [code]#stream# class and related functions |[code]## From fe64b691ceeea0fed7625668f2592ab8cfcb1f34 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 9 Sep 2025 14:31:27 +0200 Subject: [PATCH 30/47] Apply comments to the introduction sections of the extension --- adoc/extensions/sycl_khr_includes.adoc | 31 +++++++------------------- 1 file changed, 8 insertions(+), 23 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index ad78cebf9..2e686a815 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -1,28 +1,15 @@ [[sec:khr-includes]] = sycl_khr_includes -The core SYCL specification says that all APIs provided by the specification are -accessible through single [code]## header file. - -That leads to increased compilation times because SYCL users have to pay for -features that they are not even using. Moreover, the situation doesn't scale -well with more extensions being proposed. - -This extension provides an alternative set of header files which provide -limited set of APIs each, thus allowing user to avoid paying compilation time -cost for features that are not used by an application. - -The alternative set of headers provided by this extension does not introduce -any new functionality, but simply provides an alternative way of accessing the -core SYCL 2020 features with less compile-time overhead on features unused by -an application. +This extension provides an alternative set of header files, with each providing +a limited set of APIs. +This allows developers to avoid paying compilation time cost for features that +are not used by an application. [[sec:khr-includes-dependencies]] == Dependencies -This extension has no dependencies on other extensions. However, other -extensions may not be adapted to be used together with this extension. See -<> for more details about this. +This extension has no dependencies on other extensions. [[sec:khr-includes-feature-test]] == Feature test macro @@ -41,11 +28,9 @@ below. |=== {note} -Please note that an implementation may choose the -<> to implementing the SYCL -specification and therefore it won't be possible for it to predefine any macro -outside of header files. See <> below -about performing a portable check for this extension. +A <> implementation of SYCL cannot predefine macros outside +of header files. +See <> for a portable way to check for this extension. {endnote} [[sec:khr-includes-full-list-of-headers]] From cdf04a30b74a521ec25b94a1da55798d2101b156 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:01:52 +0200 Subject: [PATCH 31/47] Apply wording suggestions --- adoc/extensions/sycl_khr_includes.adoc | 38 +++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 2e686a815..07de52d9f 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -36,8 +36,8 @@ See <> for a portable way to check for this extension. [[sec:khr-includes-full-list-of-headers]] == Extension overview -The <> below provides a list of all new -headers with high-level description of their content. +<> provides a list of all new headers with high-level +description of their content. All headers are provided under [code]## include path. @@ -190,9 +190,10 @@ exist within the [code]#::sycl# namespace as with the standard There is no guarantee that headers documented by this extension contain anything else besides things listed in sections below. For example, [code]#queue# class has methods which accept [code]#accessor# object, but -[code]## is not required to provide [code]#accessor# -definition. Therefore, a portable application should include the corresponding -header to get [code]#accessor# definition explicitly. +[code]## is not required to provide a definition of +[code]#accessor#. +Therefore, a portable application should include the corresponding header to +define [code]#accessor# definition explicitly. {note} However, there is no requirement for the implementations to **only** provide @@ -208,17 +209,17 @@ as small as reasonably possible to provide maximum benefit for users. This header provides definitions of: -* [code]#SYCL_KHR_INCLUDES# macro -* All macro defined by <> -* All macro defined by other extensions supported by an implementation +* [code]#SYCL_KHR_INCLUDES# macro; +* All macros defined in <>; +* Any macros defined by other extensions supported by an implementation; and * Backend macros in the form of [code]#SYCL_BACKEND_# defined by - <> + <>. [code]## header is included by every other header documented by this extension, as well as [code]##. -There is no guarantee that the aforementioned macro are defined before the -inclusion point of [code]##. +There is no guarantee that the aforementioned macros are defined before +[code]## is included. {note}Implementations providing a dedicated SYCL compiler can predefine those macro within the compiler. However, the SYCL standard allows for library-only @@ -226,8 +227,8 @@ implementations and therefore a portable application should not assume that any macro definitions are available until [code]## is included.{endnote} -To properly detect in a portable way if this extension is supported by an -implementation, the following approach should be used: +The code below demonstrates a portable way to detect if this extension is +supported: [source] ---- @@ -642,9 +643,9 @@ of fine-grained headers is an extension specification itself. However, there are many existing extensions which may not have been updated to account for this extension. -Therefore, any extension which does not explicitly document how can it -be accessed through header files, should be assumed to be available through -[code]## only. +Any extension which does not explicitly document how it can be accessed through +header files should be assumed to be available only through +[code]##. {note}It _may_ seem safe to assume that if an extension modifies some existing class, then its functionality should be available through a header file which @@ -652,9 +653,8 @@ exposes that class. However, there exist implementation possibilities where this won't be the case and therefore this assumption is not safe to make for applications that aim to be portable between SYCL implementations.{endnote} -If an implementation supports this extension together with other extensions, -then any macro defined by other extensions must be made available through -[code]## header. +If an implementation supports this extension, then any macro defined by other +supported extensions must be defined in [code]##. == Open issues/questions From cde0cd224e434d352cbac3e52d8c362373abe7f6 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:03:41 +0200 Subject: [PATCH 32/47] Fix some typos --- adoc/extensions/sycl_khr_includes.adoc | 46 +++++++++++++------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 07de52d9f..4c10df13f 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -56,23 +56,23 @@ file is provided in subsequent sections below. |This header provides varios macro definitions |[code]## -|This header provides defintion of the [code]#queue# class +|This header provides definition of the [code]#queue# class |[code]## -|This header provides defintion of the [code]#handler# class +|This header provides definition of the [code]#handler# class |[code]## -|This header provides defintion of the [code]#event# class +|This header provides definition of the [code]#event# class |[code]## -|This header provides defintions of the [code]#device# class and device +|This header provides definitions of the [code]#device# class and device selectors |[code]## -|This header provides defintion of the [code]#platform# class +|This header provides definition of the [code]#platform# class |[code]## -|This header provides defintion of the [code]#context# class +|This header provides definition of the [code]#context# class |[code]## |This header groups together ranges and most of index space identifiers from @@ -88,17 +88,17 @@ other headers. like [code]#malloc_shared#. |[code]## -|This header provides defintion of the [code]#buffer# class +|This header provides definition of the [code]#buffer# class |[code]## -|This header provides defintions of the [code]#accessor#, [code]#local_accessor# +|This header provides definitions of the [code]#accessor#, [code]#local_accessor# and [code]#host_accessor# classes. |[code]## -|This header provides defintion of the [code]#atomic_ref# class +|This header provides definition of the [code]#atomic_ref# class |[code]## -|This header provides defintion of the [code]#half# data type +|This header provides definition of the [code]#half# data type |[code]## |This header provides functionality defined by <>, i.e. @@ -109,23 +109,23 @@ and [code]#host_accessor# classes. [code]#marray# class |[code]## -|This header provides defintions of built-in functions defined by +|This header provides definitions of built-in functions defined by <> |[code]## -|This header provides defintions of the [code]#group# and [code]#sub_group# +|This header provides definitions of the [code]#group# and [code]#sub_group# classes |[code]## -|This header provides defintions of group operations such as broadcasts or scans +|This header provides definitions of group operations such as broadcasts or scans |[code]## -|This header provides defintions of the [code]#multi_ptr# class and related +|This header provides definitions of the [code]#multi_ptr# class and related address space class aliases |[code]## |This header provides definitions of function objects like [code]#plus# or -[code]#locial_or# defined by <> +[code]#logical_or# defined by <> |[code]## |This set of headers each are named after a property class they describe, such @@ -142,11 +142,11 @@ does not provide definitions of group algorithm functions such as [code]#stream# class and related functions |[code]## -|This header provides defintions of various type traits like +|This header provides definitions of various type traits like [code]#is_property#, [code]#is_group#, [code]#is_device_copyable#, etc. |[code]## -|This header provides defintion of the [code]#property_list# class +|This header provides definition of the [code]#property_list# class |[code]## |This header provides definitions defined by <>, such @@ -157,7 +157,7 @@ as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, |This header provides definition of the [code]#kernel_handler# class |[code]## -|This header provides defintions of the [code]#sampler#, [code]#sampled_image#, +|This header provides definitions of the [code]#sampler#, [code]#sampled_image#, [code]#unsampled_image# and corresponding accessors |[code]## @@ -165,14 +165,14 @@ as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, <>, such as [code]#exception# and [code]#exception_list# classes |[code]## -|This header provides defintions of the [code]#private_memory# and +|This header provides definitions of the [code]#private_memory# and [code]#h_item# classes |[code]## -|This header provides defintion of the [code]#interop_handle# class +|This header provides definition of the [code]#interop_handle# class |[code]## -|This header provides defintion of the [code]#backend_traits# and +|This header provides definition of the [code]#backend_traits# and [code]#make_*# functions |[code]##, [code]## @@ -180,7 +180,7 @@ as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, specification. They contain pre-adopted features from that standard. |[code]## -|This header provides defintion of the [code]#byte# alias +|This header provides definition of the [code]#byte# alias |==== Classes, constants, types and functions provided by the headers listed above @@ -189,7 +189,7 @@ exist within the [code]#::sycl# namespace as with the standard There is no guarantee that headers documented by this extension contain anything else besides things listed in sections below. For example, [code]#queue# class -has methods which accept [code]#accessor# object, but +has methods which accept [code]#accessor# objects, but [code]## is not required to provide a definition of [code]#accessor#. Therefore, a portable application should include the corresponding header to From c48866eb4a3982b9bbd70ddeb214cf281d089e78 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:10:23 +0200 Subject: [PATCH 33/47] Reformat the extension overview table --- adoc/extensions/sycl_khr_includes.adoc | 100 ++++++++++++------------- 1 file changed, 46 insertions(+), 54 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 4c10df13f..65b252779 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -53,134 +53,126 @@ file is provided in subsequent sections below. |Description |[code]## -|This header provides varios macro definitions +|Provides varios macro definitions. |[code]## -|This header provides definition of the [code]#queue# class +|Provides definition of the [code]#queue# class. |[code]## -|This header provides definition of the [code]#handler# class +|Provides definition of the [code]#handler# class. |[code]## -|This header provides definition of the [code]#event# class +|Provides definition of the [code]#event# class. |[code]## -|This header provides definitions of the [code]#device# class and device -selectors +|Provides definitions of the [code]#device# class and device selectors. |[code]## -|This header provides definition of the [code]#platform# class +|Provides definition of the [code]#platform# class. |[code]## -|This header provides definition of the [code]#context# class +|Provides definition of the [code]#context# class. |[code]## -|This header groups together ranges and most of index space identifiers from -<> +|Provides definition of the most index space identifiers from +<>. {note} Classes like [code]#h_item#, [code]#group# and [code]#sub_group# are provided by other headers. {endnote} |[code]## -|This header provides functionality defined by <>, such as -[code]#usm_allocator# class and USM free functions for memory management -like [code]#malloc_shared#. +|Provides definitions from <>, such as [code]#usm_allocator# +class and USM free functions for memory management like [code]#malloc_shared#. |[code]## -|This header provides definition of the [code]#buffer# class +|Provides definition of the [code]#buffer# class. |[code]## -|This header provides definitions of the [code]#accessor#, [code]#local_accessor# -and [code]#host_accessor# classes. +|Provides definitions of the [code]#accessor#, [code]#local_accessor# and +[code]#host_accessor# classes. |[code]## -|This header provides definition of the [code]#atomic_ref# class +|Provides definition of the [code]#atomic_ref# class. |[code]## -|This header provides definition of the [code]#half# data type +|Provides definition of the [code]#half# data type. |[code]## -|This header provides functionality defined by <>, i.e. -[code]#vec# class and related enumerations +|Provides definitions from <>, i.e. [code]#vec# class and +related enumerations. |[code]## -|This header provides functionality defined by <>, i.e. -[code]#marray# class +|Provides definitions from <>, i.e. [code]#marray# class. |[code]## -|This header provides definitions of built-in functions defined by -<> +|Provides definitions of built-in functions defined by <>. |[code]## -|This header provides definitions of the [code]#group# and [code]#sub_group# -classes +|Provides definitions of the [code]#group# and [code]#sub_group# classes. |[code]## -|This header provides definitions of group operations such as broadcasts or scans +|Provides definitions of group operations such as broadcasts or scans. |[code]## -|This header provides definitions of the [code]#multi_ptr# class and related -address space class aliases +|Provides definitions of the [code]#multi_ptr# class and related address space +class aliases. |[code]## -|This header provides definitions of function objects like [code]#plus# or -[code]#logical_or# defined by <> +|Provides definitions of function objects like [code]#plus# or +[code]#logical_or# defined by <>. |[code]## |This set of headers each are named after a property class they describe, such as [code]#use_host_ptr# or [code]#no_init# |[code]## -|This header provides definitions defined by <>, such as -[code]#reduction# interface and [code]#reducer# class. Note that this header -does not provide definitions of group algorithm functions such as -[code]#joint_reduce#. +|Provides definitions defined by <>, such as [code]#reduction# +interface and [code]#reducer# class. Note that this header does not provide +definitions of group algorithm functions such as [code]#joint_reduce#. |[code]## -|This header provides functionality defined by <>, i.e. -[code]#stream# class and related functions +|Provides functionality defined by <>, i.e. [code]#stream# class +and related functions. |[code]## -|This header provides definitions of various type traits like -[code]#is_property#, [code]#is_group#, [code]#is_device_copyable#, etc. +|Provides definitions of various type traits like [code]#is_property#, +[code]#is_group#, [code]#is_device_copyable#, etc. |[code]## -|This header provides definition of the [code]#property_list# class +|Provides definition of the [code]#property_list# class. |[code]## -|This header provides definitions defined by <>, such -as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, -[code]#device_image# and [code]#specialization_id# classes +|Provides definitions defined by <>, such as +[code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, [code]#device_image# +and [code]#specialization_id# classes. |[code]## -|This header provides definition of the [code]#kernel_handler# class +|Provides definition of the [code]#kernel_handler# class. |[code]## -|This header provides definitions of the [code]#sampler#, [code]#sampled_image#, -[code]#unsampled_image# and corresponding accessors +|Provides definitions of the [code]#sampler#, [code]#sampled_image#, +[code]#unsampled_image# and corresponding accessors. |[code]## -|This header provides definitions of error handling APIs defined by -<>, such as [code]#exception# and [code]#exception_list# classes +|Provides definitions of error handling APIs from <>, such as +[code]#exception# and [code]#exception_list# classes. |[code]## -|This header provides definitions of the [code]#private_memory# and -[code]#h_item# classes +|Provides definitions of the [code]#private_memory# and [code]#h_item# classes. |[code]## -|This header provides definition of the [code]#interop_handle# class +|Provides definition of the [code]#interop_handle# class. |[code]## -|This header provides definition of the [code]#backend_traits# and -[code]#make_*# functions +|Provides definition of the [code]#backend_traits# and [code]#make_*# functions. |[code]##, [code]## |Headers in this set match by name with those provided by the next C++ specification. They contain pre-adopted features from that standard. |[code]## -|This header provides definition of the [code]#byte# alias +|Provides definition of the [code]#byte# alias. |==== Classes, constants, types and functions provided by the headers listed above From 5f0921c3a926f59a7a2eb04a3a589f14873fef37 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:12:45 +0200 Subject: [PATCH 34/47] Revert "Outline all properties into distinct headers" This reverts commit 59b5e14ed8c6d020c5bda03f2d5c76cd6b484566. --- adoc/extensions/sycl_khr_includes.adoc | 50 +++++--------------------- 1 file changed, 8 insertions(+), 42 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 65b252779..1a00ec6a6 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -122,10 +122,6 @@ class aliases. |Provides definitions of function objects like [code]#plus# or [code]#logical_or# defined by <>. -|[code]## -|This set of headers each are named after a property class they describe, such -as [code]#use_host_ptr# or [code]#no_init# - |[code]## |Provides definitions defined by <>, such as [code]#reduction# interface and [code]#reducer# class. Note that this header does not provide @@ -294,6 +290,7 @@ This header provides definitions of: * [code]#queue# class * All [code]#info::queue# information descriptors defined by <> +* All [code]#properties::queue# types defined by <> [[sec:khr-includes-handler]] === [code]## header @@ -322,6 +319,7 @@ This header provides definitions of: * [code]#buffer# class * [code]#buffer_allocator# +* All [code]#property::buffer# types defined by <> [[sec:khr-includes-image]] === [code]## header @@ -330,9 +328,12 @@ This header provides definitions of: * [code]#unsampled_image# and [code]#sampled_image# classes * [code]#image_allocator# +* All [code]#property::image# types defined by <> * [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, [code]#host_unsampled_image_accessor# and [code]#host_sampled_image_accessor# classes +* [code]#property::no_init# and [code]#no_init# defined by + <> * [code]#addresing_mode#, [code]#filtering_mode#, [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# struct @@ -343,6 +344,8 @@ This header provides definitions of: This header provides definitions of: * [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes +* [code]#property::no_init# and [code]#no_init# defined by + <> * [code]#target#, [code]#access::target#, [code]#access::placeholder#, [code]#access_mode# and [code]#access::access_mode# enumerations * Deduction tags defined by <> @@ -393,6 +396,7 @@ This header provides definitions of: * [code]#reduction# interface * [code]#reducer# class +* All [code]#property::reduction# types defined by <> This header also includes [code]## for convenience. @@ -526,44 +530,6 @@ This header provides definitions of: * [code]#minimum# * [code]#maximum# -[[sec:khr-includes-properties-enable-profiling]] -=== [code]## header - -This header provides definition of [code]#enable_profiling# property - -[[sec:khr-includes-properties-in-order]] -=== [code]## header - -This header provides definition of [code]#in_order# property - -[[sec:khr-includes-properties-use-host-ptr]] -=== [code]## header - -This header provides definition of [code]#use_host_ptr# property (in both -[code]#buffer# and [code]#image# namespaces) - -[[sec:khr-includes-properties-use-mutex]] -=== [code]## header - -This header provides definition of [code]#use_mutex# property (in both -[code]#buffer# and [code]#image# namespaces) - -[[sec:khr-includes-properties-context-bound]] -=== [code]## header - -This header provides definition of [code]#context_bound# property (in both -[code]#buffer# and [code]#image# namespaces) - -[[sec:khr-includes-properties-no-init]] -=== [code]## header - -This header provides definition of [code]#no_init# property - -[[sec:khr-includes-properties-initialize-to-identity]] -=== [code]## header - -This header provides definition of [code]#initialize_to_identity# property - [[sec:khr-includes-groups]] === [code]## header From 53a7e46ac3fd9098795481651076cab07b7eb0a4 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:15:41 +0200 Subject: [PATCH 35/47] Accept removal suggestions --- adoc/extensions/sycl_khr_includes.adoc | 28 -------------------------- 1 file changed, 28 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 1a00ec6a6..00ad48833 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -209,12 +209,6 @@ documented by this extension, as well as [code]##. There is no guarantee that the aforementioned macros are defined before [code]## is included. -{note}Implementations providing a dedicated SYCL compiler can predefine those -macro within the compiler. However, the SYCL standard allows for library-only -implementations and therefore a portable application should not assume that -any macro definitions are available until [code]## is -included.{endnote} - The code below demonstrates a portable way to detect if this extension is supported: @@ -582,35 +576,13 @@ pre-adopted from the next C++ specification. This header contains definition of [code]#byte# type alias -[[sec:khr-includes-macro]] -=== Preprocessor directives and macros - -In case a SYCL implementation is made using library-only approach, macros -defined by <> should be available -regardless of which one of the headers introduced by this extension is included. - -For example, [code]#SYCL_LANGUAGE_VERSION# macro should be available even if -a translation unit within an application only includes -[code]## header. - [[sec:khr-includes-other-extensions]] === Co-existence with other extensions -The ultimate source of truth about accessibility of an extension through a set -of fine-grained headers is an extension specification itself. However, there are -many existing extensions which may not have been updated to account for this -extension. - Any extension which does not explicitly document how it can be accessed through header files should be assumed to be available only through [code]##. -{note}It _may_ seem safe to assume that if an extension modifies some existing -class, then its functionality should be available through a header file which -exposes that class. However, there exist implementation possibilities where this -won't be the case and therefore this assumption is not safe to make for -applications that aim to be portable between SYCL implementations.{endnote} - If an implementation supports this extension, then any macro defined by other supported extensions must be defined in [code]##. From b2a9e9c35938defd06d60d8f7cb79ff55bcaf6bc Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:20:27 +0200 Subject: [PATCH 36/47] Update code example about version.hpp --- adoc/extensions/sycl_khr_includes.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 00ad48833..cc4ce4097 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -215,19 +215,19 @@ supported: [source] ---- #if __has_include() -// The extension is supported, but the SYCL_KHR_INCLUDES is not -// guaranteed to be defined at this point for library-only implementations +// The extension is supported, but the SYCL_KHR_INCLUDES is not necessarily +// defined #include -// Now the SYCL_KHR_INCLUDES macro is guaranteed to be defined for all kinds of -// implementations +// SYCL_KHR_INCLUDES macro is guaranteed to be defined if the extension is +// supported. +#endif -// Use the extension +#if SYCL_KHR_INCLUDES +// Extension is supported #include - #else -// Extension is not supported by an implementation -// Fallback to the core SYCL standard +// Extension is not supported #include #endif ---- From fd6e5aa3bd3ee069964e50fc111d3bab25ea70ef Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Wed, 10 Sep 2025 15:36:04 +0200 Subject: [PATCH 37/47] Fix a couple more spec links --- adoc/chapters/programming_interface.adoc | 2 +- adoc/extensions/sycl_khr_includes.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 5b5c995fd..ff10d2aed 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -7217,7 +7217,7 @@ access_mode::read_write |==== -[[subsec:accessor-deducation-tags]] +[[subsec:accessor-deduction-tags]] ==== Deduction tags Some accessor constructors take a [code]#DeductionTagT# parameter, which is used diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index cc4ce4097..da706e54c 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -370,7 +370,7 @@ This header provides definitions of: * [code]#usm_allocator# class * Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, [code]#malloc# and [code]#get_pointer_type# as defined by sections - <> and <> + <> and <> [[sec:khr-includes-index-space]] === [code]## header From 4abdba609a7f2094ee9d03bd35a88a40d20f65da Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 30 Sep 2025 16:19:28 +0200 Subject: [PATCH 38/47] Definitions defined by -> definitions from --- adoc/extensions/sycl_khr_includes.adoc | 71 ++++++++++++-------------- 1 file changed, 34 insertions(+), 37 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index da706e54c..27f3ae4b1 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -106,7 +106,7 @@ related enumerations. |Provides definitions from <>, i.e. [code]#marray# class. |[code]## -|Provides definitions of built-in functions defined by <>. +|Provides definitions of built-in functions from <>. |[code]## |Provides definitions of the [code]#group# and [code]#sub_group# classes. @@ -120,15 +120,15 @@ class aliases. |[code]## |Provides definitions of function objects like [code]#plus# or -[code]#logical_or# defined by <>. +[code]#logical_or# from <>. |[code]## -|Provides definitions defined by <>, such as [code]#reduction# +|Provides definitions from <>, such as [code]#reduction# interface and [code]#reducer# class. Note that this header does not provide definitions of group algorithm functions such as [code]#joint_reduce#. |[code]## -|Provides functionality defined by <>, i.e. [code]#stream# class +|Provides functionality from <>, i.e. [code]#stream# class and related functions. |[code]## @@ -139,7 +139,7 @@ and related functions. |Provides definition of the [code]#property_list# class. |[code]## -|Provides definitions defined by <>, such as +|Provides definitions from <>, such as [code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, [code]#device_image# and [code]#specialization_id# classes. @@ -242,7 +242,7 @@ This header provides definitions of common SYCL backend APIs: * [code]#backend_input_t# * [code]#backend_return_t# * [code]#get_native# -* [code]#make_*# functions defined by <> +* [code]#make_*# functions from <> [[sec:khr-includes-device]] === [code]## header @@ -253,9 +253,9 @@ This header provides definitions of: [code]#accelerator_selector_v#, [code]#cpu_selector_v#, [code]#aspect_selector# * [code]#device# class -* All [code]#info::device# information descriptors defined by +* All [code]#info::device# information descriptors from <> -* All other enumerations defined by <> +* All other enumerations from <> * [code]#enum class aspect# [[sec:khr-includes-platform]] @@ -264,7 +264,7 @@ This header provides definitions of: This header provides definitions of: * [code]#platform# class -* All [code]#info::platform# information descriptors defined by +* All [code]#info::platform# information descriptors from <> [[sec:khr-includes-context]] @@ -273,7 +273,7 @@ This header provides definitions of: This header provides definitions of: * [code]#context# class -* All [code]#info::context# information descriptors defined by +* All [code]#info::context# information descriptors from <> [[sec:khr-includes-queue]] @@ -282,9 +282,9 @@ This header provides definitions of: This header provides definitions of: * [code]#queue# class -* All [code]#info::queue# information descriptors defined by +* All [code]#info::queue# information descriptors from <> -* All [code]#properties::queue# types defined by <> +* All [code]#properties::queue# types from <> [[sec:khr-includes-handler]] === [code]## header @@ -299,11 +299,11 @@ This header provides definition of: This header provides definitions of: * [code]#event# class -* All [code]#info::event# information descriptors defined by +* All [code]#info::event# information descriptors from <> -* All [code]#info::event_command_status# descriptors defined by +* All [code]#info::event_command_status# descriptors from <> -* All [code]#info::event_profiling# descriptors defined by +* All [code]#info::event_profiling# descriptors from <> [[sec:khr-includes-buffer]] @@ -313,7 +313,7 @@ This header provides definitions of: * [code]#buffer# class * [code]#buffer_allocator# -* All [code]#property::buffer# types defined by <> +* All [code]#property::buffer# types from <> [[sec:khr-includes-image]] === [code]## header @@ -322,12 +322,11 @@ This header provides definitions of: * [code]#unsampled_image# and [code]#sampled_image# classes * [code]#image_allocator# -* All [code]#property::image# types defined by <> +* All [code]#property::image# types from <> * [code]#unsampled_image_accessor#, [code]#sampled_image_accessor#, [code]#host_unsampled_image_accessor# and [code]#host_sampled_image_accessor# classes -* [code]#property::no_init# and [code]#no_init# defined by - <> +* [code]#property::no_init# and [code]#no_init# from <> * [code]#addresing_mode#, [code]#filtering_mode#, [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# struct @@ -338,11 +337,10 @@ This header provides definitions of: This header provides definitions of: * [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes -* [code]#property::no_init# and [code]#no_init# defined by - <> +* [code]#property::no_init# and [code]#no_init# from <> * [code]#target#, [code]#access::target#, [code]#access::placeholder#, [code]#access_mode# and [code]#access::access_mode# enumerations -* Deduction tags defined by <> +* Deduction tags from <> [[sec:khr-includes-multi-ptr]] === [code]## header @@ -352,7 +350,7 @@ This header provides definitions of: * [code]#multi_ptr# class * [code]#access::address_space#, [code]#access::decorated# enumerations * [code]#global_ptr#, [code]#raw_private_ptr#, [code]#decorated_local_ptr# and - other aliases defined by <> + other aliases from <> [[sec:khr-includes-hierarchical-parallelism]] === [code]## header @@ -369,7 +367,7 @@ This header provides definitions of: * [code]#usm::alloc# enumeration * [code]#usm_allocator# class * Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, - [code]#malloc# and [code]#get_pointer_type# as defined by sections + [code]#malloc# and [code]#get_pointer_type# as from sections <> and <> [[sec:khr-includes-index-space]] @@ -390,7 +388,7 @@ This header provides definitions of: * [code]#reduction# interface * [code]#reducer# class -* All [code]#property::reduction# types defined by <> +* All [code]#property::reduction# types from <> This header also includes [code]## for convenience. @@ -411,7 +409,7 @@ This header provides definitions of: * [code]#kernel_id#, [code]#kernel#, [code]#device_image# and [code]#kernel_bundle# classes * All [code]#info::kernel# and [code]#info::kernel_device_specific# information - descriptors defined by <> + descriptors from <> * Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, [code]#compile#, [code]#link# * [code]#specialization_id# class @@ -445,12 +443,12 @@ This header provides definitions of: * [code]#rounding_mode# enumeration * [code]#elem# struct and [code]#vec# class -* Type aliases defined by <> +* Type aliases from <> * [code]#+__writeable_swizzle__+# and [code]#+__const_swizzle__+# classes - defined by <> + from <> In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and -[code]#RGBA_SWIZZLE# defined by <>) available, the macro +[code]#RGBA_SWIZZLE# from <>) available, the macro [code]#SYCL_SIMPLE_SWIZZLES# should be defined before *any* other [code]#sycl/# header is included. The recommended way of doing that is through command line options. @@ -461,7 +459,7 @@ command line options. This header provides definitions of: * [code]#marray# class -* Type aliases defined by <> +* Type aliases from <> [[sec:khr-includes-atomic]] === [code]## header @@ -470,9 +468,9 @@ This header provides definitions of: * [code]#atomic_fence# function * [code]#memory_order#, [code]#memory_scope# enumerations -* [code]#atomic_ref# class as defined by <> +* [code]#atomic_ref# class from <> * [code]#atomic# class and free functions like [code]#atomic_store#, - [code]#atomic_fetch_and# as defined by <> + [code]#atomic_fetch_and# from <> [[sec:khr-includes-stream]] === [code]## header @@ -492,12 +490,11 @@ This header provides definitions of: This header provides definitions of: * [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and - [code]#is_property_of_v# defined by <> -* [code]#is_group# and [code]#is_group_v# defined by - <> -* [code]#is_device_copyable# defined by <> + [code]#is_property_of_v# from <> +* [code]#is_group# and [code]#is_group_v# from <> +* [code]#is_device_copyable# from <> * [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# - and [code]#all_devices_have_v# defined by <> + and [code]#all_devices_have_v# from <> * [code]#remove_decoration# type trait * [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# and [code]#has_known_identity_v# type traits From b7325471a84d4c3966f9b75f47e7d1edb689c587 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 30 Sep 2025 16:23:57 +0200 Subject: [PATCH 39/47] Make the overview table normative --- adoc/extensions/sycl_khr_includes.adoc | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 27f3ae4b1..9e8549e67 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -41,9 +41,9 @@ description of their content. All headers are provided under [code]## include path. -The Description column in the table is non-normative and intended to help you -navigate the extension document quicker. Formal description of each new header -file is provided in subsequent sections below. +The Description column in the table is intended to help you navigate the +extension document quicker. It does not offer the exaustive listing of each new +header file contents that provided in subsequent sections below. [[table.khr-includes-list]] .List of headers provided by the extension @@ -75,11 +75,8 @@ file is provided in subsequent sections below. |[code]## |Provides definition of the most index space identifiers from -<>. -{note} -Classes like [code]#h_item#, [code]#group# and [code]#sub_group# are provided by -other headers. -{endnote} +<>. Classes like [code]#h_item#, [code]#group# and +[code]#sub_group# are provided by other headers. |[code]## |Provides definitions from <>, such as [code]#usm_allocator# From 1296117b09a64c6538d603b215d166df90ae185e Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 30 Sep 2025 16:24:52 +0200 Subject: [PATCH 40/47] Update comments in the code snippet --- adoc/extensions/sycl_khr_includes.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 9e8549e67..dbab1cdfe 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -212,8 +212,8 @@ supported: [source] ---- #if __has_include() -// The extension is supported, but the SYCL_KHR_INCLUDES is not necessarily -// defined +// The file exists, but the SYCL_KHR_INCLUDES is not necessarily defined, i.e. +// the extension may not be fully supported by an implementation. #include // SYCL_KHR_INCLUDES macro is guaranteed to be defined if the extension is From ed0abc7532320d7c0b5eac6f8bc9bf547c2bfc41 Mon Sep 17 00:00:00 2001 From: "Kornev, Nikita" Date: Wed, 14 Jan 2026 16:22:18 +0100 Subject: [PATCH 41/47] fix typos --- adoc/extensions/sycl_khr_includes.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index dbab1cdfe..af2828ac8 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -74,7 +74,7 @@ header file contents that provided in subsequent sections below. |Provides definition of the [code]#context# class. |[code]## -|Provides definition of the most index space identifiers from +|Provides definitions of most of the index space identifiers from <>. Classes like [code]#h_item#, [code]#group# and [code]#sub_group# are provided by other headers. @@ -116,7 +116,7 @@ related enumerations. class aliases. |[code]## -|Provides definitions of function objects like [code]#plus# or +|Provides definitions of function objects like [code]#plus# and [code]#logical_or# from <>. |[code]## @@ -364,7 +364,7 @@ This header provides definitions of: * [code]#usm::alloc# enumeration * [code]#usm_allocator# class * Free functions like [code]#malloc_device#, [code]#aligned_alloc_host#, - [code]#malloc# and [code]#get_pointer_type# as from sections + [code]#malloc# and [code]#get_pointer_type# from sections <> and <> [[sec:khr-includes-index-space]] From cf2a0c80e87c5e0cc6c8d6b70911e32a725e67f1 Mon Sep 17 00:00:00 2001 From: "Kornev, Nikita" Date: Wed, 14 Jan 2026 16:36:07 +0100 Subject: [PATCH 42/47] reorganize the headings --- adoc/extensions/sycl_khr_includes.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index af2828ac8..5effe6c48 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -189,6 +189,9 @@ headers. Nevertheless, implementations are encouraged to keep headers contents as small as reasonably possible to provide maximum benefit for users. {endnote} +[[sec:khr-includes-new-headers]] +== New headers + [[sec:khr-includes-version]] === [code]## header @@ -571,7 +574,7 @@ pre-adopted from the next C++ specification. This header contains definition of [code]#byte# type alias [[sec:khr-includes-other-extensions]] -=== Co-existence with other extensions +== Co-existence with other extensions Any extension which does not explicitly document how it can be accessed through header files should be assumed to be available only through From 2790b823574497715618afff5ced79c99bc4b7f0 Mon Sep 17 00:00:00 2001 From: "Kornev, Nikita" Date: Fri, 16 Jan 2026 13:45:43 +0100 Subject: [PATCH 43/47] Update existing KHR extensions --- adoc/extensions/sycl_khr_default_context.adoc | 10 ++++++++++ adoc/extensions/sycl_khr_dynamic_addrspace_cast.adoc | 12 ++++++++++++ adoc/extensions/sycl_khr_group_interface.adoc | 12 ++++++++++++ adoc/extensions/sycl_khr_max_work_group_queries.adoc | 12 ++++++++++++ adoc/extensions/sycl_khr_queue_empty_query.adoc | 10 ++++++++++ adoc/extensions/sycl_khr_queue_flush.adoc | 10 ++++++++++ adoc/extensions/sycl_khr_static_addrspace_cast.adoc | 12 ++++++++++++ adoc/extensions/sycl_khr_work_item_queries.adoc | 12 ++++++++++++ 8 files changed, 90 insertions(+) diff --git a/adoc/extensions/sycl_khr_default_context.adoc b/adoc/extensions/sycl_khr_default_context.adoc index 797ab0a76..dc0d3fd1c 100644 --- a/adoc/extensions/sycl_khr_default_context.adoc +++ b/adoc/extensions/sycl_khr_default_context.adoc @@ -11,6 +11,16 @@ This extension adds a new query function to retrieve this default context from a This extension has no dependencies on other extensions. +[[sec:khr-default-context-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the feature test macro is additionally provided by +[code]##. + [[sec:khr-default-context-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_dynamic_addrspace_cast.adoc b/adoc/extensions/sycl_khr_dynamic_addrspace_cast.adoc index 0886a0add..28056c535 100644 --- a/adoc/extensions/sycl_khr_dynamic_addrspace_cast.adoc +++ b/adoc/extensions/sycl_khr_dynamic_addrspace_cast.adoc @@ -12,6 +12,18 @@ clarifies the expected behavior of a dynamic address space cast. This extension has no dependencies on other extensions. +[[sec:khr-dynamic-addrspace-cast-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the APIs defined in the [code]#sycl::khr# namespace are +additionally provided by the header +[code]##, and the feature test macro is +additionally provided by [code]##. + [[sec:khr-dynamic-addrspace-cast-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_group_interface.adoc b/adoc/extensions/sycl_khr_group_interface.adoc index 47f554afb..1e21c83ba 100644 --- a/adoc/extensions/sycl_khr_group_interface.adoc +++ b/adoc/extensions/sycl_khr_group_interface.adoc @@ -14,6 +14,18 @@ This extension has no dependencies on other extensions. Some features of this extension are only available when a SYCL implementation conforms to {cpp23} or later. +[[sec:khr-group-interface-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the APIs defined in the [code]#sycl::khr# namespace are +additionally provided by the header [code]##, and +the feature test macro is additionally provided by +[code]##. + [[sec:khr-group-interface-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_max_work_group_queries.adoc b/adoc/extensions/sycl_khr_max_work_group_queries.adoc index b58141f14..dc8e78c52 100644 --- a/adoc/extensions/sycl_khr_max_work_group_queries.adoc +++ b/adoc/extensions/sycl_khr_max_work_group_queries.adoc @@ -11,6 +11,18 @@ is within the range of values returned by these queries. This extension does not depend on other extensions. +[[sec:khr-max-work-group-queries-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the APIs defined in the [code]#sycl::khr# namespace are +additionally provided by the header +[code]##, and the feature test macro is +additionally provided by [code]##. + [[sec:khr-max-work-group-queries-feature-test]] == Feature test macro An implementation supporting this extension must predefine the diff --git a/adoc/extensions/sycl_khr_queue_empty_query.adoc b/adoc/extensions/sycl_khr_queue_empty_query.adoc index cf5b00674..8b90be1e1 100644 --- a/adoc/extensions/sycl_khr_queue_empty_query.adoc +++ b/adoc/extensions/sycl_khr_queue_empty_query.adoc @@ -9,6 +9,16 @@ commands submitted to a queue have been completed. This extension has no dependencies on other extensions. +[[sec:khr-queue-empty-query-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the feature test macro is additionally provided by +[code]##. + [[sec:khr-queue-empty-query-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_queue_flush.adoc b/adoc/extensions/sycl_khr_queue_flush.adoc index 0a0fc65ad..e6fb69bb6 100644 --- a/adoc/extensions/sycl_khr_queue_flush.adoc +++ b/adoc/extensions/sycl_khr_queue_flush.adoc @@ -9,6 +9,16 @@ forward progress without the need to call [api]#queue::wait#. This extension has no dependencies on other extensions. +[[sec:khr-queue-flush-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the feature test macro is additionally provided by +[code]##. + [[sec:khr-queue-flush-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_static_addrspace_cast.adoc b/adoc/extensions/sycl_khr_static_addrspace_cast.adoc index beb63d97e..1a34dac38 100644 --- a/adoc/extensions/sycl_khr_static_addrspace_cast.adoc +++ b/adoc/extensions/sycl_khr_static_addrspace_cast.adoc @@ -16,6 +16,18 @@ without any performance overhead. This extension has no dependencies on other extensions. +[[sec:khr-static-addrspace-cast-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the APIs defined in the [code]#sycl::khr# namespace are +additionally provided by the header +[code]##, and the feature test macro is +additionally provided by [code]##. + [[sec:khr-static-addrspace-cast-feature-test]] == Feature test macro diff --git a/adoc/extensions/sycl_khr_work_item_queries.adoc b/adoc/extensions/sycl_khr_work_item_queries.adoc index c3e5dddab..34975e0d7 100644 --- a/adoc/extensions/sycl_khr_work_item_queries.adoc +++ b/adoc/extensions/sycl_khr_work_item_queries.adoc @@ -20,6 +20,18 @@ interfaces is not feasible. This extension has no dependencies on other extensions. +[[sec:khr-work-item-queries-header-files]] +== Header files + +The APIs defined in this extension are provided by the [code]## +header file. + +If the implementation also implements the <> +extension, then the APIs defined in the [code]#sycl::khr# namespace are +additionally provided by the header [code]##, +and the feature test macro is additionally provided by +[code]##. + [[sec:khr-work-item-queries-feature-test]] == Feature test macro From 39ee523166dd19fbfa94e98bfb3c23dedf250fdd Mon Sep 17 00:00:00 2001 From: "Kornev, Nikita" Date: Fri, 16 Jan 2026 14:30:34 +0100 Subject: [PATCH 44/47] Fix pre-commit --- adoc/extensions/sycl_khr_includes.adoc | 53 +++++++++++++------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 5effe6c48..45ad21e7c 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -15,8 +15,7 @@ This extension has no dependencies on other extensions. == Feature test macro An implementation supporting this extension must predefine the macro -[code]#SYCL_KHR_INCLUDES# to one of the values defined in the table -below. +[code]#SYCL_KHR_INCLUDES# to one of the values defined in the table below. [%header,cols="1,5"] |=== @@ -27,9 +26,8 @@ below. |Initial version of this extension. |=== -{note} -A <> implementation of SYCL cannot predefine macros outside -of header files. +{note} A <> implementation of SYCL cannot predefine macros +outside of header files. See <> for a portable way to check for this extension. {endnote} @@ -42,8 +40,9 @@ description of their content. All headers are provided under [code]## include path. The Description column in the table is intended to help you navigate the -extension document quicker. It does not offer the exaustive listing of each new -header file contents that provided in subsequent sections below. +extension document quicker. +It does not offer the exaustive listing of each new header file contents that +provided in subsequent sections below. [[table.khr-includes-list]] .List of headers provided by the extension @@ -173,20 +172,20 @@ exist within the [code]#::sycl# namespace as with the standard [code]## header. There is no guarantee that headers documented by this extension contain anything -else besides things listed in sections below. For example, [code]#queue# class -has methods which accept [code]#accessor# objects, but -[code]## is not required to provide a definition of -[code]#accessor#. +else besides things listed in sections below. +For example, [code]#queue# class has methods which accept [code]#accessor# +objects, but [code]## is not required to provide a +definition of [code]#accessor#. Therefore, a portable application should include the corresponding header to define [code]#accessor# definition explicitly. -{note} -However, there is no requirement for the implementations to **only** provide -through those headers exactly what's specified, i.e. they may contain other -functions and classes than documented in this extension. In fact, some classes, -functions or enumerations are documented to be available through multiple -headers. Nevertheless, implementations are encouraged to keep headers contents -as small as reasonably possible to provide maximum benefit for users. +{note} However, there is no requirement for the implementations to **only** +provide through those headers exactly what's specified, i.e. they may contain +other functions and classes than documented in this extension. +In fact, some classes, functions or enumerations are documented to be available +through multiple headers. +Nevertheless, implementations are encouraged to keep headers contents as small +as reasonably possible to provide maximum benefit for users. {endnote} [[sec:khr-includes-new-headers]] @@ -444,14 +443,14 @@ This header provides definitions of: * [code]#rounding_mode# enumeration * [code]#elem# struct and [code]#vec# class * Type aliases from <> -* [code]#+__writeable_swizzle__+# and [code]#+__const_swizzle__+# classes - from <> +* [code]#+__writeable_swizzle__+# and [code]#+__const_swizzle__+# classes from + <> In order to make simple swizzle functions ([code]#XYZW_SWIZZLE# and [code]#RGBA_SWIZZLE# from <>) available, the macro -[code]#SYCL_SIMPLE_SWIZZLES# should be defined before *any* other -[code]#sycl/# header is included. The recommended way of doing that is through -command line options. +[code]#SYCL_SIMPLE_SWIZZLES# should be defined before *any* other [code]#sycl/# +header is included. +The recommended way of doing that is through command line options. [[sec:khr-includes-marray]] === [code]## header @@ -481,8 +480,8 @@ This header provides definitions of: [code]#flush# or [code]#endl#) * [code]#setprecision# and [code]#setw# functions * [code]#stream# class -* [code]#template const stream& operator<<(const stream& os, const T& rhs)# - operator +* [code]#template const stream& operator<<(const stream& os, const + T& rhs)# operator [[sec:khr-includes-type-traits]] === [code]## header @@ -493,8 +492,8 @@ This header provides definitions of: [code]#is_property_of_v# from <> * [code]#is_group# and [code]#is_group_v# from <> * [code]#is_device_copyable# from <> -* [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# - and [code]#all_devices_have_v# from <> +* [code]#any_device_has#, [code]#any_device_has_v#, [code]#all_devices_have# and + [code]#all_devices_have_v# from <> * [code]#remove_decoration# type trait * [code]#known_identity#, [code]#known_identity_v#, [code]#has_known_identity# and [code]#has_known_identity_v# type traits From ffbde213cc5d5052f42a78d6091c9e4dceed10b2 Mon Sep 17 00:00:00 2001 From: "Kornev, Nikita" Date: Mon, 19 Jan 2026 13:18:41 +0100 Subject: [PATCH 45/47] Add Header files section --- adoc/extensions/sycl_khr_includes.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 45ad21e7c..4af16c945 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -11,6 +11,12 @@ are not used by an application. This extension has no dependencies on other extensions. +[[sec:khr-includes-header-files]] +== Header files + +The header files provided by this extension are located in the +[code]## directory. + [[sec:khr-includes-feature-test]] == Feature test macro From 1a9713f1ea5a43e003ec4764982a197bb2bff177 Mon Sep 17 00:00:00 2001 From: Nikita Kornev Date: Fri, 30 Jan 2026 13:24:10 +0100 Subject: [PATCH 46/47] Update adoc/extensions/sycl_khr_includes.adoc Co-authored-by: Verena Beckham --- adoc/extensions/sycl_khr_includes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 4af16c945..5f8433393 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -58,7 +58,7 @@ provided in subsequent sections below. |Description |[code]## -|Provides varios macro definitions. +|Provides various macro definitions. |[code]## |Provides definition of the [code]#queue# class. From 883ceb206f480c6d09341571ba35e037b121f3bf Mon Sep 17 00:00:00 2001 From: Konstantinos Parasyris Date: Tue, 21 Apr 2026 11:42:40 -0700 Subject: [PATCH 47/47] [KHR] Split builtin KHR include docs into per-section headers --- adoc/extensions/sycl_khr_includes.adoc | 50 +++++++++++++++++++++----- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/adoc/extensions/sycl_khr_includes.adoc b/adoc/extensions/sycl_khr_includes.adoc index 5f8433393..c943df1d4 100644 --- a/adoc/extensions/sycl_khr_includes.adoc +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -107,8 +107,22 @@ related enumerations. |[code]## |Provides definitions from <>, i.e. [code]#marray# class. -|[code]## -|Provides definitions of built-in functions from <>. +|[code]## +|Provides definitions of built-in functions from <>, +<> and +<>. + +|[code]## +|Provides definitions of built-in functions from <>. + +|[code]## +|Provides definitions of built-in functions from <>. + +|[code]## +|Provides definitions of built-in functions from <>. + +|[code]## +|Provides definitions of built-in functions from <>. |[code]## |Provides definitions of the [code]#group# and [code]#sub_group# classes. @@ -548,18 +562,38 @@ This header provides definitions of: [code]#joint_exclusive_scan# and [code]#joint_inclusive_scan# functions functions -[[sec:khr-includes-math]] -=== [code]## header +[[sec:khr-includes-builtins-math]] +=== [code]## header This header includes all SYCL built-in functions documented by sections: * <> * <> * <> -* <> -* <> -* <> -* <> + +[[sec:khr-includes-builtins-integer]] +=== [code]## header + +This header includes all SYCL built-in functions documented by +<>. + +[[sec:khr-includes-builtins-common]] +=== [code]## header + +This header includes all SYCL built-in functions documented by +<>. + +[[sec:khr-includes-builtins-geometric]] +=== [code]## header + +This header includes all SYCL built-in functions documented by +<>. + +[[sec:khr-includes-builtins-relational]] +=== [code]## header + +This header includes all SYCL built-in functions documented by +<>. [[sec:khr-includes-bit]] === [code]## header