From 7997ea50d68dc709487377f49636a610a4aa6764 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Fri, 24 Oct 2025 16:19:49 -0400 Subject: [PATCH 1/2] [SYCL][Doc] Add spec for device's default context Add a proposed specification to get the default context of the platform that contains a device. --- ...ext_oneapi_device_default_context.asciidoc | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc new file mode 100644 index 0000000000000..0744e80017b82 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc @@ -0,0 +1,112 @@ += sycl_ext_oneapi_device_default_context + +:source-highlighter: coderay +:coderay-linenums-mode: table + +// This section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en +:dpcpp: pass:[DPC++] +:endnote: —{nbsp}end{nbsp}note + +// Set the default source code type in this document to C++, +// for syntax highlighting purposes. This is needed because +// docbook uses c++ and html5 uses cpp. +:language: {basebackend@docbook:c++:cpp} + + +== Notice + +[%hardbreaks] +Copyright (C) 2025 Intel Corporation. All rights reserved. + +Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks +of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by +permission by Khronos. + + +== Contact + +To report problems with this extension, please open a new issue at: + +https://github.com/intel/llvm/issues + + +== Dependencies + +This extension is written against the SYCL 2020 revision 10 specification. +All references below to the "core SYCL specification" or to section numbers in +the SYCL specification refer to that revision. + + +== Status + +This is a proposed extension specification, intended to gather community +feedback. +Interfaces defined in this specification may not be implemented yet or may be in +a preliminary state. +The specification itself may also change in incompatible ways before it is +finalized. +*Shipping software products should not rely on APIs defined in this +specification.* + + +== Overview + +This extension provides a shortcut to get the platform's default context from a +`device` object. + + +== Specification + +=== Feature test macro + +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_DEVICE_DEFAULT_CONTEXT` 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. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|The APIs of this experimental extension are not versioned, so the + feature-test macro always has this value. +|=== + +=== New member function in the device class + +This extension adds the following new member function to the `device` class. + +[source,c++] +---- +class device { + // ... + context ext_oneapi_get_default_context(); +}; +---- + +''' + +[source,c++] +---- +context ext_oneapi_get_default_context(); +---- + +_Effects_: Equivalent to: + +[source,c++,indent=2] +---- +return get_platform().khr_get_default_context(); +---- + +''' From 508a2a5521db3f1008101fa338b79e5ae0135cbc Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Mon, 27 Oct 2025 09:08:48 -0400 Subject: [PATCH 2/2] Add note about relation to KHR Add a note about the relationship between this extension and sycl_khr_default_context. --- .../sycl_ext_oneapi_device_default_context.asciidoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc index 0744e80017b82..7c9ecbc2d3dd2 100644 --- a/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_device_default_context.asciidoc @@ -41,6 +41,19 @@ This extension is written against the SYCL 2020 revision 10 specification. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision. +[_Note:_ The APIs in this extension depend on the concept of a per-platform +default context as specified in section 4.6.2 "Platform class" of the core SYCL +specification. +As a convenience, this extension specification describes the behavior of its +APIs by using the `khr_get_default_context` function from {khr-default-context}[ +sycl_khr_default_context], however there is no true dependency on that +extension. +An implementation could still implement sycl_ext_oneapi_device_default_context +even without implementing sycl_khr_default_context because the core SYCL +specification still requires there to be a per-platform default context even if +the core SYCL specification does not provide a convenient way to get it. +_{endnote}_] + == Status