[SYCL][Doc] Update sub-group extension docs (#1330)

Splits sub-group functionality into three extensions:
- SubGroup (sub_group class and device queries)
- SubGroupAlgorithms (GroupAlgorithm support and permute)
- GroupMask (sub_group::mask_type and ballot)

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

Author: Pennycook

sycl/doc/extensions/GroupMask/README.md

@@ -0,0 +1,3 @@
+# SYCL_INTEL_group_mask
+
+A new `group_mask` class providing an ability to efficiently represent subsets of work-items in a group for which a given Boolean condition holds.

sycl/doc/extensions/GroupMask/SYCL_INTEL_group_mask.asciidoc

@@ -0,0 +1,290 @@
+= SYCL_INTEL_group_mask
+: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}
+
+== 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 which adds a +group_mask+ type.  Such a mask can be used to efficiently represent subsets of work-items in a group for which a given Boolean condition holds.  Group mask functionality is currently limited to groups that are instances of the +sub_group+ class.
+
+== Name Strings
+
++SYCL_INTEL_group_mask+
+
+== 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
+John Pennycook, Intel (john 'dot' pennycook 'at' intel 'dot' com)
+
+== Dependencies
+
+This extension is written against the SYCL 1.2.1 specification, Revision 6 and the following extensions:
+
+- +SYCL_INTEL_sub_group+
+
+== Overview
+
+A group mask is an integral type sized such that each work-item in the group is represented by a single bit. Such a mask can be used to efficiently represent subsets of work-items in a group for which a given Boolean condition holds.
+
+Group mask functionality is currently limited to groups that are instances of the +sub_group+ class, but this limitation may be lifted in a future version of the specification.
+
+=== Ballot
+
+The +ballot+ algorithm converts a Boolean condition from each work-item in the group into a group mask.  Like other group algorithms, +ballot+ must be encountered by all work-items in the group in converged control flow.
+
+|===
+|Member Functions|Description
+
+|+template <typename Group> Group::mask_type ballot(bool predicate = true) const+
+|Return a +group_mask+ representing the set of work-items in the group for which _predicate_ is +true+.
+|===
+
+=== Group Masks
+
+The group mask type is an opaque type, permitting implementations to use any mask representation subject to the following restrictions:
+
+- The size and alignment of the mask type must be the same on the host and device
+- A SYCL implementation supporting OpenCL interoperability must use a 128-bit mask convertible to a +vec<uint,4>+
+
+Functions declared in the +mask+ class can be called independently by different work-items in the same group.  An instance of a group class (e.g. +group+ or +sub_group+) is not required to manipulate a group mask.
+
+The mask is defined such that the least significant bit (LSB) corresponds to the work-item with id 0, and the most significant bit (MSB) corresponds to the work-item with the id +max_local_range()-1+.
+
+|===
+|Member Function|Description
+
+|+bool operator[](id<1> id) const+
+|Return +true+ if the bit corresponding to the specified _id_ is set in the mask.
+
+|+mask::reference operator[](id<1> id) const+
+|Return a reference to the bit corresponding to the specified _id_ in the mask.
+
+|+bool test(id<1> id) const+
+|Return +true+ if the bit corresponding to the specified _id_ is set in the mask.
+
+|+bool all() const+
+|Return +true+ if all bits in the mask are set.
+
+|+bool any() const+
+|Return +true+ if any bits in the mask are set.
+
+|+bool none() const+
+|Return +true+ if none of the bits in the mask are set.
+
+|+uint32_t count() const+
+|Return the number of bits set in the mask.
+
+|+uint32_t size() const+
+|Return the number of bits in the mask.
+
+|+id<1> find_low() const+
+|Return the lowest +id+ with a corresponding bit set in the mask. If no bits are set, the return value is equal to `size()`.
+
+|+id<1> find_high() const+
+|Return the highest +id+ with a corresponding bit set in the mask. If no bits are set, the return value is equal to `size()`.
+
+|+template <typename T = vec<uint32_t,4>> void insert_bits(T bits, id<1> pos = 0)+
+|Insert `CHAR_BIT * sizeof(T)` bits into the mask, starting from _pos_.  `T` must be an integral type or a SYCL vector of integral types.  _pos_ must be a multiple of `CHAR_BIT * sizeof(T)` in the range [0, `size()`).  If _pos_ + `CHAR_BIT * sizeof(T)` is greater than `size()`, the final `size()` - (_pos_ + `CHAR_BIT * sizeof(T)`) bits are ignored.
+
+|+template <typename T = vec<uint32_t,4>> T extract_bits(id<1> pos = 0) const+
+|Return `CHAR_BIT * sizeof(T)` bits from the mask, starting from _pos_.  `T` must be an integral type or a SYCL vector of integral types.  _pos_ must be a multiple of `CHAR_BIT * sizeof(T)` in the range [0, `size()`).  If _pos_ + `CHAR_BIT * sizeof(T)` is greater than `size()`, the final `size()` - (_pos_ + `CHAR_BIT * sizeof(T)`) bits of the return value are zero.
+
+|+void set()+
+|Set all bits in the mask to true.
+
+|+void set(id<1> id, bool value = true)+
+|Set the bit corresponding to the specified _id_ to the value specified by _value_.
+
+|+void reset()+
+|Reset all bits in the mask.
+
+|+void reset(id<1> id)+
+|Reset the bit corresponding to the specified _id_.
+
+|+void reset_low()+
+|Reset the bit for the lowest +id+ with a corresponding bit set in the mask.  Functionally equivalent to +reset(find_low())+.
+
+|+void reset_high()+
+|Reset the bit for the highest +id+ with a corresponding bit set in the mask.  Functionally equivalent to +reset(find_high())+.
+
+|+void flip()+
+|Toggle the values of all bits in the mask.
+
+|+void flip(id<1> id)+
+|Toggle the value of the bit corresponding to the specified _id_.
+
+|+bool operator==(group_mask rhs) const+
+|Return true if each bit in this mask is equal to the corresponding bit in +rhs+.
+
+|+bool operator!=(group_mask rhs) const+
+|Return true if any bit in this mask is not equal to the corresponding bit in +rhs+.
+
+|+group_mask operator &=(group_mask rhs)+
+|Set the bits of this mask to the result of performing a bitwise AND with this mask and +rhs+.
+
+|+group_mask operator |=(group_mask rhs)+
+|Set the bits of this mask to the result of performing a bitwise OR with this mask and +rhs+.
+
+|+group_mask operator ^=(group_mask rhs)+
+|Set the bits of this mask to the result of performing a bitwise XOR with this mask and +rhs+.
+
+|+group_mask operator <<=(size_t shift)+
+|Set the bits of this mask to the result of shifting its bits _shift_ positions to the left using a logical shift.  Bits that are shifted out to the left are discarded, and zeroes are shifted in from the right.
+
+|+group_mask operator >>=(size_t shift)+
+|Set the bits of this mask to the result of shifting its bits _shift_ positions to the right using a logical shift.  Bits that are shifted out to the right are discarded, and zeroes are shifted in from the left.
+
+|+group_mask operator ~() const+
+|Return a mask representing the result of flipping all the bits in this mask.
+
+|+group_mask operator <<(size_t shift)+
+|Return a mask representing the result of shifting its bits _shift_ positions to the left using a logical shift.  Bits that are shifted out to the left are discarded, and zeroes are shifted in from the right.
+
+|+group_mask operator >>(size_t shift)+
+|Return a mask representing the result of shifting its bits _shift_ positions to the right using a logical shift.  Bits that are shifted out to the right are discarded, and zeroes are shifted in from the left.
+|===
+
+|===
+|Function|Description
+
+|+group_mask operator &(const group_mask& lhs, const group_mask& rhs)+
+|Return a mask representing the result of performing a bitwise AND of +lhs+ and +rhs+.
+
+|+group_mask operator |(const group_mask& lhs, const group_mask& rhs)+
+|Return a mask representing the result of performing a bitwise OR of +lhs+ and +rhs+.
+
+|+group_mask operator ^(const group_mask& lhs, const group_mask& rhs)+
+|Return a mask representing the result of performing a bitwise XOR of +lhs+ and +rhs+.
+
+|===
+
+==== Sample Header
+
+[source, c++]
+----
+namespace cl {
+namespace sycl {
+namespace intel {
+
+struct group_mask {
+
+  // enable reference to individual bit
+  struct reference {
+    reference& operator=(bool x);
+    reference& operator=(const reference& x);
+    bool operator~() const;
+    operator bool() const;
+    reference& flip();
+  };
+
+  bool operator[](id<1> id) const;
+  reference operator[](id<1> id) const;
+  bool test(id<1> id) const;
+  bool all() const;
+  bool any() const;
+  bool none() const;
+  uint32_t count() const;
+  uint32_t size() const;
+  id<1> find_low() const;
+  id<1> find_high() const;
+
+  template <typename T = vec<uint32_t,4>>
+  void insert_bits(T bits, id<1> pos = 0);
+
+  template <typename T = vec<uint32_t,4>>
+  T extract_bits(id<1> pos = 0);
+
+  void set();
+  void set(id<1> id, bool value = true);
+  void reset();
+  void reset(id<1> id);
+  void reset_low();
+  void reset_high();
+  void flip();
+  void flip(id<1> id);
+
+  bool operator==(group_mask rhs) const;
+  bool operator!=(group_mask rhs) const;
+
+  group_mask operator &=(group_mask rhs);
+  group_mask operator |=(group_mask rhs);
+  group_mask operator ^=(group_mask rhs);
+  group_mask operator <<=(size_t);
+  group_mask operator >>=(size_t rhs);
+
+  group_mask operator ~() const;
+  group_mask operator <<(size_t) const;
+  group_mask operator >>(size_t) const;
+
+};
+
+group_mask operator &(const group_mask& lhs, const group_mask& rhs);
+group_mask operator |(const group_mask& lhs, const group_mask& rhs);
+group_mask operator ^(const group_mask& lhs, const group_mask& rhs);
+
+} // intel
+} // sycl
+} // cl
+----
+
+== Issues
+
+None.
+
+//. asd
+//+
+//--
+//*RESOLUTION*: Not resolved.
+//--
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-03-16|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.
+//************************************************************************

sycl/doc/extensions/SubGroup/README.md

@@ -0,0 +1,4 @@
+# SYCL_INTEL_sub_group
+
+A new `sub_group` class representing an implementation-defined grouping of work-items in a work-group.
+