[SYCL][Doc] Add spec to get device index

sycl/doc/extensions/proposed/sycl_ext_oneapi_device_index.asciidoc

@@ -0,0 +1,162 @@
+= sycl_ext_oneapi_device_index
+
+: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
+
+Some SYCL applications find it more convenient to represent a device as an
+integer value rather than using the `device` class.
+The core SYCL specification already allows an application to do this by using
+the `device` object's index in the list of all devices returned by
+`device::get_devices`.
+However, converting between a `device` object and its index could be expensive
+because the conversion requires a search through all of the devices returned by
+`get_devices`.
+This extension adds functions that make it easy and efficient to do this
+conversion.
+
+
+== 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_INDEX` 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
+|Initial version of this extension.
+|===
+
+=== New member functions in the device class
+
+This extension adds the following new member functions to the `device` class.
+
+[frame=all,grid=none,separator="@"]
+|====
+a@
+[source,c++]
+----
+class device {
+  // ...
+  size_t ext_oneapi_to_index() const;
+  static device ext_oneapi_from_index(size_t index);
+};
+----
+|====
+
+'''
+
+[frame=all,grid=none,separator="@"]
+|====
+a@
+[source,c++]
+----
+size_t ext_oneapi_to_index() const;
+----
+|====
+
+_Returns:_ If this device is a root device as defined by the core SYCL
+specification, returns the index that it has in the `std::vector` that is
+returned when calling `device::get_devices()`.
+
+_Throws:_ An `exception` with the `errc::invalid` error code if this device is
+not a root device.
+
+'''
+
+[frame=all,grid=none,separator="@"]
+|====
+a@
+[source,c++]
+----
+static device ext_oneapi_from_index(size_t index);
+----
+|====
+
+_Returns:_ If the `index` is within range of the `std::vector` that is returned
+when calling `device::get_devices()`, returns a copy of the `device` object
+which has that index.
+
+_Throws:_ An `exception` with the `errc::invalid` error code if the `index` is
+out of range.
+
+'''
+
+
+== Example
+
+[source,c++]
+----
+#include <sycl/sycl.hpp>
+
+int main() {
+  sycl::device d1;  // Get the default device.
+                    // There is no guarantee this has index 0.
+
+  size_t index = d1.ext_oneapi_to_index();
+  sycl::device d2 = sycl::device::ext_oneapi_from_index(index);
+  assert(d1 == d2);
+}
+----