[SYCL][Doc] First revision of standard layout relaxation extension

sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc

@@ -0,0 +1,161 @@
+= SYCL_INTEL_relax_standard_layout
+
+: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 removes the requirement for data accessible on a device to be standard layout.  The trivially copyable requirement remains unchanged.
+
+== Name Strings
+
++SYCL_INTEL_relax_standard_layout+
+
+== 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: 2
+
+== Contact
+Michael Kinsner, Intel (michael 'dot' kinsner 'at' intel 'dot' com)
+
+== Dependencies
+
+This extension is written against the SYCL 1.2.1 specification, Revision 6.
+
+== Overview
+
+SYCL 1.2.1 requires data stored into a buffer or passed as a kernel argument to be standard layout.  This is in addition to the data also being trivially copyable.  This extension relaxes the standard layout requirement while leaving the trivially copyable requirement intact.
+
+Standard layout does not guarantee ABI compatibility across devices or between a device and the host, but can help.  To avoid introducing incompatible data layouts, this extension also requires device compilers to validate that their layout of data is compatible with that used by the host.  There are multiple implementation approaches that can achieve this, although they are beyond the scope of this extension which describes the behavior only.
+
+== Modifications of SYCL 1.2.1 Specification
+
+=== Modify Sentence in Section 3.10 (Language restrictions in kernels)
+
+==== From:
+
+Sharing data structures between host and device code imposes certain restrictions, such as use of only user defined classes that are {cpp}11 standard layout classes for the data structures, classes that are {cpp}11 trivially copyable classes for the data structures, and in general, no pointers initialized for the host can be used on the device.
+
+==== To:
+
+Sharing data structures between host and device code imposes certain restrictions, such as use of only user defined classes that are {cpp}11 trivially copyable classes for the data structures, and in general, no pointers initialized for the host can be used on the device.
+
+=== Modify Sentence in Section 4.8.5 (SYCL function for invoking kernels, +set_arg+ description)
+
+==== From:
+
+The argument can be either a SYCL accessor, a SYCL sampler or a trivially copyable and standard-layout C++ type.
+
+==== To:
+
+The argument can be either a SYCL accessor, a SYCL sampler or a trivially copyable C++ type.
+
+=== Modify Sentence in Section 4.8.9 (Defining kernels)
+
+==== From:
+
+These function objects provide the same functionality as any C++ function object, with the restriction that they need to follow {cpp}11 standard layout rules.
+
+==== To:
+
+These function objects provide the same functionality as any C++ function object, with the restriction that they need to follow {cpp}11 rules to be trivially copyable.
+
+
+=== Add new bullet point in Section 4.8.11 (Rules for parameter passing to kernels)
+
+The device compiler(s) must validate that the layout of any data shared between the host and the device(s) (e.g. value kernel arguments or data accessed through an accessor or USM) matches the layout of that data on the host.  If there is a layout mismatch, realized or potential, the device compiler must issue an error and compilation must fail.
+
+=== Modify bullet point in Section 4.8.11 (Rules for parameter passing to kernels)
+
+==== From:
+
+{cpp} standard layout values must be passed by value to the kernel.
+
+==== To:
+
+{cpp} trivially copyable types must be passed by value to the kernel.
+
+=== Modify bullet point in Section 4.8.11 (Rules for parameter passing to kernels)
+
+==== From:
+
+{cpp} non-standard layout values must not be passed as arguments to a kernel that is compiled for a device.
+
+==== To:
+
+{cpp} non-trivially copyable types must not be passed as arguments to a kernel that is compiled for a device.
+
+=== Modify sentence in glossary entry for "SYCL kernel function"
+
+==== From:
+
+The function object can be a named standard layout type or lambda function.
+
+==== To:
+
+The function object can be a named trivially copyable type or lambda function.
+
+== Issues
+
+None.
+
+//. asd
+//+
+//--
+//*RESOLUTION*: Not resolved.
+//--
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-03-17|Michael Kinsner|*Initial public working draft*
+|2|2020-03-24|Michael Kinsner|Remove repeated sentence and fix typo
+|========================================
+
+//************************************************************************
+//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.
+//************************************************************************