diff --git a/sycl/doc/extensions/DeviceSpecificKernelQueries/SYCL_INTEL_device_specific_kernel_queries.asciidoc b/sycl/doc/extensions/DeviceSpecificKernelQueries/SYCL_INTEL_device_specific_kernel_queries.asciidoc new file mode 100644 index 0000000000000..54a361c8e2dcd --- /dev/null +++ b/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 +typename info::param_traits::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 +typename info::param_traits::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 typename info::param_traits::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 typename info::param_traits::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. +//************************************************************************