Copyright © 2023-2023 Intel Corporation. All rights reserved.
Khronos® is a registered trademark and SYCL™ and SPIR™ are trademarks of The Khronos Group Inc. OpenCL™ is a trademark of Apple Inc. used by permission by Khronos.
To report problems with this extension, please open a new issue at:
This extension is written against the SYCL 2020 revision 8 specification. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision.
This extension also depends on the following other SYCL extensions:
This is an experimental extension specification, intended to provide early access to features and gather community feedback. Interfaces defined in this specification are implemented in DPC, but they are not finalized and may change incompatibly in future versions of DPC without prior notice. Shipping software products should not rely on APIs defined in this specification.
This extension adds APIs that allow the application to dynamically generate the source code for a kernel, which it can then compile and enqueue to a device. The APIs allow a kernel to be written in any of several possible languages, where support for each of these languages is defined by a separate extension. As a result, this extension provides a framework of APIs for online compilation of kernels, but it does not define the details for any specific kernel language. These details are provided by other extensions.
The new APIs added by this extension are an expansion of the existing
kernel_bundle capabilities.
Thus, an application can create a kernel bundle from a source string and then
build the bundle into "executable" bundle state.
Once the application obtains a kernel object, it can use existing APIs from
the core SYCL specification to set the value of kernel arguments and enqueue
the kernel to a device.
This extension provides a feature-test macro as described in the core SYCL
specification.
An implementation supporting this extension must predefine the macro
SYCL_EXT_ONEAPI_KERNEL_COMPILER
to one of the values defined in the table below.
Applications can test for the existence of this macro to determine if
the implementation supports this feature, or applications can test the macro’s
value to determine which of the extension’s features the implementation
supports.
| Value | Description |
|---|---|
1 |
The APIs of this experimental extension are not versioned, so the feature-test macro always has this value. |
This extension adds the ext_oneapi_source enumerator to sycl::bundle_state
to identify a kernel bundle that is represented as a source code string.
namespace sycl {
enum class bundle_state : /*unspecified*/ {
// ...
ext_oneapi_source
};
} // namespace syclThis extension adds the source_language enumeration, which identifies
possible languages for a kernel bundle that is in ext_oneapi_source state:
namespace sycl::ext::oneapi::experimental {
enum class source_language : /*unspecified*/ {
// see below
};
} // namespace sycl::ext::oneapi::experimentalHowever, there are no enumerators defined by this extension. Instead, this enumeration is an extension point for other extensions, which can specify the exact semantics of each possible kernel language.
This extension adds the following new member functions to the device class:
Returns: The value |
This extension adds the following new free functions to create and build a
kernel bundle in ext_oneapi_source state.
Preconditions: There are two overloads of this function: one that reads the
source code of the kernel from a Effects: Creates a new kernel bundle that represents a kernel written in the
source language Returns: The newly created kernel bundle, which has Throws:
[Note: Calling this function does not attempt to compile the source code. As a result, syntactic errors in the source code string are not diagnosed by this function. This function succeeds even if some devices in |
|
Constraints: Available only when Effects (1): The source code from The new bundle has the same associated context as Effects (2): Equivalent to Returns: The newly created kernel bundle, which has Throws:
[Note: An uncaught |
This extension adds the following properties, which can be used in conjunction
with the build function that is defined above:
This property provides build options that may affect the compilation or linking of the kernel, where each build option is a string. There are no standard build options that are common across all source languages. Instead, each source language specification defines its own set of build options. Effects (1): Constructs a Effects (2): Constructs a |
|
This property allows the caller to request a log to be created with additional
information about the compilation and linking operations.
Use of this property is not required in order to get information about a failed
build.
When a build fails, an Instead, the Effects (1): Constructs a |
This extension adds the following constraint to some of the kernel_bundle
member functions from the core SYCL specification:
Constraints: This function is not available when
Stateisbundle_state::ext_oneapi_source.
This new constraint applies to the following member functions:
-
empty; -
All overloads and function templates of
has_kernel; -
get_kernel_ids; -
contains_specialization_constants; -
native_specialization_constant; -
has_specialization_constant; -
get_specialization_constant; -
begin; and -
end.
As a result, the only kernel_bundle member functions from the core SYCL
specification that are available for bundles in ext_oneapi_source state are
get_backend, get_context, and get_devices.
Kernels created from online compilation of source code do not have any
associated kernel_id.
Therefore, the function kernel_bundle::get_kernel_ids returns an empty vector
of kernel_id objects if the kernel bundle was created from a bundle of state
bundle_state::ext_oneapi_source.
This extensions adds the following new kernel_bundle member functions:
namespace sycl {
template <bundle_state State>
class kernel_bundle {
// ...
bool ext_oneapi_has_kernel(const std::string &name);
kernel ext_oneapi_get_kernel(const std::string &name);
};
} // namespace sycl
Constraints: This function is not available when Returns: The value |
|
Constraints: This function is available only when Returns: A Throws:
|
The following example demonstrates how a SYCL application can define a kernel as a string and then compile and launch it.
#include <sycl/sycl.hpp>
namespace syclex = sycl::ext::oneapi::experimental;
int main() {
sycl::queue q;
// The source code for one or more kernels, defined in one of
// the supported source languages.
std::string source = R"""(
/* language specific kernel source code */
)""";
// Create a kernel bundle in "source" state. The "some-language" is
// a stand-in for the enumerator telling which source language is used.
sycl::kernel_bundle<sycl::bundle_state::ext_oneapi_source> kb_src =
syclex::create_kernel_bundle_from_source(
q.get_context(),
syclex::source_language::/*some-language*/,
source);
sycl::kernel_bundle<sycl::bundle_state::executable> kb_exe =
syclex::build(kb_src);
// Get the kernel via its name. The "kernel-name" is a stand-in for the
// actual kernel name in the source string.
sycl::kernel k = kb_exe.ext_oneapi_get_kernel("kernel-name");
q.submit([&](sycl::handler &cgh) {
// Any arguments for the kernel must be set manually.
cgh.set_args(/*...*/);
// Launch the kernel according to its type.
// This assumes a simple "range" kernel.
cgh.parallel_for(sycl::range{1024}, k);
});
}