[SYCL][Doc][RTC] Document [un]supported features and build_options

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<dir>` +
-`-I <dir>` +
-`--include-directory=<dir>` +
-`--include-directory <dir>`
-| Add `<dir>` 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=<dir>` (`-I<dir>`)
+
+Add `<dir>` 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=<name>[=<value>]` (`-D<name>[=<value>]`)
+
+Define macro `<name>`, optionally to the given `<value>`.
+
+===== `--undefine-macro=<name>` (`-U<name>`)
+
+Undefine macro `<name>`.
+
+==== 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<arg>`
+
+Pass `<arg>` to the target compiler. When using `-Xs<arg>`, a `-` is prepended
+to `<arg>` before handing it to the target compiler. Otherwise, `<arg>` 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.