From 555392c7af272c80dec0513ab02057b0903b27d3 Mon Sep 17 00:00:00 2001
From: Felipe de Azevedo Piovezan <felipe.de.azevedo.piovezan@intel.com>
Date: Thu, 16 Apr 2020 15:49:43 -0400
Subject: [PATCH] [SYCL][Doc] Add sycl_bitcast extension

This commit adds the sycl_bitcast extension, introducing sycl::bit_cast with
the same semantics as C++20's std::bit_cast (p0476r2).

Signed-off-by: Felipe de Azevedo Piovezan <felipe.de.azevedo.piovezan@intel.com>
---
 .../Bitcast/SYCL_INTEL_bitcast.asciidoc       | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 sycl/doc/extensions/Bitcast/SYCL_INTEL_bitcast.asciidoc

diff --git a/sycl/doc/extensions/Bitcast/SYCL_INTEL_bitcast.asciidoc b/sycl/doc/extensions/Bitcast/SYCL_INTEL_bitcast.asciidoc
new file mode 100644
index 0000000000000..553ee705a9d0f
--- /dev/null
+++ b/sycl/doc/extensions/Bitcast/SYCL_INTEL_bitcast.asciidoc
@@ -0,0 +1,124 @@
+= SYCL_INTEL_bitcast
+
+: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 allows reinterpreting bits in a data
+type as another data type.
+
+== Name Strings
+
++SYCL_INTEL_bitcast+
+
+== 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
+
+It is frequently necessary to reinterpret the bits of an object as an object of
+a different data type. Several methods to achieve this conversion exist but
+most result in undefined behavior according to the {cpp} language. This
+extension defines the function `sycl::bit_cast` to convert between data types
+of the same size. The semantics of `sycl::bit_cast` are aligned with those of
+`std::bit_cast`, which will be introduced by the {cpp}20 language (p0476r2).
+
+== Modifications of SYCL 1.2.1 Specification
+
+=== Add Section 4.14 Conversions and Type Casting
+
+==== Add Section 4.14.1 Reinterpreting Data As Another Type
+
+Reinterpreting the bits of an object as an object of a different data type can
+be accomplished with the `sycl::bit_cast` function. This function has the same
+specification as `std::bit_cast`, defined by {cpp}20.
+
+[source,c++,`sycl::bit_cast`,linenums]
+----
+namespace cl {
+namespace sycl {
+  template<class To, class From>
+  constexpr To bit_cast(const From& from) noexcept;
+}
+}
+----
+
+|========================================
+|Function|Description
+|+template<class To, class From> constexpr To bit_cast(const From& from) noexcept+
+|Reinterprets the bits of an object of type `From` as an object of type `To`. Data types `To` and `From` must have the same size and must be trivially copyable.
+|========================================
+
+== Issues
+
+None.
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-04-14|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.
+//************************************************************************