diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index 0e77dc256..2e9a1cfe2 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -1774,6 +1774,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 a56159e66..7dc4ec918 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 5541fd1f3..ff10d2aed 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-deduction-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 diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc index 520ad7dd7..79af605b0 100644 --- a/adoc/extensions/index.adoc +++ b/adoc/extensions/index.adoc @@ -14,4 +14,5 @@ include::sycl_khr_default_context.adoc[leveloffset=2] include::sycl_khr_queue_empty_query.adoc[leveloffset=2] include::sycl_khr_group_interface.adoc[leveloffset=2] include::sycl_khr_max_work_group_queries.adoc[leveloffset=2] -include::sycl_khr_queue_flush.adoc[leveloffset=2] \ No newline at end of file +include::sycl_khr_queue_flush.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..dbab1cdfe --- /dev/null +++ b/adoc/extensions/sycl_khr_includes.adoc @@ -0,0 +1,584 @@ +[[sec:khr-includes]] += sycl_khr_includes + +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. + +[[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} +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]] +== Extension overview + +<> 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 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 +[width="100%",options="header",cols="1,2"] +|==== +|Header +|Description + +|[code]## +|Provides varios macro definitions. + +|[code]## +|Provides definition of the [code]#queue# class. + +|[code]## +|Provides definition of the [code]#handler# class. + +|[code]## +|Provides definition of the [code]#event# class. + +|[code]## +|Provides definitions of the [code]#device# class and device selectors. + +|[code]## +|Provides definition of the [code]#platform# class. + +|[code]## +|Provides definition of the [code]#context# class. + +|[code]## +|Provides definition of the most index space identifiers from +<>. 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# +class and USM free functions for memory management like [code]#malloc_shared#. + +|[code]## +|Provides definition of the [code]#buffer# class. + +|[code]## +|Provides definitions of the [code]#accessor#, [code]#local_accessor# and +[code]#host_accessor# classes. + +|[code]## +|Provides definition of the [code]#atomic_ref# class. + +|[code]## +|Provides definition of the [code]#half# data type. + +|[code]## +|Provides definitions from <>, i.e. [code]#vec# class and +related enumerations. + +|[code]## +|Provides definitions from <>, i.e. [code]#marray# class. + +|[code]## +|Provides definitions of built-in functions from <>. + +|[code]## +|Provides definitions of the [code]#group# and [code]#sub_group# classes. + +|[code]## +|Provides definitions of group operations such as broadcasts or scans. + +|[code]## +|Provides definitions of the [code]#multi_ptr# class and related address space +class aliases. + +|[code]## +|Provides definitions of function objects like [code]#plus# or +[code]#logical_or# from <>. + +|[code]## +|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 from <>, i.e. [code]#stream# class +and related functions. + +|[code]## +|Provides definitions of various type traits like [code]#is_property#, +[code]#is_group#, [code]#is_device_copyable#, etc. + +|[code]## +|Provides definition of the [code]#property_list# class. + +|[code]## +|Provides definitions from <>, such as +[code]#kernel_bundle#, [code]#kernel#, [code]#kernel_id#, [code]#device_image# +and [code]#specialization_id# classes. + +|[code]## +|Provides definition of the [code]#kernel_handler# class. + +|[code]## +|Provides definitions of the [code]#sampler#, [code]#sampled_image#, +[code]#unsampled_image# and corresponding accessors. + +|[code]## +|Provides definitions of error handling APIs from <>, such as +[code]#exception# and [code]#exception_list# classes. + +|[code]## +|Provides definitions of the [code]#private_memory# and [code]#h_item# classes. + +|[code]## +|Provides definition of the [code]#interop_handle# class. + +|[code]## +|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]## +|Provides definition of the [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. + +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#. +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. +{endnote} + +[[sec:khr-includes-version]] +=== [code]## header + +This header provides definitions of: + +* [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 macros are defined before +[code]## is included. + +The code below demonstrates a portable way to detect if this extension is +supported: + +[source] +---- +#if __has_include() +// 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 +// supported. +#endif + +#if SYCL_KHR_INCLUDES +// Extension is supported +#include +#else +// Extension is not supported +#include +#endif +---- + +[[sec:khr-includes-backend]] +=== [code]## header + +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 from <> + +[[sec:khr-includes-device]] +=== [code]## header + +This header provides definitions of: + +* [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 from + <> +* All other enumerations from <> +* [code]#enum class aspect# + +[[sec:khr-includes-platform]] +=== [code]## header + +This header provides definitions of: + +* [code]#platform# class +* All [code]#info::platform# information descriptors from + <> + +[[sec:khr-includes-context]] +=== [code]## header + +This header provides definitions of: + +* [code]#context# class +* All [code]#info::context# information descriptors from + <> + +[[sec:khr-includes-queue]] +=== [code]## header + +This header provides definitions of: + +* [code]#queue# class +* All [code]#info::queue# information descriptors from + <> +* All [code]#properties::queue# types from <> + +[[sec:khr-includes-handler]] +=== [code]## header + +This header provides definition of: + +* [code]#handler# class + +[[sec:khr-includes-event]] +=== [code]## header + +This header provides definitions of: + +* [code]#event# class +* All [code]#info::event# information descriptors from + <> +* All [code]#info::event_command_status# descriptors from + <> +* All [code]#info::event_profiling# descriptors from + <> + +[[sec:khr-includes-buffer]] +=== [code]## header + +This header provides definitions of: + +* [code]#buffer# class +* [code]#buffer_allocator# +* All [code]#property::buffer# types from <> + +[[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 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# from <> +* [code]#addresing_mode#, [code]#filtering_mode#, + [code]#coordinate_normalization_mode# enumerations and [code]#image_sampler# + struct + +[[sec:khr-includes-accessor]] +=== [code]## header + +This header provides definitions of: + +* [code]#accessor#, [code]#host_accessor# and [code]#local_accessor# classes +* [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 from <> + +[[sec:khr-includes-multi-ptr]] +=== [code]## header + +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 from <> + +[[sec:khr-includes-hierarchical-parallelism]] +=== [code]## header + +This header provides definitions of: + +* [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]#malloc# and [code]#get_pointer_type# as from sections + <> and <> + +[[sec:khr-includes-index-space]] +=== [code]## header + +This header provides definitions of: + +* [code]#id# +* [code]#item# +* [code]#nd_item# +* [code]#range# +* [code]#nd_range# + +[[sec:khr-includes-reduction]] +=== [code]## header + +This header provides definitions of: + +* [code]#reduction# interface +* [code]#reducer# class +* All [code]#property::reduction# types from <> + +This header also includes [code]## for +convenience. + +[[sec:khr-includes-interop-handle]] +=== [code]## header + +This header provides definition of: + +* [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]#kernel_bundle# classes +* All [code]#info::kernel# and [code]#info::kernel_device_specific# information + descriptors from <> +* Free functions like [code]#get_kernel_bundle#, [code]#has_kernel_bundle#, + [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 + +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]#sycl::errc# + +[[sec:khr-includes-half]] +=== [code]## header + +This header provides definition of [code]#half# data type + +[[sec:khr-includes-vec]] +=== [code]## header + +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 <> + +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. + +[[sec:khr-includes-marray]] +=== [code]## header + +This header provides definitions of: + +* [code]#marray# class +* Type aliases from <> + +[[sec:khr-includes-atomic]] +=== [code]## header + +This header provides definitions of: + +* [code]#atomic_fence# function +* [code]#memory_order#, [code]#memory_scope# enumerations +* [code]#atomic_ref# class from <> +* [code]#atomic# class and free functions like [code]#atomic_store#, + [code]#atomic_fetch_and# from <> + +[[sec:khr-includes-stream]] +=== [code]## header + +This header provides definitions of: + +* [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 provides definitions of: + +* [code]#is_property#, [code]#is_property_v#, [code]#is_property_of# and + [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]#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 + +This header provides definition of: + +* [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]#bit_xor# +* [code]#logical_and# +* [code]#logical_or# +* [code]#minimum# +* [code]#maximum# + +[[sec:khr-includes-groups]] +=== [code]## header + +This header provides definitions of: + +* [code]#group# and [code]#sub_group# classes +* [code]#device_event# class +* [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 + +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-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 +[code]##. + +If an implementation supports this extension, then any macro defined by other +supported extensions must be defined in [code]##. + +== Open issues/questions +