Skip to content

Commit 29435fc

Browse files
authored
[SYCL][Doc] Add spec for device's default context (#20469)
Add a proposed specification to get the default context of the platform that contains a device.
1 parent 24794c4 commit 29435fc

File tree

1 file changed

+125
-0
lines changed

1 file changed

+125
-0
lines changed
Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
= sycl_ext_oneapi_device_default_context
2+
3+
:source-highlighter: coderay
4+
:coderay-linenums-mode: table
5+
6+
// This section needs to be after the document title.
7+
:doctype: book
8+
:toc2:
9+
:toc: left
10+
:encoding: utf-8
11+
:lang: en
12+
:dpcpp: pass:[DPC++]
13+
:endnote: —{nbsp}end{nbsp}note
14+
15+
// Set the default source code type in this document to C++,
16+
// for syntax highlighting purposes. This is needed because
17+
// docbook uses c++ and html5 uses cpp.
18+
:language: {basebackend@docbook:c++:cpp}
19+
20+
21+
== Notice
22+
23+
[%hardbreaks]
24+
Copyright (C) 2025 Intel Corporation. All rights reserved.
25+
26+
Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks
27+
of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by
28+
permission by Khronos.
29+
30+
31+
== Contact
32+
33+
To report problems with this extension, please open a new issue at:
34+
35+
https://github.com/intel/llvm/issues
36+
37+
38+
== Dependencies
39+
40+
This extension is written against the SYCL 2020 revision 10 specification.
41+
All references below to the "core SYCL specification" or to section numbers in
42+
the SYCL specification refer to that revision.
43+
44+
[_Note:_ The APIs in this extension depend on the concept of a per-platform
45+
default context as specified in section 4.6.2 "Platform class" of the core SYCL
46+
specification.
47+
As a convenience, this extension specification describes the behavior of its
48+
APIs by using the `khr_get_default_context` function from {khr-default-context}[
49+
sycl_khr_default_context], however there is no true dependency on that
50+
extension.
51+
An implementation could still implement sycl_ext_oneapi_device_default_context
52+
even without implementing sycl_khr_default_context because the core SYCL
53+
specification still requires there to be a per-platform default context even if
54+
the core SYCL specification does not provide a convenient way to get it.
55+
_{endnote}_]
56+
57+
58+
== Status
59+
60+
This is a proposed extension specification, intended to gather community
61+
feedback.
62+
Interfaces defined in this specification may not be implemented yet or may be in
63+
a preliminary state.
64+
The specification itself may also change in incompatible ways before it is
65+
finalized.
66+
*Shipping software products should not rely on APIs defined in this
67+
specification.*
68+
69+
70+
== Overview
71+
72+
This extension provides a shortcut to get the platform's default context from a
73+
`device` object.
74+
75+
76+
== Specification
77+
78+
=== Feature test macro
79+
80+
This extension provides a feature-test macro as described in the core SYCL
81+
specification.
82+
An implementation supporting this extension must predefine the macro
83+
`SYCL_EXT_ONEAPI_DEVICE_DEFAULT_CONTEXT` to one of the values defined in the
84+
table below.
85+
Applications can test for the existence of this macro to determine if the
86+
implementation supports this feature, or applications can test the macro's value
87+
to determine which of the extension's features the implementation supports.
88+
89+
[%header,cols="1,5"]
90+
|===
91+
|Value
92+
|Description
93+
94+
|1
95+
|The APIs of this experimental extension are not versioned, so the
96+
feature-test macro always has this value.
97+
|===
98+
99+
=== New member function in the device class
100+
101+
This extension adds the following new member function to the `device` class.
102+
103+
[source,c++]
104+
----
105+
class device {
106+
// ...
107+
context ext_oneapi_get_default_context();
108+
};
109+
----
110+
111+
'''
112+
113+
[source,c++]
114+
----
115+
context ext_oneapi_get_default_context();
116+
----
117+
118+
_Effects_: Equivalent to:
119+
120+
[source,c++,indent=2]
121+
----
122+
return get_platform().khr_get_default_context();
123+
----
124+
125+
'''

0 commit comments

Comments
 (0)