[SYCL][DOC] Initial commit for extension to add 2d USM memcpy (#6105)

This extension defines operations to perform 2D non-contiguous data
copies (that is, rows may be padded) on USM allocations.

Signed-off-by: James Brodman <james.brodman@intel.com>
Co-authored-by: Greg Lueck <gregory.m.lueck@intel.com>

sycl/doc/extensions/proposed/sycl_ext_oneapi_memcpy2d.asciidoc

@@ -0,0 +1,235 @@
+= sycl_ext_oneapi_memcpy2d
+: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
+:dpcpp: pass:[DPC++]
+
+// 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}
+
+== Notice
+
+[%hardbreaks]
+Copyright (C) 2022-2022 Intel Corporation.  All rights reserved.
+
+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.
+
+== Contact
+
+To report problems with this extension, please open a new issue at:
+
+https://github.com/intel/llvm/issues
+
+
+== Dependencies
+
+This extension is written against the SYCL 2020 revision 4 specification.  All
+references below to the "core SYCL specification" or to section numbers in the
+SYCL specification refer to that revision.
+
+== Status
+
+This is a proposed extension specification, intended to gather community
+feedback.  Interfaces defined in this specification may not be implemented yet
+or may be in a preliminary state.  The specification itself may also change in
+incompatible ways before it is finalized.  *Shipping software products should
+not rely on APIs defined in this specification.*
+
+== Specification
+
+This extension adds support for 2D memcpy and associated routines that can
+copy a specified rectangular region in the presence of array padding.
+
+=== Feature test macro
+
+This extension provides a feature-test macro as described in the core SYCL
+specification.  An implementation supporting this extension must predefine the
+macro `SYCL_EXT_ONEAPI_MEMCPY2D` to one of the values defined in the table
+below.  Applications can test for the existence of this macro to determine if
+the implementation supports this feature, or applications can test the macro's
+value to determine which of the extension's features the implementation
+supports.
+
+[%header,cols="1,5"]
+|===
+|Value
+|Description
+
+|1
+|Initial version of this extension.
+|===
+
+=== API Additions
+
+
+The handler class gains the following new methods:
+
+[cols="60a,40"]
+|===
+| Member Function | Description
+
+a|
+[source,c++]
+----
+void ext_oneapi_memcpy2d(void *dest, size_t destPitch,
+  const void *src, size_t srcPitch,
+  size_t width, size_t height)
+----
+
+| Copies the data located at `src` to `dest`. The width of a row in bytes,
+including any padding, is specified by `destPitch` for `dest` and `srcPitch`
+for `src`. The amount of data to copy is specified as `width` bytes per row
+times `height` number of rows.  `width` must not be larger than either
+`srcPitch` or `destPitch`, otherwise this function throws a synchronous
+`exception` with the `errc::invalid` error code. The `dest` and `src`
+parameters must each either be a host pointer or a pointer within a USM
+allocation that is accessible on the handler's device. If a pointer is to a
+USM allocation, that allocation must have been created from the same context
+as the handler's queue.
+
+a|
+[source,c++]
+----
+template <typename T>
+void ext_oneapi_copy2d(const T *src, size_t srcPitch,
+  T *dest, size_t destPitch,
+  size_t width, size_t height)
+----
+
+| Copies the data located at `src` to `dest`. The width of a row in number
+of elements, including any padding, is specified by `destPitch` for `dest`
+and `srcPitch` for `src`. The amount of data to copy is specified as `width`
+elements per row times `height` number of rows. `width` must not be larger
+than either `srcPitch` or `destPitch`, otherwise this function throws a
+synchronous `exception` with the `errc::invalid` error code. The `dest`
+and `src` parameters must each either be a host pointer or a pointer within
+a USM allocation that is accessible on the handler's device. If a pointer is
+to a USM allocation, that allocation must have been created from the same context
+as the handler's queue.
+
+a|
+[source,c++]
+----
+void ext_oneapi_memset2d(void *dest, size_t destPitch,
+  int value, size_t width, size_t height)
+----
+
+| Fills the data located at `dest` with `value`. Note that `value` is
+interpreted as an `unsigned char`. The width of a row in bytes,
+including any padding, is specified by `destPitch` for `dest`.
+The amount of data to fill is specified as `width` bytes per row
+times `height` number of rows.  `width` must not be larger than `destPitch`,
+otherwise this function throws a synchronous `exception` with the
+`errc::invalid` error code. The `dest` parameter must be a pointer
+within a USM allocation that is accessible on the handler's device and
+that allocation must have been created from the same context as the
+handler's queue.
+
+a|
+[source,c++]
+----
+template <typename T>
+void ext_oneapi_fill2d(void *dest, size_t destPitch,
+  const T& pattern, size_t width, size_t height)
+----
+
+| Fills the data located at `dest` with `pattern`. The width of a row in
+number of elements, including any padding, is specified by `destPitch`.
+The amount of data to fill is specified as `width` elements per row
+times `height` number of rows.  `width` must not be larger than `destPitch`,
+otherwise this function throws a synchronous `exception` with the
+`errc::invalid` error code. The `dest` parameter must be a pointer within
+a USM allocation that is accessible on the handler's device and that
+allocation must have been created from the same context as the handler's
+queue.
+
+|===
+
+This extension also defines additional shortcut methods. The `queue` class
+gains several new methods:
+
+[cols="60a,40"]
+|===
+| Member Function | Description
+
+|
+[source,c++]
+----
+event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
+  const void *src, size_t srcPitch,
+  size_t width, size_t height)
+
+event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
+  const void *src, size_t srcPitch,
+  size_t width, size_t height,
+  event depEvent)
+
+event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
+  const void *src, size_t srcPitch,
+  size_t width, size_t height,
+  const std::vector<event> &depEvents)
+
+template <typename T>
+event ext_oneapi_copy2d(const T *src, size_t srcPitch,
+  T *dest, size_t destPitch,
+  size_t width, size_t height)
+
+template <typename T>
+event ext_oneapi_copy2d(const T *src, size_t srcPitch,
+  T *dest, size_t destPitch,
+  size_t width, size_t height,
+  event depEvent)
+
+template <typename T>
+event ext_oneapi_copy2d(const T *src, size_t srcPitch,
+  T *dest, size_t destPitch,
+  size_t width, size_t height,
+  const std::vector<event> &depEvents)
+
+event ext_oneapi_memset2d(void *dest, size_t destPitch,
+  int value, size_t width, size_t height)
+
+event ext_oneapi_memset2d(void *dest, size_t destPitch,
+  int value, size_t width, size_t height,
+  event depEvent)
+
+event ext_oneapi_memset2d(void *dest, size_t destPitch,
+  int value, size_t width, size_t height,
+  const std::vector<event> &depEvents)
+
+template <typename T>
+event ext_oneapi_fill2d(void *dest, size_t destPitch,
+  const T& pattern, size_t width, size_t height)
+
+template <typename T>
+event ext_oneapi_fill2d(void *dest, size_t destPitch,
+  const T& pattern, size_t width, size_t height,
+  event depEvent)
+
+template <typename T>
+event ext_oneapi_fill2d(void *dest, size_t destPitch,
+  const T& pattern, size_t width, size_t height,
+  const std::vector<event> &depEvents)
+
+----
+
+| Equivalent to submitting a command group containing the corresponding
+method in the `handler` class. Dependences may be specified through
+the parameters `depEvent` or `depEvents` as if the handler contained a call to
+`depends_on`.
+
+|===
+
+
+
+