[SYCL][Doc] Add device_specific_kernel_queries extension.

sycl/doc/extensions/DeviceSpecificKernelQueries/SYCL_INTEL_device_specific_kernel_queries.asciidoc

@@ -0,0 +1,160 @@
+= SYCL_INTEL_device_specific_kernel_queries
+
+: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
+
+:blank: pass:[ +]
+
+// 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}
+
+// This is necessary for asciidoc, but not for asciidoctor
+:cpp: C++
+
+== Introduction
+IMPORTANT: This specification is a draft.
+
+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.
+
+NOTE: This document is better viewed when rendered as html with asciidoctor.
+GitHub does not render image icons.
+
+This document describes an extension to rename device-specific kernel queries
+to better describe the operations performed.
+
+== Name Strings
+
++SYCL_INTEL_device_specific_kernel_queries+
+
+== Notice
+
+Copyright (c) 2020 Intel Corporation.  All rights reserved.
+
+== Status
+
+Working Draft
+
+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.
+
+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.
+
+== Version
+
+Built On: {docdate} +
+Revision: 1
+
+== Contact
+Felipe de Azevedo Piovezan, Intel (felipe 'dot' de 'dot' azevedo 'dot' piovezan 'at' intel 'dot' com)
+
+== Dependencies
+
+This extension is written against the SYCL 1.2.1 specification, Revision 6.
+
+== Overview
+
+OpenCL provides two functions for querying properties of a kernel:
+`clGetKernelInfo` is used for kernel properties that are device agnostic,
+whereas `clGetKernelWorkGroupInfo` is used for kernel and work-group properties
+that depend on a specific device. The name `clGetKernelWorkGroupInfo` doesn't
+convey the API's intended use explicitly, that is, queries for
+*device-specific* properties. In this sense, `clGetKernelWorkGroupInfo` is a
+misnomer for some uses of the API.
+
+SYCL inherited these names in the form of the queries `kernel::get_info` and
+`kernel::get_work_group_info`. This extension renames the latter (and its
+template arguments as appropriate) in order to align the query name with its
+functionality.
+
+== Modifications of SYCL 1.2.1 Specification
+
+=== Change Section 4.8.7 Kernel class
+
+==== Change `kernel` class interface
+
+Remove lines 29-31 (inclusive) from the `kernel` class interface:
+
+[source,c++,`sycl::kernel`,linenums]
+----
+template <info::kernel_work_group param>
+typename info::param_traits<info::kernel_work_group, param>::return_type
+get_work_group_info(const device &dev) const;
+----
+
+Add function overload `get_info` to the `kernel` class interface:
+
+[source,c++,`sycl::kernel`,linenums]
+----
+template <info::kernel_device_specific param>
+typename info::param_traits<info::kernel_device_specific, param>::return_type
+get_info(const device &dev) const;
+----
+
+==== Change table 4.83 Member functions of the Kernel class
+
+Remove row `get_work_group_info(const device &dev)`:
+
+[width="40%",frame="topbot",options="header,footer"]
+|======================
+|Member functions |Description
+|`template <info::kernel_work_group param>typename info::param_traits<info::kernel_work_group, param>::return_type get_work_group_info(const device &dev)const` |
+Query information from the work-group from a kernel using the info::kernel_work_group descriptor for a specific device
+|======================
+
+Add row `get_info(const device &dev)`:
+
+[width="40%",frame="topbot",options="header,footer"]
+|======================
+|Member functions |Description
+|`template <info::kernel_device_specific param>typename info::param_traits<info::kernel_device_specific, param>::return_type get_info(const device &dev)const` |
+Query information from a kernel using the info::kernel_device_specific descriptor for a specific device.
+|======================
+
+==== Change table 4.85 Kernel work-group information descriptors
+
+Rename table to: +Kernel device-specific information descriptors+.
+
+Replace all references to `info::kernel_work_group` with
+`info::kernel_device_specific`.
+
+==== Change A.5 Kernel Information Descriptors
+
+Rename `enum class kernel_work_group: int` to `enum class
+kernel_device_specific: int`.
+
+== Issues
+
+None.
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-04-15|Felipe de Azevedo Piovezan|*Initial public working draft*
+|========================================
+
+//************************************************************************
+//Other formatting suggestions:
+//
+//* Use *bold* text for host APIs, or [source] syntax highlighting.
+//* Use +mono+ text for device APIs, or [source] syntax highlighting.
+//* Use +mono+ text for extension names, types, or enum values.
+//* Use _italics_ for parameters.
+//************************************************************************