[SYCL][DOC] Add initial spec draft for new default device

sycl/doc/extensions/proposed/sycl_ext_oneapi_global_defaults.asciidoc

@@ -0,0 +1,150 @@
+= sycl_ext_oneapi_global_defaults
+
+
+: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++]
+
+// 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) 2024 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 9 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:
+
+* link:../supported/sycl_ext_oneapi_defaultcontext.asciidoc[
+  sycl_ext_oneapi_defaultcontext]
+* link:../experimental/sycl_ext_oneapi_enqueue_functions.asciidoc[
+  sycl_ext_oneapi_enqueue_functions]
+* link:../supported/sycl_ext_oneapi_enqueue_barrier.asciidoc[
+  sycl_ext_oneapi_enqueue_barrier]
+
+
+== 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 introduces additional state into SYCL in order to simplify 
+programming for developers. The extension provides a mechanism to both set and
+query the 'current' global `sycl::device`. By adding the notion of a 'current'
+device, this can simplify interfaces and reduce the amount of boilerplate code
+required to write a SYCL application.
+
+This extension also introduces the notion of a default queue for a device. When
+combined with the notion of the current device and the extension for new 
+free enqueue functions, this allows for a simplified way to write SYCL code.
+
+== 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_GLOBAL_DEFAULTS` 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 free functions
+
+This extension adds the following new free functions:
+
+
+'''
+
+[frame=all,grid=none,separator="@"]
+!====
+a@
+[source,c++]
+----
+namespace sycl::ext::oneapi::experimental::this_thread {
+
+sycl::device get_current_device();
+
+} // namespace sycl::ext::oneapi::experimental::this_thread
+----
+!====
+
+_Returns:_ The current default device for the calling host thread. If `set_current_device()` 
+has not been called by this thread, returns the device selected by the default device selector.
+
+_Remarks:_ Calling this method from within a host task or an asynchronous error handler is
+undefined behavior.
+
+[frame=all,grid=none,separator="@"]
+!====
+a@
+[source,c++]
+----
+namespace sycl::ext::oneapi::experimental::this_thread {
+
+void set_current_device(sycl::device dev);
+
+} // namespace sycl::ext::oneapi::experimental::this_thread
+----
+!====
+
+_Returns:_ Nothing
+
+_Effects:_ Sets the current default device to `dev` for the current host thread.
+
+_Remarks:_ Calling this method from within a host task or an asynchronous error handler is
+undefined behavior.
+
+'''
+
+== Issues
+. [RESOLVED] Should the currrent device be global or should we also support a per-thread
+   device? Answer: It should be per-thread to align with the behavior of other programming
+   models.
+. [OPEN] We want to add a default queue per device. Should this queue be in-order or out-of-order?
+   Do we want to allow the user to specify this?