Skip to content

Commit 07f0cba

Browse files
PennycookPennycook
committed
Restore experimental version of the extension
1 parent 05f1f77 commit 07f0cba

File tree

1 file changed

+226
-0
lines changed

1 file changed

+226
-0
lines changed

‎sycl/doc/extensions/experimental/SYCL_EXT_ONEAPI_FREE_FUNCTION_QUERIES.asciidoc

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
= SYCL_INTEL_free_function_queries
2+
:source-highlighter: coderay
3+
:coderay-linenums-mode: table
4+
5+
// This section needs to be after the document title.
6+
:doctype: book
7+
:toc2:
8+
:toc: left
9+
:encoding: utf-8
10+
:lang: en
11+
12+
13+
:blank: pass:[ +]
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+
== Introduction
21+
IMPORTANT: This specification is a draft.
22+
23+
NOTE: 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.
24+
25+
NOTE: This document is better viewed when rendered as html with asciidoctor. GitHub does not render image icons.
26+
27+
This document describes an extension that adds features for SYCL work items and groups to be available globally.
28+
29+
30+
== Name Strings
31+
32+
+SYCL_INTEL_free_function_queries+
33+
34+
== Notice
35+
36+
Copyright (c) 2020 Intel Corporation. All rights reserved.
37+
38+
== Status
39+
40+
Working Draft
41+
42+
This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension.
43+
44+
Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products.
45+
46+
== Version
47+
48+
Built On: {docdate} +
49+
Revision: 1
50+
51+
== Contact
52+
Ruslan Arutyunyan, Intel (ruslan 'dot' arutyunyan 'at' intel 'dot' com)
53+
54+
John Pennycook, Intel (john 'dot' pennycook 'at' intel 'dot' com)
55+
56+
== Dependencies
57+
58+
This extension is written against the SYCL 2020 Provisional specification, Revision 1.
59+
60+
== Overview
61+
62+
The extension allows to get `id`, `item`, `nd_item`, `group`, `sub_group` instances globally
63+
64+
== Modifications of SYCL 2020 provisional specification
65+
66+
=== Changes in 4.10.1.3 (id class)
67+
68+
==== Changes in synopsis
69+
70+
===== Add the following free function
71+
72+
[source,c++,multiptr,linenums]
73+
----
74+
template <int dimensions>
75+
id<dimensions> this_id();
76+
----
77+
78+
===== Add the table with free functions description
79+
80+
|===
81+
a|
82+
[source,c++,multiptr,linenums]
83+
----
84+
template <int dimensions>
85+
id<dimensions> this_id();
86+
---- a|
87+
Returns the `id` instance representing the current work item in a `range`. The prerequisites:
88+
89+
* `dimensions` value passed to `this_id` function shall match `dimensions` value passed to the `range` when the `parallel_for` is called
90+
91+
* shall only be invoked within the `parallel_for` with `range` or `nd_range` as the argument.
92+
93+
If prerequisites are not fulfilled the behavior is undefined
94+
|===
95+
96+
=== Changes in 4.10.1.4 (item class)
97+
98+
==== Changes in synopsis
99+
100+
===== Add the following free function
101+
102+
[source,c++,multiptr,linenums]
103+
----
104+
template <int dimensions>
105+
item<dimensions> this_item();
106+
----
107+
108+
===== Add the table with free functions description
109+
110+
|===
111+
a|
112+
[source,c++,multiptr,linenums]
113+
----
114+
template <int dimensions>
115+
item<dimensions> this_item();
116+
---- a|
117+
Returns the `item` instance representing the current work item in a `range`. The prerequisites:
118+
119+
* `dimensions` value passed to `this_item` function shall match `dimensions` value passed to the `range` when the `parallel_for` is called
120+
121+
* shall only be invoked within the `parallel_for` with `range` or `nd_range` as the argument
122+
123+
If prerequisites are not fulfilled the behavior is undefined
124+
|===
125+
126+
=== Changes in 4.10.1.5 (nd_item class)
127+
128+
==== Changes in synopsis
129+
130+
===== Add the following free function
131+
132+
[source,c++,multiptr,linenums]
133+
----
134+
template <int dimensions>
135+
nd_item<dimensions> this_nd_item();
136+
----
137+
138+
===== Add the table with free functions description
139+
140+
|===
141+
a|
142+
[source,c++,multiptr,linenums]
143+
----
144+
template <int dimensions>
145+
nd_item<dimensions> this_nd_item();
146+
---- a|
147+
Returns the `nd_item` instance representing the current work item in a `nd_range`. The prerequisites:
148+
149+
* `dimensions` value passed to `this_nd_item` function shall match `dimensions` value passed to the `nd_range` when the `parallel_for` is called
150+
151+
* shall only be invoked within the `parallel_for` with `nd_range` as the argument
152+
153+
If prerequisites are not fulfilled the behavior is undefined
154+
|===
155+
156+
=== Changes in 4.10.1.7 (group class)
157+
158+
==== Changes in synopsis
159+
160+
===== Add the following free function
161+
162+
[source,c++,multiptr,linenums]
163+
----
164+
template <int dimensions>
165+
group<dimensions> this_group();
166+
----
167+
168+
===== Add the table with free functions description
169+
170+
|===
171+
a|
172+
[source,c++,multiptr,linenums]
173+
----
174+
template <int dimensions>
175+
group<dimensions> this_group();
176+
---- a|
177+
Returns the `group` instance representing the particular work-group within the parallel execution. The prerequisites:
178+
179+
* `dimensions` value passed to `this_group` function shall match `dimensions` value passed to the `range` when the `parallel_for` is called
180+
181+
* shall only be called from within the `parallel_for` with `nd_range` as the argument
182+
183+
If prerequisites are not fulfilled the behavior is undefined
184+
|===
185+
186+
=== Changes in 4.10.1.8 (sub_group class)
187+
188+
==== Changes in synopsis
189+
190+
===== Add the following free function
191+
192+
[source,c++,multiptr,linenums]
193+
----
194+
sub_group this_sub_group();
195+
----
196+
197+
===== Add the table with free functions description
198+
199+
|===
200+
a|
201+
[source,c++,multiptr,linenums]
202+
----
203+
sub_group this_sub_group();
204+
---- a|
205+
Returns the `sub_group` instance representing the particular `sub-group` within the parallel execution. The prerequisites:
206+
207+
* shall only be called from within the `parallel_for` with `nd_range` as the argument
208+
209+
If prerequisites are not fulfilled the behavior is undefined
210+
|===
211+
212+
== Feature test macro
213+
214+
This extension provides a feature-test macro as described in the core SYCL
215+
specification section 6.3.3 "Feature test macros". Therefore, an implementation
216+
supporting this extension must predefine the macro `SYCL_EXT_ONEAPI_FREE_FUNCTION_QUERIES`
217+
to one of the values defined in the table below. Applications can test for the
218+
existence of this macro to determine if the implementation supports this
219+
feature, or applications can test the macro's value to determine which of the
220+
extension's APIs the implementation supports.
221+
222+
[%header,cols="1,5"]
223+
|===
224+
|Value |Description
225+
|1 |Initial extension version. Base features are supported.
226+
|===

0 commit comments

Comments
 (0)