Skip to content

Clarify requirements for types in device code #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Pennycook wants to merge 11 commits into
base: main
Choose a base branch
from
Draft

Clarify requirements for types in device code #733

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
dac49fd
Clarify requirements for types in device code
Pennycook Feb 18, 2025
22334ab
Remove sentence about device compiler options
Pennycook Feb 19, 2025
d3238a4
Fix typo: descrived
Pennycook Feb 19, 2025
f4373e2
Clarify type requirements for enums
Pennycook Feb 19, 2025
e690144
Replace supported types with unsupported types
Pennycook Feb 20, 2025
ab95d12
Add note about the availability of extended types
Pennycook Feb 20, 2025
7b489a9
Add new section for standard library support
Pennycook Feb 20, 2025
6f04c82
Fix incorrect reference to long double types
Pennycook Feb 24, 2025
da1c0db
Add introduction to standard library section
Pennycook Apr 10, 2025
a339d3b
Remove note about enumerations with fixed type
Pennycook Apr 10, 2025
c0d33c0
Satisfy reflow
Pennycook Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 19 additions & 120 deletions adoc/chapters/device_compiler.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,132 +216,31 @@ The restriction waiver in <<discarded-statement>> or
<<device-function>>.
====

[[subsec:scalartypes]]
Copy link
Copy Markdown
Contributor

@gmlueck gmlueck Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that the latest version of the "main" branch has text that refers to this section identifier. (This was part of the recent vec clarification.) You will need to reword that new text somehow to avoid the reference.

== Built-in scalar data types
== Data types

In a SYCL device compiler, the device definition of all standard {cpp}
fundamental types from <<table.types.fundamental>> 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#);
Comment thread
Pennycook marked this conversation as resolved.
Outdated

- 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#.
Comment thread
Pennycook marked this conversation as resolved.

|====
- Any type aliases defined by the {cpp} core language (e.g.,
[code]#std::size_t#, [code]#std::ptrdiff_t#).
Comment thread
Pennycook marked this conversation as resolved.
Outdated

All types which are available in device code must have the same size, alignment
requirements, and representation on both host and device.
Comment on lines +232 to +233
Copy link
Copy Markdown

@tahonermann tahonermann Feb 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think enumeration types should be addressed in this section as well. There is an implementation requirement as well as a user requirement. For enumerations with a fixed underlying type (e.g., enum X : char), there should be a requirement that the same fixed type be specified for host and device code. Similarly, for enumerations without a fixed underlying type, there should be a requirement that the implementation select the same underlying type for host and device code.

Copy link
Copy Markdown
Contributor Author

@Pennycook Pennycook Feb 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense to me. I've added wording very similar to what you wrote here in f4373e2.

Copy link
Copy Markdown

@tahonermann tahonermann Feb 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updates for enumeration types looks good to me.

Copy link
Copy Markdown
Contributor

@gmlueck gmlueck Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm unresolving this conversation. It seems confusing to me to say that applications are required to choose the same underlying type for enumerations. Why state this specifically when there are other things an application could do that cause types to be different on host and device? For example, if an application defines members of a struct to be different on host and device, you would have a similar problem.

If we feel we need to say something about this, perhaps we could say it more generally like:

Applications that define types to be have different size, alignment requirement, or representation on host vs. device via the __SYCL_DEVICE_ONLY__ macro have undefined behavior.

Or maybe it should be "... implementation defined behavior"?

I think it is useful to specifically list __SYCL_DEVICE_ONLY__ here because that is the only way that an application possibly could define types differently. At least I can't think of any other way. You might point out that there are other macros like this in DPC++, but those are vendor extensions and are therefore out of scope of this spec.

Copy link
Copy Markdown

@tahonermann tahonermann Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is reasonable to relax the requirement that (user specified) fixed underlying types must match so long as device copyability rules retain a requirement for the same (or at least a compatible) fixed underlying type.

Copy link
Copy Markdown
Contributor Author

@Pennycook Pennycook Feb 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a general note like the one @gmlueck suggests would be useful for application developers, but I didn't think that was what @tahonermann was talking about here.

The wording I added in f4373e2 is in the "Device compiler" section, and I didn't intend it to be advice for application developers. The intent was to clarify that the implementation must guarantee that enumerations have matching types. The first sentence just says that enumerations with different fixed underlying types are invalid -- that means a device compiler (and more broadly, the implementation) shouldn't introduce any of those. The second sentence is probably the more important one, because it means that a device compiler may require specific logic to ensure that it selects the same underlying type as the host compiler if an enumeration has no fixed underlying type.

Copy link
Copy Markdown

@tahonermann tahonermann Feb 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With regard to explicit fixed types, there is both an implementation and a requirement on application developers.

I expect device code restrictions to be relaxed over time to allow more use of the C and C++ standard libraries in device code. Device code can already link with device-only TUs via SYCL_EXTERNAL. Maintaining a single C and C++ standard library that works for both host and device code isn't particularly realistic, especially when the host implementations are provided by, e.g., GNU C, libstdc++, Microsoft, etc... This increases the likelihood that enumeration types defined in these libraries will be differently specified for the host and the device. This imposes a requirement on the SYCL implementation to ensure such enumeration types are consistently defined if objects of those types might transition the host/device divide. We can either require all such types to be consistently defined, or we can require specific ones to be consistently defined so that those specific types satisfy device copyability rules, or we can say its all implementation-defined and code that uses such types is non-portable.

Likewise, user-defined enumeration types must be consistently defined to be copied between the host and device. For those cases, we can require all such types to be consistently defined, or we can place the requirement in the device copyable restrictions (with or without a compatible size/alignment allowance and corresponding std::underlying_type observability).

A device compiler may rely on additional command-line options to provide this
guarantee for specific combinations of host and device.
Comment thread
Pennycook marked this conversation as resolved.
Outdated

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 <<sec:device-aspects>>.
Comment thread
Pennycook marked this conversation as resolved.
Outdated

== Preprocessor directives and macros

Expand Down
22 changes: 5 additions & 17 deletions adoc/chapters/programming_interface.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<subsec:scalartypes>>.
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
<<table.types.fundamental>>.
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 <<table.types.additional>>.

In addition to the scalar types defined by {cpp}, SYCL defines a number of
scalar types as described in <<table.types.additional>>.

[[table.types.additional]]
.Additional scalar data types supported by SYCL
Expand Down