From dac49fdf0536384854f1fbff97259d947dfe03ee Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Tue, 18 Feb 2025 14:57:15 +0000 Subject: [PATCH 01/11] Clarify requirements for types in device code --- adoc/chapters/device_compiler.adoc | 139 ++++------------------- adoc/chapters/programming_interface.adoc | 22 +--- 2 files changed, 24 insertions(+), 137 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index f8b3348f1..45fc51c87 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -216,132 +216,31 @@ The restriction waiver in <> or <>. ==== -[[subsec:scalartypes]] -== Built-in scalar data types +== Data types -In a SYCL device compiler, the device definition of all standard {cpp} -fundamental types from <> must match the host -definition of those types, in both size and alignment. -A device compiler may have this preconfigured so that it can match them based on -the definitions of those types on the platform, or there may be a necessity for -a device compiler command-line option to ensure the types are the same. +The following types must be available in device code: -The standard {cpp} fixed width types, e.g. [code]#int8_t#, [code]#int16_t#, -[code]#int32_t#,[code]#int64_t#, should have the same size as defined by the -{cpp} standard for host and device. +- The fundamental data types defined by the {cpp} core language (i.e., + [code]#bool#, [code]#char#, [code]#signed char#, [code]#unsigned char#, + [code]#short int#, [code]#unsigned short int#, [code]#int#, [code]#unsigned + int#, [code]#long int#, [code]#unsigned long int#, [code]#long long int#, + [code]#unsigned long long int#, [code]#float# and [code]#double#); +- The fixed width types defined by the {cpp} core language (e.g., + [code]#int8_t#, [code]#int16_t#, [code]#int32_t#, [code]#int64_t#); and -[[table.types.fundamental]] -.Fundamental data types supported by SYCL -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Fundamental data type @ Description -a@ -[source] ----- -bool ----- - a@ A conditional data type which can be either true or false. The value - true expands to the integer constant 1 and the value false expands to the - integer constant 0. - -a@ -[source] ----- -char ----- - a@ A signed or unsigned 8-bit integer, as defined by the {cpp} core language - -a@ -[source] ----- -signed char ----- - a@ A signed 8-bit integer, as defined by the {cpp} core language - -a@ -[source] ----- -unsigned char ----- - a@ An unsigned 8-bit integer, as defined by the {cpp} core language - -a@ -[source] ----- -short int ----- - a@ A signed integer of at least 16-bits, as defined by the {cpp} core language - -a@ -[source] ----- -unsigned short int ----- - a@ An unsigned integer of at least 16-bits, as defined by the {cpp} core language - -a@ -[source] ----- -int ----- - a@ A signed integer of at least 16-bits, as defined by the {cpp} core language - -a@ -[source] ----- -unsigned int ----- - a@ An unsigned integer of at least 16-bits, as defined by the {cpp} core language - -a@ -[source] ----- -long int ----- - a@ A signed integer of at least 32-bits, as defined by the {cpp} core language - -a@ -[source] ----- -unsigned long int ----- - a@ An unsigned integer of at least 32-bits, as defined by the {cpp} core language - -a@ -[source] ----- -long long int ----- - a@ An integer of at least 64-bits, as defined by the {cpp} core language - -a@ -[source] ----- -unsigned long long int ----- - a@ An unsigned integer of at least 64-bits, as defined by the {cpp} core language - -a@ -[source] ----- -float ----- - a@ A 32-bit floating-point. The float data type must conform to the IEEE 754 - single precision storage format. - -a@ -[source] ----- -double ----- - a@ A 64-bit floating-point. The double data type must conform to the IEEE 754 - double precision storage format. This type is only supported on devices - that have [code]#aspect::fp64#. - -|==== +- Any type aliases defined by the {cpp} core language (e.g., + [code]#std::size_t#, [code]#std::ptrdiff_t#). +All types which are available in device code must have the same size, alignment +requirements, and representation on both host and device. +A device compiler may rely on additional command-line options to provide this +guarantee for specific combinations of host and device. +The availability of these types in device code does not guarantee that they will +be supported by all devices. +Some types are only supported on devices with specific device aspects, as +descrived in <>. == Preprocessor directives and macros diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index af92ab351..ba77f1cbf 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -17809,25 +17809,13 @@ std::error_code make_error_code(errc e) noexcept; == Data types -SYCL as a {cpp} programming model supports the {cpp} core language data types, -and it also provides the ability for all SYCL applications to be executed on -SYCL compatible devices. -The scalar and vector data types that are supported by the SYCL system are -defined below. -More details about the SYCL device compiler support for fundamental and backend -interoperability types are found in <>. +All types which are available in device code must have the same size, alignment +requirements, and representation on both host and device. +=== Scalar types -=== Scalar data types - -The fundamental {cpp} data types which are supported in SYCL are described in -<>. -Note these types are fundamental and therefore do not exist within the -[code]#sycl# namespace. - -Additional scalar data types which are supported by SYCL within the [code]#sycl# -namespace are described in <>. - +In addition to the scalar types defined by {cpp}, SYCL defines a number of +scalar types as described in <>. [[table.types.additional]] .Additional scalar data types supported by SYCL From 22334ab7a7def1244223901363c0d70d3d4ae271 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Wed, 19 Feb 2025 10:46:42 +0000 Subject: [PATCH 02/11] Remove sentence about device compiler options --- adoc/chapters/device_compiler.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 45fc51c87..562b78691 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -234,8 +234,6 @@ The following types must be available in device code: All types which are available in device code must have the same size, alignment requirements, and representation on both host and device. -A device compiler may rely on additional command-line options to provide this -guarantee for specific combinations of host and device. The availability of these types in device code does not guarantee that they will be supported by all devices. From d3238a4e649d6aad6ddc15a38f0820efcae5a762 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Wed, 19 Feb 2025 10:47:58 +0000 Subject: [PATCH 03/11] Fix typo: descrived --- adoc/chapters/device_compiler.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 562b78691..e6e583b92 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -238,7 +238,7 @@ requirements, and representation on both host and device. The availability of these types in device code does not guarantee that they will be supported by all devices. Some types are only supported on devices with specific device aspects, as -descrived in <>. +described in <>. == Preprocessor directives and macros From f4373e2ab29ac15636fd4c36c1cac8db109ce6b8 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Wed, 19 Feb 2025 11:17:42 +0000 Subject: [PATCH 04/11] Clarify type requirements for enums --- adoc/chapters/device_compiler.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index e6e583b92..5f7d8fa52 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -240,6 +240,11 @@ be supported by all devices. Some types are only supported on devices with specific device aspects, as described in <>. +For enumerations with a fixed underlying type, the same fixed type must be +specified for host and device. +For enumerations without a fixed underlying type, the implementation must select +the same underlying type on host and device. + == Preprocessor directives and macros The standard {cpp} preprocessing directives and macros are supported. From e690144874fc6c10c1dd6366ab9d179299634980 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 20 Feb 2025 16:41:11 +0000 Subject: [PATCH 05/11] Replace supported types with unsupported types A list of types that cannot be used in device code is clearer than what we had before, and will help to ensure that we give due consideration to additional types introduced in future versions of ISO C++. --- adoc/chapters/device_compiler.adoc | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 5f7d8fa52..756d3a2e4 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -204,6 +204,7 @@ Amongst other things, this restriction makes it illegal for a However, a function may be defined in another translation unit if the implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. + * Use of [code]#long double# types results in undefined behavior. Inside a <> or in the case of a <>, any code accepted by the C++ standard in this @@ -218,28 +219,16 @@ The restriction waiver in <> or == Data types -The following types must be available in device code: - -- The fundamental data types defined by the {cpp} core language (i.e., - [code]#bool#, [code]#char#, [code]#signed char#, [code]#unsigned char#, - [code]#short int#, [code]#unsigned short int#, [code]#int#, [code]#unsigned - int#, [code]#long int#, [code]#unsigned long int#, [code]#long long int#, - [code]#unsigned long long int#, [code]#float# and [code]#double#); - -- The fixed width types defined by the {cpp} core language (e.g., - [code]#int8_t#, [code]#int16_t#, [code]#int32_t#, [code]#int64_t#); and - -- Any type aliases defined by the {cpp} core language (e.g., - [code]#std::size_t#, [code]#std::ptrdiff_t#). +All fundamental types defined by the {cpp} core language must be available in +device code except for those listed in <>. +However, the availability of these types in device code does not guarantee that +they will be supported by all devices. +Some types are only supported on devices with specific device aspects, as +described in <>. All types which are available in device code must have the same size, alignment requirements, and representation on both host and device. -The availability of these types in device code does not guarantee that they will -be supported by all devices. -Some types are only supported on devices with specific device aspects, as -described in <>. - For enumerations with a fixed underlying type, the same fixed type must be specified for host and device. For enumerations without a fixed underlying type, the implementation must select From ab95d1215c4ae471b2c93ab7738dad6372137f21 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 20 Feb 2025 17:15:10 +0000 Subject: [PATCH 06/11] Add note about the availability of extended types These are implementation-defined, so whether they are available in device code should also be implementation-defined. --- adoc/chapters/device_compiler.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 756d3a2e4..1ebf23e60 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -221,8 +221,11 @@ The restriction waiver in <> or All fundamental types defined by the {cpp} core language must be available in device code except for those listed in <>. -However, the availability of these types in device code does not guarantee that -they will be supported by all devices. +Whether extended integer and/or extended floating-point types are available in +device code is implementation-defined. + +The availability of a type in device code does not guarantee that it will be +supported by all devices. Some types are only supported on devices with specific device aspects, as described in <>. From 7b489a9689d29d040841e60a800745437aca178c Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 20 Feb 2025 17:28:13 +0000 Subject: [PATCH 07/11] Add new section for standard library support This gives us a place to talk about things like: - Which C++ standard library features (e.g., type aliases) are guaranteed to work on the device; and - Whether there are any additional restrictions on C++ standard library behavior. --- adoc/chapters/device_compiler.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 1ebf23e60..2cbb501b4 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -281,6 +281,25 @@ literal with greater value. In addition, for each <> supported, the preprocessor macros described in <> must be defined by all conformant implementations. +[[sec:standard-library-support]] +== {cpp} standard library support + +=== Type aliases + +The following type aliases must alias the same types on host and device: + + * [code]#std::size_t#; + * [code]#std::ptrdiff_t#; + * [code]#std::max_align_t#; + * [code]#std::nullptr_t#; and + * The type aliases for integer types defined in [code]##. + +=== Type traits + +For any type available in device code, specializations of the following type +traits must have identical definitions on host and device: + + * [code]#std::numeric_limits# [[sec:optional-kernel-features]] == Optional kernel features From 6f04c82c1caf2269e94d1f1a07e0d70ce26a61a2 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Mon, 24 Feb 2025 09:41:53 +0000 Subject: [PATCH 08/11] Fix incorrect reference to long double types There is only one long double type. Co-authored-by: Tom Honermann --- adoc/chapters/device_compiler.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 2cbb501b4..b49207f8e 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -204,7 +204,7 @@ Amongst other things, this restriction makes it illegal for a However, a function may be defined in another translation unit if the implementation defines the [code]#SYCL_EXTERNAL# macro as described in <>. - * Use of [code]#long double# types results in undefined behavior. + * Use of the [code]#long double# type results in undefined behavior. Inside a <> or in the case of a <>, any code accepted by the C++ standard in this From da1c0db2e23e1ad79f35c6970975ec49fd370201 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 10 Apr 2025 09:55:18 +0100 Subject: [PATCH 09/11] Add introduction to standard library section --- adoc/chapters/device_compiler.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index b49207f8e..98c250d51 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -284,6 +284,11 @@ in <> must be defined by all conformant implementations. [[sec:standard-library-support]] == {cpp} standard library support +In general, any use of functions or types from the [code]#std# namespace in +device code produces undefined behavior. However, the functions and types +listed in this section are guaranteed to have defined semantics when used in +device code. + === Type aliases The following type aliases must alias the same types on host and device: From a339d3b7c442d90ed2dda6b709fd5b3dace2e871 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 10 Apr 2025 09:56:53 +0100 Subject: [PATCH 10/11] Remove note about enumerations with fixed type --- adoc/chapters/device_compiler.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 98c250d51..1adb99cd8 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -232,8 +232,6 @@ described in <>. All types which are available in device code must have the same size, alignment requirements, and representation on both host and device. -For enumerations with a fixed underlying type, the same fixed type must be -specified for host and device. For enumerations without a fixed underlying type, the implementation must select the same underlying type on host and device. From c0d33c0505af44bc45a80f30823213243afe8db7 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 10 Apr 2025 10:00:47 +0100 Subject: [PATCH 11/11] Satisfy reflow --- adoc/chapters/device_compiler.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adoc/chapters/device_compiler.adoc b/adoc/chapters/device_compiler.adoc index 1adb99cd8..d625c7881 100644 --- a/adoc/chapters/device_compiler.adoc +++ b/adoc/chapters/device_compiler.adoc @@ -283,9 +283,9 @@ in <> must be defined by all conformant implementations. == {cpp} standard library support In general, any use of functions or types from the [code]#std# namespace in -device code produces undefined behavior. However, the functions and types -listed in this section are guaranteed to have defined semantics when used in -device code. +device code produces undefined behavior. +However, the functions and types listed in this section are guaranteed to have +defined semantics when used in device code. === Type aliases