From c46d59fc4f9a97c36c428deaf2ecfc3b432d5d9e Mon Sep 17 00:00:00 2001 From: Michael Kinsner Date: Wed, 18 Mar 2020 11:03:53 -0300 Subject: [PATCH 1/2] First revision of standard layout relaxation extension Signed-off-by: Michael Kinsner --- .../SYCL_INTEL_relax_standard_layout.asciidoc | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100755 sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc diff --git a/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc b/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc new file mode 100755 index 0000000000000..f2567206f5a47 --- /dev/null +++ b/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc @@ -0,0 +1,160 @@ += 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: 1 + +== 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 required 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, 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* +|======================================== + +//************************************************************************ +//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. +//************************************************************************ From ebb8d440399607bd11818073edacfdc8ff25a636 Mon Sep 17 00:00:00 2001 From: Michael Kinsner Date: Tue, 24 Mar 2020 17:09:06 -0300 Subject: [PATCH 2/2] Incorporate feedback Signed-off-by: Michael Kinsner --- .../SYCL_INTEL_relax_standard_layout.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc b/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc index f2567206f5a47..3c5bce70f2740 100755 --- a/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc +++ b/sycl/doc/extensions/RelaxStdLayout/SYCL_INTEL_relax_standard_layout.asciidoc @@ -48,7 +48,7 @@ Because the interfaces defined by this specification are not final and are subje == Version Built On: {docdate} + -Revision: 1 +Revision: 2 == Contact Michael Kinsner, Intel (michael 'dot' kinsner 'at' intel 'dot' com) @@ -59,7 +59,7 @@ This extension is written against the SYCL 1.2.1 specification, Revision 6. == Overview -SYCL 1.2.1 required 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. +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. @@ -73,7 +73,7 @@ Sharing data structures between host and device code imposes certain restriction ==== 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, 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. +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) @@ -148,6 +148,7 @@ None. |======================================== |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 |======================================== //************************************************************************