From 296e9c3a2e20f9322fe63805b0c9ae428386d62c Mon Sep 17 00:00:00 2001 From: jbrodman Date: Fri, 4 Nov 2022 13:26:31 -0400 Subject: [PATCH] [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 Co-authored-by: Greg Lueck --- .../sycl_ext_oneapi_memcpy2d.asciidoc | 235 ++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 sycl/doc/extensions/proposed/sycl_ext_oneapi_memcpy2d.asciidoc diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_memcpy2d.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_memcpy2d.asciidoc new file mode 100644 index 0000000000000..b26465ed25552 --- /dev/null +++ b/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 +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 +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 &depEvents) + +template +event ext_oneapi_copy2d(const T *src, size_t srcPitch, + T *dest, size_t destPitch, + size_t width, size_t height) + +template +event ext_oneapi_copy2d(const T *src, size_t srcPitch, + T *dest, size_t destPitch, + size_t width, size_t height, + event depEvent) + +template +event ext_oneapi_copy2d(const T *src, size_t srcPitch, + T *dest, size_t destPitch, + size_t width, size_t height, + const std::vector &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 &depEvents) + +template +event ext_oneapi_fill2d(void *dest, size_t destPitch, + const T& pattern, size_t width, size_t height) + +template +event ext_oneapi_fill2d(void *dest, size_t destPitch, + const T& pattern, size_t width, size_t height, + event depEvent) + +template +event ext_oneapi_fill2d(void *dest, size_t destPitch, + const T& pattern, size_t width, size_t height, + const std::vector &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`. + +|=== + + + +