[SYCL][Doc] Add reqd_work_group_size extension (#1057)

Signed-off-by: John Pennycook <[email protected]>

Author: Pennycook

sycl/doc/extensions/ReqdWorkGroupSize/README.md

@@ -0,0 +1,4 @@
+# SYCL_INTEL_reqd_work_group_size
+
+Attribute asserting that a kernel may be invoked only with a specific work-group size.
+

sycl/doc/extensions/ReqdWorkGroupSize/SYCL_INTEL_reqd_work_group_size.asciidoc

@@ -0,0 +1,121 @@
+= SYCL_INTEL_reqd_work_group_size
+: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 that introduces a +reqd_work_group_size+ attribute for SYCL kernels.  This attribute enables developers to declare that a kernel may be invoked only with a specific work-group size.
+
+== Name Strings
+
++SYCL_INTEL_reqd_work_group_size+
+
+== Notice
+
+Copyright (c) 2019 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
+John Pennycook, Intel (john 'dot' pennycook 'at' intel 'dot' com)
+
+== Dependencies
+
+This extension is written against the SYCL 1.2.1 specification, Revision v1.2.1-6.
+
+== Overview
+
+The +reqd_work_group_size+ attribute is declared in the +intel+ namespace, and can be attached to the declaration of kernel functors and kernel lambdas using {cpp}11 attribute specifier syntax:
+
+[source,c++]
+----
+struct Functor
+{
+  void operator()(nd_item<1> it) [[intel::reqd_work_group_size(32)]]
+  { ... }
+};
+----
+
+[source,c++]
+----
+auto kernel = [](nd_item<1> it) [[intel::reqd_work_group_size(32)]] { ... };
+----
+
+The attribute-token +intel::reqd_work_group_size+ shall appear at most once in each _attribute-list_. The attribute may be applied to the function-type in a function declaration. The first declaration of a function shall specify the +intel::reqd_work_group_size+ attribute if any declaration of that function specifies the +intel::reqd_work_group_size+ attribute. If a function is declared with the +intel::reqd_work_group_size+ attribute in one translation unit and the same function is declared without the +intel::reqd_work_group_size+ attribute in another translation unit, the program is ill-formed and no diagnostic is required.
+
+SYCL device compilers should give a compilation error if the required work-group size is unsupported.  If the kernel is submitted for execution using an incompatible work-group size, the SYCL runtime must throw a SYCL +nd_range_error+.
+
+== Attribute Syntax
+
+The attribute has three variants, corresponding to one-, two- and three-dimensional work-groups:
+
+[source,c++]
+----
+[[intel::reqd_work_group_size(dim0)]]
+[[intel::reqd_work_group_size(dim0, dim1)]]
+[[intel::reqd_work_group_size(dim0, dim1, dim2)]]
+----
+
+The sizes are written in row-major format.  Each argument to the attribute must be a +constexpr+ integral value.  The dimensionality of the attribute variant used must match the dimensionality of the work-group used to invoke the kernel.
+
+== Issues
+
+None.
+
+//. asd
+//+
+//--
+//*RESOLUTION*: Not resolved.
+//--
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-01-24|John Pennycook|*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.
+//************************************************************************