KhronosGroup / KhronosGroup/SYCL-Docs

__SYCL_DEVICE_ONLY__ definition is unclear

Open
#430 0 comments 1 reaction 0 assignees View on GitHub
clarification
Dominant language
JavaScript
Stars
158
Forks
80
Avg merge
7d 6h
Merged PRs (30d)
5

Description

I've just realized that all uses of `__SYCL_DEVICE_ONLY__` in code snippets in the core SYCL specification are incorrect with the current wording of the specification. However, I guess that the macro is simply defined incorrectly and that code snippets do actually represent the intent of the specification.

So, from [5.6. Preprocessor directives and macros](https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_preprocessor_directives_and_macros):

> The standard C++ preprocessing directives and macros are supported. The following preprocessor macros must be defined by all conformant implementations:
> `__SYCL_DEVICE_ONLY__` is defined to `1` if the source file is being compiled with a SYCL device compiler which does not produce host binary;

What concerns me is that there is no description of what is a state of the macro when source file is **not** being compiled with a SYCL device compiler which does not produce host binary: is it defined to `0`, or is it undefined?

That phrase at the beginning that the following preprocessor macros **must** be defined doesn't add clarity here either. Moreover, it suggest that the macro should always be defined to some value, it is just when we are within a dedicated device pass, it is set to `1`. In that case, a couple of code snippets we have in the spec are now incorrect:
```c++
#ifdef __SYCL_DEVICE_ONLY__
// If macro is defined on host as well, the check should look like:
// #if __SYCL_DEVICE_ONLY__ == 1
using vector_t = __unspecified__;
#endif

vec();

explicit constexpr vec(const DataT& arg);

template constexpr vec(const ArgTN&... args);

constexpr vec(const vec& rhs);

#ifdef __SYCL_DEVICE_ONLY__
// same here
vec(vector_t nativeVector);

operator vector_t() const;
#endif
```

Considering that `#ifdef __SYCL_DEVICE_ONLY__` is quite a popular construct in both SYCL apps and SYCL implementations, we should probably clarify macro behavior for host compilation pass

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with section 5.6, “Preprocessor directives and macros,” and review the shown __SYCL_DEVICE_ONLY__ snippets in the core SYCL specification. Clarify whether the macro is defined during host compilation and ensure the wording and conditional examples consistently describe its host and device behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.