From 190f0186fa002248e6bc2c6c0773c79b0ccb3247 Mon Sep 17 00:00:00 2001 From: Julian Oppermann Date: Fri, 14 Mar 2025 03:24:51 +0000 Subject: [PATCH 1/4] [SYCL][Doc][RTC] Document [un]supported features and `build_options` Signed-off-by: Julian Oppermann --- .../sycl_ext_oneapi_kernel_compiler.asciidoc | 124 ++++++++++++++++-- 1 file changed, 111 insertions(+), 13 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc index 1f783bd115cde..428beb7c528ff 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc @@ -958,17 +958,115 @@ this extension. The SYCL runtime compiler supports the following {dpcpp} options to be passed in the `build_options` property. -[%header,cols="1,3"] -|=== -|Option -|Notes - -|`-I` + -`-I ` + -`--include-directory=` + -`--include-directory ` -| Add `` to to the search list for include files (see section "Including +[_Note:_ Some options have equivalent long (starting with `--`) and short +(starting with `-`) option names. When using the long option name, an argument +can be either separated by `=` in the same element of the `build_options` +property, or given as a separate element. When using the short option name, an +argument is either append directly after the option name, or given as a separate +element in the `build_options` property. The following example shows how to +construct the `build_options` property with each of the forms. + +[source,c++] +---- +build_options{{ + {"--include-directory=dir1"}, + {"--include-directory"}, {"dir2"}, + {"-Idir3"}, + {"-I"}, {"dir4"} +}}; +---- +_{endnote}_] + +==== Preprocessor options + +===== `--include-directory=` (`-I`) + +Add `` to to the search list for include files (see section "Including files when the language is ``sycl``"). This is useful, for example, to compile -kernels using external libraries. Note that for the second and fourth form, -`dir` is a separate element in the `build_options` list. -|=== +kernels using external libraries. + +===== `--define-macro=[=]` (`-D[=]`) + +Define macro ``, optionally to the given ``. + +===== `--undefine-macro=` (`-U`) + +Undefine macro ``. + +==== Diagnostic options + +The usual warning (starting with `-W`) and remark (starting with `-R`) emission +options are supported. Note that the `save_log` property must be used to obtain +detailed output from the compilation process. + +==== SYCL-specific options + +===== `-Xs` + +Pass `` to the target compiler. When using `-Xs`, a `-` is prepended +to `` before handing it to the target compiler. Otherwise, `` is +passed on unmodified. + +For example, the following forms are equivalent: + +[source,c++] +---- +build_options{{ + {"-XsDFOO=bar"}, + {"-Xs"}, {"-DFOO=bar"} +}}; +---- + +===== `-fsycl-rtc-mode` + +Relax the requirement that parameter types for free-function kernels must be +forward-declarable. + +=== Unsupported `build_options` when the language is `sycl` + +The SYCL runtime compiler currently does not support the following {dpcpp} +options and associated features. + +==== Ahead-of-time compilation + +With the exception of the `-Xs` option, all other options to control +ahead-of-time (AOT) compilation, such as `-fsycl-targets`, are unsupported. + +[_Note:_ +The kernels in a SYCL source string are compiled automatically to native code +for all devices passed to the `build` function (see section "New free functions +to create and build kernel bundles"). +_{endnote}_] + +==== Other compiler actions + +As the {dpcpp} frontend is integrated tightly in the runtime compilation +pipeline, all options to change the compiler action (e.g. `-c`, `-S`) or output +files (`-o`) are unsupported. Options related to linking (e.g. `-L`) are +unsupported, including the SYCL-specific `-fsycl-link` action. + +==== Debug info + +Currently, debugging of runtime-compiled kernels is not supported. Hence, all +options related to the generation and embedding of debug information (e.g. `-g`) +are unsupported. + +==== `invoke_simd` + +While the SYCL runtime compiler supports ESIMD kernels and source strings +containing a mix of SYCL and ESIMD kernels, the `invoke_simd` functionality is +currently unsupported. The related `-fno-sycl-device-code-split-esimd` option is +unsupported. + +==== Sanitizers + +Device, memory and thread sanitizers are unsupported for runtime-compiled +kernels. The `-fsanitize=` option is unsupported. + +=== Caching + +The `kernel_compiler` implementation in {dpcpp} supports persistent caching. To +enable it, set the the environment variable `SYCL_CACHE_PERSISTENT=1`. The +location of the cache can be changed by setting `SYCL_CACHE_DIR`. Refer to +https://intel.github.io/llvm/design/KernelProgramCache.html#persistent-cache for +more details on how to control the cache. From 202909d98abf8ba52fb903921a3a5ddafbd24cd9 Mon Sep 17 00:00:00 2001 From: Julian Oppermann Date: Mon, 17 Mar 2025 06:00:02 +0000 Subject: [PATCH 2/4] Remove note markup; typo. Signed-off-by: Julian Oppermann --- .../sycl_ext_oneapi_kernel_compiler.asciidoc | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc index 428beb7c528ff..850badf71bf09 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc @@ -958,13 +958,13 @@ this extension. The SYCL runtime compiler supports the following {dpcpp} options to be passed in the `build_options` property. -[_Note:_ Some options have equivalent long (starting with `--`) and short -(starting with `-`) option names. When using the long option name, an argument -can be either separated by `=` in the same element of the `build_options` -property, or given as a separate element. When using the short option name, an -argument is either append directly after the option name, or given as a separate -element in the `build_options` property. The following example shows how to -construct the `build_options` property with each of the forms. +Some options have equivalent long (starting with `--`) and short (starting with +`-`) option names. When using the long option name, an argument can be either +separated by `=` in the same element of the `build_options` property, or given +as a separate element. When using the short option name, an argument is either +appended directly after the option name, or given as a separate element in the +`build_options` property. The following example shows how to construct the +`build_options` property with each of the forms. [source,c++] ---- @@ -975,7 +975,6 @@ build_options{{ {"-I"}, {"dir4"} }}; ---- -_{endnote}_] ==== Preprocessor options @@ -1032,11 +1031,9 @@ options and associated features. With the exception of the `-Xs` option, all other options to control ahead-of-time (AOT) compilation, such as `-fsycl-targets`, are unsupported. -[_Note:_ The kernels in a SYCL source string are compiled automatically to native code for all devices passed to the `build` function (see section "New free functions to create and build kernel bundles"). -_{endnote}_] ==== Other compiler actions From 62be7813bc9fd18914b9631f3ba3406de911476a Mon Sep 17 00:00:00 2001 From: Julian Oppermann Date: Mon, 17 Mar 2025 10:28:00 +0000 Subject: [PATCH 3/4] Update: -W/-R, -Xs. Drop: debug info Signed-off-by: Julian Oppermann --- .../sycl_ext_oneapi_kernel_compiler.asciidoc | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc index 850badf71bf09..e85a6369dcb7f 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc @@ -994,16 +994,21 @@ Undefine macro ``. ==== Diagnostic options -The usual warning (starting with `-W`) and remark (starting with `-R`) emission -options are supported. Note that the `save_log` property must be used to obtain -detailed output from the compilation process. +The `build_options` property accepts warning (`-W`) and remark (`-R`) emission +options supported by the `clang` compiler. For an overview of these options, see +https://clang.llvm.org/docs/DiagnosticsReference.html. The specific options +available for SYCL runtime compilation depend on the version of the {dpcpp} +compiler distributed with the SYCL runtime used by the application. + +Note: Use the `save_log` property to obtain detailed output from the compilation +process. ==== SYCL-specific options ===== `-Xs` -Pass `` to the target compiler. When using `-Xs`, a `-` is prepended -to `` before handing it to the target compiler. Otherwise, `` is +Pass `` to the backend of the device compiler. When using `-Xs`, a `-` +is prepended to `` before handing it to the backend. Otherwise, `` is passed on unmodified. For example, the following forms are equivalent: @@ -1042,12 +1047,6 @@ pipeline, all options to change the compiler action (e.g. `-c`, `-S`) or output files (`-o`) are unsupported. Options related to linking (e.g. `-L`) are unsupported, including the SYCL-specific `-fsycl-link` action. -==== Debug info - -Currently, debugging of runtime-compiled kernels is not supported. Hence, all -options related to the generation and embedding of debug information (e.g. `-g`) -are unsupported. - ==== `invoke_simd` While the SYCL runtime compiler supports ESIMD kernels and source strings From daf9769e3ec065424ecd9382019c4b3dd1745ba0 Mon Sep 17 00:00:00 2001 From: Julian Oppermann Date: Mon, 17 Mar 2025 21:32:16 +0000 Subject: [PATCH 4/4] Rework unsupported options section Signed-off-by: Julian Oppermann --- .../sycl_ext_oneapi_kernel_compiler.asciidoc | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc index e85a6369dcb7f..0057a9265e984 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_kernel_compiler.asciidoc @@ -1026,38 +1026,44 @@ build_options{{ Relax the requirement that parameter types for free-function kernels must be forward-declarable. -=== Unsupported `build_options` when the language is `sycl` +=== Known issues and limitations when the language is `sycl` -The SYCL runtime compiler currently does not support the following {dpcpp} -options and associated features. +==== Changing the compiler action or output -==== Ahead-of-time compilation +As the {dpcpp} frontend is integrated tightly in the runtime compilation +pipeline, the application cannot change the runtime compiler's action (e.g. +`-c`, `-S`) or output file (`-o`). Similarly, options related to linking (e.g. +`-L`) are incompatible, including the SYCL-specific `-fsycl-link` action. The +implementation throws an `exception` with the `errc::invalid` error code when it +detects an option that conflicts with the runtime compilation pipeline. -With the exception of the `-Xs` option, all other options to control -ahead-of-time (AOT) compilation, such as `-fsycl-targets`, are unsupported. +==== Ahead-of-time compilation The kernels in a SYCL source string are compiled automatically to native code for all devices passed to the `build` function (see section "New free functions -to create and build kernel bundles"). - -==== Other compiler actions - -As the {dpcpp} frontend is integrated tightly in the runtime compilation -pipeline, all options to change the compiler action (e.g. `-c`, `-S`) or output -files (`-o`) are unsupported. Options related to linking (e.g. `-L`) are -unsupported, including the SYCL-specific `-fsycl-link` action. +to create and build kernel bundles"). The implementation rejects the use of the +`-fsycl-targets=` options to request ahead-of-time (AOT) compilation, and throws +an `exception` with the `errc::invalid` error code when this option is detected. +The application can use the `-Xs` option described above to pass options to the +backend of the device compiler, but all other options to control AOT compilation +are ignored. ==== `invoke_simd` -While the SYCL runtime compiler supports ESIMD kernels and source strings -containing a mix of SYCL and ESIMD kernels, the `invoke_simd` functionality is -currently unsupported. The related `-fno-sycl-device-code-split-esimd` option is -unsupported. +The SYCL runtime compiler currently does not implement the logic required to +support the `-fno-sycl-device-code-split-esimd` option, and throws an +`exception` with the `errc::invalid` error code when this option is detected. As +a consequence, the `invoke_simd` functionality is unavailable. However, the SYCL +runtime compiler supports ESIMD kernels and source strings containing a mix of +SYCL and ESIMD kernels. ==== Sanitizers -Device, memory and thread sanitizers are unsupported for runtime-compiled -kernels. The `-fsanitize=` option is unsupported. +The implementation currently lacks the necessary linking of device libraries to +support device, memory and thread sanitizers for runtime-compiled code. If the +`-fsanitize=` option is detected, an `exception` with the `errc::invalid` error +code is thrown. Other means of activating the sanitizer (e.g. via +`-Xsycl-device-frontend`) may cause the runtime compilation to fail. === Caching